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..658348b 100644
--- a/README.md
+++ b/README.md
@@ -312,6 +312,35 @@ 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 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).
+
+```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..c8c2fce 100644
--- a/Sources/FluidUse/Vela2/Vela2Manager.swift
+++ b/Sources/FluidUse/Vela2/Vela2Manager.swift
@@ -514,12 +514,29 @@ 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") }
-        self.hidden = n.count
-        self.proj = p.count
+        try self.init(weights: w)
+    }
+
+    /// 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")
+        }
+        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(w["log_tau"]![0])
-        self.tauSpan = exp(w["log_tau_span"]![0])
+        self.tau = exp(logTau)
+        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
new file mode 100644
index 0000000..8fa0496
--- /dev/null
+++ b/Sources/FluidUse/Vela3/Vela3Manager.swift
@@ -0,0 +1,512 @@
+@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
+    /// 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
+}
+
+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, 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 {
+        let q, o, e, sep: Int
+        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 role: String
+        let prefix: [Int]
+        let ePos: [Int]
+    }
+
+    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]
+    /// 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] {
+            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]], !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], !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)") }
+            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: tokenizer,
+            markers: Markers(
+                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: 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)] {
+        let 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)
+        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 (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, 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
+    }
+
+    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.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)
+
+    /// 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 {
+                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)
+        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[self.piiBuckets.count - 1].threshold
+        }
+    }
+
+    /// 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 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 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 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: 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, windows: plan.passes.count,
+            timing: Vela3Timing(encoderMs: encoderMs, totalMs: Date().timeIntervalSince(started) * 1000, buckets: used))
+    }
+
+    /// 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))
+        }
+        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
+        }
+        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)
+        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
+        }
+        // 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)
+        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..4bb69e4
--- /dev/null
+++ b/Sources/FluidUse/Vela3/Vela3Tokenizer.swift
@@ -0,0 +1,233 @@
+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 (`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.
+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, 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. Long pieces are not
+    /// cached.
+    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, 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, t["lstrip"] as? Bool ?? false, t["rstrip"] as? Bool ?? false)
+        }
+        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) }) {
+                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
+            }
+        }
+        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). 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 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]
+        }
+        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)
+        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..b16a702
--- /dev/null
+++ b/Sources/Vela3Check/main.swift
@@ -0,0 +1,120 @@
+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; 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 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
+        }
+        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> | warm <model dir> | 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, windows = 0, maxSpanDp = 0.0
+        var spanMs: [Double] = []
+        for c in fx.spans {
+            let (ids, r): ([[Int]], Vela3SpanResult)
+            if c.kind == "pii" {
+                ids = try m.spanSequences(pii: c.text!)
+                r = try await m.pii(c.text!)
+            } else {
+                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)
+            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
+            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())")
+            }
+            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(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)))
+        // 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) }
+    }
+}