From 40b219090c3d7418f701db7c21f3273a2e876c0b Mon Sep 17 00:00:00 2001
From: Alex-Wengg <hanweng9@gmail.com>
Date: Wed, 28 Oct 2026 18:52:20 -0400
Subject: [PATCH 1/2] Vela 3.0 (vela3-fast) on Core ML: decisions, PII and
 unsupported-claim spans

Vela3Manager runs vllm-sr/vela3-fast (UltraBERT-380M) from FluidInference/vela-3.0-coreml:
decisions over named options (choice / yes-no about a state) on the decision
backbone, and the span_sets adapter's two label sets (17 PII types, words of an
answer its context does not support). One encoder pass per question, GPU.

- Vela3Tokenizer: byte-level BPE with Hugging Face offsets (no trimming: the
  post-processor is TemplateProcessing; pieces of a multi-byte character share
  its offsets).
- Rendering, readout and thresholds follow the release's vela3_encoder.py /
  vela3_schema.py; span assembly, word units and the decoder reuse the Vela 2.0
  Swift code (the release copied that Python verbatim).
- Vela2Heads gains init(weights:) (Vela 3 ships safetensors heads; the decision
  head set has no span temperature).
- Vela3ModelStore pins revision deaf348c with per-file SHA-256.
- Vela3Check parity vs the Python runtime on the same encoders: 0 token
  mismatches on 17 Unicode-heavy texts, 0 / 120 decisions and 0 / 12 span sets
  differ.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 Package.swift                                |   1 +
 README.md                                    |  27 ++
 Sources/FluidUse/Vela2/Vela2Manager.swift    |  14 +-
 Sources/FluidUse/Vela3/Vela3Manager.swift    | 389 +++++++++++++++++++
 Sources/FluidUse/Vela3/Vela3ModelStore.swift |  78 ++++
 Sources/FluidUse/Vela3/Vela3Tokenizer.swift  | 160 ++++++++
 Sources/Vela3Check/main.swift                | 101 +++++
 7 files changed, 767 insertions(+), 3 deletions(-)
 create mode 100644 Sources/FluidUse/Vela3/Vela3Manager.swift
 create mode 100644 Sources/FluidUse/Vela3/Vela3ModelStore.swift
 create mode 100644 Sources/FluidUse/Vela3/Vela3Tokenizer.swift
 create mode 100644 Sources/Vela3Check/main.swift

diff --git a/Package.swift b/Package.swift
index 4d906da..e97fb6d 100644
--- a/Package.swift
+++ b/Package.swift
@@ -85,6 +85,7 @@ let package = Package(
         .executableTarget(
             name: "IssueTriageDemo", dependencies: ["FluidUse"], exclude: ["README.md", "fetch-issues.sh"]),
         .executableTarget(name: "Vela2Check", dependencies: ["FluidUse"]),
+        .executableTarget(name: "Vela3Check", dependencies: ["FluidUse"]),
         .executableTarget(name: "EvokeCheck", dependencies: ["FluidUse"]),
         .executableTarget(
             name: "EvokeSearchDemo", dependencies: ["FluidUse"], exclude: ["README.md", "fetch-posts.py", "demo.sh"]),
diff --git a/README.md b/README.md
index 2111fba..15029e2 100644
--- a/README.md
+++ b/README.md
@@ -312,6 +312,33 @@ PII-masked before sending, replies checked against a source document) and
 [Sources/FrontDoorDemo](Sources/FrontDoorDemo/README.md) (1,000 synthetic chatbot messages screened and routed at ~90
 messages per second: guard on the Neural Engine, route + PII on the GPU).
 
+## Vela 3.0 decisions and spans
+
+`Vela3Manager` runs [vela3-fast](https://huggingface.co/vllm-sr/vela3-fast) (Vela 3.0, vLLM Semantic Router × KR Labs;
+UltraBERT-380M encoder, Apache-2.0) on Core ML: decisions over options you name (choice or yes / no about a state), and
+the two label sets of the release's `span_sets` adapter, personal information (17 types) and the words of an answer its
+context does not support. One encoder pass per question on the GPU (~10 ms for a decision, ~18 ms for a PII pass over a
+paragraph; the Neural Engine is slower for this encoder at every length). Rendering, readout, thresholds and the span
+decoder reproduce the release's own code: against the Python runtime on the same encoders, 0 token mismatches on 17
+Unicode-heavy texts, 0 / 120 decisions and 0 / 12 span sets differ (`swift run -c release Vela3Check parity …`). Inputs are
+limited to 1,024 tokens per pass. The pinned snapshot downloads from
+[FluidInference/vela-3.0-coreml](https://huggingface.co/FluidInference/vela-3.0-coreml) on first use (~1.48 GB: two
+multifunction packages, macOS 15 / iOS 18).
+
+```swift
+let vela = try await Vela3Manager.load(from: try await Vela3ModelStore.ensure())
+let r = try await vela.decide(
+    state: "My card was charged twice and I need this fixed today.",
+    questions: [
+        .choice(id: "intent", instructions: "What does the customer want?",
+                options: [("refund", "Money back for the duplicate charge"), ("cancel", "Cancel the order")]),
+        .yesNo(id: "urgent", instructions: "The customer needs a fast response."),
+    ])
+print(r["intent"]!.answer, r["urgent"]!.yes!)
+print(try await vela.pii("Hi, I'm Dana Whitfield, dana@example.com.").spans.map { "\($0.label): \($0.text)" })
+print(try await vela.unsupported(context: "Adults may take up to 4 g a day.", answer: "Adults may take up to 6 g a day.").spans.map(\.text))
+```
+
 ## d1-omni-600M decisions and moderation
 
 `D1OmniManager` runs the text path of Liquid AI's [d1-omni-600M](https://huggingface.co/LiquidAI/d1-omni-600M)
diff --git a/Sources/FluidUse/Vela2/Vela2Manager.swift b/Sources/FluidUse/Vela2/Vela2Manager.swift
index 9caafd0..efc3cf9 100644
--- a/Sources/FluidUse/Vela2/Vela2Manager.swift
+++ b/Sources/FluidUse/Vela2/Vela2Manager.swift
@@ -514,12 +514,20 @@ struct Vela2Heads: Sendable {
                 w[name] = Array(f[offset..<(offset + count)])
             }
         }
-        guard let n = w["norm.weight"], let p = w["w_o.bias"] else { throw Vela2Error.invalidAsset("heads.bin") }
+        try self.init(weights: w)
+    }
+
+    /// Heads from named fp32 tensors (Vela 3 ships them as safetensors). A decision-only head set has no span
+    /// temperature (`log_tau_span`) and is never asked for span logits.
+    init(weights w: [String: [Float]]) throws {
+        guard let n = w["norm.weight"], let p = w["w_o.bias"], let logTau = w["log_tau"]?.first else {
+            throw Vela2Error.invalidAsset("readout heads are missing norm / w_o / log_tau")
+        }
         self.hidden = n.count
         self.proj = p.count
         self.w = w
-        self.tau = exp(w["log_tau"]![0])
-        self.tauSpan = exp(w["log_tau_span"]![0])
+        self.tau = exp(logTau)
+        self.tauSpan = exp(w["log_tau_span"]?.first ?? 0)
     }
 
     private func layerNorm(_ x: ArraySlice<Float>) -> [Float] {
diff --git a/Sources/FluidUse/Vela3/Vela3Manager.swift b/Sources/FluidUse/Vela3/Vela3Manager.swift
new file mode 100644
index 0000000..514cef3
--- /dev/null
+++ b/Sources/FluidUse/Vela3/Vela3Manager.swift
@@ -0,0 +1,389 @@
+@preconcurrency import CoreML
+import Foundation
+
+/// A Vela 3.0 decision question: pick one option, or a yes / no statement (answered as the probability of yes).
+public enum Vela3Question: Sendable {
+    case choice(id: String, instructions: String, options: [(name: String, description: String)])
+    case yesNo(id: String, instructions: String)
+
+    var id: String {
+        switch self {
+        case .choice(let id, _, _), .yesNo(let id, _): id
+        }
+    }
+}
+
+public struct Vela3Decision: Sendable {
+    public let id: String
+    public let names: [String]
+    public let probabilities: [Double]
+    public let answer: String
+    public func probability(_ name: String) -> Double? { names.firstIndex(of: name).map { probabilities[$0] } }
+    /// For a yes / no question: the probability of yes.
+    public var yes: Double? { probability("yes") }
+}
+
+public struct Vela3Span: Sendable {
+    public let label: String
+    /// Unicode scalar offsets into the text the span is in.
+    public let start: Int
+    public let end: Int
+    public let text: String
+    public let probability: Double
+}
+
+public struct Vela3Timing: Sendable {
+    /// Core ML encoder time and the whole call (tokenize, encode, heads, decode), in milliseconds.
+    public let encoderMs: Double
+    public let totalMs: Double
+    /// The encoder function (sequence length) of each pass.
+    public let buckets: [Int]
+}
+
+public struct Vela3DecisionResult: Sendable {
+    public let decisions: [Vela3Decision]
+    public let timing: Vela3Timing
+    public subscript(id: String) -> Vela3Decision? { decisions.first { $0.id == id } }
+}
+
+public struct Vela3SpanResult: Sendable {
+    public let spans: [Vela3Span]
+    public let threshold: Double
+    public let timing: Vela3Timing
+}
+
+public enum Vela3Error: Error, LocalizedError, Sendable {
+    case invalidAsset(String)
+    case invalidRequest(String)
+    case tooLong(String)
+
+    public var errorDescription: String? {
+        switch self {
+        case .invalidAsset(let r): "Invalid Vela 3.0 asset: \(r)"
+        case .invalidRequest(let r): "Invalid Vela 3.0 request: \(r)"
+        case .tooLong(let r): "Vela 3.0 request too long: \(r)"
+        }
+    }
+}
+
+/// Vela 3.0 vela3-fast (vLLM Semantic Router × KR Labs; UltraBERT-380M encoder) on Core ML, from
+/// [FluidInference/vela-3.0-coreml](https://huggingface.co/FluidInference/vela-3.0-coreml): decisions over options you
+/// name (the decision backbone) and the two label sets of the release's `span_sets` adapter, personal information (17
+/// types) and claims of an answer its context does not support. One encoder pass per question, on the GPU (the Neural
+/// Engine is slower for this encoder at every length and drifts further from the fp32 answers). Rendering, readout,
+/// thresholds and the span decoder reproduce the release's `vela3_encoder.py` / `vela3_schema.py`; inputs are limited to
+/// 1,024 tokens per pass (the release windows longer span inputs).
+@available(macOS 15.0, iOS 18.0, *)
+public final class Vela3Manager: Sendable {
+    struct Markers: Sendable {
+        let q, o, e, sep: Int
+        let seg: [String: Int]
+    }
+
+    struct SpanSet: Sendable {
+        let names: [String]
+        let descriptions: [String]
+        let role: String
+    }
+
+    private let tokenizer: Vela3Tokenizer
+    private let markers: Markers
+    private let bos: Int
+    private let eos: Int
+    private let decisionHeads: Vela2Heads
+    private let spanHeads: Vela2Heads
+    private let decisionModels: [(length: Int, model: MLModel)]
+    private let spanModels: [(length: Int, model: MLModel)]
+    private let pii: SpanSet
+    private let unsupported: SpanSet
+    /// The set adapter's span temperature, PII thresholds by target length, and the unsupported-claim threshold.
+    private let spanTemperature: Double
+    private let piiBuckets: [(maxTokens: Int, threshold: Double)]
+    private let unsupportedThreshold: Double
+
+    public static let decisionLengths = [128, 256, 512, 1024]
+    public static let spanLengths = [512, 1024]
+
+    public static func load(from directory: URL) async throws -> Vela3Manager {
+        func json(_ name: String) throws -> [String: Any] {
+            guard let o = try JSONSerialization.jsonObject(with: Data(contentsOf: directory.appendingPathComponent(name))) as? [String: Any]
+            else { throw Vela3Error.invalidAsset(name) }
+            return o
+        }
+        let config = try json("config.json")
+        let vela = try json("vela3_config.json")
+        guard let decision = config["decision"] as? [String: Any], let marker = decision["marker_ids"] as? [String: Int],
+            let bos = config["bos_token_id"] as? Int, let eos = config["eos_token_id"] as? Int
+        else { throw Vela3Error.invalidAsset("config.json is missing fields") }
+        func m(_ k: String) throws -> Int {
+            guard let v = marker[k] else { throw Vela3Error.invalidAsset("marker \(k)") }
+            return v
+        }
+        guard let span = vela["span"] as? [String: Any], let sets = span["router_label_sets"] as? [String: [String]],
+            let schemas = span["schemas"] as? [String: [String: Any]], let setAdapter = span["set_adapter"] as? [String: Any],
+            let temperature = setAdapter["router_set_temperature"] as? Double,
+            let buckets = setAdapter["pii_buckets"] as? [[String: Any]],
+            let byset = setAdapter["thresholds_by_set"] as? [String: Double], let halu = byset["halu"]
+        else { throw Vela3Error.invalidAsset("vela3_config.json is missing the span_sets settings") }
+        func spanSet(_ name: String) throws -> SpanSet {
+            guard let names = sets[name], let schema = schemas[name], let labels = schema["labels"] as? [String: String],
+                let over = schema["over"] as? String
+            else { throw Vela3Error.invalidAsset("vela3_config.json label set \(name)") }
+            return SpanSet(names: names, descriptions: names.map { labels[$0] ?? "" }, role: over)
+        }
+        let decisionModels = try await models(directory.appendingPathComponent("Vela3Decision.mlpackage"), lengths: decisionLengths)
+        let spanModels = try await models(directory.appendingPathComponent("Vela3SpanSets.mlpackage"), lengths: spanLengths)
+        return Vela3Manager(
+            tokenizer: try Vela3Tokenizer(tokenizerJsonURL: directory.appendingPathComponent("tokenizer.json")),
+            markers: Markers(
+                q: try m("[Q]"), o: try m("[O]"), e: try m("[E]"), sep: try m("[SEP_SCHEMA]"),
+                seg: ["user": try m("[SEG_user]"), "context": try m("[SEG_context]"), "answer": try m("[SEG_answer]")]),
+            bos: bos, eos: eos,
+            decisionHeads: try Vela2Heads(weights: try safetensors(directory.appendingPathComponent("heads_decision.safetensors"))),
+            spanHeads: try Vela2Heads(weights: try safetensors(directory.appendingPathComponent("heads_span_sets.safetensors"))),
+            decisionModels: decisionModels, spanModels: spanModels,
+            pii: try spanSet("pii"), unsupported: try spanSet("halu"), spanTemperature: temperature,
+            piiBuckets: buckets.compactMap { b in
+                guard let t = b["threshold"] as? Double, let n = b["max_tokens"] as? NSNumber else { return nil }
+                return (n.intValue, t)
+            }, unsupportedThreshold: halu)
+    }
+
+    private static func models(_ package: URL, lengths: [Int]) async throws -> [(length: Int, model: MLModel)] {
+        var compiled = package.deletingPathExtension().appendingPathExtension("mlmodelc")
+        if !FileManager.default.fileExists(atPath: compiled.path) { compiled = try await KevManager.compiled(package) }
+        var out: [(Int, MLModel)] = []
+        for length in lengths {
+            let configuration = MLModelConfiguration()
+            configuration.functionName = "L\(length)"
+            configuration.computeUnits = .cpuAndGPU
+            out.append((length, try await MLModel.load(contentsOf: compiled, configuration: configuration)))
+        }
+        return out
+    }
+
+    /// fp32 tensors of a safetensors file by name.
+    static func safetensors(_ url: URL) throws -> [String: [Float]] {
+        let data = try Data(contentsOf: url)
+        guard data.count >= 8 else { throw Vela3Error.invalidAsset(url.lastPathComponent) }
+        let headerLength = data.prefix(8).enumerated().reduce(0) { $0 | (Int($1.element) << (8 * $1.offset)) }
+        guard 8 + headerLength <= data.count,
+            let header = try JSONSerialization.jsonObject(with: data.subdata(in: 8..<(8 + headerLength))) as? [String: Any]
+        else { throw Vela3Error.invalidAsset("\(url.lastPathComponent) header") }
+        var out: [String: [Float]] = [:]
+        for (name, value) in header where name != "__metadata__" {
+            guard let meta = value as? [String: Any], meta["dtype"] as? String == "F32", let range = meta["data_offsets"] as? [Int],
+                range.count == 2
+            else { throw Vela3Error.invalidAsset("\(url.lastPathComponent): \(name) is not an F32 tensor") }
+            let bytes = data.subdata(in: (8 + headerLength + range[0])..<(8 + headerLength + range[1]))
+            out[name] = bytes.withUnsafeBytes { Array($0.bindMemory(to: Float.self)) }
+        }
+        return out
+    }
+
+    init(
+        tokenizer: Vela3Tokenizer, markers: Markers, bos: Int, eos: Int, decisionHeads: Vela2Heads, spanHeads: Vela2Heads,
+        decisionModels: [(length: Int, model: MLModel)], spanModels: [(length: Int, model: MLModel)], pii: SpanSet,
+        unsupported: SpanSet, spanTemperature: Double, piiBuckets: [(maxTokens: Int, threshold: Double)], unsupportedThreshold: Double
+    ) {
+        self.tokenizer = tokenizer
+        self.markers = markers
+        self.bos = bos
+        self.eos = eos
+        self.decisionHeads = decisionHeads
+        self.spanHeads = spanHeads
+        self.decisionModels = decisionModels
+        self.spanModels = spanModels
+        self.pii = pii
+        self.unsupported = unsupported
+        self.spanTemperature = spanTemperature
+        self.piiBuckets = piiBuckets
+        self.unsupportedThreshold = unsupportedThreshold
+    }
+
+    /// Runs every encoder function once so no request pays for the first dispatch.
+    public func warm() async throws {
+        for (length, model) in (decisionModels + spanModels).reversed() {
+            _ = try await encode(ids: [bos, eos], model: model, length: length, dim: decisionHeads.hidden)
+        }
+    }
+
+    // MARK: decisions (vela3_encoder.DecisionEncoder)
+
+    /// Answer each question about `state` (the release reads a JSON state as compact JSON; pass that text here).
+    public func decide(state: String, questions: [Vela3Question]) async throws -> Vela3DecisionResult {
+        let started = Date()
+        var seen = Set<String>()
+        for q in questions {
+            guard seen.insert(q.id).inserted else { throw Vela3Error.invalidRequest("duplicate question id \(q.id)") }
+            if case .choice(let id, _, let options) = q, options.count < 2 {
+                throw Vela3Error.invalidRequest("choice \(id) needs at least 2 options")
+            }
+        }
+        let stateIDs = tokenizer.encode(state)
+        var decisions: [Vela3Decision] = []
+        var encoderMs = 0.0
+        var used: [Int] = []
+        for q in questions {
+            let rec = decisionRecord(q, stateIDs: stateIDs)
+            guard let (length, model) = decisionModels.first(where: { rec.ids.count <= $0.length }) else {
+                throw Vela3Error.tooLong("\(rec.ids.count) tokens exceed the largest encoder function L\(Self.decisionLengths.last!)")
+            }
+            let t = Date()
+            let hidden = try await encode(ids: rec.ids, model: model, length: length, dim: decisionHeads.hidden)
+            encoderMs += Date().timeIntervalSince(t) * 1000
+            used.append(length)
+            let logits = decisionHeads.run(hidden: hidden, dim: decisionHeads.hidden, rec: rec).0.map(Double.init)
+            let m = logits.max() ?? 0
+            let e = logits.map { exp($0 - m) }
+            let s = e.reduce(0, +)
+            let p = e.map { $0 / s }
+            let names = rec.questions[0].names
+            var best = 0
+            for i in 1..<p.count where p[i] > p[best] { best = i }
+            decisions.append(Vela3Decision(id: q.id, names: names, probabilities: p, answer: names[best]))
+        }
+        return Vela3DecisionResult(
+            decisions: decisions, timing: Vela3Timing(encoderMs: encoderMs, totalMs: Date().timeIntervalSince(started) * 1000, buckets: used))
+    }
+
+    /// The encoder input of a decision question (for parity checks).
+    public func decisionSequence(state: String, question: Vela3Question) -> [Int] {
+        decisionRecord(question, stateIDs: tokenizer.encode(state)).ids
+    }
+
+    /// `[BOS] [Q] instructions [O] key_1: description_1 [O] key_2 ... [SEP_SCHEMA] [SEG_user] state [EOS]`; a yes / no
+    /// question is the 2-option choice {no, yes}. The readout pools [SEG_user] .. the end of the state.
+    private func decisionRecord(_ q: Vela3Question, stateIDs: [Int]) -> Vela2Manager.Record {
+        let (instructions, options): (String, [(name: String, description: String)]) =
+            switch q {
+            case .choice(_, let text, let options): (text, options)
+            case .yesNo(_, let text): (text, [("no", ""), ("yes", "")])
+            }
+        var ids = [bos, markers.q] + tokenizer.encode(instructions)
+        var optPos: [Int] = []
+        for o in options {
+            optPos.append(ids.count)
+            ids.append(markers.o)
+            ids += tokenizer.encode(o.description.isEmpty ? o.name : "\(o.name): \(o.description)")
+        }
+        ids.append(markers.sep)
+        let ps = ids.count
+        ids.append(markers.seg["user"]!)
+        ids += stateIDs
+        let pe = ids.count
+        ids.append(eos)
+        let rec = Vela2Manager.QuestionRec(id: q.id, qPos: 1, optPos: optPos, names: options.map(\.name), absPos: nil, pool: (ps, pe))
+        return Vela2Manager.Record(ids: ids, questions: [rec], span: nil)
+    }
+
+    // MARK: spans (vela3_schema, span_sets adapter)
+
+    /// Personal information in `text` (17 types: names, e-mail addresses, phone numbers, street addresses, card numbers, …).
+    public func pii(_ text: String, threshold: Double? = nil) async throws -> Vela3SpanResult {
+        try await spans(set: pii, parts: [("user", text)], threshold: threshold) { tokens in
+            self.piiBuckets.first { tokens <= $0.maxTokens }?.threshold ?? self.piiBuckets.last?.threshold ?? 0.5
+        }
+    }
+
+    /// The words of `answer` that `context` does not support.
+    public func unsupported(context: String, answer: String, threshold: Double? = nil) async throws -> Vela3SpanResult {
+        try await spans(set: unsupported, parts: [("context", context), ("answer", answer)], threshold: threshold) { _ in
+            self.unsupportedThreshold
+        }
+    }
+
+    /// Token ids and Unicode-scalar offsets of a text (for parity checks).
+    public func tokenize(_ text: String) -> (ids: [Int], offsets: [(Int, Int)]) {
+        let t = tokenizer.tokens(Array(text.unicodeScalars))
+        return (t.map(\.id), t.map { ($0.start, $0.end) })
+    }
+
+    /// The encoder input of a PII or unsupported-claim call (for parity checks).
+    public func spanSequence(pii text: String) -> [Int] { spanRecord(set: pii, parts: [("user", text)]).0.ids }
+    public func spanSequence(context: String, answer: String) -> [Int] {
+        spanRecord(set: unsupported, parts: [("context", context), ("answer", answer)]).0.ids
+    }
+
+    private func spans(
+        set: SpanSet, parts: [(role: String, text: String)], threshold: Double?, defaultThreshold: (Int) -> Double
+    ) async throws -> Vela3SpanResult {
+        let started = Date()
+        let (rec, target) = spanRecord(set: set, parts: parts)
+        guard let span = rec.span else { throw Vela3Error.invalidRequest("no \(set.role) part") }
+        guard let (length, model) = spanModels.first(where: { rec.ids.count <= $0.length }) else {
+            throw Vela3Error.tooLong("\(rec.ids.count) tokens exceed the largest encoder function L\(Self.spanLengths.last!)")
+        }
+        let t = Date()
+        let hidden = try await encode(ids: rec.ids, model: model, length: length, dim: spanHeads.hidden)
+        let encoderMs = Date().timeIntervalSince(t) * 1000
+        let logits = spanHeads.run(hidden: hidden, dim: spanHeads.hidden, rec: rec).1
+        let probs = logits.map { row in row.map { 1 / (1 + exp(-Double($0) / spanTemperature)) } }
+        let thr = threshold ?? defaultThreshold(span.tokenCount)
+        let decoded = span.wOffsets.isEmpty ? [] : Vela2Text.decodeSpans(probs, offsets: span.wOffsets, text: target, threshold: thr)
+        let out = decoded.map {
+            Vela3Span(
+                label: span.names[$0.label], start: $0.start, end: $0.end,
+                text: String(String.UnicodeScalarView(target[$0.start..<$0.end])), probability: $0.probability)
+        }
+        return Vela3SpanResult(
+            spans: out, threshold: thr,
+            timing: Vela3Timing(encoderMs: encoderMs, totalMs: Date().timeIntervalSince(started) * 1000, buckets: [length]))
+    }
+
+    /// `<bos> ([E] label: description)* [SEP_SCHEMA] ([SEG_role] part)* <eos>` (vela3_schema.assemble with one span
+    /// question; its text is not part of the input), with the target part's word units for the span readout.
+    private func spanRecord(set: SpanSet, parts: [(role: String, text: String)]) -> (Vela2Manager.Record, [Unicode.Scalar]) {
+        var ids = [bos]
+        var ePos: [Int] = []
+        for (name, description) in zip(set.names, set.descriptions) {
+            ePos.append(ids.count)
+            ids.append(markers.e)
+            ids += tokenizer.encode(description.isEmpty ? name : "\(name): \(description)")
+        }
+        ids.append(markers.sep)
+        var span: Vela2Manager.SpanRec?
+        var target: [Unicode.Scalar] = []
+        for part in parts {
+            let scalars = Array(part.text.unicodeScalars)
+            let toks = tokenizer.tokens(scalars)
+            let start = ids.count
+            ids.append(markers.seg[part.role]!)
+            ids += toks.map(\.id)
+            if part.role == set.role {
+                let offsets = toks.map { ($0.start, $0.end) }
+                let (words, first) = Vela2Text.wordFirstTokens(scalars, offsets: offsets)
+                span = Vela2Manager.SpanRec(
+                    id: set.role, role: part.role, names: set.names, ePos: ePos, wPos: first.map { start + 1 + $0 }, wOffsets: words,
+                    tokenCount: toks.count)
+                target = scalars
+            }
+        }
+        ids.append(eos)
+        return (Vela2Manager.Record(ids: ids, questions: [], span: span), target)
+    }
+
+    // MARK: encoder
+
+    private func encode(ids: [Int], model: MLModel, length: Int, dim: Int) async throws -> [Float] {
+        let input = try MLMultiArray(shape: [1, NSNumber(value: length)], dataType: .int32)
+        let mask = try MLMultiArray(shape: [1, NSNumber(value: length)], dataType: .int32)
+        let ip = input.dataPointer.assumingMemoryBound(to: Int32.self)
+        let mp = mask.dataPointer.assumingMemoryBound(to: Int32.self)
+        for i in 0..<length {
+            ip[i] = i < ids.count ? Int32(ids[i]) : 0
+            mp[i] = i < ids.count ? 1 : 0
+        }
+        let out = try await model.prediction(from: MLDictionaryFeatureProvider(dictionary: ["input_ids": input, "attention_mask": mask]))
+        guard let hidden = out.featureValue(for: "hidden")?.multiArrayValue, hidden.dataType == .float16 else {
+            throw Vela3Error.invalidAsset("encoder returned no fp16 hidden states")
+        }
+        let strides = hidden.strides.map(\.intValue)
+        var h = [Float](repeating: 0, count: ids.count * dim)
+        let src = hidden.dataPointer.assumingMemoryBound(to: Float16.self)
+        for t in 0..<ids.count {
+            for c in 0..<dim { h[t * dim + c] = Float(src[t * strides[1] + c * strides[2]]) }
+        }
+        return h
+    }
+}
diff --git a/Sources/FluidUse/Vela3/Vela3ModelStore.swift b/Sources/FluidUse/Vela3/Vela3ModelStore.swift
new file mode 100644
index 0000000..c8ede30
--- /dev/null
+++ b/Sources/FluidUse/Vela3/Vela3ModelStore.swift
@@ -0,0 +1,78 @@
+import CryptoKit
+import Foundation
+
+/// Downloads the pinned, checksummed Vela 3.0 Core ML snapshot
+/// ([FluidInference/vela-3.0-coreml](https://huggingface.co/FluidInference/vela-3.0-coreml)) into the FluidUse cache,
+/// laid out as `Vela3Manager.load(from:)` expects (~1.48 GB: the decision and span-sets encoders, heads, tokenizer).
+public enum Vela3ModelStore {
+    public typealias Progress = @Sendable (_ file: String, _ bytes: Int64) -> Void
+
+    static let repository = "FluidInference/vela-3.0-coreml"
+    static let revision = "deaf348c702054ad27189b4d5eebfb66314f3b5b"
+    static let folder = "vela-3.0-coreml"
+
+    static let assets: [(path: String, sha256: String)] = [
+        ("config.json", "a85b358ac11b71d780deb09e8a082efddc67938a2eb4fc16d68d8ae888c69d14"),
+        ("vela3_config.json", "ee5088605aa5151210fbc12e3f6ee0c9a382dddf90d3a43ac606c0df305d9ff2"),
+        ("tokenizer.json", "5c7d325b4759ac77f8b95a70d8fb885bb39b66749e728bd745ec67984754b244"),
+        ("heads_decision.safetensors", "402dffef5218b64d55e11372db414046219e0d6dccae93193e92cd6e8a0635d5"),
+        ("heads_span_sets.safetensors", "71bac50e691185155ba9d30a08c4f70bb07bbce37a6caee0f7bb922859a83e92"),
+        ("Vela3Decision.mlpackage/Manifest.json", "71d8d30fd441df570149bca488634b5a1d22caf314643e4533000b4f3c6c8d30"),
+        ("Vela3Decision.mlpackage/Data/com.apple.CoreML/model.mlmodel", "3983ec2a96ba8403cf48feaefc9f16cf73645d80e25ceb054718c4ee7f44fdb4"),
+        ("Vela3Decision.mlpackage/Data/com.apple.CoreML/weights/weight.bin", "af7431750cca9421b75d9ef1420a29b7ce4e6cdbe61e9029c81f8129ca344eff"),
+        ("Vela3SpanSets.mlpackage/Manifest.json", "5b5298314d69ced1e8e832eed230675c101a2f37bdd8649a015765ef03985431"),
+        ("Vela3SpanSets.mlpackage/Data/com.apple.CoreML/model.mlmodel", "3e8d0a64e7c85378c23e1e12e3eb2db5f9e6dad50a4172cb57966f6a6657be05"),
+        ("Vela3SpanSets.mlpackage/Data/com.apple.CoreML/weights/weight.bin", "2c3a719b4df3d682f399222484a7daa756954cdbca0c4a74c9943dcfb14c544a"),
+    ]
+
+    /// Ensure the snapshot exists in the FluidUse cache and return its directory. Files are checksummed once per
+    /// pinned revision; later launches only check that they are present.
+    public static func ensure(cacheDirectory: URL? = nil, progress: Progress? = nil) async throws -> URL {
+        let root = cacheDirectory ?? LayaModelStore.defaultCacheDirectory()
+        let directory = root.appendingPathComponent(folder, isDirectory: true)
+        let manager = FileManager.default
+        let verified = directory.appendingPathComponent(".verified-\(revision)")
+        if manager.fileExists(atPath: verified.path),
+            assets.allSatisfy({ manager.fileExists(atPath: directory.appendingPathComponent($0.path).path) })
+        {
+            return directory
+        }
+        try manager.createDirectory(at: directory, withIntermediateDirectories: true)
+        for asset in assets {
+            try Task.checkCancellation()
+            let destination = directory.appendingPathComponent(asset.path)
+            if manager.fileExists(atPath: destination.path), try checksum(of: destination) == asset.sha256 { continue }
+            try manager.createDirectory(at: destination.deletingLastPathComponent(), withIntermediateDirectories: true)
+            progress?(asset.path, 0)
+            let escaped = asset.path.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed) ?? asset.path
+            guard let url = URL(string: "https://huggingface.co/\(repository)/resolve/\(revision)/\(escaped)") else {
+                throw Vela3Error.invalidAsset("Invalid Hugging Face asset URL for \(asset.path)")
+            }
+            let (temporary, response) = try await URLSession.shared.download(from: url)
+            defer { try? manager.removeItem(at: temporary) }
+            guard let http = response as? HTTPURLResponse, http.statusCode == 200 else {
+                throw Vela3Error.invalidAsset("Download failed for \(asset.path)")
+            }
+            let actual = try checksum(of: temporary)
+            guard actual == asset.sha256 else {
+                throw Vela3Error.invalidAsset("Checksum mismatch for \(asset.path): expected \(asset.sha256), got \(actual)")
+            }
+            let size = (try manager.attributesOfItem(atPath: temporary.path)[.size] as? NSNumber)?.int64Value ?? 0
+            try LayaModelStore.installDownloadedFile(temporary, at: destination)
+            for package in ["Vela3Decision", "Vela3SpanSets"] where asset.path.hasPrefix("\(package).mlpackage/") {
+                try? manager.removeItem(at: directory.appendingPathComponent("\(package).mlmodelc"))  // no stale compiled model
+            }
+            progress?(asset.path, size)
+        }
+        try Data().write(to: verified)
+        return directory
+    }
+
+    private static func checksum(of file: URL) throws -> String {
+        let handle = try FileHandle(forReadingFrom: file)
+        defer { try? handle.close() }
+        var digest = SHA256()
+        while let chunk = try handle.read(upToCount: 4_194_304), !chunk.isEmpty { digest.update(data: chunk) }
+        return digest.finalize().map { String(format: "%02x", $0) }.joined()
+    }
+}
diff --git a/Sources/FluidUse/Vela3/Vela3Tokenizer.swift b/Sources/FluidUse/Vela3/Vela3Tokenizer.swift
new file mode 100644
index 0000000..47bd06e
--- /dev/null
+++ b/Sources/FluidUse/Vela3/Vela3Tokenizer.swift
@@ -0,0 +1,160 @@
+import Foundation
+import os
+
+/// The byte-level BPE tokenizer of vela3-fast (UltraBERT's GPT-2 style `tokenizer.json`), with Hugging Face `tokenizers`
+/// offsets: special tokens matched literally, the GPT-2 split regex, merges by rank (leftmost first on ties), and each
+/// token's offsets running from the character of its first byte to the character of its last byte (so pieces of one
+/// multi-byte character share its offsets). Offsets are Unicode scalar indices, as Python string indices. No offset
+/// trimming: this tokenizer's post-processor is `TemplateProcessing`, so the leading space stays in a token's span.
+public final class Vela3Tokenizer: Sendable {
+    public struct Token: Sendable, Equatable {
+        public let id: Int
+        public let start: Int
+        public let end: Int
+    }
+
+    private static let pattern = #"'s|'t|'re|'ve|'m|'ll|'d| ?\p{L}+| ?\p{N}+| ?[^\s\p{L}\p{N}]+|\s+(?!\S)|\s+"#
+
+    private let vocabulary: [String: Int]
+    private let mergeRanks: [String: Int]
+    /// Added tokens, longest first, so a longer token wins over one it contains.
+    private let addedTokens: [(scalars: [Unicode.Scalar], id: Int)]
+    private let byteToCharacter: [String]
+    private let regex: NSRegularExpression
+    /// Encoded pieces (token ids with their byte ranges); ordinary text repeats the same words.
+    private let cache = OSAllocatedUnfairLock<[String: [(Int, Int, Int)]]>(initialState: [:])
+
+    public init(tokenizerJsonURL: URL) throws {
+        let data = try Data(contentsOf: tokenizerJsonURL)
+        guard let root = try JSONSerialization.jsonObject(with: data) as? [String: Any],
+            let model = root["model"] as? [String: Any], model["type"] as? String == "BPE",
+            let vocab = model["vocab"] as? [String: Int], let merges = model["merges"] as? [Any]
+        else { throw Vela3Error.invalidAsset("tokenizer.json is not a byte-level BPE tokenizer") }
+        vocabulary = vocab
+        var ranks: [String: Int] = [:]
+        ranks.reserveCapacity(merges.count)
+        for (rank, merge) in merges.enumerated() {
+            if let pair = merge as? [String], pair.count == 2 {
+                ranks[pair[0] + " " + pair[1]] = rank
+            } else if let text = merge as? String {
+                ranks[text] = rank
+            } else {
+                throw Vela3Error.invalidAsset("tokenizer.json merge \(rank) is malformed")
+            }
+        }
+        mergeRanks = ranks
+        let added = (root["added_tokens"] as? [[String: Any]] ?? []).compactMap { t -> ([Unicode.Scalar], Int)? in
+            guard let content = t["content"] as? String, let id = t["id"] as? Int, !content.isEmpty else { return nil }
+            return (Array(content.unicodeScalars), id)
+        }
+        addedTokens = added.sorted { $0.0.count > $1.0.count }
+        byteToCharacter = Self.bytesToUnicode()
+        regex = try NSRegularExpression(pattern: Self.pattern)
+    }
+
+    public func encode(_ text: String) -> [Int] { tokens(Array(text.unicodeScalars)).map(\.id) }
+
+    /// Tokens of a text with Unicode-scalar offsets into it.
+    public func tokens(_ scalars: [Unicode.Scalar]) -> [Token] {
+        var out: [Token] = []
+        var segmentStart = 0
+        var i = 0
+        while i < scalars.count {
+            if let match = addedTokens.first(where: { matches($0.scalars, scalars, at: i) }) {
+                if segmentStart < i { out += textTokens(scalars, segmentStart..<i) }
+                out.append(Token(id: match.id, start: i, end: i + match.scalars.count))
+                i += match.scalars.count
+                segmentStart = i
+            } else {
+                i += 1
+            }
+        }
+        if segmentStart < scalars.count { out += textTokens(scalars, segmentStart..<scalars.count) }
+        return out
+    }
+
+    private func matches(_ token: [Unicode.Scalar], _ s: [Unicode.Scalar], at i: Int) -> Bool {
+        guard i + token.count <= s.count, s[i] == token[0] else { return false }
+        for k in 1..<token.count where s[i + k] != token[k] { return false }
+        return true
+    }
+
+    /// Split one stretch of ordinary text with the GPT-2 regex and BPE-encode each piece.
+    private func textTokens(_ scalars: [Unicode.Scalar], _ range: Range<Int>) -> [Token] {
+        let segment = Array(scalars[range])
+        var view = String.UnicodeScalarView()
+        view.append(contentsOf: segment)
+        let string = String(view)
+        // UTF-16 offset -> scalar index (within the segment)
+        var scalarAt: [Int] = []
+        scalarAt.reserveCapacity(string.utf16.count + 1)
+        for (k, s) in segment.enumerated() { for _ in 0..<(s.value > 0xFFFF ? 2 : 1) { scalarAt.append(k) } }
+        scalarAt.append(segment.count)
+        var pieces: [Range<Int>] = []
+        var last = 0
+        for m in regex.matches(in: string, range: NSRange(location: 0, length: string.utf16.count)) {
+            let a = scalarAt[m.range.location], b = scalarAt[m.range.location + m.range.length]
+            if a > last { pieces.append(last..<a) }  // nothing the regex skipped is dropped
+            if b > a { pieces.append(a..<b) }
+            last = b
+        }
+        if last < segment.count { pieces.append(last..<segment.count) }
+        var out: [Token] = []
+        for piece in pieces {
+            // the bytes of the piece and the scalar each byte belongs to
+            var bytes: [UInt8] = []
+            var owner: [Int] = []
+            for k in piece {
+                for b in String(segment[k]).utf8 {
+                    bytes.append(b)
+                    owner.append(range.lowerBound + k)
+                }
+            }
+            for (id, b0, b1) in encodePiece(bytes) {
+                out.append(Token(id: id, start: owner[b0], end: owner[b1 - 1] + 1))
+            }
+        }
+        return out
+    }
+
+    /// BPE over the byte characters of one piece -> (token id, first byte, end byte).
+    private func encodePiece(_ bytes: [UInt8]) -> [(Int, Int, Int)] {
+        let key = bytes.map { byteToCharacter[Int($0)] }.joined()
+        if let hit = cache.withLock({ $0[key] }) { return hit }
+        var symbols: [(text: String, start: Int, end: Int)] = bytes.enumerated().map { (byteToCharacter[Int($0.element)], $0.offset, $0.offset + 1) }
+        while symbols.count > 1 {
+            var best = Int.max
+            var at = -1
+            for k in 0..<(symbols.count - 1) {
+                if let r = mergeRanks[symbols[k].text + " " + symbols[k + 1].text], r < best {
+                    best = r
+                    at = k
+                }
+            }
+            if at < 0 { break }
+            symbols[at] = (symbols[at].text + symbols[at + 1].text, symbols[at].start, symbols[at + 1].end)
+            symbols.remove(at: at + 1)
+        }
+        let out = symbols.map { (vocabulary[$0.text] ?? 0, $0.start, $0.end) }
+        cache.withLock { c in
+            if c.count > 50_000 { c.removeAll() }
+            c[key] = out
+        }
+        return out
+    }
+
+    /// GPT-2's reversible byte -> printable character table.
+    private static func bytesToUnicode() -> [String] {
+        var bs: [Int] = Array(33...126) + Array(161...172) + Array(174...255)
+        var cs = bs
+        var n = 0
+        for b in 0..<256 where !bs.contains(b) {
+            bs.append(b)
+            cs.append(256 + n)
+            n += 1
+        }
+        var table = [String](repeating: "", count: 256)
+        for (b, c) in zip(bs, cs) { table[b] = String(Character(Unicode.Scalar(UInt32(c))!)) }
+        return table
+    }
+}
diff --git a/Sources/Vela3Check/main.swift b/Sources/Vela3Check/main.swift
new file mode 100644
index 0000000..9d771d4
--- /dev/null
+++ b/Sources/Vela3Check/main.swift
@@ -0,0 +1,101 @@
+import FluidUse
+import Foundation
+
+/// Vela 3.0 parity against the Python runtime of FluidInference/vela-3.0-coreml (`vela3_coreml.py`, same Core ML
+/// encoders on the GPU, the release's own rendering / thresholds / span decoder), plus a timing run.
+///
+///     swift run -c release Vela3Check parity <model directory> <fixtures.json>
+///     swift run -c release Vela3Check download            # fetch the pinned snapshot into the FluidUse cache
+///
+/// Fixtures (vela-3.0-coreml/conversion/fixtures.py): token ids and offsets of varied texts, encoder sequences and
+/// answers of typed decisions, PII and unsupported-claim calls.
+@main
+struct Vela3Check {
+    struct Fixtures: Decodable {
+        struct Tok: Decodable { let text: String; let ids: [Int]; let offsets: [[Int]] }
+        struct Decision: Decodable {
+            let state: String; let id: String; let type: String; let instructions: String; let options: [[String]]
+            let ids: [Int]; let names: [String]; let probabilities: [Double]
+        }
+        struct Span: Decodable { let label: String; let start: Int; let end: Int }
+        struct SpanCase: Decodable {
+            let kind: String; let text: String?; let context: String?; let answer: String?
+            let ids: [Int]; let spans: [Span]; let threshold: Double
+        }
+        let tokens: [Tok]
+        let decisions: [Decision]
+        let spans: [SpanCase]
+    }
+
+    static func main() async throws {
+        let a = Array(CommandLine.arguments.dropFirst())
+        guard #available(macOS 15.0, *) else { exit(2) }
+        if a.first == "download" {
+            let dir = try await Vela3ModelStore.ensure { file, bytes in print(bytes == 0 ? "downloading \(file)" : "  \(bytes / 1_048_576) MB") }
+            print(dir.path)
+            return
+        }
+        guard a.count >= 3, a[0] == "parity" else {
+            fputs("usage: Vela3Check parity <model dir> <fixtures.json> | Vela3Check download\n", stderr)
+            exit(2)
+        }
+        let fx = try JSONDecoder().decode(Fixtures.self, from: Data(contentsOf: URL(fileURLWithPath: a[2])))
+        let t0 = Date()
+        let m = try await Vela3Manager.load(from: URL(fileURLWithPath: a[1]))
+        try await m.warm()
+        print(String(format: "loaded + warmed in %.1f s", Date().timeIntervalSince(t0)))
+
+        var bad = 0
+        for t in fx.tokens {
+            let (ids, offs) = m.tokenize(t.text)
+            if ids != t.ids || offs.map({ [$0.0, $0.1] }) != t.offsets {
+                bad += 1
+                print("token mismatch: \(t.text.debugDescription.prefix(80))")
+            }
+        }
+        print("tokens: \(fx.tokens.count) texts, \(bad) mismatches")
+
+        var seqBad = 0, flips = 0, maxDp = 0.0
+        var decisionMs: [Double] = []
+        for d in fx.decisions {
+            let q: Vela3Question =
+                d.type == "noul"
+                ? .yesNo(id: d.id, instructions: d.instructions)
+                : .choice(id: d.id, instructions: d.instructions, options: d.options.map { ($0[0], $0[1]) })
+            if m.decisionSequence(state: d.state, question: q) != d.ids { seqBad += 1 }
+            let r = try await m.decide(state: d.state, questions: [q])
+            decisionMs.append(r.timing.totalMs)
+            let got = r.decisions[0]
+            let want = zip(d.names, d.probabilities).max { $0.1 < $1.1 }!.0
+            if got.answer != want { flips += 1 }
+            for (n, p) in zip(d.names, d.probabilities) { maxDp = max(maxDp, abs((got.probability(n) ?? -1) - p)) }
+        }
+        print(String(format: "decisions: %d questions, %d sequence mismatches, %d answers differ, max |dp| %.5f", fx.decisions.count, seqBad, flips, maxDp))
+
+        var spanSeqBad = 0, spanBad = 0, nSpans = 0
+        var spanMs: [Double] = []
+        for c in fx.spans {
+            let (ids, r): ([Int], Vela3SpanResult)
+            if c.kind == "pii" {
+                ids = m.spanSequence(pii: c.text!)
+                r = try await m.pii(c.text!)
+            } else {
+                ids = m.spanSequence(context: c.context!, answer: c.answer!)
+                r = try await m.unsupported(context: c.context!, answer: c.answer!)
+            }
+            spanMs.append(r.timing.totalMs)
+            if ids != c.ids { spanSeqBad += 1 }
+            let got = Set(r.spans.map { "\($0.label)|\($0.start)|\($0.end)" })
+            let want = Set(c.spans.map { "\($0.label)|\($0.start)|\($0.end)" })
+            nSpans += want.count
+            if got != want || abs(r.threshold - c.threshold) > 1e-9 {
+                spanBad += 1
+                print("span mismatch [\(c.kind)]: want \(want.subtracting(got).sorted()) got extra \(got.subtracting(want).sorted())")
+            }
+        }
+        print("spans: \(fx.spans.count) calls (\(nSpans) spans), \(spanSeqBad) sequence mismatches, \(spanBad) span sets differ")
+        func median(_ x: [Double]) -> Double { x.isEmpty ? 0 : x.sorted()[x.count / 2] }
+        print(String(format: "median call: decision %.1f ms, span %.1f ms (GPU, end to end)", median(decisionMs), median(spanMs)))
+        if bad + seqBad + flips + spanSeqBad + spanBad > 0 { exit(1) }
+    }
+}

From 7792562160721316d690809e71100b795af4ab2d Mon Sep 17 00:00:00 2001
From: Alex-Wengg <hanweng9@gmail.com>
Date: Wed, 28 Oct 2026 19:47:58 -0400
Subject: [PATCH 2/2] Vela 3.0: address review (long inputs, tokenizer,
 cold-start abort, validation)

- Long span inputs follow the release's assemble/_windows with a 1,024-token
  pass: the other part (an unsupported-claim context) is cut first (to 64
  tokens, then 1), then the target is read in overlapping windows, each
  window re-fitted (a short last window gives the context its room back);
  per-word logits are averaged over windows (-30 where uncovered).
- Tokenizer: added tokens honour lstrip / rstrip (<|mask|> absorbs the
  whitespace before it, as HF); BPE merges via a (rank, position) min-heap
  instead of a quadratic rescan; long pieces are not cached.
- Core ML: hidden states go into an output backing with a synchronous
  prediction. With Core ML allocating the output, the first GPU prediction
  on a cold compile cache aborted in MPSGraphTensorData
  (shape.count = 0 != strides.count = 3) in ~1 of 3 cold runs; with the
  backing 0 of 20 (12 cold, 8 under a launcher that crashed 3 of 3).
- Validation: heads tensor shapes (span heads must carry w_t / w_e /
  log_tau_span), safetensors bounds, hidden-state shape, pii_buckets,
  duplicate option names; heads errors surface as Vela3Error.
- The label schema is tokenized once at load.
- Vela3Check: compares every window's sequence and span probabilities, fails
  on probability drift (> 1e-3), adds a `warm` cold-start command; fixtures
  add <|mask|>, a 3,000-letter word, 2- and 9-window PII and long contexts.

Parity vs the Python runtime: 0 / 23 token, 0 / 120 decision and 0 / 16
span-set mismatches (29 windows, 599 spans), max |dp| 0.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 README.md                                   |   8 +-
 Sources/FluidUse/Vela2/Vela2Manager.swift   |  21 +-
 Sources/FluidUse/Vela3/Vela3Manager.swift   | 293 ++++++++++++++------
 Sources/FluidUse/Vela3/Vela3Tokenizer.swift | 129 +++++++--
 Sources/Vela3Check/main.swift               |  39 ++-
 5 files changed, 358 insertions(+), 132 deletions(-)

diff --git a/README.md b/README.md
index 15029e2..658348b 100644
--- a/README.md
+++ b/README.md
@@ -319,9 +319,11 @@ UltraBERT-380M encoder, Apache-2.0) on Core ML: decisions over options you name
 the two label sets of the release's `span_sets` adapter, personal information (17 types) and the words of an answer its
 context does not support. One encoder pass per question on the GPU (~10 ms for a decision, ~18 ms for a PII pass over a
 paragraph; the Neural Engine is slower for this encoder at every length). Rendering, readout, thresholds and the span
-decoder reproduce the release's own code: against the Python runtime on the same encoders, 0 token mismatches on 17
-Unicode-heavy texts, 0 / 120 decisions and 0 / 12 span sets differ (`swift run -c release Vela3Check parity …`). Inputs are
-limited to 1,024 tokens per pass. The pinned snapshot downloads from
+decoder reproduce the release's own code: against the Python runtime on the same encoders, 0 token mismatches on 23
+Unicode-heavy texts, 0 / 120 decisions and 0 / 16 span sets differ, including windowed inputs
+(`swift run -c release Vela3Check parity …`). One pass holds 1,024 tokens: a longer decision throws `tooLong`; for spans the
+context of an unsupported-claim check is cut first, then long text is read in overlapping windows (the release's rule).
+The pinned snapshot downloads from
 [FluidInference/vela-3.0-coreml](https://huggingface.co/FluidInference/vela-3.0-coreml) on first use (~1.48 GB: two
 multifunction packages, macOS 15 / iOS 18).
 
diff --git a/Sources/FluidUse/Vela2/Vela2Manager.swift b/Sources/FluidUse/Vela2/Vela2Manager.swift
index efc3cf9..c8c2fce 100644
--- a/Sources/FluidUse/Vela2/Vela2Manager.swift
+++ b/Sources/FluidUse/Vela2/Vela2Manager.swift
@@ -517,17 +517,26 @@ struct Vela2Heads: Sendable {
         try self.init(weights: w)
     }
 
-    /// Heads from named fp32 tensors (Vela 3 ships them as safetensors). A decision-only head set has no span
-    /// temperature (`log_tau_span`) and is never asked for span logits.
-    init(weights w: [String: [Float]]) throws {
+    /// Heads from named fp32 tensors (Vela 3 ships them as safetensors). `span: false` is a decision-only head set
+    /// (no `w_t` / `w_e` / `log_tau_span`), which is never asked for span logits.
+    init(weights w: [String: [Float]], span: Bool = true) throws {
         guard let n = w["norm.weight"], let p = w["w_o.bias"], let logTau = w["log_tau"]?.first else {
             throw Vela2Error.invalidAsset("readout heads are missing norm / w_o / log_tau")
         }
-        self.hidden = n.count
-        self.proj = p.count
+        let h = n.count, d = p.count
+        var shapes: [(String, Int)] = [
+            ("norm.bias", h), ("w_o.weight", d * h), ("w_q.weight", d * h), ("w_q.bias", d), ("w_p.weight", d * h), ("w_p.bias", d),
+            ("cls_mlp.0.weight", 2 * h * h), ("cls_mlp.0.bias", 2 * h), ("cls_mlp.3.weight", 2 * h), ("cls_mlp.3.bias", 1),
+        ]
+        if span { shapes += [("w_t.weight", d * h), ("w_t.bias", d), ("w_e.weight", d * h), ("w_e.bias", d), ("log_tau_span", 1)] }
+        for (name, count) in shapes where w[name]?.count != count {
+            throw Vela2Error.invalidAsset("readout head \(name) is missing or has \(w[name]?.count ?? 0) values, expected \(count)")
+        }
+        self.hidden = h
+        self.proj = d
         self.w = w
         self.tau = exp(logTau)
-        self.tauSpan = exp(w["log_tau_span"]?.first ?? 0)
+        self.tauSpan = span ? exp(w["log_tau_span"]![0]) : 1
     }
 
     private func layerNorm(_ x: ArraySlice<Float>) -> [Float] {
diff --git a/Sources/FluidUse/Vela3/Vela3Manager.swift b/Sources/FluidUse/Vela3/Vela3Manager.swift
index 514cef3..8fa0496 100644
--- a/Sources/FluidUse/Vela3/Vela3Manager.swift
+++ b/Sources/FluidUse/Vela3/Vela3Manager.swift
@@ -49,6 +49,8 @@ public struct Vela3DecisionResult: Sendable {
 public struct Vela3SpanResult: Sendable {
     public let spans: [Vela3Span]
     public let threshold: Double
+    /// Encoder passes the target text was read in (1 unless it was longer than one pass's budget).
+    public let windows: Int
     public let timing: Vela3Timing
 }
 
@@ -69,10 +71,12 @@ public enum Vela3Error: Error, LocalizedError, Sendable {
 /// Vela 3.0 vela3-fast (vLLM Semantic Router × KR Labs; UltraBERT-380M encoder) on Core ML, from
 /// [FluidInference/vela-3.0-coreml](https://huggingface.co/FluidInference/vela-3.0-coreml): decisions over options you
 /// name (the decision backbone) and the two label sets of the release's `span_sets` adapter, personal information (17
-/// types) and claims of an answer its context does not support. One encoder pass per question, on the GPU (the Neural
+/// types) and claims of an answer its context does not support. One encoder pass per question on the GPU (the Neural
 /// Engine is slower for this encoder at every length and drifts further from the fp32 answers). Rendering, readout,
-/// thresholds and the span decoder reproduce the release's `vela3_encoder.py` / `vela3_schema.py`; inputs are limited to
-/// 1,024 tokens per pass (the release windows longer span inputs).
+/// thresholds, the span decoder and long-input handling reproduce the release's `vela3_encoder.py` / `vela3_schema.py`
+/// with a 1,024-token pass: a decision longer than that throws `tooLong`; for spans the other part (the context of an
+/// unsupported-claim check) is cut first, then the target text is read in overlapping windows (the release's own rule,
+/// as the Python runtime of the snapshot; the PyTorch release windows at 8,192 tokens).
 @available(macOS 15.0, iOS 18.0, *)
 public final class Vela3Manager: Sendable {
     struct Markers: Sendable {
@@ -80,10 +84,12 @@ public final class Vela3Manager: Sendable {
         let seg: [String: Int]
     }
 
+    /// A trained label set with its schema prefix (`<bos> ([E] label: description)*`) tokenized once.
     struct SpanSet: Sendable {
         let names: [String]
-        let descriptions: [String]
         let role: String
+        let prefix: [Int]
+        let ePos: [Int]
     }
 
     private let tokenizer: Vela3Tokenizer
@@ -103,6 +109,10 @@ public final class Vela3Manager: Sendable {
 
     public static let decisionLengths = [128, 256, 512, 1024]
     public static let spanLengths = [512, 1024]
+    /// The release's long-input constants: the other part keeps at least this many tokens before the target is cut,
+    /// and windows overlap by up to `overlap` tokens (a quarter of the window at most).
+    static let shrinkFloor = 64
+    static let overlap = 512
 
     public static func load(from directory: URL) async throws -> Vela3Manager {
         func json(_ name: String) throws -> [String: Any] {
@@ -122,36 +132,59 @@ public final class Vela3Manager: Sendable {
         guard let span = vela["span"] as? [String: Any], let sets = span["router_label_sets"] as? [String: [String]],
             let schemas = span["schemas"] as? [String: [String: Any]], let setAdapter = span["set_adapter"] as? [String: Any],
             let temperature = setAdapter["router_set_temperature"] as? Double,
-            let buckets = setAdapter["pii_buckets"] as? [[String: Any]],
+            let buckets = setAdapter["pii_buckets"] as? [[String: Any]], !buckets.isEmpty,
             let byset = setAdapter["thresholds_by_set"] as? [String: Double], let halu = byset["halu"]
         else { throw Vela3Error.invalidAsset("vela3_config.json is missing the span_sets settings") }
+        let piiBuckets = try buckets.map { b -> (Int, Double) in
+            guard let t = b["threshold"] as? Double, let n = b["max_tokens"] as? NSNumber else {
+                throw Vela3Error.invalidAsset("vela3_config.json pii_buckets entry \(b)")
+            }
+            return (n.intValue, t)
+        }
+        let tokenizer = try Vela3Tokenizer(tokenizerJsonURL: directory.appendingPathComponent("tokenizer.json"))
+        let e = try m("[E]")
         func spanSet(_ name: String) throws -> SpanSet {
-            guard let names = sets[name], let schema = schemas[name], let labels = schema["labels"] as? [String: String],
-                let over = schema["over"] as? String
+            guard let names = sets[name], !names.isEmpty, Set(names).count == names.count, let schema = schemas[name],
+                let labels = schema["labels"] as? [String: String], let over = schema["over"] as? String
             else { throw Vela3Error.invalidAsset("vela3_config.json label set \(name)") }
-            return SpanSet(names: names, descriptions: names.map { labels[$0] ?? "" }, role: over)
+            var prefix = [bos]
+            var ePos: [Int] = []
+            for n in names {
+                let d = labels[n] ?? ""
+                ePos.append(prefix.count)
+                prefix.append(e)
+                prefix += tokenizer.encode(d.isEmpty ? n : "\(n): \(d)")
+            }
+            return SpanSet(names: names, role: over, prefix: prefix, ePos: ePos)
+        }
+        func heads(_ file: String, span: Bool) throws -> Vela2Heads {
+            do {
+                return try Vela2Heads(weights: try safetensors(directory.appendingPathComponent(file)), span: span)
+            } catch let error as Vela3Error {
+                throw error
+            } catch {
+                throw Vela3Error.invalidAsset("\(file): \(error.localizedDescription)")
+            }
+        }
+        let decisionHeads = try heads("heads_decision.safetensors", span: false)
+        let spanHeads = try heads("heads_span_sets.safetensors", span: true)
+        guard decisionHeads.hidden == spanHeads.hidden else {
+            throw Vela3Error.invalidAsset("decision and span heads disagree on the hidden size")
         }
         let decisionModels = try await models(directory.appendingPathComponent("Vela3Decision.mlpackage"), lengths: decisionLengths)
         let spanModels = try await models(directory.appendingPathComponent("Vela3SpanSets.mlpackage"), lengths: spanLengths)
         return Vela3Manager(
-            tokenizer: try Vela3Tokenizer(tokenizerJsonURL: directory.appendingPathComponent("tokenizer.json")),
+            tokenizer: tokenizer,
             markers: Markers(
-                q: try m("[Q]"), o: try m("[O]"), e: try m("[E]"), sep: try m("[SEP_SCHEMA]"),
+                q: try m("[Q]"), o: try m("[O]"), e: e, sep: try m("[SEP_SCHEMA]"),
                 seg: ["user": try m("[SEG_user]"), "context": try m("[SEG_context]"), "answer": try m("[SEG_answer]")]),
-            bos: bos, eos: eos,
-            decisionHeads: try Vela2Heads(weights: try safetensors(directory.appendingPathComponent("heads_decision.safetensors"))),
-            spanHeads: try Vela2Heads(weights: try safetensors(directory.appendingPathComponent("heads_span_sets.safetensors"))),
-            decisionModels: decisionModels, spanModels: spanModels,
-            pii: try spanSet("pii"), unsupported: try spanSet("halu"), spanTemperature: temperature,
-            piiBuckets: buckets.compactMap { b in
-                guard let t = b["threshold"] as? Double, let n = b["max_tokens"] as? NSNumber else { return nil }
-                return (n.intValue, t)
-            }, unsupportedThreshold: halu)
+            bos: bos, eos: eos, decisionHeads: decisionHeads, spanHeads: spanHeads, decisionModels: decisionModels,
+            spanModels: spanModels, pii: try spanSet("pii"), unsupported: try spanSet("halu"), spanTemperature: temperature,
+            piiBuckets: piiBuckets, unsupportedThreshold: halu)
     }
 
     private static func models(_ package: URL, lengths: [Int]) async throws -> [(length: Int, model: MLModel)] {
-        var compiled = package.deletingPathExtension().appendingPathExtension("mlmodelc")
-        if !FileManager.default.fileExists(atPath: compiled.path) { compiled = try await KevManager.compiled(package) }
+        let compiled = try await KevManager.compiled(package)
         var out: [(Int, MLModel)] = []
         for length in lengths {
             let configuration = MLModelConfiguration()
@@ -165,18 +198,24 @@ public final class Vela3Manager: Sendable {
     /// fp32 tensors of a safetensors file by name.
     static func safetensors(_ url: URL) throws -> [String: [Float]] {
         let data = try Data(contentsOf: url)
-        guard data.count >= 8 else { throw Vela3Error.invalidAsset(url.lastPathComponent) }
-        let headerLength = data.prefix(8).enumerated().reduce(0) { $0 | (Int($1.element) << (8 * $1.offset)) }
-        guard 8 + headerLength <= data.count,
-            let header = try JSONSerialization.jsonObject(with: data.subdata(in: 8..<(8 + headerLength))) as? [String: Any]
-        else { throw Vela3Error.invalidAsset("\(url.lastPathComponent) header") }
+        let name = url.lastPathComponent
+        guard data.count >= 8 else { throw Vela3Error.invalidAsset("\(name) is too short") }
+        let length = data.prefix(8).enumerated().reduce(UInt64(0)) { $0 | (UInt64($1.element) << (8 * UInt64($1.offset))) }
+        guard length <= UInt64(data.count - 8) else { throw Vela3Error.invalidAsset("\(name) header runs past the file") }
+        let base = 8 + Int(length)
+        guard let header = try JSONSerialization.jsonObject(with: data.subdata(in: 8..<base)) as? [String: Any] else {
+            throw Vela3Error.invalidAsset("\(name) header")
+        }
         var out: [String: [Float]] = [:]
-        for (name, value) in header where name != "__metadata__" {
+        for (tensor, value) in header where tensor != "__metadata__" {
             guard let meta = value as? [String: Any], meta["dtype"] as? String == "F32", let range = meta["data_offsets"] as? [Int],
-                range.count == 2
-            else { throw Vela3Error.invalidAsset("\(url.lastPathComponent): \(name) is not an F32 tensor") }
-            let bytes = data.subdata(in: (8 + headerLength + range[0])..<(8 + headerLength + range[1]))
-            out[name] = bytes.withUnsafeBytes { Array($0.bindMemory(to: Float.self)) }
+                range.count == 2, let shape = meta["shape"] as? [Int]
+            else { throw Vela3Error.invalidAsset("\(name): \(tensor) is not an F32 tensor") }
+            let (a, b) = (range[0], range[1])
+            guard a >= 0, a <= b, b <= data.count - base, (b - a) == 4 * shape.reduce(1, *) else {
+                throw Vela3Error.invalidAsset("\(name): \(tensor) offsets \(range) do not match its shape \(shape)")
+            }
+            out[tensor] = data.subdata(in: (base + a)..<(base + b)).withUnsafeBytes { Array($0.bindMemory(to: Float.self)) }
         }
         return out
     }
@@ -203,9 +242,12 @@ public final class Vela3Manager: Sendable {
 
     /// Runs every encoder function once so no request pays for the first dispatch.
     public func warm() async throws {
-        for (length, model) in (decisionModels + spanModels).reversed() {
+        for (length, model) in decisionModels.reversed() {
             _ = try await encode(ids: [bos, eos], model: model, length: length, dim: decisionHeads.hidden)
         }
+        for (length, model) in spanModels.reversed() {
+            _ = try await encode(ids: [bos, eos], model: model, length: length, dim: spanHeads.hidden)
+        }
     }
 
     // MARK: decisions (vela3_encoder.DecisionEncoder)
@@ -216,8 +258,11 @@ public final class Vela3Manager: Sendable {
         var seen = Set<String>()
         for q in questions {
             guard seen.insert(q.id).inserted else { throw Vela3Error.invalidRequest("duplicate question id \(q.id)") }
-            if case .choice(let id, _, let options) = q, options.count < 2 {
-                throw Vela3Error.invalidRequest("choice \(id) needs at least 2 options")
+            if case .choice(let id, _, let options) = q {
+                guard options.count >= 2 else { throw Vela3Error.invalidRequest("choice \(id) needs at least 2 options") }
+                guard Set(options.map(\.name)).count == options.count else {
+                    throw Vela3Error.invalidRequest("choice \(id) has duplicate option names")
+                }
             }
         }
         let stateIDs = tokenizer.encode(state)
@@ -282,7 +327,7 @@ public final class Vela3Manager: Sendable {
     /// Personal information in `text` (17 types: names, e-mail addresses, phone numbers, street addresses, card numbers, …).
     public func pii(_ text: String, threshold: Double? = nil) async throws -> Vela3SpanResult {
         try await spans(set: pii, parts: [("user", text)], threshold: threshold) { tokens in
-            self.piiBuckets.first { tokens <= $0.maxTokens }?.threshold ?? self.piiBuckets.last?.threshold ?? 0.5
+            self.piiBuckets.first { tokens <= $0.maxTokens }?.threshold ?? self.piiBuckets[self.piiBuckets.count - 1].threshold
         }
     }
 
@@ -299,72 +344,147 @@ public final class Vela3Manager: Sendable {
         return (t.map(\.id), t.map { ($0.start, $0.end) })
     }
 
-    /// The encoder input of a PII or unsupported-claim call (for parity checks).
-    public func spanSequence(pii text: String) -> [Int] { spanRecord(set: pii, parts: [("user", text)]).0.ids }
-    public func spanSequence(context: String, answer: String) -> [Int] {
-        spanRecord(set: unsupported, parts: [("context", context), ("answer", answer)]).0.ids
+    /// The encoder inputs (one per window) of a PII or unsupported-claim call (for parity checks).
+    public func spanSequences(pii text: String) throws -> [[Int]] { try plan(set: pii, parts: [("user", text)]).passes.map { $0.rec.ids } }
+    public func spanSequences(context: String, answer: String) throws -> [[Int]] {
+        try plan(set: unsupported, parts: [("context", context), ("answer", answer)]).passes.map { $0.rec.ids }
+    }
+
+    struct Part {
+        let role: String
+        let scalars: [Unicode.Scalar]
+        let tokens: [Vela3Tokenizer.Token]
+        var ids: [Int] { tokens.map(\.id) }
+    }
+
+    struct Plan {
+        /// One encoder pass per window, with the target words (indices into `words`) it reads.
+        let passes: [(rec: Vela2Manager.Record, words: [Int])]
+        let words: [(Int, Int)]
+        let target: [Unicode.Scalar]
+        let targetTokens: Int
     }
 
     private func spans(
         set: SpanSet, parts: [(role: String, text: String)], threshold: Double?, defaultThreshold: (Int) -> Double
     ) async throws -> Vela3SpanResult {
         let started = Date()
-        let (rec, target) = spanRecord(set: set, parts: parts)
-        guard let span = rec.span else { throw Vela3Error.invalidRequest("no \(set.role) part") }
-        guard let (length, model) = spanModels.first(where: { rec.ids.count <= $0.length }) else {
-            throw Vela3Error.tooLong("\(rec.ids.count) tokens exceed the largest encoder function L\(Self.spanLengths.last!)")
+        let plan = try self.plan(set: set, parts: parts)
+        // per word: logits averaged over the windows that read it (-30 where none did), as predict_raw
+        var acc = [[Double]](repeating: [Double](repeating: 0, count: set.names.count), count: plan.words.count)
+        var cnt = [Int](repeating: 0, count: plan.words.count)
+        var encoderMs = 0.0
+        var used: [Int] = []
+        for pass in plan.passes {
+            guard let (length, model) = spanModels.first(where: { pass.rec.ids.count <= $0.length }) else {
+                throw Vela3Error.tooLong("\(pass.rec.ids.count) tokens exceed L\(Self.spanLengths.last!)")
+            }
+            let t = Date()
+            let hidden = try await encode(ids: pass.rec.ids, model: model, length: length, dim: spanHeads.hidden)
+            encoderMs += Date().timeIntervalSince(t) * 1000
+            used.append(length)
+            let logits = spanHeads.run(hidden: hidden, dim: spanHeads.hidden, rec: pass.rec).1
+            for (row, w) in zip(logits, pass.words) {
+                for k in 0..<row.count { acc[w][k] += Double(row[k]) }
+                cnt[w] += 1
+            }
+        }
+        let probs = zip(acc, cnt).map { row, c in
+            row.map { c > 0 ? 1 / (1 + exp(-($0 / Double(c)) / spanTemperature)) : 1 / (1 + exp(30 / spanTemperature)) }
         }
-        let t = Date()
-        let hidden = try await encode(ids: rec.ids, model: model, length: length, dim: spanHeads.hidden)
-        let encoderMs = Date().timeIntervalSince(t) * 1000
-        let logits = spanHeads.run(hidden: hidden, dim: spanHeads.hidden, rec: rec).1
-        let probs = logits.map { row in row.map { 1 / (1 + exp(-Double($0) / spanTemperature)) } }
-        let thr = threshold ?? defaultThreshold(span.tokenCount)
-        let decoded = span.wOffsets.isEmpty ? [] : Vela2Text.decodeSpans(probs, offsets: span.wOffsets, text: target, threshold: thr)
+        let thr = threshold ?? defaultThreshold(plan.targetTokens)
+        let decoded = plan.words.isEmpty ? [] : Vela2Text.decodeSpans(probs, offsets: plan.words, text: plan.target, threshold: thr)
         let out = decoded.map {
             Vela3Span(
-                label: span.names[$0.label], start: $0.start, end: $0.end,
-                text: String(String.UnicodeScalarView(target[$0.start..<$0.end])), probability: $0.probability)
+                label: set.names[$0.label], start: $0.start, end: $0.end,
+                text: String(String.UnicodeScalarView(plan.target[$0.start..<$0.end])), probability: $0.probability)
         }
         return Vela3SpanResult(
-            spans: out, threshold: thr,
-            timing: Vela3Timing(encoderMs: encoderMs, totalMs: Date().timeIntervalSince(started) * 1000, buckets: [length]))
+            spans: out, threshold: thr, windows: plan.passes.count,
+            timing: Vela3Timing(encoderMs: encoderMs, totalMs: Date().timeIntervalSince(started) * 1000, buckets: used))
     }
 
-    /// `<bos> ([E] label: description)* [SEP_SCHEMA] ([SEG_role] part)* <eos>` (vela3_schema.assemble with one span
-    /// question; its text is not part of the input), with the target part's word units for the span readout.
-    private func spanRecord(set: SpanSet, parts: [(role: String, text: String)]) -> (Vela2Manager.Record, [Unicode.Scalar]) {
-        var ids = [bos]
-        var ePos: [Int] = []
-        for (name, description) in zip(set.names, set.descriptions) {
-            ePos.append(ids.count)
-            ids.append(markers.e)
-            ids += tokenizer.encode(description.isEmpty ? name : "\(name): \(description)")
+    /// The release's `_assemble` / `assemble` / `_windows` for one span question in a 1,024-token pass: cut the part
+    /// the question is not over (to `shrinkFloor`, then to 1 token), then, if the target still does not fit, read it in
+    /// windows of the room left, overlapping by min(`overlap`, window / 4) tokens.
+    func plan(set: SpanSet, parts raw: [(role: String, text: String)]) throws -> Plan {
+        let parts = raw.map { p -> Part in
+            let scalars = Array(p.text.unicodeScalars)
+            return Part(role: p.role, scalars: scalars, tokens: tokenizer.tokens(scalars))
         }
-        ids.append(markers.sep)
-        var span: Vela2Manager.SpanRec?
-        var target: [Unicode.Scalar] = []
-        for part in parts {
-            let scalars = Array(part.text.unicodeScalars)
-            let toks = tokenizer.tokens(scalars)
-            let start = ids.count
-            ids.append(markers.seg[part.role]!)
-            ids += toks.map(\.id)
-            if part.role == set.role {
-                let offsets = toks.map { ($0.start, $0.end) }
-                let (words, first) = Vela2Text.wordFirstTokens(scalars, offsets: offsets)
-                span = Vela2Manager.SpanRec(
-                    id: set.role, role: part.role, names: set.names, ePos: ePos, wPos: first.map { start + 1 + $0 }, wOffsets: words,
-                    tokenCount: toks.count)
-                target = scalars
+        guard let target = parts.first(where: { $0.role == set.role }) else { throw Vela3Error.invalidRequest("no \(set.role) part") }
+        let (words, first) = Vela2Text.wordFirstTokens(target.scalars, offsets: target.tokens.map { ($0.start, $0.end) })
+        let maxLength = Self.spanLengths.last!
+        let fixed = set.prefix.count + 1 + 1 + parts.count  // prefix (with <bos>), [SEP_SCHEMA], <eos>, one [SEG] per part
+        let t = parts.firstIndex { $0.role == set.role }!
+        let shrink = parts.firstIndex { $0.role != set.role }
+        /// Part lengths after `assemble`'s cuts for a target of `targetCount` tokens: the other part first (to the
+        /// floor, then to 1 token), then the target. Each window is re-assembled this way, so a short last window
+        /// gives the other part its room back.
+        func fit(_ targetCount: Int) -> [Int] {
+            var lengths = parts.map { $0.tokens.count }
+            lengths[t] = targetCount
+            func over() -> Int { fixed + lengths.reduce(0, +) - maxLength }
+            if let s = shrink {
+                if over() > 0 { lengths[s] = max(min(lengths[s], Self.shrinkFloor), lengths[s] - over()) }
+                if over() > 0 { lengths[s] = max(1, lengths[s] - over()) }
             }
+            if over() > 0 { lengths[t] = max(1, lengths[t] - over()) }
+            return lengths
         }
-        ids.append(eos)
-        return (Vela2Manager.Record(ids: ids, questions: [], span: span), target)
+        let n = target.tokens.count
+        let lengths = fit(n)
+        guard fixed + lengths.reduce(0, +) <= maxLength else {
+            throw Vela3Error.tooLong("the label schema alone does not fit in \(maxLength) tokens")
+        }
+        let cut = lengths[t] < n
+        let partIDs = parts.map(\.ids)
+        func record(_ a: Int, _ b: Int) -> (Vela2Manager.Record, [Int]) {
+            let lengths = fit(b - a)
+            var ids = set.prefix
+            ids.append(markers.sep)
+            var span: Vela2Manager.SpanRec?
+            var sel: [Int] = []
+            for (k, p) in parts.enumerated() {
+                let start = ids.count
+                ids.append(markers.seg[p.role]!)
+                if k == t {
+                    ids += partIDs[k][a..<b]
+                    sel = first.indices.filter { first[$0] >= a && first[$0] < b }
+                    span = Vela2Manager.SpanRec(
+                        id: set.role, role: p.role, names: set.names, ePos: set.ePos, wPos: sel.map { start + 1 + first[$0] - a },
+                        wOffsets: sel.map { words[$0] }, tokenCount: b - a)
+                } else {
+                    ids += partIDs[k].prefix(lengths[k])
+                }
+            }
+            ids.append(eos)
+            return (Vela2Manager.Record(ids: ids, questions: [], span: span), sel)
+        }
+        var passes: [(rec: Vela2Manager.Record, words: [Int])] = []
+        if !cut {
+            passes.append(record(0, n))
+        } else {
+            let window = lengths[t]
+            let overlap = min(Self.overlap, window / 4)
+            let stride = max(1, window - overlap)
+            var a = 0
+            while a < max(1, n - overlap) {
+                let b = min(n, a + window)
+                passes.append(record(a, b))
+                if b >= n { break }
+                a += stride
+            }
+        }
+        return Plan(passes: passes, words: words, target: target.scalars, targetTokens: n)
     }
 
     // MARK: encoder
 
+    private static func predict(_ model: MLModel, _ input: MLFeatureProvider, options: MLPredictionOptions) throws -> MLFeatureProvider {
+        try model.prediction(from: input, options: options)
+    }
+
     private func encode(ids: [Int], model: MLModel, length: Int, dim: Int) async throws -> [Float] {
         let input = try MLMultiArray(shape: [1, NSNumber(value: length)], dataType: .int32)
         let mask = try MLMultiArray(shape: [1, NSNumber(value: length)], dataType: .int32)
@@ -374,10 +494,13 @@ public final class Vela3Manager: Sendable {
             ip[i] = i < ids.count ? Int32(ids[i]) : 0
             mp[i] = i < ids.count ? 1 : 0
         }
-        let out = try await model.prediction(from: MLDictionaryFeatureProvider(dictionary: ["input_ids": input, "attention_mask": mask]))
-        guard let hidden = out.featureValue(for: "hidden")?.multiArrayValue, hidden.dataType == .float16 else {
-            throw Vela3Error.invalidAsset("encoder returned no fp16 hidden states")
-        }
+        // The hidden states go into a buffer we allocate (output backing), with a synchronous prediction. Letting Core ML
+        // allocate the output, the first GPU prediction on a cold compile cache aborted in MPSGraphTensorData
+        // (`shape.count = 0 != strides.count = 3`) in about 1 of 3 cold runs (macOS 27.0); with the backing, 0 of 20.
+        let hidden = try MLMultiArray(shape: [1, NSNumber(value: length), NSNumber(value: dim)], dataType: .float16)
+        let options = MLPredictionOptions()
+        options.outputBackings = ["hidden": hidden]
+        _ = try Self.predict(model, MLDictionaryFeatureProvider(dictionary: ["input_ids": input, "attention_mask": mask]), options: options)
         let strides = hidden.strides.map(\.intValue)
         var h = [Float](repeating: 0, count: ids.count * dim)
         let src = hidden.dataPointer.assumingMemoryBound(to: Float16.self)
diff --git a/Sources/FluidUse/Vela3/Vela3Tokenizer.swift b/Sources/FluidUse/Vela3/Vela3Tokenizer.swift
index 47bd06e..4bb69e4 100644
--- a/Sources/FluidUse/Vela3/Vela3Tokenizer.swift
+++ b/Sources/FluidUse/Vela3/Vela3Tokenizer.swift
@@ -2,7 +2,8 @@ import Foundation
 import os
 
 /// The byte-level BPE tokenizer of vela3-fast (UltraBERT's GPT-2 style `tokenizer.json`), with Hugging Face `tokenizers`
-/// offsets: special tokens matched literally, the GPT-2 split regex, merges by rank (leftmost first on ties), and each
+/// offsets: special tokens matched literally (`lstrip` / `rstrip` ones absorb the whitespace next to them, offsets
+/// included), the GPT-2 split regex, merges by rank (leftmost first on ties, O(n log n)), and each
 /// token's offsets running from the character of its first byte to the character of its last byte (so pieces of one
 /// multi-byte character share its offsets). Offsets are Unicode scalar indices, as Python string indices. No offset
 /// trimming: this tokenizer's post-processor is `TemplateProcessing`, so the leading space stays in a token's span.
@@ -18,10 +19,11 @@ public final class Vela3Tokenizer: Sendable {
     private let vocabulary: [String: Int]
     private let mergeRanks: [String: Int]
     /// Added tokens, longest first, so a longer token wins over one it contains.
-    private let addedTokens: [(scalars: [Unicode.Scalar], id: Int)]
+    private let addedTokens: [(scalars: [Unicode.Scalar], id: Int, lstrip: Bool, rstrip: Bool)]
     private let byteToCharacter: [String]
     private let regex: NSRegularExpression
-    /// Encoded pieces (token ids with their byte ranges); ordinary text repeats the same words.
+    /// Encoded pieces (token ids with their byte ranges); ordinary text repeats the same words. Long pieces are not
+    /// cached.
     private let cache = OSAllocatedUnfairLock<[String: [(Int, Int, Int)]]>(initialState: [:])
 
     public init(tokenizerJsonURL: URL) throws {
@@ -43,9 +45,9 @@ public final class Vela3Tokenizer: Sendable {
             }
         }
         mergeRanks = ranks
-        let added = (root["added_tokens"] as? [[String: Any]] ?? []).compactMap { t -> ([Unicode.Scalar], Int)? in
+        let added = (root["added_tokens"] as? [[String: Any]] ?? []).compactMap { t -> ([Unicode.Scalar], Int, Bool, Bool)? in
             guard let content = t["content"] as? String, let id = t["id"] as? Int, !content.isEmpty else { return nil }
-            return (Array(content.unicodeScalars), id)
+            return (Array(content.unicodeScalars), id, t["lstrip"] as? Bool ?? false, t["rstrip"] as? Bool ?? false)
         }
         addedTokens = added.sorted { $0.0.count > $1.0.count }
         byteToCharacter = Self.bytesToUnicode()
@@ -61,9 +63,13 @@ public final class Vela3Tokenizer: Sendable {
         var i = 0
         while i < scalars.count {
             if let match = addedTokens.first(where: { matches($0.scalars, scalars, at: i) }) {
-                if segmentStart < i { out += textTokens(scalars, segmentStart..<i) }
-                out.append(Token(id: match.id, start: i, end: i + match.scalars.count))
-                i += match.scalars.count
+                var start = i
+                var end = i + match.scalars.count
+                if match.lstrip { while start > segmentStart, scalars[start - 1].properties.isWhitespace { start -= 1 } }
+                if match.rstrip { while end < scalars.count, scalars[end].properties.isWhitespace { end += 1 } }
+                if segmentStart < start { out += textTokens(scalars, segmentStart..<start) }
+                out.append(Token(id: match.id, start: start, end: end))
+                i = end
                 segmentStart = i
             } else {
                 i += 1
@@ -117,32 +123,99 @@ public final class Vela3Tokenizer: Sendable {
         return out
     }
 
-    /// BPE over the byte characters of one piece -> (token id, first byte, end byte).
+    /// BPE over the byte characters of one piece -> (token id, first byte, end byte). Merges come off a min-heap of
+    /// (rank, position) over a linked list of symbols, as Hugging Face's `Word::merge_all`.
     private func encodePiece(_ bytes: [UInt8]) -> [(Int, Int, Int)] {
-        let key = bytes.map { byteToCharacter[Int($0)] }.joined()
-        if let hit = cache.withLock({ $0[key] }) { return hit }
-        var symbols: [(text: String, start: Int, end: Int)] = bytes.enumerated().map { (byteToCharacter[Int($0.element)], $0.offset, $0.offset + 1) }
-        while symbols.count > 1 {
-            var best = Int.max
-            var at = -1
-            for k in 0..<(symbols.count - 1) {
-                if let r = mergeRanks[symbols[k].text + " " + symbols[k + 1].text], r < best {
-                    best = r
-                    at = k
-                }
-            }
-            if at < 0 { break }
-            symbols[at] = (symbols[at].text + symbols[at + 1].text, symbols[at].start, symbols[at + 1].end)
-            symbols.remove(at: at + 1)
+        let cacheable = bytes.count <= 256
+        let key = cacheable ? bytes.map { byteToCharacter[Int($0)] }.joined() : ""
+        if cacheable, let hit = cache.withLock({ $0[key] }) { return hit }
+        let n = bytes.count
+        var text = bytes.map { byteToCharacter[Int($0)] }
+        var end = (0..<n).map { $0 + 1 }
+        var next = (0..<n).map { $0 + 1 < n ? $0 + 1 : -1 }
+        var prev = (0..<n).map { $0 - 1 }
+        var alive = [Bool](repeating: true, count: n)
+        var version = [Int](repeating: 0, count: n)
+        var heap = MergeHeap()
+        func push(_ left: Int) {
+            let right = next[left]
+            guard right >= 0, let rank = mergeRanks[text[left] + " " + text[right]] else { return }
+            heap.push(.init(rank: rank, left: left, leftVersion: version[left], right: right, rightVersion: version[right]))
+        }
+        for k in 0..<max(n - 1, 0) { push(k) }
+        while let m = heap.pop() {
+            guard alive[m.left], alive[m.right], next[m.left] == m.right, version[m.left] == m.leftVersion,
+                version[m.right] == m.rightVersion
+            else { continue }
+            text[m.left] += text[m.right]
+            end[m.left] = end[m.right]
+            alive[m.right] = false
+            next[m.left] = next[m.right]
+            if next[m.left] >= 0 { prev[next[m.left]] = m.left }
+            version[m.left] += 1
+            if prev[m.left] >= 0 { push(prev[m.left]) }
+            push(m.left)
+        }
+        var out: [(Int, Int, Int)] = []
+        var k = n > 0 ? 0 : -1
+        var start = 0
+        while k >= 0 {
+            out.append((vocabulary[text[k]] ?? 0, start, end[k]))
+            start = end[k]
+            k = next[k]
         }
-        let out = symbols.map { (vocabulary[$0.text] ?? 0, $0.start, $0.end) }
-        cache.withLock { c in
-            if c.count > 50_000 { c.removeAll() }
-            c[key] = out
+        if cacheable {
+            let result = out
+            cache.withLock { c in
+                if c.count > 50_000 { c.removeAll() }
+                c[key] = result
+            }
         }
         return out
     }
 
+    private struct MergeHeap {
+        struct Item {
+            let rank: Int
+            let left: Int
+            let leftVersion: Int
+            let right: Int
+            let rightVersion: Int
+            func before(_ o: Item) -> Bool { rank != o.rank ? rank < o.rank : left < o.left }
+        }
+        private var items: [Item] = []
+
+        mutating func push(_ x: Item) {
+            items.append(x)
+            var i = items.count - 1
+            while i > 0 {
+                let p = (i - 1) / 2
+                guard items[i].before(items[p]) else { break }
+                items.swapAt(i, p)
+                i = p
+            }
+        }
+
+        mutating func pop() -> Item? {
+            guard let top = items.first else { return nil }
+            let last = items.removeLast()
+            if !items.isEmpty {
+                items[0] = last
+                var i = 0
+                while true {
+                    let l = 2 * i + 1, r = l + 1
+                    var m = i
+                    if l < items.count, items[l].before(items[m]) { m = l }
+                    if r < items.count, items[r].before(items[m]) { m = r }
+                    if m == i { break }
+                    items.swapAt(i, m)
+                    i = m
+                }
+            }
+            return top
+        }
+    }
+
     /// GPT-2's reversible byte -> printable character table.
     private static func bytesToUnicode() -> [String] {
         var bs: [Int] = Array(33...126) + Array(161...172) + Array(174...255)
diff --git a/Sources/Vela3Check/main.swift b/Sources/Vela3Check/main.swift
index 9d771d4..b16a702 100644
--- a/Sources/Vela3Check/main.swift
+++ b/Sources/Vela3Check/main.swift
@@ -17,10 +17,10 @@ struct Vela3Check {
             let state: String; let id: String; let type: String; let instructions: String; let options: [[String]]
             let ids: [Int]; let names: [String]; let probabilities: [Double]
         }
-        struct Span: Decodable { let label: String; let start: Int; let end: Int }
+        struct Span: Decodable { let label: String; let start: Int; let end: Int; let probability: Double }
         struct SpanCase: Decodable {
             let kind: String; let text: String?; let context: String?; let answer: String?
-            let ids: [Int]; let spans: [Span]; let threshold: Double
+            let ids: [[Int]]; let spans: [Span]; let threshold: Double
         }
         let tokens: [Tok]
         let decisions: [Decision]
@@ -35,8 +35,16 @@ struct Vela3Check {
             print(dir.path)
             return
         }
+        if a.first == "warm", a.count >= 2 {  // load + warm only (cold-start smoke test); optional fixtures decoded first
+            let fx = a.count > 2 ? try JSONDecoder().decode(Fixtures.self, from: Data(contentsOf: URL(fileURLWithPath: a[2]))) : nil
+            let t = Date()
+            let m = try await Vela3Manager.load(from: URL(fileURLWithPath: a[1]))
+            try await m.warm()
+            print(String(format: "loaded + warmed in %.1f s", Date().timeIntervalSince(t)), fx?.decisions.count ?? 0)
+            return
+        }
         guard a.count >= 3, a[0] == "parity" else {
-            fputs("usage: Vela3Check parity <model dir> <fixtures.json> | Vela3Check download\n", stderr)
+            fputs("usage: Vela3Check parity <model dir> <fixtures.json> | warm <model dir> | download\n", stderr)
             exit(2)
         }
         let fx = try JSONDecoder().decode(Fixtures.self, from: Data(contentsOf: URL(fileURLWithPath: a[2])))
@@ -72,19 +80,23 @@ struct Vela3Check {
         }
         print(String(format: "decisions: %d questions, %d sequence mismatches, %d answers differ, max |dp| %.5f", fx.decisions.count, seqBad, flips, maxDp))
 
-        var spanSeqBad = 0, spanBad = 0, nSpans = 0
+        var spanSeqBad = 0, spanBad = 0, nSpans = 0, windows = 0, maxSpanDp = 0.0
         var spanMs: [Double] = []
         for c in fx.spans {
-            let (ids, r): ([Int], Vela3SpanResult)
+            let (ids, r): ([[Int]], Vela3SpanResult)
             if c.kind == "pii" {
-                ids = m.spanSequence(pii: c.text!)
+                ids = try m.spanSequences(pii: c.text!)
                 r = try await m.pii(c.text!)
             } else {
-                ids = m.spanSequence(context: c.context!, answer: c.answer!)
+                ids = try m.spanSequences(context: c.context!, answer: c.answer!)
                 r = try await m.unsupported(context: c.context!, answer: c.answer!)
             }
             spanMs.append(r.timing.totalMs)
-            if ids != c.ids { spanSeqBad += 1 }
+            windows += ids.count
+            if ids.count != c.ids.count || Set(ids) != Set(c.ids) {  // Python runs windows sorted by length
+                spanSeqBad += 1
+                print("sequence mismatch [\(c.kind)]: swift windows \(ids.map(\.count)), python \(c.ids.map(\.count))")
+            }
             let got = Set(r.spans.map { "\($0.label)|\($0.start)|\($0.end)" })
             let want = Set(c.spans.map { "\($0.label)|\($0.start)|\($0.end)" })
             nSpans += want.count
@@ -92,10 +104,17 @@ struct Vela3Check {
                 spanBad += 1
                 print("span mismatch [\(c.kind)]: want \(want.subtracting(got).sorted()) got extra \(got.subtracting(want).sorted())")
             }
+            for w in c.spans {
+                if let g = r.spans.first(where: { $0.label == w.label && $0.start == w.start && $0.end == w.end }) {
+                    maxSpanDp = max(maxSpanDp, abs(g.probability - w.probability))
+                }
+            }
         }
-        print("spans: \(fx.spans.count) calls (\(nSpans) spans), \(spanSeqBad) sequence mismatches, \(spanBad) span sets differ")
+        print(String(format: "spans: %d calls (%d windows, %d spans), %d sequence mismatches, %d span sets differ, max span |dp| %.5f",
+                     fx.spans.count, windows, nSpans, spanSeqBad, spanBad, maxSpanDp))
         func median(_ x: [Double]) -> Double { x.isEmpty ? 0 : x.sorted()[x.count / 2] }
         print(String(format: "median call: decision %.1f ms, span %.1f ms (GPU, end to end)", median(decisionMs), median(spanMs)))
-        if bad + seqBad + flips + spanSeqBad + spanBad > 0 { exit(1) }
+        // same encoders on both sides: probabilities should agree to rounding, so drift fails the check too
+        if bad + seqBad + flips + spanSeqBad + spanBad > 0 || maxDp > 1e-3 || maxSpanDp > 1e-3 { exit(1) }
     }
 }