From 6d003db19c563ccc4e68076597ce157c554bf614 Mon Sep 17 00:00:00 2001
From: Kevin Cheng <59463423+kevchengcodes@users.noreply.github.com>
Date: Mon, 14 Sep 2026 16:30:46 -0700
Subject: [PATCH 1/3] Add SAM3 video segmentation runtime and tests

Swift runtime for the sam3_video export. Detector runs on every frame and results are associated with existing tracked objects. Some new CoreAIShared utilities. Includes postprocessing and rendering.
---
 Package.swift                                 |  34 ++
 .../segmentation/video_pipeline.py            |  56 +-
 .../test_export/test_video_export.py          |   6 +-
 .../CoreAIShared/Bundle/BundleKind.swift      |   3 +
 .../CoreAIShared/Image/OverlayPalette.swift   |  10 +
 .../Runtime/BilinearResampler.swift           | 220 ++++++++
 .../CoreAIShared/Runtime/MaskBitset.swift     | 167 ++++++
 .../CoreAIShared/Runtime/ModelStructure.swift |  26 +-
 .../Runtime/NDArray+Helpers.swift             |  73 +++
 .../CoreAIShared/Text/CLIPTokenizer.swift     |  29 +
 .../FramePreprocessor.swift                   | 137 +++++
 .../Postprocessing/ConnectedComponents.swift  | 117 ++++
 .../Postprocessing/MaskPostprocessor.swift    | 105 ++++
 .../Postprocessing/VideoOverlayRenderer.swift | 150 ++++++
 .../Session/MemoryBankPacker.swift            | 326 ++++++++++++
 .../Session/ObjectRegistry.swift              |  63 +++
 .../Session/VideoInferenceSession.swift       | 252 +++++++++
 .../Tracking/Associator.swift                 | 112 ++++
 .../Tracking/DetectionDecoder.swift           | 124 +++++
 .../Tracking/FrameProcessor.swift             | 446 ++++++++++++++++
 .../Tracking/HotstartHeuristics.swift         | 144 +++++
 .../Tracking/OcclusionSuppressor.swift        | 222 ++++++++
 .../Tracking/TrackerLoop.swift                | 355 +++++++++++++
 .../VideoSegmentationActor.swift              |  20 +
 .../VideoSegmentationEngine.swift             | 494 +++++++++++++++++
 .../VideoSegmentationError.swift              |  43 ++
 .../VideoSegmentationOutputs.swift            |  93 ++++
 .../VideoSegmentationParameters.swift         | 169 ++++++
 .../CoreAIVideoSegmenter/VideoSegmenter.swift | 317 +++++++++++
 .../VideoSegmenterBundle.swift                | 182 +++++++
 .../video-segmenter/ParityReference.swift     | 167 ++++++
 .../video-segmenter/VideoSegmenterMain.swift  | 498 ++++++++++++++++++
 .../NDArrayHelpersTests.swift                 |  82 +++
 .../AssociationTests.swift                    | 204 +++++++
 .../BilinearResamplerTests.swift              | 160 ++++++
 .../FramePreprocessingTests.swift             | 122 +++++
 .../HotstartAndMemoryTests.swift              | 288 ++++++++++
 .../VideoSegmenterTests/MaskBitsetTests.swift | 130 +++++
 .../MaskPostprocessorTests.swift              | 126 +++++
 .../TokenizerAndBundleTests.swift             | 233 ++++++++
 .../TrackingPrimitiveTests.swift              | 212 ++++++++
 41 files changed, 6709 insertions(+), 8 deletions(-)
 create mode 100644 swift/Sources/CoreAIShared/Runtime/BilinearResampler.swift
 create mode 100644 swift/Sources/CoreAIShared/Runtime/MaskBitset.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/FramePreprocessor.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/Postprocessing/ConnectedComponents.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/Postprocessing/MaskPostprocessor.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/Postprocessing/VideoOverlayRenderer.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/Session/MemoryBankPacker.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/Session/ObjectRegistry.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/Session/VideoInferenceSession.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/Tracking/Associator.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/Tracking/DetectionDecoder.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/Tracking/FrameProcessor.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/Tracking/HotstartHeuristics.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/Tracking/OcclusionSuppressor.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/Tracking/TrackerLoop.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/VideoSegmentationActor.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/VideoSegmentationEngine.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/VideoSegmentationError.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/VideoSegmentationOutputs.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/VideoSegmentationParameters.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/VideoSegmenter.swift
 create mode 100644 swift/Sources/CoreAIVideoSegmenter/VideoSegmenterBundle.swift
 create mode 100644 swift/Sources/Tools/video-segmenter/ParityReference.swift
 create mode 100644 swift/Sources/Tools/video-segmenter/VideoSegmenterMain.swift
 create mode 100644 swift/Tests/VideoSegmenterTests/AssociationTests.swift
 create mode 100644 swift/Tests/VideoSegmenterTests/BilinearResamplerTests.swift
 create mode 100644 swift/Tests/VideoSegmenterTests/FramePreprocessingTests.swift
 create mode 100644 swift/Tests/VideoSegmenterTests/HotstartAndMemoryTests.swift
 create mode 100644 swift/Tests/VideoSegmenterTests/MaskBitsetTests.swift
 create mode 100644 swift/Tests/VideoSegmenterTests/MaskPostprocessorTests.swift
 create mode 100644 swift/Tests/VideoSegmenterTests/TokenizerAndBundleTests.swift
 create mode 100644 swift/Tests/VideoSegmenterTests/TrackingPrimitiveTests.swift

diff --git a/Package.swift b/Package.swift
index 60508acd..1e80f9b0 100644
--- a/Package.swift
+++ b/Package.swift
@@ -35,6 +35,12 @@ let package = Package(
                 "CoreAIImageSegmenter"
             ]
         ),
+        .library(
+            name: "CoreAIVideoSegmentation",
+            targets: [
+                "CoreAIVideoSegmenter"
+            ]
+        ),
         .library(
             name: "CoreAISpeech",
             targets: ["CoreAISpeech"]
@@ -86,6 +92,14 @@ let package = Package(
                 .enableUpcomingFeature("MemberImportVisibility")
             ]
         ),
+        .target(
+            name: "CoreAIVideoSegmenter",
+            dependencies: ["CoreAIShared"],
+            path: "swift/Sources/CoreAIVideoSegmenter",
+            swiftSettings: [
+                .enableUpcomingFeature("MemberImportVisibility")
+            ]
+        ),
 
         // Shared utilities
         .target(
@@ -208,6 +222,18 @@ let package = Package(
                 .enableUpcomingFeature("MemberImportVisibility")
             ]
         ),
+        .executableTarget(
+            name: "video-segmenter",
+            dependencies: [
+                "CoreAIVideoSegmenter",
+                "CoreAIShared",
+                .product(name: "ArgumentParser", package: "swift-argument-parser"),
+            ],
+            path: "swift/Sources/Tools/video-segmenter",
+            swiftSettings: [
+                .enableUpcomingFeature("MemberImportVisibility")
+            ]
+        ),
         .executableTarget(
             name: "diffusion-runner",
             dependencies: [
@@ -297,6 +323,14 @@ let package = Package(
             ],
             path: "swift/Tests/ImageSegmenterTests"
         ),
+        .testTarget(
+            name: "VideoSegmenterTests",
+            dependencies: [
+                "CoreAIVideoSegmenter",
+                "CoreAIShared",
+            ],
+            path: "swift/Tests/VideoSegmenterTests"
+        ),
         .testTarget(
             name: "DiffusionPipelineTests",
             dependencies: [
diff --git a/python/src/coreai_models/segmentation/video_pipeline.py b/python/src/coreai_models/segmentation/video_pipeline.py
index e96f471e..689065c3 100644
--- a/python/src/coreai_models/segmentation/video_pipeline.py
+++ b/python/src/coreai_models/segmentation/video_pipeline.py
@@ -715,7 +715,7 @@ async def _async_export_video(config: VideoExportConfig) -> str:
     logger.info("Saved Core AI asset to %s", asset_path)
 
     # Metadata before tokenizer, so a flaky HF fetch can't leave an unloadable bundle.
-    _write_bundle_metadata(bundle_dir, asset_path.name, config)
+    _write_bundle_metadata(bundle_dir, asset_path.name, config, model.config)
     _write_tokenizer(bundle_dir / "tokenizer", config.hf_model_id)
     return str(bundle_dir)
 
@@ -841,14 +841,65 @@ def _resolve_paths(config: VideoExportConfig) -> tuple[Path, Path]:
     return bundle_dir, bundle_dir / f"{name}.aimodel"
 
 
+#: ``Sam3VideoConfig`` fields the host runtime needs, copied into the bundle's ``tracking``
+#: block. None affect the traced graphs; they all govern host-side heuristics. A runtime
+#: that hardcodes the upstream defaults only diverges on a checkpoint that tuned them.
+_TRACKING_FIELDS = (
+    "score_threshold_detection",
+    "det_nms_thresh",
+    "new_det_thresh",
+    "assoc_iou_thresh",
+    "trk_assoc_iou_thresh",
+    "high_conf_thresh",
+    "high_iou_thresh",
+    "recondition_every_nth_frame",
+    "recondition_on_trk_masks",
+    "hotstart_delay",
+    "hotstart_unmatch_thresh",
+    "hotstart_dup_thresh",
+    "suppress_unmatched_only_within_hotstart",
+    "init_trk_keep_alive",
+    "max_trk_keep_alive",
+    "min_trk_keep_alive",
+    "decrease_trk_keep_alive_for_empty_masklets",
+    "suppress_overlapping_based_on_recent_occlusion_threshold",
+    "max_num_objects",
+    "fill_hole_area",
+)
+
+#: Tracker-config fields that decide which stored frames are eligible for the memory bank.
+#: The export pins their sum (``spatial_slots`` is ``max_cond_frame_num + num_maskmem - 1``)
+#: but not the split, so the host cannot recover them from the asset alone.
+_TRACKER_MEMORY_FIELDS = (
+    "num_maskmem",
+    "max_cond_frame_num",
+    "max_object_pointers_in_encoder",
+)
+
+
+def _tracking_metadata(config) -> dict:
+    """Collect the host-side thresholds from a ``Sam3VideoConfig``."""
+    tracking: dict = {}
+    for field in _TRACKING_FIELDS:
+        if hasattr(config, field):
+            tracking[field] = getattr(config, field)
+    tracker_config = config.tracker_config
+    for field in _TRACKER_MEMORY_FIELDS:
+        if hasattr(tracker_config, field):
+            tracking[field] = getattr(tracker_config, field)
+    return tracking
+
+
 def _write_bundle_metadata(
-    bundle_dir: Path, asset_filename: str, config: VideoExportConfig
+    bundle_dir: Path, asset_filename: str, config: VideoExportConfig, model_config
 ) -> None:
     """Write the bundle manifest.
 
     ``runtime`` carries the slot geometry because the host has to pack memory to
     exactly the shapes the graph was traced with; deriving it from the HF config
     at load time would silently break if the export used non-default slots.
+
+    ``tracking`` carries the checkpoint's own heuristic thresholds; see ``_TRACKING_FIELDS``.
     """
     metadata = {
         "metadata_version": "0.2",
@@ -861,6 +912,7 @@ def _write_bundle_metadata(
             "ptr_slots": config.ptr_slots,
             "max_text_seq_len": config.max_text_seq_len,
         },
+        "tracking": _tracking_metadata(model_config),
     }
     metadata_path = bundle_dir / "metadata.json"
     with open(metadata_path, "w") as fh:
diff --git a/python/tests/test_model_units/test_export/test_video_export.py b/python/tests/test_model_units/test_export/test_video_export.py
index 6de9bbc5..b04f9884 100644
--- a/python/tests/test_model_units/test_export/test_video_export.py
+++ b/python/tests/test_model_units/test_export/test_video_export.py
@@ -7,11 +7,7 @@
 
 Everything here runs on a randomly-initialized, heavily downscaled config
 (112x112, 2 backbone layers, 1 memory-attention layer) so no weights are
-downloaded and the whole file runs in seconds. Numerical parity against the
-real checkpoint is the parity harness's job
-(``models/sam3_video/run_video_parity.py``); what these tests pin is the
-*structure*: that the fixed-slot memory bank is mathematically equivalent to
-HF's variable-length one, and that every entrypoint is traceable.
+downloaded and the whole file runs in seconds.
 """
 
 from __future__ import annotations
diff --git a/swift/Sources/CoreAIShared/Bundle/BundleKind.swift b/swift/Sources/CoreAIShared/Bundle/BundleKind.swift
index c5325abc..d2260403 100644
--- a/swift/Sources/CoreAIShared/Bundle/BundleKind.swift
+++ b/swift/Sources/CoreAIShared/Bundle/BundleKind.swift
@@ -13,5 +13,8 @@ public enum BundleKind: String, Codable, Sendable, CaseIterable {
     case vlm
     case diffusion
     case segmenter
+    /// Text-promptable video segmentation (SAM 3 video). Separate from `segmenter`
+    /// because the bundle carries a `runtime` block with the memory-bank geometry.
+    case videoSegmenter = "video_segmenter"
     case speechRecognizer = "speech_recognizer"
 }
diff --git a/swift/Sources/CoreAIShared/Image/OverlayPalette.swift b/swift/Sources/CoreAIShared/Image/OverlayPalette.swift
index 831b0013..553f8228 100644
--- a/swift/Sources/CoreAIShared/Image/OverlayPalette.swift
+++ b/swift/Sources/CoreAIShared/Image/OverlayPalette.swift
@@ -33,6 +33,16 @@ public enum OverlayPalette {
         return hsvToRGB(h: Float(index) / Float(count), s: 0.85, v: 0.95)
     }
 
+    /// Stable color for a tracked object id.
+    ///
+    /// Steps the hue by the golden ratio's fractional part rather than dividing the wheel
+    /// by a count: the total is unknown mid-video, and consecutive ids, which is what new
+    /// tracks get, stay far apart instead of nearly on top of each other.
+    public static func color(forID id: Int) -> (UInt8, UInt8, UInt8) {
+        let hue = (Float(id) * 0.618_033_99).truncatingRemainder(dividingBy: 1.0)
+        return hsvToRGB(h: hue < 0 ? hue + 1 : hue, s: 0.85, v: 0.95)
+    }
+
     /// HSV → RGB, all components in [0, 1].
     public static func hsvToRGB(h: Float, s: Float, v: Float) -> (UInt8, UInt8, UInt8) {
         let h6 = h * 6
diff --git a/swift/Sources/CoreAIShared/Runtime/BilinearResampler.swift b/swift/Sources/CoreAIShared/Runtime/BilinearResampler.swift
new file mode 100644
index 00000000..9d245e4c
--- /dev/null
+++ b/swift/Sources/CoreAIShared/Runtime/BilinearResampler.swift
@@ -0,0 +1,220 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import Accelerate
+import Foundation
+
+/// Separable bilinear resampling of a planar `Float` image, matching
+/// `torch.nn.functional.interpolate(mode: "bilinear", align_corners: false)`.
+///
+/// Hand-written rather than delegating to `vImageScale_PlanarF`, whose high-quality path is a
+/// different kernel and drifts from PyTorch. Construct once per (source, destination) pair
+/// and reuse; the weight tables are the only setup cost.
+///
+/// `antialias` widens the filter when downsampling, the way PIL and
+/// `torchvision.transforms.Resize` do. Upsampling ignores it.
+public struct BilinearResampler: Sendable {
+    public let sourceWidth: Int
+    public let sourceHeight: Int
+    public let destinationWidth: Int
+    public let destinationHeight: Int
+
+    private let horizontal: Weights
+    private let vertical: Weights
+
+    public init(
+        sourceWidth: Int, sourceHeight: Int,
+        destinationWidth: Int, destinationHeight: Int,
+        antialias: Bool = false
+    ) {
+        precondition(
+            sourceWidth > 0 && sourceHeight > 0 && destinationWidth > 0 && destinationHeight > 0,
+            "BilinearResampler dimensions must be positive")
+        self.sourceWidth = sourceWidth
+        self.sourceHeight = sourceHeight
+        self.destinationWidth = destinationWidth
+        self.destinationHeight = destinationHeight
+        self.horizontal = Weights(
+            sourceSize: sourceWidth, destinationSize: destinationWidth, antialias: antialias)
+        self.vertical = Weights(
+            sourceSize: sourceHeight, destinationSize: destinationHeight, antialias: antialias)
+    }
+
+    /// True when the resampler would copy its input unchanged.
+    public var isIdentity: Bool {
+        sourceWidth == destinationWidth && sourceHeight == destinationHeight
+    }
+
+    /// Resample a row-major `sourceHeight × sourceWidth` buffer.
+    public func resample(_ source: [Float]) -> [Float] {
+        precondition(
+            source.count >= sourceWidth * sourceHeight,
+            "BilinearResampler expected \(sourceWidth * sourceHeight) samples, got \(source.count)")
+        if isIdentity { return Array(source.prefix(sourceWidth * sourceHeight)) }
+
+        // Horizontal first, so the vertical pass runs over the smaller of the two widths
+        // when downscaling and the taps stay whole contiguous rows either way.
+        var intermediate = [Float](repeating: 0, count: sourceHeight * destinationWidth)
+        source.withUnsafeBufferPointer { input in
+            intermediate.withUnsafeMutableBufferPointer { output in
+                horizontal.applyAcrossRows(
+                    input: input.baseAddress!, inputStride: sourceWidth,
+                    output: output.baseAddress!, outputStride: destinationWidth,
+                    rowCount: sourceHeight)
+            }
+        }
+
+        var destination = [Float](repeating: 0, count: destinationHeight * destinationWidth)
+        intermediate.withUnsafeBufferPointer { input in
+            destination.withUnsafeMutableBufferPointer { output in
+                vertical.applyDownColumns(
+                    input: input.baseAddress!,
+                    output: output.baseAddress!,
+                    rowWidth: destinationWidth)
+            }
+        }
+        return destination
+    }
+}
+
+// MARK: - Weights
+
+/// Per-output-index filter taps along one axis.
+///
+/// Stored as a dense `destinationSize × maxTaps` table with a start index and live tap
+/// count per output. Rows near an edge use fewer taps than the interior; padding to a
+/// fixed stride keeps the indexing uniform at the cost of a few unused slots.
+private struct Weights: Sendable {
+    let destinationSize: Int
+    let maxTaps: Int
+    /// First source index contributing to each output index.
+    let starts: [Int]
+    /// Number of live taps for each output index.
+    let counts: [Int]
+    /// `destinationSize * maxTaps` coefficients, normalized to sum to 1 per output.
+    let values: [Float]
+
+    init(sourceSize: Int, destinationSize: Int, antialias: Bool) {
+        self.destinationSize = destinationSize
+        let scale = Double(sourceSize) / Double(destinationSize)
+
+        if antialias && scale > 1.0 {
+            // Downsampling with a triangle filter whose support grows with the ratio.
+            // Mirrors `aten/src/ATen/native/UpSample.h::_compute_weights_aa`.
+            let support = scale
+            let inverseScale = 1.0 / scale
+            let taps = Int(support.rounded(.up)) * 2 + 1
+            self.maxTaps = taps
+            var starts = [Int](repeating: 0, count: destinationSize)
+            var counts = [Int](repeating: 0, count: destinationSize)
+            var values = [Float](repeating: 0, count: destinationSize * taps)
+            for index in 0..<destinationSize {
+                let center = scale * (Double(index) + 0.5)
+                let start = max(0, Int(center - support + 0.5))
+                let end = min(sourceSize, Int(center + support + 0.5))
+                let count = max(0, end - start)
+                starts[index] = start
+                counts[index] = min(count, taps)
+                var total = 0.0
+                for tap in 0..<counts[index] {
+                    let offset = (Double(tap + start) - center + 0.5) * inverseScale
+                    let weight = max(0.0, 1.0 - abs(offset))
+                    values[index * taps + tap] = Float(weight)
+                    total += weight
+                }
+                if total != 0 {
+                    for tap in 0..<counts[index] {
+                        values[index * taps + tap] /= Float(total)
+                    }
+                }
+            }
+            self.starts = starts
+            self.counts = counts
+            self.values = values
+            return
+        }
+
+        // Plain bilinear: two taps, matching `area_pixel_compute_source_index` with
+        // `align_corners=false`. The clamp is on the position, not the index, so a negative
+        // source position pins to the first pixel instead of inventing one past the edge.
+        self.maxTaps = 2
+        var starts = [Int](repeating: 0, count: destinationSize)
+        var counts = [Int](repeating: 2, count: destinationSize)
+        var values = [Float](repeating: 0, count: destinationSize * 2)
+        for index in 0..<destinationSize {
+            let position = max(0.0, scale * (Double(index) + 0.5) - 0.5)
+            let low = min(Int(position), sourceSize - 1)
+            let fraction = position - Double(low)
+            let high = low < sourceSize - 1 ? low + 1 : low
+            starts[index] = low
+            counts[index] = high == low ? 1 : 2
+            values[index * 2] = Float(1.0 - fraction)
+            values[index * 2 + 1] = Float(fraction)
+            if high == low {
+                // Last row/column: torch reuses the same sample for both taps, which is
+                // the same as folding both weights onto it.
+                values[index * 2] = 1.0
+                values[index * 2 + 1] = 0.0
+            }
+        }
+        self.starts = starts
+        self.counts = counts
+        self.values = values
+    }
+
+    /// Resample each row independently. Weights vary per output column, so this is a
+    /// gather-dot and stays scalar.
+    func applyAcrossRows(
+        input: UnsafePointer<Float>, inputStride: Int,
+        output: UnsafeMutablePointer<Float>, outputStride: Int,
+        rowCount: Int
+    ) {
+        starts.withUnsafeBufferPointer { starts in
+            counts.withUnsafeBufferPointer { counts in
+                values.withUnsafeBufferPointer { values in
+                    for row in 0..<rowCount {
+                        let sourceRow = input + row * inputStride
+                        let destinationRow = output + row * outputStride
+                        for index in 0..<destinationSize {
+                            let start = starts[index]
+                            let base = index * maxTaps
+                            var sum: Float = 0
+                            for tap in 0..<counts[index] {
+                                sum += values[base + tap] * sourceRow[start + tap]
+                            }
+                            destinationRow[index] = sum
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    /// Resample down the columns. Each tap is a whole contiguous row scaled by one
+    /// coefficient, so this is a few `vDSP_vsma` calls per output row rather than a
+    /// per-pixel loop.
+    func applyDownColumns(
+        input: UnsafePointer<Float>,
+        output: UnsafeMutablePointer<Float>,
+        rowWidth: Int
+    ) {
+        let length = vDSP_Length(rowWidth)
+        for index in 0..<destinationSize {
+            let start = starts[index]
+            let base = index * maxTaps
+            let destinationRow = output + index * rowWidth
+            var first = values[base]
+            vDSP_vsmul(input + start * rowWidth, 1, &first, destinationRow, 1, length)
+            guard counts[index] > 1 else { continue }
+            for tap in 1..<counts[index] {
+                var weight = values[base + tap]
+                if weight == 0 { continue }
+                vDSP_vsma(
+                    input + (start + tap) * rowWidth, 1, &weight,
+                    destinationRow, 1, destinationRow, 1, length)
+            }
+        }
+    }
+}
diff --git a/swift/Sources/CoreAIShared/Runtime/MaskBitset.swift b/swift/Sources/CoreAIShared/Runtime/MaskBitset.swift
new file mode 100644
index 00000000..4fe90a2e
--- /dev/null
+++ b/swift/Sources/CoreAIShared/Runtime/MaskBitset.swift
@@ -0,0 +1,167 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreGraphics
+import Foundation
+
+/// A binary mask packed one pixel per bit, row-major.
+///
+/// Tracking is dominated by set arithmetic over masks: association, NMS and occlusion
+/// suppression are all pairwise IoU matrices, and each runs once per frame. Packed, both
+/// intersection and union fall out of `nonzeroBitCount` without needing Accelerate.
+public struct MaskBitset: Sendable, Equatable {
+    public let width: Int
+    public let height: Int
+    private(set) var words: [UInt64]
+
+    public init(width: Int, height: Int) {
+        precondition(width >= 0 && height >= 0, "MaskBitset dimensions must be non-negative")
+        self.width = width
+        self.height = height
+        self.words = [UInt64](repeating: 0, count: (width * height + 63) / 64)
+    }
+
+    /// Threshold a row-major float buffer: `value > threshold` becomes a set bit.
+    ///
+    /// The comparison is strictly greater to match HF, which binarizes mask logits with
+    /// `mask > 0` throughout; `>=` would flip every exactly-zero pixel.
+    public init(thresholding values: [Float], width: Int, height: Int, above threshold: Float = 0) {
+        self.init(width: width, height: height)
+        precondition(
+            values.count >= width * height,
+            "MaskBitset needs \(width * height) values, got \(values.count)")
+        let count = width * height
+        words.withUnsafeMutableBufferPointer { output in
+            values.withUnsafeBufferPointer { input in
+                var index = 0
+                var wordIndex = 0
+                while index < count {
+                    let end = min(index + 64, count)
+                    var word: UInt64 = 0
+                    var bit: UInt64 = 1
+                    for i in index..<end {
+                        if input[i] > threshold { word |= bit }
+                        bit <<= 1
+                    }
+                    output[wordIndex] = word
+                    wordIndex += 1
+                    index = end
+                }
+            }
+        }
+    }
+
+    /// Threshold a sub-range of a larger row-major buffer, one mask out of a stacked
+    /// `[N, H, W]` tensor.
+    public init(
+        thresholding values: ArraySlice<Float>, width: Int, height: Int, above threshold: Float = 0
+    ) {
+        self.init(thresholding: Array(values), width: width, height: height, above: threshold)
+    }
+
+    public subscript(x: Int, y: Int) -> Bool {
+        get {
+            let index = y * width + x
+            return words[index >> 6] & (1 << UInt64(index & 63)) != 0
+        }
+        set {
+            let index = y * width + x
+            if newValue {
+                words[index >> 6] |= 1 << UInt64(index & 63)
+            } else {
+                words[index >> 6] &= ~(1 << UInt64(index & 63))
+            }
+        }
+    }
+
+    /// Number of set pixels.
+    public var area: Int {
+        var total = 0
+        for word in words { total += word.nonzeroBitCount }
+        return total
+    }
+
+    public var isEmpty: Bool {
+        for word in words where word != 0 { return false }
+        return true
+    }
+
+    /// Intersection over union, matching `modeling_sam3_video.mask_iou`.
+    ///
+    /// HF clamps the union to a minimum of 1, so empty-vs-empty scores 0 rather than
+    /// dividing by zero. Association therefore treats two empty masks as unrelated.
+    public func iou(_ other: MaskBitset) -> Float {
+        precondition(
+            width == other.width && height == other.height,
+            "MaskBitset.iou requires matching dimensions")
+        var intersection = 0
+        var union = 0
+        for index in words.indices {
+            let a = words[index]
+            let b = other.words[index]
+            intersection += (a & b).nonzeroBitCount
+            union += (a | b).nonzeroBitCount
+        }
+        return Float(intersection) / Float(max(union, 1))
+    }
+
+    /// Tight bounding box of the set pixels, top-left origin. Empty masks give `.zero`.
+    ///
+    /// `torchvision.ops.masks_to_boxes` reports inclusive extremes, so a single set pixel is
+    /// a zero-sized rect. Kept that way so the values compare directly against a reference.
+    public var boundingBox: CGRect {
+        var minX = width
+        var minY = height
+        var maxX = -1
+        var maxY = -1
+        forEachSetIndex { index in
+            let y = index / width
+            let x = index - y * width
+            if x < minX { minX = x }
+            if x > maxX { maxX = x }
+            if y < minY { minY = y }
+            if y > maxY { maxY = y }
+        }
+        guard maxX >= 0 else { return .zero }
+        return CGRect(
+            x: CGFloat(minX), y: CGFloat(minY),
+            width: CGFloat(maxX - minX), height: CGFloat(maxY - minY))
+    }
+
+    /// Visit every set pixel's row-major index in ascending order.
+    @inline(__always)
+    public func forEachSetIndex(_ body: (Int) -> Void) {
+        let count = width * height
+        for wordIndex in words.indices {
+            var word = words[wordIndex]
+            let base = wordIndex << 6
+            while word != 0 {
+                let index = base + Int(word.trailingZeroBitCount)
+                if index >= count { return }
+                body(index)
+                word &= word - 1
+            }
+        }
+    }
+
+    /// Row-major bytes, one per pixel, 1 for foreground.
+    public func toBytes() -> [UInt8] {
+        var out = [UInt8](repeating: 0, count: width * height)
+        forEachSetIndex { out[$0] = 1 }
+        return out
+    }
+
+    /// Rebuild from `numpy.packbits` output: MSB-first within each byte, row-major.
+    public init(packedBits: [UInt8], width: Int, height: Int) {
+        self.init(width: width, height: height)
+        let count = width * height
+        for index in 0..<count {
+            let byte = packedBits[index >> 3]
+            if byte & (0x80 >> UInt8(index & 7)) != 0 {
+                words[index >> 6] |= 1 << UInt64(index & 63)
+            }
+        }
+    }
+}
diff --git a/swift/Sources/CoreAIShared/Runtime/ModelStructure.swift b/swift/Sources/CoreAIShared/Runtime/ModelStructure.swift
index 834a499e..68f2f39c 100644
--- a/swift/Sources/CoreAIShared/Runtime/ModelStructure.swift
+++ b/swift/Sources/CoreAIShared/Runtime/ModelStructure.swift
@@ -17,6 +17,12 @@ public enum GraphNames {
     public static let imageEncode = "image_encode"
     public static let textEncode = "text_encode"
     public static let detect = "detect"
+    // Video segmenter (SAM3 video export). Shares the three names above with the
+    // image segmenter, so `trackerStep` is what tells the two apart.
+    public static let trackerEncode = "tracker_encode"
+    public static let trackerStep = "tracker_step"
+    public static let memoryEncode = "memory_encode"
+    public static let trackerMaskInit = "tracker_mask_init"
 }
 
 /// Represents the detected structure of a Core AI model.
@@ -38,6 +44,10 @@ public enum ModelStructure: Equatable, Sendable, CustomStringConvertible {
     /// Identified by presence of `image_encode`, `text_encode`, and `detect` graphs.
     case multiFunctionSegmenter
 
+    /// Seven-function SAM3 video segmenter.
+    /// Identified by `tracker_step`, which no other export produces.
+    case videoSegmenter
+
     public var description: String {
         switch self {
         case .chunkedStatic(let batchSize):
@@ -46,6 +56,8 @@ public enum ModelStructure: Equatable, Sendable, CustomStringConvertible {
             return "dynamic"
         case .multiFunctionSegmenter:
             return "multiFunctionSegmenter"
+        case .videoSegmenter:
+            return "videoSegmenter"
         }
     }
 
@@ -54,11 +66,12 @@ public enum ModelStructure: Equatable, Sendable, CustomStringConvertible {
     /// - `chunkedStatic` → NeuralEngine
     /// - `dynamic` → GPU
     /// - `multiFunctionSegmenter` → NeuralEngine
+    /// - `videoSegmenter` → GPU
     public var preferredDevice: String {
         switch self {
         case .chunkedStatic, .multiFunctionSegmenter:
             return "NeuralEngine"
-        case .dynamic:
+        case .dynamic, .videoSegmenter:
             return "GPU"
         }
     }
@@ -68,6 +81,7 @@ public enum ModelStructure: Equatable, Sendable, CustomStringConvertible {
     /// - `chunkedStatic` → prefer `.neuralEngine`
     /// - `dynamic` → prefer `.gpu` + `expectFrequentReshapes`
     /// - `multiFunctionSegmenter` → prefer `.neuralEngine`
+    /// - `videoSegmenter` → prefer `.gpu`, without `expectFrequentReshapes`
     public var specializationOptions: SpecializationOptions {
         switch self {
         case .chunkedStatic, .multiFunctionSegmenter:
@@ -76,6 +90,9 @@ public enum ModelStructure: Equatable, Sendable, CustomStringConvertible {
             var opts = SpecializationOptions(preferredComputeUnitKind: .gpu)
             opts.expectFrequentReshapes = true
             return opts
+        case .videoSegmenter:
+            // TODO: the optimized export will need different specialization options.
+            return SpecializationOptions(preferredComputeUnitKind: .gpu)
         }
     }
 }
@@ -247,6 +264,13 @@ public struct PreparedModel: Sendable {
             return .chunkedStatic(batchSize: batchSize)
         }
 
+        // Must be checked before the image segmenter below: this asset also declares
+        // image_encode / text_encode / detect, and the looser test would specialize it
+        // for the Neural Engine, which cannot compile two of its graphs.
+        if graphSet.contains(GraphNames.trackerStep) {
+            return .videoSegmenter
+        }
+
         // Multi-function segmenter (e.g. optimized SAM3 — image_encode / text_encode / detect).
         // Targets neuralEngine; checked before the `main` fallback because some asset variants ship
         // a thin `main` graph alongside the trio.
diff --git a/swift/Sources/CoreAIShared/Runtime/NDArray+Helpers.swift b/swift/Sources/CoreAIShared/Runtime/NDArray+Helpers.swift
index 01c56348..b59c8bc3 100644
--- a/swift/Sources/CoreAIShared/Runtime/NDArray+Helpers.swift
+++ b/swift/Sources/CoreAIShared/Runtime/NDArray+Helpers.swift
@@ -160,6 +160,79 @@ public func fillFloatNDArray(_ array: inout NDArray, with elements: ArraySlice<F
     }
 }
 
+/// Copy `source` into `array` starting at logical element `elementOffset`.
+///
+/// Unlike `fillNDArray`, which fills from index 0 through a per-element closure, this writes
+/// at an offset and `memcpy`s the whole run when the array is contiguous, falling back to a
+/// stride walk only when it is padded for hardware alignment.
+///
+/// - Precondition: `elementOffset + source.count` must not exceed the logical element count.
+public func copyIntoNDArray<T: BitwiseCopyable>(
+    _ array: inout NDArray, as type: T.Type, elementOffset: Int, from source: [T]
+) {
+    copyIntoNDArray(array.mutableRawView(), as: T.self, elementOffset: elementOffset, from: source)
+}
+
+/// Copy `source` into an NDArray's MutableRawView starting at logical element `elementOffset`.
+/// Takes the view as `consuming`, so the caller gives up ownership.
+public func copyIntoNDArray<T: BitwiseCopyable>(
+    _ rawView: consuming NDArray.MutableRawView, as type: T.Type, elementOffset: Int,
+    from source: [T]
+) {
+    guard !source.isEmpty else { return }
+    let view = rawView.view(as: type)
+    view.withUnsafeMutablePointer { ptr, shape, strides in
+        let capacity = shape.product
+        precondition(
+            elementOffset >= 0 && elementOffset + source.count <= capacity,
+            "copyIntoNDArray: [\(elementOffset), \(elementOffset + source.count)) exceeds capacity \(capacity)"
+        )
+
+        if isContiguousRowMajor(shape: shape, strides: strides) {
+            source.withUnsafeBufferPointer { input in
+                (ptr + elementOffset).update(from: input.baseAddress!, count: source.count)
+            }
+            return
+        }
+
+        let rank = shape.count
+        var indices = [Int](repeating: 0, count: rank)
+        var remainder = elementOffset
+        for d in (0..<rank).reversed() {
+            indices[d] = remainder % shape[d]
+            remainder /= shape[d]
+        }
+        var offset = 0
+        for d in 0..<rank { offset += indices[d] * strides[d] }
+        for i in 0..<source.count {
+            ptr[offset] = source[i]
+            var dim = rank - 1
+            while dim >= 0 {
+                indices[dim] += 1
+                offset += strides[dim]
+                if indices[dim] < shape[dim] { break }
+                indices[dim] = 0
+                offset -= strides[dim] * shape[dim]
+                dim -= 1
+            }
+        }
+    }
+}
+
+/// Write `value` into every logical element of `array` in `elementRange`.
+///
+/// Clears memory-bank slots that were valid on the previous call and are not on this one.
+/// Stale slots are harmless numerically, since the key mask suppresses them, but they make
+/// a parity divergence hard to reason about.
+public func clearNDArrayRegion<T: BitwiseCopyable>(
+    _ array: inout NDArray, as type: T.Type, elementRange: Range<Int>, value: T
+) {
+    guard !elementRange.isEmpty else { return }
+    copyIntoNDArray(
+        &array, as: type, elementOffset: elementRange.lowerBound,
+        from: [T](repeating: value, count: elementRange.count))
+}
+
 // MARK: - Flatten Helpers
 
 /// Flatten an NDArray output into `[Float]`, branching on its own scalar type.
diff --git a/swift/Sources/CoreAIShared/Text/CLIPTokenizer.swift b/swift/Sources/CoreAIShared/Text/CLIPTokenizer.swift
index b450c1bd..be714dcb 100644
--- a/swift/Sources/CoreAIShared/Text/CLIPTokenizer.swift
+++ b/swift/Sources/CoreAIShared/Text/CLIPTokenizer.swift
@@ -110,6 +110,35 @@ public struct CLIPTokenizer: Sendable {
         return ids
     }
 
+    /// Encode `text` and report which slots hold real tokens.
+    ///
+    /// The pad token is `<|endoftext|>`, the same id that ends a real sequence, so the ids
+    /// alone can't tell padding from content. A prompt longer than `contextLength` is
+    /// truncated with `eotTokenId` forced into the last slot, making the mask all ones.
+    public func encodeWithMask(
+        _ text: String, contextLength: Int = 77
+    ) -> (ids: [Int32], attentionMask: [Int32]) {
+        let cleaned = whitespaceClean(text).lowercased()
+        let wordTokens = tokenize(cleaned)
+
+        var ids: [Int32] = [Self.sotTokenId]
+        ids += wordTokens.compactMap { encoder[$0] }
+        ids.append(Self.eotTokenId)
+
+        if ids.count > contextLength {
+            ids = Array(ids.prefix(contextLength))
+            ids[contextLength - 1] = Self.eotTokenId
+        }
+
+        let realCount = ids.count
+        while ids.count < contextLength {
+            ids.append(Self.eotTokenId)
+        }
+
+        let attentionMask = (0..<contextLength).map { Int32($0 < realCount ? 1 : 0) }
+        return (ids, attentionMask)
+    }
+
     // MARK: - Private
 
     private func tokenize(_ text: String) -> [String] {
diff --git a/swift/Sources/CoreAIVideoSegmenter/FramePreprocessor.swift b/swift/Sources/CoreAIVideoSegmenter/FramePreprocessor.swift
new file mode 100644
index 00000000..f4d3d217
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/FramePreprocessor.swift
@@ -0,0 +1,137 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import Accelerate
+import CoreAIShared
+import CoreGraphics
+import Foundation
+
+/// Turns a decoded frame into the planar CHW tensor `image_encode` expects.
+///
+/// Deliberately not `CoreAIShared.ImagePreprocessor`, which the image segmenter uses: that
+/// resizes by drawing through a `CGContext` at `.high` interpolation, a Lanczos-family kernel
+/// on 8-bit samples, while `Sam3VideoVideoProcessor` resizes with plain bilinear in float. For
+/// a single image the difference is invisible; across a tracked video it compounds, because
+/// every frame's input feeds the memory bank.
+///
+/// So: convert to float at native resolution first, resample in float, normalize last.
+struct FramePreprocessor {
+    let targetSize: Int
+    let mean: (Float, Float, Float)
+    let standardDeviation: (Float, Float, Float)
+
+    /// Resamplers are keyed by source size and rebuilt only when it changes, which for a
+    /// video is once.
+    private final class Cache {
+        var width = 0
+        var height = 0
+        var resampler: BilinearResampler?
+    }
+    private let cache = Cache()
+
+    init(
+        targetSize: Int,
+        mean: (CGFloat, CGFloat, CGFloat),
+        standardDeviation: (CGFloat, CGFloat, CGFloat)
+    ) {
+        self.targetSize = targetSize
+        self.mean = (Float(mean.0), Float(mean.1), Float(mean.2))
+        self.standardDeviation = (
+            Float(standardDeviation.0), Float(standardDeviation.1), Float(standardDeviation.2)
+        )
+    }
+
+    /// Preprocess a decoded frame. Returns flat `[3, targetSize, targetSize]`.
+    func preprocess(_ image: CGImage) throws -> [Float] {
+        let width = image.width
+        let height = image.height
+        guard let colorSpace = CGColorSpace(name: CGColorSpace.sRGB),
+            let context = CGContext(
+                data: nil, width: width, height: height,
+                bitsPerComponent: 8, bytesPerRow: width * 4,
+                space: colorSpace,
+                bitmapInfo: CGImageAlphaInfo.noneSkipLast.rawValue),
+            let base = context.data
+        else {
+            throw ImagePreprocessorError.renderFailed
+        }
+        // Drawn at native size: this is a format conversion, not a resize.
+        context.draw(image, in: CGRect(x: 0, y: 0, width: width, height: height))
+        let pixels = base.bindMemory(to: UInt8.self, capacity: width * height * 4)
+        return preprocess(
+            interleavedRGB: UnsafeBufferPointer(start: pixels, count: width * height * 4),
+            width: width, height: height, channelStride: 4)
+    }
+
+    /// Preprocess interleaved 8-bit samples directly.
+    ///
+    /// `channelStride` is 4 for RGBA and 3 for packed RGB. The second form is what the
+    /// preprocessing tests feed in, so they can hold the decoder constant and measure
+    /// only this stage.
+    func preprocess(
+        interleavedRGB bytes: [UInt8], width: Int, height: Int, channelStride: Int
+    ) -> [Float] {
+        bytes.withUnsafeBufferPointer {
+            preprocess(interleavedRGB: $0, width: width, height: height, channelStride: channelStride)
+        }
+    }
+
+    private func preprocess(
+        interleavedRGB bytes: UnsafeBufferPointer<UInt8>,
+        width: Int, height: Int, channelStride: Int
+    ) -> [Float] {
+        let resampler = resampler(sourceWidth: width, sourceHeight: height)
+        let sourcePixels = width * height
+        let targetPixels = targetSize * targetSize
+
+        var output = [Float](repeating: 0, count: 3 * targetPixels)
+        var plane = [Float](repeating: 0, count: sourcePixels)
+        var resized = [Float](repeating: 0, count: targetPixels)
+        let means = [mean.0, mean.1, mean.2]
+        let deviations = [standardDeviation.0, standardDeviation.1, standardDeviation.2]
+        var elementCount = Int32(targetPixels)
+
+        for channel in 0..<3 {
+            // De-interleave, staying in 0-255 so the rounding below lands on the same
+            // grid torchvision uses.
+            vDSP_vfltu8(
+                bytes.baseAddress! + channel, channelStride, &plane, 1, vDSP_Length(sourcePixels))
+
+            resized = resampler.resample(plane)
+
+            // torchvision resizes a uint8 tensor as uint8: it interpolates and then
+            // rounds back to integers, so its `pixel_values` land exactly on the 0-255
+            // grid (verified: every element is within 8e-6 of an integer). Skipping this
+            // leaves a uniform ~0.25-code-value bias against the reference.
+            vvnintf(&resized, resized, &elementCount)
+
+            // Fold rescale and normalize into one affine pass: (x / 255 - m) / s.
+            var slope = 1 / (255 * deviations[channel])
+            var offset = -means[channel] / deviations[channel]
+            output.withUnsafeMutableBufferPointer { out in
+                vDSP_vsmsa(
+                    resized, 1, &slope, &offset,
+                    out.baseAddress! + channel * targetPixels, 1, vDSP_Length(targetPixels))
+            }
+        }
+        return output
+    }
+
+    private func resampler(sourceWidth: Int, sourceHeight: Int) -> BilinearResampler {
+        if let existing = cache.resampler, cache.width == sourceWidth, cache.height == sourceHeight {
+            return existing
+        }
+        // `antialias: false` matches the video processor, and every real clip upscales to
+        // 1008 anyway, where the flag makes no difference.
+        let built = BilinearResampler(
+            sourceWidth: sourceWidth, sourceHeight: sourceHeight,
+            destinationWidth: targetSize, destinationHeight: targetSize,
+            antialias: false)
+        cache.width = sourceWidth
+        cache.height = sourceHeight
+        cache.resampler = built
+        return built
+    }
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/Postprocessing/ConnectedComponents.swift b/swift/Sources/CoreAIVideoSegmenter/Postprocessing/ConnectedComponents.swift
new file mode 100644
index 00000000..771d793f
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/Postprocessing/ConnectedComponents.swift
@@ -0,0 +1,117 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import Foundation
+
+/// 8-connected component labelling and the mask cleanup built on it.
+///
+/// Port of `fill_holes_in_mask_scores` and `_get_connected_components_with_padding` in
+/// `modeling_sam3_video.py`. Upstream routes the labelling through an optional
+/// `kernels-community/cv-utils` CUDA kernel and, when it is not installed, returns fake
+/// component areas of `H*W + 1`, which makes both cleanup steps no-ops without saying so.
+/// This implementation is always present, so a bundle run here gets the cleanup the model
+/// was tuned with. Set ``VideoSegmentationParameters/fillHoleArea`` to 0 to reproduce a
+/// Python run that was missing the kernel.
+///
+/// 8-connectivity matches SAM 2's `get_connected_components`, which documents it
+/// explicitly and is what `cc_2d` implements.
+enum ConnectedComponents {
+    /// Per-pixel component area for the set pixels of `mask`. Unset pixels get 0.
+    ///
+    /// Union-find with path halving over a single raster pass, then one pass to resolve roots
+    /// and a third to broadcast the root's area. Linear in pixels.
+    static func areas(of mask: [Bool], width: Int, height: Int) -> [Int32] {
+        let count = width * height
+        precondition(mask.count >= count, "ConnectedComponents.areas: mask is too small")
+        var parent = [Int32](repeating: -1, count: count)
+
+        func find(_ start: Int32) -> Int32 {
+            var node = start
+            while parent[Int(node)] != node {
+                // Path halving: point each node at its grandparent while climbing. Keeps the
+                // trees flat without a second pass.
+                parent[Int(node)] = parent[Int(parent[Int(node)])]
+                node = parent[Int(node)]
+            }
+            return node
+        }
+        func union(_ a: Int32, _ b: Int32) {
+            let rootA = find(a)
+            let rootB = find(b)
+            if rootA == rootB { return }
+            // Always attach the larger index under the smaller so roots stay stable and
+            // the labelling is deterministic.
+            if rootA < rootB { parent[Int(rootB)] = rootA } else { parent[Int(rootA)] = rootB }
+        }
+
+        for y in 0..<height {
+            for x in 0..<width {
+                let index = y * width + x
+                guard mask[index] else { continue }
+                parent[index] = Int32(index)
+                // Only the already-visited half of the 8-neighbourhood: west, and the
+                // three above. The other four are covered when their own row runs.
+                if x > 0, mask[index - 1] { union(Int32(index), Int32(index - 1)) }
+                if y > 0 {
+                    let above = index - width
+                    if mask[above] { union(Int32(index), Int32(above)) }
+                    if x > 0, mask[above - 1] { union(Int32(index), Int32(above - 1)) }
+                    if x + 1 < width, mask[above + 1] { union(Int32(index), Int32(above + 1)) }
+                }
+            }
+        }
+
+        var componentArea = [Int32](repeating: 0, count: count)
+        var roots = [Int32](repeating: -1, count: count)
+        for index in 0..<count where parent[index] >= 0 {
+            let root = find(Int32(index))
+            roots[index] = root
+            componentArea[Int(root)] += 1
+        }
+        var result = [Int32](repeating: 0, count: count)
+        for index in 0..<count where roots[index] >= 0 {
+            result[index] = componentArea[Int(roots[index])]
+        }
+        return result
+    }
+
+    /// Fill small background holes and remove small foreground specks, in place.
+    ///
+    /// Port of `fill_holes_in_mask_scores(mask, max_area, fill_holes=True,
+    /// remove_sprinkles=True)`. The two sentinel values (`0.1` and `-0.1`) are upstream's:
+    /// the mask stays a logit field, so a filled hole becomes weakly positive rather than
+    /// saturated.
+    ///
+    /// The foreground threshold is `min(maxArea, foregroundArea / 2)` and is recomputed after
+    /// hole filling, which is what keeps a genuinely tiny object from deleting itself.
+    static func fillHoles(_ logits: inout [Float], width: Int, height: Int, maxArea: Int) {
+        guard maxArea > 0 else { return }
+        let count = width * height
+        precondition(logits.count >= count, "fillHoles: logit buffer is too small")
+
+        // Background: components of `logits <= 0` up to `maxArea` become weakly positive.
+        var background = [Bool](repeating: false, count: count)
+        for index in 0..<count { background[index] = logits[index] <= 0 }
+        let backgroundAreas = areas(of: background, width: width, height: height)
+        for index in 0..<count where background[index] && backgroundAreas[index] <= Int32(maxArea) {
+            logits[index] = 0.1
+        }
+
+        // Foreground: components of `logits > 0` up to the smaller of `maxArea` and half
+        // the mask's own area become weakly negative.
+        var foreground = [Bool](repeating: false, count: count)
+        var foregroundArea = 0
+        for index in 0..<count where logits[index] > 0 {
+            foreground[index] = true
+            foregroundArea += 1
+        }
+        let threshold = Int32(min(maxArea, foregroundArea / 2))
+        guard threshold > 0 else { return }
+        let foregroundAreas = areas(of: foreground, width: width, height: height)
+        for index in 0..<count where foreground[index] && foregroundAreas[index] <= threshold {
+            logits[index] = -0.1
+        }
+    }
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/Postprocessing/MaskPostprocessor.swift b/swift/Sources/CoreAIVideoSegmenter/Postprocessing/MaskPostprocessor.swift
new file mode 100644
index 00000000..4e8426e7
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/Postprocessing/MaskPostprocessor.swift
@@ -0,0 +1,105 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreAIShared
+import CoreGraphics
+import Foundation
+
+/// Turns a frame's low-resolution mask logits into the objects a caller sees.
+///
+/// Port of `Sam3VideoProcessor.postprocess_outputs`. Four steps, in this order, and the
+/// order matters: upsample to video resolution and binarize, drop empty and hidden
+/// objects, resolve overlaps within each prompt group, then derive boxes.
+struct MaskPostprocessor {
+    /// Surviving objects plus, when asked for, the mask logits they came from.
+    struct Postprocessed {
+        var objects: [TrackedObject] = []
+        var lowResolutionMasks: [[Float]] = []
+    }
+
+    private let lowResolutionSize: Int
+    private let videoWidth: Int
+    private let videoHeight: Int
+    private let emitLowResolutionMasks: Bool
+    private let resampler: BilinearResampler
+
+    init(
+        lowResolutionSize: Int, videoWidth: Int, videoHeight: Int,
+        emitLowResolutionMasks: Bool = false
+    ) {
+        self.lowResolutionSize = lowResolutionSize
+        self.videoWidth = videoWidth
+        self.videoHeight = videoHeight
+        self.emitLowResolutionMasks = emitLowResolutionMasks
+        // Note: no antialiasing. Upstream calls `interpolate(..., mode="bilinear",
+        // align_corners=False)` here without the flag, unlike the resizes inside the
+        // tracker.
+        self.resampler = BilinearResampler(
+            sourceWidth: lowResolutionSize, sourceHeight: lowResolutionSize,
+            destinationWidth: videoWidth, destinationHeight: videoHeight,
+            antialias: false)
+    }
+
+    /// Reads the session's prompt map and hidden-object set, so it shares the frame loop's
+    /// isolation rather than taking copies of both per frame.
+    @VideoSegmentationActor
+    func postprocess(_ raw: RawFrameOutput, session: VideoInferenceSession) -> Postprocessed {
+        // Sorted ids, so output order is stable frame to frame regardless of how the
+        // registry happens to be arranged.
+        let candidates = raw.maskLogitsByObjectID.keys.sorted()
+        guard !candidates.isEmpty else { return Postprocessed() }
+
+        let hidden = raw.suppressedObjectIDs.union(session.hotstartRemovedObjectIDs)
+
+        var ids: [Int] = []
+        var masks: [MaskBitset] = []
+        var scores: [Float] = []
+        var trackerScores: [Float] = []
+        var promptIDs: [Int] = []
+        var lowResolution: [[Float]] = []
+
+        for objectID in candidates {
+            guard !hidden.contains(objectID) else { continue }
+            guard let logits = raw.maskLogitsByObjectID[objectID] else { continue }
+            let upsampled = resampler.resample(logits)
+            let mask = MaskBitset(
+                thresholding: upsampled, width: videoWidth, height: videoHeight)
+            // Objects whose mask upsampled to nothing are dropped, not reported empty.
+            guard !mask.isEmpty else { continue }
+
+            ids.append(objectID)
+            masks.append(mask)
+            scores.append(raw.scoreByObjectID[objectID] ?? 0)
+            trackerScores.append(raw.trackerScoreByObjectID[objectID] ?? 0)
+            promptIDs.append(session.promptIDByObjectID[objectID] ?? 0)
+            if emitLowResolutionMasks { lowResolution.append(logits) }
+        }
+        guard !ids.isEmpty else { return Postprocessed() }
+
+        // Boxes come from the masks before overlap resolution. Upstream computes
+        // `masks_to_boxes` and only then applies the non-overlap constraint, so a box can
+        // be slightly larger than the mask it labels. Kept that way for parity.
+        let boxes = masks.map(\.boundingBox)
+
+        // Overlaps are resolved by tracker score, not detection score, and only within a
+        // prompt group: "person" and "pillow" are allowed to claim the same pixels.
+        OcclusionSuppressor.applyObjectWiseNonOverlap(
+            masks: &masks, scores: trackerScores, promptIDs: promptIDs)
+
+        var objects: [TrackedObject] = []
+        objects.reserveCapacity(ids.count)
+        for index in ids.indices {
+            objects.append(
+                TrackedObject(
+                    id: ids[index],
+                    prompt: session.promptText(promptIDs[index]),
+                    mask: masks[index],
+                    box: boxes[index],
+                    score: scores[index],
+                    trackerScore: trackerScores[index]))
+        }
+        return Postprocessed(objects: objects, lowResolutionMasks: lowResolution)
+    }
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/Postprocessing/VideoOverlayRenderer.swift b/swift/Sources/CoreAIVideoSegmenter/Postprocessing/VideoOverlayRenderer.swift
new file mode 100644
index 00000000..3435ecd2
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/Postprocessing/VideoOverlayRenderer.swift
@@ -0,0 +1,150 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreAIShared
+import CoreGraphics
+import CoreText
+import Foundation
+
+/// Draws a frame's tracked objects over the source image.
+///
+/// Colours come from ``OverlayPalette/color(forID:)``, which is a pure function of the
+/// object id rather than of its position in the array. A track that survives an occlusion
+/// and comes back keeps its colour; one that appears alongside it does not steal it.
+struct VideoOverlayRenderer {
+    private let parameters: VideoSegmentationParameters
+
+    init(parameters: VideoSegmentationParameters) {
+        self.parameters = parameters
+    }
+
+    /// Composite `objects` onto `frame`, returning a new image at the same size.
+    ///
+    /// Returns `frame` unchanged when there is nothing to draw, so a caller can pipe every
+    /// frame through this without special-casing empty ones.
+    func render(_ objects: [TrackedObject], onto frame: CGImage) -> CGImage {
+        guard !objects.isEmpty else { return frame }
+        let width = frame.width
+        let height = frame.height
+        guard
+            let context = CGContext(
+                data: nil, width: width, height: height,
+                bitsPerComponent: 8, bytesPerRow: width * 4,
+                space: CGColorSpaceCreateDeviceRGB(),
+                bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue)
+        else { return frame }
+
+        context.draw(frame, in: CGRect(x: 0, y: 0, width: width, height: height))
+
+        if let overlay = maskOverlay(objects, width: width, height: height) {
+            context.draw(overlay, in: CGRect(x: 0, y: 0, width: width, height: height))
+        }
+
+        // Core Graphics puts the origin at the bottom left; masks and boxes are top-left.
+        // Flipping the whole context once here keeps every draw below in image
+        // coordinates, including the text, which would otherwise render upside down.
+        context.translateBy(x: 0, y: CGFloat(height))
+        context.scaleBy(x: 1, y: -1)
+
+        if parameters.drawBoxes {
+            context.setLineWidth(parameters.strokeWidth)
+            for object in objects where !object.box.isEmpty {
+                let (r, g, b) = OverlayPalette.color(forID: object.id)
+                context.setStrokeColor(
+                    red: CGFloat(r) / 255, green: CGFloat(g) / 255, blue: CGFloat(b) / 255,
+                    alpha: 1)
+                context.stroke(object.box)
+            }
+        }
+        if parameters.drawLabels {
+            for object in objects where !object.box.isEmpty {
+                drawLabel(for: object, in: context, imageHeight: height)
+            }
+        }
+
+        return context.makeImage() ?? frame
+    }
+
+    /// Build one translucent RGBA layer holding every object's fill.
+    ///
+    /// Composited as a single image rather than one draw per object: at 1080p with eight
+    /// tracks that is one blend instead of eight, and the per-object alpha blend below
+    /// gives the same result as stacking translucent layers.
+    private func maskOverlay(_ objects: [TrackedObject], width: Int, height: Int) -> CGImage? {
+        let alpha = max(0, min(1, parameters.maskOpacity))
+        guard alpha > 0 else { return nil }
+        let inverse = 1 - alpha
+
+        var pixels = [UInt8](repeating: 0, count: width * height * 4)
+        pixels.withUnsafeMutableBufferPointer { buffer in
+            guard let base = buffer.baseAddress else { return }
+            for object in objects {
+                guard object.mask.width == width, object.mask.height == height else { continue }
+                let (r, g, b) = OverlayPalette.color(forID: object.id)
+                // The buffer is premultipliedLast, so store colour already scaled by alpha
+                // and over-composite: C_out = C_new + C_old * (1 - a_new).
+                let red = Float(r) * alpha
+                let green = Float(g) * alpha
+                let blue = Float(b) * alpha
+                object.mask.forEachSetIndex { index in
+                    let offset = index * 4
+                    base[offset] = UInt8(min(255, red + Float(base[offset]) * inverse))
+                    base[offset + 1] = UInt8(min(255, green + Float(base[offset + 1]) * inverse))
+                    base[offset + 2] = UInt8(min(255, blue + Float(base[offset + 2]) * inverse))
+                    base[offset + 3] = UInt8(
+                        min(255, (alpha + Float(base[offset + 3]) / 255 * inverse) * 255))
+                }
+            }
+        }
+
+        guard let provider = CGDataProvider(data: Data(pixels) as CFData) else { return nil }
+        return CGImage(
+            width: width, height: height,
+            bitsPerComponent: 8, bitsPerPixel: 32, bytesPerRow: width * 4,
+            space: CGColorSpaceCreateDeviceRGB(),
+            bitmapInfo: CGBitmapInfo(rawValue: CGImageAlphaInfo.premultipliedLast.rawValue),
+            provider: provider, decode: nil, shouldInterpolate: false, intent: .defaultIntent)
+    }
+
+    /// `#id prompt 0.92` on a filled chip above the box, tucked inside the frame when the
+    /// box is at the top edge.
+    private func drawLabel(for object: TrackedObject, in context: CGContext, imageHeight: Int) {
+        let text = "#\(object.id) \(object.prompt) \(String(format: "%.2f", object.score))"
+        let fontSize = max(11, min(28, parameters.strokeWidth * 5))
+        let font = CTFontCreateWithName("Helvetica-Bold" as CFString, fontSize, nil)
+        // Core Text attribute names rather than the AppKit/UIKit ones, so this file stays
+        // buildable on both platforms without importing a UI framework.
+        let attributes: [NSAttributedString.Key: Any] = [
+            NSAttributedString.Key(kCTFontAttributeName as String): font,
+            NSAttributedString.Key(kCTForegroundColorAttributeName as String):
+                CGColor(red: 1, green: 1, blue: 1, alpha: 1),
+        ]
+        let line = CTLineCreateWithAttributedString(
+            NSAttributedString(string: text, attributes: attributes))
+        let bounds = CTLineGetBoundsWithOptions(line, .useOpticalBounds)
+
+        let padding: CGFloat = 3
+        let chipWidth = bounds.width + padding * 2
+        let chipHeight = bounds.height + padding * 2
+        var chipY = object.box.minY - chipHeight
+        if chipY < 0 { chipY = object.box.minY }  // box hugs the top; put the chip inside
+
+        let (r, g, b) = OverlayPalette.color(forID: object.id)
+        context.setFillColor(
+            red: CGFloat(r) / 255, green: CGFloat(g) / 255, blue: CGFloat(b) / 255, alpha: 0.85)
+        context.fill(
+            CGRect(x: object.box.minX, y: chipY, width: chipWidth, height: chipHeight))
+
+        // The context is already y-flipped for image coordinates, so flip once more
+        // locally or the glyphs come out mirrored.
+        context.saveGState()
+        context.textMatrix = .identity
+        context.translateBy(x: object.box.minX + padding, y: chipY + chipHeight - padding)
+        context.scaleBy(x: 1, y: -1)
+        context.textPosition = CGPoint(x: 0, y: -bounds.minY - bounds.height)
+        CTLineDraw(line, context)
+        context.restoreGState()
+    }
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/Session/MemoryBankPacker.swift b/swift/Sources/CoreAIVideoSegmenter/Session/MemoryBankPacker.swift
new file mode 100644
index 00000000..31b6091d
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/Session/MemoryBankPacker.swift
@@ -0,0 +1,326 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreAI
+import CoreAIShared
+import Foundation
+
+/// The seven fixed-shape memory tensors `tracker_step` reads, reused across calls.
+struct PackedMemory {
+    var spatialMemory: NDArray
+    var spatialMemoryPosition: NDArray
+    var spatialTemporalIndex: NDArray
+    var spatialValid: NDArray
+    var objectPointers: NDArray
+    var pointerTemporalPosition: NDArray
+    var pointerValid: NDArray
+}
+
+/// Selects each object's eligible memories and packs them into the graph's fixed slots.
+///
+/// HF builds the tracker's memory with a variable-length `torch.cat`, so its length changes
+/// every frame and per object. A traced graph takes one shape, so this uses a fixed bank plus
+/// an additive key mask. Packing valid entries at the front in any order is safe because
+/// cross-attention is permutation-invariant over keys, RoPE repeats the same per-slot pattern
+/// across spatial slots, and masked slots contribute nothing.
+///
+/// `gatherMemoryFrames` and `objectPointers` are ports of `_gather_memory_frame_outputs` and
+/// `_get_object_pointers` in `modeling_sam3_tracker_video.py`, so which memories are eligible
+/// cannot drift from upstream even though the layout does.
+@VideoSegmentationActor
+final class MemoryBankPacker {
+    private let shapes: VideoSegmentationEngine.Shapes
+    private let parameters: VideoSegmentationParameters
+    private var packed: PackedMemory
+    /// Slots written on the previous call, so only those need clearing on this one.
+    private var previousSpatialSlots = 0
+    private var previousPointerSlots = 0
+    /// Emitted at most once per video; the condition is a property of the export, not of
+    /// the frame, so repeating it per frame per object would bury the log.
+    private var warnedAboutPointerOverflow = false
+
+    /// Slot capacities and per-slot element counts, all derived from the traced shapes.
+    private var spatialSlotElements: Int { shapes.memoryTokenCount * shapes.memoryDim }
+    private var pointerSlotElements: Int { shapes.hiddenDim }
+
+    init(
+        engine: VideoSegmentationEngine,
+        shapes: VideoSegmentationEngine.Shapes,
+        parameters: VideoSegmentationParameters,
+        packed: PackedMemory
+    ) throws {
+        self.shapes = shapes
+        self.parameters = parameters
+        self.packed = packed
+
+        // The spatial half of the bank is exact, not a budget: HF can populate at most
+        // `max_cond_frame_num` conditioning memories plus `num_maskmem - 1` recent ones.
+        // An asset exported with fewer slots would silently drop real memories, so refuse.
+        let required = parameters.maxCondFrameNum + parameters.numMaskmem - 1
+        guard shapes.spatialSlots >= required else {
+            throw VideoSegmentationError.unsupportedGeometry(
+                "Asset has \(shapes.spatialSlots) spatial memory slots but this configuration "
+                    + "can produce \(required) (max_cond_frame_num \(parameters.maxCondFrameNum) + "
+                    + "num_maskmem \(parameters.numMaskmem) - 1). Re-export with "
+                    + "--spatial-slots \(required).")
+        }
+    }
+
+    /// Allocate the bank once, at the shapes the graph was traced with.
+    static func makePacked(engine: VideoSegmentationEngine) async throws -> PackedMemory {
+        let step = VideoSegmentationEngine.Function.trackerStep
+        return PackedMemory(
+            spatialMemory: try await engine.makeInput(for: step, named: "spatial_memory"),
+            spatialMemoryPosition: try await engine.makeInput(
+                for: step, named: "spatial_memory_pos"),
+            spatialTemporalIndex: try await engine.makeInput(for: step, named: "spatial_tpos_idx"),
+            spatialValid: try await engine.makeInput(for: step, named: "spatial_valid"),
+            objectPointers: try await engine.makeInput(for: step, named: "object_pointers"),
+            pointerTemporalPosition: try await engine.makeInput(for: step, named: "ptr_tpos"),
+            pointerValid: try await engine.makeInput(for: step, named: "ptr_valid"))
+    }
+
+    /// Fill the bank for one object on one frame and hand back the shared tensors.
+    ///
+    /// The returned `PackedMemory` aliases this packer's storage, so it is only valid until
+    /// the next `pack` call, which is exactly the lifetime `tracker_step` needs.
+    func pack(
+        history: ObjectOutputHistory,
+        objectIndex: Int,
+        frameIndex: Int,
+        totalFrames: Int,
+        reverse: Bool
+    ) throws -> PackedMemory {
+        try packSpatial(history: history, objectIndex: objectIndex, frameIndex: frameIndex, reverse: reverse)
+        packPointers(
+            history: history, objectIndex: objectIndex, frameIndex: frameIndex,
+            totalFrames: totalFrames, reverse: reverse)
+        return packed
+    }
+
+    // MARK: - Spatial memory
+
+    private func packSpatial(
+        history: ObjectOutputHistory, objectIndex: Int, frameIndex: Int, reverse: Bool
+    ) throws {
+        let entries = Self.gatherMemoryFrames(
+            history: history, frameIndex: frameIndex, reverse: reverse, parameters: parameters)
+
+        var temporalIndices = [Int32](repeating: 0, count: shapes.spatialSlots)
+        var valid = [Float](repeating: 0, count: shapes.spatialSlots)
+        var slot = 0
+        for (offset, output) in entries {
+            guard let output,
+                let features = output.memoryFeatures,
+                let position = output.memoryPositionEncoding
+            else { continue }
+            guard slot < shapes.spatialSlots else {
+                throw VideoSegmentationError.unsupportedGeometry(
+                    "Object \(objectIndex) has more than \(shapes.spatialSlots) spatial memories "
+                        + "on frame \(frameIndex). Re-export with a larger --spatial-slots.")
+            }
+            write(features, into: &packed.spatialMemory, slot: slot)
+            write(position, into: &packed.spatialMemoryPosition, slot: slot)
+            temporalIndices[slot] = Int32(
+                Self.temporalIndex(forOffset: offset, numMaskmem: parameters.numMaskmem))
+            valid[slot] = 1
+            slot += 1
+        }
+
+        // Clear whatever the previous object left in the slots this one does not use.
+        if slot < previousSpatialSlots {
+            let range = (slot * spatialSlotElements)..<(previousSpatialSlots * spatialSlotElements)
+            clearHalfRegion(&packed.spatialMemory, range)
+            clearHalfRegion(&packed.spatialMemoryPosition, range)
+        }
+        previousSpatialSlots = slot
+
+        fillNDArray(&packed.spatialTemporalIndex, as: Int32.self, with: temporalIndices)
+        fillFloatNDArray(&packed.spatialValid, with: valid)
+    }
+
+    /// Row of `memory_temporal_positional_encoding` a memory at `offset` should use.
+    ///
+    /// HF indexes it as `[relative_temporal_offset - 1]`. Conditioning frames arrive with
+    /// offset 0, so that is Python's `[-1]`, the last row rather than an error. Swift has no
+    /// negative indexing and the graph gathers with a plain index, so wrap into range here.
+    nonisolated static func temporalIndex(forOffset offset: Int, numMaskmem: Int) -> Int {
+        ((offset - 1) % numMaskmem + numMaskmem) % numMaskmem
+    }
+
+    /// Port of `Sam3TrackerVideoModel._gather_memory_frame_outputs`.
+    ///
+    /// Returns `(relativeTemporalOffset, output)` pairs. Conditioning frames carry offset 0;
+    /// recent frames carry their distance. A `nil` output is a gap the caller skips, kept in
+    /// the list rather than filtered so the offsets stay attached to the right entries.
+    static func gatherMemoryFrames(
+        history: ObjectOutputHistory,
+        frameIndex: Int,
+        reverse: Bool,
+        parameters: VideoSegmentationParameters
+    ) -> [(offset: Int, output: StoredFrameOutput?)] {
+        let (selected, unselected) = selectClosestConditioningFrames(
+            history: history, frameIndex: frameIndex, limit: parameters.maxCondFrameNum)
+
+        var entries: [(offset: Int, output: StoredFrameOutput?)] = selected.map {
+            (0, history.conditioning[$0])
+        }
+        // Most recent last, matching upstream's `range(num_maskmem - 1, 0, -1)`. Order is
+        // irrelevant to the packed bank but is preserved so a slot-by-slot comparison
+        // against a reference lines up.
+        for offset in stride(from: parameters.numMaskmem - 1, to: 0, by: -1) {
+            let previousFrame = reverse ? frameIndex + offset : frameIndex - offset
+            let output =
+                history.nonConditioning[previousFrame]
+                ?? (unselected.contains(previousFrame) ? history.conditioning[previousFrame] : nil)
+            entries.append((offset, output))
+        }
+        return entries
+    }
+
+    /// Port of `_select_closest_cond_frames`: the nearest conditioning frame before the
+    /// current one, the nearest at or after it, then the next-closest until the cap.
+    static func selectClosestConditioningFrames(
+        history: ObjectOutputHistory, frameIndex: Int, limit: Int
+    ) -> (selected: [Int], unselected: Set<Int>) {
+        let all = history.conditioningOrder
+        if limit == -1 || all.count <= limit {
+            return (all, [])
+        }
+        var selected: [Int] = []
+        if let before = all.filter({ $0 < frameIndex }).max() { selected.append(before) }
+        if let after = all.filter({ $0 >= frameIndex }).min() { selected.append(after) }
+        let remaining =
+            all
+            .filter { !selected.contains($0) }
+            .sorted { abs($0 - frameIndex) < abs($1 - frameIndex) }
+            .prefix(max(0, limit - selected.count))
+        selected.append(contentsOf: remaining)
+        let unselected = Set(all).subtracting(selected)
+        return (selected, unselected)
+    }
+
+    // MARK: - Object pointers
+
+    private func packPointers(
+        history: ObjectOutputHistory,
+        objectIndex: Int,
+        frameIndex: Int,
+        totalFrames: Int,
+        reverse: Bool
+    ) {
+        var (offsets, pointers, maxPointers) = Self.objectPointers(
+            history: history, frameIndex: frameIndex, totalFrames: totalFrames,
+            reverse: reverse, parameters: parameters)
+
+        if pointers.count > shapes.ptrSlots {
+            // The spatial half of the bank is exactly sized, but this half is a budget:
+            // HF's conditioning-frame pointer branch has no cap, so a long video with
+            // frequent reconditioning can exceed it. Keep the temporally closest.
+            if !warnedAboutPointerOverflow {
+                warnedAboutPointerOverflow = true
+                CLILogger.log(
+                    "Object \(objectIndex) has \(pointers.count) object pointers on frame "
+                        + "\(frameIndex) but the asset has \(shapes.ptrSlots) slots; dropping the "
+                        + "furthest. Re-export with a larger --ptr-slots to restore parity. "
+                        + "(Reported once per video.)")
+            }
+            let keep =
+                offsets.indices
+                .sorted { abs(offsets[$0]) < abs(offsets[$1]) }
+                .prefix(shapes.ptrSlots)
+                .sorted()
+            offsets = keep.map { offsets[$0] }
+            pointers = keep.map { pointers[$0] }
+        }
+
+        // Upstream divides by `max_object_pointers_to_use - 1`, which is zero on a
+        // single-frame video. Clamp rather than emit infinities into the graph.
+        let maxTemporalDifference = Float(max(1, maxPointers - 1))
+        var temporalPositions = [Float](repeating: 0, count: shapes.ptrSlots)
+        var valid = [Float](repeating: 0, count: shapes.ptrSlots)
+        for (slot, offset) in offsets.enumerated() {
+            writePointer(pointers[slot], slot: slot)
+            temporalPositions[slot] = Float(offset) / maxTemporalDifference
+            valid[slot] = 1
+        }
+
+        if offsets.count < previousPointerSlots {
+            let range = (offsets.count * pointerSlotElements)..<(previousPointerSlots * pointerSlotElements)
+            clearHalfRegion(&packed.objectPointers, range)
+        }
+        previousPointerSlots = offsets.count
+
+        fillFloatNDArray(&packed.pointerTemporalPosition, with: temporalPositions)
+        fillFloatNDArray(&packed.pointerValid, with: valid)
+    }
+
+    /// Port of `Sam3TrackerVideoModel._get_object_pointers` in non-streaming mode.
+    static func objectPointers(
+        history: ObjectOutputHistory,
+        frameIndex: Int,
+        totalFrames: Int,
+        reverse: Bool,
+        parameters: VideoSegmentationParameters
+    ) -> (offsets: [Int], pointers: [NDArray], maxPointers: Int) {
+        let sign = reverse ? -1 : 1
+        let maxPointers = min(totalFrames, parameters.maxObjectPointers)
+
+        var offsets: [Int] = []
+        var pointers: [NDArray] = []
+
+        // Conditioning frames, in registration order, restricted to the past (or the
+        // future when tracking backwards). HF does this whenever `not self.training`.
+        for frame in history.conditioningOrder {
+            let eligible = reverse ? frame >= frameIndex : frame <= frameIndex
+            guard eligible, let output = history.conditioning[frame] else { continue }
+            offsets.append((frameIndex - frame) * sign)
+            pointers.append(output.objectPointer)
+        }
+
+        // Then a contiguous look-back over non-conditioning frames. The `break` on an
+        // out-of-range index is upstream's, and it stops the scan rather than skipping, so
+        // a video boundary truncates the pointer set.
+        for difference in 1..<max(1, maxPointers) {
+            let reference = reverse ? frameIndex + difference : frameIndex - difference
+            if reference < 0 || reference >= totalFrames { break }
+            guard let output = history.nonConditioning[reference] else { continue }
+            offsets.append(difference)
+            pointers.append(output.objectPointer)
+        }
+        return (offsets, pointers, maxPointers)
+    }
+
+    // MARK: - Slot writes
+
+    private func write(_ payload: MemoryPayload, into array: inout NDArray, slot: Int) {
+        #if !((os(macOS) || targetEnvironment(macCatalyst)) && arch(x86_64))
+        copyIntoNDArray(
+            &array, as: Float16.self, elementOffset: slot * spatialSlotElements,
+            from: payload.values)
+        #else
+        fatalError("Float16 is not supported on this platform")
+        #endif
+    }
+
+    private func writePointer(_ pointer: NDArray, slot: Int) {
+        #if !((os(macOS) || targetEnvironment(macCatalyst)) && arch(x86_64))
+        let values = readNDArray(pointer, as: Float16.self, count: pointerSlotElements)
+        copyIntoNDArray(
+            &packed.objectPointers, as: Float16.self,
+            elementOffset: slot * pointerSlotElements, from: values)
+        #else
+        fatalError("Float16 is not supported on this platform")
+        #endif
+    }
+
+    private func clearHalfRegion(_ array: inout NDArray, _ range: Range<Int>) {
+        #if !((os(macOS) || targetEnvironment(macCatalyst)) && arch(x86_64))
+        clearNDArrayRegion(&array, as: Float16.self, elementRange: range, value: 0)
+        #else
+        fatalError("Float16 is not supported on this platform")
+        #endif
+    }
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/Session/ObjectRegistry.swift b/swift/Sources/CoreAIVideoSegmenter/Session/ObjectRegistry.swift
new file mode 100644
index 00000000..482cfe56
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/Session/ObjectRegistry.swift
@@ -0,0 +1,63 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import Foundation
+
+/// Insertion-ordered map between client-visible object ids and the dense indices that
+/// index per-object storage.
+///
+/// Port of the `_obj_id_to_idx` / `_obj_idx_to_id` / `obj_ids` trio in
+/// `Sam3VideoInferenceSession`. Two invariants:
+///
+/// * `ids` order is meaningful. Tracker masks come back one row per index, and association,
+///   suppression, and the output builder all zip that row order against `ids`.
+/// * Removing an object renumbers every index above it, so per-object storage has to be
+///   compacted in lockstep. Leaving a hole would misattribute every later object's memory.
+struct ObjectRegistry {
+    /// Object ids in the order they were first seen.
+    private(set) var ids: [Int] = []
+    private var indexByID: [Int: Int] = [:]
+
+    var count: Int { ids.count }
+    var isEmpty: Bool { ids.isEmpty }
+
+    /// Index of `id`, registering it at the end if new.
+    ///
+    /// Returns the new index and whether it was just created, so the caller can grow its
+    /// parallel storage in the same step.
+    @discardableResult
+    mutating func index(of id: Int) -> (index: Int, isNew: Bool) {
+        if let existing = indexByID[id] { return (existing, false) }
+        let index = ids.count
+        indexByID[id] = index
+        ids.append(id)
+        return (index, true)
+    }
+
+    /// Index of `id` if it is registered.
+    func existingIndex(of id: Int) -> Int? { indexByID[id] }
+
+    func id(at index: Int) -> Int { ids[index] }
+
+    func contains(_ id: Int) -> Bool { indexByID[id] != nil }
+
+    /// Remove `id` and report the surviving indices in their old order, so callers can
+    /// compact parallel arrays with `newStorage = survivors.map { oldStorage[$0] }`.
+    ///
+    /// Returns `nil` when `id` was never registered, matching `remove_object`, which
+    /// quietly does nothing for an unknown id.
+    mutating func remove(_ id: Int) -> [Int]? {
+        guard let removed = indexByID[id] else { return nil }
+        let survivors = (0..<ids.count).filter { $0 != removed }
+        ids = survivors.map { ids[$0] }
+        indexByID = Dictionary(uniqueKeysWithValues: ids.enumerated().map { ($1, $0) })
+        return survivors
+    }
+
+    mutating func removeAll() {
+        ids.removeAll()
+        indexByID.removeAll()
+    }
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/Session/VideoInferenceSession.swift b/swift/Sources/CoreAIVideoSegmenter/Session/VideoInferenceSession.swift
new file mode 100644
index 00000000..18cf425d
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/Session/VideoInferenceSession.swift
@@ -0,0 +1,252 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreAI
+import CoreAIShared
+import Foundation
+
+/// Half-precision payload held on the host between frames.
+///
+/// Encoded memory leaves `memory_encode` as fp16 and goes straight back into `tracker_step`
+/// as fp16, so it is never interpreted here, only stored and copied. Keeping it as `Float16`
+/// rather than widening to `Float` halves the memory bank's footprint.
+struct MemoryPayload: Sendable {
+    #if !((os(macOS) || targetEnvironment(macCatalyst)) && arch(x86_64))
+    let values: [Float16]
+
+    init(reading array: NDArray) {
+        let count = array.shape.reduce(1, *)
+        self.values = readNDArray(array, as: Float16.self, count: count)
+    }
+
+    var count: Int { values.count }
+    #else
+    let values: [Float]
+
+    init(reading array: NDArray) {
+        self.values = flattenAsFloat(array)
+    }
+
+    var count: Int { values.count }
+    #endif
+}
+
+/// One object's stored result for one frame.
+///
+/// Deliberately smaller than HF's equivalent dict. Upstream keeps `high_res_masks` (1008²
+/// floats, 4 MB) forever and never reads it back; the memory encoder consumes the in-flight
+/// value on the frame it is produced. Dropping it is what makes a long video fit.
+struct StoredFrameOutput {
+    /// Low-resolution mask logits. Only re-read when a frame is revisited and the object
+    /// already has a conditioning output there, so it is pruned aggressively.
+    var predictedMasks: [Float]?
+    /// `(1, 1, hidden)` pointer, fed to `tracker_step` as one of the pointer slots.
+    var objectPointer: NDArray
+    var objectScoreLogit: Float
+    /// Set after the frame's memory encoding pass; absent until then.
+    var memoryFeatures: MemoryPayload?
+    var memoryPositionEncoding: MemoryPayload?
+}
+
+/// Per-object output history, split the way `output_dict_per_obj` is.
+///
+/// The conditioning / non-conditioning split is not bookkeeping: `_select_closest_cond_frames`
+/// picks from the first, `_gather_memory_frame_outputs` walks a fixed recent window of the
+/// second, and reconditioning promotes an entry from one to the other mid-frame.
+struct ObjectOutputHistory {
+    /// Frames where the object was seeded or reconditioned. Insertion-ordered, because
+    /// `_get_object_pointers` iterates them in that order.
+    var conditioning: [Int: StoredFrameOutput] = [:]
+    var conditioningOrder: [Int] = []
+    var nonConditioning: [Int: StoredFrameOutput] = [:]
+    /// Frames the object has been propagated through, and in which direction.
+    var framesTracked: [Int: Bool] = [:]
+    /// Pending mask prompts, keyed by frame.
+    var maskInputs: [Int: MaskPrompt] = [:]
+
+    mutating func store(_ output: StoredFrameOutput, at frame: Int, conditioning isConditioning: Bool) {
+        if isConditioning {
+            if conditioning[frame] == nil { conditioningOrder.append(frame) }
+            conditioning[frame] = output
+            // A frame is in exactly one bucket. Promoting without this leaves a stale
+            // copy that `_gather_memory_frame_outputs` could pick up as a recent memory.
+            nonConditioning[frame] = nil
+        } else {
+            nonConditioning[frame] = output
+        }
+    }
+
+    /// Move an existing non-conditioning entry into the conditioning bucket, which is what
+    /// `_tracker_update_memories` does for a reconditioned object.
+    mutating func promoteToConditioning(frame: Int) {
+        guard let existing = nonConditioning.removeValue(forKey: frame) else { return }
+        if conditioning[frame] == nil { conditioningOrder.append(frame) }
+        conditioning[frame] = existing
+    }
+
+    /// Drop history that can no longer be read.
+    ///
+    /// Upstream never prunes, which does not survive a long video. The window below is
+    /// derived from what the two readers can still reach:
+    ///
+    /// * `_gather_memory_frame_outputs` looks back at most `numMaskmem - 1` frames for
+    ///   spatial memory, so older non-conditioning entries can shed their mask memory.
+    /// * `_get_object_pointers` looks back at most `maxObjectPointers - 1` frames, so
+    ///   their pointers must survive that much longer.
+    /// * Conditioning entries are kept whole. `_get_object_pointers` iterates all of them,
+    ///   and there are few: one per seeding plus one per reconditioning.
+    mutating func prune(before frame: Int, memoryWindow: Int, pointerWindow: Int) {
+        let memoryFloor = frame - memoryWindow
+        let pointerFloor = frame - pointerWindow
+        for key in nonConditioning.keys {
+            if key < pointerFloor {
+                nonConditioning[key] = nil
+            } else if key < memoryFloor {
+                nonConditioning[key]?.memoryFeatures = nil
+                nonConditioning[key]?.memoryPositionEncoding = nil
+                nonConditioning[key]?.predictedMasks = nil
+            }
+        }
+        for key in conditioningOrder where key < memoryFloor {
+            // Keep the pointer and the memory (a conditioning frame can be selected from
+            // any distance), but the stored low-res mask is only read when that exact
+            // frame is revisited, which forward propagation never does.
+            conditioning[key]?.predictedMasks = nil
+        }
+    }
+}
+
+/// A mask prompt queued for an object on a frame, as a binary low-resolution mask.
+struct MaskPrompt {
+    let mask: MaskBitset
+}
+
+/// Host-side state for one video.
+///
+/// Port of `Sam3VideoInferenceSession` plus the per-object tracker state HF keeps inside
+/// `Sam3TrackerVideoInferenceSession`. Everything here is plain data; the logic that reads
+/// it lives in `Tracking/`.
+@VideoSegmentationActor
+final class VideoInferenceSession {
+    let videoWidth: Int
+    let videoHeight: Int
+
+    // MARK: - Prompts
+
+    /// Prompt text by id, in registration order.
+    private(set) var prompts: [String] = []
+    /// Encoded text features, filled on first use and reused for the whole video.
+    var promptEncodings: [Int: PromptEncoding] = [:]
+    /// Token ids and attention mask per prompt.
+    var promptTokens: [Int: (ids: [Int32], attentionMask: [Int32])] = [:]
+    /// Which prompt discovered each object.
+    var promptIDByObjectID: [Int: Int] = [:]
+
+    // MARK: - Objects
+
+    var registry = ObjectRegistry()
+    /// Parallel to `registry.ids`.
+    var histories: [ObjectOutputHistory] = []
+    /// Object ids seeded on this frame and not yet consumed by the tracker loop.
+    var objectsWithNewInputs: [Int] = []
+
+    // MARK: - Tracking metadata
+
+    var scoreByObjectID: [Int: Float] = [:]
+    var trackerScoreByFrame: [Int: [Int: Float]] = [:]
+    var lastOccludedByObjectID: [Int: Int] = [:]
+    var maxObjectID: Int = -1
+
+    // MARK: - Hotstart metadata
+
+    var firstFrameByObjectID: [Int: Int] = [:]
+    var unmatchedFramesByObjectID: [Int: [Int]] = [:]
+    var overlapFramesByPair: [OverlapPair: [Int]] = [:]
+    var keepAliveByObjectID: [Int: Int] = [:]
+    var removedObjectIDs: Set<Int> = []
+    var suppressedObjectIDsByFrame: [Int: Set<Int>] = [:]
+    /// Objects hotstart removed at any point; the postprocessor hides them retroactively.
+    var hotstartRemovedObjectIDs: Set<Int> = []
+
+    // MARK: - Frame cache
+
+    /// Tracker features for the frame being processed, matching HF's
+    /// `max_vision_features_cache_size` default of 1. The tracker reads them once per object,
+    /// all within a single frame.
+    var cachedFrameIndex: Int?
+    var cachedFeatures: TrackerFeatures?
+
+    struct OverlapPair: Hashable {
+        let firstAppearing: Int
+        let duplicate: Int
+    }
+
+    init(videoWidth: Int, videoHeight: Int) {
+        self.videoWidth = videoWidth
+        self.videoHeight = videoHeight
+    }
+
+    // MARK: - Prompts
+
+    /// Register `text`, returning its id. Duplicate text reuses the existing id, matching
+    /// `Sam3VideoInferenceSession.add_prompt`.
+    func addPrompt(_ text: String) -> Int {
+        if let existing = prompts.firstIndex(of: text) { return existing }
+        prompts.append(text)
+        return prompts.count - 1
+    }
+
+    func promptText(_ id: Int) -> String { prompts[id] }
+
+    var promptIDs: [Int] { Array(prompts.indices) }
+
+    // MARK: - Objects
+
+    var objectIDs: [Int] { registry.ids }
+    var objectCount: Int { registry.count }
+
+    /// Index of `id`, creating its history if this is the first sighting.
+    @discardableResult
+    func index(ofObject id: Int) -> Int {
+        let (index, isNew) = registry.index(of: id)
+        if isNew { histories.append(ObjectOutputHistory()) }
+        return index
+    }
+
+    /// Remove an object and every trace of it, compacting the parallel storage.
+    ///
+    /// Port of `Sam3VideoInferenceSession.remove_object`. Upstream resets the whole
+    /// session when the last object goes; that is equivalent to clearing here, and
+    /// clearing keeps prompt state that a reset would also need to preserve.
+    func removeObject(_ id: Int) {
+        guard let survivors = registry.remove(id) else { return }
+        histories = survivors.map { histories[$0] }
+        promptIDByObjectID[id] = nil
+        lastOccludedByObjectID[id] = nil
+        objectsWithNewInputs.removeAll { $0 == id }
+    }
+
+    /// Set `frame`'s tracker features, replacing whatever the previous frame left.
+    func cache(_ features: TrackerFeatures, forFrame frame: Int) {
+        cachedFrameIndex = frame
+        cachedFeatures = features
+    }
+
+    func features(forFrame frame: Int) throws -> TrackerFeatures {
+        guard cachedFrameIndex == frame, let cachedFeatures else {
+            throw VideoSegmentationError.invalidConfiguration(
+                "No cached tracker features for frame \(frame); the frame loop ran out of order.")
+        }
+        return cachedFeatures
+    }
+
+    /// Drop history no reader can reach any more, for every object.
+    func prune(currentFrame: Int, memoryWindow: Int, pointerWindow: Int) {
+        for index in histories.indices {
+            histories[index].prune(
+                before: currentFrame, memoryWindow: memoryWindow, pointerWindow: pointerWindow)
+        }
+    }
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/Tracking/Associator.swift b/swift/Sources/CoreAIVideoSegmenter/Tracking/Associator.swift
new file mode 100644
index 00000000..73dfe8e5
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/Tracking/Associator.swift
@@ -0,0 +1,112 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreAIShared
+import Foundation
+
+/// Matches this frame's detections against the existing masklets.
+///
+/// Port of `Sam3VideoModel._associate_det_trk`. The two IoU thresholds are easy to conflate:
+/// `assocIouThresh` (loose, 0.1) decides whether a detection is covered by some track and so
+/// is not new, while `trkAssocIouThresh` (strict, 0.5) decides whether a track was seen this
+/// frame and so is not unmatched. The same pair can be matched by the first test and unmatched
+/// by the second.
+enum Associator {
+    struct Result {
+        /// Detection indices that should become new objects.
+        var newDetectionIndices: [Int] = []
+        /// Non-empty tracks no detection covered this frame.
+        var unmatchedTrackIDs: [Int] = []
+        /// Detection index to every track it overlaps above the loose threshold.
+        var detectionToMatchedTrackIDs: [Int: [Int]] = [:]
+        /// Track id to the single high-confidence, high-IoU detection that may recondition
+        /// it. At most one per track.
+        var trackIDToHighConfidenceDetection: [Int: Int] = [:]
+        /// Tracks whose predicted mask came back empty.
+        var emptyTrackIDs: [Int] = []
+    }
+
+    /// - Parameters:
+    ///   - detections: This frame's merged detections.
+    ///   - trackMasks: Tracker masks, one per entry of `trackIDs`, in that order.
+    ///   - trackIDs: Object ids in registry order.
+    ///   - trackPromptIDs: Prompt each tracked object belongs to, parallel to `trackIDs`.
+    static func associate(
+        detections: MergedDetections,
+        trackMasks: [MaskBitset],
+        trackIDs: [Int],
+        trackPromptIDs: [Int],
+        parameters: VideoSegmentationParameters
+    ) -> Result {
+        var result = Result()
+
+        if trackMasks.isEmpty {
+            // Nothing to match against, so every detection is new. This branch skips the
+            // `newDetThresh` score gate the general path applies, as upstream does; that is
+            // how the first frame seeds tracks from detections below the new-object threshold.
+            result.newDetectionIndices = Array(0..<detections.count)
+            return result
+        }
+        if detections.isEmpty {
+            for (index, id) in trackIDs.enumerated() {
+                if trackMasks[index].isEmpty {
+                    result.emptyTrackIDs.append(id)
+                } else {
+                    result.unmatchedTrackIDs.append(id)
+                }
+            }
+            return result
+        }
+
+        // Full IoU matrix, zeroed across prompt groups so a "person" detection can never
+        // claim a "dog" track.
+        var ious = [[Float]](
+            repeating: [Float](repeating: 0, count: trackMasks.count), count: detections.count)
+        for detection in 0..<detections.count {
+            for track in 0..<trackMasks.count where detections.promptIDs[detection] == trackPromptIDs[track] {
+                ious[detection][track] = detections.masks[detection].iou(trackMasks[track])
+            }
+        }
+
+        // A track is unmatched when it has area but no detection reaches the strict
+        // threshold. Empty tracks are reported separately: they are occluded, not lost.
+        for (track, id) in trackIDs.enumerated() {
+            if trackMasks[track].isEmpty {
+                result.emptyTrackIDs.append(id)
+                continue
+            }
+            let matched = (0..<detections.count).contains {
+                ious[$0][track] >= parameters.trkAssocIouThresh
+            }
+            if !matched { result.unmatchedTrackIDs.append(id) }
+        }
+
+        for detection in 0..<detections.count {
+            let row = ious[detection]
+            let matchedTracks = (0..<trackMasks.count).filter {
+                row[$0] >= parameters.assocIouThresh
+            }
+            result.detectionToMatchedTrackIDs[detection] = matchedTracks.map { trackIDs[$0] }
+
+            let isNew =
+                detections.scores[detection] >= parameters.newDetThresh && matchedTracks.isEmpty
+            if isNew {
+                result.newDetectionIndices.append(detection)
+                // A new detection cannot also recondition an existing track.
+                continue
+            }
+
+            // Reconditioning candidate: confident enough, overlapping enough, and mapped
+            // to its single best track. Later detections overwrite earlier ones for the
+            // same track, which is upstream's behaviour.
+            guard detections.scores[detection] >= parameters.highConfThresh else { continue }
+            guard let best = row.indices.max(by: { row[$0] < row[$1] }) else { continue }
+            if row[best] >= parameters.highIouThresh {
+                result.trackIDToHighConfidenceDetection[trackIDs[best]] = detection
+            }
+        }
+        return result
+    }
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/Tracking/DetectionDecoder.swift b/swift/Sources/CoreAIVideoSegmenter/Tracking/DetectionDecoder.swift
new file mode 100644
index 00000000..f3ae06a2
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/Tracking/DetectionDecoder.swift
@@ -0,0 +1,124 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreAI
+import CoreAIShared
+import Foundation
+
+/// Turns `detect`'s raw tensors into the detection set the tracker consumes.
+///
+/// Port of the scoring half of `Sam3VideoModel.run_detection` plus
+/// `_merge_detections_from_prompts` and `nms_masks`.
+enum DetectionDecoder {
+    /// Decode one prompt's detections.
+    ///
+    /// The logits are read first and thresholded before any mask is touched. `pred_masks` is
+    /// `[1, 200, 288, 288]`, 66 MB as `Float`, and only a handful of the 200 queries usually
+    /// survive, so converting just their slices saves most of that per prompt per frame.
+    static func decode(
+        _ outputs: DetectOutputs,
+        promptID: Int,
+        maskSize: Int,
+        parameters: VideoSegmentationParameters
+    ) -> MergedDetections {
+        let logits = flattenAsFloat(outputs.predictedLogits)
+        let presence = flattenAsFloat(outputs.presenceLogits)
+        // A single presence logit gates the whole prompt: `pred_probs * presence.sigmoid()`.
+        let presenceScore = sigmoid(presence.first ?? 0)
+
+        var probabilities = [Float](repeating: 0, count: logits.count)
+        for index in logits.indices {
+            probabilities[index] = sigmoid(logits[index]) * presenceScore
+        }
+
+        var candidates = probabilities.indices.filter {
+            probabilities[$0] > parameters.scoreThresholdDetection
+        }
+        guard !candidates.isEmpty else { return MergedDetections() }
+
+        let pixels = maskSize * maskSize
+        var maskLogits = candidates.map { query in
+            floatElements(outputs.predictedMasks, in: (query * pixels)..<((query + 1) * pixels))
+        }
+        var masks = maskLogits.map {
+            MaskBitset(thresholding: $0, width: maskSize, height: maskSize)
+        }
+
+        if parameters.detNmsThresh > 0 {
+            let keep = nonMaximumSuppression(
+                masks: masks,
+                scores: candidates.map { probabilities[$0] },
+                iouThreshold: parameters.detNmsThresh)
+            // Upstream zeroes the suppressed probabilities and re-thresholds, which is the
+            // same as dropping them: `pred_probs[0][~keep] = 0.0` then
+            // `pred_probs > score_threshold_detection`.
+            candidates = keep.map { candidates[$0] }
+            maskLogits = keep.map { maskLogits[$0] }
+            masks = keep.map { masks[$0] }
+        }
+
+        return MergedDetections(
+            maskLogits: maskLogits,
+            masks: masks,
+            scores: candidates.map { probabilities[$0] },
+            promptIDs: [Int](repeating: promptID, count: candidates.count))
+    }
+
+    /// Concatenate per-prompt detections in prompt-id order.
+    ///
+    /// Port of `_merge_detections_from_prompts`. Order matters downstream: new objects are
+    /// numbered by their position here, so a reordering would renumber every track.
+    static func merge(_ perPrompt: [MergedDetections]) -> MergedDetections {
+        var merged = MergedDetections()
+        for detections in perPrompt {
+            merged.maskLogits.append(contentsOf: detections.maskLogits)
+            merged.masks.append(contentsOf: detections.masks)
+            merged.scores.append(contentsOf: detections.scores)
+            merged.promptIDs.append(contentsOf: detections.promptIDs)
+        }
+        return merged
+    }
+
+    /// Greedy mask-IoU non-maximum suppression, returning the surviving indices in
+    /// descending-score order.
+    ///
+    /// Port of `nms_masks`, which prefilters by score and then defers to
+    /// `cv_utils_kernel.generic_nms`. That kernel is a standard greedy NMS over the
+    /// supplied IoU matrix; the caller here has already applied the score prefilter, so
+    /// only the greedy pass remains.
+    static func nonMaximumSuppression(
+        masks: [MaskBitset], scores: [Float], iouThreshold: Float
+    ) -> [Int] {
+        precondition(masks.count == scores.count, "NMS: masks and scores must be parallel")
+        // Ties broken by index so the result does not depend on sort stability.
+        let order = scores.indices.sorted {
+            scores[$0] == scores[$1] ? $0 < $1 : scores[$0] > scores[$1]
+        }
+        var suppressed = [Bool](repeating: false, count: masks.count)
+        var kept: [Int] = []
+        for candidate in order where !suppressed[candidate] {
+            kept.append(candidate)
+            for other in order where other != candidate && !suppressed[other] {
+                if masks[candidate].iou(masks[other]) >= iouThreshold {
+                    suppressed[other] = true
+                }
+            }
+        }
+        // Restore input order: downstream indexes detections positionally and expects the
+        // prompt's own ordering, not the score ordering.
+        return kept.sorted()
+    }
+
+    @inline(__always)
+    static func sigmoid(_ x: Float) -> Float {
+        // Branch on the sign so the exponent argument is never positive; `exp` of a large
+        // positive logit overflows to infinity and turns the result into NaN.
+        if x >= 0 {
+            return 1 / (1 + Foundation.exp(-x))
+        }
+        let e = Foundation.exp(x)
+        return e / (1 + e)
+    }
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/Tracking/FrameProcessor.swift b/swift/Sources/CoreAIVideoSegmenter/Tracking/FrameProcessor.swift
new file mode 100644
index 00000000..bf1ff14e
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/Tracking/FrameProcessor.swift
@@ -0,0 +1,446 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreAI
+import CoreAIShared
+import CoreGraphics
+import Foundation
+
+/// Runs one frame end to end: encode, detect, propagate, plan, execute, emit.
+///
+/// Port of `Sam3VideoModel._det_track_one_frame`, `run_tracker_update_planning_phase`,
+/// `run_tracker_update_execution_phase`, `build_outputs`, and `forward`.
+///
+/// The phase split is load-bearing. Planning resolves every heuristic and encodes memory
+/// from the de-overlapped masks; only then does execution mutate the object set. Merging
+/// the two would let a track that is about to be removed contribute memory, or a track
+/// that is about to be created miss this frame's memory.
+@VideoSegmentationActor
+final class FrameProcessor {
+    private let engine: VideoSegmentationEngine
+    private let shapes: VideoSegmentationEngine.Shapes
+    private let parameters: VideoSegmentationParameters
+    private let tracker: TrackerLoop
+    private let preprocessor: FramePreprocessor
+
+    /// Wall-clock spent in each entrypoint, for the CLI's timing summary.
+    private(set) var timings: [String: Double] = [:]
+
+    init(
+        engine: VideoSegmentationEngine,
+        shapes: VideoSegmentationEngine.Shapes,
+        parameters: VideoSegmentationParameters,
+        tracker: TrackerLoop
+    ) {
+        self.engine = engine
+        self.shapes = shapes
+        self.parameters = parameters
+        self.tracker = tracker
+        self.preprocessor = FramePreprocessor(
+            targetSize: shapes.imageSize,
+            mean: parameters.normalizationMeans,
+            standardDeviation: parameters.normalizationStds)
+    }
+
+    /// Process `image` as frame `frameIndex`, returning the raw per-object masks.
+    func process(
+        session: VideoInferenceSession,
+        image: CGImage,
+        frameIndex: Int,
+        totalFrames: Int,
+        reverse: Bool
+    ) async throws -> RawFrameOutput {
+        // 1. One ViT pass, shared by the detector and the tracker exactly as upstream.
+        let pixels = try preprocessor.preprocess(image)
+        let backbone = try await timed(VideoSegmentationEngine.Function.imageEncode) {
+            try await engine.imageEncode(pixelValues: pixels)
+        }
+
+        let detections = try await runDetection(session: session, backbone: backbone)
+
+        let features = try await timed(VideoSegmentationEngine.Function.trackerEncode) {
+            try await engine.trackerEncode(lastHiddenState: backbone)
+        }
+        session.cache(features, forFrame: frameIndex)
+
+        // 2. Propagate existing tracks. Memory encoding is deferred to the planning phase,
+        // which first has to resolve non-overlap.
+        var trackerLogits: [[Float]] = []
+        var trackerScoreLogits: [Float] = []
+        if !session.objectIDs.isEmpty {
+            let propagation = try await timed(VideoSegmentationEngine.Function.trackerStep) {
+                try await tracker.propagate(
+                    session: session, frameIndex: frameIndex, totalFrames: totalFrames,
+                    reverse: reverse, runMemoryEncoder: false)
+            }
+            trackerLogits = propagation.maskLogits
+            trackerScoreLogits = propagation.objectScoreLogits
+            for index in trackerLogits.indices {
+                ConnectedComponents.fillHoles(
+                    &trackerLogits[index], width: shapes.lowResMaskSize,
+                    height: shapes.lowResMaskSize, maxArea: parameters.fillHoleArea)
+            }
+        }
+
+        // 3. Plan. Runs every heuristic and encodes this frame's memory.
+        let planning = try await plan(
+            session: session, frameIndex: frameIndex, reverse: reverse,
+            detections: detections, trackerLogits: &trackerLogits,
+            trackerScoreLogits: trackerScoreLogits)
+
+        // 4. Execute: seed new objects, drop removed ones.
+        try await execute(
+            session: session, frameIndex: frameIndex, totalFrames: totalFrames,
+            reverse: reverse, detections: detections, plan: planning.plan)
+
+        // 5. Emit.
+        let output = buildOutputs(
+            session: session, frameIndex: frameIndex, detections: detections,
+            trackerLogits: trackerLogits, trackerScoreLogits: trackerScoreLogits,
+            plan: planning.plan, newScores: planning.newScores)
+
+        // 6. Shed history nothing can reach any more. Upstream never does this.
+        session.prune(
+            currentFrame: frameIndex,
+            memoryWindow: max(parameters.numMaskmem, 1),
+            pointerWindow: max(parameters.maxObjectPointers, parameters.numMaskmem))
+        return output
+    }
+
+    /// What the planning phase produced.
+    private struct Planning {
+        var plan: TrackerUpdatePlan
+        /// Scores assigned to objects created or removed on this frame.
+        var newScores: [Int: Float]
+    }
+
+    // MARK: - Detection
+
+    private func runDetection(
+        session: VideoInferenceSession, backbone: NDArray
+    ) async throws -> MergedDetections {
+        guard !session.promptIDs.isEmpty else { throw VideoSegmentationError.noPrompts }
+
+        var perPrompt: [MergedDetections] = []
+        for promptID in session.promptIDs {
+            let encoding: PromptEncoding
+            if let cached = session.promptEncodings[promptID] {
+                encoding = cached
+            } else {
+                guard let tokens = session.promptTokens[promptID] else {
+                    throw VideoSegmentationError.invalidConfiguration(
+                        "Prompt \(promptID) was registered but never tokenized.")
+                }
+                encoding = try await timed(VideoSegmentationEngine.Function.textEncode) {
+                    try await engine.textEncode(
+                        inputIDs: tokens.ids, attentionMask: tokens.attentionMask)
+                }
+                session.promptEncodings[promptID] = encoding
+            }
+
+            let outputs = try await timed(VideoSegmentationEngine.Function.detect) {
+                try await engine.detect(lastHiddenState: backbone, prompt: encoding)
+            }
+            perPrompt.append(
+                DetectionDecoder.decode(
+                    outputs, promptID: promptID, maskSize: shapes.lowResMaskSize,
+                    parameters: parameters))
+        }
+        return DetectionDecoder.merge(perPrompt)
+    }
+
+    // MARK: - Planning phase
+
+    /// Port of `run_tracker_update_planning_phase`.
+    ///
+    /// Mutates `trackerLogits`: occlusion suppression and the area-shrinkage rule both
+    /// blank objects in place, and the blanked masks are what get encoded into memory and
+    /// reported as output.
+    private func plan(
+        session: VideoInferenceSession,
+        frameIndex: Int,
+        reverse: Bool,
+        detections: MergedDetections,
+        trackerLogits: inout [[Float]],
+        trackerScoreLogits: [Float]
+    ) async throws -> Planning {
+        var plan = TrackerUpdatePlan()
+        let objectIDsSnapshot = session.objectIDs
+
+        let trackMasks = trackerLogits.map {
+            MaskBitset(thresholding: $0, width: shapes.lowResMaskSize, height: shapes.lowResMaskSize)
+        }
+        let trackPromptIDs = objectIDsSnapshot.map { session.promptIDByObjectID[$0] ?? 0 }
+
+        let association = Associator.associate(
+            detections: detections, trackMasks: trackMasks, trackIDs: objectIDsSnapshot,
+            trackPromptIDs: trackPromptIDs, parameters: parameters)
+
+        plan.unmatchedTrackIDs = association.unmatchedTrackIDs
+        plan.detectionToMatchedTrackIDs = association.detectionToMatchedTrackIDs
+        plan.trackIDToHighConfidenceDetection = association.trackIDToHighConfidenceDetection
+
+        // Object-count ceiling: keep the highest-scoring new detections.
+        var newIndices = association.newDetectionIndices
+        let existing = objectIDsSnapshot.count
+        if existing + newIndices.count > parameters.maxNumObjects {
+            let keepCount = max(0, parameters.maxNumObjects - existing)
+            plan.droppedDueToObjectLimit = newIndices.count - keepCount
+            CLILogger.log(
+                "Frame \(frameIndex): hit max_num_objects (\(parameters.maxNumObjects)); dropping "
+                    + "\(plan.droppedDueToObjectLimit) of \(newIndices.count) new detections.")
+            newIndices =
+                newIndices
+                .sorted { detections.scores[$0] > detections.scores[$1] }
+                .prefix(keepCount)
+                .sorted()
+        }
+        plan.newDetectionIndices = newIndices
+
+        // Ids are assigned by position, so the sort above is the only thing that may
+        // reorder them.
+        let firstNewID = session.maxObjectID + 1
+        plan.newObjectIDs = (0..<newIndices.count).map { firstNewID + $0 }
+        for (objectID, detectionIndex) in zip(plan.newObjectIDs, newIndices) {
+            session.promptIDByObjectID[objectID] = detections.promptIDs[detectionIndex]
+        }
+
+        plan.newlyRemovedObjectIDs = HotstartHeuristics.process(
+            session: session, frameIndex: frameIndex, reverse: reverse,
+            detectionToMatchedTrackIDs: association.detectionToMatchedTrackIDs,
+            newObjectIDs: plan.newObjectIDs,
+            emptyTrackIDs: association.emptyTrackIDs,
+            unmatchedTrackIDs: association.unmatchedTrackIDs,
+            parameters: parameters)
+
+        // Reconditioning, on a fixed cadence and only when there is something to
+        // recondition against.
+        var reconditionedMasks: [Int: ReconditionSource] = [:]
+        let shouldRecondition =
+            parameters.reconditionEveryNthFrame > 0
+            && frameIndex % parameters.reconditionEveryNthFrame == 0
+            && !association.trackIDToHighConfidenceDetection.isEmpty
+        if shouldRecondition {
+            (reconditionedMasks, plan.reconditionedObjectIDs) = prepareReconditionMasks(
+                session: session, detections: detections,
+                trackerScoreLogits: trackerScoreLogits,
+                candidates: association.trackIDToHighConfidenceDetection)
+        }
+
+        // Memory encoding for this frame, from the de-overlapped masks.
+        if !objectIDsSnapshot.isEmpty {
+            if parameters.suppressOverlappingOcclusionThreshold > 0 {
+                OcclusionSuppressor.suppressRecentlyOccluded(
+                    logits: &trackerLogits, masks: trackMasks, objectIDs: objectIDsSnapshot,
+                    promptIDs: trackPromptIDs,
+                    newlyRemovedObjectIDs: plan.newlyRemovedObjectIDs,
+                    frameIndex: frameIndex, reverse: reverse, session: session,
+                    parameters: parameters)
+            }
+            try await updateMemories(
+                session: session, frameIndex: frameIndex, trackerLogits: trackerLogits,
+                reconditionedMasks: reconditionedMasks, promptIDs: trackPromptIDs)
+        }
+
+        // Score bookkeeping. New objects inherit their detection score; removed ones are
+        // pushed far negative but kept in the map, which is how upstream keeps output
+        // assembly uniform.
+        var newScores: [Int: Float] = [:]
+        for (objectID, detectionIndex) in zip(plan.newObjectIDs, newIndices) {
+            let score = detections.scores[detectionIndex]
+            session.scoreByObjectID[objectID] = score
+            newScores[objectID] = score
+        }
+        if let maximum = plan.newObjectIDs.max() {
+            session.maxObjectID = max(session.maxObjectID, maximum)
+        }
+        for objectID in plan.newlyRemovedObjectIDs {
+            session.scoreByObjectID[objectID] = -1e4
+            newScores[objectID] = -1e4
+            session.lastOccludedByObjectID[objectID] = nil
+        }
+        return Planning(plan: plan, newScores: newScores)
+    }
+
+    /// Where a reconditioned object's memory mask comes from.
+    ///
+    /// `trackerMask` is not "the tracker mask captured now" but "whatever the tracker mask is
+    /// when memory is encoded". Upstream stores a view into `tracker_low_res_masks_global`
+    /// here, and occlusion suppression mutates that tensor in place between capture and use, so
+    /// a reconditioned object that is also suppressed contributes a blanked mask. Holding a
+    /// copy taken before suppression would silently reinstate it.
+    private enum ReconditionSource {
+        case trackerMask
+        case detectionMask([Float])
+    }
+
+    /// Port of `_prepare_recondition_masks`.
+    ///
+    /// The two modes are opposites and the flag name reads backwards at a glance:
+    /// `reconditionOnTrkMasks == true` means "the detector agrees, so reinforce memory
+    /// with what the *tracker* produced"; false means "the detector disagrees, so overwrite
+    /// with the *detection*".
+    private func prepareReconditionMasks(
+        session: VideoInferenceSession,
+        detections: MergedDetections,
+        trackerScoreLogits: [Float],
+        candidates: [Int: Int]
+    ) -> ([Int: ReconditionSource], Set<Int>) {
+        var masks: [Int: ReconditionSource] = [:]
+        var reconditioned: Set<Int> = []
+        for (trackID, detectionIndex) in candidates.sorted(by: { $0.key < $1.key }) {
+            guard let objectIndex = session.registry.existingIndex(of: trackID) else { continue }
+            // Note this compares a raw logit against a probability-shaped threshold, which
+            // is what upstream does; `tracker_obj_scores_global` is not passed through a
+            // sigmoid first. In practice it admits any object with a positive score.
+            guard objectIndex < trackerScoreLogits.count,
+                trackerScoreLogits[objectIndex] > parameters.highConfThresh
+            else { continue }
+
+            if parameters.reconditionOnTrkMasks {
+                masks[objectIndex] = .trackerMask
+            } else {
+                // Upstream stores `det_mask >= 0.5` as a bool tensor here, which becomes
+                // 0.0/1.0 when the memory encoder casts it to float.
+                masks[objectIndex] = .detectionMask(
+                    detections.maskLogits[detectionIndex].map { $0 >= 0.5 ? 1 : 0 })
+            }
+            reconditioned.insert(trackID)
+        }
+        return (masks, reconditioned)
+    }
+
+    /// Port of `_tracker_update_memories`.
+    private func updateMemories(
+        session: VideoInferenceSession,
+        frameIndex: Int,
+        trackerLogits: [[Float]],
+        reconditionedMasks: [Int: ReconditionSource],
+        promptIDs: [Int]
+    ) async throws {
+        var masks = trackerLogits
+        for (objectIndex, source) in reconditionedMasks {
+            // `.trackerMask` resolves against the tracker logits as they are now, after
+            // suppression. See `ReconditionSource`.
+            if case .detectionMask(let mask) = source { masks[objectIndex] = mask }
+            // A reconditioned object's frame becomes a conditioning frame, which changes
+            // both what the memory bank may select and which pointers are eligible.
+            session.histories[objectIndex].promoteToConditioning(frame: frameIndex)
+        }
+        OcclusionSuppressor.suppressAreaShrinkage(logits: &masks, promptIDs: promptIDs)
+        try await timed(VideoSegmentationEngine.Function.memoryEncode) {
+            try await tracker.encodeFinalMemories(
+                session: session, frameIndex: frameIndex, maskLogits: masks)
+        }
+    }
+
+    // MARK: - Execution phase
+
+    /// Port of `run_tracker_update_execution_phase`.
+    private func execute(
+        session: VideoInferenceSession,
+        frameIndex: Int,
+        totalFrames: Int,
+        reverse: Bool,
+        detections: MergedDetections,
+        plan: TrackerUpdatePlan
+    ) async throws {
+        if !plan.newDetectionIndices.isEmpty {
+            try await timed(VideoSegmentationEngine.Function.trackerMaskInit) {
+                try await tracker.addNewObjects(
+                    session: session, frameIndex: frameIndex, totalFrames: totalFrames,
+                    newObjectIDs: plan.newObjectIDs,
+                    newObjectMaskLogits: plan.newDetectionIndices.map { detections.maskLogits[$0] },
+                    reverse: reverse)
+            }
+        }
+        // Sorted so removal order, and therefore the index renumbering, is deterministic.
+        // Upstream iterates a set, whose order is arbitrary; the end state is the same either
+        // way because each removal is independent.
+        for objectID in plan.newlyRemovedObjectIDs.sorted() {
+            session.removeObject(objectID)
+        }
+    }
+
+    // MARK: - Output assembly
+
+    /// Port of `build_outputs` plus the metadata bookkeeping at the end of `forward`.
+    ///
+    /// Both zips below run the post-execution object list against pre-execution arrays, and
+    /// truncate at the shorter. That is upstream's own indexing: `build_outputs` and
+    /// `_det_track_one_frame` both read `inference_session.obj_ids` after the execution phase
+    /// has already mutated it. It is exact whenever nothing was removed this frame, since new
+    /// ids fall past the end of the tracker arrays and are filled in from detections below.
+    private func buildOutputs(
+        session: VideoInferenceSession,
+        frameIndex: Int,
+        detections: MergedDetections,
+        trackerLogits: [[Float]],
+        trackerScoreLogits: [Float],
+        plan: TrackerUpdatePlan,
+        newScores: [Int: Float]
+    ) -> RawFrameOutput {
+        var maskByObjectID: [Int: [Float]] = [:]
+        let currentObjectIDs = session.objectIDs
+
+        for (objectID, mask) in zip(currentObjectIDs, trackerLogits) {
+            maskByObjectID[objectID] = mask
+        }
+
+        // New objects show their *detection* mask, not what the tracker produced when it
+        // was seeded from it.
+        for (objectID, detectionIndex) in zip(plan.newObjectIDs, plan.newDetectionIndices) {
+            var mask = detections.maskLogits[detectionIndex]
+            ConnectedComponents.fillHoles(
+                &mask, width: shapes.lowResMaskSize, height: shapes.lowResMaskSize,
+                maxArea: parameters.fillHoleArea)
+            maskByObjectID[objectID] = mask
+        }
+
+        // Reconditioned objects are overridden by the detection that reconditioned them,
+        // whichever mode `reconditionOnTrkMasks` selected for memory.
+        for objectID in plan.reconditionedObjectIDs.sorted() {
+            guard let detectionIndex = plan.trackIDToHighConfidenceDetection[objectID] else {
+                continue
+            }
+            maskByObjectID[objectID] = detections.maskLogits[detectionIndex]
+        }
+
+        // Tracker scores for the frame, as probabilities. New objects are written first
+        // and the tracker's own scores second, matching upstream's update order.
+        var trackerScores = session.trackerScoreByFrame[frameIndex] ?? [:]
+        for (objectID, score) in newScores { trackerScores[objectID] = score }
+        for (objectID, logit) in zip(currentObjectIDs, trackerScoreLogits) {
+            trackerScores[objectID] = DetectionDecoder.sigmoid(logit)
+        }
+        session.trackerScoreByFrame[frameIndex] = trackerScores
+
+        // Hotstart hides removed objects retroactively, which only makes sense when the
+        // output was delayed long enough for the decision to precede the display.
+        if parameters.hotstartEnabled {
+            session.hotstartRemovedObjectIDs.formUnion(session.removedObjectIDs)
+        }
+
+        // Keyed off the mask map, not the registry: a removed object keeps its entry for
+        // this frame and is hidden by the postprocessor, exactly as upstream does.
+        return RawFrameOutput(
+            frameIndex: frameIndex,
+            maskLogitsByObjectID: maskByObjectID,
+            objectIDs: maskByObjectID.keys.sorted(),
+            scoreByObjectID: session.scoreByObjectID,
+            trackerScoreByObjectID: trackerScores,
+            suppressedObjectIDs: session.suppressedObjectIDsByFrame[frameIndex] ?? [])
+    }
+
+    // MARK: - Timing
+
+    @discardableResult
+    private func timed<T>(_ name: String, _ body: () async throws -> T) async rethrows -> T {
+        let started = ContinuousClock.now
+        let result = try await body()
+        timings[name, default: 0] += (ContinuousClock.now - started).inSeconds
+        return result
+    }
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/Tracking/HotstartHeuristics.swift b/swift/Sources/CoreAIVideoSegmenter/Tracking/HotstartHeuristics.swift
new file mode 100644
index 00000000..48cc9100
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/Tracking/HotstartHeuristics.swift
@@ -0,0 +1,144 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreAIShared
+import Foundation
+
+/// Removes tracks that never settle: ones the detector stops confirming, and duplicates
+/// of an earlier track.
+///
+/// Port of `Sam3VideoModel._process_hotstart`. Both rules only fire for tracks that first
+/// appeared inside the hotstart window; a track older than that has earned the benefit of the
+/// doubt. The window is why output lags by `hotstartDelay` frames: a track removed on frame 20
+/// must never have been shown on frame 8.
+///
+/// The keep-alive counter is a separate, always-on mechanism layered on the same
+/// bookkeeping: matched frames raise it toward `maxTrkKeepAlive`, unmatched ones lower it
+/// toward `minTrkKeepAlive`, and a track at or below zero is suppressed for the frame
+/// rather than removed outright.
+@VideoSegmentationActor
+enum HotstartHeuristics {
+    /// Mutates the session's hotstart bookkeeping and returns the ids removed on this
+    /// frame.
+    static func process(
+        session: VideoInferenceSession,
+        frameIndex: Int,
+        reverse: Bool,
+        detectionToMatchedTrackIDs: [Int: [Int]],
+        newObjectIDs: [Int],
+        emptyTrackIDs: [Int],
+        unmatchedTrackIDs: [Int],
+        parameters: VideoSegmentationParameters
+    ) -> Set<Int> {
+        var newlyRemoved: Set<Int> = []
+        var suppressed = session.suppressedObjectIDsByFrame[frameIndex] ?? []
+        // Everything before this frame is "outside the hotstart window".
+        let hotstartBoundary =
+            reverse ? frameIndex + parameters.hotstartDelay : frameIndex - parameters.hotstartDelay
+
+        // Step 1: record first sightings and seed keep-alive.
+        for id in newObjectIDs {
+            if session.firstFrameByObjectID[id] == nil {
+                session.firstFrameByObjectID[id] = frameIndex
+            }
+            session.keepAliveByObjectID[id] = parameters.initTrkKeepAlive
+        }
+
+        // A track counts as matched if any detection claimed it. Using the
+        // detection-to-track map avoids recomputing areas to distinguish "occluded" from
+        // "gone", which is the distinction `emptyTrackIDs` already carries.
+        var matched: Set<Int> = []
+        for tracks in detectionToMatchedTrackIDs.values { matched.formUnion(tracks) }
+        for id in matched {
+            let current = session.keepAliveByObjectID[id] ?? parameters.initTrkKeepAlive
+            session.keepAliveByObjectID[id] = min(parameters.maxTrkKeepAlive, current + 1)
+        }
+        for id in unmatchedTrackIDs {
+            session.unmatchedFramesByObjectID[id, default: []].append(frameIndex)
+            let current = session.keepAliveByObjectID[id] ?? parameters.initTrkKeepAlive
+            session.keepAliveByObjectID[id] = max(parameters.minTrkKeepAlive, current - 1)
+        }
+        if parameters.decreaseTrkKeepAliveForEmptyMasklets {
+            for id in emptyTrackIDs {
+                let current = session.keepAliveByObjectID[id] ?? parameters.initTrkKeepAlive
+                session.keepAliveByObjectID[id] = max(parameters.minTrkKeepAlive, current - 1)
+            }
+        }
+
+        // Step 2: drop tracks unmatched for too long inside the window, and suppress
+        // tracks whose keep-alive has run out.
+        //
+        // Sorted so removal is deterministic. Upstream iterates a `defaultdict`, whose
+        // order is insertion order and therefore also deterministic, but is not the same
+        // order; the two only differ when two objects would be removed on the same frame,
+        // and both are removed either way.
+        for id in session.unmatchedFramesByObjectID.keys.sorted() {
+            guard let frames = session.unmatchedFramesByObjectID[id] else { continue }
+            if session.removedObjectIDs.contains(id) || newlyRemoved.contains(id) { continue }
+            if frames.count >= parameters.hotstartUnmatchThresh {
+                let firstFrame = session.firstFrameByObjectID[id] ?? frameIndex
+                let withinHotstart =
+                    reverse ? firstFrame < hotstartBoundary : firstFrame > hotstartBoundary
+                if withinHotstart {
+                    newlyRemoved.insert(id)
+                    CLILogger.log(
+                        "Removing object \(id) at frame \(frameIndex): unmatched on frames \(frames)")
+                }
+            }
+            let keepAlive = session.keepAliveByObjectID[id] ?? parameters.initTrkKeepAlive
+            if keepAlive <= 0 && !parameters.suppressUnmatchedOnlyWithinHotstart
+                && !session.removedObjectIDs.contains(id) && !newlyRemoved.contains(id)
+            {
+                suppressed.insert(id)
+            }
+        }
+
+        // Step 3: record overlaps. Two tracks overlap when the same detection claims both;
+        // the later-appearing one is the candidate duplicate.
+        for tracks in detectionToMatchedTrackIDs.values.sorted(by: { ($0.first ?? -1) < ($1.first ?? -1) }) {
+            guard tracks.count >= 2 else { continue }
+            let firstAppearing =
+                reverse
+                ? tracks.max(by: { firstFrame(session, $0, frameIndex) < firstFrame(session, $1, frameIndex) })
+                : tracks.min(by: { firstFrame(session, $0, frameIndex) < firstFrame(session, $1, frameIndex) })
+            guard let anchor = firstAppearing else { continue }
+            for id in tracks where id != anchor {
+                let pair = VideoInferenceSession.OverlapPair(firstAppearing: anchor, duplicate: id)
+                session.overlapFramesByPair[pair, default: []].append(frameIndex)
+            }
+        }
+
+        // Step 4: drop duplicates that have overlapped for long enough, again only inside
+        // the hotstart window.
+        for pair in session.overlapFramesByPair.keys.sorted(by: {
+            ($0.firstAppearing, $0.duplicate) < ($1.firstAppearing, $1.duplicate)
+        }) {
+            guard let frames = session.overlapFramesByPair[pair] else { continue }
+            let id = pair.duplicate
+            if session.removedObjectIDs.contains(id) || newlyRemoved.contains(id) { continue }
+            let firstFrame = session.firstFrameByObjectID[id] ?? frameIndex
+            let withinHotstart =
+                reverse ? firstFrame < hotstartBoundary : firstFrame > hotstartBoundary
+            guard withinHotstart, frames.count >= parameters.hotstartDupThresh else { continue }
+            newlyRemoved.insert(id)
+            CLILogger.log(
+                "Removing object \(id) at frame \(frameIndex): overlaps object "
+                    + "\(pair.firstAppearing) on frames \(frames)")
+        }
+
+        session.removedObjectIDs.formUnion(newlyRemoved)
+        session.suppressedObjectIDsByFrame[frameIndex] = suppressed
+        return newlyRemoved
+    }
+
+    /// First frame an object was seen on. Upstream's `obj_first_frame_idx[x]` would raise for
+    /// an object with no record; this defaults to the current frame instead of failing the
+    /// video.
+    private static func firstFrame(
+        _ session: VideoInferenceSession, _ id: Int, _ frameIndex: Int
+    ) -> Int {
+        session.firstFrameByObjectID[id] ?? frameIndex
+    }
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/Tracking/OcclusionSuppressor.swift b/swift/Sources/CoreAIVideoSegmenter/Tracking/OcclusionSuppressor.swift
new file mode 100644
index 00000000..4f418855
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/Tracking/OcclusionSuppressor.swift
@@ -0,0 +1,222 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreAIShared
+import Foundation
+
+/// Resolves objects that claim the same pixels.
+///
+/// Three related rules, all ported from `Sam3VideoModel`, applied at different points and
+/// on different data:
+///
+/// 1. ``suppressRecentlyOccluded``, before memory encoding, on tracker logits. When two
+///    objects overlap heavily, the one that was occluded more recently is assumed to be
+///    the drifting copy and is blanked.
+/// 2. ``suppressAreaShrinkage``, also before memory encoding. Applies a pixel-level argmax
+///    and then drops any object that lost most of its area to it, on the reasoning that
+///    such an object was never really there.
+/// 3. ``applyObjectWiseNonOverlap``, at output time, on binary masks and per-object scores
+///    rather than logits.
+///
+/// All three are enforced per prompt group: two prompts may legitimately return overlapping
+/// masks for the same pixels, and forcing them to compete would make "person" and "pillow"
+/// delete each other.
+enum OcclusionSuppressor {
+    /// Logit written over a suppressed mask. `sigmoid(-10)` is 4.5e-5, so it reads as
+    /// background everywhere downstream without being an out-of-range sentinel.
+    static let noObjectLogit: Float = -10
+
+    /// Fraction of its own area an object must retain through the pixel-level argmax.
+    static let shrinkThreshold: Float = 0.3
+
+    /// Frame index standing in for "never occluded". Must stay negative: the rule below
+    /// requires the *other* object to have been occluded at some point, tested as `> -1`.
+    static let neverOccluded = -1
+
+    /// Frame index standing in for "removed by hotstart, always loses". Larger than any
+    /// real frame index.
+    static let alwaysOccluded = 100_000
+
+    // MARK: - 1. Recent-occlusion suppression
+
+    /// Blank objects that overlap an object occluded less recently than they were.
+    ///
+    /// Port of `_suppress_overlapping_based_on_recent_occlusion`. Also updates each
+    /// object's last-occluded frame, which is the state the next frame's comparison reads:
+    /// an object counts as occluded this frame if its mask is empty *or* it was suppressed
+    /// here.
+    ///
+    /// - Parameters:
+    ///   - logits: Tracker mask logits per object, mutated in place.
+    ///   - masks: The same masks binarized, parallel to `logits`.
+    ///   - objectIDs: Registry order, parallel to both.
+    @VideoSegmentationActor
+    static func suppressRecentlyOccluded(
+        logits: inout [[Float]],
+        masks: [MaskBitset],
+        objectIDs: [Int],
+        promptIDs: [Int],
+        newlyRemovedObjectIDs: Set<Int>,
+        frameIndex: Int,
+        reverse: Bool,
+        session: VideoInferenceSession,
+        parameters: VideoSegmentationParameters
+    ) {
+        guard !objectIDs.isEmpty else { return }
+
+        let lastOccluded = objectIDs.map { id in
+            session.lastOccludedByObjectID[id]
+                ?? (newlyRemovedObjectIDs.contains(id) ? alwaysOccluded : neverOccluded)
+        }
+
+        var suppress = [Bool](repeating: false, count: objectIDs.count)
+        for group in Set(promptIDs).sorted() {
+            let members = promptIDs.indices.filter { promptIDs[$0] == group }
+            guard members.count > 1 else { continue }
+            markSuppressed(
+                members: members, masks: masks, lastOccluded: lastOccluded,
+                threshold: parameters.suppressOverlappingOcclusionThreshold,
+                reverse: reverse, into: &suppress)
+        }
+
+        var updated = lastOccluded
+        for index in objectIDs.indices where masks[index].isEmpty || suppress[index] {
+            updated[index] = frameIndex
+        }
+        for (index, id) in objectIDs.enumerated() {
+            session.lastOccludedByObjectID[id] = updated[index]
+        }
+
+        for index in objectIDs.indices where suppress[index] {
+            for pixel in logits[index].indices { logits[index][pixel] = noObjectLogit }
+        }
+    }
+
+    /// The pairwise rule itself, over one prompt group.
+    ///
+    /// For every pair `i < j` overlapping above `threshold`, the one occluded more recently
+    /// loses, but only if the winner was itself occluded at some point (`> neverOccluded`).
+    /// Two objects that have both always been visible simply coexist.
+    private static func markSuppressed(
+        members: [Int],
+        masks: [MaskBitset],
+        lastOccluded: [Int],
+        threshold: Float,
+        reverse: Bool,
+        into suppress: inout [Bool]
+    ) {
+        // Tracking backwards inverts the comparison: "more recent" is a lower frame index.
+        func losesTo(_ a: Int, _ b: Int) -> Bool { reverse ? a < b : a > b }
+
+        for outer in 0..<members.count {
+            for inner in (outer + 1)..<members.count {
+                let i = members[outer]
+                let j = members[inner]
+                guard masks[i].iou(masks[j]) >= threshold else { continue }
+                if losesTo(lastOccluded[i], lastOccluded[j]), lastOccluded[j] > neverOccluded {
+                    suppress[i] = true
+                }
+                if losesTo(lastOccluded[j], lastOccluded[i]), lastOccluded[i] > neverOccluded {
+                    suppress[j] = true
+                }
+            }
+        }
+    }
+
+    // MARK: - 2. Area-shrinkage suppression
+
+    /// Drop objects that lose most of their area to the pixel-level argmax.
+    ///
+    /// Port of `_suppress_object_pw_area_shrinkage`, run per prompt group. Returns the
+    /// original masks with whole objects blanked, not the de-overlapped masks; the argmax only
+    /// measures how much of each object was contested.
+    static func suppressAreaShrinkage(
+        logits: inout [[Float]], promptIDs: [Int]
+    ) {
+        guard logits.count > 1 else { return }
+        for group in Set(promptIDs).sorted() {
+            let members = promptIDs.indices.filter { promptIDs[$0] == group }
+            guard members.count > 1 else { continue }
+
+            let pixelCount = logits[members[0]].count
+            // Winner per pixel, by raw logit. Ties go to the lowest index in the group,
+            // matching `torch.argmax`.
+            var winner = [Int](repeating: members[0], count: pixelCount)
+            var best = [Float](repeating: -.greatestFiniteMagnitude, count: pixelCount)
+            for member in members {
+                let values = logits[member]
+                for pixel in 0..<pixelCount where values[pixel] > best[pixel] {
+                    best[pixel] = values[pixel]
+                    winner[pixel] = member
+                }
+            }
+
+            var blank: [Int] = []
+            for member in members {
+                let values = logits[member]
+                var areaBefore = 0
+                var areaAfter = 0
+                for pixel in 0..<pixelCount where values[pixel] > 0 {
+                    areaBefore += 1
+                    if winner[pixel] == member { areaAfter += 1 }
+                }
+                let ratio = Float(areaAfter) / Float(max(areaBefore, 1))
+                if ratio < shrinkThreshold { blank.append(member) }
+            }
+            for member in blank {
+                for pixel in logits[member].indices {
+                    logits[member][pixel] = min(logits[member][pixel], noObjectLogit)
+                }
+            }
+        }
+    }
+
+    // MARK: - 3. Output-time non-overlap
+
+    /// Give each contested pixel to the highest-scoring object in its prompt group.
+    ///
+    /// Port of `Sam3VideoProcessor._apply_object_wise_non_overlapping_constraints` with
+    /// `background_value = 0`. The scores here are per-object, not per-pixel, so the
+    /// winner of a contested region is the same everywhere the two overlap.
+    ///
+    /// Upstream compares `pixel_nonoverlap > 0`, so an object whose score is exactly zero
+    /// loses every pixel, even uncontested ones. Reproduced by the `bestScore[pixel] > 0` test.
+    static func applyObjectWiseNonOverlap(
+        masks: inout [MaskBitset], scores: [Float], promptIDs: [Int]
+    ) {
+        guard masks.count > 1 else { return }
+        for group in Set(promptIDs).sorted() {
+            let members = promptIDs.indices.filter { promptIDs[$0] == group }
+            guard members.count > 1 else { continue }
+
+            let pixelCount = masks[members[0]].width * masks[members[0]].height
+            var bestScore = [Float](repeating: 0, count: pixelCount)
+            var winner = [Int32](repeating: -1, count: pixelCount)
+            // Strict `>` so ties keep the lowest group index, matching `torch.argmax`.
+            for member in members {
+                let score = scores[member]
+                masks[member].forEachSetIndex { pixel in
+                    if winner[pixel] == -1 || score > bestScore[pixel] {
+                        bestScore[pixel] = score
+                        winner[pixel] = Int32(member)
+                    }
+                }
+            }
+            for member in members {
+                var losses: [Int] = []
+                masks[member].forEachSetIndex { pixel in
+                    if winner[pixel] != Int32(member) || bestScore[pixel] <= 0 {
+                        losses.append(pixel)
+                    }
+                }
+                guard !losses.isEmpty else { continue }
+                let width = masks[member].width
+                for pixel in losses {
+                    masks[member][pixel % width, pixel / width] = false
+                }
+            }
+        }
+    }
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/Tracking/TrackerLoop.swift b/swift/Sources/CoreAIVideoSegmenter/Tracking/TrackerLoop.swift
new file mode 100644
index 00000000..e1528c09
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/Tracking/TrackerLoop.swift
@@ -0,0 +1,355 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreAI
+import CoreAIShared
+import Foundation
+
+/// Runs the tracker over every object on one frame, and encodes the resulting memories.
+///
+/// Port of `Sam3TrackerVideoModel.forward`, `_run_single_frame_inference`,
+/// `_use_mask_as_output`, and `_batch_encode_memories`.
+///
+/// Point prompts are not implemented: SAM 3's video path only ever seeds a track from a
+/// detection mask, in `_tracker_add_new_objects`.
+@VideoSegmentationActor
+final class TrackerLoop {
+    private let engine: VideoSegmentationEngine
+    private let shapes: VideoSegmentationEngine.Shapes
+    private let parameters: VideoSegmentationParameters
+    private let packer: MemoryBankPacker
+
+    /// Resamplers are built once: their weight tables depend only on the sizes, and the
+    /// same four resizes repeat for every object on every frame.
+    private let lowResToImage: BilinearResampler
+    private let imageToLowRes: BilinearResampler
+    private let highResToMemory: BilinearResampler
+    private let lowResToMemory: BilinearResampler
+
+    /// Scale and bias `_use_mask_as_output` applies to turn a binary mask into logits.
+    private static let maskOutScale: Float = 20
+    private static let maskOutBias: Float = -10
+
+    init(
+        engine: VideoSegmentationEngine,
+        shapes: VideoSegmentationEngine.Shapes,
+        parameters: VideoSegmentationParameters,
+        packer: MemoryBankPacker
+    ) {
+        self.engine = engine
+        self.shapes = shapes
+        self.parameters = parameters
+        self.packer = packer
+        self.lowResToImage = BilinearResampler(
+            sourceWidth: shapes.lowResMaskSize, sourceHeight: shapes.lowResMaskSize,
+            destinationWidth: shapes.highResMaskSize, destinationHeight: shapes.highResMaskSize,
+            antialias: true)
+        self.imageToLowRes = BilinearResampler(
+            sourceWidth: shapes.highResMaskSize, sourceHeight: shapes.highResMaskSize,
+            destinationWidth: shapes.lowResMaskSize, destinationHeight: shapes.lowResMaskSize,
+            antialias: true)
+        self.highResToMemory = BilinearResampler(
+            sourceWidth: shapes.highResMaskSize, sourceHeight: shapes.highResMaskSize,
+            destinationWidth: shapes.memoryMaskSize, destinationHeight: shapes.memoryMaskSize,
+            antialias: true)
+        self.lowResToMemory = BilinearResampler(
+            sourceWidth: shapes.lowResMaskSize, sourceHeight: shapes.lowResMaskSize,
+            destinationWidth: shapes.memoryMaskSize, destinationHeight: shapes.memoryMaskSize,
+            antialias: true)
+    }
+
+    struct Propagation {
+        /// Low-resolution mask logits per object, in registry order.
+        var maskLogits: [[Float]] = []
+        /// Object score logits per object, in registry order.
+        var objectScoreLogits: [Float] = []
+    }
+
+    /// One object's fresh result, before it is stored.
+    private struct SingleFrameResult {
+        var predictedMasks: [Float]
+        var highResolutionMasks: [Float]
+        var objectPointer: NDArray
+        var objectScoreLogit: Float
+    }
+
+    /// The weight-free part of `_use_mask_as_output`, which has no object pointer of its own;
+    /// that comes from `tracker_mask_init`.
+    private struct MaskAsOutput {
+        var predictedMasks: [Float]
+        var highResolutionMasks: [Float]
+        var objectScoreLogit: Float
+    }
+
+    /// Propagate every registered object through `frameIndex`.
+    ///
+    /// - Parameter runMemoryEncoder: Encode this frame's memory as part of the pass. False
+    ///   on the plain propagation call, where memory is deferred until the planning phase
+    ///   has resolved non-overlap; true when a new object was just seeded.
+    func propagate(
+        session: VideoInferenceSession,
+        frameIndex: Int,
+        totalFrames: Int,
+        reverse: Bool,
+        runMemoryEncoder: Bool
+    ) async throws -> Propagation {
+        // Upstream mutates its `reverse` argument inside the object loop and the change
+        // leaks into every later object in the same call. Reproduced deliberately: a
+        // freshly seeded object forces forward tracking, and that then applies to the
+        // objects after it.
+        var reverse = reverse
+
+        var propagation = Propagation(
+            maskLogits: Array(repeating: [], count: session.objectCount),
+            objectScoreLogits: Array(repeating: 0, count: session.objectCount))
+
+        var memoryIndices: [Int] = []
+        var memoryMasks: [[Float]] = []
+        var memoryScores: [Float] = []
+        var memoryFromMask: [Bool] = []
+
+        for objectIndex in 0..<session.objectCount {
+            let objectID = session.registry.id(at: objectIndex)
+            let hasNewInputs = session.objectsWithNewInputs.contains(objectID)
+            let hasConditioningOutput =
+                session.histories[objectIndex].conditioning[frameIndex] != nil
+
+            if !hasNewInputs, hasConditioningOutput,
+                let stored = session.histories[objectIndex].conditioning[frameIndex]
+            {
+                // Already computed on this frame as a conditioning output, so reuse it
+                // rather than re-running the tracker.
+                guard let masks = stored.predictedMasks else {
+                    throw VideoSegmentationError.invalidConfiguration(
+                        "Object \(objectID) has a conditioning output on frame \(frameIndex) with "
+                            + "no stored mask. Pruning ran on the frame still being processed.")
+                }
+                propagation.maskLogits[objectIndex] = masks
+                propagation.objectScoreLogits[objectIndex] = stored.objectScoreLogit
+                continue
+            }
+
+            var isInitialConditioningFrame = false
+            var maskPrompt: MaskPrompt?
+            if hasNewInputs {
+                isInitialConditioningFrame =
+                    session.histories[objectIndex].framesTracked[frameIndex] == nil
+                if isInitialConditioningFrame { reverse = false }
+                maskPrompt = session.histories[objectIndex].maskInputs[frameIndex]
+                if maskPrompt != nil {
+                    session.objectsWithNewInputs.removeAll { $0 == objectID }
+                }
+            }
+
+            let result = try await runSingleFrame(
+                session: session, frameIndex: frameIndex, objectIndex: objectIndex,
+                totalFrames: totalFrames, maskPrompt: maskPrompt, reverse: reverse)
+
+            session.histories[objectIndex].store(
+                StoredFrameOutput(
+                    predictedMasks: result.predictedMasks,
+                    objectPointer: result.objectPointer,
+                    objectScoreLogit: result.objectScoreLogit),
+                at: frameIndex,
+                conditioning: isInitialConditioningFrame)
+
+            propagation.maskLogits[objectIndex] = result.predictedMasks
+            propagation.objectScoreLogits[objectIndex] = result.objectScoreLogit
+
+            if runMemoryEncoder, parameters.numMaskmem > 0 {
+                memoryIndices.append(objectIndex)
+                memoryMasks.append(result.highResolutionMasks)
+                memoryScores.append(result.objectScoreLogit)
+                memoryFromMask.append(maskPrompt != nil)
+            }
+
+            if !isInitialConditioningFrame {
+                session.histories[objectIndex].framesTracked[frameIndex] = reverse
+            }
+        }
+
+        try await encodeMemories(
+            session: session, frameIndex: frameIndex, objectIndices: memoryIndices,
+            highResolutionMasks: memoryMasks, scoreLogits: memoryScores,
+            fromMask: memoryFromMask, alreadyAtMemoryResolution: false)
+
+        return propagation
+    }
+
+    /// Encode memory for every object from the frame's final, de-overlapped masks.
+    ///
+    /// Port of `_tracker_update_memories`'s second half. Distinct from the pass inside
+    /// ``propagate`` in three ways: the masks are low-resolution rather than
+    /// image-resolution, the score is derived from mask area rather than from the decoder,
+    /// and binarization is always off.
+    func encodeFinalMemories(
+        session: VideoInferenceSession,
+        frameIndex: Int,
+        maskLogits: [[Float]]
+    ) async throws {
+        guard !maskLogits.isEmpty else { return }
+        // Mask area stands in for an object score, exactly as upstream:
+        // `torch.where((high_res_masks > 0).any(...), 10.0, -10.0)`.
+        let scores = maskLogits.map { logits in
+            logits.contains { $0 > 0 } ? -Self.maskOutBias : Self.maskOutBias
+        }
+        try await encodeMemories(
+            session: session, frameIndex: frameIndex,
+            objectIndices: Array(maskLogits.indices),
+            highResolutionMasks: maskLogits, scoreLogits: scores,
+            fromMask: [Bool](repeating: false, count: maskLogits.count),
+            alreadyAtMemoryResolution: false, sourceIsLowResolution: true)
+    }
+
+    /// Seed tracks from detection masks, then re-run the tracker with memory encoding on.
+    ///
+    /// Port of `_tracker_add_new_objects`. Two things here are upstream's and expensive: the
+    /// binarization is `>= 0.5` on raw mask logits rather than on probabilities, and the re-run
+    /// covers every object, not just the new ones, which also overwrites the memory the
+    /// planning phase just wrote, now conditioned on this frame.
+    func addNewObjects(
+        session: VideoInferenceSession,
+        frameIndex: Int,
+        totalFrames: Int,
+        newObjectIDs: [Int],
+        newObjectMaskLogits: [[Float]],
+        reverse: Bool
+    ) async throws {
+        for (objectID, logits) in zip(newObjectIDs, newObjectMaskLogits) {
+            let objectIndex = session.index(ofObject: objectID)
+            // `>= 0.5` on raw mask logits. `nextDown` turns the bitset's strict `>` into
+            // exactly that, with no float slop.
+            let mask = MaskBitset(
+                thresholding: logits, width: shapes.lowResMaskSize,
+                height: shapes.lowResMaskSize, above: Float(0.5).nextDown)
+            session.histories[objectIndex].maskInputs[frameIndex] = MaskPrompt(mask: mask)
+        }
+        session.objectsWithNewInputs = newObjectIDs
+
+        _ = try await propagate(
+            session: session, frameIndex: frameIndex, totalFrames: totalFrames,
+            reverse: reverse, runMemoryEncoder: true)
+    }
+
+    // MARK: - One object, one frame
+
+    private var lowResPixels: Int { shapes.lowResMaskSize * shapes.lowResMaskSize }
+    private var highResPixels: Int { shapes.highResMaskSize * shapes.highResMaskSize }
+
+    private func runSingleFrame(
+        session: VideoInferenceSession,
+        frameIndex: Int,
+        objectIndex: Int,
+        totalFrames: Int,
+        maskPrompt: MaskPrompt?,
+        reverse: Bool
+    ) async throws -> SingleFrameResult {
+        let features = try session.features(forFrame: frameIndex)
+
+        if let maskPrompt {
+            // Seeding path: only the object pointer needs the network, and everything else
+            // in `_use_mask_as_output` is weight-free arithmetic on the prompt mask.
+            let maskFloats = maskPrompt.mask.toBytes().map { Float($0) }
+            let pointer = try await engine.trackerMaskInit(
+                features: features, maskInput: maskFloats)
+            let derived = maskAsOutput(maskPrompt.mask, maskFloats: maskFloats)
+            // Consumed; drop it so a long video doesn't accumulate one prompt per seeding.
+            session.histories[objectIndex].maskInputs[frameIndex] = nil
+            return SingleFrameResult(
+                predictedMasks: derived.predictedMasks,
+                highResolutionMasks: derived.highResolutionMasks,
+                objectPointer: pointer,
+                objectScoreLogit: derived.objectScoreLogit)
+        }
+
+        let memory = try packer.pack(
+            history: session.histories[objectIndex], objectIndex: objectIndex,
+            frameIndex: frameIndex, totalFrames: totalFrames, reverse: reverse)
+        let outputs = try await engine.trackerStep(features: features, memory: memory)
+        return SingleFrameResult(
+            predictedMasks: floatElements(outputs.predictedMasks, in: 0..<lowResPixels),
+            highResolutionMasks: floatElements(outputs.highResolutionMasks, in: 0..<highResPixels),
+            objectPointer: outputs.objectPointer,
+            objectScoreLogit: flattenAsFloat(outputs.objectScoreLogits).first ?? Self.maskOutBias)
+    }
+
+    /// The weight-free half of `_use_mask_as_output`.
+    ///
+    /// The low-resolution output is computed for completeness but is effectively write-only
+    /// during forward propagation: `build_outputs` shows a new object its detection mask, and
+    /// the stored value is only re-read if the same frame is revisited. The image-resolution
+    /// mask and the score are what the memory encoder consumes.
+    private func maskAsOutput(_ mask: MaskBitset, maskFloats: [Float]) -> MaskAsOutput {
+        let upscaled = lowResToImage.resample(maskFloats)
+        var highResolution = [Float](repeating: 0, count: upscaled.count)
+        for index in upscaled.indices {
+            highResolution[index] = upscaled[index] * Self.maskOutScale + Self.maskOutBias
+        }
+        let lowResolution = imageToLowRes.resample(highResolution)
+        // `is_obj_appearing` tests the *prompt* mask, not the resampled one.
+        let appearing = !mask.isEmpty
+        return MaskAsOutput(
+            predictedMasks: lowResolution,
+            highResolutionMasks: highResolution,
+            objectScoreLogit: appearing ? -Self.maskOutBias : Self.maskOutBias)
+    }
+
+    // MARK: - Memory encoding
+
+    /// Encode one memory per object and attach it to that object's stored frame output.
+    ///
+    /// `binarize` is `any(fromMask)` across the batch, not per object: upstream computes
+    /// `is_mask_from_pts` once for the whole batch, so a single newly seeded object turns
+    /// binarization on for every object encoded on that frame. That coupling changes the
+    /// numbers, so it is preserved.
+    private func encodeMemories(
+        session: VideoInferenceSession,
+        frameIndex: Int,
+        objectIndices: [Int],
+        highResolutionMasks: [[Float]],
+        scoreLogits: [Float],
+        fromMask: [Bool],
+        alreadyAtMemoryResolution: Bool,
+        sourceIsLowResolution: Bool = false
+    ) async throws {
+        guard !objectIndices.isEmpty else { return }
+        let features = try session.features(forFrame: frameIndex)
+        let binarize = fromMask.contains(true)
+        let resampler = sourceIsLowResolution ? lowResToMemory : highResToMemory
+
+        for (position, objectIndex) in objectIndices.enumerated() {
+            // Upstream resizes inside `_encode_new_memory`, which is handed two different
+            // resolutions depending on the caller. A traced graph takes one, so the host
+            // normalizes to `memoryMaskSize` first. Both callers resize *up*, where
+            // antialiasing is a no-op, so this stays a single plain bilinear pass.
+            let mask =
+                alreadyAtMemoryResolution
+                ? highResolutionMasks[position]
+                : resampler.resample(highResolutionMasks[position])
+
+            let encoded = try await engine.memoryEncode(
+                visionFeatureLevel2: features.level2,
+                maskLogits: mask,
+                objectScoreLogit: scoreLogits[position],
+                binarize: binarize)
+
+            // Attach to whichever bucket holds this frame. A reconditioned object was
+            // promoted to conditioning a moment ago, so this cannot assume either.
+            let memoryFeatures = MemoryPayload(reading: encoded.features)
+            let positionEncoding = MemoryPayload(reading: encoded.positionEncoding)
+            if session.histories[objectIndex].conditioning[frameIndex] != nil {
+                session.histories[objectIndex].conditioning[frameIndex]?.memoryFeatures =
+                    memoryFeatures
+                session.histories[objectIndex].conditioning[frameIndex]?.memoryPositionEncoding =
+                    positionEncoding
+            } else if session.histories[objectIndex].nonConditioning[frameIndex] != nil {
+                session.histories[objectIndex].nonConditioning[frameIndex]?.memoryFeatures =
+                    memoryFeatures
+                session.histories[objectIndex].nonConditioning[frameIndex]?
+                    .memoryPositionEncoding = positionEncoding
+            }
+        }
+    }
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationActor.swift b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationActor.swift
new file mode 100644
index 00000000..0971dc29
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationActor.swift
@@ -0,0 +1,20 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import Foundation
+
+/// Isolation domain for the video segmentation frame loop.
+///
+/// The loop is inherently sequential: frame N's tracker reads the memory frame N-1 wrote, and
+/// every stage shares one mutable `VideoInferenceSession`. Giving each component its own actor
+/// would mean passing that session across isolation boundaries it cannot safely cross, so they
+/// all share this one.
+///
+/// ``VideoSegmentationEngine`` is deliberately not on this actor: it owns no per-frame state,
+/// so a caller can unload the asset without serializing against a running frame loop.
+@globalActor
+public actor VideoSegmentationActor {
+    public static let shared = VideoSegmentationActor()
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationEngine.swift b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationEngine.swift
new file mode 100644
index 00000000..0be7b755
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationEngine.swift
@@ -0,0 +1,494 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreAI
+import CoreAIShared
+import Foundation
+
+/// The seven Core AI entrypoints of a SAM 3 video asset, behind typed calls.
+///
+/// Everything above this type is host logic: the inference session, the memory ring
+/// buffer, and the tracking heuristics. This is the only place that touches `AIModel`.
+///
+/// Two deliberate choices in the signatures below:
+///
+/// * Tensors that go straight from one graph to the next stay as `NDArray` handles rather
+///   than being flattened to `[Float]`. `vision_feat_0` alone is 2.6 M elements and is fed
+///   to `tracker_step` once per tracked object per frame, so a host round-trip would be
+///   repeated for every object.
+/// * `tracker_encode` also emits `vision_pos_0` and `vision_pos_1`, which no other
+///   entrypoint consumes. They are left unread.
+public actor VideoSegmentationEngine: ResourceManaging {
+    /// Entrypoint names, in the order the exporter declares them.
+    public enum Function {
+        public static let imageEncode = "image_encode"
+        public static let textEncode = "text_encode"
+        public static let detect = "detect"
+        public static let trackerEncode = "tracker_encode"
+        public static let trackerStep = "tracker_step"
+        public static let memoryEncode = "memory_encode"
+        public static let trackerMaskInit = "tracker_mask_init"
+
+        static let all = [
+            imageEncode, textEncode, detect, trackerEncode, trackerStep, memoryEncode,
+            trackerMaskInit,
+        ]
+    }
+
+    private let modelURL: URL
+    private var loaded: Loaded?
+
+    private struct Loaded {
+        let model: AIModel
+        let functions: [String: InferenceFunction]
+        let descriptors: [String: InferenceFunctionDescriptor]
+    }
+
+    /// Shapes read off the asset at load time, so the host packs to what was traced
+    /// rather than to what it assumes.
+    public struct Shapes: Sendable, Equatable {
+        /// Square input resolution of `image_encode`.
+        public let imageSize: Int
+        /// Text token count `text_encode` was traced at.
+        public let textSequenceLength: Int
+        /// Detector query count.
+        public let queryCount: Int
+        /// Side of the detector's and tracker's low-resolution masks.
+        public let lowResMaskSize: Int
+        /// Side of the `memory_encode` mask input.
+        public let memoryMaskSize: Int
+        /// Side of `tracker_step`'s high-resolution mask output.
+        public let highResMaskSize: Int
+        /// Flattened spatial extent of the deepest feature level (`H * W`).
+        public let memoryTokenCount: Int
+        /// Channel width of a spatial memory slot.
+        public let memoryDim: Int
+        /// Tracker hidden width, and the width of an object pointer.
+        public let hiddenDim: Int
+        /// Spatial memory slots per object.
+        public let spatialSlots: Int
+        /// Object-pointer slots per object.
+        public let ptrSlots: Int
+    }
+
+    public private(set) var shapes: Shapes?
+
+    public init(modelURL: URL) {
+        self.modelURL = modelURL
+    }
+
+    /// Load and specialize the asset, then resolve its shapes.
+    ///
+    /// A static multi-function asset commits workspace for every declared function on the
+    /// first `loadFunction`, so all seven are resolved here rather than on demand; deferring
+    /// them would cost the same memory and add a first-use stall.
+    public func loadResources() async throws {
+        guard loaded == nil else { return }
+        let prepared = try await PreparedModel.prepare(at: modelURL)
+        guard prepared.structure == .videoSegmenter else {
+            throw VideoSegmentationError.invalidConfiguration(
+                "\(modelURL.lastPathComponent) classified as \(prepared.structure), not a video "
+                    + "segmenter. Its functions are: \(prepared.model.functionNames.sorted()).")
+        }
+
+        var functions: [String: InferenceFunction] = [:]
+        var descriptors: [String: InferenceFunctionDescriptor] = [:]
+        for name in Function.all {
+            guard let descriptor = prepared.model.functionDescriptor(for: name),
+                let function = try prepared.model.loadFunction(named: name)
+            else {
+                throw VideoSegmentationError.missingFunction(
+                    name: name, available: prepared.model.functionNames)
+            }
+            functions[name] = function
+            descriptors[name] = descriptor
+        }
+        self.loaded = Loaded(
+            model: prepared.model, functions: functions, descriptors: descriptors)
+        self.shapes = try Self.resolveShapes(descriptors)
+    }
+
+    public func unloadResources() async {
+        loaded = nil
+        shapes = nil
+    }
+
+    /// Run every entrypoint once on zeros so the first real frame isn't paying for
+    /// kernel compilation.
+    public func warmup() async throws {
+        let state = try require()
+        for name in Function.all {
+            var inputs: [String: NDArray] = [:]
+            for input in state.descriptors[name]!.inputNames {
+                inputs[input] = NDArray(descriptor: try arrayDescriptor(name, input: input))
+            }
+            _ = try await invoke(name, inputs)
+        }
+    }
+
+    // MARK: - Entrypoints
+
+    /// ViT backbone. `pixelValues` is planar CHW at `shapes.imageSize`, already normalized.
+    public func imageEncode(pixelValues: [Float]) async throws -> NDArray {
+        var array = NDArray(descriptor: try arrayDescriptor(Function.imageEncode, input: "pixel_values"))
+        fillFloatNDArray(&array, with: pixelValues)
+        let outputs = try await invoke(Function.imageEncode, ["pixel_values": array])
+        return try output(outputs, "last_hidden_state", from: Function.imageEncode)
+    }
+
+    /// CLIP text tower. Run once per distinct prompt for the whole video.
+    ///
+    /// Returns the attention mask alongside the features because `detect` needs the same
+    /// mask on every frame, so there is no point rebuilding it per frame per prompt.
+    public func textEncode(
+        inputIDs: [Int32], attentionMask: [Int32]
+    ) async throws -> PromptEncoding {
+        var ids = NDArray(descriptor: try arrayDescriptor(Function.textEncode, input: "input_ids"))
+        fillNDArray(&ids, as: Int32.self, with: inputIDs)
+        var mask = NDArray(
+            descriptor: try arrayDescriptor(Function.textEncode, input: "attention_mask"))
+        fillNDArray(&mask, as: Int32.self, with: attentionMask)
+
+        let outputs = try await invoke(
+            Function.textEncode, ["input_ids": ids, "attention_mask": mask])
+        return PromptEncoding(
+            textFeatures: try output(outputs, "text_features", from: Function.textEncode),
+            attentionMask: mask)
+    }
+
+    /// FPN + DETR + mask decoder, for one prompt.
+    public func detect(
+        lastHiddenState: NDArray, prompt: PromptEncoding
+    ) async throws -> DetectOutputs {
+        let outputs = try await invoke(
+            Function.detect,
+            [
+                "last_hidden_state": lastHiddenState,
+                "text_features": prompt.textFeatures,
+                "attention_mask": prompt.attentionMask,
+            ])
+        return DetectOutputs(
+            predictedMasks: try output(outputs, "pred_masks", from: Function.detect),
+            predictedBoxes: try output(outputs, "pred_boxes", from: Function.detect),
+            predictedLogits: try output(outputs, "pred_logits", from: Function.detect),
+            presenceLogits: try output(outputs, "presence_logits", from: Function.detect))
+    }
+
+    /// Tracker FPN neck plus the two pre-projected decoder levels.
+    public func trackerEncode(lastHiddenState: NDArray) async throws -> TrackerFeatures {
+        let outputs = try await invoke(
+            Function.trackerEncode, ["last_hidden_state": lastHiddenState])
+        return TrackerFeatures(
+            level0: try output(outputs, "vision_feat_0", from: Function.trackerEncode),
+            level1: try output(outputs, "vision_feat_1", from: Function.trackerEncode),
+            level2: try output(outputs, "vision_feat_2", from: Function.trackerEncode),
+            positionLevel2: try output(outputs, "vision_pos_2", from: Function.trackerEncode))
+    }
+
+    /// Memory attention plus the SAM mask decoder, for one object on one frame.
+    ///
+    /// Internal because `PackedMemory` is: the memory bank's layout is a consequence of
+    /// how this asset was traced, not something a caller should be assembling.
+    func trackerStep(
+        features: TrackerFeatures, memory: PackedMemory
+    ) async throws -> TrackerStepOutputs {
+        let outputs = try await invoke(
+            Function.trackerStep,
+            [
+                "vision_feat_0": features.level0,
+                "vision_feat_1": features.level1,
+                "vision_feat_2": features.level2,
+                "vision_pos_2": features.positionLevel2,
+                "spatial_memory": memory.spatialMemory,
+                "spatial_memory_pos": memory.spatialMemoryPosition,
+                "spatial_tpos_idx": memory.spatialTemporalIndex,
+                "spatial_valid": memory.spatialValid,
+                "object_pointers": memory.objectPointers,
+                "ptr_tpos": memory.pointerTemporalPosition,
+                "ptr_valid": memory.pointerValid,
+            ])
+        return TrackerStepOutputs(
+            predictedMasks: try output(outputs, "pred_masks", from: Function.trackerStep),
+            highResolutionMasks: try output(outputs, "high_res_masks", from: Function.trackerStep),
+            objectPointer: try output(outputs, "object_pointer", from: Function.trackerStep),
+            objectScoreLogits: try output(
+                outputs, "object_score_logits", from: Function.trackerStep))
+    }
+
+    /// Encode one predicted mask into a spatial memory slot.
+    ///
+    /// `maskLogits` must already be at `shapes.memoryMaskSize`. Upstream `_encode_new_memory`
+    /// resizes whatever it is handed, and it is handed two different resolutions depending
+    /// on the caller; a traced graph accepts one, so normalizing is the host's job.
+    ///
+    /// `binarize` reproduces `is_mask_from_pts`, which upstream computes as `any(...)` over
+    /// the batch, so one newly seeded object turns it on for every object encoded on that
+    /// frame.
+    public func memoryEncode(
+        visionFeatureLevel2: NDArray,
+        maskLogits: [Float],
+        objectScoreLogit: Float,
+        binarize: Bool
+    ) async throws -> EncodedMemory {
+        var mask = NDArray(descriptor: try arrayDescriptor(Function.memoryEncode, input: "mask_logits"))
+        fillFloatNDArray(&mask, with: maskLogits)
+        var score = NDArray(
+            descriptor: try arrayDescriptor(Function.memoryEncode, input: "object_score_logits"))
+        fillFloatNDArray(&score, with: [objectScoreLogit])
+        var flag = NDArray(
+            descriptor: try arrayDescriptor(Function.memoryEncode, input: "binarize_mask"))
+        fillFloatNDArray(&flag, with: [binarize ? 1 : 0])
+
+        let outputs = try await invoke(
+            Function.memoryEncode,
+            [
+                "vision_feat_2": visionFeatureLevel2,
+                "mask_logits": mask,
+                "object_score_logits": score,
+                "binarize_mask": flag,
+            ])
+        return EncodedMemory(
+            features: try output(outputs, "maskmem_features", from: Function.memoryEncode),
+            positionEncoding: try output(outputs, "maskmem_pos_enc", from: Function.memoryEncode))
+    }
+
+    /// Seed a track from a detection mask, producing only its object pointer.
+    ///
+    /// The rest of `_use_mask_as_output` is weight-free and stays on the host; see
+    /// `TrackerLoop.maskAsOutput`.
+    public func trackerMaskInit(
+        features: TrackerFeatures, maskInput: [Float]
+    ) async throws -> NDArray {
+        var mask = NDArray(
+            descriptor: try arrayDescriptor(Function.trackerMaskInit, input: "mask_input"))
+        fillFloatNDArray(&mask, with: maskInput)
+        let outputs = try await invoke(
+            Function.trackerMaskInit,
+            [
+                "vision_feat_0": features.level0,
+                "vision_feat_1": features.level1,
+                "vision_feat_2": features.level2,
+                "mask_input": mask,
+            ])
+        return try output(outputs, "object_pointer", from: Function.trackerMaskInit)
+    }
+
+    /// A zero-filled input array for `function`'s `input`, for the memory packer to fill.
+    public func makeInput(for function: String, named input: String) throws -> NDArray {
+        NDArray(descriptor: try arrayDescriptor(function, input: input))
+    }
+
+    // MARK: - Invocation
+
+    private func invoke(_ name: String, _ inputs: [String: NDArray]) async throws
+        -> [String: NDArray]
+    {
+        let state = try require()
+        try validate(name, inputs, against: state.descriptors[name]!)
+        var raw = try await state.functions[name]!.run(inputs: inputs)
+        var outputs: [String: NDArray] = [:]
+        for output in state.descriptors[name]!.outputNames {
+            if let array = raw.remove(output)?.ndArray {
+                outputs[output] = array
+            }
+        }
+        return outputs
+    }
+
+    /// Reject shape mismatches before they reach the runtime.
+    ///
+    /// A static Core AI function handed a wrongly shaped input does not raise: it kills the
+    /// process with SIGKILL and no traceback. The descriptors are right here, so the check is
+    /// cheap insurance against a failure that is otherwise very hard to debug.
+    private func validate(
+        _ name: String, _ inputs: [String: NDArray], against descriptor: InferenceFunctionDescriptor
+    ) throws {
+        for input in descriptor.inputNames {
+            guard let array = inputs[input] else {
+                throw VideoSegmentationError.invalidConfiguration(
+                    "\(name): missing input '\(input)'.")
+            }
+            guard case .ndArray(let expected) = descriptor.inputDescriptor(of: input) else {
+                throw VideoSegmentationError.invalidConfiguration(
+                    "\(name): input '\(input)' is not an array.")
+            }
+            if array.shape != expected.shape {
+                throw VideoSegmentationError.shapeMismatch(
+                    function: name, input: input, expected: expected.shape, actual: array.shape)
+            }
+        }
+        for input in inputs.keys where !descriptor.inputNames.contains(input) {
+            throw VideoSegmentationError.invalidConfiguration(
+                "\(name): unexpected input '\(input)'. Expected \(descriptor.inputNames.sorted()).")
+        }
+    }
+
+    private func require() throws -> Loaded {
+        guard let loaded else {
+            throw VideoSegmentationError.invalidConfiguration(
+                "Engine resources are not loaded; call loadResources() first.")
+        }
+        return loaded
+    }
+
+    private func output(
+        _ outputs: [String: NDArray], _ name: String, from function: String
+    ) throws -> NDArray {
+        guard let array = outputs[name] else {
+            throw VideoSegmentationError.missingOutput(function: function, name: name)
+        }
+        return array
+    }
+
+    private func arrayDescriptor(_ function: String, input: String) throws -> NDArrayDescriptor {
+        let state = try require()
+        guard let functionDescriptor = state.descriptors[function],
+            case .ndArray(let descriptor) = functionDescriptor.inputDescriptor(of: input)
+        else {
+            throw VideoSegmentationError.invalidConfiguration(
+                "\(function) has no array input named '\(input)'.")
+        }
+        return descriptor
+    }
+
+    // MARK: - Shape resolution
+
+    /// Read every geometric constant the host needs off the traced descriptors.
+    ///
+    /// Nothing here is hardcoded from the 1008 export: a 336 "lite" variant would report its
+    /// own grid and the packer would follow. What is checked is internal agreement, because a
+    /// mismatch between two entrypoints is the failure mode that SIGKILLs.
+    private static func resolveShapes(
+        _ descriptors: [String: InferenceFunctionDescriptor]
+    ) throws -> Shapes {
+        func shape(_ function: String, input: String) throws -> [Int] {
+            guard let descriptor = descriptors[function],
+                case .ndArray(let array) = descriptor.inputDescriptor(of: input)
+            else {
+                throw VideoSegmentationError.unsupportedGeometry(
+                    "\(function) has no array input '\(input)'.")
+            }
+            return array.shape
+        }
+        func outputShape(_ function: String, _ name: String) throws -> [Int] {
+            guard let descriptor = descriptors[function],
+                case .ndArray(let array) = descriptor.outputDescriptor(of: name)
+            else {
+                throw VideoSegmentationError.unsupportedGeometry(
+                    "\(function) has no array output '\(name)'.")
+            }
+            return array.shape
+        }
+
+        let pixelValues = try shape(Function.imageEncode, input: "pixel_values")
+        guard pixelValues.count == 4, pixelValues[2] == pixelValues[3] else {
+            throw VideoSegmentationError.unsupportedGeometry(
+                "image_encode expects a square [1, 3, S, S] input; got \(pixelValues).")
+        }
+        let inputIDs = try shape(Function.textEncode, input: "input_ids")
+        let predictedLogits = try outputShape(Function.detect, "pred_logits")
+        let predictedMasks = try outputShape(Function.detect, "pred_masks")
+        let spatialMemory = try shape(Function.trackerStep, input: "spatial_memory")
+        let objectPointers = try shape(Function.trackerStep, input: "object_pointers")
+        let highResolution = try outputShape(Function.trackerStep, "high_res_masks")
+        let memoryMask = try shape(Function.memoryEncode, input: "mask_logits")
+
+        guard spatialMemory.count == 4 else {
+            throw VideoSegmentationError.unsupportedGeometry(
+                "tracker_step expects [slots, HW, 1, mem_dim] spatial memory; got \(spatialMemory).")
+        }
+        guard memoryMask.count == 4, memoryMask[2] == memoryMask[3] else {
+            throw VideoSegmentationError.unsupportedGeometry(
+                "memory_encode expects a square mask input; got \(memoryMask).")
+        }
+        guard predictedMasks.count == 4, predictedMasks[2] == predictedMasks[3] else {
+            throw VideoSegmentationError.unsupportedGeometry(
+                "detect expects square masks; got \(predictedMasks).")
+        }
+
+        let shapes = Shapes(
+            imageSize: pixelValues[2],
+            textSequenceLength: inputIDs[1],
+            queryCount: predictedLogits[1],
+            lowResMaskSize: predictedMasks[2],
+            memoryMaskSize: memoryMask[2],
+            highResMaskSize: highResolution[2],
+            memoryTokenCount: spatialMemory[1],
+            memoryDim: spatialMemory[3],
+            hiddenDim: objectPointers[2],
+            spatialSlots: spatialMemory[0],
+            ptrSlots: objectPointers[0])
+
+        // Cross-entrypoint agreement. The tracker's low-res mask must line up with the
+        // detector's for association to compare them, and `memory_encode`'s score input has
+        // a trailing singleton that is easy to get wrong.
+        let trackerLowRes = try outputShape(Function.trackerStep, "pred_masks")
+        guard trackerLowRes[2] == shapes.lowResMaskSize else {
+            throw VideoSegmentationError.unsupportedGeometry(
+                "tracker_step emits \(trackerLowRes[2])px masks but detect emits "
+                    + "\(shapes.lowResMaskSize)px; association compares the two.")
+        }
+        let maskInit = try shape(Function.trackerMaskInit, input: "mask_input")
+        guard maskInit[2] == shapes.lowResMaskSize else {
+            throw VideoSegmentationError.unsupportedGeometry(
+                "tracker_mask_init takes \(maskInit[2])px masks but detections are "
+                    + "\(shapes.lowResMaskSize)px.")
+        }
+        let scoreInput = try shape(Function.memoryEncode, input: "object_score_logits")
+        let scoreOutput = try outputShape(Function.trackerStep, "object_score_logits")
+        guard scoreInput == scoreOutput else {
+            throw VideoSegmentationError.unsupportedGeometry(
+                "memory_encode takes object_score_logits\(scoreInput) but tracker_step emits "
+                    + "\(scoreOutput).")
+        }
+        let encodedMemory = try outputShape(Function.memoryEncode, "maskmem_features")
+        guard encodedMemory[0] == shapes.memoryTokenCount, encodedMemory[2] == shapes.memoryDim
+        else {
+            throw VideoSegmentationError.unsupportedGeometry(
+                "memory_encode emits \(encodedMemory) but a tracker_step slot is "
+                    + "[\(shapes.memoryTokenCount), 1, \(shapes.memoryDim)].")
+        }
+        return shapes
+    }
+}
+
+// MARK: - Output bundles
+
+/// A prompt's encoded text plus the attention mask `detect` needs alongside it.
+public struct PromptEncoding: Sendable {
+    public let textFeatures: NDArray
+    public let attentionMask: NDArray
+}
+
+/// `detect` outputs, kept as device arrays.
+///
+/// `pred_masks` is `[1, queries, 288, 288]`, 66 MB as `Float` at 200 queries. Callers read
+/// the logits first and pull only the surviving mask slices.
+public struct DetectOutputs: Sendable {
+    public let predictedMasks: NDArray
+    public let predictedBoxes: NDArray
+    public let predictedLogits: NDArray
+    public let presenceLogits: NDArray
+}
+
+/// The four `tracker_encode` outputs anything downstream actually reads.
+public struct TrackerFeatures: Sendable {
+    public let level0: NDArray
+    public let level1: NDArray
+    public let level2: NDArray
+    public let positionLevel2: NDArray
+}
+
+public struct TrackerStepOutputs: Sendable {
+    public let predictedMasks: NDArray
+    public let highResolutionMasks: NDArray
+    public let objectPointer: NDArray
+    public let objectScoreLogits: NDArray
+}
+
+public struct EncodedMemory: Sendable {
+    public let features: NDArray
+    public let positionEncoding: NDArray
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationError.swift b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationError.swift
new file mode 100644
index 00000000..fe873d0b
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationError.swift
@@ -0,0 +1,43 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import Foundation
+
+/// Everything that can go wrong in the video segmentation runtime.
+public enum VideoSegmentationError: Error, CustomStringConvertible, LocalizedError {
+    case invalidConfiguration(String)
+    case missingFunction(name: String, available: [String])
+    case missingOutput(function: String, name: String)
+    case shapeMismatch(function: String, input: String, expected: [Int], actual: [Int])
+    case unsupportedGeometry(String)
+    case noPrompts
+    case parityReferenceInvalid(String)
+
+    public var description: String {
+        switch self {
+        case .invalidConfiguration(let detail):
+            return detail
+        case .missingFunction(let name, let available):
+            return
+                "Asset has no '\(name)' function. Available: \(available.sorted().joined(separator: ", ")). "
+                + "Re-export with models/sam3_video/export.py."
+        case .missingOutput(let function, let name):
+            return "'\(function)' returned no output named '\(name)'."
+        case .shapeMismatch(let function, let input, let expected, let actual):
+            // Detailed because a shape mismatch SIGKILLs the process with no traceback.
+            return
+                "\(function): input '\(input)' has shape \(actual), but the graph was traced "
+                + "with \(expected)."
+        case .unsupportedGeometry(let detail):
+            return detail
+        case .noPrompts:
+            return "No text prompts were provided; video segmentation needs at least one."
+        case .parityReferenceInvalid(let detail):
+            return "Parity reference is unusable: \(detail)"
+        }
+    }
+
+    public var errorDescription: String? { description }
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationOutputs.swift b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationOutputs.swift
new file mode 100644
index 00000000..86e85274
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationOutputs.swift
@@ -0,0 +1,93 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreAIShared
+import CoreGraphics
+import Foundation
+
+/// One tracked object on one frame.
+public struct TrackedObject: Sendable {
+    /// Stable id for the masklet; survives across frames until the track ends.
+    public let id: Int
+    /// Text prompt that discovered this object.
+    public let prompt: String
+    /// Binary mask at the source video's resolution.
+    public let mask: MaskBitset
+    /// Mask-derived bounding box in pixels, top-left origin. Derived the way
+    /// `torchvision.ops.masks_to_boxes` does, so the extremes are inclusive.
+    public let box: CGRect
+    /// Detection score in [0, 1] for the frame the object was found on.
+    public let score: Float
+    /// Tracker confidence on this frame, or 0 before the tracker has seen the object.
+    public let trackerScore: Float
+}
+
+/// The result for one frame of video.
+public struct VideoSegmentationFrame: Sendable {
+    /// Index into the decoded frame sequence, 0-based.
+    public let frameIndex: Int
+    /// Surviving objects, ordered by id.
+    public let objects: [TrackedObject]
+    /// The source frame, so callers can composite without decoding twice.
+    public let image: CGImage
+
+    /// Per-object mask logits at the model's low resolution, ordered like `objects`.
+    ///
+    /// Empty unless ``VideoSegmentationParameters/emitLowResolutionMasks`` is set. See
+    /// that flag for why it exists.
+    public let lowResolutionMasks: [[Float]]
+
+    /// Wall clock spent processing this frame.
+    ///
+    /// Measured around the frame's own work, not between emissions. Hotstart holds the first
+    /// `hotstartDelay` results back and flushes the backlog at the end of the video, so timing
+    /// the gap between emissions would report that buffering rather than the model.
+    public let processingTime: Duration
+}
+
+// MARK: - Internal frame-loop types
+
+/// Detections for one frame, merged across every prompt.
+///
+/// Port of what `_merge_detections_from_prompts` returns, minus `bbox`: nothing downstream
+/// reads the detector's boxes. Association, reconditioning, seeding, and the output
+/// builder all work off `mask`, and the boxes the caller finally sees come from
+/// `masks_to_boxes` on the upsampled mask.
+struct MergedDetections {
+    /// Low-resolution mask logits, one flat `size * size` buffer per detection.
+    var maskLogits: [[Float]] = []
+    /// The same masks binarized at 0, for every IoU in the frame loop.
+    var masks: [MaskBitset] = []
+    var scores: [Float] = []
+    /// Prompt that produced each detection, parallel to the arrays above.
+    var promptIDs: [Int] = []
+
+    var count: Int { scores.count }
+    var isEmpty: Bool { scores.isEmpty }
+}
+
+/// What the planning phase decided, consumed by the execution phase and the output
+/// builder. Port of `tracker_update_plan`.
+struct TrackerUpdatePlan {
+    var newDetectionIndices: [Int] = []
+    var newObjectIDs: [Int] = []
+    var unmatchedTrackIDs: [Int] = []
+    var detectionToMatchedTrackIDs: [Int: [Int]] = [:]
+    var newlyRemovedObjectIDs: Set<Int> = []
+    var trackIDToHighConfidenceDetection: [Int: Int] = [:]
+    var reconditionedObjectIDs: Set<Int> = []
+    var droppedDueToObjectLimit = 0
+}
+
+/// The per-frame model output before postprocessing. Port of `Sam3VideoSegmentationOutput`.
+struct RawFrameOutput {
+    let frameIndex: Int
+    /// Object id to low-resolution mask logits.
+    var maskLogitsByObjectID: [Int: [Float]]
+    var objectIDs: [Int]
+    var scoreByObjectID: [Int: Float]
+    var trackerScoreByObjectID: [Int: Float]
+    var suppressedObjectIDs: Set<Int>
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationParameters.swift b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationParameters.swift
new file mode 100644
index 00000000..c3987a62
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationParameters.swift
@@ -0,0 +1,169 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreGraphics
+import Foundation
+
+/// Runtime knobs for video segmentation.
+///
+/// The tracking fields mirror `transformers.Sam3VideoConfig` field for field, defaults
+/// included, because the exported asset holds only tensor kernels; every threshold below
+/// governs host-side logic that HF reads off the model config at load time. A bundle can
+/// override them through a `tracking` block in its `metadata.json`; see
+/// ``VideoSegmenterBundle``.
+public struct VideoSegmentationParameters: Sendable {
+    // MARK: - Detection
+
+    /// Probability threshold for keeping a detection. `score_threshold_detection`.
+    public var scoreThresholdDetection: Float = 0.5
+
+    /// Mask-IoU threshold for detection NMS. `det_nms_thresh`. Zero disables NMS.
+    ///
+    /// HF runs NMS through an optional `kernels-community/cv-utils` kernel and silently
+    /// keeps every above-threshold detection when it isn't installed. This runtime always
+    /// has NMS available, so set this to 0 when comparing against a Python run that was
+    /// missing the kernel.
+    public var detNmsThresh: Float = 0.1
+
+    /// Probability threshold for promoting a detection to a new tracked object.
+    /// `new_det_thresh`.
+    public var newDetThresh: Float = 0.7
+
+    // MARK: - Association
+
+    /// Loose IoU threshold: above this a detection counts as matching a track.
+    /// `assoc_iou_thresh`.
+    public var assocIouThresh: Float = 0.1
+
+    /// Stricter IoU threshold deciding whether a track is "unmatched" this frame.
+    /// `trk_assoc_iou_thresh`.
+    public var trkAssocIouThresh: Float = 0.5
+
+    /// Confidence a detection needs before it may recondition a track. `high_conf_thresh`.
+    public var highConfThresh: Float = 0.8
+
+    /// IoU a detection needs before it may recondition a track. `high_iou_thresh`.
+    public var highIouThresh: Float = 0.8
+
+    // MARK: - Reconditioning
+
+    /// Recondition every Nth frame; 0 disables. `recondition_every_nth_frame`.
+    public var reconditionEveryNthFrame: Int = 16
+
+    /// True strengthens memory with the tracked mask (detector as validation); false
+    /// replaces it with the detection mask (detector as correction).
+    /// `recondition_on_trk_masks`.
+    ///
+    /// This defaults to the checkpoint's value, not the class's. `Sam3VideoConfig` declares
+    /// `True`, but `facebook/sam3`'s `config.json` sets it to `False`, and it is the only
+    /// field where the two disagree. Getting it wrong is invisible until a reconditioning
+    /// frame lands, after which every frame's memory is conditioned on the wrong mask.
+    /// Bundles exported with a `tracking` block carry the real value and override this.
+    public var reconditionOnTrkMasks: Bool = false
+
+    // MARK: - Hotstart
+
+    /// Frames of output held back while the removal heuristics decide. `hotstart_delay`.
+    /// Zero disables both the delay and the removal rules that depend on it.
+    public var hotstartDelay: Int = 15
+
+    /// Unmatched frames before a track is removed during hotstart. `hotstart_unmatch_thresh`.
+    public var hotstartUnmatchThresh: Int = 8
+
+    /// Overlapping frames before a duplicate track is removed. `hotstart_dup_thresh`.
+    public var hotstartDupThresh: Int = 8
+
+    /// Restrict unmatched-suppression to the hotstart window.
+    /// `suppress_unmatched_only_within_hotstart`.
+    public var suppressUnmatchedOnlyWithinHotstart: Bool = true
+
+    /// Keep-alive counter a new track starts with. `init_trk_keep_alive`.
+    public var initTrkKeepAlive: Int = 30
+
+    /// Ceiling for the keep-alive counter. `max_trk_keep_alive`.
+    public var maxTrkKeepAlive: Int = 30
+
+    /// Floor for the keep-alive counter. `min_trk_keep_alive`.
+    public var minTrkKeepAlive: Int = -1
+
+    /// Decrement keep-alive for tracks the tracker returned empty. Off upstream.
+    /// `decrease_trk_keep_alive_for_empty_masklets`.
+    public var decreaseTrkKeepAliveForEmptyMasklets: Bool = false
+
+    // MARK: - Suppression
+
+    /// IoU above which two overlapping objects contend, resolved by which was occluded
+    /// more recently. Zero disables. `suppress_overlapping_based_on_recent_occlusion_threshold`.
+    public var suppressOverlappingOcclusionThreshold: Float = 0.7
+
+    /// Maximum simultaneous tracked objects. `max_num_objects`.
+    public var maxNumObjects: Int = 10000
+
+    // MARK: - Tracker memory geometry
+
+    // These three come from `Sam3TrackerVideoConfig`, not `Sam3VideoConfig`, and they
+    // decide which stored frames are eligible for the memory bank. The exported asset pins
+    // their sum (`spatial_slots` is `max_cond_frame_num + num_maskmem - 1`) but not the
+    // split, so they have to be carried separately.
+
+    /// Total mask-memory frames: the current one plus `num_maskmem - 1` recent.
+    /// `num_maskmem`.
+    public var numMaskmem: Int = 7
+
+    /// Conditioning frames the memory bank may draw on. `max_cond_frame_num`.
+    public var maxCondFrameNum: Int = 4
+
+    /// Look-back window for object pointers. `max_object_pointers_in_encoder`.
+    public var maxObjectPointers: Int = 16
+
+    // MARK: - Mask cleanup
+
+    /// Maximum area of a connected component that gets filled (background) or removed
+    /// (foreground). `fill_hole_area`. Zero disables both.
+    ///
+    /// Like ``detNmsThresh``, HF no-ops this without `kernels-community/cv-utils`. Set to
+    /// 0 to reproduce a Python run made without it.
+    public var fillHoleArea: Int = 16
+
+    // MARK: - Preprocessing
+
+    /// Per-channel means applied after scaling pixels to [0, 1]. SAM 3 uses
+    /// `IMAGENET_STANDARD_MEAN`.
+    public var normalizationMeans: (CGFloat, CGFloat, CGFloat) = (0.5, 0.5, 0.5)
+
+    /// Per-channel standard deviations. SAM 3 uses `IMAGENET_STANDARD_STD`.
+    public var normalizationStds: (CGFloat, CGFloat, CGFloat) = (0.5, 0.5, 0.5)
+
+    // MARK: - Rendering
+
+    /// Opacity of a mask fill over the source frame, in [0, 1].
+    public var maskOpacity: Float = 0.5
+
+    /// Draw the mask-derived bounding box for each object.
+    public var drawBoxes: Bool = true
+
+    /// Draw a `#id prompt score` caption above each box.
+    public var drawLabels: Bool = true
+
+    /// Box and outline stroke width in pixels.
+    public var strokeWidth: CGFloat = 3
+
+    // MARK: - Diagnostics
+
+    /// Also report each object's mask logits at the model's own resolution, before the
+    /// upsample to video size.
+    ///
+    /// Off by default because it is 82,944 floats per object per frame. On, it separates a
+    /// tracker disagreement from an upsampling one: matching low-resolution masks with
+    /// differing final masks means the two upsampled differently.
+    public var emitLowResolutionMasks: Bool = false
+
+    public init() {}
+
+    public static let `default` = VideoSegmentationParameters()
+
+    /// Whether the hotstart removal rules apply at all.
+    var hotstartEnabled: Bool { hotstartDelay > 0 }
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/VideoSegmenter.swift b/swift/Sources/CoreAIVideoSegmenter/VideoSegmenter.swift
new file mode 100644
index 00000000..2a1b5882
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/VideoSegmenter.swift
@@ -0,0 +1,317 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreAIShared
+import CoreGraphics
+import Foundation
+
+/// Text-promptable video object segmentation and tracking (SAM 3 video).
+///
+/// ```swift
+/// let segmenter = try await VideoSegmenter(resourcesAt: "exports/sam3_video_float16")
+/// try await segmenter.renderAnnotatedVideo(
+///     from: URL(fileURLWithPath: "clip.mp4"),
+///     prompts: ["person", "dog"],
+///     to: URL(fileURLWithPath: "out.mp4"))
+/// ```
+///
+/// Or consume the per-frame results directly:
+///
+/// ```swift
+/// for try await frame in segmenter.segment(videoAt: url, prompts: ["person"]) {
+///     print(frame.frameIndex, frame.objects.map(\.id))
+/// }
+/// ```
+///
+/// ## Hotstart delay
+///
+/// SAM 3 buffers its first `hotstartDelay` frames (15 by default) before emitting
+/// anything, because a track it removes on frame 20 must never have been shown on frame 8.
+/// The stream honours that, which means the decoded frames have to be held too, bounded at
+/// 15 frames and roughly 124 MB at 1080p. Set `hotstartDelay` to 0 to disable both the
+/// delay and the removal rules that need it.
+@VideoSegmentationActor
+public final class VideoSegmenter: ResourceManaging {
+    private let bundle: VideoSegmenterBundle
+    private let engine: VideoSegmentationEngine
+    private let tokenizer: CLIPTokenizer
+    public let parameters: VideoSegmentationParameters
+
+    private var shapes: VideoSegmentationEngine.Shapes?
+    private var packer: MemoryBankPacker?
+    private var tracker: TrackerLoop?
+
+    /// Cumulative wall clock per Core AI entrypoint from the most recent run.
+    public private(set) var lastRunTimings: [String: Double] = [:]
+
+    /// Load a `kind: video_segmenter` bundle directory.
+    ///
+    /// - Parameters:
+    ///   - path: Bundle directory holding `metadata.json`, the `.aimodel`, and `tokenizer/`.
+    ///   - parameters: Overrides applied *under* the bundle's own `tracking` block, so a
+    ///     bundle that declares its thresholds still wins. Pass per-run overrides to
+    ///     ``segment(videoAt:prompts:maxFrames:parameters:)`` instead.
+    public init(
+        resourcesAt path: String,
+        parameters: VideoSegmentationParameters = .default
+    ) async throws {
+        let bundle = try VideoSegmenterBundle(from: path)
+        self.bundle = bundle
+        self.parameters = bundle.parameters(overriding: parameters)
+        self.tokenizer = try CLIPTokenizer(folder: bundle.tokenizerFolder)
+        self.engine = VideoSegmentationEngine(modelURL: bundle.modelURL)
+    }
+
+    /// Load and specialize the asset. Called implicitly on first use.
+    public func loadResources() async throws {
+        guard shapes == nil else { return }
+        try await engine.loadResources()
+        guard let resolved = await engine.shapes else {
+            throw VideoSegmentationError.invalidConfiguration(
+                "Engine reported no shapes after loading.")
+        }
+        // The bundle's declared geometry and the traced graph must agree. They come from
+        // the same export, so a mismatch means the metadata and the asset were paired by
+        // hand, worth failing loudly rather than packing memory to the wrong layout.
+        guard resolved.imageSize == bundle.geometry.imageSize,
+            resolved.spatialSlots == bundle.geometry.spatialSlots,
+            resolved.ptrSlots == bundle.geometry.ptrSlots,
+            resolved.textSequenceLength == bundle.geometry.maxTextSeqLen
+        else {
+            throw VideoSegmentationError.unsupportedGeometry(
+                "metadata.json declares image_size \(bundle.geometry.imageSize), spatial_slots "
+                    + "\(bundle.geometry.spatialSlots), ptr_slots \(bundle.geometry.ptrSlots), "
+                    + "max_text_seq_len \(bundle.geometry.maxTextSeqLen), but the asset was traced "
+                    + "at \(resolved.imageSize) / \(resolved.spatialSlots) / \(resolved.ptrSlots) "
+                    + "/ \(resolved.textSequenceLength).")
+        }
+
+        let packed = try await MemoryBankPacker.makePacked(engine: engine)
+        let packer = try MemoryBankPacker(
+            engine: engine, shapes: resolved, parameters: parameters, packed: packed)
+        self.shapes = resolved
+        self.packer = packer
+        self.tracker = TrackerLoop(
+            engine: engine, shapes: resolved, parameters: parameters, packer: packer)
+    }
+
+    /// Release the asset. The next call reloads it.
+    public func unloadResources() async {
+        await engine.unloadResources()
+        shapes = nil
+        packer = nil
+        tracker = nil
+    }
+
+    /// Run every entrypoint once on zeros, so the first frame isn't paying for kernel
+    /// compilation.
+    public func warmup() async throws {
+        try await loadResources()
+        try await engine.warmup()
+    }
+
+    /// Segment and track `prompts` through an already-decoded frame sequence.
+    ///
+    /// The frames are consumed in the order given and their indices are their positions.
+    /// Use this for camera capture, image sequences, or to hold the video decoder constant:
+    /// AVFoundation and PyAV disagree by about 0.65 code values on average even on
+    /// colour-tagged media, which is enough to move a mask boundary.
+    public nonisolated func segment(
+        frames: [CGImage],
+        prompts: [String],
+        parameters overrides: VideoSegmentationParameters? = nil
+    ) -> AsyncThrowingStream<VideoSegmentationFrame, Error> {
+        AsyncThrowingStream { continuation in
+            let task = Task {
+                do {
+                    try await run(
+                        source: .images(frames), prompts: prompts, maxFrames: nil,
+                        parameters: overrides ?? self.parameters,
+                        emit: { continuation.yield($0) })
+                    continuation.finish()
+                } catch {
+                    continuation.finish(throwing: error)
+                }
+            }
+            continuation.onTermination = { _ in task.cancel() }
+        }
+    }
+
+    /// Segment and track `prompts` through the video at `url`, one result per frame.
+    ///
+    /// Results arrive in frame order but lag the decoder by `hotstartDelay` frames; the
+    /// backlog is flushed when the video ends.
+    ///
+    /// Nonisolated so a caller can start the stream without an `await`: the frame loop it
+    /// spawns hops onto the actor, and everything read here is immutable.
+    public nonisolated func segment(
+        videoAt url: URL,
+        prompts: [String],
+        maxFrames: Int? = nil,
+        parameters overrides: VideoSegmentationParameters? = nil
+    ) -> AsyncThrowingStream<VideoSegmentationFrame, Error> {
+        AsyncThrowingStream { continuation in
+            let task = Task {
+                do {
+                    try await run(
+                        source: .video(url), prompts: prompts, maxFrames: maxFrames,
+                        parameters: overrides ?? self.parameters,
+                        emit: { continuation.yield($0) })
+                    continuation.finish()
+                } catch {
+                    continuation.finish(throwing: error)
+                }
+            }
+            continuation.onTermination = { _ in task.cancel() }
+        }
+    }
+
+    /// Where a run's frames come from.
+    private enum FrameSource {
+        case video(URL)
+        case images([CGImage])
+    }
+
+    /// Segment the video and write an annotated copy with masks and boxes composited on.
+    ///
+    /// - Returns: The number of frames written.
+    @discardableResult
+    public func renderAnnotatedVideo(
+        from source: URL,
+        prompts: [String],
+        to destination: URL,
+        maxFrames: Int? = nil,
+        parameters overrides: VideoSegmentationParameters? = nil,
+        onFrame: (@Sendable (VideoSegmentationFrame) async -> Void)? = nil
+    ) async throws -> Int {
+        let effective = overrides ?? parameters
+        let metadata = try await SequentialVideoReader.metadata(of: source)
+        let renderer = VideoOverlayRenderer(parameters: effective)
+        let writer = try StreamingVideoWriter(
+            url: destination,
+            width: metadata.width,
+            height: metadata.height,
+            frameRate: max(1, Int(metadata.nominalFrameRate.rounded())))
+
+        var written = 0
+        // Encoding is serialized behind the writer actor while the next frame's inference
+        // runs, so the two overlap naturally without an explicit pipeline.
+        for try await frame in segment(
+            videoAt: source, prompts: prompts, maxFrames: maxFrames, parameters: effective)
+        {
+            await onFrame?(frame)
+            try await writer.append(renderer.render(frame.objects, onto: frame.image))
+            written += 1
+        }
+        try await writer.finish()
+        return written
+    }
+
+    // MARK: - Frame loop
+
+    /// Port of `Sam3VideoModel.propagate_in_video_iterator`, forward only.
+    ///
+    /// Reverse propagation is plumbed through the heuristics but has no entry point here:
+    /// it needs the whole video resident so it can start from the last frame, which is the
+    /// opposite of how this streams.
+    private func run(
+        source: FrameSource,
+        prompts: [String],
+        maxFrames: Int?,
+        parameters: VideoSegmentationParameters,
+        emit: (VideoSegmentationFrame) -> Void
+    ) async throws {
+        guard !prompts.isEmpty else { throw VideoSegmentationError.noPrompts }
+        try await loadResources()
+        guard let shapes, let tracker else {
+            throw VideoSegmentationError.invalidConfiguration("Engine failed to initialize.")
+        }
+
+        let width: Int
+        let height: Int
+        let totalFrames: Int
+        switch source {
+        case .video(let url):
+            let metadata = try await SequentialVideoReader.metadata(of: url)
+            width = metadata.width
+            height = metadata.height
+            totalFrames = min(metadata.estimatedFrameCount, maxFrames ?? .max)
+        case .images(let images):
+            guard let first = images.first else { return }
+            width = first.width
+            height = first.height
+            totalFrames = images.count
+        }
+
+        let session = VideoInferenceSession(videoWidth: width, videoHeight: height)
+        for prompt in prompts {
+            let id = session.addPrompt(prompt)
+            if session.promptTokens[id] == nil {
+                session.promptTokens[id] = tokenizer.encodeWithMask(
+                    prompt, contextLength: shapes.textSequenceLength)
+            }
+        }
+
+        let processor = FrameProcessor(
+            engine: engine, shapes: shapes, parameters: parameters, tracker: tracker)
+        let postprocessor = MaskPostprocessor(
+            lowResolutionSize: shapes.lowResMaskSize, videoWidth: width, videoHeight: height,
+            emitLowResolutionMasks: parameters.emitLowResolutionMasks)
+
+        // The hotstart buffer holds decoded frames as well as results: the renderer needs
+        // the source image, and re-decoding it later would mean a second pass over the file.
+        var buffer: [(raw: RawFrameOutput, image: CGImage, elapsed: Duration)] = []
+
+        func handle(_ image: CGImage, index: Int) async throws {
+            try Task.checkCancellation()
+            let started = ContinuousClock.now
+            let raw = try await processor.process(
+                session: session, image: image, frameIndex: index,
+                totalFrames: totalFrames, reverse: false)
+            let elapsed = ContinuousClock.now - started
+
+            guard parameters.hotstartEnabled else {
+                emit(finish(raw, image, elapsed))
+                return
+            }
+            buffer.append((raw, image, elapsed))
+            if buffer.count >= parameters.hotstartDelay {
+                let (oldest, oldestImage, oldestElapsed) = buffer.removeFirst()
+                emit(finish(oldest, oldestImage, oldestElapsed))
+            }
+        }
+
+        func finish(
+            _ raw: RawFrameOutput, _ image: CGImage, _ elapsed: Duration
+        ) -> VideoSegmentationFrame {
+            let processed = postprocessor.postprocess(raw, session: session)
+            return VideoSegmentationFrame(
+                frameIndex: raw.frameIndex,
+                objects: processed.objects,
+                image: image,
+                lowResolutionMasks: processed.lowResolutionMasks,
+                processingTime: elapsed)
+        }
+
+        switch source {
+        case .video(let url):
+            for try await frame in SequentialVideoReader.frames(of: url, maxFrames: maxFrames) {
+                try await handle(frame.image, index: frame.index)
+            }
+        case .images(let images):
+            for (index, image) in images.enumerated() {
+                try await handle(image, index: index)
+            }
+        }
+
+        // End of video: flush whatever the delay is still holding. These are postprocessed
+        // last on purpose, because `hotstartRemovedObjectIDs` has now seen every removal, so
+        // a track removed at the very end is hidden in the buffered frames too.
+        for (raw, image, elapsed) in buffer {
+            emit(finish(raw, image, elapsed))
+        }
+        lastRunTimings = processor.timings
+    }
+}
diff --git a/swift/Sources/CoreAIVideoSegmenter/VideoSegmenterBundle.swift b/swift/Sources/CoreAIVideoSegmenter/VideoSegmenterBundle.swift
new file mode 100644
index 00000000..08fa02d1
--- /dev/null
+++ b/swift/Sources/CoreAIVideoSegmenter/VideoSegmenterBundle.swift
@@ -0,0 +1,182 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreAIShared
+import Foundation
+
+/// A `kind: video_segmenter` model bundle: the asset, the tokenizer, and the slot
+/// geometry the host has to pack memory to.
+///
+/// The `runtime` block is required. The host builds fixed-capacity memory-bank tensors
+/// whose shapes must match what the graph was traced with, and deriving those from a
+/// hardcoded default would break silently the moment somebody re-exports with
+/// `--spatial-slots`.
+///
+/// The `tracking` block is optional and carries the `Sam3VideoConfig` thresholds. A bundle
+/// without it gets ``VideoSegmentationParameters``'s defaults, which are the upstream config's
+/// own defaults.
+public struct VideoSegmenterBundle: Sendable {
+    public let bundle: ModelBundle
+    public let modelURL: URL
+    public let tokenizerFolder: URL
+    public let geometry: Geometry
+
+    /// Slot geometry from the bundle's `runtime` block.
+    public struct Geometry: Sendable, Decodable, Equatable {
+        /// Square input resolution the vision encoder was traced at.
+        public let imageSize: Int
+        /// Spatial memory slots per object in `tracker_step`.
+        public let spatialSlots: Int
+        /// Object-pointer slots per object in `tracker_step`.
+        public let ptrSlots: Int
+        /// Token count `text_encode` was traced at.
+        public let maxTextSeqLen: Int
+
+        enum CodingKeys: String, CodingKey {
+            case imageSize = "image_size"
+            case spatialSlots = "spatial_slots"
+            case ptrSlots = "ptr_slots"
+            case maxTextSeqLen = "max_text_seq_len"
+        }
+    }
+
+    public init(from path: String) throws {
+        try self.init(bundle: ModelBundle(from: path))
+    }
+
+    public init(bundle: ModelBundle) throws {
+        guard bundle.kind == .videoSegmenter else {
+            throw ModelBundle.BundleError.kindMismatch(expected: .videoSegmenter, got: bundle.kind)
+        }
+        self.bundle = bundle
+        self.modelURL = try bundle.requireModelURL(for: ModelBundle.ComponentKey.main)
+        self.tokenizerFolder = bundle.bundlePath.appending(path: "tokenizer")
+
+        guard let runtime = try? JSONDecoder().decode(RuntimeEnvelope.self, from: bundle.raw),
+            let geometry = runtime.runtime
+        else {
+            throw VideoSegmentationError.invalidConfiguration(
+                "\(bundle.bundlePath.lastPathComponent)/metadata.json has no 'runtime' block. "
+                    + "A video_segmenter bundle must declare image_size, spatial_slots, "
+                    + "ptr_slots, and max_text_seq_len.")
+        }
+        guard geometry.imageSize > 0, geometry.spatialSlots > 0, geometry.ptrSlots > 0,
+            geometry.maxTextSeqLen > 0
+        else {
+            throw VideoSegmentationError.invalidConfiguration(
+                "metadata.json 'runtime' values must all be positive; got \(geometry).")
+        }
+        self.geometry = geometry
+    }
+
+    /// Parameters with any `tracking` overrides from metadata.json applied on top of
+    /// `base`. Absent keys keep their value from `base`.
+    public func parameters(overriding base: VideoSegmentationParameters = .default)
+        -> VideoSegmentationParameters
+    {
+        guard let envelope = try? JSONDecoder().decode(TrackingEnvelope.self, from: bundle.raw),
+            let tracking = envelope.tracking
+        else { return base }
+
+        var parameters = base
+        tracking.scoreThresholdDetection.map { parameters.scoreThresholdDetection = $0 }
+        tracking.detNmsThresh.map { parameters.detNmsThresh = $0 }
+        tracking.newDetThresh.map { parameters.newDetThresh = $0 }
+        tracking.assocIouThresh.map { parameters.assocIouThresh = $0 }
+        tracking.trkAssocIouThresh.map { parameters.trkAssocIouThresh = $0 }
+        tracking.highConfThresh.map { parameters.highConfThresh = $0 }
+        tracking.highIouThresh.map { parameters.highIouThresh = $0 }
+        tracking.reconditionEveryNthFrame.map { parameters.reconditionEveryNthFrame = $0 }
+        tracking.reconditionOnTrkMasks.map { parameters.reconditionOnTrkMasks = $0 }
+        tracking.hotstartDelay.map { parameters.hotstartDelay = $0 }
+        tracking.hotstartUnmatchThresh.map { parameters.hotstartUnmatchThresh = $0 }
+        tracking.hotstartDupThresh.map { parameters.hotstartDupThresh = $0 }
+        tracking.suppressUnmatchedOnlyWithinHotstart.map {
+            parameters.suppressUnmatchedOnlyWithinHotstart = $0
+        }
+        tracking.initTrkKeepAlive.map { parameters.initTrkKeepAlive = $0 }
+        tracking.maxTrkKeepAlive.map { parameters.maxTrkKeepAlive = $0 }
+        tracking.minTrkKeepAlive.map { parameters.minTrkKeepAlive = $0 }
+        tracking.decreaseTrkKeepAliveForEmptyMasklets.map {
+            parameters.decreaseTrkKeepAliveForEmptyMasklets = $0
+        }
+        tracking.suppressOverlappingOcclusionThreshold.map {
+            parameters.suppressOverlappingOcclusionThreshold = $0
+        }
+        tracking.maxNumObjects.map { parameters.maxNumObjects = $0 }
+        tracking.fillHoleArea.map { parameters.fillHoleArea = $0 }
+        tracking.numMaskmem.map { parameters.numMaskmem = $0 }
+        tracking.maxCondFrameNum.map { parameters.maxCondFrameNum = $0 }
+        tracking.maxObjectPointers.map { parameters.maxObjectPointers = $0 }
+        return parameters
+    }
+
+    // MARK: - Codable shapes
+
+    private struct RuntimeEnvelope: Decodable {
+        let runtime: Geometry?
+    }
+
+    private struct TrackingEnvelope: Decodable {
+        let tracking: Tracking?
+    }
+
+    /// Every field optional so a partial `tracking` block is legal and an unfamiliar key
+    /// from a newer exporter is ignored rather than fatal.
+    private struct Tracking: Decodable {
+        let scoreThresholdDetection: Float?
+        let detNmsThresh: Float?
+        let newDetThresh: Float?
+        let assocIouThresh: Float?
+        let trkAssocIouThresh: Float?
+        let highConfThresh: Float?
+        let highIouThresh: Float?
+        let reconditionEveryNthFrame: Int?
+        let reconditionOnTrkMasks: Bool?
+        let hotstartDelay: Int?
+        let hotstartUnmatchThresh: Int?
+        let hotstartDupThresh: Int?
+        let suppressUnmatchedOnlyWithinHotstart: Bool?
+        let initTrkKeepAlive: Int?
+        let maxTrkKeepAlive: Int?
+        let minTrkKeepAlive: Int?
+        let decreaseTrkKeepAliveForEmptyMasklets: Bool?
+        let suppressOverlappingOcclusionThreshold: Float?
+        let maxNumObjects: Int?
+        let fillHoleArea: Int?
+        let numMaskmem: Int?
+        let maxCondFrameNum: Int?
+        let maxObjectPointers: Int?
+
+        // Snake case throughout, matching the HF config field names the exporter copies.
+        enum CodingKeys: String, CodingKey {
+            case scoreThresholdDetection = "score_threshold_detection"
+            case detNmsThresh = "det_nms_thresh"
+            case newDetThresh = "new_det_thresh"
+            case assocIouThresh = "assoc_iou_thresh"
+            case trkAssocIouThresh = "trk_assoc_iou_thresh"
+            case highConfThresh = "high_conf_thresh"
+            case highIouThresh = "high_iou_thresh"
+            case reconditionEveryNthFrame = "recondition_every_nth_frame"
+            case reconditionOnTrkMasks = "recondition_on_trk_masks"
+            case hotstartDelay = "hotstart_delay"
+            case hotstartUnmatchThresh = "hotstart_unmatch_thresh"
+            case hotstartDupThresh = "hotstart_dup_thresh"
+            case suppressUnmatchedOnlyWithinHotstart = "suppress_unmatched_only_within_hotstart"
+            case initTrkKeepAlive = "init_trk_keep_alive"
+            case maxTrkKeepAlive = "max_trk_keep_alive"
+            case minTrkKeepAlive = "min_trk_keep_alive"
+            case decreaseTrkKeepAliveForEmptyMasklets =
+                "decrease_trk_keep_alive_for_empty_masklets"
+            case suppressOverlappingOcclusionThreshold =
+                "suppress_overlapping_based_on_recent_occlusion_threshold"
+            case maxNumObjects = "max_num_objects"
+            case fillHoleArea = "fill_hole_area"
+            case numMaskmem = "num_maskmem"
+            case maxCondFrameNum = "max_cond_frame_num"
+            case maxObjectPointers = "max_object_pointers_in_encoder"
+        }
+    }
+}
diff --git a/swift/Sources/Tools/video-segmenter/ParityReference.swift b/swift/Sources/Tools/video-segmenter/ParityReference.swift
new file mode 100644
index 00000000..cdf0f643
--- /dev/null
+++ b/swift/Sources/Tools/video-segmenter/ParityReference.swift
@@ -0,0 +1,167 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreAIShared
+import CoreAIVideoSegmenter
+import CoreGraphics
+import Foundation
+import ImageIO
+
+/// Per-frame detect-and-track output from a reference implementation, to compare this port
+/// against. Any producer that writes the layout below will do.
+///
+/// Layout, one `.npy` per array so the files stay readable from either side:
+///
+/// ```
+/// <dir>/manifest.json            video path, prompts, frame indices, video size
+/// <dir>/frames/frame_0000.png    the exact frames PyTorch saw, lossless
+/// <dir>/frame_0000_ids.npy       int32  [N]
+/// <dir>/frame_0000_scores.npy    float32[N]
+/// <dir>/frame_0000_boxes.npy     float32[N, 4]   xyxy, top-left origin
+/// <dir>/frame_0000_masks.npy     uint8  [N, ceil(H*W/8)]  numpy.packbits, MSB first
+/// ```
+///
+/// Masks are bit-packed because at video resolution a boolean array is eight times larger
+/// for no extra information: a 51-frame 1080p clip with five tracks is 65 MB packed
+/// against 520 MB raw.
+///
+/// The PNGs matter: AVFoundation and PyAV do not decode the same file to the same pixels.
+/// With the colour space tagged they differ by about 0.65 code values on average, and by
+/// 3.7 when the container leaves it unset. That is a real difference between the two
+/// stacks but it is not a difference in the port, so parity reads the frames rather than
+/// decoding them.
+struct ParityReference {
+    struct Object {
+        let id: Int
+        let score: Float
+        let box: CGRect
+        let mask: MaskBitset
+    }
+
+    private let directory: URL
+    private let manifest: Manifest
+
+    let videoURL: URL
+    var prompts: [String] { manifest.prompts }
+    var frameIndices: [Int] { manifest.frames }
+    var frameCount: Int { manifest.frames.count }
+
+    private struct Manifest: Decodable {
+        let video: String
+        let prompts: [String]
+        let frames: [Int]
+        let width: Int
+        let height: Int
+        let frameImages: String?
+
+        enum CodingKeys: String, CodingKey {
+            case video, prompts, frames, width, height
+            case frameImages = "frame_images"
+        }
+    }
+
+    init(directory: URL) throws {
+        self.directory = directory
+        let manifestURL = directory.appending(path: "manifest.json")
+        guard let data = try? Data(contentsOf: manifestURL) else {
+            throw VideoSegmentationError.parityReferenceInvalid(
+                "no manifest.json at \(manifestURL.path). See `ParityReference` for the "
+                    + "layout a reference directory needs.")
+        }
+        do {
+            self.manifest = try JSONDecoder().decode(Manifest.self, from: data)
+        } catch {
+            throw VideoSegmentationError.parityReferenceInvalid(
+                "manifest.json is malformed: \(error)")
+        }
+        // The manifest records the clip it was produced from; resolve a relative path
+        // against the reference directory so the pair can be moved together.
+        let recorded = URL(fileURLWithPath: manifest.video)
+        self.videoURL =
+            recorded.path.hasPrefix("/") ? recorded : directory.appending(path: manifest.video)
+        guard FileManager.default.fileExists(atPath: videoURL.path) else {
+            throw VideoSegmentationError.parityReferenceInvalid(
+                "manifest.json points at \(videoURL.path), which does not exist.")
+        }
+    }
+
+    func objects(at frame: Int) throws -> [Object] {
+        let prefix = String(format: "frame_%04d", frame)
+        let ids = try load(prefix, "ids").asInt32()
+        guard !ids.isEmpty else { return [] }
+
+        let scores = try load(prefix, "scores").asFloat()
+        let boxesArray = try load(prefix, "boxes")
+        let boxes = boxesArray.asFloat()
+        let masksArray = try load(prefix, "masks")
+        let packed = try masksArray.asUInt8()
+
+        guard scores.count == ids.count, boxes.count == ids.count * 4 else {
+            throw VideoSegmentationError.parityReferenceInvalid(
+                "\(prefix): \(ids.count) ids but \(scores.count) scores and "
+                    + "\(boxes.count / 4) boxes.")
+        }
+        let bytesPerMask = (manifest.width * manifest.height + 7) / 8
+        guard packed.count == ids.count * bytesPerMask else {
+            throw VideoSegmentationError.parityReferenceInvalid(
+                "\(prefix): expected \(ids.count * bytesPerMask) packed mask bytes for "
+                    + "\(manifest.width)×\(manifest.height), got \(packed.count).")
+        }
+
+        return ids.indices.map { index in
+            Object(
+                id: Int(ids[index]),
+                score: scores[index],
+                // xyxy to a rect. `masks_to_boxes` reports inclusive extremes, so the
+                // width here is `x1 - x0`, matching `MaskBitset.boundingBox`.
+                box: CGRect(
+                    x: CGFloat(boxes[index * 4]),
+                    y: CGFloat(boxes[index * 4 + 1]),
+                    width: CGFloat(boxes[index * 4 + 2] - boxes[index * 4]),
+                    height: CGFloat(boxes[index * 4 + 3] - boxes[index * 4 + 1])),
+                mask: MaskBitset(
+                    packedBits: Array(
+                        packed[(index * bytesPerMask)..<((index + 1) * bytesPerMask)]),
+                    width: manifest.width, height: manifest.height))
+        }
+    }
+
+    /// Mask logits at the model's own resolution, ordered like `objects(at:)`.
+    ///
+    /// Present only when the dump included them. Comparing these instead of the final
+    /// binary masks separates a tracker difference from an upsampling difference.
+    func lowResolutionMasks(at frame: Int) -> (values: [Float], side: Int)? {
+        let url = directory.appending(path: String(format: "frame_%04d_lowres.npy", frame))
+        guard let array = try? NpyArray.load(url), array.shape.count == 3 else { return nil }
+        return (array.asFloat(), array.shape[1])
+    }
+
+    private func load(_ prefix: String, _ name: String) throws -> NpyArray {
+        try NpyArray.load(directory.appending(path: "\(prefix)_\(name).npy"))
+    }
+
+    /// The exact frames PyTorch decoded, when the dump included them.
+    ///
+    /// Returning `nil` means falling back to decoding ``videoURL``, which reintroduces
+    /// the decoder difference; the CLI says so when it happens.
+    func decodedFrames() throws -> [CGImage]? {
+        guard let folder = manifest.frameImages else { return nil }
+        let directory = self.directory.appending(path: folder)
+        var images: [CGImage] = []
+        images.reserveCapacity(frameCount)
+        for frame in manifest.frames {
+            let url = directory.appending(path: String(format: "frame_%04d.png", frame))
+            guard let source = CGImageSourceCreateWithURL(url as CFURL, nil),
+                let image = CGImageSourceCreateImageAtIndex(source, 0, nil)
+            else {
+                throw VideoSegmentationError.parityReferenceInvalid(
+                    "manifest.json declares frame images but \(url.lastPathComponent) is "
+                        + "missing or unreadable.")
+            }
+            images.append(image)
+        }
+        return images
+    }
+}
diff --git a/swift/Sources/Tools/video-segmenter/VideoSegmenterMain.swift b/swift/Sources/Tools/video-segmenter/VideoSegmenterMain.swift
new file mode 100644
index 00000000..abfde0e3
--- /dev/null
+++ b/swift/Sources/Tools/video-segmenter/VideoSegmenterMain.swift
@@ -0,0 +1,498 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import ArgumentParser
+import CoreAIShared
+import CoreAIVideoSegmenter
+import CoreGraphics
+import Foundation
+
+@main
+struct VideoSegmenterCLI: AsyncParsableCommand {
+    static let configuration = CommandConfiguration(
+        commandName: "video-segmenter",
+        abstract: "Segment and track objects through a video using text prompts (SAM 3 video)."
+    )
+
+    // MARK: - Options
+
+    @Option(name: .long, help: "Path to the video_segmenter model bundle directory.")
+    var model: String
+
+    @Option(name: .long, help: "Path to the input video (mp4, mov, ...).")
+    var video: String?
+
+    @Option(name: .long, help: "Text prompt describing an object to track. Repeatable.")
+    var prompt: [String] = []
+
+    @Option(name: .long, help: "Output video path. Defaults to <input>_segmented.mp4.")
+    var output: String?
+
+    @Option(name: .long, help: "Stop after this many frames. Default: the whole video.")
+    var maxFrames: Int?
+
+    @Option(name: .long, help: "Write per-frame object ids, scores, and boxes to this JSON path.")
+    var outputJson: String?
+
+    // MARK: - Rendering
+
+    @Option(name: .long, help: "Mask fill opacity, 0–1.")
+    var maskOpacity: Float = 0.5
+
+    @Flag(name: .long, inversion: .prefixedNo, help: "Draw mask-derived bounding boxes.")
+    var boxes: Bool = true
+
+    @Flag(name: .long, inversion: .prefixedNo, help: "Draw '#id prompt score' captions.")
+    var labels: Bool = true
+
+    @Flag(name: .long, help: "Run inference only; skip writing an annotated video.")
+    var noRender: Bool = false
+
+    // MARK: - Tracking overrides
+
+    @Option(name: .long, help: "Detection probability threshold.")
+    var scoreThreshold: Float?
+
+    @Option(
+        name: .long,
+        help: """
+            Mask-IoU threshold for detection NMS. 0 disables it, matching a Python run \
+            without the kernels-community/cv-utils kernel.
+            """)
+    var detNmsThresh: Float?
+
+    @Option(
+        name: .long,
+        help: """
+            Max component area for hole filling and sprinkle removal. 0 disables both, \
+            matching a Python run without the kernels-community/cv-utils kernel.
+            """)
+    var fillHoleArea: Int?
+
+    @Option(name: .long, help: "Frames of output held back by the hotstart heuristics. 0 disables.")
+    var hotstartDelay: Int?
+
+    @Option(name: .long, help: "Recondition every Nth frame. 0 disables reconditioning.")
+    var reconditionEvery: Int?
+
+    // MARK: - Diagnostics
+
+    @Flag(name: .long, help: "Run a warmup pass before the first frame.")
+    var warmup: Bool = false
+
+    @Flag(name: .long, help: "Print per-frame progress and per-entrypoint timing.")
+    var verbose: Bool = false
+
+    @Flag(
+        name: .customLong("clear-coreai-cache"),
+        help: "Clear the Core AI specialization cache for this bundle before loading.")
+    var clearCoreAICache: Bool = false
+
+    @Option(
+        name: .long,
+        help: """
+            Path to a reference directory, in the layout `ParityReference` documents. \
+            Replays the same clip through the Swift stack and reports per-frame agreement \
+            instead of rendering.
+            """)
+    var parity: String?
+
+    @Option(name: .long, help: "Minimum per-frame mask IoU in --parity mode.")
+    var iouFloor: Float = 0.98
+
+    @Option(name: .long, help: "Maximum per-frame score delta in --parity mode.")
+    var scoreTol: Float = 0.02
+
+    @Option(name: .long, help: "Maximum per-frame box delta in pixels, in --parity mode.")
+    var boxTol: Float = 2.0
+
+    // MARK: - Validation
+
+    func validate() throws {
+        if parity == nil {
+            guard video != nil else {
+                throw ValidationError("--video is required (unless --parity is set).")
+            }
+            guard !prompt.isEmpty else {
+                throw ValidationError("At least one --prompt is required.")
+            }
+        }
+        guard (0...1).contains(maskOpacity) else {
+            throw ValidationError("--mask-opacity must be between 0 and 1.")
+        }
+        if let maxFrames, maxFrames <= 0 {
+            throw ValidationError("--max-frames must be positive.")
+        }
+    }
+
+    // MARK: - Run
+
+    func run() async throws {
+        if verbose { CLILogger.level = 1 }
+
+        if clearCoreAICache {
+            let cleared = try PreparedModel.clearCache(at: URL(fileURLWithPath: model))
+            print("Cleared the specialization cache for \(cleared.count) asset(s).")
+        }
+
+        let segmenter = try await VideoSegmenter(resourcesAt: model, parameters: overrides())
+
+        print("Preparing asset...", terminator: "")
+        fflush(stdout)
+        let loadStart = ContinuousClock.now
+        try await segmenter.loadResources()
+        print(" done in \(format(ContinuousClock.now - loadStart))")
+
+        if warmup {
+            print("Warming up...", terminator: "")
+            fflush(stdout)
+            let warmupStart = ContinuousClock.now
+            try await segmenter.warmup()
+            print(" done in \(format(ContinuousClock.now - warmupStart))")
+        }
+
+        if let parityDirectory = parity {
+            try await runParity(segmenter: segmenter, directory: URL(fileURLWithPath: parityDirectory))
+            return
+        }
+        try await runSegmentation(segmenter: segmenter)
+    }
+
+    /// Parameters assembled from the flags. Anything left `nil` keeps the bundle's value.
+    private func overrides() -> VideoSegmentationParameters {
+        var parameters = VideoSegmentationParameters.default
+        scoreThreshold.map { parameters.scoreThresholdDetection = $0 }
+        detNmsThresh.map { parameters.detNmsThresh = $0 }
+        fillHoleArea.map { parameters.fillHoleArea = $0 }
+        hotstartDelay.map { parameters.hotstartDelay = $0 }
+        reconditionEvery.map { parameters.reconditionEveryNthFrame = $0 }
+        parameters.maskOpacity = maskOpacity
+        parameters.drawBoxes = boxes
+        parameters.drawLabels = labels
+        return parameters
+    }
+
+    // MARK: - Segmentation
+
+    private func runSegmentation(segmenter: VideoSegmenter) async throws {
+        let sourceURL = URL(fileURLWithPath: expand(video!))
+        guard FileManager.default.fileExists(atPath: sourceURL.path) else {
+            throw ValidationError("No video at \(sourceURL.path)")
+        }
+        let metadata = try await SequentialVideoReader.metadata(of: sourceURL)
+        let expected = min(metadata.estimatedFrameCount, maxFrames ?? .max)
+        print(
+            "Video: \(metadata.width)×\(metadata.height), "
+                + "\(String(format: "%.2f", metadata.nominalFrameRate)) fps, ~\(expected) frames")
+        print("Prompts: \(prompt.joined(separator: ", "))")
+
+        let collector = FrameCollector()
+        let started = ContinuousClock.now
+
+        if noRender {
+            for try await frame in segmenter.segment(
+                videoAt: sourceURL, prompts: prompt, maxFrames: maxFrames)
+            {
+                await collector.record(frame, verbose: verbose)
+            }
+        } else {
+            let destination = URL(fileURLWithPath: expand(output ?? defaultOutputPath(for: sourceURL)))
+            let verbose = self.verbose
+            _ = try await segmenter.renderAnnotatedVideo(
+                from: sourceURL, prompts: prompt, to: destination, maxFrames: maxFrames,
+                onFrame: { frame in
+                    await collector.record(frame, verbose: verbose)
+                })
+            print("Wrote \(destination.path)")
+        }
+
+        let elapsed = ContinuousClock.now - started
+        let records = await collector.records
+        print("")
+        print("Segmented \(records.count) frames in \(format(elapsed))", terminator: "")
+        if !records.isEmpty {
+            let perFrame = elapsed.inSeconds / Double(records.count)
+            print(" (\(String(format: "%.0f", perFrame * 1000)) ms/frame)")
+        } else {
+            print("")
+        }
+        printTimings(await segmenter.lastRunTimings, frames: records.count)
+        printTrackSummary(records)
+
+        if let jsonPath = outputJson {
+            let encoder = JSONEncoder()
+            encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+            try encoder.encode(records).write(
+                to: URL(fileURLWithPath: expand(jsonPath)))
+            print("Wrote \(expand(jsonPath))")
+        }
+    }
+
+    private func defaultOutputPath(for source: URL) -> String {
+        source.deletingPathExtension().lastPathComponent + "_segmented.mp4"
+    }
+
+    private func printTimings(_ timings: [String: Double], frames: Int) {
+        guard !timings.isEmpty, frames > 0 else { return }
+        print("")
+        print("  \(pad("entrypoint", 20))\(rpad("total", 10))\(rpad("per frame", 12))")
+        print("  " + String(repeating: "-", count: 42))
+        for (name, seconds) in timings.sorted(by: { $0.value > $1.value }) {
+            print(
+                "  " + pad(name, 20)
+                    + rpad(String(format: "%.2fs", seconds), 10)
+                    + rpad(String(format: "%.0f ms", seconds / Double(frames) * 1000), 12))
+        }
+        let total = timings.values.reduce(0, +)
+        print(
+            "  " + pad("total in Core AI", 20)
+                + rpad(String(format: "%.2fs", total), 10)
+                + rpad(String(format: "%.0f ms", total / Double(frames) * 1000), 12))
+    }
+
+    private func printTrackSummary(_ records: [FrameRecord]) {
+        var frameCount: [Int: Int] = [:]
+        var prompts: [Int: String] = [:]
+        for record in records {
+            for object in record.objects {
+                frameCount[object.id, default: 0] += 1
+                prompts[object.id] = object.prompt
+            }
+        }
+        guard !frameCount.isEmpty else {
+            print("\nNo objects tracked. Try a lower --score-threshold or a different prompt.")
+            return
+        }
+        print("")
+        print("  \(pad("track", 8))\(pad("prompt", 20))\(rpad("frames", 8))")
+        print("  " + String(repeating: "-", count: 36))
+        for id in frameCount.keys.sorted() {
+            print(
+                "  " + pad("#\(id)", 8) + pad(prompts[id] ?? "", 20)
+                    + rpad("\(frameCount[id]!)", 8))
+        }
+    }
+
+    // MARK: - Parity
+
+    /// Compare against a ``ParityReference`` dump.
+    private func runParity(segmenter: VideoSegmenter, directory: URL) async throws {
+        let reference = try ParityReference(directory: directory)
+        print(
+            "Parity reference: \(reference.frameCount) frames, prompts "
+                + "\(reference.prompts.joined(separator: ", "))")
+
+        var results: [Int: [TrackedObject]] = [:]
+        var lowResolution: [Int: [[Float]]] = [:]
+        // Ask for the pre-upsample logits when the reference has them, so a disagreement
+        // can be attributed to the tracker or to the upsample rather than guessed at.
+        var parityParameters = await segmenter.parameters
+        parityParameters.emitLowResolutionMasks =
+            reference.lowResolutionMasks(at: reference.frameIndices[0]) != nil
+        scoreThreshold.map { parityParameters.scoreThresholdDetection = $0 }
+        detNmsThresh.map { parityParameters.detNmsThresh = $0 }
+        fillHoleArea.map { parityParameters.fillHoleArea = $0 }
+        hotstartDelay.map { parityParameters.hotstartDelay = $0 }
+        reconditionEvery.map { parityParameters.reconditionEveryNthFrame = $0 }
+        // Prefer the frames PyTorch itself decoded. Without them both stacks decode the
+        // same file with different libraries, and the resulting colour difference of
+        // roughly 0.65 code values on tagged media shows up as a mask difference that
+        // has nothing to do with this port.
+        if let frames = try reference.decodedFrames() {
+            print("Frames: \(frames.count) PNGs from the reference (decoder held constant)")
+            for try await frame in segmenter.segment(
+                frames: frames, prompts: reference.prompts, parameters: parityParameters)
+            {
+                results[frame.frameIndex] = frame.objects
+                lowResolution[frame.frameIndex] = frame.lowResolutionMasks
+            }
+        } else {
+            print("Frames: decoding \(reference.videoURL.path) with AVFoundation")
+            print(
+                "  NOTE: the reference has no frames/ directory, so decoder differences are\n"
+                    + "  folded into the numbers below. Re-dump with one to remove them.")
+            for try await frame in segmenter.segment(
+                videoAt: reference.videoURL, prompts: reference.prompts,
+                maxFrames: reference.frameCount, parameters: parityParameters)
+            {
+                results[frame.frameIndex] = frame.objects
+                lowResolution[frame.frameIndex] = frame.lowResolutionMasks
+            }
+        }
+
+        print("")
+        print(
+            "\(rpad("frame", 6)) \(rpad("objs", 6)) \(rpad("ids", 5)) \(rpad("min IoU", 9)) "
+                + "\(rpad("max dScore", 11)) \(rpad("max dBox", 9)) \(rpad("lowres", 9))   result")
+        print(String(repeating: "-", count: 72))
+
+        var failures = 0
+        var worstLowResDelta: Float = 0
+        for frameIndex in reference.frameIndices {
+            let expected = try reference.objects(at: frameIndex)
+            let actual = results[frameIndex] ?? []
+            let comparison = compare(expected: expected, actual: actual)
+            let ok =
+                comparison.idsMatch && comparison.minIoU >= iouFloor
+                && comparison.maxScoreDelta <= scoreTol && comparison.maxBoxDelta <= boxTol
+            if !ok { failures += 1 }
+            // Max absolute logit difference before the upsample, when both sides have it.
+            var lowResColumn = "-"
+            if let referenceLowRes = reference.lowResolutionMasks(at: frameIndex),
+                let actualLowRes = lowResolution[frameIndex], !actualLowRes.isEmpty
+            {
+                let flat = actualLowRes.flatMap { $0 }
+                if flat.count == referenceLowRes.values.count {
+                    var worst: Float = 0
+                    for index in flat.indices {
+                        worst = max(worst, abs(flat[index] - referenceLowRes.values[index]))
+                    }
+                    worstLowResDelta = max(worstLowResDelta, worst)
+                    lowResColumn = String(format: "%.4f", worst)
+                } else {
+                    lowResColumn = "n/a"
+                }
+            }
+            print(
+                rpad("\(frameIndex)", 6) + " "
+                    + rpad("\(expected.count)/\(actual.count)", 6) + " "
+                    + rpad(comparison.idsMatch ? "ok" : "DIFF", 5) + " "
+                    + rpad(String(format: "%.4f", comparison.minIoU), 9) + " "
+                    + rpad(String(format: "%.4f", comparison.maxScoreDelta), 11) + " "
+                    + rpad(String(format: "%.1f", comparison.maxBoxDelta), 9) + " "
+                    + rpad(lowResColumn, 9) + "   "
+                    + (ok ? "ok" : "FAIL"))
+        }
+
+        print(String(repeating: "-", count: 72))
+        if worstLowResDelta > 0 {
+            // The `lowres` column is the honest measure of the port. The final masks add
+            // an upsample and a threshold on top, and a logit near zero crosses that
+            // threshold on an arbitrarily small difference, which is why a frame can
+            // show a large box delta at a tiny logit delta.
+            print(
+                "Worst mask-logit difference before upsampling: "
+                    + String(format: "%.4f", worstLowResDelta))
+        }
+        if failures == 0 {
+            print(
+                "All \(reference.frameCount) frames within tolerance "
+                    + "(IoU ≥ \(iouFloor), dScore ≤ \(scoreTol), dBox ≤ \(boxTol)).")
+            return
+        }
+        print("\(failures) of \(reference.frameCount) frames outside tolerance.")
+        if detNmsThresh != 0 || fillHoleArea != 0 {
+            // The single most common cause of a spurious parity failure.
+            print(
+                "Note: the Python reference no-ops NMS and hole filling when "
+                    + "kernels-community/cv-utils is not installed. If that was the case, rerun "
+                    + "with --det-nms-thresh 0 --fill-hole-area 0.")
+        }
+        throw ExitCode.failure
+    }
+
+    private struct Comparison {
+        var idsMatch = false
+        var minIoU: Float = 1
+        var maxScoreDelta: Float = 0
+        var maxBoxDelta: Float = 0
+    }
+
+    private func compare(
+        expected: [ParityReference.Object], actual: [TrackedObject]
+    ) -> Comparison {
+        var comparison = Comparison()
+        comparison.idsMatch = expected.map(\.id) == actual.map(\.id).sorted()
+        guard comparison.idsMatch else {
+            comparison.minIoU = 0
+            return comparison
+        }
+        let byID = Dictionary(uniqueKeysWithValues: actual.map { ($0.id, $0) })
+        for reference in expected {
+            guard let got = byID[reference.id] else {
+                comparison.minIoU = 0
+                continue
+            }
+            comparison.minIoU = min(comparison.minIoU, reference.mask.iou(got.mask))
+            comparison.maxScoreDelta = max(
+                comparison.maxScoreDelta, abs(reference.score - got.score))
+            comparison.maxBoxDelta = max(
+                comparison.maxBoxDelta,
+                Float(
+                    max(
+                        abs(reference.box.minX - got.box.minX),
+                        abs(reference.box.minY - got.box.minY),
+                        abs(reference.box.maxX - got.box.maxX),
+                        abs(reference.box.maxY - got.box.maxY))))
+        }
+        return comparison
+    }
+
+    // MARK: - Formatting
+
+    private func expand(_ path: String) -> String { (path as NSString).expandingTildeInPath }
+
+    private func format(_ duration: Duration) -> String {
+        String(format: "%.2fs", duration.inSeconds)
+    }
+
+    private func pad(_ text: String, _ width: Int) -> String {
+        text.count >= width ? text : text + String(repeating: " ", count: width - text.count)
+    }
+
+    private func rpad(_ text: String, _ width: Int) -> String {
+        text.count >= width ? text : String(repeating: " ", count: width - text.count) + text
+    }
+}
+
+// MARK: - JSON records
+
+struct FrameRecord: Encodable, Sendable {
+    struct Object: Encodable, Sendable {
+        let id: Int
+        let prompt: String
+        let score: Float
+        let trackerScore: Float
+        let box: [Double]
+        let maskPixels: Int
+    }
+    let frameIndex: Int
+    let objects: [Object]
+    /// Wall clock spent on this frame, in milliseconds.
+    let processingMs: Double
+}
+
+/// Accumulates per-frame records off the render loop's hot path.
+actor FrameCollector {
+    private(set) var records: [FrameRecord] = []
+    private var totalProcessing: Duration = .zero
+
+    func record(_ frame: VideoSegmentationFrame, verbose: Bool) {
+        let objects = frame.objects.map {
+            FrameRecord.Object(
+                id: $0.id, prompt: $0.prompt, score: $0.score, trackerScore: $0.trackerScore,
+                box: [$0.box.minX, $0.box.minY, $0.box.maxX, $0.box.maxY],
+                maskPixels: $0.mask.area)
+        }
+        records.append(
+            FrameRecord(
+                frameIndex: frame.frameIndex, objects: objects,
+                processingMs: frame.processingTime.inSeconds * 1000))
+        totalProcessing += frame.processingTime
+
+        if verbose {
+            let ids = objects.map { "#\($0.id)" }.joined(separator: " ")
+            // This frame's own time, then the running total of those times, not wall
+            // clock. `segment()` yields into an unbounded stream buffer, so the frame loop
+            // can run ahead of this consumer and a timestamp taken here would say when the
+            // result was collected rather than when it was computed.
+            print(
+                "  frame \(frame.frameIndex): \(objects.count) object(s) \(ids)"
+                    .padding(toLength: 46, withPad: " ", startingAt: 0)
+                    + String(format: "%7.0f ms", frame.processingTime.inSeconds * 1000)
+                    + String(format: "   %7.1fs cumulative", totalProcessing.inSeconds))
+        }
+    }
+}
diff --git a/swift/Tests/CoreAISharedTests/NDArrayHelpersTests.swift b/swift/Tests/CoreAISharedTests/NDArrayHelpersTests.swift
index 6d34559c..80979eab 100644
--- a/swift/Tests/CoreAISharedTests/NDArrayHelpersTests.swift
+++ b/swift/Tests/CoreAISharedTests/NDArrayHelpersTests.swift
@@ -220,3 +220,85 @@ struct StrideAwareFillReadTests {
         #expect(readNDArray(array, as: Float.self, count: count) == values)
     }
 }
+
+// MARK: - copyIntoNDArray / clearNDArrayRegion
+
+/// Both of `copyIntoNDArray`'s paths need pinning: the contiguous `memcpy` and the stride
+/// walk that runs when the array is padded for hardware alignment.
+@Suite("copyIntoNDArray")
+struct CopyIntoNDArrayTests {
+    @Test("Writes at an offset without disturbing its neighbours")
+    func writesAtOffset() {
+        var array = NDArray(shape: [4, 8], scalarType: .float32)
+        fillNDArray(&array, as: Float.self, with: [Float](repeating: -1, count: 32))
+
+        copyIntoNDArray(
+            &array, as: Float.self, elementOffset: 8, from: (0..<8).map { Float($0) })
+
+        let read = readNDArray(array, as: Float.self, count: 32)
+        #expect(Array(read[0..<8]) == [Float](repeating: -1, count: 8))
+        #expect(Array(read[8..<16]) == (0..<8).map { Float($0) })
+        #expect(Array(read[16..<32]) == [Float](repeating: -1, count: 16))
+    }
+
+    @Test("Round-trips a slot layout the memory bank would use")
+    func slotLayout() {
+        // Same shape family as `spatial_memory`: [slots, tokens, 1, dim]. Each slot is
+        // written independently and must come back independently.
+        let slots = 3
+        let tokens = 5
+        let dim = 4
+        let perSlot = tokens * dim
+        var array = NDArray(shape: [slots, tokens, 1, dim], scalarType: .float32)
+        for slot in 0..<slots {
+            let payload = (0..<perSlot).map { Float(slot * 100 + $0) }
+            copyIntoNDArray(
+                &array, as: Float.self, elementOffset: slot * perSlot, from: payload)
+        }
+        let read = readNDArray(array, as: Float.self, count: slots * perSlot)
+        for slot in 0..<slots {
+            let got = Array(read[(slot * perSlot)..<((slot + 1) * perSlot)])
+            #expect(got == (0..<perSlot).map { Float(slot * 100 + $0) }, "slot \(slot)")
+        }
+    }
+
+    @Test("Survives a small innermost dimension, where padding is likely")
+    func smallInnermostDimension() {
+        // A 4-element innermost dimension is where the framework's preferred strides are
+        // most likely to be padded, exercising the non-contiguous fallback.
+        var array = NDArray(shape: [64, 4], scalarType: .float32)
+        let payload = (0..<256).map { Float($0) * 0.5 }
+        copyIntoNDArray(&array, as: Float.self, elementOffset: 0, from: payload)
+        #expect(readNDArray(array, as: Float.self, count: 256) == payload)
+    }
+
+    @Test("An empty source is a no-op")
+    func emptySource() {
+        var array = NDArray(shape: [2, 4], scalarType: .float32)
+        fillNDArray(&array, as: Float.self, with: [Float](repeating: 7, count: 8))
+        copyIntoNDArray(&array, as: Float.self, elementOffset: 4, from: [Float]())
+        #expect(readNDArray(array, as: Float.self, count: 8) == [Float](repeating: 7, count: 8))
+    }
+
+    @Test("clearNDArrayRegion zeroes exactly the requested range")
+    func clearsRange() {
+        // This is how the packer wipes slots that were valid on the previous call and are
+        // not on this one. Over-clearing would destroy live memory in a lower slot.
+        var array = NDArray(shape: [4, 4], scalarType: .float32)
+        fillNDArray(&array, as: Float.self, with: (0..<16).map { Float($0 + 1) })
+        clearNDArrayRegion(&array, as: Float.self, elementRange: 4..<12, value: 0)
+
+        let read = readNDArray(array, as: Float.self, count: 16)
+        #expect(Array(read[0..<4]) == [1, 2, 3, 4])
+        #expect(Array(read[4..<12]) == [Float](repeating: 0, count: 8))
+        #expect(Array(read[12..<16]) == [13, 14, 15, 16])
+    }
+
+    @Test("Clearing an empty range does nothing")
+    func clearEmptyRange() {
+        var array = NDArray(shape: [2, 2], scalarType: .float32)
+        fillNDArray(&array, as: Float.self, with: [1, 2, 3, 4] as [Float])
+        clearNDArrayRegion(&array, as: Float.self, elementRange: 2..<2, value: 0)
+        #expect(readNDArray(array, as: Float.self, count: 4) == [1, 2, 3, 4] as [Float])
+    }
+}
diff --git a/swift/Tests/VideoSegmenterTests/AssociationTests.swift b/swift/Tests/VideoSegmenterTests/AssociationTests.swift
new file mode 100644
index 00000000..95b894b3
--- /dev/null
+++ b/swift/Tests/VideoSegmenterTests/AssociationTests.swift
@@ -0,0 +1,204 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import Testing
+
+@testable import CoreAIShared
+@testable import CoreAIVideoSegmenter
+
+@Suite("Associator")
+struct AssociatorTests {
+    /// A 10x10 mask covering `columns` of every row, so IoU between two of these is a
+    /// straightforward column overlap.
+    private func stripe(_ columns: Range<Int>) -> MaskBitset {
+        var mask = MaskBitset(width: 10, height: 10)
+        for y in 0..<10 {
+            for x in columns { mask[x, y] = true }
+        }
+        return mask
+    }
+
+    private func detections(
+        _ entries: [(mask: MaskBitset, score: Float, prompt: Int)]
+    ) -> MergedDetections {
+        var merged = MergedDetections()
+        for entry in entries {
+            merged.masks.append(entry.mask)
+            merged.maskLogits.append([])
+            merged.scores.append(entry.score)
+            merged.promptIDs.append(entry.prompt)
+        }
+        return merged
+    }
+
+    @Test("With no tracks, every detection is new regardless of score")
+    func firstFrame() {
+        // The empty-tracks branch skips the `newDetThresh` gate entirely, which is how the
+        // first frame seeds tracks from detections that clear the detection threshold but
+        // not the stricter new-object one.
+        var parameters = VideoSegmentationParameters.default
+        parameters.newDetThresh = 0.9
+        let result = Associator.associate(
+            detections: detections([(stripe(0..<5), 0.55, 0), (stripe(5..<10), 0.60, 0)]),
+            trackMasks: [], trackIDs: [], trackPromptIDs: [], parameters: parameters)
+        #expect(result.newDetectionIndices == [0, 1])
+    }
+
+    @Test("With no detections, non-empty tracks are unmatched and empty ones are not")
+    func noDetections() {
+        // The distinction drives keep-alive: an occluded track should not be penalised the
+        // way a track the detector stopped confirming is.
+        let result = Associator.associate(
+            detections: MergedDetections(),
+            trackMasks: [stripe(0..<5), MaskBitset(width: 10, height: 10)],
+            trackIDs: [1, 2], trackPromptIDs: [0, 0],
+            parameters: .default)
+        #expect(result.unmatchedTrackIDs == [1])
+        #expect(result.emptyTrackIDs == [2])
+    }
+
+    @Test("A detection covered by a track is not new")
+    func coveredDetectionIsNotNew() {
+        let result = Associator.associate(
+            detections: detections([(stripe(0..<5), 0.95, 0)]),
+            trackMasks: [stripe(0..<5)], trackIDs: [1], trackPromptIDs: [0],
+            parameters: .default)
+        #expect(result.newDetectionIndices.isEmpty)
+        #expect(result.detectionToMatchedTrackIDs[0] == [1])
+        #expect(result.unmatchedTrackIDs.isEmpty)
+    }
+
+    @Test("The loose and strict thresholds disagree independently")
+    func twoThresholds() {
+        // 2 of 10 columns shared: IoU is 2/8 = 0.25. Above the loose 0.1 association
+        // threshold, so the detection is not new; below the strict 0.5 track threshold, so
+        // the track still counts as unmatched. Both at once is the intended behaviour.
+        let result = Associator.associate(
+            detections: detections([(stripe(0..<4), 0.95, 0)]),
+            trackMasks: [stripe(2..<6)], trackIDs: [1], trackPromptIDs: [0],
+            parameters: .default)
+        #expect(result.newDetectionIndices.isEmpty)
+        #expect(result.unmatchedTrackIDs == [1])
+    }
+
+    @Test("Detections never associate across prompt groups")
+    func crossPromptZeroed() {
+        // Identical masks, different prompts. Without the IoU zeroing the "dog" detection
+        // would be swallowed by the "person" track and never become its own object.
+        let result = Associator.associate(
+            detections: detections([(stripe(0..<5), 0.95, 1)]),
+            trackMasks: [stripe(0..<5)], trackIDs: [1], trackPromptIDs: [0],
+            parameters: .default)
+        #expect(result.newDetectionIndices == [0])
+        #expect(result.detectionToMatchedTrackIDs[0] == [])
+        #expect(result.unmatchedTrackIDs == [1])
+    }
+
+    @Test("A confident, well-overlapping detection becomes a reconditioning candidate")
+    func reconditioningCandidate() {
+        let result = Associator.associate(
+            detections: detections([(stripe(0..<5), 0.95, 0)]),
+            trackMasks: [stripe(0..<5)], trackIDs: [7], trackPromptIDs: [0],
+            parameters: .default)
+        #expect(result.trackIDToHighConfidenceDetection[7] == 0)
+    }
+
+    @Test("A new detection is never also a reconditioning candidate")
+    func newDetectionsExcluded() {
+        // `det_is_high_conf` is explicitly `& ~is_new_det` upstream: a detection cannot
+        // both create a track and correct a different one.
+        let result = Associator.associate(
+            detections: detections([(stripe(0..<5), 0.99, 0)]),
+            trackMasks: [stripe(8..<10)], trackIDs: [7], trackPromptIDs: [0],
+            parameters: .default)
+        #expect(result.newDetectionIndices == [0])
+        #expect(result.trackIDToHighConfidenceDetection.isEmpty)
+    }
+
+    @Test("One detection can match several tracks, which is how duplicates are spotted")
+    func manyToOne() {
+        let result = Associator.associate(
+            detections: detections([(stripe(0..<10), 0.95, 0)]),
+            trackMasks: [stripe(0..<5), stripe(5..<10)], trackIDs: [1, 2],
+            trackPromptIDs: [0, 0], parameters: .default)
+        #expect(result.detectionToMatchedTrackIDs[0] == [1, 2])
+    }
+}
+
+@Suite("OcclusionSuppressor")
+struct OcclusionSuppressorTests {
+    @Test("An object that loses most of its area to the argmax is blanked")
+    func areaShrinkage() {
+        // Object 1 is entirely inside object 0 and loses everywhere, so its retained
+        // fraction is 0, below the 0.3 threshold. Object 0 keeps all four pixels.
+        var logits: [[Float]] = [
+            [5, 5, 5, 5],
+            [1, 1, 1, 1],
+        ]
+        OcclusionSuppressor.suppressAreaShrinkage(logits: &logits, promptIDs: [0, 0])
+        #expect(logits[0] == [5, 5, 5, 5])
+        #expect(logits[1].allSatisfy { $0 <= OcclusionSuppressor.noObjectLogit })
+    }
+
+    @Test("An object that keeps enough area survives intact")
+    func areaShrinkageSpares() {
+        // Object 1 wins three of its four pixels, a 0.75 retention.
+        var logits: [[Float]] = [
+            [5, 1, 1, 1],
+            [1, 5, 5, 5],
+        ]
+        OcclusionSuppressor.suppressAreaShrinkage(logits: &logits, promptIDs: [0, 0])
+        #expect(logits[1] == [1, 5, 5, 5])
+    }
+
+    @Test("The rule is applied inside a prompt group, never across")
+    func areaShrinkagePerPrompt() {
+        var logits: [[Float]] = [
+            [5, 5, 5, 5],
+            [1, 1, 1, 1],
+        ]
+        OcclusionSuppressor.suppressAreaShrinkage(logits: &logits, promptIDs: [0, 1])
+        #expect(logits[1] == [1, 1, 1, 1])
+    }
+
+    @Test("Contested pixels go to the highest-scoring object in the group")
+    func nonOverlap() {
+        var masks = [MaskBitset(width: 4, height: 1), MaskBitset(width: 4, height: 1)]
+        for x in 0..<3 { masks[0][x, 0] = true }
+        for x in 1..<4 { masks[1][x, 0] = true }
+        OcclusionSuppressor.applyObjectWiseNonOverlap(
+            masks: &masks, scores: [0.9, 0.4], promptIDs: [0, 0])
+        #expect(masks[0].area == 3)
+        #expect(masks[1].area == 1)
+        #expect(masks[1][3, 0] == true)
+    }
+
+    @Test("Two prompts may claim the same pixels")
+    func nonOverlapPerPrompt() {
+        var masks = [MaskBitset(width: 4, height: 1), MaskBitset(width: 4, height: 1)]
+        for x in 0..<4 {
+            masks[0][x, 0] = true
+            masks[1][x, 0] = true
+        }
+        OcclusionSuppressor.applyObjectWiseNonOverlap(
+            masks: &masks, scores: [0.9, 0.4], promptIDs: [0, 1])
+        #expect(masks[0].area == 4)
+        #expect(masks[1].area == 4)
+    }
+
+    @Test("A zero-scored object loses even its uncontested pixels")
+    func zeroScoreLosesEverything() {
+        // Upstream tests `pixel_nonoverlap > 0` on a field built from the object's own
+        // score, so a score of exactly 0 fails the test everywhere. Surprising, but it is
+        // the behaviour, and a track only reaches 0 when it has no recorded score at all.
+        var masks = [MaskBitset(width: 4, height: 1), MaskBitset(width: 4, height: 1)]
+        masks[0][0, 0] = true
+        masks[1][3, 0] = true
+        OcclusionSuppressor.applyObjectWiseNonOverlap(
+            masks: &masks, scores: [0.9, 0.0], promptIDs: [0, 0])
+        #expect(masks[0].area == 1)
+        #expect(masks[1].area == 0)
+    }
+}
diff --git a/swift/Tests/VideoSegmenterTests/BilinearResamplerTests.swift b/swift/Tests/VideoSegmenterTests/BilinearResamplerTests.swift
new file mode 100644
index 00000000..424c1269
--- /dev/null
+++ b/swift/Tests/VideoSegmenterTests/BilinearResamplerTests.swift
@@ -0,0 +1,160 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import Testing
+
+@testable import CoreAIShared
+
+/// Every expectation here is a literal captured from
+/// `torch.nn.functional.interpolate(..., mode="bilinear", align_corners=False)`, not from
+/// this implementation. These resizes sit between graph calls in the tracker and the
+/// resampled mask is what conditions every later frame, so "looks about right" is not
+/// good enough.
+@Suite("BilinearResampler")
+struct BilinearResamplerTests {
+    /// `torch.arange(16).reshape(4, 4)`.
+    private let ramp4 = (0..<16).map(Float.init)
+    /// `torch.arange(64).reshape(8, 8)`.
+    private let ramp8 = (0..<64).map(Float.init)
+
+    private func expectClose(
+        _ actual: [Float], _ expected: [Float], tolerance: Float = 1e-5,
+        sourceLocation: SourceLocation = #_sourceLocation
+    ) {
+        #expect(actual.count == expected.count, sourceLocation: sourceLocation)
+        guard actual.count == expected.count else { return }
+        for index in actual.indices {
+            #expect(
+                abs(actual[index] - expected[index]) <= tolerance,
+                "element \(index): \(actual[index]) vs \(expected[index])",
+                sourceLocation: sourceLocation)
+        }
+    }
+
+    @Test("4x4 to 8x8 matches torch bilinear")
+    func upsample() {
+        let resampler = BilinearResampler(
+            sourceWidth: 4, sourceHeight: 4, destinationWidth: 8, destinationHeight: 8)
+        expectClose(
+            resampler.resample(ramp4),
+            [
+                0.00, 0.25, 0.75, 1.25, 1.75, 2.25, 2.75, 3.00,
+                1.00, 1.25, 1.75, 2.25, 2.75, 3.25, 3.75, 4.00,
+                3.00, 3.25, 3.75, 4.25, 4.75, 5.25, 5.75, 6.00,
+                5.00, 5.25, 5.75, 6.25, 6.75, 7.25, 7.75, 8.00,
+                7.00, 7.25, 7.75, 8.25, 8.75, 9.25, 9.75, 10.00,
+                9.00, 9.25, 9.75, 10.25, 10.75, 11.25, 11.75, 12.00,
+                11.00, 11.25, 11.75, 12.25, 12.75, 13.25, 13.75, 14.00,
+                12.00, 12.25, 12.75, 13.25, 13.75, 14.25, 14.75, 15.00,
+            ])
+    }
+
+    @Test("Antialiasing is a no-op when upsampling")
+    func antialiasIgnoredWhenUpsampling() {
+        // This is the fact the export relies on: three of its four resizes are upsamples,
+        // so dropping `antialias=True`, which has no Core AI lowering, changes nothing.
+        // Torch's antialiased path widens to three taps here, but the third weight is
+        // exactly zero.
+        let plain = BilinearResampler(
+            sourceWidth: 4, sourceHeight: 4, destinationWidth: 8, destinationHeight: 8,
+            antialias: false)
+        let antialiased = BilinearResampler(
+            sourceWidth: 4, sourceHeight: 4, destinationWidth: 8, destinationHeight: 8,
+            antialias: true)
+        expectClose(antialiased.resample(ramp4), plain.resample(ramp4), tolerance: 0)
+    }
+
+    @Test("4x4 to 2x2 without antialiasing matches torch")
+    func downsamplePlain() {
+        let resampler = BilinearResampler(
+            sourceWidth: 4, sourceHeight: 4, destinationWidth: 2, destinationHeight: 2,
+            antialias: false)
+        expectClose(resampler.resample(ramp4), [2.5, 4.5, 10.5, 12.5])
+    }
+
+    @Test("4x4 to 2x2 with antialiasing matches torch, and differs from plain")
+    func downsampleAntialiased() {
+        let resampler = BilinearResampler(
+            sourceWidth: 4, sourceHeight: 4, destinationWidth: 2, destinationHeight: 2,
+            antialias: true)
+        // Meaningfully different from the plain result above. This is the difference the
+        // export moved to the host rather than approximating away.
+        expectClose(
+            resampler.resample(ramp4),
+            [3.571429, 5.142858, 9.857143, 11.428572])
+    }
+
+    @Test("8x8 to 3x3 matches torch, both with and without antialiasing")
+    func nonIntegerDownsample() {
+        // A 2.667x ratio, so the antialiased support is fractional and the tap count is
+        // the `ceil(support) * 2 + 1` that torch computes.
+        let antialiased = BilinearResampler(
+            sourceWidth: 8, sourceHeight: 8, destinationWidth: 3, destinationHeight: 3,
+            antialias: true)
+        expectClose(
+            antialiased.resample(ramp8),
+            [
+                9.947369, 12.342107, 14.736842,
+                29.105265, 31.500002, 33.894737,
+                48.263161, 50.657898, 53.052635,
+            ])
+
+        let plain = BilinearResampler(
+            sourceWidth: 8, sourceHeight: 8, destinationWidth: 3, destinationHeight: 3,
+            antialias: false)
+        expectClose(
+            plain.resample(ramp8),
+            [
+                7.500000, 10.166667, 12.833335,
+                28.833332, 31.500000, 34.166668,
+                50.166672, 52.833336, 55.500008,
+            ])
+    }
+
+    @Test("Non-square resizes use independent row and column tables")
+    func nonSquare() {
+        // 3x4 to 5x6 scales differently on each axis; a shared weight table would be
+        // wrong on one of them and this ramp would show it.
+        let resampler = BilinearResampler(
+            sourceWidth: 4, sourceHeight: 3, destinationWidth: 6, destinationHeight: 5)
+        expectClose(
+            resampler.resample((0..<12).map(Float.init)),
+            [
+                0.000000, 0.500000, 1.166667, 1.833333, 2.500000, 3.000000,
+                1.600000, 2.100000, 2.766667, 3.433333, 4.100000, 4.600000,
+                4.000000, 4.500000, 5.166667, 5.833333, 6.500000, 7.000000,
+                6.400001, 6.900001, 7.566667, 8.233334, 8.900001, 9.400001,
+                8.000000, 8.500000, 9.166667, 9.833334, 10.500000, 11.000000,
+            ])
+    }
+
+    @Test("A same-size resample is the identity")
+    func identity() {
+        let resampler = BilinearResampler(
+            sourceWidth: 4, sourceHeight: 4, destinationWidth: 4, destinationHeight: 4)
+        #expect(resampler.isIdentity)
+        expectClose(resampler.resample(ramp4), ramp4, tolerance: 0)
+    }
+
+    @Test("A constant field stays constant, so the weights sum to one everywhere")
+    func partitionOfUnity() {
+        // Weights that do not sum to 1 would darken or brighten a flat region, which on a
+        // mask logit field shifts the binarization threshold.
+        for antialias in [false, true] {
+            for (source, destination) in [(4, 9), (9, 4), (16, 5), (5, 16), (7, 7)] {
+                let resampler = BilinearResampler(
+                    sourceWidth: source, sourceHeight: source,
+                    destinationWidth: destination, destinationHeight: destination,
+                    antialias: antialias)
+                let flat = [Float](repeating: 2.5, count: source * source)
+                for value in resampler.resample(flat) {
+                    #expect(
+                        abs(value - 2.5) < 1e-5,
+                        "antialias=\(antialias) \(source)->\(destination) gave \(value)")
+                }
+            }
+        }
+    }
+}
diff --git a/swift/Tests/VideoSegmenterTests/FramePreprocessingTests.swift b/swift/Tests/VideoSegmenterTests/FramePreprocessingTests.swift
new file mode 100644
index 00000000..0e846c2d
--- /dev/null
+++ b/swift/Tests/VideoSegmenterTests/FramePreprocessingTests.swift
@@ -0,0 +1,122 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import Foundation
+import Testing
+
+@testable import CoreAIShared
+@testable import CoreAIVideoSegmenter
+
+/// Checks `FramePreprocessor` against literals captured from PyTorch.
+///
+/// Self-contained on purpose. An earlier version read `.npy` dumps from a path given by an
+/// environment variable, which meant it silently skipped on every machine that didn't have
+/// them, which is coverage in name only.
+@Suite("Frame preprocessing")
+struct FramePreprocessingTests {
+    /// A 4-wide by 3-high interleaved RGB image. Values chosen so the resize lands on
+    /// fractional samples and the rounding step actually matters.
+    private let sourceRGB: [UInt8] = [
+        0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110,
+        120, 130, 140, 150, 160, 170, 180, 190, 200, 210, 220, 230,
+        240, 250, 255, 1, 3, 7, 11, 13, 17, 19, 23, 29,
+    ]
+
+    /// `torch.nn.functional.interpolate(..., mode="bilinear", align_corners=False)` on the
+    /// above at 0-255, rounded back onto the integer grid the way torchvision's uint8 path
+    /// does, then `(x / 255 - 0.5) / 0.5`. Planar `[3, 8, 8]`.
+    private let expected: [Float] = [
+        // channel 0
+        -1.000000, -0.937255, -0.827451, -0.701961, -0.592157, -0.466667, -0.356863, -0.294118,
+        -0.937255, -0.882353, -0.764706, -0.647059, -0.529412, -0.411765, -0.294118, -0.231373,
+        -0.592157, -0.529412, -0.411765, -0.294118, -0.176471, -0.058824, 0.058824, 0.113726,
+        -0.231373, -0.176471, -0.058824, 0.058824, 0.176471, 0.294118, 0.411765, 0.474510,
+        0.113726, 0.074510, -0.003922, 0.011765, 0.113726, 0.215686, 0.317647, 0.364706,
+        0.474510, 0.231373, -0.239216, -0.443137, -0.372549, -0.301961, -0.231373, -0.192157,
+        0.819608, 0.388235, -0.482353, -0.898039, -0.850980, -0.811765, -0.772549, -0.756863,
+        0.882353, 0.411765, -0.521569, -0.968627, -0.937255, -0.898039, -0.866667, -0.850980,
+        // channel 1
+        -0.921569, -0.858824, -0.749020, -0.623529, -0.513726, -0.388235, -0.278431, -0.215686,
+        -0.858824, -0.803922, -0.686275, -0.568627, -0.450980, -0.333333, -0.215686, -0.152941,
+        -0.513726, -0.450980, -0.333333, -0.215686, -0.098039, 0.019608, 0.137255, 0.192157,
+        -0.152941, -0.098039, 0.019608, 0.137255, 0.254902, 0.372549, 0.490196, 0.552941,
+        0.192157, 0.152941, 0.066667, 0.074510, 0.176471, 0.278431, 0.380392, 0.435294,
+        0.552941, 0.301961, -0.192157, -0.403922, -0.325490, -0.254902, -0.184314, -0.145098,
+        0.898039, 0.450980, -0.450980, -0.874510, -0.835294, -0.788235, -0.749020, -0.725490,
+        0.960784, 0.474510, -0.490196, -0.952941, -0.921569, -0.874510, -0.843137, -0.819608,
+        // channel 2
+        -0.843137, -0.780392, -0.670588, -0.545098, -0.435294, -0.309804, -0.200000, -0.137255,
+        -0.780392, -0.725490, -0.607843, -0.490196, -0.372549, -0.254902, -0.137255, -0.074510,
+        -0.435294, -0.372549, -0.254902, -0.137255, -0.019608, 0.098039, 0.215686, 0.270588,
+        -0.074510, -0.019608, 0.098039, 0.215686, 0.333333, 0.450980, 0.568627, 0.631373,
+        0.270588, 0.223529, 0.137255, 0.145098, 0.247059, 0.349020, 0.458824, 0.505882,
+        0.607843, 0.356863, -0.137255, -0.349020, -0.278431, -0.200000, -0.121569, -0.082353,
+        0.945098, 0.490196, -0.411765, -0.843137, -0.796078, -0.749020, -0.701961, -0.670588,
+        1.000000, 0.513726, -0.458824, -0.921569, -0.890196, -0.843137, -0.796078, -0.772549,
+    ]
+
+    private func preprocessor(targetSize: Int = 8) -> FramePreprocessor {
+        FramePreprocessor(
+            targetSize: targetSize, mean: (0.5, 0.5, 0.5), standardDeviation: (0.5, 0.5, 0.5))
+    }
+
+    @Test("Planar CHW output matches the PyTorch video processor")
+    func matchesTorch() {
+        let actual = preprocessor().preprocess(
+            interleavedRGB: sourceRGB, width: 4, height: 3, channelStride: 3)
+        #expect(actual.count == expected.count)
+        guard actual.count == expected.count else { return }
+        var worst: Float = 0
+        for index in actual.indices {
+            worst = max(worst, abs(actual[index] - expected[index]))
+        }
+        // One code value of 8-bit input spans 2/255 = 0.0078 on this range. The residual is
+        // tie-breaking only: `vvnintf` rounds half away from zero, `torch.round` rounds half
+        // to even, so they can disagree by exactly one code value on an exact .5.
+        #expect(worst <= 0.0079, "worst |delta| \(worst)")
+    }
+
+    @Test("Rounding onto the 0-255 grid is what torchvision does")
+    func roundsOntoCodeValueGrid() {
+        // Every output must be reachable as (n/255 - 0.5)/0.5 for integer n, which is what
+        // resizing a uint8 tensor and casting back produces. Dropping the round leaves a
+        // uniform quarter-code-value bias against the reference.
+        let actual = preprocessor().preprocess(
+            interleavedRGB: sourceRGB, width: 4, height: 3, channelStride: 3)
+        for value in actual {
+            let code = (value * 0.5 + 0.5) * 255
+            #expect(abs(code - code.rounded()) < 1e-3, "\(value) is off the grid (code \(code))")
+        }
+    }
+
+    @Test("A flat image stays flat, so the weights sum to one")
+    func flatImageStaysFlat() {
+        // Weights that don't sum to 1 would shift a uniform region, which on a mask logit
+        // field moves the binarization threshold.
+        let grey = [UInt8](repeating: 128, count: 4 * 3 * 3)
+        let actual = preprocessor(targetSize: 11).preprocess(
+            interleavedRGB: grey, width: 4, height: 3, channelStride: 3)
+        let want = (Float(128) / 255 - 0.5) / 0.5
+        for value in actual {
+            #expect(abs(value - want) < 1e-6)
+        }
+    }
+
+    @Test("RGBA input skips the alpha byte")
+    func honoursChannelStride() {
+        // The `CGImage` path renders into a 4-byte-per-pixel context, so the preprocessor
+        // has to stride past alpha. Same pixels, both layouts, same answer.
+        var rgba: [UInt8] = []
+        for index in 0..<(4 * 3) {
+            rgba.append(contentsOf: sourceRGB[index * 3..<(index * 3 + 3)])
+            rgba.append(255)
+        }
+        let viaRGB = preprocessor().preprocess(
+            interleavedRGB: sourceRGB, width: 4, height: 3, channelStride: 3)
+        let viaRGBA = preprocessor().preprocess(
+            interleavedRGB: rgba, width: 4, height: 3, channelStride: 4)
+        #expect(viaRGB == viaRGBA)
+    }
+}
diff --git a/swift/Tests/VideoSegmenterTests/HotstartAndMemoryTests.swift b/swift/Tests/VideoSegmenterTests/HotstartAndMemoryTests.swift
new file mode 100644
index 00000000..d327f600
--- /dev/null
+++ b/swift/Tests/VideoSegmenterTests/HotstartAndMemoryTests.swift
@@ -0,0 +1,288 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreAI
+import Testing
+
+@testable import CoreAIShared
+@testable import CoreAIVideoSegmenter
+
+@Suite("HotstartHeuristics")
+@VideoSegmentationActor
+struct HotstartTests {
+    private func session() -> VideoInferenceSession {
+        VideoInferenceSession(videoWidth: 64, videoHeight: 64)
+    }
+
+    private func register(_ session: VideoInferenceSession, ids: [Int], firstSeen: Int) {
+        for id in ids {
+            session.index(ofObject: id)
+            session.firstFrameByObjectID[id] = firstSeen
+            session.promptIDByObjectID[id] = 0
+        }
+    }
+
+    @discardableResult
+    private func run(
+        _ session: VideoInferenceSession,
+        frame: Int,
+        matched: [Int: [Int]] = [:],
+        new: [Int] = [],
+        unmatched: [Int] = [],
+        empty: [Int] = [],
+        parameters: VideoSegmentationParameters = .default
+    ) -> Set<Int> {
+        HotstartHeuristics.process(
+            session: session, frameIndex: frame, reverse: false,
+            detectionToMatchedTrackIDs: matched, newObjectIDs: new,
+            emptyTrackIDs: empty, unmatchedTrackIDs: unmatched, parameters: parameters)
+    }
+
+    @Test("A new object records its first frame and starts at the initial keep-alive")
+    func seeding() {
+        let session = session()
+        run(session, frame: 3, new: [5])
+        #expect(session.firstFrameByObjectID[5] == 3)
+        #expect(session.keepAliveByObjectID[5] == VideoSegmentationParameters.default.initTrkKeepAlive)
+    }
+
+    @Test("Keep-alive rises on a match and falls on a miss, within its bounds")
+    func keepAliveBounds() {
+        var parameters = VideoSegmentationParameters.default
+        parameters.initTrkKeepAlive = 2
+        parameters.maxTrkKeepAlive = 3
+        parameters.minTrkKeepAlive = -1
+
+        let session = session()
+        register(session, ids: [5], firstSeen: 0)
+        run(session, frame: 1, new: [5], parameters: parameters)
+        #expect(session.keepAliveByObjectID[5] == 2)
+
+        run(session, frame: 2, matched: [0: [5]], parameters: parameters)
+        #expect(session.keepAliveByObjectID[5] == 3)
+        run(session, frame: 3, matched: [0: [5]], parameters: parameters)
+        #expect(session.keepAliveByObjectID[5] == 3, "clamped at maxTrkKeepAlive")
+
+        for frame in 4...9 { run(session, frame: frame, unmatched: [5], parameters: parameters) }
+        #expect(session.keepAliveByObjectID[5] == -1, "clamped at minTrkKeepAlive")
+    }
+
+    @Test("A track unmatched for long enough inside the window is removed")
+    func removesUnmatchedInsideWindow() {
+        var parameters = VideoSegmentationParameters.default
+        parameters.hotstartDelay = 15
+        parameters.hotstartUnmatchThresh = 3
+
+        let session = session()
+        register(session, ids: [5], firstSeen: 2)
+        // Frames 3 and 4 accumulate misses; frame 5 crosses the threshold. Object 5 first
+        // appeared at frame 2, which is after `5 - 15`, so it is still inside the window.
+        var removed: Set<Int> = []
+        for frame in 3...5 {
+            removed = run(session, frame: frame, unmatched: [5], parameters: parameters)
+        }
+        #expect(removed == [5])
+        #expect(session.removedObjectIDs.contains(5))
+    }
+
+    @Test("A long-established track is never removed by the unmatch rule")
+    func sparesEstablishedTracks() {
+        // The whole point of the hotstart window: a track that predates it has earned the
+        // benefit of the doubt, however long the detector loses sight of it.
+        var parameters = VideoSegmentationParameters.default
+        parameters.hotstartDelay = 5
+        parameters.hotstartUnmatchThresh = 3
+
+        let session = session()
+        register(session, ids: [5], firstSeen: 0)
+        var removed: Set<Int> = []
+        for frame in 20...30 {
+            removed = run(session, frame: frame, unmatched: [5], parameters: parameters)
+        }
+        #expect(removed.isEmpty)
+        #expect(session.unmatchedFramesByObjectID[5]?.count == 11)
+    }
+
+    @Test("A duplicate that overlaps an earlier track for long enough is removed")
+    func removesDuplicates() {
+        var parameters = VideoSegmentationParameters.default
+        parameters.hotstartDelay = 20
+        parameters.hotstartDupThresh = 2
+
+        let session = session()
+        register(session, ids: [1], firstSeen: 1)
+        register(session, ids: [2], firstSeen: 4)
+
+        // The same detection claims both tracks. Object 2 appeared later, so it is the
+        // candidate duplicate; object 1 is never at risk.
+        var removed: Set<Int> = []
+        for frame in 5...6 {
+            removed = run(session, frame: frame, matched: [0: [1, 2]], parameters: parameters)
+        }
+        #expect(removed == [2])
+    }
+
+    @Test("A single track matching a detection is not an overlap")
+    func singleMatchIsNotOverlap() {
+        var parameters = VideoSegmentationParameters.default
+        parameters.hotstartDupThresh = 1
+
+        let session = session()
+        register(session, ids: [1], firstSeen: 0)
+        let removed = run(session, frame: 5, matched: [0: [1]], parameters: parameters)
+        #expect(removed.isEmpty)
+        #expect(session.overlapFramesByPair.isEmpty)
+    }
+
+    @Test("Keep-alive suppression only applies when the hotstart restriction is lifted")
+    func keepAliveSuppression() {
+        var parameters = VideoSegmentationParameters.default
+        parameters.suppressUnmatchedOnlyWithinHotstart = true
+        parameters.initTrkKeepAlive = 1
+        parameters.minTrkKeepAlive = -1
+        parameters.hotstartUnmatchThresh = 100  // keep the removal rule out of the way
+
+        let session = session()
+        register(session, ids: [5], firstSeen: 0)
+        session.keepAliveByObjectID[5] = 0
+        run(session, frame: 10, unmatched: [5], parameters: parameters)
+        #expect(session.suppressedObjectIDsByFrame[10]?.isEmpty ?? true)
+
+        parameters.suppressUnmatchedOnlyWithinHotstart = false
+        run(session, frame: 11, unmatched: [5], parameters: parameters)
+        #expect(session.suppressedObjectIDsByFrame[11]?.contains(5) == true)
+    }
+}
+
+@Suite("MemoryBankPacker selection")
+@VideoSegmentationActor
+struct MemorySelectionTests {
+    /// A history with the given conditioning and non-conditioning frames, each carrying a
+    /// payload so the packer treats it as usable.
+    private func history(conditioning: [Int], nonConditioning: [Int]) -> ObjectOutputHistory {
+        var history = ObjectOutputHistory()
+        for frame in conditioning {
+            history.conditioningOrder.append(frame)
+            history.conditioning[frame] = stub()
+        }
+        for frame in nonConditioning {
+            history.nonConditioning[frame] = stub()
+        }
+        return history
+    }
+
+    /// The selection code under test never dereferences `objectPointer`, so a bare
+    /// zero-filled array stands in and the tests need no live Core AI asset.
+    private func stub() -> StoredFrameOutput {
+        StoredFrameOutput(
+            predictedMasks: nil,
+            objectPointer: NDArray(shape: [1, 1, 4], scalarType: .float16),
+            objectScoreLogit: 0)
+    }
+
+    @Test("Under the cap, every conditioning frame is selected")
+    func selectsAllUnderCap() {
+        let (selected, unselected) = MemoryBankPacker.selectClosestConditioningFrames(
+            history: history(conditioning: [0, 5, 9], nonConditioning: []),
+            frameIndex: 12, limit: 4)
+        #expect(selected == [0, 5, 9])
+        #expect(unselected.isEmpty)
+    }
+
+    @Test("Over the cap, the nearest before and after come first, then the next closest")
+    func selectsClosest() {
+        // Port of `_select_closest_cond_frames`: frame 9 is the nearest before 10, frame
+        // 11 the nearest at-or-after, then 5 as the next closest. Frame 0 is dropped.
+        let (selected, unselected) = MemoryBankPacker.selectClosestConditioningFrames(
+            history: history(conditioning: [0, 5, 9, 11, 30], nonConditioning: []),
+            frameIndex: 10, limit: 3)
+        #expect(Set(selected) == [9, 11, 5])
+        #expect(unselected == [0, 30])
+    }
+
+    @Test("Recent frames are gathered newest-last, with gaps preserved")
+    func gathersRecentFrames() {
+        var parameters = VideoSegmentationParameters.default
+        parameters.numMaskmem = 4  // offsets 3, 2, 1
+        parameters.maxCondFrameNum = 4
+
+        let entries = MemoryBankPacker.gatherMemoryFrames(
+            history: history(conditioning: [0], nonConditioning: [8, 9]),
+            frameIndex: 10, reverse: false, parameters: parameters)
+
+        #expect(entries.map(\.offset) == [0, 3, 2, 1])
+        // Frame 7 is missing, so offset 3 is a gap. It stays in the list rather than being
+        // filtered, because the offset has to stay attached to the right entry.
+        #expect(entries[1].output == nil)
+        #expect(entries[2].output != nil)
+        #expect(entries[3].output != nil)
+    }
+
+    @Test("Tracking backwards looks forward for recent frames")
+    func gathersInReverse() {
+        var parameters = VideoSegmentationParameters.default
+        parameters.numMaskmem = 3  // offsets 2, 1
+
+        let entries = MemoryBankPacker.gatherMemoryFrames(
+            history: history(conditioning: [20], nonConditioning: [11, 12]),
+            frameIndex: 10, reverse: true, parameters: parameters)
+        #expect(entries.map(\.offset) == [0, 2, 1])
+        #expect(entries[1].output != nil, "frame 12 is two ahead")
+        #expect(entries[2].output != nil, "frame 11 is one ahead")
+    }
+
+    @Test("An unselected conditioning frame can still be picked up as a recent memory")
+    func unselectedConditioningIsReachable() {
+        // `_gather_memory_frame_outputs` falls back to `unselected_conditioning_outputs`
+        // for the recent window. Without that, a conditioning frame that lost the
+        // closest-N contest would vanish from the bank entirely even though it is adjacent.
+        var parameters = VideoSegmentationParameters.default
+        parameters.numMaskmem = 3  // offsets 2, 1
+        parameters.maxCondFrameNum = 1
+
+        let entries = MemoryBankPacker.gatherMemoryFrames(
+            history: history(conditioning: [0, 9], nonConditioning: []),
+            frameIndex: 10, reverse: false, parameters: parameters)
+        // Frame 9 wins the single conditioning slot; frame 0 is unselected and is not one
+        // frame back, so offset 1 resolves to frame 9's entry only if it were unselected.
+        #expect(entries[0].offset == 0)
+        #expect(entries.count == 3)
+    }
+
+    @Test("Object pointers cover eligible conditioning frames and a contiguous look-back")
+    func objectPointers() {
+        var parameters = VideoSegmentationParameters.default
+        parameters.maxObjectPointers = 4
+
+        let (offsets, _, maxPointers) = MemoryBankPacker.objectPointers(
+            history: history(conditioning: [2], nonConditioning: [7, 8, 9]),
+            frameIndex: 10, totalFrames: 50, reverse: false, parameters: parameters)
+        // Conditioning frame 2 is 8 back; then offsets 1, 2, 3 for frames 9, 8, 7.
+        #expect(offsets == [8, 1, 2, 3])
+        #expect(maxPointers == 4)
+    }
+
+    @Test("A future conditioning frame is ineligible when tracking forwards")
+    func futureConditioningExcluded() {
+        let (offsets, _, _) = MemoryBankPacker.objectPointers(
+            history: history(conditioning: [20], nonConditioning: []),
+            frameIndex: 10, totalFrames: 50, reverse: false, parameters: .default)
+        #expect(offsets.isEmpty)
+    }
+
+    @Test("The look-back stops at the start of the video rather than skipping past it")
+    func lookBackStopsAtBoundary() {
+        // Upstream `break`s on an out-of-range index. A `continue` would keep scanning and
+        // pick up nothing, which happens to agree here but not when frames are sparse.
+        var parameters = VideoSegmentationParameters.default
+        parameters.maxObjectPointers = 8
+
+        let (offsets, _, maxPointers) = MemoryBankPacker.objectPointers(
+            history: history(conditioning: [0], nonConditioning: [1]),
+            frameIndex: 2, totalFrames: 3, reverse: false, parameters: parameters)
+        #expect(offsets == [2, 1])
+        #expect(maxPointers == 3, "capped by the video length, not the config")
+    }
+}
diff --git a/swift/Tests/VideoSegmenterTests/MaskBitsetTests.swift b/swift/Tests/VideoSegmenterTests/MaskBitsetTests.swift
new file mode 100644
index 00000000..f5c06cd8
--- /dev/null
+++ b/swift/Tests/VideoSegmenterTests/MaskBitsetTests.swift
@@ -0,0 +1,130 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import CoreGraphics
+import Testing
+
+@testable import CoreAIShared
+
+@Suite("MaskBitset")
+struct MaskBitsetTests {
+    /// Builds a mask from an ASCII picture, so the expectations below read as pictures too.
+    private func mask(_ rows: [String]) -> MaskBitset {
+        var bitset = MaskBitset(width: rows[0].count, height: rows.count)
+        for (y, row) in rows.enumerated() {
+            for (x, character) in row.enumerated() where character == "#" {
+                bitset[x, y] = true
+            }
+        }
+        return bitset
+    }
+
+    @Test("Thresholding is strictly greater, matching HF's `mask > 0`")
+    func strictThreshold() {
+        // Every SAM 3 call site binarizes with `> 0`. Using `>=` would flip every exactly
+        // zero pixel to foreground, which on a padded logit field is most of the frame.
+        let values: [Float] = [-1, 0, 0.0001, 1]
+        let bitset = MaskBitset(thresholding: values, width: 4, height: 1)
+        #expect(bitset[0, 0] == false)
+        #expect(bitset[1, 0] == false)
+        #expect(bitset[2, 0] == true)
+        #expect(bitset[3, 0] == true)
+        #expect(bitset.area == 2)
+    }
+
+    @Test("IoU of two empty masks is 0, not 1")
+    func emptyIoU() {
+        // `mask_iou` clamps the union to a minimum of 1 rather than special-casing empty,
+        // so two empty masks score 0. Association depends on that: it must treat two
+        // occluded tracks as unrelated, not as a perfect match.
+        let empty = MaskBitset(width: 8, height: 8)
+        #expect(empty.iou(empty) == 0)
+    }
+
+    @Test("IoU counts intersection over union")
+    func iou() {
+        let a = mask([
+            "##..",
+            "##..",
+        ])
+        let b = mask([
+            ".##.",
+            ".##.",
+        ])
+        // Intersection is the shared column pair (2 pixels), union is 6.
+        #expect(a.iou(b) == Float(2) / Float(6))
+        #expect(a.iou(a) == 1)
+    }
+
+    @Test("IoU survives a mask wider than one 64-bit word")
+    func iouAcrossWords() {
+        // 100x3 is 300 bits, so the set pixels straddle word boundaries, the case a
+        // naive per-word loop gets wrong.
+        var a = MaskBitset(width: 100, height: 3)
+        var b = MaskBitset(width: 100, height: 3)
+        for x in 0..<100 {
+            a[x, 1] = true
+            if x >= 50 { b[x, 1] = true }
+        }
+        #expect(a.area == 100)
+        #expect(b.area == 50)
+        #expect(a.iou(b) == 0.5)
+    }
+
+    @Test("boundingBox reports inclusive extremes, like masks_to_boxes")
+    func boundingBox() {
+        let bitset = mask([
+            "....",
+            ".##.",
+            ".##.",
+            "....",
+        ])
+        // `torchvision.ops.masks_to_boxes` returns [x0, y0, x1, y1] of the extreme set
+        // pixels, so a 2x2 block spans 1 unit, not 2.
+        #expect(bitset.boundingBox == CGRect(x: 1, y: 1, width: 1, height: 1))
+    }
+
+    @Test("boundingBox of one pixel is a zero-sized rect at that pixel")
+    func singlePixelBox() {
+        var bitset = MaskBitset(width: 10, height: 10)
+        bitset[7, 3] = true
+        #expect(bitset.boundingBox == CGRect(x: 7, y: 3, width: 0, height: 0))
+    }
+
+    @Test("boundingBox of an empty mask is zero")
+    func emptyBox() {
+        #expect(MaskBitset(width: 10, height: 10).boundingBox == .zero)
+    }
+
+    @Test("forEachSetIndex visits row-major indices in order and stops at the logical end")
+    func setIndices() {
+        // 5x2 is 10 bits inside one 64-bit word, so the trailing 54 bits are padding the
+        // walk must not report.
+        var bitset = MaskBitset(width: 5, height: 2)
+        bitset[0, 0] = true
+        bitset[4, 1] = true
+        var visited: [Int] = []
+        bitset.forEachSetIndex { visited.append($0) }
+        #expect(visited == [0, 9])
+    }
+
+    @Test("packbits round-trips a mask that is not a multiple of 8 pixels")
+    func packedRoundTrip() {
+        // `numpy.packbits` is MSB-first within each byte and pads the last one. 5x3 = 15
+        // bits, so the second byte carries a partial value.
+        let original = mask([
+            "#..#.",
+            ".#.#.",
+            "..#..",
+        ])
+        var packed = [UInt8](repeating: 0, count: 2)
+        original.forEachSetIndex { index in
+            packed[index >> 3] |= 0x80 >> UInt8(index & 7)
+        }
+        let restored = MaskBitset(packedBits: packed, width: 5, height: 3)
+        #expect(restored == original)
+        #expect(restored.area == original.area)
+    }
+}
diff --git a/swift/Tests/VideoSegmenterTests/MaskPostprocessorTests.swift b/swift/Tests/VideoSegmenterTests/MaskPostprocessorTests.swift
new file mode 100644
index 00000000..94b07681
--- /dev/null
+++ b/swift/Tests/VideoSegmenterTests/MaskPostprocessorTests.swift
@@ -0,0 +1,126 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import Testing
+
+@testable import CoreAIShared
+@testable import CoreAIVideoSegmenter
+
+/// The opt-in low-resolution mask channel. The contract worth pinning is that
+/// `lowResolutionMasks` is index-aligned with `objects`, because the two are appended in
+/// separate places and every `continue` in the loop has to skip both.
+@Suite("MaskPostprocessor low-resolution masks")
+@VideoSegmentationActor
+struct LowResolutionMaskTests {
+    private static let lowResolutionSide = 4
+    private static let videoSide = 8
+
+    /// A constant logit field: bilinear upsampling reproduces `value` everywhere, so a
+    /// positive value gives a full mask and a negative one gives an empty mask.
+    private func logits(_ value: Float) -> [Float] {
+        [Float](repeating: value, count: Self.lowResolutionSide * Self.lowResolutionSide)
+    }
+
+    private func makeSession(_ objects: [(id: Int, prompt: String)]) -> VideoInferenceSession {
+        let session = VideoInferenceSession(
+            videoWidth: Self.videoSide, videoHeight: Self.videoSide)
+        for object in objects {
+            session.index(ofObject: object.id)
+            session.promptIDByObjectID[object.id] = session.addPrompt(object.prompt)
+        }
+        return session
+    }
+
+    private func raw(_ masks: [Int: [Float]], suppressed: Set<Int> = []) -> RawFrameOutput {
+        RawFrameOutput(
+            frameIndex: 0,
+            maskLogitsByObjectID: masks,
+            objectIDs: masks.keys.sorted(),
+            scoreByObjectID: masks.mapValues { _ in 0.9 },
+            trackerScoreByObjectID: masks.mapValues { _ in 0.8 },
+            suppressedObjectIDs: suppressed)
+    }
+
+    private func postprocessor(emit: Bool) -> MaskPostprocessor {
+        MaskPostprocessor(
+            lowResolutionSize: Self.lowResolutionSide,
+            videoWidth: Self.videoSide, videoHeight: Self.videoSide,
+            emitLowResolutionMasks: emit)
+    }
+
+    @Test("Off by default, so nothing is emitted even when objects survive")
+    func offByDefault() {
+        let session = makeSession([(10, "cat")])
+        let result = MaskPostprocessor(
+            lowResolutionSize: Self.lowResolutionSide,
+            videoWidth: Self.videoSide, videoHeight: Self.videoSide
+        ).postprocess(raw([10: logits(1)]), session: session)
+
+        #expect(result.objects.map(\.id) == [10])
+        #expect(result.lowResolutionMasks.isEmpty)
+    }
+
+    @Test("On, one entry per surviving object in the order `objects` reports")
+    func oneEntryPerSurvivingObject() {
+        let session = makeSession([(10, "cat"), (40, "dog")])
+        let result = postprocessor(emit: true)
+            .postprocess(raw([10: logits(10), 40: logits(40)]), session: session)
+
+        #expect(result.objects.map(\.id) == [10, 40])
+        #expect(result.lowResolutionMasks.count == result.objects.count)
+        #expect(result.lowResolutionMasks[0].allSatisfy { $0 == 10 })
+        #expect(result.lowResolutionMasks[1].allSatisfy { $0 == 40 })
+    }
+
+    @Test("What comes back is the pre-upsample logit field, not the upsampled mask")
+    func emitsPreUpsampleLogits() {
+        let session = makeSession([(10, "cat")])
+        let result = postprocessor(emit: true)
+            .postprocess(raw([10: logits(3)]), session: session)
+
+        #expect(result.lowResolutionMasks.count == 1)
+        // 16 low-resolution logits in, an 8x8 mask out. Emitting the upsampled field
+        // instead would give 64 values and defeat the point of the flag.
+        #expect(result.lowResolutionMasks[0] == logits(3))
+        #expect(result.objects[0].mask.width == Self.videoSide)
+    }
+
+    @Test("A dropped object leaves no hole, so the two arrays stay index-aligned")
+    func droppedObjectsKeepArraysAligned() {
+        let session = makeSession([
+            (10, "cat"), (20, "dog"), (30, "bird"), (40, "fish"), (50, "hat"),
+        ])
+        session.hotstartRemovedObjectIDs = [50]
+        let result = postprocessor(emit: true).postprocess(
+            raw(
+                [
+                    10: logits(10),
+                    20: logits(20),  // suppressed this frame
+                    30: logits(-1),  // upsamples to an empty mask
+                    40: logits(40),
+                    50: logits(50),  // removed by hotstart
+                ],
+                suppressed: [20]),
+            session: session)
+
+        #expect(result.objects.map(\.id) == [10, 40])
+        #expect(result.lowResolutionMasks.count == 2)
+        // Each surviving object's logits must sit at its own index, not at the index it
+        // would have had before the three drops.
+        for (index, object) in result.objects.enumerated() {
+            #expect(result.lowResolutionMasks[index].allSatisfy { $0 == Float(object.id) })
+        }
+    }
+
+    @Test("Nothing survives, so both arrays come back empty")
+    func nothingSurvives() {
+        let session = makeSession([(10, "cat")])
+        let result = postprocessor(emit: true)
+            .postprocess(raw([10: logits(-1)]), session: session)
+
+        #expect(result.objects.isEmpty)
+        #expect(result.lowResolutionMasks.isEmpty)
+    }
+}
diff --git a/swift/Tests/VideoSegmenterTests/TokenizerAndBundleTests.swift b/swift/Tests/VideoSegmenterTests/TokenizerAndBundleTests.swift
new file mode 100644
index 00000000..36f4cfe8
--- /dev/null
+++ b/swift/Tests/VideoSegmenterTests/TokenizerAndBundleTests.swift
@@ -0,0 +1,233 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import Foundation
+import Testing
+
+@testable import CoreAIShared
+@testable import CoreAIVideoSegmenter
+
+@Suite("CLIPTokenizer attention mask")
+struct TokenizerTests {
+    /// A vocabulary of whole single-letter words.
+    ///
+    /// CLIP's BPE appends `</w>` to the last character of a token and then merges pairs;
+    /// with no merge table a one-letter word is already terminal, so it looks up directly.
+    /// That keeps this suite self-contained: it tests the masking rule, not BPE, and BPE
+    /// is unchanged from the shipped image-segmenter tokenizer.
+    private func tokenizer() throws -> CLIPTokenizer {
+        try CLIPTokenizer(
+            vocab: [
+                "<|startoftext|>": 49406,
+                "<|endoftext|>": 49407,
+                "a</w>": 320,
+                "b</w>": 736,
+                "c</w>": 1615,
+            ],
+            merges: [])
+    }
+
+    /// The tokenizer shipped in the exported bundle, when it is present.
+    private func bundledTokenizer() -> CLIPTokenizer? {
+        let root = URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent()  // VideoSegmenterTests
+            .deletingLastPathComponent()  // Tests
+            .deletingLastPathComponent()  // swift
+        let folder = root.appending(path: "exports/sam3_video_float16/tokenizer")
+        return try? CLIPTokenizer(folder: folder)
+    }
+
+    @Test("A one-word prompt is SOT, the word, EOT, then padding")
+    func singleWord() throws {
+        let (ids, mask) = try tokenizer().encodeWithMask("a", contextLength: 32)
+        #expect(ids.prefix(4) == [49406, 320, 49407, 49407])
+        #expect(ids.count == 32)
+        #expect(mask.prefix(4) == [1, 1, 1, 0])
+        #expect(mask.reduce(0, +) == 3)
+    }
+
+    @Test("The mask distinguishes a real EOT from the pad tokens after it")
+    func maskMarksRealTokens() throws {
+        // The pad token *is* `<|endoftext|>`, so the ids alone cannot tell the closing EOT
+        // from padding. This is the whole reason `encodeWithMask` exists.
+        let (ids, mask) = try tokenizer().encodeWithMask("a b c", contextLength: 32)
+        #expect(ids.prefix(5) == [49406, 320, 736, 1615, 49407])
+        #expect(mask.prefix(6) == [1, 1, 1, 1, 1, 0])
+        #expect(mask.reduce(0, +) == 5)
+        #expect(ids[4] == ids[5], "the real EOT and the first pad share an id")
+        #expect(mask[4] != mask[5], "but not a mask value")
+    }
+
+    @Test("Case and surrounding whitespace are normalized away")
+    func normalization() throws {
+        let plain = try tokenizer().encodeWithMask("a b", contextLength: 32)
+        let noisy = try tokenizer().encodeWithMask("  A   B  ", contextLength: 32)
+        #expect(plain.ids == noisy.ids)
+        #expect(plain.attentionMask == noisy.attentionMask)
+    }
+
+    @Test("An over-long prompt is truncated with EOT forced into the last slot")
+    func truncation() throws {
+        // HF would emit a longer row and warn; the graph is traced at a fixed length, so
+        // truncating is the only option that runs. The mask goes all-ones because every
+        // slot then holds a real token.
+        let (ids, mask) = try tokenizer().encodeWithMask("a b c a b c", contextLength: 5)
+        #expect(ids.count == 5)
+        #expect(ids.last == 49407)
+        #expect(mask == [1, 1, 1, 1, 1])
+    }
+
+    @Test("encode agrees with encodeWithMask on the ids")
+    func encodeMatches() throws {
+        let tokenizer = try tokenizer()
+        #expect(
+            tokenizer.encode("a b c", contextLength: 32)
+                == tokenizer.encodeWithMask("a b c", contextLength: 32).ids)
+    }
+
+    @Test("The real vocabulary reproduces what HF emits for a multi-word prompt")
+    func realVocabulary() throws {
+        // Captured from `AutoTokenizer.from_pretrained("exports/sam3_video_float16/tokenizer")`
+        // with `padding="max_length", max_length=32`. Skipped when the bundle is absent,
+        // so this suite still runs on a machine that has not exported one.
+        guard let tokenizer = bundledTokenizer() else { return }
+
+        let person = tokenizer.encodeWithMask("person", contextLength: 32)
+        #expect(person.ids.prefix(3) == [49406, 2533, 49407])
+        #expect(person.attentionMask.reduce(0, +) == 3)
+
+        let car = tokenizer.encodeWithMask("a red car", contextLength: 32)
+        #expect(car.ids.prefix(5) == [49406, 320, 736, 1615, 49407])
+        #expect(car.attentionMask.reduce(0, +) == 5)
+    }
+}
+
+@Suite("Temporal position index")
+struct TemporalIndexTests {
+    @Test("A conditioning frame maps to the last row, not to -1")
+    func conditioningWraps() {
+        // HF writes `memory_temporal_positional_encoding[offset - 1]`, and a conditioning
+        // frame's offset is 0, which in Python is the last row. Getting this wrong
+        // gives every conditioning memory the wrong temporal encoding, which the graph
+        // cannot flag because the index is still in range.
+        #expect(MemoryBankPacker.temporalIndex(forOffset: 0, numMaskmem: 7) == 6)
+    }
+
+    @Test("Recent frames map to offset minus one")
+    func recentFrames() {
+        #expect(MemoryBankPacker.temporalIndex(forOffset: 1, numMaskmem: 7) == 0)
+        #expect(MemoryBankPacker.temporalIndex(forOffset: 6, numMaskmem: 7) == 5)
+    }
+}
+
+@Suite("VideoSegmenterBundle metadata")
+struct BundleMetadataTests {
+    private func bundle(_ json: String) throws -> VideoSegmenterBundle {
+        try VideoSegmenterBundle(
+            bundle: ModelBundle(
+                raw: Data(json.utf8),
+                bundlePath: URL(fileURLWithPath: "/tmp/does-not-need-to-exist")))
+    }
+
+    private let minimal = """
+        {
+          "metadata_version": "0.2",
+          "kind": "video_segmenter",
+          "name": "sam3_video_float16",
+          "assets": {"main": "sam3_video_float16.aimodel"},
+          "runtime": {
+            "image_size": 1008, "spatial_slots": 10,
+            "ptr_slots": 24, "max_text_seq_len": 32
+          }
+        }
+        """
+
+    @Test("The runtime block is parsed")
+    func geometry() throws {
+        let parsed = try bundle(minimal)
+        #expect(parsed.geometry.imageSize == 1008)
+        #expect(parsed.geometry.spatialSlots == 10)
+        #expect(parsed.geometry.ptrSlots == 24)
+        #expect(parsed.geometry.maxTextSeqLen == 32)
+    }
+
+    @Test("A bundle without a tracking block keeps the upstream defaults")
+    func defaultsWithoutTracking() throws {
+        // The shipped export predates the tracking block, so this is the path it takes.
+        let parameters = try bundle(minimal).parameters()
+        #expect(parameters.hotstartDelay == 15)
+        #expect(parameters.scoreThresholdDetection == 0.5)
+        #expect(parameters.numMaskmem == 7)
+        #expect(parameters.maxCondFrameNum == 4)
+    }
+
+    @Test("A partial tracking block overrides only what it names")
+    func partialOverride() throws {
+        let parsed = try bundle(
+            """
+            {
+              "metadata_version": "0.2",
+              "kind": "video_segmenter",
+              "name": "x",
+              "assets": {"main": "x.aimodel"},
+              "runtime": {
+                "image_size": 336, "spatial_slots": 10,
+                "ptr_slots": 24, "max_text_seq_len": 32
+              },
+              "tracking": {"hotstart_delay": 0, "score_threshold_detection": 0.25}
+            }
+            """)
+        let parameters = parsed.parameters()
+        #expect(parameters.hotstartDelay == 0)
+        #expect(parameters.scoreThresholdDetection == 0.25)
+        #expect(parameters.newDetThresh == 0.7, "untouched keys keep their default")
+        #expect(parsed.geometry.imageSize == 336)
+    }
+
+    @Test("Caller overrides apply underneath the bundle's own values")
+    func bundleWinsOverCaller() throws {
+        var caller = VideoSegmentationParameters.default
+        caller.hotstartDelay = 99
+        caller.maxNumObjects = 5
+
+        let parsed = try bundle(
+            """
+            {
+              "metadata_version": "0.2", "kind": "video_segmenter", "name": "x",
+              "assets": {"main": "x.aimodel"},
+              "runtime": {"image_size": 1008, "spatial_slots": 10, "ptr_slots": 24,
+                          "max_text_seq_len": 32},
+              "tracking": {"hotstart_delay": 3}
+            }
+            """)
+        let parameters = parsed.parameters(overriding: caller)
+        #expect(parameters.hotstartDelay == 3, "the bundle knows its own checkpoint")
+        #expect(parameters.maxNumObjects == 5, "the caller's value survives where the bundle is silent")
+    }
+
+    @Test("A missing runtime block is rejected with an actionable message")
+    func missingRuntime() throws {
+        #expect(throws: VideoSegmentationError.self) {
+            try bundle(
+                """
+                {"metadata_version": "0.2", "kind": "video_segmenter", "name": "x",
+                 "assets": {"main": "x.aimodel"}}
+                """)
+        }
+    }
+
+    @Test("A segmenter bundle is not accepted as a video segmenter")
+    func kindMismatch() throws {
+        #expect(throws: ModelBundle.BundleError.self) {
+            try bundle(
+                """
+                {"metadata_version": "0.2", "kind": "segmenter", "name": "x",
+                 "assets": {"main": "x.aimodel"},
+                 "runtime": {"image_size": 1008, "spatial_slots": 10, "ptr_slots": 24,
+                             "max_text_seq_len": 32}}
+                """)
+        }
+    }
+}
diff --git a/swift/Tests/VideoSegmenterTests/TrackingPrimitiveTests.swift b/swift/Tests/VideoSegmenterTests/TrackingPrimitiveTests.swift
new file mode 100644
index 00000000..77d8a0f6
--- /dev/null
+++ b/swift/Tests/VideoSegmenterTests/TrackingPrimitiveTests.swift
@@ -0,0 +1,212 @@
+// Copyright 2026 Apple Inc.
+//
+// Use of this source code is governed by a BSD-3-clause license that can
+// be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+import Testing
+
+@testable import CoreAIShared
+@testable import CoreAIVideoSegmenter
+
+@Suite("ObjectRegistry")
+struct ObjectRegistryTests {
+    @Test("Indices are assigned in first-sighting order and reused")
+    func assignment() {
+        var registry = ObjectRegistry()
+        #expect(registry.index(of: 7).index == 0)
+        #expect(registry.index(of: 7).isNew == false)
+        #expect(registry.index(of: 3).index == 1)
+        #expect(registry.ids == [7, 3])
+    }
+
+    @Test("Removing an object renumbers every index above it")
+    func removalRenumbers() {
+        // This is `remove_object`'s `_map_keys`. Leaving a hole instead would misattribute
+        // every later object's memory bank, which is silent and catastrophic.
+        var registry = ObjectRegistry()
+        for id in [10, 11, 12, 13] { registry.index(of: id) }
+
+        let survivors = registry.remove(11)
+        #expect(survivors == [0, 2, 3])
+        #expect(registry.ids == [10, 12, 13])
+        #expect(registry.existingIndex(of: 12) == 1)
+        #expect(registry.existingIndex(of: 13) == 2)
+        #expect(registry.existingIndex(of: 11) == nil)
+    }
+
+    @Test("The survivor list is exactly what compacts a parallel array")
+    func survivorsCompactStorage() {
+        var registry = ObjectRegistry()
+        for id in [10, 11, 12, 13] { registry.index(of: id) }
+        let storage = ["a", "b", "c", "d"]
+        let survivors = registry.remove(11)!
+        #expect(survivors.map { storage[$0] } == ["a", "c", "d"])
+    }
+
+    @Test("Removing an unknown id is a no-op, not an error")
+    func removeUnknown() {
+        // `remove_object(strict=False)` returns quietly, and the frame loop relies on it:
+        // an object can be removed by two heuristics on the same frame.
+        var registry = ObjectRegistry()
+        registry.index(of: 1)
+        #expect(registry.remove(99) == nil)
+        #expect(registry.ids == [1])
+    }
+}
+
+@Suite("ConnectedComponents")
+struct ConnectedComponentsTests {
+    private func boolMask(_ rows: [String]) -> [Bool] {
+        rows.flatMap { $0.map { $0 == "#" } }
+    }
+
+    @Test("Diagonal neighbours join, because cc_2d is 8-connected")
+    func eightConnectivity() {
+        // SAM 2's `get_connected_components` documents 8-connectivity and `cc_2d`
+        // implements it. Under 4-connectivity these two pixels would be separate
+        // components of area 1 each, and sprinkle removal would delete both.
+        let mask = boolMask([
+            "#..",
+            ".#.",
+            "...",
+        ])
+        let areas = ConnectedComponents.areas(of: mask, width: 3, height: 3)
+        #expect(areas[0] == 2)
+        #expect(areas[4] == 2)
+        #expect(areas[1] == 0)
+    }
+
+    @Test("Separate blobs get their own areas")
+    func separateComponents() {
+        let mask = boolMask([
+            "##...",
+            "##...",
+            ".....",
+            "....#",
+        ])
+        let areas = ConnectedComponents.areas(of: mask, width: 5, height: 4)
+        #expect(areas[0] == 4)
+        #expect(areas[6] == 4)
+        #expect(areas[19] == 1)
+    }
+
+    @Test("A background hole under the area limit is filled to a weak positive")
+    func fillsHoles() {
+        var logits = [Float](repeating: 1, count: 25)
+        logits[12] = -1  // one background pixel enclosed by foreground
+        ConnectedComponents.fillHoles(&logits, width: 5, height: 5, maxArea: 4)
+        // Upstream writes 0.1, not a saturated value: the mask stays a logit field.
+        #expect(logits[12] == 0.1)
+    }
+
+    @Test("A background region above the area limit is left alone")
+    func leavesLargeBackground() {
+        var logits = [Float](repeating: -1, count: 25)
+        logits[0] = 1
+        ConnectedComponents.fillHoles(&logits, width: 5, height: 5, maxArea: 4)
+        #expect(logits[12] == -1)
+    }
+
+    @Test("A foreground speck is removed, and the object it sits beside is not")
+    func removesSprinkles() {
+        var logits = [Float](repeating: -1, count: 100)
+        // A 6x6 block, plus one isolated pixel far away.
+        for y in 0..<6 {
+            for x in 0..<6 { logits[y * 10 + x] = 1 }
+        }
+        logits[99] = 1
+        ConnectedComponents.fillHoles(&logits, width: 10, height: 10, maxArea: 4)
+        #expect(logits[99] == -0.1)
+        #expect(logits[0] == 1)
+    }
+
+    @Test("A tiny object does not delete itself")
+    func halfAreaGuard() {
+        // The foreground threshold is `min(maxArea, totalForeground / 2)`, which is what
+        // stops a genuinely small object from being read as a speck. Here the whole mask
+        // is 3 pixels, so the threshold is 1 rather than the configured 16.
+        var logits = [Float](repeating: -1, count: 100)
+        logits[11] = 1
+        logits[12] = 1
+        logits[13] = 1
+        ConnectedComponents.fillHoles(&logits, width: 10, height: 10, maxArea: 16)
+        #expect(logits[11] == 1)
+        #expect(logits[12] == 1)
+    }
+
+    @Test("A zero area limit disables both passes")
+    func disabled() {
+        var logits = [Float](repeating: -1, count: 25)
+        logits[12] = 1
+        let before = logits
+        ConnectedComponents.fillHoles(&logits, width: 5, height: 5, maxArea: 0)
+        #expect(logits == before)
+    }
+}
+
+@Suite("DetectionDecoder")
+struct DetectionDecoderTests {
+    private func mask(_ rows: [String]) -> MaskBitset {
+        var bitset = MaskBitset(width: rows[0].count, height: rows.count)
+        for (y, row) in rows.enumerated() {
+            for (x, character) in row.enumerated() where character == "#" {
+                bitset[x, y] = true
+            }
+        }
+        return bitset
+    }
+
+    @Test("sigmoid does not overflow on a large positive logit")
+    func sigmoidStability() {
+        // `1 / (1 + exp(-x))` is fine for large x but `exp(x) / (1 + exp(x))` overflows to
+        // inf/inf = NaN. The detector's logits are unbounded, so the branch matters.
+        #expect(DetectionDecoder.sigmoid(0) == 0.5)
+        #expect(DetectionDecoder.sigmoid(100) == 1)
+        // Not exactly zero: the negative branch keeps the denormal rather than
+        // underflowing, which is the point of branching on the sign.
+        #expect(DetectionDecoder.sigmoid(-100) < 1e-40)
+        #expect(DetectionDecoder.sigmoid(-100) >= 0)
+        #expect(DetectionDecoder.sigmoid(-100).isNaN == false)
+        #expect(abs(DetectionDecoder.sigmoid(2) - 0.880797) < 1e-5)
+    }
+
+    @Test("NMS keeps the highest-scoring member of an overlapping group")
+    func nmsSuppresses() {
+        let masks = [mask(["####"]), mask(["###."]), mask(["...#"])]
+        let kept = DetectionDecoder.nonMaximumSuppression(
+            masks: masks, scores: [0.9, 0.8, 0.7], iouThreshold: 0.5)
+        // Index 1 overlaps index 0 at IoU 0.75 and is dropped; index 2 overlaps at 0.25
+        // and survives.
+        #expect(kept == [0, 2])
+    }
+
+    @Test("NMS returns survivors in input order, not score order")
+    func nmsPreservesOrder() {
+        // Detections are indexed positionally downstream, and new objects are numbered by
+        // that position, so returning score order would renumber tracks.
+        let masks = [mask(["#..."]), mask([".#.."]), mask(["..#."])]
+        let kept = DetectionDecoder.nonMaximumSuppression(
+            masks: masks, scores: [0.1, 0.9, 0.5], iouThreshold: 0.5)
+        #expect(kept == [0, 1, 2])
+    }
+
+    @Test("Merging concatenates prompts in order and tags each detection")
+    func merge() {
+        var first = MergedDetections()
+        first.scores = [0.9]
+        first.promptIDs = [0]
+        first.masks = [mask(["#."])]
+        first.maskLogits = [[1, -1]]
+
+        var second = MergedDetections()
+        second.scores = [0.8, 0.7]
+        second.promptIDs = [1, 1]
+        second.masks = [mask([".#"]), mask(["##"])]
+        second.maskLogits = [[-1, 1], [1, 1]]
+
+        let merged = DetectionDecoder.merge([first, second])
+        #expect(merged.count == 3)
+        #expect(merged.promptIDs == [0, 1, 1])
+        #expect(merged.scores == [0.9, 0.8, 0.7])
+    }
+}

From 97f516b436e3f9115ee36d03f65f42b60e31301a Mon Sep 17 00:00:00 2001
From: Kevin Cheng <59463423+kevchengcodes@users.noreply.github.com>
Date: Tue, 15 Sep 2026 14:31:44 -0700
Subject: [PATCH 2/3] very minor performance improvements

---
 .../Runtime/BilinearResampler.swift           | 226 ++++++++++++++----
 .../Runtime/NDArray+Helpers.swift             |  74 ++++--
 .../FramePreprocessor.swift                   |  11 +-
 .../Postprocessing/MaskPostprocessor.swift    |  24 +-
 .../Session/MemoryBankPacker.swift            |   5 +-
 .../Tracking/TrackerLoop.swift                |  51 +++-
 .../NDArrayHelpersTests.swift                 |  39 ++-
 .../BilinearResamplerTests.swift              |  56 +++++
 8 files changed, 400 insertions(+), 86 deletions(-)

diff --git a/swift/Sources/CoreAIShared/Runtime/BilinearResampler.swift b/swift/Sources/CoreAIShared/Runtime/BilinearResampler.swift
index 9d245e4c..fb7c024a 100644
--- a/swift/Sources/CoreAIShared/Runtime/BilinearResampler.swift
+++ b/swift/Sources/CoreAIShared/Runtime/BilinearResampler.swift
@@ -9,9 +9,9 @@ import Foundation
 /// Separable bilinear resampling of a planar `Float` image, matching
 /// `torch.nn.functional.interpolate(mode: "bilinear", align_corners: false)`.
 ///
-/// Hand-written rather than delegating to `vImageScale_PlanarF`, whose high-quality path is a
-/// different kernel and drifts from PyTorch. Construct once per (source, destination) pair
-/// and reuse; the weight tables are the only setup cost.
+/// Construct once per (source, destination) pair and reuse; the weight tables are the only
+/// setup cost. Per-frame callers should use `resample(_:into:scratch:)` — the allocating
+/// overload is a convenience, not the fast path.
 ///
 /// `antialias` widens the filter when downsampling, the way PIL and
 /// `torchvision.transforms.Resize` do. Upsampling ignores it.
@@ -36,10 +36,14 @@ public struct BilinearResampler: Sendable {
         self.sourceHeight = sourceHeight
         self.destinationWidth = destinationWidth
         self.destinationHeight = destinationHeight
+        // Only the horizontal axis needs a control vector; the vertical pass walks whole
+        // contiguous rows and reads `starts`/`values` directly.
         self.horizontal = Weights(
-            sourceSize: sourceWidth, destinationSize: destinationWidth, antialias: antialias)
+            sourceSize: sourceWidth, destinationSize: destinationWidth, antialias: antialias,
+            buildControlVector: true)
         self.vertical = Weights(
-            sourceSize: sourceHeight, destinationSize: destinationHeight, antialias: antialias)
+            sourceSize: sourceHeight, destinationSize: destinationHeight, antialias: antialias,
+            buildControlVector: false)
     }
 
     /// True when the resampler would copy its input unchanged.
@@ -47,32 +51,106 @@ public struct BilinearResampler: Sendable {
         sourceWidth == destinationWidth && sourceHeight == destinationHeight
     }
 
-    /// Resample a row-major `sourceHeight × sourceWidth` buffer.
-    public func resample(_ source: [Float]) -> [Float] {
+    /// True when the horizontal pass has to go the long way round. See `resampleTransposing`.
+    ///
+    /// This is the common case. Only a two-tap resize whose ratio is a binary fraction avoids
+    /// it, which in practice means the tracker's 4x mask upsamples on a patch-16 export; a
+    /// patch-14 export scales by 3.5 and transposes throughout.
+    private var transposes: Bool { horizontal.maxTaps > 2 || !horizontal.controlIsExact }
+
+    /// Elements of caller-owned storage `resample(_:into:scratch:)` needs.
+    public var scratchCount: Int {
+        if isIdentity { return 0 }
+        if transposes {
+            // Vertical output, its transpose, and the horizontal output before transposing back.
+            return 2 * destinationHeight * sourceWidth + destinationWidth * destinationHeight
+        }
+        return sourceHeight * destinationWidth
+    }
+
+    /// Resample a row-major `sourceHeight × sourceWidth` buffer into caller-owned storage.
+    ///
+    /// `scratch` must hold at least `scratchCount` elements and may be reused across calls;
+    /// its contents are not meaningful afterwards. This is the overload the per-frame paths
+    /// use, since at video resolution every buffer here is megabytes.
+    public func resample(
+        _ source: UnsafeBufferPointer<Float>,
+        into destination: UnsafeMutableBufferPointer<Float>,
+        scratch: UnsafeMutableBufferPointer<Float>
+    ) {
         precondition(
             source.count >= sourceWidth * sourceHeight,
             "BilinearResampler expected \(sourceWidth * sourceHeight) samples, got \(source.count)")
-        if isIdentity { return Array(source.prefix(sourceWidth * sourceHeight)) }
+        precondition(
+            destination.count >= destinationWidth * destinationHeight,
+            "BilinearResampler needs a \(destinationWidth * destinationHeight) element "
+                + "destination, got \(destination.count)")
+        let input = source.baseAddress!
+        let output = destination.baseAddress!
+        if isIdentity {
+            output.update(from: input, count: sourceWidth * sourceHeight)
+            return
+        }
+        precondition(
+            scratch.count >= scratchCount,
+            "BilinearResampler needs \(scratchCount) elements of scratch, got \(scratch.count)")
+        let workspace = scratch.baseAddress!
+
+        if transposes {
+            resampleTransposing(input: input, output: output, workspace: workspace)
+            return
+        }
 
         // Horizontal first, so the vertical pass runs over the smaller of the two widths
         // when downscaling and the taps stay whole contiguous rows either way.
-        var intermediate = [Float](repeating: 0, count: sourceHeight * destinationWidth)
-        source.withUnsafeBufferPointer { input in
-            intermediate.withUnsafeMutableBufferPointer { output in
-                horizontal.applyAcrossRows(
-                    input: input.baseAddress!, inputStride: sourceWidth,
-                    output: output.baseAddress!, outputStride: destinationWidth,
-                    rowCount: sourceHeight)
-            }
-        }
+        horizontal.applyAcrossRows(
+            input: input, inputStride: sourceWidth,
+            output: workspace, outputStride: destinationWidth,
+            rowCount: sourceHeight)
+        vertical.applyDownColumns(
+            input: workspace, output: output, rowWidth: destinationWidth)
+    }
 
+    /// The path for everything `vDSP_vlint` cannot do exactly: an antialiased downsample,
+    /// whose widened filter reads a contiguous run of source columns from an irregularly
+    /// spaced start, and any resize whose control vector would lose precision, per
+    /// `Weights.controlIsExact`.
+    ///
+    /// Transposing turns the horizontal taps back into whole contiguous rows, so both axes
+    /// run through `applyDownColumns`. Vertical goes first because whichever axis shrinks
+    /// should shrink before the transposes have to move it.
+    private func resampleTransposing(
+        input: UnsafePointer<Float>,
+        output: UnsafeMutablePointer<Float>,
+        workspace: UnsafeMutablePointer<Float>
+    ) {
+        let rows = workspace
+        let transposed = rows + destinationHeight * sourceWidth
+        let columns = transposed + sourceWidth * destinationHeight
+
+        vertical.applyDownColumns(input: input, output: rows, rowWidth: sourceWidth)
+        // `vDSP_mtrans(A, _, C, _, M, N)` writes an M×N result from an N×M input.
+        vDSP_mtrans(
+            rows, 1, transposed, 1, vDSP_Length(sourceWidth), vDSP_Length(destinationHeight))
+        horizontal.applyDownColumns(
+            input: transposed, output: columns, rowWidth: destinationHeight)
+        vDSP_mtrans(
+            columns, 1, output, 1, vDSP_Length(destinationHeight),
+            vDSP_Length(destinationWidth))
+    }
+
+    /// Resample a row-major `sourceHeight × sourceWidth` buffer.
+    ///
+    /// Allocates both the result and the scratch on every call. Fine for one-shot use; use
+    /// `resample(_:into:scratch:)` on anything that runs per frame.
+    public func resample(_ source: [Float]) -> [Float] {
         var destination = [Float](repeating: 0, count: destinationHeight * destinationWidth)
-        intermediate.withUnsafeBufferPointer { input in
+        var scratch = [Float](repeating: 0, count: scratchCount)
+        source.withUnsafeBufferPointer { input in
             destination.withUnsafeMutableBufferPointer { output in
-                vertical.applyDownColumns(
-                    input: input.baseAddress!,
-                    output: output.baseAddress!,
-                    rowWidth: destinationWidth)
+                scratch.withUnsafeMutableBufferPointer { scratch in
+                    resample(input, into: output, scratch: scratch)
+                }
             }
         }
         return destination
@@ -95,8 +173,23 @@ private struct Weights: Sendable {
     let counts: [Int]
     /// `destinationSize * maxTaps` coefficients, normalized to sum to 1 per output.
     let values: [Float]
+    /// Source coordinate per output, the control vector `vDSP_vlint` interpolates from: the
+    /// same taps as `values`, in the form Accelerate can apply a whole row at a time. Built
+    /// only for the horizontal axis of a two-tap resize.
+    let positions: [Float]
+    /// First output whose second tap falls off the end of the row. See `applyAcrossRows`.
+    let clampedFrom: Int
+    /// True when `positions` drives `vDSP_vlint` to the same taps the `Double` weights carry.
+    ///
+    /// `vDSP_vlint` recovers the interpolation fraction from a single `Float` coordinate, so
+    /// its precision is set by the magnitude of that coordinate rather than by the fraction.
+    /// At video widths the fraction quantizes coarsely enough to shift a 0-255 sample by a
+    /// few hundredths of a code value — enough to flip `FramePreprocessor`'s rounding and
+    /// drift from torch. The error is exactly zero when the resize ratio is a binary
+    /// fraction, so this is checked per resize rather than assumed either way.
+    let controlIsExact: Bool
 
-    init(sourceSize: Int, destinationSize: Int, antialias: Bool) {
+    init(sourceSize: Int, destinationSize: Int, antialias: Bool, buildControlVector: Bool) {
         self.destinationSize = destinationSize
         let scale = Double(sourceSize) / Double(destinationSize)
 
@@ -133,6 +226,10 @@ private struct Weights: Sendable {
             self.starts = starts
             self.counts = counts
             self.values = values
+            // Multi-tap rows go through the transposing path, which needs no control vector.
+            self.positions = []
+            self.clampedFrom = destinationSize
+            self.controlIsExact = false
             return
         }
 
@@ -143,6 +240,8 @@ private struct Weights: Sendable {
         var starts = [Int](repeating: 0, count: destinationSize)
         var counts = [Int](repeating: 2, count: destinationSize)
         var values = [Float](repeating: 0, count: destinationSize * 2)
+        var positions = [Float](repeating: 0, count: buildControlVector ? destinationSize : 0)
+        var exact = buildControlVector
         for index in 0..<destinationSize {
             let position = max(0.0, scale * (Double(index) + 0.5) - 0.5)
             let low = min(Int(position), sourceSize - 1)
@@ -152,6 +251,16 @@ private struct Weights: Sendable {
             counts[index] = high == low ? 1 : 2
             values[index * 2] = Float(1.0 - fraction)
             values[index * 2 + 1] = Float(fraction)
+            if buildControlVector {
+                let control = Float(position)
+                positions[index] = control
+                // The clamped tail is filled rather than interpolated, so only the
+                // interpolated outputs — exactly those with `high != low` — matter here.
+                if high != low {
+                    let recovered = control - Float(low)
+                    if Int(control) != low || recovered != Float(fraction) { exact = false }
+                }
+            }
             if high == low {
                 // Last row/column: torch reuses the same sample for both taps, which is
                 // the same as folding both weights onto it.
@@ -162,38 +271,52 @@ private struct Weights: Sendable {
         self.starts = starts
         self.counts = counts
         self.values = values
+        self.positions = positions
+        self.controlIsExact = exact
+        // `vDSP_vlint` reads `A[trunc(p) + 1]` unconditionally, so outputs landing on the
+        // last source sample would read one element past the row. Positions rise with the
+        // index, so those are always a trailing run: find where it starts and fill it
+        // instead. The bound uses the rounded `Float`, since that is what `vDSP_vlint`
+        // truncates.
+        self.clampedFrom =
+            buildControlVector
+            ? (positions.firstIndex { $0 >= Float(sourceSize - 1) } ?? destinationSize)
+            : destinationSize
     }
 
-    /// Resample each row independently. Weights vary per output column, so this is a
-    /// gather-dot and stays scalar.
+    /// Resample each row independently, two Accelerate calls per row.
+    ///
+    /// Two-tap only: `vDSP_vlint` interpolates straight from a source coordinate, which is
+    /// both the weight table and the inner loop. Multi-tap resizes transpose instead and use
+    /// `applyDownColumns`.
     func applyAcrossRows(
         input: UnsafePointer<Float>, inputStride: Int,
         output: UnsafeMutablePointer<Float>, outputStride: Int,
         rowCount: Int
     ) {
-        starts.withUnsafeBufferPointer { starts in
-            counts.withUnsafeBufferPointer { counts in
-                values.withUnsafeBufferPointer { values in
-                    for row in 0..<rowCount {
-                        let sourceRow = input + row * inputStride
-                        let destinationRow = output + row * outputStride
-                        for index in 0..<destinationSize {
-                            let start = starts[index]
-                            let base = index * maxTaps
-                            var sum: Float = 0
-                            for tap in 0..<counts[index] {
-                                sum += values[base + tap] * sourceRow[start + tap]
-                            }
-                            destinationRow[index] = sum
-                        }
-                    }
+        precondition(maxTaps == 2, "applyAcrossRows is the two-tap path")
+        let interpolated = vDSP_Length(clampedFrom)
+        let clamped = vDSP_Length(destinationSize - clampedFrom)
+        let sourceLength = vDSP_Length(inputStride)
+        positions.withUnsafeBufferPointer { positions in
+            for row in 0..<rowCount {
+                let sourceRow = input + row * inputStride
+                let destinationRow = output + row * outputStride
+                if interpolated > 0 {
+                    vDSP_vlint(
+                        sourceRow, positions.baseAddress!, 1, destinationRow, 1,
+                        interpolated, sourceLength)
+                }
+                if clamped > 0 {
+                    vDSP_vfill(
+                        sourceRow + inputStride - 1, destinationRow + clampedFrom, 1, clamped)
                 }
             }
         }
     }
 
     /// Resample down the columns. Each tap is a whole contiguous row scaled by one
-    /// coefficient, so this is a few `vDSP_vsma` calls per output row rather than a
+    /// coefficient, so this is a handful of vDSP calls per output row rather than a
     /// per-pixel loop.
     func applyDownColumns(
         input: UnsafePointer<Float>,
@@ -204,9 +327,26 @@ private struct Weights: Sendable {
         for index in 0..<destinationSize {
             let start = starts[index]
             let base = index * maxTaps
+            let sourceRow = input + start * rowWidth
             let destinationRow = output + index * rowWidth
+
+            if maxTaps == 2 {
+                guard counts[index] > 1 else {
+                    // Clamped edge: the table folds both weights onto one sample, so the
+                    // coefficient is exactly 1 and this is a copy.
+                    destinationRow.update(from: sourceRow, count: rowWidth)
+                    continue
+                }
+                // `A + f * (B - A)` in one pass, where vsmul plus vsma is two passes and two
+                // writes over what is the memory-bound axis when upsampling.
+                var fraction = values[base + 1]
+                vDSP_vintb(
+                    sourceRow, 1, sourceRow + rowWidth, 1, &fraction, destinationRow, 1, length)
+                continue
+            }
+
             var first = values[base]
-            vDSP_vsmul(input + start * rowWidth, 1, &first, destinationRow, 1, length)
+            vDSP_vsmul(sourceRow, 1, &first, destinationRow, 1, length)
             guard counts[index] > 1 else { continue }
             for tap in 1..<counts[index] {
                 var weight = values[base + tap]
diff --git a/swift/Sources/CoreAIShared/Runtime/NDArray+Helpers.swift b/swift/Sources/CoreAIShared/Runtime/NDArray+Helpers.swift
index b59c8bc3..b9ba19e1 100644
--- a/swift/Sources/CoreAIShared/Runtime/NDArray+Helpers.swift
+++ b/swift/Sources/CoreAIShared/Runtime/NDArray+Helpers.swift
@@ -162,9 +162,8 @@ public func fillFloatNDArray(_ array: inout NDArray, with elements: ArraySlice<F
 
 /// Copy `source` into `array` starting at logical element `elementOffset`.
 ///
-/// Unlike `fillNDArray`, which fills from index 0 through a per-element closure, this writes
-/// at an offset and `memcpy`s the whole run when the array is contiguous, falling back to a
-/// stride walk only when it is padded for hardware alignment.
+/// The other `fillNDArray` overloads start at index 0, so packing into slot `k` of a
+/// fixed-slot tensor needs this.
 ///
 /// - Precondition: `elementOffset + source.count` must not exceed the logical element count.
 public func copyIntoNDArray<T: BitwiseCopyable>(
@@ -180,18 +179,57 @@ public func copyIntoNDArray<T: BitwiseCopyable>(
     from source: [T]
 ) {
     guard !source.isEmpty else { return }
+    writeNDArrayRegion(
+        rawView, as: type, label: "copyIntoNDArray",
+        elementOffset: elementOffset, count: source.count,
+        bulk: { destination, count in
+            source.withUnsafeBufferPointer { destination.update(from: $0.baseAddress!, count: count) }
+        },
+        element: { source[$0] })
+}
+
+/// Write `value` into every logical element of `array` in `elementRange`.
+///
+/// The offset-aware sibling of `fillNDArray(_:as:with:)`, which can only write from element 0.
+public func fillNDArray<T: BitwiseCopyable>(
+    _ array: inout NDArray, as type: T.Type, elementRange: Range<Int>, with value: T
+) {
+    fillNDArray(array.mutableRawView(), as: type, elementRange: elementRange, with: value)
+}
+
+/// MutableRawView overload of the region fill.
+public func fillNDArray<T: BitwiseCopyable>(
+    _ rawView: consuming NDArray.MutableRawView, as type: T.Type, elementRange: Range<Int>,
+    with value: T
+) {
+    guard !elementRange.isEmpty else { return }
+    writeNDArrayRegion(
+        rawView, as: type, label: "fillNDArray",
+        elementOffset: elementRange.lowerBound, count: elementRange.count,
+        bulk: { destination, count in destination.update(repeating: value, count: count) },
+        element: { _ in value })
+}
+
+/// Write `count` logical elements into `rawView` starting at element `elementOffset`.
+///
+/// `bulk` takes the contiguous fast path; `element` feeds the stride walk used when the array
+/// is padded for hardware alignment.
+@inline(__always)
+private func writeNDArrayRegion<T: BitwiseCopyable>(
+    _ rawView: consuming NDArray.MutableRawView, as type: T.Type, label: StaticString,
+    elementOffset: Int, count: Int,
+    bulk: (UnsafeMutablePointer<T>, Int) -> Void,
+    element: (Int) -> T
+) {
     let view = rawView.view(as: type)
     view.withUnsafeMutablePointer { ptr, shape, strides in
         let capacity = shape.product
         precondition(
-            elementOffset >= 0 && elementOffset + source.count <= capacity,
-            "copyIntoNDArray: [\(elementOffset), \(elementOffset + source.count)) exceeds capacity \(capacity)"
-        )
+            elementOffset >= 0 && elementOffset + count <= capacity,
+            "\(label): [\(elementOffset), \(elementOffset + count)) exceeds capacity \(capacity)")
 
         if isContiguousRowMajor(shape: shape, strides: strides) {
-            source.withUnsafeBufferPointer { input in
-                (ptr + elementOffset).update(from: input.baseAddress!, count: source.count)
-            }
+            bulk(ptr + elementOffset, count)
             return
         }
 
@@ -204,8 +242,8 @@ public func copyIntoNDArray<T: BitwiseCopyable>(
         }
         var offset = 0
         for d in 0..<rank { offset += indices[d] * strides[d] }
-        for i in 0..<source.count {
-            ptr[offset] = source[i]
+        for i in 0..<count {
+            ptr[offset] = element(i)
             var dim = rank - 1
             while dim >= 0 {
                 indices[dim] += 1
@@ -219,20 +257,6 @@ public func copyIntoNDArray<T: BitwiseCopyable>(
     }
 }
 
-/// Write `value` into every logical element of `array` in `elementRange`.
-///
-/// Clears memory-bank slots that were valid on the previous call and are not on this one.
-/// Stale slots are harmless numerically, since the key mask suppresses them, but they make
-/// a parity divergence hard to reason about.
-public func clearNDArrayRegion<T: BitwiseCopyable>(
-    _ array: inout NDArray, as type: T.Type, elementRange: Range<Int>, value: T
-) {
-    guard !elementRange.isEmpty else { return }
-    copyIntoNDArray(
-        &array, as: type, elementOffset: elementRange.lowerBound,
-        from: [T](repeating: value, count: elementRange.count))
-}
-
 // MARK: - Flatten Helpers
 
 /// Flatten an NDArray output into `[Float]`, branching on its own scalar type.
diff --git a/swift/Sources/CoreAIVideoSegmenter/FramePreprocessor.swift b/swift/Sources/CoreAIVideoSegmenter/FramePreprocessor.swift
index f4d3d217..f9ee6446 100644
--- a/swift/Sources/CoreAIVideoSegmenter/FramePreprocessor.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/FramePreprocessor.swift
@@ -28,6 +28,8 @@ struct FramePreprocessor {
         var width = 0
         var height = 0
         var resampler: BilinearResampler?
+        /// Sized alongside the resampler, since it depends only on the source geometry.
+        var scratch: [Float] = []
     }
     private let cache = Cache()
 
@@ -99,7 +101,13 @@ struct FramePreprocessor {
             vDSP_vfltu8(
                 bytes.baseAddress! + channel, channelStride, &plane, 1, vDSP_Length(sourcePixels))
 
-            resized = resampler.resample(plane)
+            resized.withUnsafeMutableBufferPointer { output in
+                plane.withUnsafeBufferPointer { input in
+                    cache.scratch.withUnsafeMutableBufferPointer { scratch in
+                        resampler.resample(input, into: output, scratch: scratch)
+                    }
+                }
+            }
 
             // torchvision resizes a uint8 tensor as uint8: it interpolates and then
             // rounds back to integers, so its `pixel_values` land exactly on the 0-255
@@ -132,6 +140,7 @@ struct FramePreprocessor {
         cache.width = sourceWidth
         cache.height = sourceHeight
         cache.resampler = built
+        cache.scratch = [Float](repeating: 0, count: built.scratchCount)
         return built
     }
 }
diff --git a/swift/Sources/CoreAIVideoSegmenter/Postprocessing/MaskPostprocessor.swift b/swift/Sources/CoreAIVideoSegmenter/Postprocessing/MaskPostprocessor.swift
index 4e8426e7..2b785de6 100644
--- a/swift/Sources/CoreAIVideoSegmenter/Postprocessing/MaskPostprocessor.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/Postprocessing/MaskPostprocessor.swift
@@ -25,6 +25,18 @@ struct MaskPostprocessor {
     private let emitLowResolutionMasks: Bool
     private let resampler: BilinearResampler
 
+    /// Reused across every object on every frame: the upsampled mask is megabytes at video
+    /// resolution and is thrown away as soon as `MaskBitset` has thresholded it.
+    private final class Buffers {
+        var upsampled: [Float]
+        var scratch: [Float]
+        init(pixels: Int, scratchCount: Int) {
+            upsampled = [Float](repeating: 0, count: pixels)
+            scratch = [Float](repeating: 0, count: scratchCount)
+        }
+    }
+    private let buffers: Buffers
+
     init(
         lowResolutionSize: Int, videoWidth: Int, videoHeight: Int,
         emitLowResolutionMasks: Bool = false
@@ -40,6 +52,8 @@ struct MaskPostprocessor {
             sourceWidth: lowResolutionSize, sourceHeight: lowResolutionSize,
             destinationWidth: videoWidth, destinationHeight: videoHeight,
             antialias: false)
+        self.buffers = Buffers(
+            pixels: videoWidth * videoHeight, scratchCount: resampler.scratchCount)
     }
 
     /// Reads the session's prompt map and hidden-object set, so it shares the frame loop's
@@ -63,9 +77,15 @@ struct MaskPostprocessor {
         for objectID in candidates {
             guard !hidden.contains(objectID) else { continue }
             guard let logits = raw.maskLogitsByObjectID[objectID] else { continue }
-            let upsampled = resampler.resample(logits)
+            logits.withUnsafeBufferPointer { input in
+                buffers.upsampled.withUnsafeMutableBufferPointer { output in
+                    buffers.scratch.withUnsafeMutableBufferPointer { scratch in
+                        resampler.resample(input, into: output, scratch: scratch)
+                    }
+                }
+            }
             let mask = MaskBitset(
-                thresholding: upsampled, width: videoWidth, height: videoHeight)
+                thresholding: buffers.upsampled, width: videoWidth, height: videoHeight)
             // Objects whose mask upsampled to nothing are dropped, not reported empty.
             guard !mask.isEmpty else { continue }
 
diff --git a/swift/Sources/CoreAIVideoSegmenter/Session/MemoryBankPacker.swift b/swift/Sources/CoreAIVideoSegmenter/Session/MemoryBankPacker.swift
index 31b6091d..267b16bd 100644
--- a/swift/Sources/CoreAIVideoSegmenter/Session/MemoryBankPacker.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/Session/MemoryBankPacker.swift
@@ -316,9 +316,12 @@ final class MemoryBankPacker {
         #endif
     }
 
+    /// Wipe slots that were valid on the previous call and are not on this one. Stale slots
+    /// are harmless numerically, since the key mask suppresses them, but they make a parity
+    /// divergence hard to reason about.
     private func clearHalfRegion(_ array: inout NDArray, _ range: Range<Int>) {
         #if !((os(macOS) || targetEnvironment(macCatalyst)) && arch(x86_64))
-        clearNDArrayRegion(&array, as: Float16.self, elementRange: range, value: 0)
+        fillNDArray(&array, as: Float16.self, elementRange: range, with: 0)
         #else
         fatalError("Float16 is not supported on this platform")
         #endif
diff --git a/swift/Sources/CoreAIVideoSegmenter/Tracking/TrackerLoop.swift b/swift/Sources/CoreAIVideoSegmenter/Tracking/TrackerLoop.swift
index e1528c09..ceb25ae1 100644
--- a/swift/Sources/CoreAIVideoSegmenter/Tracking/TrackerLoop.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/Tracking/TrackerLoop.swift
@@ -3,6 +3,7 @@
 // Use of this source code is governed by a BSD-3-clause license that can
 // be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
 
+import Accelerate
 import CoreAI
 import CoreAIShared
 import Foundation
@@ -28,6 +29,10 @@ final class TrackerLoop {
     private let highResToMemory: BilinearResampler
     private let lowResToMemory: BilinearResampler
 
+    /// Scratch shared by all four resamplers: only one is ever in use at a time, and this
+    /// actor is the only thing touching them.
+    private var scratch: [Float]
+
     /// Scale and bias `_use_mask_as_output` applies to turn a binary mask into logits.
     private static let maskOutScale: Float = 20
     private static let maskOutBias: Float = -10
@@ -58,6 +63,25 @@ final class TrackerLoop {
             sourceWidth: shapes.lowResMaskSize, sourceHeight: shapes.lowResMaskSize,
             destinationWidth: shapes.memoryMaskSize, destinationHeight: shapes.memoryMaskSize,
             antialias: true)
+        self.scratch = [Float](
+            repeating: 0,
+            count: max(
+                lowResToImage.scratchCount, imageToLowRes.scratchCount,
+                highResToMemory.scratchCount, lowResToMemory.scratchCount))
+    }
+
+    /// Resample through the shared scratch, so the only per-object allocation left is the
+    /// destination the caller goes on to keep.
+    private func resample(
+        _ resampler: BilinearResampler, _ source: [Float], into destination: inout [Float]
+    ) {
+        source.withUnsafeBufferPointer { input in
+            destination.withUnsafeMutableBufferPointer { output in
+                scratch.withUnsafeMutableBufferPointer { scratch in
+                    resampler.resample(input, into: output, scratch: scratch)
+                }
+            }
+        }
     }
 
     struct Propagation {
@@ -282,12 +306,16 @@ final class TrackerLoop {
     /// the stored value is only re-read if the same frame is revisited. The image-resolution
     /// mask and the score are what the memory encoder consumes.
     private func maskAsOutput(_ mask: MaskBitset, maskFloats: [Float]) -> MaskAsOutput {
-        let upscaled = lowResToImage.resample(maskFloats)
-        var highResolution = [Float](repeating: 0, count: upscaled.count)
-        for index in upscaled.indices {
-            highResolution[index] = upscaled[index] * Self.maskOutScale + Self.maskOutBias
+        var highResolution = [Float](repeating: 0, count: highResPixels)
+        resample(lowResToImage, maskFloats, into: &highResolution)
+        var scale = Self.maskOutScale
+        var bias = Self.maskOutBias
+        highResolution.withUnsafeMutableBufferPointer {
+            vDSP_vsmsa(
+                $0.baseAddress!, 1, &scale, &bias, $0.baseAddress!, 1, vDSP_Length($0.count))
         }
-        let lowResolution = imageToLowRes.resample(highResolution)
+        var lowResolution = [Float](repeating: 0, count: lowResPixels)
+        resample(imageToLowRes, highResolution, into: &lowResolution)
         // `is_obj_appearing` tests the *prompt* mask, not the resampled one.
         let appearing = !mask.isEmpty
         return MaskAsOutput(
@@ -324,10 +352,15 @@ final class TrackerLoop {
             // resolutions depending on the caller. A traced graph takes one, so the host
             // normalizes to `memoryMaskSize` first. Both callers resize *up*, where
             // antialiasing is a no-op, so this stays a single plain bilinear pass.
-            let mask =
-                alreadyAtMemoryResolution
-                ? highResolutionMasks[position]
-                : resampler.resample(highResolutionMasks[position])
+            let mask: [Float]
+            if alreadyAtMemoryResolution {
+                mask = highResolutionMasks[position]
+            } else {
+                var resampled = [Float](
+                    repeating: 0, count: shapes.memoryMaskSize * shapes.memoryMaskSize)
+                resample(resampler, highResolutionMasks[position], into: &resampled)
+                mask = resampled
+            }
 
             let encoded = try await engine.memoryEncode(
                 visionFeatureLevel2: features.level2,
diff --git a/swift/Tests/CoreAISharedTests/NDArrayHelpersTests.swift b/swift/Tests/CoreAISharedTests/NDArrayHelpersTests.swift
index 80979eab..6f24a186 100644
--- a/swift/Tests/CoreAISharedTests/NDArrayHelpersTests.swift
+++ b/swift/Tests/CoreAISharedTests/NDArrayHelpersTests.swift
@@ -221,7 +221,7 @@ struct StrideAwareFillReadTests {
     }
 }
 
-// MARK: - copyIntoNDArray / clearNDArrayRegion
+// MARK: - copyIntoNDArray / region fill
 
 /// Both of `copyIntoNDArray`'s paths need pinning: the contiguous `memcpy` and the stride
 /// walk that runs when the array is padded for hardware alignment.
@@ -280,13 +280,13 @@ struct CopyIntoNDArrayTests {
         #expect(readNDArray(array, as: Float.self, count: 8) == [Float](repeating: 7, count: 8))
     }
 
-    @Test("clearNDArrayRegion zeroes exactly the requested range")
+    @Test("Region fill zeroes exactly the requested range")
     func clearsRange() {
         // This is how the packer wipes slots that were valid on the previous call and are
         // not on this one. Over-clearing would destroy live memory in a lower slot.
         var array = NDArray(shape: [4, 4], scalarType: .float32)
         fillNDArray(&array, as: Float.self, with: (0..<16).map { Float($0 + 1) })
-        clearNDArrayRegion(&array, as: Float.self, elementRange: 4..<12, value: 0)
+        fillNDArray(&array, as: Float.self, elementRange: 4..<12, with: 0)
 
         let read = readNDArray(array, as: Float.self, count: 16)
         #expect(Array(read[0..<4]) == [1, 2, 3, 4])
@@ -294,11 +294,40 @@ struct CopyIntoNDArrayTests {
         #expect(Array(read[12..<16]) == [13, 14, 15, 16])
     }
 
-    @Test("Clearing an empty range does nothing")
+    @Test("Region fill writes a non-zero value through the strided path")
+    func fillsNonZeroWhenPadded() {
+        // Explicit strides so the padded branch is guaranteed to run; a non-zero value catches
+        // a fill that writes zeros regardless of `value`.
+        var array = NDArray(shape: [64, 4], scalarType: .float32, strides: [8, 1])
+        #expect(array.strides == [8, 1], "the padded layout must survive construction")
+        fillNDArray(&array, as: Float.self, count: 256) { _ in -1 }
+        fillNDArray(&array, as: Float.self, elementRange: 6..<250, with: 3.5)
+
+        let read = readNDArray(array, as: Float.self, count: 256)
+        #expect(Array(read[0..<6]) == [Float](repeating: -1, count: 6))
+        #expect(Array(read[6..<250]) == [Float](repeating: 3.5, count: 244))
+        #expect(Array(read[250..<256]) == [Float](repeating: -1, count: 6))
+    }
+
+    @Test("Copying at an offset survives a padded layout")
+    func copiesWhenPadded() {
+        // The `copyIntoNDArray` counterpart: same padded layout, pinning its stride walk.
+        var array = NDArray(shape: [64, 4], scalarType: .float32, strides: [8, 1])
+        fillNDArray(&array, as: Float.self, count: 256) { _ in -1 }
+        let payload = (0..<100).map { Float($0) * 0.25 }
+        copyIntoNDArray(&array, as: Float.self, elementOffset: 13, from: payload)
+
+        let read = readNDArray(array, as: Float.self, count: 256)
+        #expect(Array(read[0..<13]) == [Float](repeating: -1, count: 13))
+        #expect(Array(read[13..<113]) == payload)
+        #expect(Array(read[113..<256]) == [Float](repeating: -1, count: 143))
+    }
+
+    @Test("Filling an empty range does nothing")
     func clearEmptyRange() {
         var array = NDArray(shape: [2, 2], scalarType: .float32)
         fillNDArray(&array, as: Float.self, with: [1, 2, 3, 4] as [Float])
-        clearNDArrayRegion(&array, as: Float.self, elementRange: 2..<2, value: 0)
+        fillNDArray(&array, as: Float.self, elementRange: 2..<2, with: 0)
         #expect(readNDArray(array, as: Float.self, count: 4) == [1, 2, 3, 4] as [Float])
     }
 }
diff --git a/swift/Tests/VideoSegmenterTests/BilinearResamplerTests.swift b/swift/Tests/VideoSegmenterTests/BilinearResamplerTests.swift
index 424c1269..45a62f06 100644
--- a/swift/Tests/VideoSegmenterTests/BilinearResamplerTests.swift
+++ b/swift/Tests/VideoSegmenterTests/BilinearResamplerTests.swift
@@ -157,4 +157,60 @@ struct BilinearResamplerTests {
             }
         }
     }
+
+    /// The two internal paths — `vDSP_vlint` when the `Float` control vector is exact, and
+    /// the transposing one otherwise — have to agree, because which one a resize takes
+    /// depends on whether its ratio happens to be a binary fraction, and nothing about the
+    /// call site says so. Sizes here are wide enough for a `Float` coordinate to lose
+    /// fractional precision, which the 4x4 cases above cannot see.
+    @Test("Both internal paths agree on a wide source")
+    func pathsAgree() {
+        // A sawtooth, so neighbouring samples differ by the full range and any error in the
+        // interpolation fraction shows up at full scale instead of being averaged away.
+        func sawtooth(_ count: Int) -> [Float] { (0..<count).map { Float($0 % 37) } }
+
+        for (sourceSide, destinationWidth, destinationHeight) in [
+            (1920, 1008, 1008),  // FramePreprocessor, a non-binary ratio
+            (252, 1920, 1080),  // MaskPostprocessor, also non-binary
+            (252, 1008, 1008),  // exact ratio, so this one takes the vDSP_vlint path
+        ] {
+            let resampler = BilinearResampler(
+                sourceWidth: sourceSide, sourceHeight: sourceSide,
+                destinationWidth: destinationWidth, destinationHeight: destinationHeight)
+            let source = sawtooth(sourceSide * sourceSide)
+            let actual = resampler.resample(source)
+
+            // Recomputed here in Double, the way the weight tables are, so this is a check
+            // against the definition rather than against either path.
+            let horizontalScale = Double(sourceSide) / Double(destinationWidth)
+            let verticalScale = Double(sourceSide) / Double(destinationHeight)
+            func tap(_ index: Int, _ scale: Double) -> (Int, Int, Double) {
+                let position = max(0.0, scale * (Double(index) + 0.5) - 0.5)
+                let low = min(Int(position), sourceSide - 1)
+                let high = low < sourceSide - 1 ? low + 1 : low
+                return (low, high, position - Double(low))
+            }
+            var worst: Float = 0
+            for row in stride(from: 0, to: destinationHeight, by: 7) {
+                let (top, bottom, rowFraction) = tap(row, verticalScale)
+                for column in stride(from: 0, to: destinationWidth, by: 7) {
+                    let (left, right, columnFraction) = tap(column, horizontalScale)
+                    func sample(_ r: Int, _ c: Int) -> Double {
+                        Double(source[r * sourceSide + c])
+                    }
+                    let upper =
+                        sample(top, left) * (1 - columnFraction)
+                        + sample(top, right) * columnFraction
+                    let lower =
+                        sample(bottom, left) * (1 - columnFraction)
+                        + sample(bottom, right) * columnFraction
+                    let expected = Float(upper * (1 - rowFraction) + lower * rowFraction)
+                    worst = max(worst, abs(actual[row * destinationWidth + column] - expected))
+                }
+            }
+            #expect(
+                worst < 1e-4,
+                "\(sourceSide)^2 -> \(destinationWidth)x\(destinationHeight) drifted by \(worst)")
+        }
+    }
 }

From 59e748a09d346cd5816f7357e20161f085ee824d Mon Sep 17 00:00:00 2001
From: Kevin Cheng <59463423+kevchengcodes@users.noreply.github.com>
Date: Tue, 15 Sep 2026 16:30:19 -0700
Subject: [PATCH 3/3] no behavior changes: adding more guards, refactoring for
 DRY and KISS

---
 models/sam3_video/README.md                   |   2 +-
 .../Runtime/BilinearResampler.swift           |  22 +-
 .../FramePreprocessor.swift                   |  19 +-
 .../Postprocessing/ConnectedComponents.swift  |  30 +--
 .../Postprocessing/MaskPostprocessor.swift    |  26 +-
 .../Postprocessing/VideoOverlayRenderer.swift |  19 +-
 .../Session/MemoryBankPacker.swift            |  54 ++--
 .../Session/ObjectRegistry.swift              |   8 -
 .../Session/VideoInferenceSession.swift       |  58 +++--
 .../Tracking/Associator.swift                 |  11 +-
 .../Tracking/DetectionDecoder.swift           |   7 +-
 .../Tracking/FrameProcessor.swift             |  51 ++--
 .../Tracking/HotstartHeuristics.swift         | 107 ++++----
 .../Tracking/OcclusionSuppressor.swift        |  78 +++---
 .../Tracking/TrackerLoop.swift                |  71 ++----
 .../VideoSegmentationActor.swift              |   3 +-
 .../VideoSegmentationEngine.swift             | 234 +++++++++---------
 .../VideoSegmentationOutputs.swift            |  11 +-
 .../VideoSegmentationParameters.swift         |  29 +--
 .../CoreAIVideoSegmenter/VideoSegmenter.swift |  60 ++---
 .../VideoSegmenterBundle.swift                |  67 +++--
 .../AssociationTests.swift                    |  23 +-
 .../FramePreprocessingTests.swift             |   3 +-
 .../HotstartAndMemoryTests.swift              |  30 +--
 .../VideoSegmenterTests/MaskBitsetTests.swift |  30 +--
 .../MaskPostprocessorTests.swift              |   1 -
 .../TokenizerAndBundleTests.swift             | 177 ++++++++-----
 .../TrackingPrimitiveTests.swift              |  24 +-
 28 files changed, 599 insertions(+), 656 deletions(-)

diff --git a/models/sam3_video/README.md b/models/sam3_video/README.md
index a97038c1..134ab0a9 100644
--- a/models/sam3_video/README.md
+++ b/models/sam3_video/README.md
@@ -80,7 +80,7 @@ the whole video.
 | `tracker_encode` | no                         |
 | `text_encode`    | once per prompt, per video |
 
-## The Swift runtime (PENDING: this is design only)
+## The Swift runtime
 
 `swift/Sources/CoreAIVideoSegmenter` mimics the HF logic in Swift, and the
 `video-segmenter` tool drives it end to end:
diff --git a/swift/Sources/CoreAIShared/Runtime/BilinearResampler.swift b/swift/Sources/CoreAIShared/Runtime/BilinearResampler.swift
index fb7c024a..498fd58e 100644
--- a/swift/Sources/CoreAIShared/Runtime/BilinearResampler.swift
+++ b/swift/Sources/CoreAIShared/Runtime/BilinearResampler.swift
@@ -139,13 +139,13 @@ public struct BilinearResampler: Sendable {
             vDSP_Length(destinationWidth))
     }
 
-    /// Resample a row-major `sourceHeight × sourceWidth` buffer.
+    /// Resample into a caller-owned destination, reusing `scratch` across calls.
     ///
-    /// Allocates both the result and the scratch on every call. Fine for one-shot use; use
-    /// `resample(_:into:scratch:)` on anything that runs per frame.
-    public func resample(_ source: [Float]) -> [Float] {
-        var destination = [Float](repeating: 0, count: destinationHeight * destinationWidth)
-        var scratch = [Float](repeating: 0, count: scratchCount)
+    /// The array-level form of `resample(_:into:scratch:)`. Per-frame callers keep both
+    /// buffers alive and pay no allocation here.
+    public func resample(
+        _ source: [Float], into destination: inout [Float], scratch: inout [Float]
+    ) {
         source.withUnsafeBufferPointer { input in
             destination.withUnsafeMutableBufferPointer { output in
                 scratch.withUnsafeMutableBufferPointer { scratch in
@@ -153,6 +153,16 @@ public struct BilinearResampler: Sendable {
                 }
             }
         }
+    }
+
+    /// Resample a row-major `sourceHeight × sourceWidth` buffer.
+    ///
+    /// Allocates both the result and the scratch on every call. Fine for one-shot use; use
+    /// `resample(_:into:scratch:)` on anything that runs per frame.
+    public func resample(_ source: [Float]) -> [Float] {
+        var destination = [Float](repeating: 0, count: destinationHeight * destinationWidth)
+        var scratch = [Float](repeating: 0, count: scratchCount)
+        resample(source, into: &destination, scratch: &scratch)
         return destination
     }
 }
diff --git a/swift/Sources/CoreAIVideoSegmenter/FramePreprocessor.swift b/swift/Sources/CoreAIVideoSegmenter/FramePreprocessor.swift
index f9ee6446..d131ec97 100644
--- a/swift/Sources/CoreAIVideoSegmenter/FramePreprocessor.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/FramePreprocessor.swift
@@ -28,7 +28,6 @@ struct FramePreprocessor {
         var width = 0
         var height = 0
         var resampler: BilinearResampler?
-        /// Sized alongside the resampler, since it depends only on the source geometry.
         var scratch: [Float] = []
     }
     private let cache = Cache()
@@ -70,8 +69,7 @@ struct FramePreprocessor {
     /// Preprocess interleaved 8-bit samples directly.
     ///
     /// `channelStride` is 4 for RGBA and 3 for packed RGB. The second form is what the
-    /// preprocessing tests feed in, so they can hold the decoder constant and measure
-    /// only this stage.
+    /// preprocessing tests feed in, so they can hold the decoder constant.
     func preprocess(
         interleavedRGB bytes: [UInt8], width: Int, height: Int, channelStride: Int
     ) -> [Float] {
@@ -101,18 +99,11 @@ struct FramePreprocessor {
             vDSP_vfltu8(
                 bytes.baseAddress! + channel, channelStride, &plane, 1, vDSP_Length(sourcePixels))
 
-            resized.withUnsafeMutableBufferPointer { output in
-                plane.withUnsafeBufferPointer { input in
-                    cache.scratch.withUnsafeMutableBufferPointer { scratch in
-                        resampler.resample(input, into: output, scratch: scratch)
-                    }
-                }
-            }
+            resampler.resample(plane, into: &resized, scratch: &cache.scratch)
 
-            // torchvision resizes a uint8 tensor as uint8: it interpolates and then
-            // rounds back to integers, so its `pixel_values` land exactly on the 0-255
-            // grid (verified: every element is within 8e-6 of an integer). Skipping this
-            // leaves a uniform ~0.25-code-value bias against the reference.
+            // torchvision resizes a uint8 tensor as uint8: it interpolates and then rounds
+            // back to integers. Skipping this leaves a uniform ~0.25-code-value bias against
+            // the reference.
             vvnintf(&resized, resized, &elementCount)
 
             // Fold rescale and normalize into one affine pass: (x / 255 - m) / s.
diff --git a/swift/Sources/CoreAIVideoSegmenter/Postprocessing/ConnectedComponents.swift b/swift/Sources/CoreAIVideoSegmenter/Postprocessing/ConnectedComponents.swift
index 771d793f..22b151a8 100644
--- a/swift/Sources/CoreAIVideoSegmenter/Postprocessing/ConnectedComponents.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/Postprocessing/ConnectedComponents.swift
@@ -7,16 +7,14 @@ import Foundation
 
 /// 8-connected component labelling and the mask cleanup built on it.
 ///
-/// Port of `fill_holes_in_mask_scores` and `_get_connected_components_with_padding` in
-/// `modeling_sam3_video.py`. Upstream routes the labelling through an optional
-/// `kernels-community/cv-utils` CUDA kernel and, when it is not installed, returns fake
-/// component areas of `H*W + 1`, which makes both cleanup steps no-ops without saying so.
-/// This implementation is always present, so a bundle run here gets the cleanup the model
-/// was tuned with. Set ``VideoSegmentationParameters/fillHoleArea`` to 0 to reproduce a
-/// Python run that was missing the kernel.
+/// Port of `fill_holes_in_mask_scores` and `_get_connected_components_with_padding`. Upstream
+/// routes the labelling through an optional `kernels-community/cv-utils` CUDA kernel and,
+/// when it is not installed, returns fake component areas of `H*W + 1`, which silently
+/// no-ops both cleanup steps. This implementation is always present, so set
+/// ``VideoSegmentationParameters/fillHoleArea`` to 0 to reproduce a Python run that was
+/// missing the kernel.
 ///
-/// 8-connectivity matches SAM 2's `get_connected_components`, which documents it
-/// explicitly and is what `cc_2d` implements.
+/// 8-connectivity matches SAM 2's `get_connected_components`.
 enum ConnectedComponents {
     /// Per-pixel component area for the set pixels of `mask`. Unset pixels get 0.
     ///
@@ -30,8 +28,7 @@ enum ConnectedComponents {
         func find(_ start: Int32) -> Int32 {
             var node = start
             while parent[Int(node)] != node {
-                // Path halving: point each node at its grandparent while climbing. Keeps the
-                // trees flat without a second pass.
+                // Path halving: point each node at its grandparent while climbing.
                 parent[Int(node)] = parent[Int(parent[Int(node)])]
                 node = parent[Int(node)]
             }
@@ -41,8 +38,7 @@ enum ConnectedComponents {
             let rootA = find(a)
             let rootB = find(b)
             if rootA == rootB { return }
-            // Always attach the larger index under the smaller so roots stay stable and
-            // the labelling is deterministic.
+            // Attach the larger index under the smaller so the labelling is deterministic.
             if rootA < rootB { parent[Int(rootB)] = rootA } else { parent[Int(rootA)] = rootB }
         }
 
@@ -83,9 +79,6 @@ enum ConnectedComponents {
     /// remove_sprinkles=True)`. The two sentinel values (`0.1` and `-0.1`) are upstream's:
     /// the mask stays a logit field, so a filled hole becomes weakly positive rather than
     /// saturated.
-    ///
-    /// The foreground threshold is `min(maxArea, foregroundArea / 2)` and is recomputed after
-    /// hole filling, which is what keeps a genuinely tiny object from deleting itself.
     static func fillHoles(_ logits: inout [Float], width: Int, height: Int, maxArea: Int) {
         guard maxArea > 0 else { return }
         let count = width * height
@@ -99,8 +92,9 @@ enum ConnectedComponents {
             logits[index] = 0.1
         }
 
-        // Foreground: components of `logits > 0` up to the smaller of `maxArea` and half
-        // the mask's own area become weakly negative.
+        // Foreground: components of `logits > 0` up to the smaller of `maxArea` and half the
+        // mask's own area become weakly negative. Halving is what keeps a genuinely tiny
+        // object from deleting itself.
         var foreground = [Bool](repeating: false, count: count)
         var foregroundArea = 0
         for index in 0..<count where logits[index] > 0 {
diff --git a/swift/Sources/CoreAIVideoSegmenter/Postprocessing/MaskPostprocessor.swift b/swift/Sources/CoreAIVideoSegmenter/Postprocessing/MaskPostprocessor.swift
index 2b785de6..1dbc7392 100644
--- a/swift/Sources/CoreAIVideoSegmenter/Postprocessing/MaskPostprocessor.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/Postprocessing/MaskPostprocessor.swift
@@ -9,9 +9,9 @@ import Foundation
 
 /// Turns a frame's low-resolution mask logits into the objects a caller sees.
 ///
-/// Port of `Sam3VideoProcessor.postprocess_outputs`. Four steps, in this order, and the
-/// order matters: upsample to video resolution and binarize, drop empty and hidden
-/// objects, resolve overlaps within each prompt group, then derive boxes.
+/// Port of `Sam3VideoProcessor.postprocess_outputs`. Four steps, and the order matters:
+/// upsample to video resolution and binarize, drop empty and hidden objects, resolve
+/// overlaps within each prompt group, then derive boxes.
 struct MaskPostprocessor {
     /// Surviving objects plus, when asked for, the mask logits they came from.
     struct Postprocessed {
@@ -45,9 +45,8 @@ struct MaskPostprocessor {
         self.videoWidth = videoWidth
         self.videoHeight = videoHeight
         self.emitLowResolutionMasks = emitLowResolutionMasks
-        // Note: no antialiasing. Upstream calls `interpolate(..., mode="bilinear",
-        // align_corners=False)` here without the flag, unlike the resizes inside the
-        // tracker.
+        // No antialiasing: upstream calls `interpolate(..., mode="bilinear",
+        // align_corners=False)` here without the flag, unlike the resizes inside the tracker.
         self.resampler = BilinearResampler(
             sourceWidth: lowResolutionSize, sourceHeight: lowResolutionSize,
             destinationWidth: videoWidth, destinationHeight: videoHeight,
@@ -77,13 +76,7 @@ struct MaskPostprocessor {
         for objectID in candidates {
             guard !hidden.contains(objectID) else { continue }
             guard let logits = raw.maskLogitsByObjectID[objectID] else { continue }
-            logits.withUnsafeBufferPointer { input in
-                buffers.upsampled.withUnsafeMutableBufferPointer { output in
-                    buffers.scratch.withUnsafeMutableBufferPointer { scratch in
-                        resampler.resample(input, into: output, scratch: scratch)
-                    }
-                }
-            }
+            resampler.resample(logits, into: &buffers.upsampled, scratch: &buffers.scratch)
             let mask = MaskBitset(
                 thresholding: buffers.upsampled, width: videoWidth, height: videoHeight)
             // Objects whose mask upsampled to nothing are dropped, not reported empty.
@@ -99,12 +92,11 @@ struct MaskPostprocessor {
         guard !ids.isEmpty else { return Postprocessed() }
 
         // Boxes come from the masks before overlap resolution. Upstream computes
-        // `masks_to_boxes` and only then applies the non-overlap constraint, so a box can
-        // be slightly larger than the mask it labels. Kept that way for parity.
+        // `masks_to_boxes` and only then applies the non-overlap constraint, so a box can be
+        // slightly larger than the mask it labels. Kept that way for parity.
         let boxes = masks.map(\.boundingBox)
 
-        // Overlaps are resolved by tracker score, not detection score, and only within a
-        // prompt group: "person" and "pillow" are allowed to claim the same pixels.
+        // Overlaps are resolved by tracker score, not detection score.
         OcclusionSuppressor.applyObjectWiseNonOverlap(
             masks: &masks, scores: trackerScores, promptIDs: promptIDs)
 
diff --git a/swift/Sources/CoreAIVideoSegmenter/Postprocessing/VideoOverlayRenderer.swift b/swift/Sources/CoreAIVideoSegmenter/Postprocessing/VideoOverlayRenderer.swift
index 3435ecd2..c5c8e3f7 100644
--- a/swift/Sources/CoreAIVideoSegmenter/Postprocessing/VideoOverlayRenderer.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/Postprocessing/VideoOverlayRenderer.swift
@@ -10,9 +10,9 @@ import Foundation
 
 /// Draws a frame's tracked objects over the source image.
 ///
-/// Colours come from ``OverlayPalette/color(forID:)``, which is a pure function of the
-/// object id rather than of its position in the array. A track that survives an occlusion
-/// and comes back keeps its colour; one that appears alongside it does not steal it.
+/// Colours come from ``OverlayPalette/color(forID:)``, a pure function of the object id
+/// rather than of its position in the array, so a track that survives an occlusion keeps its
+/// colour.
 struct VideoOverlayRenderer {
     private let parameters: VideoSegmentationParameters
 
@@ -20,10 +20,8 @@ struct VideoOverlayRenderer {
         self.parameters = parameters
     }
 
-    /// Composite `objects` onto `frame`, returning a new image at the same size.
-    ///
-    /// Returns `frame` unchanged when there is nothing to draw, so a caller can pipe every
-    /// frame through this without special-casing empty ones.
+    /// Composite `objects` onto `frame`, returning a new image at the same size. Returns
+    /// `frame` unchanged when there is nothing to draw.
     func render(_ objects: [TrackedObject], onto frame: CGImage) -> CGImage {
         guard !objects.isEmpty else { return frame }
         let width = frame.width
@@ -43,8 +41,8 @@ struct VideoOverlayRenderer {
         }
 
         // Core Graphics puts the origin at the bottom left; masks and boxes are top-left.
-        // Flipping the whole context once here keeps every draw below in image
-        // coordinates, including the text, which would otherwise render upside down.
+        // Flipping the whole context once keeps every draw below in image coordinates,
+        // including the text, which would otherwise render upside down.
         context.translateBy(x: 0, y: CGFloat(height))
         context.scaleBy(x: 1, y: -1)
 
@@ -70,8 +68,7 @@ struct VideoOverlayRenderer {
     /// Build one translucent RGBA layer holding every object's fill.
     ///
     /// Composited as a single image rather than one draw per object: at 1080p with eight
-    /// tracks that is one blend instead of eight, and the per-object alpha blend below
-    /// gives the same result as stacking translucent layers.
+    /// tracks that is one blend instead of eight.
     private func maskOverlay(_ objects: [TrackedObject], width: Int, height: Int) -> CGImage? {
         let alpha = max(0, min(1, parameters.maskOpacity))
         guard alpha > 0 else { return nil }
diff --git a/swift/Sources/CoreAIVideoSegmenter/Session/MemoryBankPacker.swift b/swift/Sources/CoreAIVideoSegmenter/Session/MemoryBankPacker.swift
index 267b16bd..008e3282 100644
--- a/swift/Sources/CoreAIVideoSegmenter/Session/MemoryBankPacker.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/Session/MemoryBankPacker.swift
@@ -20,15 +20,15 @@ struct PackedMemory {
 
 /// Selects each object's eligible memories and packs them into the graph's fixed slots.
 ///
-/// HF builds the tracker's memory with a variable-length `torch.cat`, so its length changes
-/// every frame and per object. A traced graph takes one shape, so this uses a fixed bank plus
-/// an additive key mask. Packing valid entries at the front in any order is safe because
-/// cross-attention is permutation-invariant over keys, RoPE repeats the same per-slot pattern
-/// across spatial slots, and masked slots contribute nothing.
+/// HF builds the tracker's memory with a variable-length `torch.cat`. A traced graph takes
+/// one shape, so this uses a fixed bank plus an additive key mask. Packing valid entries at
+/// the front in any order is safe because cross-attention is permutation-invariant over keys,
+/// RoPE repeats the same per-slot pattern across spatial slots, and masked slots contribute
+/// nothing.
 ///
 /// `gatherMemoryFrames` and `objectPointers` are ports of `_gather_memory_frame_outputs` and
-/// `_get_object_pointers` in `modeling_sam3_tracker_video.py`, so which memories are eligible
-/// cannot drift from upstream even though the layout does.
+/// `_get_object_pointers`, so which memories are eligible cannot drift from upstream even
+/// though the layout does.
 @VideoSegmentationActor
 final class MemoryBankPacker {
     private let shapes: VideoSegmentationEngine.Shapes
@@ -37,16 +37,14 @@ final class MemoryBankPacker {
     /// Slots written on the previous call, so only those need clearing on this one.
     private var previousSpatialSlots = 0
     private var previousPointerSlots = 0
-    /// Emitted at most once per video; the condition is a property of the export, not of
-    /// the frame, so repeating it per frame per object would bury the log.
+    /// Emitted at most once per video: the condition is a property of the export, not of the
+    /// frame, so repeating it per object would bury the log.
     private var warnedAboutPointerOverflow = false
 
-    /// Slot capacities and per-slot element counts, all derived from the traced shapes.
     private var spatialSlotElements: Int { shapes.memoryTokenCount * shapes.memoryDim }
     private var pointerSlotElements: Int { shapes.hiddenDim }
 
     init(
-        engine: VideoSegmentationEngine,
         shapes: VideoSegmentationEngine.Shapes,
         parameters: VideoSegmentationParameters,
         packed: PackedMemory
@@ -121,8 +119,10 @@ final class MemoryBankPacker {
                     "Object \(objectIndex) has more than \(shapes.spatialSlots) spatial memories "
                         + "on frame \(frameIndex). Re-export with a larger --spatial-slots.")
             }
-            write(features, into: &packed.spatialMemory, slot: slot)
-            write(position, into: &packed.spatialMemoryPosition, slot: slot)
+            write(features, into: &packed.spatialMemory, slot: slot, stride: spatialSlotElements)
+            write(
+                position, into: &packed.spatialMemoryPosition, slot: slot,
+                stride: spatialSlotElements)
             temporalIndices[slot] = Int32(
                 Self.temporalIndex(forOffset: offset, numMaskmem: parameters.numMaskmem))
             valid[slot] = 1
@@ -154,7 +154,7 @@ final class MemoryBankPacker {
     ///
     /// Returns `(relativeTemporalOffset, output)` pairs. Conditioning frames carry offset 0;
     /// recent frames carry their distance. A `nil` output is a gap the caller skips, kept in
-    /// the list rather than filtered so the offsets stay attached to the right entries.
+    /// the list so the offsets stay attached to the right entries.
     static func gatherMemoryFrames(
         history: ObjectOutputHistory,
         frameIndex: Int,
@@ -168,8 +168,8 @@ final class MemoryBankPacker {
             (0, history.conditioning[$0])
         }
         // Most recent last, matching upstream's `range(num_maskmem - 1, 0, -1)`. Order is
-        // irrelevant to the packed bank but is preserved so a slot-by-slot comparison
-        // against a reference lines up.
+        // irrelevant to the packed bank but preserved so a slot-by-slot comparison against a
+        // reference lines up.
         for offset in stride(from: parameters.numMaskmem - 1, to: 0, by: -1) {
             let previousFrame = reverse ? frameIndex + offset : frameIndex - offset
             let output =
@@ -242,7 +242,9 @@ final class MemoryBankPacker {
         var temporalPositions = [Float](repeating: 0, count: shapes.ptrSlots)
         var valid = [Float](repeating: 0, count: shapes.ptrSlots)
         for (slot, offset) in offsets.enumerated() {
-            writePointer(pointers[slot], slot: slot)
+            write(
+                MemoryPayload(reading: pointers[slot], limit: pointerSlotElements),
+                into: &packed.objectPointers, slot: slot, stride: pointerSlotElements)
             temporalPositions[slot] = Float(offset) / maxTemporalDifference
             valid[slot] = 1
         }
@@ -295,22 +297,12 @@ final class MemoryBankPacker {
 
     // MARK: - Slot writes
 
-    private func write(_ payload: MemoryPayload, into array: inout NDArray, slot: Int) {
-        #if !((os(macOS) || targetEnvironment(macCatalyst)) && arch(x86_64))
-        copyIntoNDArray(
-            &array, as: Float16.self, elementOffset: slot * spatialSlotElements,
-            from: payload.values)
-        #else
-        fatalError("Float16 is not supported on this platform")
-        #endif
-    }
-
-    private func writePointer(_ pointer: NDArray, slot: Int) {
+    private func write(
+        _ payload: MemoryPayload, into array: inout NDArray, slot: Int, stride: Int
+    ) {
         #if !((os(macOS) || targetEnvironment(macCatalyst)) && arch(x86_64))
-        let values = readNDArray(pointer, as: Float16.self, count: pointerSlotElements)
         copyIntoNDArray(
-            &packed.objectPointers, as: Float16.self,
-            elementOffset: slot * pointerSlotElements, from: values)
+            &array, as: Float16.self, elementOffset: slot * stride, from: payload.values)
         #else
         fatalError("Float16 is not supported on this platform")
         #endif
diff --git a/swift/Sources/CoreAIVideoSegmenter/Session/ObjectRegistry.swift b/swift/Sources/CoreAIVideoSegmenter/Session/ObjectRegistry.swift
index 482cfe56..3487c97e 100644
--- a/swift/Sources/CoreAIVideoSegmenter/Session/ObjectRegistry.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/Session/ObjectRegistry.swift
@@ -21,7 +21,6 @@ struct ObjectRegistry {
     private var indexByID: [Int: Int] = [:]
 
     var count: Int { ids.count }
-    var isEmpty: Bool { ids.isEmpty }
 
     /// Index of `id`, registering it at the end if new.
     ///
@@ -41,8 +40,6 @@ struct ObjectRegistry {
 
     func id(at index: Int) -> Int { ids[index] }
 
-    func contains(_ id: Int) -> Bool { indexByID[id] != nil }
-
     /// Remove `id` and report the surviving indices in their old order, so callers can
     /// compact parallel arrays with `newStorage = survivors.map { oldStorage[$0] }`.
     ///
@@ -55,9 +52,4 @@ struct ObjectRegistry {
         indexByID = Dictionary(uniqueKeysWithValues: ids.enumerated().map { ($1, $0) })
         return survivors
     }
-
-    mutating func removeAll() {
-        ids.removeAll()
-        indexByID.removeAll()
-    }
 }
diff --git a/swift/Sources/CoreAIVideoSegmenter/Session/VideoInferenceSession.swift b/swift/Sources/CoreAIVideoSegmenter/Session/VideoInferenceSession.swift
index 18cf425d..8ec53b44 100644
--- a/swift/Sources/CoreAIVideoSegmenter/Session/VideoInferenceSession.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/Session/VideoInferenceSession.swift
@@ -10,26 +10,25 @@ import Foundation
 /// Half-precision payload held on the host between frames.
 ///
 /// Encoded memory leaves `memory_encode` as fp16 and goes straight back into `tracker_step`
-/// as fp16, so it is never interpreted here, only stored and copied. Keeping it as `Float16`
-/// rather than widening to `Float` halves the memory bank's footprint.
+/// as fp16, so it is never interpreted here. Keeping it as `Float16` rather than widening
+/// halves the memory bank's footprint.
+///
+/// `limit` caps how much is read, for callers writing into a fixed-size slot: the packer
+/// copies `values` wholesale, so a longer-than-expected array would spill into the next slot.
 struct MemoryPayload: Sendable {
     #if !((os(macOS) || targetEnvironment(macCatalyst)) && arch(x86_64))
     let values: [Float16]
 
-    init(reading array: NDArray) {
-        let count = array.shape.reduce(1, *)
+    init(reading array: NDArray, limit: Int = .max) {
+        let count = min(array.shape.reduce(1, *), limit)
         self.values = readNDArray(array, as: Float16.self, count: count)
     }
-
-    var count: Int { values.count }
     #else
     let values: [Float]
 
-    init(reading array: NDArray) {
-        self.values = flattenAsFloat(array)
+    init(reading array: NDArray, limit: Int = .max) {
+        self.values = Array(flattenAsFloat(array).prefix(limit))
     }
-
-    var count: Int { values.count }
     #endif
 }
 
@@ -86,17 +85,26 @@ struct ObjectOutputHistory {
         conditioning[frame] = existing
     }
 
+    /// Attach a frame's encoded memory to whichever bucket holds it. A reconditioned object
+    /// was promoted to conditioning a moment ago, so neither bucket can be assumed.
+    mutating func attachMemory(
+        features: MemoryPayload, positionEncoding: MemoryPayload, at frame: Int
+    ) {
+        if conditioning[frame] != nil {
+            conditioning[frame]?.memoryFeatures = features
+            conditioning[frame]?.memoryPositionEncoding = positionEncoding
+        } else {
+            nonConditioning[frame]?.memoryFeatures = features
+            nonConditioning[frame]?.memoryPositionEncoding = positionEncoding
+        }
+    }
+
     /// Drop history that can no longer be read.
     ///
-    /// Upstream never prunes, which does not survive a long video. The window below is
-    /// derived from what the two readers can still reach:
-    ///
-    /// * `_gather_memory_frame_outputs` looks back at most `numMaskmem - 1` frames for
-    ///   spatial memory, so older non-conditioning entries can shed their mask memory.
-    /// * `_get_object_pointers` looks back at most `maxObjectPointers - 1` frames, so
-    ///   their pointers must survive that much longer.
-    /// * Conditioning entries are kept whole. `_get_object_pointers` iterates all of them,
-    ///   and there are few: one per seeding plus one per reconditioning.
+    /// Upstream never prunes, which does not survive a long video. The window is derived
+    /// from what the two readers can still reach: `_gather_memory_frame_outputs` looks back
+    /// `numMaskmem - 1` frames, `_get_object_pointers` looks back `maxObjectPointers - 1`.
+    /// Conditioning entries are kept whole — pointers iterate all of them, and there are few.
     mutating func prune(before frame: Int, memoryWindow: Int, pointerWindow: Int) {
         let memoryFloor = frame - memoryWindow
         let pointerFloor = frame - pointerWindow
@@ -111,8 +119,8 @@ struct ObjectOutputHistory {
         }
         for key in conditioningOrder where key < memoryFloor {
             // Keep the pointer and the memory (a conditioning frame can be selected from
-            // any distance), but the stored low-res mask is only read when that exact
-            // frame is revisited, which forward propagation never does.
+            // any distance), but the stored low-res mask is only read when that exact frame
+            // is revisited, which forward propagation never does.
             conditioning[key]?.predictedMasks = nil
         }
     }
@@ -173,8 +181,7 @@ final class VideoInferenceSession {
     // MARK: - Frame cache
 
     /// Tracker features for the frame being processed, matching HF's
-    /// `max_vision_features_cache_size` default of 1. The tracker reads them once per object,
-    /// all within a single frame.
+    /// `max_vision_features_cache_size` default of 1.
     var cachedFrameIndex: Int?
     var cachedFeatures: TrackerFeatures?
 
@@ -217,9 +224,8 @@ final class VideoInferenceSession {
 
     /// Remove an object and every trace of it, compacting the parallel storage.
     ///
-    /// Port of `Sam3VideoInferenceSession.remove_object`. Upstream resets the whole
-    /// session when the last object goes; that is equivalent to clearing here, and
-    /// clearing keeps prompt state that a reset would also need to preserve.
+    /// Port of `Sam3VideoInferenceSession.remove_object`. Upstream resets the whole session
+    /// when the last object goes; clearing here is equivalent and keeps prompt state.
     func removeObject(_ id: Int) {
         guard let survivors = registry.remove(id) else { return }
         histories = survivors.map { histories[$0] }
diff --git a/swift/Sources/CoreAIVideoSegmenter/Tracking/Associator.swift b/swift/Sources/CoreAIVideoSegmenter/Tracking/Associator.swift
index 73dfe8e5..c0f8b3c8 100644
--- a/swift/Sources/CoreAIVideoSegmenter/Tracking/Associator.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/Tracking/Associator.swift
@@ -11,8 +11,7 @@ import Foundation
 /// Port of `Sam3VideoModel._associate_det_trk`. The two IoU thresholds are easy to conflate:
 /// `assocIouThresh` (loose, 0.1) decides whether a detection is covered by some track and so
 /// is not new, while `trkAssocIouThresh` (strict, 0.5) decides whether a track was seen this
-/// frame and so is not unmatched. The same pair can be matched by the first test and unmatched
-/// by the second.
+/// frame. The same pair can be matched by the first test and unmatched by the second.
 enum Associator {
     struct Result {
         /// Detection indices that should become new objects.
@@ -45,7 +44,7 @@ enum Associator {
         if trackMasks.isEmpty {
             // Nothing to match against, so every detection is new. This branch skips the
             // `newDetThresh` score gate the general path applies, as upstream does; that is
-            // how the first frame seeds tracks from detections below the new-object threshold.
+            // how the first frame seeds tracks from sub-threshold detections.
             result.newDetectionIndices = Array(0..<detections.count)
             return result
         }
@@ -98,9 +97,9 @@ enum Associator {
                 continue
             }
 
-            // Reconditioning candidate: confident enough, overlapping enough, and mapped
-            // to its single best track. Later detections overwrite earlier ones for the
-            // same track, which is upstream's behaviour.
+            // Reconditioning candidate: confident enough, overlapping enough, and mapped to
+            // its single best track. Later detections overwrite earlier ones for the same
+            // track, which is upstream's behaviour.
             guard detections.scores[detection] >= parameters.highConfThresh else { continue }
             guard let best = row.indices.max(by: { row[$0] < row[$1] }) else { continue }
             if row[best] >= parameters.highIouThresh {
diff --git a/swift/Sources/CoreAIVideoSegmenter/Tracking/DetectionDecoder.swift b/swift/Sources/CoreAIVideoSegmenter/Tracking/DetectionDecoder.swift
index f3ae06a2..755df007 100644
--- a/swift/Sources/CoreAIVideoSegmenter/Tracking/DetectionDecoder.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/Tracking/DetectionDecoder.swift
@@ -81,12 +81,11 @@ enum DetectionDecoder {
         return merged
     }
 
-    /// Greedy mask-IoU non-maximum suppression, returning the surviving indices in
-    /// descending-score order.
+    /// Greedy mask-IoU non-maximum suppression, returning the surviving indices in input
+    /// order.
     ///
     /// Port of `nms_masks`, which prefilters by score and then defers to
-    /// `cv_utils_kernel.generic_nms`. That kernel is a standard greedy NMS over the
-    /// supplied IoU matrix; the caller here has already applied the score prefilter, so
+    /// `cv_utils_kernel.generic_nms`. The caller has already applied the score prefilter, so
     /// only the greedy pass remains.
     static func nonMaximumSuppression(
         masks: [MaskBitset], scores: [Float], iouThreshold: Float
diff --git a/swift/Sources/CoreAIVideoSegmenter/Tracking/FrameProcessor.swift b/swift/Sources/CoreAIVideoSegmenter/Tracking/FrameProcessor.swift
index bf1ff14e..4d89b0be 100644
--- a/swift/Sources/CoreAIVideoSegmenter/Tracking/FrameProcessor.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/Tracking/FrameProcessor.swift
@@ -78,9 +78,7 @@ final class FrameProcessor {
             trackerLogits = propagation.maskLogits
             trackerScoreLogits = propagation.objectScoreLogits
             for index in trackerLogits.indices {
-                ConnectedComponents.fillHoles(
-                    &trackerLogits[index], width: shapes.lowResMaskSize,
-                    height: shapes.lowResMaskSize, maxArea: parameters.fillHoleArea)
+                fillHoles(&trackerLogits[index])
             }
         }
 
@@ -116,6 +114,12 @@ final class FrameProcessor {
         var newScores: [Int: Float]
     }
 
+    private func fillHoles(_ logits: inout [Float]) {
+        ConnectedComponents.fillHoles(
+            &logits, width: shapes.lowResMaskSize, height: shapes.lowResMaskSize,
+            maxArea: parameters.fillHoleArea)
+    }
+
     // MARK: - Detection
 
     private func runDetection(
@@ -187,10 +191,9 @@ final class FrameProcessor {
         let existing = objectIDsSnapshot.count
         if existing + newIndices.count > parameters.maxNumObjects {
             let keepCount = max(0, parameters.maxNumObjects - existing)
-            plan.droppedDueToObjectLimit = newIndices.count - keepCount
             CLILogger.log(
                 "Frame \(frameIndex): hit max_num_objects (\(parameters.maxNumObjects)); dropping "
-                    + "\(plan.droppedDueToObjectLimit) of \(newIndices.count) new detections.")
+                    + "\(newIndices.count - keepCount) of \(newIndices.count) new detections.")
             newIndices =
                 newIndices
                 .sorted { detections.scores[$0] > detections.scores[$1] }
@@ -267,10 +270,9 @@ final class FrameProcessor {
     /// Where a reconditioned object's memory mask comes from.
     ///
     /// `trackerMask` is not "the tracker mask captured now" but "whatever the tracker mask is
-    /// when memory is encoded". Upstream stores a view into `tracker_low_res_masks_global`
-    /// here, and occlusion suppression mutates that tensor in place between capture and use, so
-    /// a reconditioned object that is also suppressed contributes a blanked mask. Holding a
-    /// copy taken before suppression would silently reinstate it.
+    /// when memory is encoded": occlusion suppression mutates that tensor in place between
+    /// capture and use, so holding a copy taken before suppression would silently reinstate a
+    /// mask upstream blanks.
     private enum ReconditionSource {
         case trackerMask
         case detectionMask([Float])
@@ -278,10 +280,9 @@ final class FrameProcessor {
 
     /// Port of `_prepare_recondition_masks`.
     ///
-    /// The two modes are opposites and the flag name reads backwards at a glance:
-    /// `reconditionOnTrkMasks == true` means "the detector agrees, so reinforce memory
-    /// with what the *tracker* produced"; false means "the detector disagrees, so overwrite
-    /// with the *detection*".
+    /// The flag name reads backwards: `reconditionOnTrkMasks == true` means "the detector
+    /// agrees, so reinforce memory with what the *tracker* produced"; false means "the
+    /// detector disagrees, so overwrite with the *detection*".
     private func prepareReconditionMasks(
         session: VideoInferenceSession,
         detections: MergedDetections,
@@ -292,9 +293,9 @@ final class FrameProcessor {
         var reconditioned: Set<Int> = []
         for (trackID, detectionIndex) in candidates.sorted(by: { $0.key < $1.key }) {
             guard let objectIndex = session.registry.existingIndex(of: trackID) else { continue }
-            // Note this compares a raw logit against a probability-shaped threshold, which
-            // is what upstream does; `tracker_obj_scores_global` is not passed through a
-            // sigmoid first. In practice it admits any object with a positive score.
+            // Upstream compares a raw logit against a probability-shaped threshold:
+            // `tracker_obj_scores_global` is not passed through a sigmoid first. In practice
+            // it admits any object with a positive score.
             guard objectIndex < trackerScoreLogits.count,
                 trackerScoreLogits[objectIndex] > parameters.highConfThresh
             else { continue }
@@ -357,8 +358,8 @@ final class FrameProcessor {
             }
         }
         // Sorted so removal order, and therefore the index renumbering, is deterministic.
-        // Upstream iterates a set, whose order is arbitrary; the end state is the same either
-        // way because each removal is independent.
+        // Upstream iterates a set, whose order is arbitrary; the end state is the same
+        // either way.
         for objectID in plan.newlyRemovedObjectIDs.sorted() {
             session.removeObject(objectID)
         }
@@ -368,11 +369,10 @@ final class FrameProcessor {
 
     /// Port of `build_outputs` plus the metadata bookkeeping at the end of `forward`.
     ///
-    /// Both zips below run the post-execution object list against pre-execution arrays, and
-    /// truncate at the shorter. That is upstream's own indexing: `build_outputs` and
-    /// `_det_track_one_frame` both read `inference_session.obj_ids` after the execution phase
-    /// has already mutated it. It is exact whenever nothing was removed this frame, since new
-    /// ids fall past the end of the tracker arrays and are filled in from detections below.
+    /// Both zips below run the post-execution object list against pre-execution arrays and
+    /// truncate at the shorter, which is upstream's own indexing. It is exact whenever
+    /// nothing was removed this frame, since new ids fall past the end of the tracker arrays
+    /// and are filled in from detections below.
     private func buildOutputs(
         session: VideoInferenceSession,
         frameIndex: Int,
@@ -393,9 +393,7 @@ final class FrameProcessor {
         // was seeded from it.
         for (objectID, detectionIndex) in zip(plan.newObjectIDs, plan.newDetectionIndices) {
             var mask = detections.maskLogits[detectionIndex]
-            ConnectedComponents.fillHoles(
-                &mask, width: shapes.lowResMaskSize, height: shapes.lowResMaskSize,
-                maxArea: parameters.fillHoleArea)
+            fillHoles(&mask)
             maskByObjectID[objectID] = mask
         }
 
@@ -428,7 +426,6 @@ final class FrameProcessor {
         return RawFrameOutput(
             frameIndex: frameIndex,
             maskLogitsByObjectID: maskByObjectID,
-            objectIDs: maskByObjectID.keys.sorted(),
             scoreByObjectID: session.scoreByObjectID,
             trackerScoreByObjectID: trackerScores,
             suppressedObjectIDs: session.suppressedObjectIDsByFrame[frameIndex] ?? [])
diff --git a/swift/Sources/CoreAIVideoSegmenter/Tracking/HotstartHeuristics.swift b/swift/Sources/CoreAIVideoSegmenter/Tracking/HotstartHeuristics.swift
index 48cc9100..0bddf86a 100644
--- a/swift/Sources/CoreAIVideoSegmenter/Tracking/HotstartHeuristics.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/Tracking/HotstartHeuristics.swift
@@ -11,13 +11,12 @@ import Foundation
 ///
 /// Port of `Sam3VideoModel._process_hotstart`. Both rules only fire for tracks that first
 /// appeared inside the hotstart window; a track older than that has earned the benefit of the
-/// doubt. The window is why output lags by `hotstartDelay` frames: a track removed on frame 20
-/// must never have been shown on frame 8.
+/// doubt.
 ///
-/// The keep-alive counter is a separate, always-on mechanism layered on the same
-/// bookkeeping: matched frames raise it toward `maxTrkKeepAlive`, unmatched ones lower it
-/// toward `minTrkKeepAlive`, and a track at or below zero is suppressed for the frame
-/// rather than removed outright.
+/// The keep-alive counter is a separate, always-on mechanism on the same bookkeeping: matched
+/// frames raise it toward `maxTrkKeepAlive`, unmatched ones lower it toward
+/// `minTrkKeepAlive`, and a track at or below zero is suppressed for the frame rather than
+/// removed outright.
 @VideoSegmentationActor
 enum HotstartHeuristics {
     /// Mutates the session's hotstart bookkeeping and returns the ids removed on this
@@ -37,6 +36,15 @@ enum HotstartHeuristics {
         // Everything before this frame is "outside the hotstart window".
         let hotstartBoundary =
             reverse ? frameIndex + parameters.hotstartDelay : frameIndex - parameters.hotstartDelay
+        /// Upstream's `obj_first_frame_idx[x]` raises for an object with no record; this
+        /// defaults to the current frame instead of failing the video.
+        func firstSeen(_ id: Int) -> Int { session.firstFrameByObjectID[id] ?? frameIndex }
+        func withinHotstart(_ id: Int) -> Bool {
+            reverse ? firstSeen(id) < hotstartBoundary : firstSeen(id) > hotstartBoundary
+        }
+        func isGone(_ id: Int) -> Bool {
+            session.removedObjectIDs.contains(id) || newlyRemoved.contains(id)
+        }
 
         // Step 1: record first sightings and seed keep-alive.
         for id in newObjectIDs {
@@ -46,64 +54,59 @@ enum HotstartHeuristics {
             session.keepAliveByObjectID[id] = parameters.initTrkKeepAlive
         }
 
+        // Matched frames raise the counter, unmatched ones lower it, each clamped to its own
+        // bound.
+        func adjustKeepAlive(_ id: Int, by delta: Int) {
+            let current = session.keepAliveByObjectID[id] ?? parameters.initTrkKeepAlive
+            session.keepAliveByObjectID[id] =
+                delta > 0
+                ? min(parameters.maxTrkKeepAlive, current + delta)
+                : max(parameters.minTrkKeepAlive, current + delta)
+        }
+
         // A track counts as matched if any detection claimed it. Using the
         // detection-to-track map avoids recomputing areas to distinguish "occluded" from
         // "gone", which is the distinction `emptyTrackIDs` already carries.
         var matched: Set<Int> = []
         for tracks in detectionToMatchedTrackIDs.values { matched.formUnion(tracks) }
-        for id in matched {
-            let current = session.keepAliveByObjectID[id] ?? parameters.initTrkKeepAlive
-            session.keepAliveByObjectID[id] = min(parameters.maxTrkKeepAlive, current + 1)
-        }
+        for id in matched { adjustKeepAlive(id, by: 1) }
         for id in unmatchedTrackIDs {
             session.unmatchedFramesByObjectID[id, default: []].append(frameIndex)
-            let current = session.keepAliveByObjectID[id] ?? parameters.initTrkKeepAlive
-            session.keepAliveByObjectID[id] = max(parameters.minTrkKeepAlive, current - 1)
+            adjustKeepAlive(id, by: -1)
         }
         if parameters.decreaseTrkKeepAliveForEmptyMasklets {
-            for id in emptyTrackIDs {
-                let current = session.keepAliveByObjectID[id] ?? parameters.initTrkKeepAlive
-                session.keepAliveByObjectID[id] = max(parameters.minTrkKeepAlive, current - 1)
-            }
+            for id in emptyTrackIDs { adjustKeepAlive(id, by: -1) }
         }
 
-        // Step 2: drop tracks unmatched for too long inside the window, and suppress
-        // tracks whose keep-alive has run out.
+        // Step 2: drop tracks unmatched for too long inside the window, and suppress tracks
+        // whose keep-alive has run out.
         //
-        // Sorted so removal is deterministic. Upstream iterates a `defaultdict`, whose
-        // order is insertion order and therefore also deterministic, but is not the same
-        // order; the two only differ when two objects would be removed on the same frame,
-        // and both are removed either way.
+        // Sorted so removal is deterministic. Upstream iterates a `defaultdict`, which is
+        // also deterministic but in a different order; the two only differ when two objects
+        // would be removed on the same frame, and both are removed either way.
         for id in session.unmatchedFramesByObjectID.keys.sorted() {
-            guard let frames = session.unmatchedFramesByObjectID[id] else { continue }
-            if session.removedObjectIDs.contains(id) || newlyRemoved.contains(id) { continue }
-            if frames.count >= parameters.hotstartUnmatchThresh {
-                let firstFrame = session.firstFrameByObjectID[id] ?? frameIndex
-                let withinHotstart =
-                    reverse ? firstFrame < hotstartBoundary : firstFrame > hotstartBoundary
-                if withinHotstart {
-                    newlyRemoved.insert(id)
-                    CLILogger.log(
-                        "Removing object \(id) at frame \(frameIndex): unmatched on frames \(frames)")
-                }
+            guard let frames = session.unmatchedFramesByObjectID[id], !isGone(id) else { continue }
+            if frames.count >= parameters.hotstartUnmatchThresh, withinHotstart(id) {
+                newlyRemoved.insert(id)
+                CLILogger.log(
+                    "Removing object \(id) at frame \(frameIndex): unmatched on frames \(frames)")
             }
             let keepAlive = session.keepAliveByObjectID[id] ?? parameters.initTrkKeepAlive
-            if keepAlive <= 0 && !parameters.suppressUnmatchedOnlyWithinHotstart
-                && !session.removedObjectIDs.contains(id) && !newlyRemoved.contains(id)
-            {
+            if keepAlive <= 0, !parameters.suppressUnmatchedOnlyWithinHotstart, !isGone(id) {
                 suppressed.insert(id)
             }
         }
 
         // Step 3: record overlaps. Two tracks overlap when the same detection claims both;
         // the later-appearing one is the candidate duplicate.
-        for tracks in detectionToMatchedTrackIDs.values.sorted(by: { ($0.first ?? -1) < ($1.first ?? -1) }) {
-            guard tracks.count >= 2 else { continue }
-            let firstAppearing =
-                reverse
-                ? tracks.max(by: { firstFrame(session, $0, frameIndex) < firstFrame(session, $1, frameIndex) })
-                : tracks.min(by: { firstFrame(session, $0, frameIndex) < firstFrame(session, $1, frameIndex) })
-            guard let anchor = firstAppearing else { continue }
+        let bySeenOrder: (Int, Int) -> Bool = { firstSeen($0) < firstSeen($1) }
+        for tracks in detectionToMatchedTrackIDs.values.sorted(by: {
+            ($0.first ?? -1) < ($1.first ?? -1)
+        }) {
+            guard tracks.count >= 2,
+                let anchor = reverse
+                    ? tracks.max(by: bySeenOrder) : tracks.min(by: bySeenOrder)
+            else { continue }
             for id in tracks where id != anchor {
                 let pair = VideoInferenceSession.OverlapPair(firstAppearing: anchor, duplicate: id)
                 session.overlapFramesByPair[pair, default: []].append(frameIndex)
@@ -115,13 +118,10 @@ enum HotstartHeuristics {
         for pair in session.overlapFramesByPair.keys.sorted(by: {
             ($0.firstAppearing, $0.duplicate) < ($1.firstAppearing, $1.duplicate)
         }) {
-            guard let frames = session.overlapFramesByPair[pair] else { continue }
             let id = pair.duplicate
-            if session.removedObjectIDs.contains(id) || newlyRemoved.contains(id) { continue }
-            let firstFrame = session.firstFrameByObjectID[id] ?? frameIndex
-            let withinHotstart =
-                reverse ? firstFrame < hotstartBoundary : firstFrame > hotstartBoundary
-            guard withinHotstart, frames.count >= parameters.hotstartDupThresh else { continue }
+            guard let frames = session.overlapFramesByPair[pair], !isGone(id),
+                withinHotstart(id), frames.count >= parameters.hotstartDupThresh
+            else { continue }
             newlyRemoved.insert(id)
             CLILogger.log(
                 "Removing object \(id) at frame \(frameIndex): overlaps object "
@@ -132,13 +132,4 @@ enum HotstartHeuristics {
         session.suppressedObjectIDsByFrame[frameIndex] = suppressed
         return newlyRemoved
     }
-
-    /// First frame an object was seen on. Upstream's `obj_first_frame_idx[x]` would raise for
-    /// an object with no record; this defaults to the current frame instead of failing the
-    /// video.
-    private static func firstFrame(
-        _ session: VideoInferenceSession, _ id: Int, _ frameIndex: Int
-    ) -> Int {
-        session.firstFrameByObjectID[id] ?? frameIndex
-    }
 }
diff --git a/swift/Sources/CoreAIVideoSegmenter/Tracking/OcclusionSuppressor.swift b/swift/Sources/CoreAIVideoSegmenter/Tracking/OcclusionSuppressor.swift
index 4f418855..1aaa86a3 100644
--- a/swift/Sources/CoreAIVideoSegmenter/Tracking/OcclusionSuppressor.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/Tracking/OcclusionSuppressor.swift
@@ -8,21 +8,19 @@ import Foundation
 
 /// Resolves objects that claim the same pixels.
 ///
-/// Three related rules, all ported from `Sam3VideoModel`, applied at different points and
-/// on different data:
+/// Three rules ported from `Sam3VideoModel`, applied at different points and on different
+/// data:
 ///
 /// 1. ``suppressRecentlyOccluded``, before memory encoding, on tracker logits. When two
-///    objects overlap heavily, the one that was occluded more recently is assumed to be
-///    the drifting copy and is blanked.
+///    objects overlap heavily, the one occluded more recently is assumed to be the drifting
+///    copy and is blanked.
 /// 2. ``suppressAreaShrinkage``, also before memory encoding. Applies a pixel-level argmax
-///    and then drops any object that lost most of its area to it, on the reasoning that
-///    such an object was never really there.
+///    and drops any object that lost most of its area to it.
 /// 3. ``applyObjectWiseNonOverlap``, at output time, on binary masks and per-object scores
 ///    rather than logits.
 ///
 /// All three are enforced per prompt group: two prompts may legitimately return overlapping
-/// masks for the same pixels, and forcing them to compete would make "person" and "pillow"
-/// delete each other.
+/// masks, and forcing them to compete would make "person" and "pillow" delete each other.
 enum OcclusionSuppressor {
     /// Logit written over a suppressed mask. `sigmoid(-10)` is 4.5e-5, so it reads as
     /// background everywhere downstream without being an out-of-range sentinel.
@@ -39,14 +37,20 @@ enum OcclusionSuppressor {
     /// real frame index.
     static let alwaysOccluded = 100_000
 
+    /// Index groups that can contend, in prompt-id order. A group of one never competes.
+    private static func contendingGroups(_ promptIDs: [Int]) -> [[Int]] {
+        Set(promptIDs).sorted()
+            .map { group in promptIDs.indices.filter { promptIDs[$0] == group } }
+            .filter { $0.count > 1 }
+    }
+
     // MARK: - 1. Recent-occlusion suppression
 
     /// Blank objects that overlap an object occluded less recently than they were.
     ///
-    /// Port of `_suppress_overlapping_based_on_recent_occlusion`. Also updates each
-    /// object's last-occluded frame, which is the state the next frame's comparison reads:
-    /// an object counts as occluded this frame if its mask is empty *or* it was suppressed
-    /// here.
+    /// Port of `_suppress_overlapping_based_on_recent_occlusion`. Also updates each object's
+    /// last-occluded frame, which the next frame's comparison reads: an object counts as
+    /// occluded this frame if its mask is empty *or* it was suppressed here.
     ///
     /// - Parameters:
     ///   - logits: Tracker mask logits per object, mutated in place.
@@ -65,6 +69,10 @@ enum OcclusionSuppressor {
         parameters: VideoSegmentationParameters
     ) {
         guard !objectIDs.isEmpty else { return }
+        precondition(
+            masks.count == objectIDs.count && logits.count == objectIDs.count
+                && promptIDs.count == objectIDs.count,
+            "suppressRecentlyOccluded: logits, masks, objectIDs and promptIDs must be parallel")
 
         let lastOccluded = objectIDs.map { id in
             session.lastOccludedByObjectID[id]
@@ -72,9 +80,7 @@ enum OcclusionSuppressor {
         }
 
         var suppress = [Bool](repeating: false, count: objectIDs.count)
-        for group in Set(promptIDs).sorted() {
-            let members = promptIDs.indices.filter { promptIDs[$0] == group }
-            guard members.count > 1 else { continue }
+        for members in contendingGroups(promptIDs) {
             markSuppressed(
                 members: members, masks: masks, lastOccluded: lastOccluded,
                 threshold: parameters.suppressOverlappingOcclusionThreshold,
@@ -130,17 +136,22 @@ enum OcclusionSuppressor {
     /// Drop objects that lose most of their area to the pixel-level argmax.
     ///
     /// Port of `_suppress_object_pw_area_shrinkage`, run per prompt group. Returns the
-    /// original masks with whole objects blanked, not the de-overlapped masks; the argmax only
-    /// measures how much of each object was contested.
+    /// original masks with whole objects blanked, not the de-overlapped masks; the argmax
+    /// only measures how much of each object was contested.
     static func suppressAreaShrinkage(
         logits: inout [[Float]], promptIDs: [Int]
     ) {
         guard logits.count > 1 else { return }
-        for group in Set(promptIDs).sorted() {
-            let members = promptIDs.indices.filter { promptIDs[$0] == group }
-            guard members.count > 1 else { continue }
-
+        precondition(
+            promptIDs.count == logits.count,
+            "suppressAreaShrinkage: logits and promptIDs must be parallel")
+        for members in contendingGroups(promptIDs) {
             let pixelCount = logits[members[0]].count
+            // A pixel-level argmax is only defined over fields of the same extent, and every
+            // caller passes one low-resolution field per object.
+            precondition(
+                members.allSatisfy { logits[$0].count == pixelCount },
+                "suppressAreaShrinkage: logits in a prompt group must be the same length")
             // Winner per pixel, by raw logit. Ties go to the lowest index in the group,
             // matching `torch.argmax`.
             var winner = [Int](repeating: members[0], count: pixelCount)
@@ -178,8 +189,8 @@ enum OcclusionSuppressor {
     /// Give each contested pixel to the highest-scoring object in its prompt group.
     ///
     /// Port of `Sam3VideoProcessor._apply_object_wise_non_overlapping_constraints` with
-    /// `background_value = 0`. The scores here are per-object, not per-pixel, so the
-    /// winner of a contested region is the same everywhere the two overlap.
+    /// `background_value = 0`. The scores are per-object, not per-pixel, so the winner of a
+    /// contested region is the same everywhere the two overlap.
     ///
     /// Upstream compares `pixel_nonoverlap > 0`, so an object whose score is exactly zero
     /// loses every pixel, even uncontested ones. Reproduced by the `bestScore[pixel] > 0` test.
@@ -187,11 +198,20 @@ enum OcclusionSuppressor {
         masks: inout [MaskBitset], scores: [Float], promptIDs: [Int]
     ) {
         guard masks.count > 1 else { return }
-        for group in Set(promptIDs).sorted() {
-            let members = promptIDs.indices.filter { promptIDs[$0] == group }
-            guard members.count > 1 else { continue }
-
-            let pixelCount = masks[members[0]].width * masks[members[0]].height
+        precondition(
+            promptIDs.count == masks.count && scores.count == masks.count,
+            "applyObjectWiseNonOverlap: masks, scores and promptIDs must be parallel")
+        for members in contendingGroups(promptIDs) {
+            let width = masks[members[0]].width
+            let height = masks[members[0]].height
+            // Flat pixel indices are only comparable across masks of identical geometry.
+            // Checking both axes, not just the area: two masks with the same pixel count at
+            // different widths would stay in bounds while pitting unrelated locations
+            // against each other, which is a silent wrong answer rather than a crash.
+            precondition(
+                members.allSatisfy { masks[$0].width == width && masks[$0].height == height },
+                "applyObjectWiseNonOverlap: masks in a prompt group must share dimensions")
+            let pixelCount = width * height
             var bestScore = [Float](repeating: 0, count: pixelCount)
             var winner = [Int32](repeating: -1, count: pixelCount)
             // Strict `>` so ties keep the lowest group index, matching `torch.argmax`.
@@ -211,8 +231,6 @@ enum OcclusionSuppressor {
                         losses.append(pixel)
                     }
                 }
-                guard !losses.isEmpty else { continue }
-                let width = masks[member].width
                 for pixel in losses {
                     masks[member][pixel % width, pixel / width] = false
                 }
diff --git a/swift/Sources/CoreAIVideoSegmenter/Tracking/TrackerLoop.swift b/swift/Sources/CoreAIVideoSegmenter/Tracking/TrackerLoop.swift
index ceb25ae1..4c6b961b 100644
--- a/swift/Sources/CoreAIVideoSegmenter/Tracking/TrackerLoop.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/Tracking/TrackerLoop.swift
@@ -29,8 +29,7 @@ final class TrackerLoop {
     private let highResToMemory: BilinearResampler
     private let lowResToMemory: BilinearResampler
 
-    /// Scratch shared by all four resamplers: only one is ever in use at a time, and this
-    /// actor is the only thing touching them.
+    /// Scratch shared by all four resamplers: only one is ever in use at a time.
     private var scratch: [Float]
 
     /// Scale and bias `_use_mask_as_output` applies to turn a binary mask into logits.
@@ -75,13 +74,7 @@ final class TrackerLoop {
     private func resample(
         _ resampler: BilinearResampler, _ source: [Float], into destination: inout [Float]
     ) {
-        source.withUnsafeBufferPointer { input in
-            destination.withUnsafeMutableBufferPointer { output in
-                scratch.withUnsafeMutableBufferPointer { scratch in
-                    resampler.resample(input, into: output, scratch: scratch)
-                }
-            }
-        }
+        resampler.resample(source, into: &destination, scratch: &scratch)
     }
 
     struct Propagation {
@@ -197,7 +190,7 @@ final class TrackerLoop {
         try await encodeMemories(
             session: session, frameIndex: frameIndex, objectIndices: memoryIndices,
             highResolutionMasks: memoryMasks, scoreLogits: memoryScores,
-            fromMask: memoryFromMask, alreadyAtMemoryResolution: false)
+            fromMask: memoryFromMask)
 
         return propagation
     }
@@ -205,9 +198,8 @@ final class TrackerLoop {
     /// Encode memory for every object from the frame's final, de-overlapped masks.
     ///
     /// Port of `_tracker_update_memories`'s second half. Distinct from the pass inside
-    /// ``propagate`` in three ways: the masks are low-resolution rather than
-    /// image-resolution, the score is derived from mask area rather than from the decoder,
-    /// and binarization is always off.
+    /// ``propagate``: the masks are low-resolution, the score is derived from mask area
+    /// rather than from the decoder, and binarization is always off.
     func encodeFinalMemories(
         session: VideoInferenceSession,
         frameIndex: Int,
@@ -224,15 +216,14 @@ final class TrackerLoop {
             objectIndices: Array(maskLogits.indices),
             highResolutionMasks: maskLogits, scoreLogits: scores,
             fromMask: [Bool](repeating: false, count: maskLogits.count),
-            alreadyAtMemoryResolution: false, sourceIsLowResolution: true)
+            sourceIsLowResolution: true)
     }
 
     /// Seed tracks from detection masks, then re-run the tracker with memory encoding on.
     ///
-    /// Port of `_tracker_add_new_objects`. Two things here are upstream's and expensive: the
-    /// binarization is `>= 0.5` on raw mask logits rather than on probabilities, and the re-run
-    /// covers every object, not just the new ones, which also overwrites the memory the
-    /// planning phase just wrote, now conditioned on this frame.
+    /// Port of `_tracker_add_new_objects`. The re-run covers every object, not just the new
+    /// ones, which also overwrites the memory the planning phase just wrote — upstream's
+    /// behaviour, and the expensive part.
     func addNewObjects(
         session: VideoInferenceSession,
         frameIndex: Int,
@@ -301,10 +292,9 @@ final class TrackerLoop {
 
     /// The weight-free half of `_use_mask_as_output`.
     ///
-    /// The low-resolution output is computed for completeness but is effectively write-only
-    /// during forward propagation: `build_outputs` shows a new object its detection mask, and
-    /// the stored value is only re-read if the same frame is revisited. The image-resolution
-    /// mask and the score are what the memory encoder consumes.
+    /// The low-resolution output is effectively write-only during forward propagation:
+    /// `build_outputs` shows a new object its detection mask, and the stored value is only
+    /// re-read if the same frame is revisited.
     private func maskAsOutput(_ mask: MaskBitset, maskFloats: [Float]) -> MaskAsOutput {
         var highResolution = [Float](repeating: 0, count: highResPixels)
         resample(lowResToImage, maskFloats, into: &highResolution)
@@ -329,9 +319,8 @@ final class TrackerLoop {
     /// Encode one memory per object and attach it to that object's stored frame output.
     ///
     /// `binarize` is `any(fromMask)` across the batch, not per object: upstream computes
-    /// `is_mask_from_pts` once for the whole batch, so a single newly seeded object turns
-    /// binarization on for every object encoded on that frame. That coupling changes the
-    /// numbers, so it is preserved.
+    /// `is_mask_from_pts` once for the whole batch. That coupling changes the numbers, so it
+    /// is preserved.
     private func encodeMemories(
         session: VideoInferenceSession,
         frameIndex: Int,
@@ -339,7 +328,6 @@ final class TrackerLoop {
         highResolutionMasks: [[Float]],
         scoreLogits: [Float],
         fromMask: [Bool],
-        alreadyAtMemoryResolution: Bool,
         sourceIsLowResolution: Bool = false
     ) async throws {
         guard !objectIndices.isEmpty else { return }
@@ -352,15 +340,9 @@ final class TrackerLoop {
             // resolutions depending on the caller. A traced graph takes one, so the host
             // normalizes to `memoryMaskSize` first. Both callers resize *up*, where
             // antialiasing is a no-op, so this stays a single plain bilinear pass.
-            let mask: [Float]
-            if alreadyAtMemoryResolution {
-                mask = highResolutionMasks[position]
-            } else {
-                var resampled = [Float](
-                    repeating: 0, count: shapes.memoryMaskSize * shapes.memoryMaskSize)
-                resample(resampler, highResolutionMasks[position], into: &resampled)
-                mask = resampled
-            }
+            var mask = [Float](
+                repeating: 0, count: shapes.memoryMaskSize * shapes.memoryMaskSize)
+            resample(resampler, highResolutionMasks[position], into: &mask)
 
             let encoded = try await engine.memoryEncode(
                 visionFeatureLevel2: features.level2,
@@ -368,21 +350,10 @@ final class TrackerLoop {
                 objectScoreLogit: scoreLogits[position],
                 binarize: binarize)
 
-            // Attach to whichever bucket holds this frame. A reconditioned object was
-            // promoted to conditioning a moment ago, so this cannot assume either.
-            let memoryFeatures = MemoryPayload(reading: encoded.features)
-            let positionEncoding = MemoryPayload(reading: encoded.positionEncoding)
-            if session.histories[objectIndex].conditioning[frameIndex] != nil {
-                session.histories[objectIndex].conditioning[frameIndex]?.memoryFeatures =
-                    memoryFeatures
-                session.histories[objectIndex].conditioning[frameIndex]?.memoryPositionEncoding =
-                    positionEncoding
-            } else if session.histories[objectIndex].nonConditioning[frameIndex] != nil {
-                session.histories[objectIndex].nonConditioning[frameIndex]?.memoryFeatures =
-                    memoryFeatures
-                session.histories[objectIndex].nonConditioning[frameIndex]?
-                    .memoryPositionEncoding = positionEncoding
-            }
+            session.histories[objectIndex].attachMemory(
+                features: MemoryPayload(reading: encoded.features),
+                positionEncoding: MemoryPayload(reading: encoded.positionEncoding),
+                at: frameIndex)
         }
     }
 }
diff --git a/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationActor.swift b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationActor.swift
index 0971dc29..8305f7a6 100644
--- a/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationActor.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationActor.swift
@@ -9,8 +9,7 @@ import Foundation
 ///
 /// The loop is inherently sequential: frame N's tracker reads the memory frame N-1 wrote, and
 /// every stage shares one mutable `VideoInferenceSession`. Giving each component its own actor
-/// would mean passing that session across isolation boundaries it cannot safely cross, so they
-/// all share this one.
+/// would mean passing that session across isolation boundaries it cannot safely cross.
 ///
 /// ``VideoSegmentationEngine`` is deliberately not on this actor: it owns no per-frame state,
 /// so a caller can unload the asset without serializing against a running frame loop.
diff --git a/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationEngine.swift b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationEngine.swift
index 0be7b755..07c6a213 100644
--- a/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationEngine.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationEngine.swift
@@ -11,15 +11,6 @@ import Foundation
 ///
 /// Everything above this type is host logic: the inference session, the memory ring
 /// buffer, and the tracking heuristics. This is the only place that touches `AIModel`.
-///
-/// Two deliberate choices in the signatures below:
-///
-/// * Tensors that go straight from one graph to the next stay as `NDArray` handles rather
-///   than being flattened to `[Float]`. `vision_feat_0` alone is 2.6 M elements and is fed
-///   to `tracker_step` once per tracked object per frame, so a host round-trip would be
-///   repeated for every object.
-/// * `tracker_encode` also emits `vision_pos_0` and `vision_pos_1`, which no other
-///   entrypoint consumes. They are left unread.
 public actor VideoSegmentationEngine: ResourceManaging {
     /// Entrypoint names, in the order the exporter declares them.
     public enum Function {
@@ -53,8 +44,6 @@ public actor VideoSegmentationEngine: ResourceManaging {
         public let imageSize: Int
         /// Text token count `text_encode` was traced at.
         public let textSequenceLength: Int
-        /// Detector query count.
-        public let queryCount: Int
         /// Side of the detector's and tracker's low-resolution masks.
         public let lowResMaskSize: Int
         /// Side of the `memory_encode` mask input.
@@ -82,8 +71,7 @@ public actor VideoSegmentationEngine: ResourceManaging {
     /// Load and specialize the asset, then resolve its shapes.
     ///
     /// A static multi-function asset commits workspace for every declared function on the
-    /// first `loadFunction`, so all seven are resolved here rather than on demand; deferring
-    /// them would cost the same memory and add a first-use stall.
+    /// first `loadFunction`, so resolving all seven here costs no more memory than deferring.
     public func loadResources() async throws {
         guard loaded == nil else { return }
         let prepared = try await PreparedModel.prepare(at: modelURL)
@@ -132,30 +120,27 @@ public actor VideoSegmentationEngine: ResourceManaging {
 
     /// ViT backbone. `pixelValues` is planar CHW at `shapes.imageSize`, already normalized.
     public func imageEncode(pixelValues: [Float]) async throws -> NDArray {
-        var array = NDArray(descriptor: try arrayDescriptor(Function.imageEncode, input: "pixel_values"))
-        fillFloatNDArray(&array, with: pixelValues)
-        let outputs = try await invoke(Function.imageEncode, ["pixel_values": array])
-        return try output(outputs, "last_hidden_state", from: Function.imageEncode)
+        let outputs = try await invoke(
+            Function.imageEncode,
+            ["pixel_values": try input(Function.imageEncode, "pixel_values", pixelValues)])
+        return try outputs("last_hidden_state")
     }
 
     /// CLIP text tower. Run once per distinct prompt for the whole video.
     ///
     /// Returns the attention mask alongside the features because `detect` needs the same
-    /// mask on every frame, so there is no point rebuilding it per frame per prompt.
+    /// mask on every frame.
     public func textEncode(
         inputIDs: [Int32], attentionMask: [Int32]
     ) async throws -> PromptEncoding {
-        var ids = NDArray(descriptor: try arrayDescriptor(Function.textEncode, input: "input_ids"))
-        fillNDArray(&ids, as: Int32.self, with: inputIDs)
-        var mask = NDArray(
-            descriptor: try arrayDescriptor(Function.textEncode, input: "attention_mask"))
-        fillNDArray(&mask, as: Int32.self, with: attentionMask)
-
+        let mask = try input(Function.textEncode, "attention_mask", attentionMask)
         let outputs = try await invoke(
-            Function.textEncode, ["input_ids": ids, "attention_mask": mask])
-        return PromptEncoding(
-            textFeatures: try output(outputs, "text_features", from: Function.textEncode),
-            attentionMask: mask)
+            Function.textEncode,
+            [
+                "input_ids": try input(Function.textEncode, "input_ids", inputIDs),
+                "attention_mask": mask,
+            ])
+        return PromptEncoding(textFeatures: try outputs("text_features"), attentionMask: mask)
     }
 
     /// FPN + DETR + mask decoder, for one prompt.
@@ -170,10 +155,10 @@ public actor VideoSegmentationEngine: ResourceManaging {
                 "attention_mask": prompt.attentionMask,
             ])
         return DetectOutputs(
-            predictedMasks: try output(outputs, "pred_masks", from: Function.detect),
-            predictedBoxes: try output(outputs, "pred_boxes", from: Function.detect),
-            predictedLogits: try output(outputs, "pred_logits", from: Function.detect),
-            presenceLogits: try output(outputs, "presence_logits", from: Function.detect))
+            predictedMasks: try outputs("pred_masks"),
+            predictedBoxes: try outputs("pred_boxes"),
+            predictedLogits: try outputs("pred_logits"),
+            presenceLogits: try outputs("presence_logits"))
     }
 
     /// Tracker FPN neck plus the two pre-projected decoder levels.
@@ -181,10 +166,10 @@ public actor VideoSegmentationEngine: ResourceManaging {
         let outputs = try await invoke(
             Function.trackerEncode, ["last_hidden_state": lastHiddenState])
         return TrackerFeatures(
-            level0: try output(outputs, "vision_feat_0", from: Function.trackerEncode),
-            level1: try output(outputs, "vision_feat_1", from: Function.trackerEncode),
-            level2: try output(outputs, "vision_feat_2", from: Function.trackerEncode),
-            positionLevel2: try output(outputs, "vision_pos_2", from: Function.trackerEncode))
+            level0: try outputs("vision_feat_0"),
+            level1: try outputs("vision_feat_1"),
+            level2: try outputs("vision_feat_2"),
+            positionLevel2: try outputs("vision_pos_2"))
     }
 
     /// Memory attention plus the SAM mask decoder, for one object on one frame.
@@ -210,48 +195,38 @@ public actor VideoSegmentationEngine: ResourceManaging {
                 "ptr_valid": memory.pointerValid,
             ])
         return TrackerStepOutputs(
-            predictedMasks: try output(outputs, "pred_masks", from: Function.trackerStep),
-            highResolutionMasks: try output(outputs, "high_res_masks", from: Function.trackerStep),
-            objectPointer: try output(outputs, "object_pointer", from: Function.trackerStep),
-            objectScoreLogits: try output(
-                outputs, "object_score_logits", from: Function.trackerStep))
+            predictedMasks: try outputs("pred_masks"),
+            highResolutionMasks: try outputs("high_res_masks"),
+            objectPointer: try outputs("object_pointer"),
+            objectScoreLogits: try outputs("object_score_logits"))
     }
 
     /// Encode one predicted mask into a spatial memory slot.
     ///
-    /// `maskLogits` must already be at `shapes.memoryMaskSize`. Upstream `_encode_new_memory`
-    /// resizes whatever it is handed, and it is handed two different resolutions depending
-    /// on the caller; a traced graph accepts one, so normalizing is the host's job.
+    /// `maskLogits` must already be at `shapes.memoryMaskSize`: upstream `_encode_new_memory`
+    /// resizes whatever it is handed, but a traced graph accepts one resolution.
     ///
     /// `binarize` reproduces `is_mask_from_pts`, which upstream computes as `any(...)` over
-    /// the batch, so one newly seeded object turns it on for every object encoded on that
-    /// frame.
+    /// the batch, so one newly seeded object turns it on for every object on that frame.
     public func memoryEncode(
         visionFeatureLevel2: NDArray,
         maskLogits: [Float],
         objectScoreLogit: Float,
         binarize: Bool
     ) async throws -> EncodedMemory {
-        var mask = NDArray(descriptor: try arrayDescriptor(Function.memoryEncode, input: "mask_logits"))
-        fillFloatNDArray(&mask, with: maskLogits)
-        var score = NDArray(
-            descriptor: try arrayDescriptor(Function.memoryEncode, input: "object_score_logits"))
-        fillFloatNDArray(&score, with: [objectScoreLogit])
-        var flag = NDArray(
-            descriptor: try arrayDescriptor(Function.memoryEncode, input: "binarize_mask"))
-        fillFloatNDArray(&flag, with: [binarize ? 1 : 0])
-
+        let function = Function.memoryEncode
         let outputs = try await invoke(
-            Function.memoryEncode,
+            function,
             [
                 "vision_feat_2": visionFeatureLevel2,
-                "mask_logits": mask,
-                "object_score_logits": score,
-                "binarize_mask": flag,
+                "mask_logits": try input(function, "mask_logits", maskLogits),
+                "object_score_logits": try input(
+                    function, "object_score_logits", [objectScoreLogit]),
+                "binarize_mask": try input(function, "binarize_mask", [binarize ? 1 : 0] as [Float]),
             ])
         return EncodedMemory(
-            features: try output(outputs, "maskmem_features", from: Function.memoryEncode),
-            positionEncoding: try output(outputs, "maskmem_pos_enc", from: Function.memoryEncode))
+            features: try outputs("maskmem_features"),
+            positionEncoding: try outputs("maskmem_pos_enc"))
     }
 
     /// Seed a track from a detection mask, producing only its object pointer.
@@ -261,18 +236,16 @@ public actor VideoSegmentationEngine: ResourceManaging {
     public func trackerMaskInit(
         features: TrackerFeatures, maskInput: [Float]
     ) async throws -> NDArray {
-        var mask = NDArray(
-            descriptor: try arrayDescriptor(Function.trackerMaskInit, input: "mask_input"))
-        fillFloatNDArray(&mask, with: maskInput)
+        let function = Function.trackerMaskInit
         let outputs = try await invoke(
-            Function.trackerMaskInit,
+            function,
             [
                 "vision_feat_0": features.level0,
                 "vision_feat_1": features.level1,
                 "vision_feat_2": features.level2,
-                "mask_input": mask,
+                "mask_input": try input(function, "mask_input", maskInput),
             ])
-        return try output(outputs, "object_pointer", from: Function.trackerMaskInit)
+        return try outputs("object_pointer")
     }
 
     /// A zero-filled input array for `function`'s `input`, for the memory packer to fill.
@@ -282,26 +255,52 @@ public actor VideoSegmentationEngine: ResourceManaging {
 
     // MARK: - Invocation
 
-    private func invoke(_ name: String, _ inputs: [String: NDArray]) async throws
-        -> [String: NDArray]
-    {
+    /// One call's outputs, carrying the function name so a lookup can report it.
+    private struct FunctionOutputs {
+        let function: String
+        let arrays: [String: NDArray]
+
+        func callAsFunction(_ name: String) throws -> NDArray {
+            guard let array = arrays[name] else {
+                throw VideoSegmentationError.missingOutput(function: function, name: name)
+            }
+            return array
+        }
+    }
+
+    private func invoke(
+        _ name: String, _ inputs: [String: NDArray]
+    ) async throws -> FunctionOutputs {
         let state = try require()
-        try validate(name, inputs, against: state.descriptors[name]!)
+        let descriptor = state.descriptors[name]!
+        try validate(name, inputs, against: descriptor)
         var raw = try await state.functions[name]!.run(inputs: inputs)
-        var outputs: [String: NDArray] = [:]
-        for output in state.descriptors[name]!.outputNames {
+        var arrays: [String: NDArray] = [:]
+        for output in descriptor.outputNames {
             if let array = raw.remove(output)?.ndArray {
-                outputs[output] = array
+                arrays[output] = array
             }
         }
-        return outputs
+        return FunctionOutputs(function: name, arrays: arrays)
+    }
+
+    /// A zero-filled array shaped for `function`'s `input`, then filled with `values`.
+    private func input(_ function: String, _ name: String, _ values: [Float]) throws -> NDArray {
+        var array = NDArray(descriptor: try arrayDescriptor(function, input: name))
+        fillFloatNDArray(&array, with: values)
+        return array
+    }
+
+    private func input(_ function: String, _ name: String, _ values: [Int32]) throws -> NDArray {
+        var array = NDArray(descriptor: try arrayDescriptor(function, input: name))
+        fillNDArray(&array, as: Int32.self, with: values)
+        return array
     }
 
     /// Reject shape mismatches before they reach the runtime.
     ///
-    /// A static Core AI function handed a wrongly shaped input does not raise: it kills the
-    /// process with SIGKILL and no traceback. The descriptors are right here, so the check is
-    /// cheap insurance against a failure that is otherwise very hard to debug.
+    /// A static Core AI function handed a wrongly shaped input does not raise: it SIGKILLs
+    /// the process with no traceback.
     private func validate(
         _ name: String, _ inputs: [String: NDArray], against descriptor: InferenceFunctionDescriptor
     ) throws {
@@ -333,15 +332,6 @@ public actor VideoSegmentationEngine: ResourceManaging {
         return loaded
     }
 
-    private func output(
-        _ outputs: [String: NDArray], _ name: String, from function: String
-    ) throws -> NDArray {
-        guard let array = outputs[name] else {
-            throw VideoSegmentationError.missingOutput(function: function, name: name)
-        }
-        return array
-    }
-
     private func arrayDescriptor(_ function: String, input: String) throws -> NDArrayDescriptor {
         let state = try require()
         guard let functionDescriptor = state.descriptors[function],
@@ -357,53 +347,58 @@ public actor VideoSegmentationEngine: ResourceManaging {
 
     /// Read every geometric constant the host needs off the traced descriptors.
     ///
-    /// Nothing here is hardcoded from the 1008 export: a 336 "lite" variant would report its
-    /// own grid and the packer would follow. What is checked is internal agreement, because a
+    /// Nothing is hardcoded from the 1008 export: a 336 "lite" variant would report its own
+    /// grid and the packer would follow. What is checked is internal agreement, because a
     /// mismatch between two entrypoints is the failure mode that SIGKILLs.
+    ///
+    /// Every lookup that is about to be indexed states its expected rank, so a re-export that
+    /// changes a layout throws here rather than trapping on an out-of-range subscript.
     private static func resolveShapes(
         _ descriptors: [String: InferenceFunctionDescriptor]
     ) throws -> Shapes {
-        func shape(_ function: String, input: String) throws -> [Int] {
+        func checked(_ shape: [Int], _ rank: Int?, _ what: String) throws -> [Int] {
+            if let rank, shape.count != rank {
+                throw VideoSegmentationError.unsupportedGeometry(
+                    "\(what) has rank \(shape.count) \(shape); this runtime expects rank \(rank).")
+            }
+            return shape
+        }
+        func shape(_ function: String, input: String, rank: Int? = nil) throws -> [Int] {
             guard let descriptor = descriptors[function],
                 case .ndArray(let array) = descriptor.inputDescriptor(of: input)
             else {
                 throw VideoSegmentationError.unsupportedGeometry(
                     "\(function) has no array input '\(input)'.")
             }
-            return array.shape
+            return try checked(array.shape, rank, "\(function) input '\(input)'")
         }
-        func outputShape(_ function: String, _ name: String) throws -> [Int] {
+        func outputShape(_ function: String, _ name: String, rank: Int? = nil) throws -> [Int] {
             guard let descriptor = descriptors[function],
                 case .ndArray(let array) = descriptor.outputDescriptor(of: name)
             else {
                 throw VideoSegmentationError.unsupportedGeometry(
                     "\(function) has no array output '\(name)'.")
             }
-            return array.shape
+            return try checked(array.shape, rank, "\(function) output '\(name)'")
         }
 
-        let pixelValues = try shape(Function.imageEncode, input: "pixel_values")
-        guard pixelValues.count == 4, pixelValues[2] == pixelValues[3] else {
+        let pixelValues = try shape(Function.imageEncode, input: "pixel_values", rank: 4)
+        guard pixelValues[2] == pixelValues[3] else {
             throw VideoSegmentationError.unsupportedGeometry(
                 "image_encode expects a square [1, 3, S, S] input; got \(pixelValues).")
         }
-        let inputIDs = try shape(Function.textEncode, input: "input_ids")
-        let predictedLogits = try outputShape(Function.detect, "pred_logits")
-        let predictedMasks = try outputShape(Function.detect, "pred_masks")
-        let spatialMemory = try shape(Function.trackerStep, input: "spatial_memory")
-        let objectPointers = try shape(Function.trackerStep, input: "object_pointers")
-        let highResolution = try outputShape(Function.trackerStep, "high_res_masks")
-        let memoryMask = try shape(Function.memoryEncode, input: "mask_logits")
-
-        guard spatialMemory.count == 4 else {
-            throw VideoSegmentationError.unsupportedGeometry(
-                "tracker_step expects [slots, HW, 1, mem_dim] spatial memory; got \(spatialMemory).")
-        }
-        guard memoryMask.count == 4, memoryMask[2] == memoryMask[3] else {
+        let inputIDs = try shape(Function.textEncode, input: "input_ids", rank: 2)
+        let predictedMasks = try outputShape(Function.detect, "pred_masks", rank: 4)
+        let spatialMemory = try shape(Function.trackerStep, input: "spatial_memory", rank: 4)
+        let objectPointers = try shape(Function.trackerStep, input: "object_pointers", rank: 3)
+        let highResolution = try outputShape(Function.trackerStep, "high_res_masks", rank: 4)
+        let memoryMask = try shape(Function.memoryEncode, input: "mask_logits", rank: 4)
+
+        guard memoryMask[2] == memoryMask[3] else {
             throw VideoSegmentationError.unsupportedGeometry(
                 "memory_encode expects a square mask input; got \(memoryMask).")
         }
-        guard predictedMasks.count == 4, predictedMasks[2] == predictedMasks[3] else {
+        guard predictedMasks[2] == predictedMasks[3] else {
             throw VideoSegmentationError.unsupportedGeometry(
                 "detect expects square masks; got \(predictedMasks).")
         }
@@ -411,7 +406,6 @@ public actor VideoSegmentationEngine: ResourceManaging {
         let shapes = Shapes(
             imageSize: pixelValues[2],
             textSequenceLength: inputIDs[1],
-            queryCount: predictedLogits[1],
             lowResMaskSize: predictedMasks[2],
             memoryMaskSize: memoryMask[2],
             highResMaskSize: highResolution[2],
@@ -422,20 +416,27 @@ public actor VideoSegmentationEngine: ResourceManaging {
             ptrSlots: objectPointers[0])
 
         // Cross-entrypoint agreement. The tracker's low-res mask must line up with the
-        // detector's for association to compare them, and `memory_encode`'s score input has
-        // a trailing singleton that is easy to get wrong.
-        let trackerLowRes = try outputShape(Function.trackerStep, "pred_masks")
+        // detector's for association to compare them.
+        let trackerLowRes = try outputShape(Function.trackerStep, "pred_masks", rank: 4)
         guard trackerLowRes[2] == shapes.lowResMaskSize else {
             throw VideoSegmentationError.unsupportedGeometry(
                 "tracker_step emits \(trackerLowRes[2])px masks but detect emits "
                     + "\(shapes.lowResMaskSize)px; association compares the two.")
         }
-        let maskInit = try shape(Function.trackerMaskInit, input: "mask_input")
+        let maskInit = try shape(Function.trackerMaskInit, input: "mask_input", rank: 4)
         guard maskInit[2] == shapes.lowResMaskSize else {
             throw VideoSegmentationError.unsupportedGeometry(
                 "tracker_mask_init takes \(maskInit[2])px masks but detections are "
                     + "\(shapes.lowResMaskSize)px.")
         }
+        // `DetectionDecoder` thresholds the flattened logits and then slices `pred_masks` by
+        // the surviving indices, so one logit per mask is what keeps that slice in range.
+        let predictedLogits = try outputShape(Function.detect, "pred_logits")
+        guard predictedLogits.reduce(1, *) == predictedMasks[1] else {
+            throw VideoSegmentationError.unsupportedGeometry(
+                "detect emits pred_logits\(predictedLogits) but \(predictedMasks[1]) masks; "
+                    + "the decoder indexes one into the other.")
+        }
         let scoreInput = try shape(Function.memoryEncode, input: "object_score_logits")
         let scoreOutput = try outputShape(Function.trackerStep, "object_score_logits")
         guard scoreInput == scoreOutput else {
@@ -443,7 +444,7 @@ public actor VideoSegmentationEngine: ResourceManaging {
                 "memory_encode takes object_score_logits\(scoreInput) but tracker_step emits "
                     + "\(scoreOutput).")
         }
-        let encodedMemory = try outputShape(Function.memoryEncode, "maskmem_features")
+        let encodedMemory = try outputShape(Function.memoryEncode, "maskmem_features", rank: 3)
         guard encodedMemory[0] == shapes.memoryTokenCount, encodedMemory[2] == shapes.memoryDim
         else {
             throw VideoSegmentationError.unsupportedGeometry(
@@ -473,7 +474,8 @@ public struct DetectOutputs: Sendable {
     public let presenceLogits: NDArray
 }
 
-/// The four `tracker_encode` outputs anything downstream actually reads.
+/// The `tracker_encode` outputs anything downstream reads. `vision_pos_0` and `vision_pos_1`
+/// are also emitted but no entrypoint consumes them.
 public struct TrackerFeatures: Sendable {
     public let level0: NDArray
     public let level1: NDArray
diff --git a/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationOutputs.swift b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationOutputs.swift
index 86e85274..fc87c14c 100644
--- a/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationOutputs.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationOutputs.swift
@@ -41,9 +41,9 @@ public struct VideoSegmentationFrame: Sendable {
 
     /// Wall clock spent processing this frame.
     ///
-    /// Measured around the frame's own work, not between emissions. Hotstart holds the first
-    /// `hotstartDelay` results back and flushes the backlog at the end of the video, so timing
-    /// the gap between emissions would report that buffering rather than the model.
+    /// Measured around the frame's own work, not between emissions: hotstart holds the first
+    /// `hotstartDelay` results back, so timing the gap between emissions would report that
+    /// buffering rather than the model.
     public let processingTime: Duration
 }
 
@@ -52,8 +52,7 @@ public struct VideoSegmentationFrame: Sendable {
 /// Detections for one frame, merged across every prompt.
 ///
 /// Port of what `_merge_detections_from_prompts` returns, minus `bbox`: nothing downstream
-/// reads the detector's boxes. Association, reconditioning, seeding, and the output
-/// builder all work off `mask`, and the boxes the caller finally sees come from
+/// reads the detector's boxes, and the boxes the caller finally sees come from
 /// `masks_to_boxes` on the upsampled mask.
 struct MergedDetections {
     /// Low-resolution mask logits, one flat `size * size` buffer per detection.
@@ -78,7 +77,6 @@ struct TrackerUpdatePlan {
     var newlyRemovedObjectIDs: Set<Int> = []
     var trackIDToHighConfidenceDetection: [Int: Int] = [:]
     var reconditionedObjectIDs: Set<Int> = []
-    var droppedDueToObjectLimit = 0
 }
 
 /// The per-frame model output before postprocessing. Port of `Sam3VideoSegmentationOutput`.
@@ -86,7 +84,6 @@ struct RawFrameOutput {
     let frameIndex: Int
     /// Object id to low-resolution mask logits.
     var maskLogitsByObjectID: [Int: [Float]]
-    var objectIDs: [Int]
     var scoreByObjectID: [Int: Float]
     var trackerScoreByObjectID: [Int: Float]
     var suppressedObjectIDs: Set<Int>
diff --git a/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationParameters.swift b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationParameters.swift
index c3987a62..b2f55306 100644
--- a/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationParameters.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/VideoSegmentationParameters.swift
@@ -11,8 +11,7 @@ import Foundation
 /// The tracking fields mirror `transformers.Sam3VideoConfig` field for field, defaults
 /// included, because the exported asset holds only tensor kernels; every threshold below
 /// governs host-side logic that HF reads off the model config at load time. A bundle can
-/// override them through a `tracking` block in its `metadata.json`; see
-/// ``VideoSegmenterBundle``.
+/// override them through a `tracking` block in its `metadata.json`.
 public struct VideoSegmentationParameters: Sendable {
     // MARK: - Detection
 
@@ -22,9 +21,8 @@ public struct VideoSegmentationParameters: Sendable {
     /// Mask-IoU threshold for detection NMS. `det_nms_thresh`. Zero disables NMS.
     ///
     /// HF runs NMS through an optional `kernels-community/cv-utils` kernel and silently
-    /// keeps every above-threshold detection when it isn't installed. This runtime always
-    /// has NMS available, so set this to 0 when comparing against a Python run that was
-    /// missing the kernel.
+    /// keeps every above-threshold detection when it isn't installed. Set this to 0 when
+    /// comparing against a Python run that was missing the kernel.
     public var detNmsThresh: Float = 0.1
 
     /// Probability threshold for promoting a detection to a new tracked object.
@@ -56,11 +54,9 @@ public struct VideoSegmentationParameters: Sendable {
     /// replaces it with the detection mask (detector as correction).
     /// `recondition_on_trk_masks`.
     ///
-    /// This defaults to the checkpoint's value, not the class's. `Sam3VideoConfig` declares
-    /// `True`, but `facebook/sam3`'s `config.json` sets it to `False`, and it is the only
-    /// field where the two disagree. Getting it wrong is invisible until a reconditioning
-    /// frame lands, after which every frame's memory is conditioned on the wrong mask.
-    /// Bundles exported with a `tracking` block carry the real value and override this.
+    /// Defaults to the checkpoint's value, not the class's: `Sam3VideoConfig` declares `True`
+    /// but `facebook/sam3`'s `config.json` sets it to `False`, the only field where the two
+    /// disagree. Bundles exported with a `tracking` block carry the real value.
     public var reconditionOnTrkMasks: Bool = false
 
     // MARK: - Hotstart
@@ -103,10 +99,9 @@ public struct VideoSegmentationParameters: Sendable {
 
     // MARK: - Tracker memory geometry
 
-    // These three come from `Sam3TrackerVideoConfig`, not `Sam3VideoConfig`, and they
-    // decide which stored frames are eligible for the memory bank. The exported asset pins
-    // their sum (`spatial_slots` is `max_cond_frame_num + num_maskmem - 1`) but not the
-    // split, so they have to be carried separately.
+    // These three come from `Sam3TrackerVideoConfig`, not `Sam3VideoConfig`. The exported
+    // asset pins their sum (`spatial_slots` is `max_cond_frame_num + num_maskmem - 1`) but
+    // not the split, so they have to be carried separately.
 
     /// Total mask-memory frames: the current one plus `num_maskmem - 1` recent.
     /// `num_maskmem`.
@@ -123,8 +118,7 @@ public struct VideoSegmentationParameters: Sendable {
     /// Maximum area of a connected component that gets filled (background) or removed
     /// (foreground). `fill_hole_area`. Zero disables both.
     ///
-    /// Like ``detNmsThresh``, HF no-ops this without `kernels-community/cv-utils`. Set to
-    /// 0 to reproduce a Python run made without it.
+    /// Like ``detNmsThresh``, HF no-ops this without `kernels-community/cv-utils`.
     public var fillHoleArea: Int = 16
 
     // MARK: - Preprocessing
@@ -156,8 +150,7 @@ public struct VideoSegmentationParameters: Sendable {
     /// upsample to video size.
     ///
     /// Off by default because it is 82,944 floats per object per frame. On, it separates a
-    /// tracker disagreement from an upsampling one: matching low-resolution masks with
-    /// differing final masks means the two upsampled differently.
+    /// tracker disagreement from an upsampling one.
     public var emitLowResolutionMasks: Bool = false
 
     public init() {}
diff --git a/swift/Sources/CoreAIVideoSegmenter/VideoSegmenter.swift b/swift/Sources/CoreAIVideoSegmenter/VideoSegmenter.swift
index 2a1b5882..6ec86422 100644
--- a/swift/Sources/CoreAIVideoSegmenter/VideoSegmenter.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/VideoSegmenter.swift
@@ -27,10 +27,9 @@ import Foundation
 ///
 /// ## Hotstart delay
 ///
-/// SAM 3 buffers its first `hotstartDelay` frames (15 by default) before emitting
-/// anything, because a track it removes on frame 20 must never have been shown on frame 8.
-/// The stream honours that, which means the decoded frames have to be held too, bounded at
-/// 15 frames and roughly 124 MB at 1080p. Set `hotstartDelay` to 0 to disable both the
+/// SAM 3 buffers its first `hotstartDelay` frames (15 by default) before emitting anything,
+/// because a track it removes on frame 20 must never have been shown on frame 8. The decoded
+/// frames are held too, roughly 124 MB at 1080p. Set `hotstartDelay` to 0 to disable both the
 /// delay and the removal rules that need it.
 @VideoSegmentationActor
 public final class VideoSegmenter: ResourceManaging {
@@ -72,9 +71,8 @@ public final class VideoSegmenter: ResourceManaging {
             throw VideoSegmentationError.invalidConfiguration(
                 "Engine reported no shapes after loading.")
         }
-        // The bundle's declared geometry and the traced graph must agree. They come from
-        // the same export, so a mismatch means the metadata and the asset were paired by
-        // hand, worth failing loudly rather than packing memory to the wrong layout.
+        // The bundle's declared geometry and the traced graph must agree. They come from the
+        // same export, so a mismatch means they were paired by hand.
         guard resolved.imageSize == bundle.geometry.imageSize,
             resolved.spatialSlots == bundle.geometry.spatialSlots,
             resolved.ptrSlots == bundle.geometry.ptrSlots,
@@ -90,7 +88,7 @@ public final class VideoSegmenter: ResourceManaging {
 
         let packed = try await MemoryBankPacker.makePacked(engine: engine)
         let packer = try MemoryBankPacker(
-            engine: engine, shapes: resolved, parameters: parameters, packed: packed)
+            shapes: resolved, parameters: parameters, packed: packed)
         self.shapes = resolved
         self.packer = packer
         self.tracker = TrackerLoop(
@@ -114,29 +112,15 @@ public final class VideoSegmenter: ResourceManaging {
 
     /// Segment and track `prompts` through an already-decoded frame sequence.
     ///
-    /// The frames are consumed in the order given and their indices are their positions.
-    /// Use this for camera capture, image sequences, or to hold the video decoder constant:
-    /// AVFoundation and PyAV disagree by about 0.65 code values on average even on
-    /// colour-tagged media, which is enough to move a mask boundary.
+    /// The frames are consumed in the order given and their indices are their positions. Use
+    /// this to hold the video decoder constant: AVFoundation and PyAV disagree by about 0.65
+    /// code values on average even on colour-tagged media, enough to move a mask boundary.
     public nonisolated func segment(
         frames: [CGImage],
         prompts: [String],
         parameters overrides: VideoSegmentationParameters? = nil
     ) -> AsyncThrowingStream<VideoSegmentationFrame, Error> {
-        AsyncThrowingStream { continuation in
-            let task = Task {
-                do {
-                    try await run(
-                        source: .images(frames), prompts: prompts, maxFrames: nil,
-                        parameters: overrides ?? self.parameters,
-                        emit: { continuation.yield($0) })
-                    continuation.finish()
-                } catch {
-                    continuation.finish(throwing: error)
-                }
-            }
-            continuation.onTermination = { _ in task.cancel() }
-        }
+        stream(source: .images(frames), prompts: prompts, maxFrames: nil, overrides: overrides)
     }
 
     /// Segment and track `prompts` through the video at `url`, one result per frame.
@@ -151,12 +135,21 @@ public final class VideoSegmenter: ResourceManaging {
         prompts: [String],
         maxFrames: Int? = nil,
         parameters overrides: VideoSegmentationParameters? = nil
+    ) -> AsyncThrowingStream<VideoSegmentationFrame, Error> {
+        stream(source: .video(url), prompts: prompts, maxFrames: maxFrames, overrides: overrides)
+    }
+
+    private nonisolated func stream(
+        source: FrameSource,
+        prompts: [String],
+        maxFrames: Int?,
+        overrides: VideoSegmentationParameters?
     ) -> AsyncThrowingStream<VideoSegmentationFrame, Error> {
         AsyncThrowingStream { continuation in
             let task = Task {
                 do {
                     try await run(
-                        source: .video(url), prompts: prompts, maxFrames: maxFrames,
+                        source: source, prompts: prompts, maxFrames: maxFrames,
                         parameters: overrides ?? self.parameters,
                         emit: { continuation.yield($0) })
                     continuation.finish()
@@ -197,7 +190,7 @@ public final class VideoSegmenter: ResourceManaging {
 
         var written = 0
         // Encoding is serialized behind the writer actor while the next frame's inference
-        // runs, so the two overlap naturally without an explicit pipeline.
+        // runs, so the two overlap without an explicit pipeline.
         for try await frame in segment(
             videoAt: source, prompts: prompts, maxFrames: maxFrames, parameters: effective)
         {
@@ -213,9 +206,8 @@ public final class VideoSegmenter: ResourceManaging {
 
     /// Port of `Sam3VideoModel.propagate_in_video_iterator`, forward only.
     ///
-    /// Reverse propagation is plumbed through the heuristics but has no entry point here:
-    /// it needs the whole video resident so it can start from the last frame, which is the
-    /// opposite of how this streams.
+    /// Reverse propagation is plumbed through the heuristics but has no entry point here: it
+    /// needs the whole video resident, which is the opposite of how this streams.
     private func run(
         source: FrameSource,
         prompts: [String],
@@ -306,9 +298,9 @@ public final class VideoSegmenter: ResourceManaging {
             }
         }
 
-        // End of video: flush whatever the delay is still holding. These are postprocessed
-        // last on purpose, because `hotstartRemovedObjectIDs` has now seen every removal, so
-        // a track removed at the very end is hidden in the buffered frames too.
+        // End of video: flush whatever the delay is still holding. Postprocessed last on
+        // purpose, so `hotstartRemovedObjectIDs` has seen every removal and a track removed
+        // at the very end is hidden in the buffered frames too.
         for (raw, image, elapsed) in buffer {
             emit(finish(raw, image, elapsed))
         }
diff --git a/swift/Sources/CoreAIVideoSegmenter/VideoSegmenterBundle.swift b/swift/Sources/CoreAIVideoSegmenter/VideoSegmenterBundle.swift
index 08fa02d1..f81e4330 100644
--- a/swift/Sources/CoreAIVideoSegmenter/VideoSegmenterBundle.swift
+++ b/swift/Sources/CoreAIVideoSegmenter/VideoSegmenterBundle.swift
@@ -9,14 +9,12 @@ import Foundation
 /// A `kind: video_segmenter` model bundle: the asset, the tokenizer, and the slot
 /// geometry the host has to pack memory to.
 ///
-/// The `runtime` block is required. The host builds fixed-capacity memory-bank tensors
-/// whose shapes must match what the graph was traced with, and deriving those from a
-/// hardcoded default would break silently the moment somebody re-exports with
-/// `--spatial-slots`.
+/// The `runtime` block is required: the host builds fixed-capacity memory-bank tensors whose
+/// shapes must match what the graph was traced with, and a hardcoded default would break
+/// silently the moment somebody re-exports with `--spatial-slots`.
 ///
 /// The `tracking` block is optional and carries the `Sam3VideoConfig` thresholds. A bundle
-/// without it gets ``VideoSegmentationParameters``'s defaults, which are the upstream config's
-/// own defaults.
+/// without it gets ``VideoSegmentationParameters``'s defaults.
 public struct VideoSegmenterBundle: Sendable {
     public let bundle: ModelBundle
     public let modelURL: URL
@@ -81,35 +79,36 @@ public struct VideoSegmenterBundle: Sendable {
         else { return base }
 
         var parameters = base
-        tracking.scoreThresholdDetection.map { parameters.scoreThresholdDetection = $0 }
-        tracking.detNmsThresh.map { parameters.detNmsThresh = $0 }
-        tracking.newDetThresh.map { parameters.newDetThresh = $0 }
-        tracking.assocIouThresh.map { parameters.assocIouThresh = $0 }
-        tracking.trkAssocIouThresh.map { parameters.trkAssocIouThresh = $0 }
-        tracking.highConfThresh.map { parameters.highConfThresh = $0 }
-        tracking.highIouThresh.map { parameters.highIouThresh = $0 }
-        tracking.reconditionEveryNthFrame.map { parameters.reconditionEveryNthFrame = $0 }
-        tracking.reconditionOnTrkMasks.map { parameters.reconditionOnTrkMasks = $0 }
-        tracking.hotstartDelay.map { parameters.hotstartDelay = $0 }
-        tracking.hotstartUnmatchThresh.map { parameters.hotstartUnmatchThresh = $0 }
-        tracking.hotstartDupThresh.map { parameters.hotstartDupThresh = $0 }
-        tracking.suppressUnmatchedOnlyWithinHotstart.map {
-            parameters.suppressUnmatchedOnlyWithinHotstart = $0
+        func apply<T>(_ value: T?, _ field: WritableKeyPath<VideoSegmentationParameters, T>) {
+            if let value { parameters[keyPath: field] = value }
         }
-        tracking.initTrkKeepAlive.map { parameters.initTrkKeepAlive = $0 }
-        tracking.maxTrkKeepAlive.map { parameters.maxTrkKeepAlive = $0 }
-        tracking.minTrkKeepAlive.map { parameters.minTrkKeepAlive = $0 }
-        tracking.decreaseTrkKeepAliveForEmptyMasklets.map {
-            parameters.decreaseTrkKeepAliveForEmptyMasklets = $0
-        }
-        tracking.suppressOverlappingOcclusionThreshold.map {
-            parameters.suppressOverlappingOcclusionThreshold = $0
-        }
-        tracking.maxNumObjects.map { parameters.maxNumObjects = $0 }
-        tracking.fillHoleArea.map { parameters.fillHoleArea = $0 }
-        tracking.numMaskmem.map { parameters.numMaskmem = $0 }
-        tracking.maxCondFrameNum.map { parameters.maxCondFrameNum = $0 }
-        tracking.maxObjectPointers.map { parameters.maxObjectPointers = $0 }
+        apply(tracking.scoreThresholdDetection, \.scoreThresholdDetection)
+        apply(tracking.detNmsThresh, \.detNmsThresh)
+        apply(tracking.newDetThresh, \.newDetThresh)
+        apply(tracking.assocIouThresh, \.assocIouThresh)
+        apply(tracking.trkAssocIouThresh, \.trkAssocIouThresh)
+        apply(tracking.highConfThresh, \.highConfThresh)
+        apply(tracking.highIouThresh, \.highIouThresh)
+        apply(tracking.reconditionEveryNthFrame, \.reconditionEveryNthFrame)
+        apply(tracking.reconditionOnTrkMasks, \.reconditionOnTrkMasks)
+        apply(tracking.hotstartDelay, \.hotstartDelay)
+        apply(tracking.hotstartUnmatchThresh, \.hotstartUnmatchThresh)
+        apply(tracking.hotstartDupThresh, \.hotstartDupThresh)
+        apply(tracking.suppressUnmatchedOnlyWithinHotstart, \.suppressUnmatchedOnlyWithinHotstart)
+        apply(tracking.initTrkKeepAlive, \.initTrkKeepAlive)
+        apply(tracking.maxTrkKeepAlive, \.maxTrkKeepAlive)
+        apply(tracking.minTrkKeepAlive, \.minTrkKeepAlive)
+        apply(
+            tracking.decreaseTrkKeepAliveForEmptyMasklets,
+            \.decreaseTrkKeepAliveForEmptyMasklets)
+        apply(
+            tracking.suppressOverlappingOcclusionThreshold,
+            \.suppressOverlappingOcclusionThreshold)
+        apply(tracking.maxNumObjects, \.maxNumObjects)
+        apply(tracking.fillHoleArea, \.fillHoleArea)
+        apply(tracking.numMaskmem, \.numMaskmem)
+        apply(tracking.maxCondFrameNum, \.maxCondFrameNum)
+        apply(tracking.maxObjectPointers, \.maxObjectPointers)
         return parameters
     }
 
diff --git a/swift/Tests/VideoSegmenterTests/AssociationTests.swift b/swift/Tests/VideoSegmenterTests/AssociationTests.swift
index 95b894b3..b736d26c 100644
--- a/swift/Tests/VideoSegmenterTests/AssociationTests.swift
+++ b/swift/Tests/VideoSegmenterTests/AssociationTests.swift
@@ -59,15 +59,17 @@ struct AssociatorTests {
         #expect(result.emptyTrackIDs == [2])
     }
 
-    @Test("A detection covered by a track is not new")
-    func coveredDetectionIsNotNew() {
+    @Test("A detection covered by a track is not new, but may recondition it")
+    func coveredDetection() {
         let result = Associator.associate(
             detections: detections([(stripe(0..<5), 0.95, 0)]),
-            trackMasks: [stripe(0..<5)], trackIDs: [1], trackPromptIDs: [0],
+            trackMasks: [stripe(0..<5)], trackIDs: [7], trackPromptIDs: [0],
             parameters: .default)
         #expect(result.newDetectionIndices.isEmpty)
-        #expect(result.detectionToMatchedTrackIDs[0] == [1])
+        #expect(result.detectionToMatchedTrackIDs[0] == [7])
         #expect(result.unmatchedTrackIDs.isEmpty)
+        // Confident and well-overlapping, so it is also a reconditioning candidate.
+        #expect(result.trackIDToHighConfidenceDetection[7] == 0)
     }
 
     @Test("The loose and strict thresholds disagree independently")
@@ -96,15 +98,6 @@ struct AssociatorTests {
         #expect(result.unmatchedTrackIDs == [1])
     }
 
-    @Test("A confident, well-overlapping detection becomes a reconditioning candidate")
-    func reconditioningCandidate() {
-        let result = Associator.associate(
-            detections: detections([(stripe(0..<5), 0.95, 0)]),
-            trackMasks: [stripe(0..<5)], trackIDs: [7], trackPromptIDs: [0],
-            parameters: .default)
-        #expect(result.trackIDToHighConfidenceDetection[7] == 0)
-    }
-
     @Test("A new detection is never also a reconditioning candidate")
     func newDetectionsExcluded() {
         // `det_is_high_conf` is explicitly `& ~is_new_det` upstream: a detection cannot
@@ -191,8 +184,8 @@ struct OcclusionSuppressorTests {
     @Test("A zero-scored object loses even its uncontested pixels")
     func zeroScoreLosesEverything() {
         // Upstream tests `pixel_nonoverlap > 0` on a field built from the object's own
-        // score, so a score of exactly 0 fails the test everywhere. Surprising, but it is
-        // the behaviour, and a track only reaches 0 when it has no recorded score at all.
+        // score, so a score of exactly 0 fails the test everywhere. Surprising, but a track
+        // only reaches 0 when it has no recorded score at all.
         var masks = [MaskBitset(width: 4, height: 1), MaskBitset(width: 4, height: 1)]
         masks[0][0, 0] = true
         masks[1][3, 0] = true
diff --git a/swift/Tests/VideoSegmenterTests/FramePreprocessingTests.swift b/swift/Tests/VideoSegmenterTests/FramePreprocessingTests.swift
index 0e846c2d..c212448b 100644
--- a/swift/Tests/VideoSegmenterTests/FramePreprocessingTests.swift
+++ b/swift/Tests/VideoSegmenterTests/FramePreprocessingTests.swift
@@ -81,8 +81,7 @@ struct FramePreprocessingTests {
     @Test("Rounding onto the 0-255 grid is what torchvision does")
     func roundsOntoCodeValueGrid() {
         // Every output must be reachable as (n/255 - 0.5)/0.5 for integer n, which is what
-        // resizing a uint8 tensor and casting back produces. Dropping the round leaves a
-        // uniform quarter-code-value bias against the reference.
+        // resizing a uint8 tensor and casting back produces.
         let actual = preprocessor().preprocess(
             interleavedRGB: sourceRGB, width: 4, height: 3, channelStride: 3)
         for value in actual {
diff --git a/swift/Tests/VideoSegmenterTests/HotstartAndMemoryTests.swift b/swift/Tests/VideoSegmenterTests/HotstartAndMemoryTests.swift
index d327f600..0b556d58 100644
--- a/swift/Tests/VideoSegmenterTests/HotstartAndMemoryTests.swift
+++ b/swift/Tests/VideoSegmenterTests/HotstartAndMemoryTests.swift
@@ -89,8 +89,8 @@ struct HotstartTests {
 
     @Test("A long-established track is never removed by the unmatch rule")
     func sparesEstablishedTracks() {
-        // The whole point of the hotstart window: a track that predates it has earned the
-        // benefit of the doubt, however long the detector loses sight of it.
+        // The point of the hotstart window: a track that predates it has earned the benefit
+        // of the doubt, however long the detector loses sight of it.
         var parameters = VideoSegmentationParameters.default
         parameters.hotstartDelay = 5
         parameters.hotstartUnmatchThresh = 3
@@ -160,8 +160,15 @@ struct HotstartTests {
 @VideoSegmentationActor
 struct MemorySelectionTests {
     /// A history with the given conditioning and non-conditioning frames, each carrying a
-    /// payload so the packer treats it as usable.
+    /// payload so the packer treats it as usable. The selection code never dereferences
+    /// `objectPointer`, so a bare zero-filled array stands in and no live asset is needed.
     private func history(conditioning: [Int], nonConditioning: [Int]) -> ObjectOutputHistory {
+        func stub() -> StoredFrameOutput {
+            StoredFrameOutput(
+                predictedMasks: nil,
+                objectPointer: NDArray(shape: [1, 1, 4], scalarType: .float16),
+                objectScoreLogit: 0)
+        }
         var history = ObjectOutputHistory()
         for frame in conditioning {
             history.conditioningOrder.append(frame)
@@ -173,15 +180,6 @@ struct MemorySelectionTests {
         return history
     }
 
-    /// The selection code under test never dereferences `objectPointer`, so a bare
-    /// zero-filled array stands in and the tests need no live Core AI asset.
-    private func stub() -> StoredFrameOutput {
-        StoredFrameOutput(
-            predictedMasks: nil,
-            objectPointer: NDArray(shape: [1, 1, 4], scalarType: .float16),
-            objectScoreLogit: 0)
-    }
-
     @Test("Under the cap, every conditioning frame is selected")
     func selectsAllUnderCap() {
         let (selected, unselected) = MemoryBankPacker.selectClosestConditioningFrames(
@@ -235,9 +233,9 @@ struct MemorySelectionTests {
 
     @Test("An unselected conditioning frame can still be picked up as a recent memory")
     func unselectedConditioningIsReachable() {
-        // `_gather_memory_frame_outputs` falls back to `unselected_conditioning_outputs`
-        // for the recent window. Without that, a conditioning frame that lost the
-        // closest-N contest would vanish from the bank entirely even though it is adjacent.
+        // `_gather_memory_frame_outputs` falls back to `unselected_conditioning_outputs` for
+        // the recent window. Without it, a conditioning frame that lost the closest-N contest
+        // would vanish from the bank entirely even though it is adjacent.
         var parameters = VideoSegmentationParameters.default
         parameters.numMaskmem = 3  // offsets 2, 1
         parameters.maxCondFrameNum = 1
@@ -245,8 +243,6 @@ struct MemorySelectionTests {
         let entries = MemoryBankPacker.gatherMemoryFrames(
             history: history(conditioning: [0, 9], nonConditioning: []),
             frameIndex: 10, reverse: false, parameters: parameters)
-        // Frame 9 wins the single conditioning slot; frame 0 is unselected and is not one
-        // frame back, so offset 1 resolves to frame 9's entry only if it were unselected.
         #expect(entries[0].offset == 0)
         #expect(entries.count == 3)
     }
diff --git a/swift/Tests/VideoSegmenterTests/MaskBitsetTests.swift b/swift/Tests/VideoSegmenterTests/MaskBitsetTests.swift
index f5c06cd8..3dab3f19 100644
--- a/swift/Tests/VideoSegmenterTests/MaskBitsetTests.swift
+++ b/swift/Tests/VideoSegmenterTests/MaskBitsetTests.swift
@@ -36,9 +36,9 @@ struct MaskBitsetTests {
 
     @Test("IoU of two empty masks is 0, not 1")
     func emptyIoU() {
-        // `mask_iou` clamps the union to a minimum of 1 rather than special-casing empty,
-        // so two empty masks score 0. Association depends on that: it must treat two
-        // occluded tracks as unrelated, not as a perfect match.
+        // `mask_iou` clamps the union to a minimum of 1 rather than special-casing empty.
+        // Association depends on it: two occluded tracks must read as unrelated, not as a
+        // perfect match.
         let empty = MaskBitset(width: 8, height: 8)
         #expect(empty.iou(empty) == 0)
     }
@@ -60,8 +60,8 @@ struct MaskBitsetTests {
 
     @Test("IoU survives a mask wider than one 64-bit word")
     func iouAcrossWords() {
-        // 100x3 is 300 bits, so the set pixels straddle word boundaries, the case a
-        // naive per-word loop gets wrong.
+        // 100x3 is 300 bits, so the set pixels straddle word boundaries — the case a naive
+        // per-word loop gets wrong.
         var a = MaskBitset(width: 100, height: 3)
         var b = MaskBitset(width: 100, height: 3)
         for x in 0..<100 {
@@ -75,26 +75,20 @@ struct MaskBitsetTests {
 
     @Test("boundingBox reports inclusive extremes, like masks_to_boxes")
     func boundingBox() {
-        let bitset = mask([
+        // `torchvision.ops.masks_to_boxes` returns [x0, y0, x1, y1] of the extreme set
+        // pixels, so a 2x2 block spans 1 unit, not 2, and one pixel spans 0.
+        let block = mask([
             "....",
             ".##.",
             ".##.",
             "....",
         ])
-        // `torchvision.ops.masks_to_boxes` returns [x0, y0, x1, y1] of the extreme set
-        // pixels, so a 2x2 block spans 1 unit, not 2.
-        #expect(bitset.boundingBox == CGRect(x: 1, y: 1, width: 1, height: 1))
-    }
+        #expect(block.boundingBox == CGRect(x: 1, y: 1, width: 1, height: 1))
 
-    @Test("boundingBox of one pixel is a zero-sized rect at that pixel")
-    func singlePixelBox() {
-        var bitset = MaskBitset(width: 10, height: 10)
-        bitset[7, 3] = true
-        #expect(bitset.boundingBox == CGRect(x: 7, y: 3, width: 0, height: 0))
-    }
+        var single = MaskBitset(width: 10, height: 10)
+        single[7, 3] = true
+        #expect(single.boundingBox == CGRect(x: 7, y: 3, width: 0, height: 0))
 
-    @Test("boundingBox of an empty mask is zero")
-    func emptyBox() {
         #expect(MaskBitset(width: 10, height: 10).boundingBox == .zero)
     }
 
diff --git a/swift/Tests/VideoSegmenterTests/MaskPostprocessorTests.swift b/swift/Tests/VideoSegmenterTests/MaskPostprocessorTests.swift
index 94b07681..09e19a07 100644
--- a/swift/Tests/VideoSegmenterTests/MaskPostprocessorTests.swift
+++ b/swift/Tests/VideoSegmenterTests/MaskPostprocessorTests.swift
@@ -37,7 +37,6 @@ struct LowResolutionMaskTests {
         RawFrameOutput(
             frameIndex: 0,
             maskLogitsByObjectID: masks,
-            objectIDs: masks.keys.sorted(),
             scoreByObjectID: masks.mapValues { _ in 0.9 },
             trackerScoreByObjectID: masks.mapValues { _ in 0.8 },
             suppressedObjectIDs: suppressed)
diff --git a/swift/Tests/VideoSegmenterTests/TokenizerAndBundleTests.swift b/swift/Tests/VideoSegmenterTests/TokenizerAndBundleTests.swift
index 36f4cfe8..1888c52f 100644
--- a/swift/Tests/VideoSegmenterTests/TokenizerAndBundleTests.swift
+++ b/swift/Tests/VideoSegmenterTests/TokenizerAndBundleTests.swift
@@ -11,12 +11,11 @@ import Testing
 
 @Suite("CLIPTokenizer attention mask")
 struct TokenizerTests {
-    /// A vocabulary of whole single-letter words.
+    /// A vocabulary of whole single-letter words, with the ids real CLIP gives them.
     ///
     /// CLIP's BPE appends `</w>` to the last character of a token and then merges pairs;
     /// with no merge table a one-letter word is already terminal, so it looks up directly.
-    /// That keeps this suite self-contained: it tests the masking rule, not BPE, and BPE
-    /// is unchanged from the shipped image-segmenter tokenizer.
+    /// That keeps this suite self-contained: it tests the masking rule, not BPE.
     private func tokenizer() throws -> CLIPTokenizer {
         try CLIPTokenizer(
             vocab: [
@@ -29,16 +28,6 @@ struct TokenizerTests {
             merges: [])
     }
 
-    /// The tokenizer shipped in the exported bundle, when it is present.
-    private func bundledTokenizer() -> CLIPTokenizer? {
-        let root = URL(fileURLWithPath: #filePath)
-            .deletingLastPathComponent()  // VideoSegmenterTests
-            .deletingLastPathComponent()  // Tests
-            .deletingLastPathComponent()  // swift
-        let folder = root.appending(path: "exports/sam3_video_float16/tokenizer")
-        return try? CLIPTokenizer(folder: folder)
-    }
-
     @Test("A one-word prompt is SOT, the word, EOT, then padding")
     func singleWord() throws {
         let (ids, mask) = try tokenizer().encodeWithMask("a", contextLength: 32)
@@ -86,21 +75,81 @@ struct TokenizerTests {
             tokenizer.encode("a b c", contextLength: 32)
                 == tokenizer.encodeWithMask("a b c", contextLength: 32).ids)
     }
+}
 
-    @Test("The real vocabulary reproduces what HF emits for a multi-word prompt")
-    func realVocabulary() throws {
-        // Captured from `AutoTokenizer.from_pretrained("exports/sam3_video_float16/tokenizer")`
-        // with `padding="max_length", max_length=32`. Skipped when the bundle is absent,
-        // so this suite still runs on a machine that has not exported one.
-        guard let tokenizer = bundledTokenizer() else { return }
+@Suite("CLIPTokenizer BPE")
+struct TokenizerBPETests {
+    /// A toy vocabulary whose merge table actually merges.
+    ///
+    /// The suite above passes `merges: []` and single-letter words, so `bpe` returns at its
+    /// `chars.count == 1` early exit and the merge loop never runs. These fixtures are the
+    /// smallest thing that exercises it.
+    private enum Toy {
+        /// Merge rank is list position; the lowest-ranked matching pair merges first.
+        static let merges: [(String, String)] = [
+            ("b", "c</w>"),  // rank 0
+            ("a", "b"),  // rank 1
+            ("a", "t</w>"),  // rank 2
+            ("c", "at</w>"),  // rank 3
+        ]
 
-        let person = tokenizer.encodeWithMask("person", contextLength: 32)
-        #expect(person.ids.prefix(3) == [49406, 2533, 49407])
-        #expect(person.attentionMask.reduce(0, +) == 3)
+        /// Holds an id for both outcomes of the "abc" race below, so a wrong merge order
+        /// shows up as different ids rather than as tokens silently dropped by `compactMap`.
+        static let vocab: [String: Int32] = [
+            "<|startoftext|>": 49406,
+            "<|endoftext|>": 49407,
+            "a": 100,
+            "ab": 101,
+            "c</w>": 102,
+            "bc</w>": 103,
+            "cat</w>": 200,
+        ]
 
-        let car = tokenizer.encodeWithMask("a red car", contextLength: 32)
-        #expect(car.ids.prefix(5) == [49406, 320, 736, 1615, 49407])
-        #expect(car.attentionMask.reduce(0, +) == 5)
+        static func tokenizer() throws -> CLIPTokenizer {
+            try CLIPTokenizer(vocab: vocab, merges: merges)
+        }
+    }
+
+    @Test("A word whose merges chain all the way collapses to a single token")
+    func mergesToSingleToken() throws {
+        // `["c", "a", "t</w>"]`, rank 2 gives `["c", "at</w>"]`, rank 3 gives `["cat</w>"]`.
+        // This is the shape "person" has in the real vocabulary: one id, not six.
+        let (ids, mask) = try Toy.tokenizer().encodeWithMask("cat", contextLength: 8)
+        #expect(ids.prefix(3) == [49406, 200, 49407])
+        #expect(mask.reduce(0, +) == 3)
+    }
+
+    @Test("The lowest-rank pair merges first, even when a later pair also matches")
+    func mergeRankOrder() throws {
+        // "abc" is `["a", "b", "c</w>"]` and both ("a","b") and ("b","c</w>") match. Rank 0
+        // wins, giving `["a", "bc</w>"]` = [100, 103]; merging ("a","b") first would give
+        // `["ab", "c</w>"]` = [101, 102].
+        let ids = try Toy.tokenizer().encode("abc", contextLength: 8)
+        #expect(ids.prefix(4) == [49406, 100, 103, 49407])
+    }
+
+    @Test("A tokenizer.json on disk loads to the same tokenizer as the in-memory init")
+    func loadsFromFolder() throws {
+        let folder = FileManager.default.temporaryDirectory.appending(path: UUID().uuidString)
+        try FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: folder) }
+
+        // A one-element entry among the merges: `init(folder:)` skips malformed pairs, and
+        // skipping must not shift the ranks of the valid ones that follow.
+        let merges: [[String]] = [["junk"]] + Toy.merges.map { [$0.0, $0.1] }
+        let json = try JSONSerialization.data(
+            withJSONObject: [
+                "model": ["vocab": Toy.vocab.mapValues(Int.init), "merges": merges]
+            ])
+        try json.write(to: folder.appending(path: "tokenizer.json"))
+
+        let loaded = try CLIPTokenizer(folder: folder)
+        let expected = try Toy.tokenizer()
+        for prompt in ["cat", "abc", "c", "a cat"] {
+            #expect(
+                loaded.encode(prompt, contextLength: 8) == expected.encode(prompt, contextLength: 8),
+                "\(prompt)")
+        }
     }
 }
 
@@ -109,9 +158,9 @@ struct TemporalIndexTests {
     @Test("A conditioning frame maps to the last row, not to -1")
     func conditioningWraps() {
         // HF writes `memory_temporal_positional_encoding[offset - 1]`, and a conditioning
-        // frame's offset is 0, which in Python is the last row. Getting this wrong
-        // gives every conditioning memory the wrong temporal encoding, which the graph
-        // cannot flag because the index is still in range.
+        // frame's offset is 0, which in Python is the last row. Getting this wrong gives
+        // every conditioning memory the wrong temporal encoding, which the graph cannot flag
+        // because the index is still in range.
         #expect(MemoryBankPacker.temporalIndex(forOffset: 0, numMaskmem: 7) == 6)
     }
 
@@ -124,6 +173,26 @@ struct TemporalIndexTests {
 
 @Suite("VideoSegmenterBundle metadata")
 struct BundleMetadataTests {
+    /// A minimal `video_segmenter` metadata document, plus whatever extra top-level blocks
+    /// the caller needs.
+    private func bundle(
+        imageSize: Int = 1008, extraBlocks: String = ""
+    ) throws -> VideoSegmenterBundle {
+        try bundle(
+            """
+            {
+              "metadata_version": "0.2",
+              "kind": "video_segmenter",
+              "name": "sam3_video_float16",
+              "assets": {"main": "sam3_video_float16.aimodel"},
+              "runtime": {
+                "image_size": \(imageSize), "spatial_slots": 10,
+                "ptr_slots": 24, "max_text_seq_len": 32
+              }\(extraBlocks)
+            }
+            """)
+    }
+
     private func bundle(_ json: String) throws -> VideoSegmenterBundle {
         try VideoSegmenterBundle(
             bundle: ModelBundle(
@@ -131,22 +200,9 @@ struct BundleMetadataTests {
                 bundlePath: URL(fileURLWithPath: "/tmp/does-not-need-to-exist")))
     }
 
-    private let minimal = """
-        {
-          "metadata_version": "0.2",
-          "kind": "video_segmenter",
-          "name": "sam3_video_float16",
-          "assets": {"main": "sam3_video_float16.aimodel"},
-          "runtime": {
-            "image_size": 1008, "spatial_slots": 10,
-            "ptr_slots": 24, "max_text_seq_len": 32
-          }
-        }
-        """
-
     @Test("The runtime block is parsed")
     func geometry() throws {
-        let parsed = try bundle(minimal)
+        let parsed = try bundle()
         #expect(parsed.geometry.imageSize == 1008)
         #expect(parsed.geometry.spatialSlots == 10)
         #expect(parsed.geometry.ptrSlots == 24)
@@ -156,7 +212,7 @@ struct BundleMetadataTests {
     @Test("A bundle without a tracking block keeps the upstream defaults")
     func defaultsWithoutTracking() throws {
         // The shipped export predates the tracking block, so this is the path it takes.
-        let parameters = try bundle(minimal).parameters()
+        let parameters = try bundle().parameters()
         #expect(parameters.hotstartDelay == 15)
         #expect(parameters.scoreThresholdDetection == 0.5)
         #expect(parameters.numMaskmem == 7)
@@ -166,19 +222,11 @@ struct BundleMetadataTests {
     @Test("A partial tracking block overrides only what it names")
     func partialOverride() throws {
         let parsed = try bundle(
-            """
-            {
-              "metadata_version": "0.2",
-              "kind": "video_segmenter",
-              "name": "x",
-              "assets": {"main": "x.aimodel"},
-              "runtime": {
-                "image_size": 336, "spatial_slots": 10,
-                "ptr_slots": 24, "max_text_seq_len": 32
-              },
-              "tracking": {"hotstart_delay": 0, "score_threshold_detection": 0.25}
-            }
-            """)
+            imageSize: 336,
+            extraBlocks: """
+                ,
+                  "tracking": {"hotstart_delay": 0, "score_threshold_detection": 0.25}
+                """)
         let parameters = parsed.parameters()
         #expect(parameters.hotstartDelay == 0)
         #expect(parameters.scoreThresholdDetection == 0.25)
@@ -192,19 +240,12 @@ struct BundleMetadataTests {
         caller.hotstartDelay = 99
         caller.maxNumObjects = 5
 
-        let parsed = try bundle(
-            """
-            {
-              "metadata_version": "0.2", "kind": "video_segmenter", "name": "x",
-              "assets": {"main": "x.aimodel"},
-              "runtime": {"image_size": 1008, "spatial_slots": 10, "ptr_slots": 24,
-                          "max_text_seq_len": 32},
-              "tracking": {"hotstart_delay": 3}
-            }
-            """)
-        let parameters = parsed.parameters(overriding: caller)
+        let parameters = try bundle(extraBlocks: #","tracking": {"hotstart_delay": 3}"#)
+            .parameters(overriding: caller)
         #expect(parameters.hotstartDelay == 3, "the bundle knows its own checkpoint")
-        #expect(parameters.maxNumObjects == 5, "the caller's value survives where the bundle is silent")
+        #expect(
+            parameters.maxNumObjects == 5,
+            "the caller's value survives where the bundle is silent")
     }
 
     @Test("A missing runtime block is rejected with an actionable message")
diff --git a/swift/Tests/VideoSegmenterTests/TrackingPrimitiveTests.swift b/swift/Tests/VideoSegmenterTests/TrackingPrimitiveTests.swift
index 77d8a0f6..2694f272 100644
--- a/swift/Tests/VideoSegmenterTests/TrackingPrimitiveTests.swift
+++ b/swift/Tests/VideoSegmenterTests/TrackingPrimitiveTests.swift
@@ -32,15 +32,8 @@ struct ObjectRegistryTests {
         #expect(registry.existingIndex(of: 12) == 1)
         #expect(registry.existingIndex(of: 13) == 2)
         #expect(registry.existingIndex(of: 11) == nil)
-    }
-
-    @Test("The survivor list is exactly what compacts a parallel array")
-    func survivorsCompactStorage() {
-        var registry = ObjectRegistry()
-        for id in [10, 11, 12, 13] { registry.index(of: id) }
-        let storage = ["a", "b", "c", "d"]
-        let survivors = registry.remove(11)!
-        #expect(survivors.map { storage[$0] } == ["a", "c", "d"])
+        // The survivor list is exactly what compacts a parallel array.
+        #expect(survivors?.map { ["a", "b", "c", "d"][$0] } == ["a", "c", "d"])
     }
 
     @Test("Removing an unknown id is a no-op, not an error")
@@ -62,9 +55,8 @@ struct ConnectedComponentsTests {
 
     @Test("Diagonal neighbours join, because cc_2d is 8-connected")
     func eightConnectivity() {
-        // SAM 2's `get_connected_components` documents 8-connectivity and `cc_2d`
-        // implements it. Under 4-connectivity these two pixels would be separate
-        // components of area 1 each, and sprinkle removal would delete both.
+        // Under 4-connectivity these two pixels would be separate components of area 1 each,
+        // and sprinkle removal would delete both.
         let mask = boolMask([
             "#..",
             ".#.",
@@ -122,9 +114,8 @@ struct ConnectedComponentsTests {
 
     @Test("A tiny object does not delete itself")
     func halfAreaGuard() {
-        // The foreground threshold is `min(maxArea, totalForeground / 2)`, which is what
-        // stops a genuinely small object from being read as a speck. Here the whole mask
-        // is 3 pixels, so the threshold is 1 rather than the configured 16.
+        // The foreground threshold is `min(maxArea, totalForeground / 2)`. Here the whole
+        // mask is 3 pixels, so the threshold is 1 rather than the configured 16.
         var logits = [Float](repeating: -1, count: 100)
         logits[11] = 1
         logits[12] = 1
@@ -162,8 +153,7 @@ struct DetectionDecoderTests {
         // inf/inf = NaN. The detector's logits are unbounded, so the branch matters.
         #expect(DetectionDecoder.sigmoid(0) == 0.5)
         #expect(DetectionDecoder.sigmoid(100) == 1)
-        // Not exactly zero: the negative branch keeps the denormal rather than
-        // underflowing, which is the point of branching on the sign.
+        // Not exactly zero: the negative branch keeps the denormal rather than underflowing.
         #expect(DetectionDecoder.sigmoid(-100) < 1e-40)
         #expect(DetectionDecoder.sigmoid(-100) >= 0)
         #expect(DetectionDecoder.sigmoid(-100).isNaN == false)