@xybrid/react-native 0.10.0-rc1

package/ios/XybridSwift/xybrid_bolt.swift

@@ -0,0 +1,3198 @@
+// Auto-generated by BoltFFI. Do not edit.
+// swiftlint:disable all
+// swiftformat:disable all
+
+import Foundation
+import XybridFFI
+
+public struct FfiError: Error {
+    public let message: String
+
+    public init(message: String) {
+        self.message = message
+    }
+}
+
+/// Single metadata key/value entry. BoltFFI doesn't auto-derive
+/// `WireEncode` for `HashMap<String, String>`, so we expose metadata as
+/// `Vec<XybridMetadataEntry>`. The conversion back to `HashMap` happens
+/// at the facade boundary inside [`XybridEnvelope::into`].
+public struct XybridMetadataEntry: Hashable, Equatable, Sendable {
+    public var key: String
+    public var value: String
+
+    public init(key: String, value: String) {
+        self.key = key
+        self.value = value
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridMetadataEntry {
+        XybridMetadataEntry(key: reader.readString(), value: reader.readString())
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeString(self.key)
+        writer.writeString(self.value)
+    }
+}
+
+public struct XybridEnvelope: Hashable, Equatable, Sendable {
+    public var kind: XybridEnvelopeKind
+    public var metadata: [XybridMetadataEntry]
+
+    public init(kind: XybridEnvelopeKind, metadata: [XybridMetadataEntry]) {
+        self.kind = kind
+        self.metadata = metadata
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridEnvelope {
+        XybridEnvelope(kind: XybridEnvelopeKind.decode(from: &reader), metadata: reader.readArray { reader in XybridMetadataEntry.decode(from: &reader) })
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        self.kind.encode(to: &writer)
+        writer.writeArray(self.metadata) { writer, boltffiValue0 in boltffiValue0.encode(to: &writer) }
+    }
+}
+
+/// A tool (function) the model may ask to call.
+///
+/// `parameters_json` is the JSON Schema for the arguments, carried as a JSON
+/// string because no binding generator can describe an arbitrary JSON tree.
+public struct XybridToolDefinition: Hashable, Equatable, Sendable {
+    public var name: String
+    public var description: String
+    public var parametersJson: String
+
+    public init(name: String, description: String, parametersJson: String) {
+        self.name = name
+        self.description = description
+        self.parametersJson = parametersJson
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridToolDefinition {
+        XybridToolDefinition(name: reader.readString(), description: reader.readString(), parametersJson: reader.readString())
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeString(self.name)
+        writer.writeString(self.description)
+        writer.writeString(self.parametersJson)
+    }
+}
+
+/// One tool call the model emitted, from [`XybridResult::tool_calls`].
+public struct XybridToolCall: Hashable, Equatable, Sendable {
+    public var id: String
+    public var name: String
+    public var argumentsJson: String
+
+    public init(id: String, name: String, argumentsJson: String) {
+        self.id = id
+        self.name = name
+        self.argumentsJson = argumentsJson
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridToolCall {
+        XybridToolCall(id: reader.readString(), name: reader.readString(), argumentsJson: reader.readString())
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeString(self.id)
+        writer.writeString(self.name)
+        writer.writeString(self.argumentsJson)
+    }
+}
+
+/// The outcome of running one tool, fed back with [`tool_results_envelope`].
+public struct XybridToolResult: Hashable, Equatable, Sendable {
+    /// The [`XybridToolCall::id`] this answers.
+    public var callId: String
+    public var name: String
+    /// The tool's output as a JSON string.
+    public var contentJson: String
+
+    public init(callId: String, name: String, contentJson: String) {
+        self.callId = callId
+        self.name = name
+        self.contentJson = contentJson
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridToolResult {
+        XybridToolResult(callId: reader.readString(), name: reader.readString(), contentJson: reader.readString())
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeString(self.callId)
+        writer.writeString(self.name)
+        writer.writeString(self.contentJson)
+    }
+}
+
+public struct XybridGenerationConfig: Hashable, Equatable, Sendable {
+    public var maxTokens: UInt32?
+    public var temperature: Float?
+    public var topP: Float?
+    public var minP: Float?
+    public var topK: UInt32?
+    public var repetitionPenalty: Float?
+    public var stopSequences: [String]
+    /// Optional GBNF grammar constraining generation to structured output
+    /// (local llama backend only). Produce one from a JSON Schema with
+    /// [`json_schema_to_gbnf`], or pass raw GBNF. Appended last: `#[data]`
+    /// PODs serialize by field order across the FFI boundary.
+    public var grammar: String?
+    /// Tools the model may call this turn. Empty means no tool calling —
+    /// existing behavior, unchanged. Appended after `grammar` for the same
+    /// field-order reason.
+    ///
+    /// Tool calling is llama.cpp-only today; unsupported paths (no embedded
+    /// chat template, the mistralrs backend, the cloud fallback leg) reject
+    /// tool-bearing requests rather than quietly generating without them.
+    public var tools: [XybridToolDefinition]
+
+    public init(
+        maxTokens: UInt32?,
+        temperature: Float?,
+        topP: Float?,
+        minP: Float?,
+        topK: UInt32?,
+        repetitionPenalty: Float?,
+        stopSequences: [String],
+        grammar: String?,
+        tools: [XybridToolDefinition]
+    ) {
+        self.maxTokens = maxTokens
+        self.temperature = temperature
+        self.topP = topP
+        self.minP = minP
+        self.topK = topK
+        self.repetitionPenalty = repetitionPenalty
+        self.stopSequences = stopSequences
+        self.grammar = grammar
+        self.tools = tools
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridGenerationConfig {
+        XybridGenerationConfig(
+            maxTokens: reader.readOptional { reader in reader.readU32() },
+            temperature: reader.readOptional { reader in reader.readF32() },
+            topP: reader.readOptional { reader in reader.readF32() },
+            minP: reader.readOptional { reader in reader.readF32() },
+            topK: reader.readOptional { reader in reader.readU32() },
+            repetitionPenalty: reader.readOptional { reader in reader.readF32() },
+            stopSequences: reader.readArray { reader in reader.readString() },
+            grammar: reader.readOptional { reader in reader.readString() },
+            tools: reader.readArray { reader in XybridToolDefinition.decode(from: &reader) }
+        )
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeOptional(self.maxTokens) { writer, boltffiValue0 in writer.writeU32(boltffiValue0) }
+        writer.writeOptional(self.temperature) { writer, boltffiValue0 in writer.writeF32(boltffiValue0) }
+        writer.writeOptional(self.topP) { writer, boltffiValue0 in writer.writeF32(boltffiValue0) }
+        writer.writeOptional(self.minP) { writer, boltffiValue0 in writer.writeF32(boltffiValue0) }
+        writer.writeOptional(self.topK) { writer, boltffiValue0 in writer.writeU32(boltffiValue0) }
+        writer.writeOptional(self.repetitionPenalty) { writer, boltffiValue0 in writer.writeF32(boltffiValue0) }
+        writer.writeArray(self.stopSequences) { writer, boltffiValue0 in writer.writeString(boltffiValue0) }
+        writer.writeOptional(self.grammar) { writer, boltffiValue0 in writer.writeString(boltffiValue0) }
+        writer.writeArray(self.tools) { writer, boltffiValue0 in boltffiValue0.encode(to: &writer) }
+    }
+}
+
+public struct XybridRunOptions: Hashable, Equatable, Sendable {
+    public var generationConfig: XybridGenerationConfig?
+    public var abortOn: [XybridAbortSignal]
+    public var fallbackToCloud: Bool
+    public var maxGraceTokens: UInt32
+    public var correlationId: String?
+
+    public init(
+        generationConfig: XybridGenerationConfig?,
+        abortOn: [XybridAbortSignal],
+        fallbackToCloud: Bool,
+        maxGraceTokens: UInt32,
+        correlationId: String?
+    ) {
+        self.generationConfig = generationConfig
+        self.abortOn = abortOn
+        self.fallbackToCloud = fallbackToCloud
+        self.maxGraceTokens = maxGraceTokens
+        self.correlationId = correlationId
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridRunOptions {
+        XybridRunOptions(
+            generationConfig: reader.readOptional { reader in XybridGenerationConfig.decode(from: &reader) },
+            abortOn: reader.readArray { reader in XybridAbortSignal(rawValue: reader.readI32())! },
+            fallbackToCloud: reader.readBool(),
+            maxGraceTokens: reader.readU32(),
+            correlationId: reader.readOptional { reader in reader.readString() }
+        )
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeOptional(self.generationConfig) { writer, boltffiValue0 in boltffiValue0.encode(to: &writer) }
+        writer.writeArray(self.abortOn) { writer, boltffiValue0 in writer.writeI32(boltffiValue0.rawValue) }
+        writer.writeBool(self.fallbackToCloud)
+        writer.writeU32(self.maxGraceTokens)
+        writer.writeOptional(self.correlationId) { writer, boltffiValue0 in writer.writeString(boltffiValue0) }
+    }
+}
+
+public struct XybridStageLatency: Hashable, Equatable, Sendable {
+    public var stageId: String
+    public var latencyMs: UInt32
+
+    public init(stageId: String, latencyMs: UInt32) {
+        self.stageId = stageId
+        self.latencyMs = latencyMs
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridStageLatency {
+        XybridStageLatency(stageId: reader.readString(), latencyMs: reader.readU32())
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeString(self.stageId)
+        writer.writeU32(self.latencyMs)
+    }
+}
+
+public struct XybridInferenceMetrics: Hashable, Equatable, Sendable {
+    public var totalMs: UInt32
+    public var ttftMs: UInt32?
+    public var tokensPerSecond: Float?
+    public var prefillTps: Float?
+    public var decodeTps: Float?
+    public var tokensOut: UInt32?
+    public var stageLatenciesMs: [XybridStageLatency]
+
+    public init(
+        totalMs: UInt32,
+        ttftMs: UInt32?,
+        tokensPerSecond: Float?,
+        prefillTps: Float?,
+        decodeTps: Float?,
+        tokensOut: UInt32?,
+        stageLatenciesMs: [XybridStageLatency]
+    ) {
+        self.totalMs = totalMs
+        self.ttftMs = ttftMs
+        self.tokensPerSecond = tokensPerSecond
+        self.prefillTps = prefillTps
+        self.decodeTps = decodeTps
+        self.tokensOut = tokensOut
+        self.stageLatenciesMs = stageLatenciesMs
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridInferenceMetrics {
+        XybridInferenceMetrics(
+            totalMs: reader.readU32(),
+            ttftMs: reader.readOptional { reader in reader.readU32() },
+            tokensPerSecond: reader.readOptional { reader in reader.readF32() },
+            prefillTps: reader.readOptional { reader in reader.readF32() },
+            decodeTps: reader.readOptional { reader in reader.readF32() },
+            tokensOut: reader.readOptional { reader in reader.readU32() },
+            stageLatenciesMs: reader.readArray { reader in XybridStageLatency.decode(from: &reader) }
+        )
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeU32(self.totalMs)
+        writer.writeOptional(self.ttftMs) { writer, boltffiValue0 in writer.writeU32(boltffiValue0) }
+        writer.writeOptional(self.tokensPerSecond) { writer, boltffiValue0 in writer.writeF32(boltffiValue0) }
+        writer.writeOptional(self.prefillTps) { writer, boltffiValue0 in writer.writeF32(boltffiValue0) }
+        writer.writeOptional(self.decodeTps) { writer, boltffiValue0 in writer.writeF32(boltffiValue0) }
+        writer.writeOptional(self.tokensOut) { writer, boltffiValue0 in writer.writeU32(boltffiValue0) }
+        writer.writeArray(self.stageLatenciesMs) { writer, boltffiValue0 in boltffiValue0.encode(to: &writer) }
+    }
+}
+
+/// Inference output. Named `XybridResult` (not `XybridInferenceResult`)
+/// to match the existing uniffi-generated Kotlin/Swift name — the iOS
+/// example references `XybridResult` directly.
+public struct XybridResult: Hashable, Equatable, Sendable {
+    public var envelope: XybridEnvelope
+    public var outputType: XybridOutputType
+    public var modelId: String
+    public var latencyMs: UInt32
+    /// Where the answer actually came from. Cloud fallback keeps `model_id`
+    /// identical on both legs, so this is the only way to tell them apart.
+    public var executionTarget: XybridExecutionTarget
+    public var metrics: XybridInferenceMetrics
+    /// Tool calls the model emitted this turn. Empty unless the request
+    /// offered tools via [`XybridGenerationConfig::tools`].
+    /// `#[data]` PODs serialize by field order across the FFI boundary.
+    public var toolCalls: [XybridToolCall]
+    /// Model reasoning emitted separately from the final answer text.
+    /// Appended last because `#[data]` fields serialize in declaration order.
+    public var reasoningContent: String?
+
+    public init(
+        envelope: XybridEnvelope,
+        outputType: XybridOutputType,
+        modelId: String,
+        latencyMs: UInt32,
+        executionTarget: XybridExecutionTarget,
+        metrics: XybridInferenceMetrics,
+        toolCalls: [XybridToolCall],
+        reasoningContent: String? = nil
+    ) {
+        self.envelope = envelope
+        self.outputType = outputType
+        self.modelId = modelId
+        self.latencyMs = latencyMs
+        self.executionTarget = executionTarget
+        self.metrics = metrics
+        self.toolCalls = toolCalls
+        self.reasoningContent = reasoningContent
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridResult {
+        let envelope = XybridEnvelope.decode(from: &reader)
+        let outputType = XybridOutputType(rawValue: reader.readI32())!
+        let modelId = reader.readString()
+        let latencyMs = reader.readU32()
+        let executionTarget = XybridExecutionTarget(rawValue: reader.readI32())!
+        let metrics = XybridInferenceMetrics.decode(from: &reader)
+        let toolCalls = reader.readArray { reader in XybridToolCall.decode(from: &reader) }
+        let reasoningContent = reader.position < reader.data.count
+            ? reader.readOptional { reader in reader.readString() }
+            : envelope.metadata.first { $0.key == "reasoning_content" }?.value
+        return XybridResult(
+            envelope: envelope,
+            outputType: outputType,
+            modelId: modelId,
+            latencyMs: latencyMs,
+            executionTarget: executionTarget,
+            metrics: metrics,
+            toolCalls: toolCalls,
+            reasoningContent: reasoningContent
+        )
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        self.envelope.encode(to: &writer)
+        writer.writeI32(self.outputType.rawValue)
+        writer.writeString(self.modelId)
+        writer.writeU32(self.latencyMs)
+        writer.writeI32(self.executionTarget.rawValue)
+        self.metrics.encode(to: &writer)
+        writer.writeArray(self.toolCalls) { writer, boltffiValue0 in boltffiValue0.encode(to: &writer) }
+        writer.writeOptional(self.reasoningContent) { writer, boltffiValue0 in writer.writeString(boltffiValue0) }
+    }
+}
+
+/// Download progress, bytes and state in one consistent read.
+///
+/// `progress` is aggregated across every artifact the model needs (weights
+/// plus companions such as a vision projector), never moves backwards, and
+/// reaches 1.0 only alongside `Ready`. `totalBytes` is null when the source
+/// declares no size — a Hugging Face repo, or a registry entry without one —
+/// in which case `downloadedBytes` is still exact and `progress` is coarser.
+///
+/// Derives `Copy` because it is carried as a stream item.
+public struct XybridDownloadStatus: Hashable, Equatable, Sendable {
+    public var state: XybridDownloadState
+    /// 0.0..=1.0.
+    public var progress: Float
+    /// Bytes written so far, across every artifact.
+    public var downloadedBytes: UInt64
+    /// Declared total across every artifact, or null when unknown.
+    public var totalBytes: UInt64?
+
+    public init(
+        state: XybridDownloadState,
+        progress: Float,
+        downloadedBytes: UInt64,
+        totalBytes: UInt64?
+    ) {
+        self.state = state
+        self.progress = progress
+        self.downloadedBytes = downloadedBytes
+        self.totalBytes = totalBytes
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridDownloadStatus {
+        XybridDownloadStatus(
+            state: XybridDownloadState(rawValue: reader.readI32())!,
+            progress: reader.readF32(),
+            downloadedBytes: reader.readU64(),
+            totalBytes: reader.readOptional { reader in reader.readU64() }
+        )
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeI32(self.state.rawValue)
+        writer.writeF32(self.progress)
+        writer.writeU64(self.downloadedBytes)
+        writer.writeOptional(self.totalBytes) { writer, boltffiValue0 in writer.writeU64(boltffiValue0) }
+    }
+}
+
+/// What one stage of a pipeline run produced.
+public struct XybridStageResult: Hashable, Equatable, Sendable {
+    /// Stage identifier from the pipeline YAML (`id:`), or the model ID when
+    /// the stage declares none. Matches [`XybridPipeline::stage_names`].
+    public var stageId: String
+    /// This stage's output, which is also the next stage's input — the
+    /// transcript of an ASR stage, the reply of an LLM stage.
+    public var envelope: XybridEnvelope
+    public var outputType: XybridOutputType
+    public var latencyMs: UInt32
+    /// Where this stage ran. Stages of one pipeline can run in different
+    /// places.
+    public var executionTarget: XybridExecutionTarget
+    /// Generation figures (TTFT, tokens per second) when this stage is a
+    /// language model; `total_ms` is the stage latency.
+    public var metrics: XybridInferenceMetrics
+
+    public init(
+        stageId: String,
+        envelope: XybridEnvelope,
+        outputType: XybridOutputType,
+        latencyMs: UInt32,
+        executionTarget: XybridExecutionTarget,
+        metrics: XybridInferenceMetrics
+    ) {
+        self.stageId = stageId
+        self.envelope = envelope
+        self.outputType = outputType
+        self.latencyMs = latencyMs
+        self.executionTarget = executionTarget
+        self.metrics = metrics
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridStageResult {
+        XybridStageResult(
+            stageId: reader.readString(),
+            envelope: XybridEnvelope.decode(from: &reader),
+            outputType: XybridOutputType(rawValue: reader.readI32())!,
+            latencyMs: reader.readU32(),
+            executionTarget: XybridExecutionTarget(rawValue: reader.readI32())!,
+            metrics: XybridInferenceMetrics.decode(from: &reader)
+        )
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeString(self.stageId)
+        self.envelope.encode(to: &writer)
+        writer.writeI32(self.outputType.rawValue)
+        writer.writeU32(self.latencyMs)
+        writer.writeI32(self.executionTarget.rawValue)
+        self.metrics.encode(to: &writer)
+    }
+}
+
+/// Result of [`XybridPipeline::run`]: the final output plus every stage's own
+/// output, so a voice pipeline can show the transcript and the reply as well
+/// as play the audio.
+public struct XybridPipelineResult: Hashable, Equatable, Sendable {
+    /// The final stage's output — the same envelope as the last entry of
+    /// `stages`.
+    public var envelope: XybridEnvelope
+    public var outputType: XybridOutputType
+    /// Wall-clock time of the whole run.
+    public var latencyMs: UInt32
+    /// Every executed stage, in order.
+    public var stages: [XybridStageResult]
+
+    public init(
+        envelope: XybridEnvelope,
+        outputType: XybridOutputType,
+        latencyMs: UInt32,
+        stages: [XybridStageResult]
+    ) {
+        self.envelope = envelope
+        self.outputType = outputType
+        self.latencyMs = latencyMs
+        self.stages = stages
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridPipelineResult {
+        XybridPipelineResult(
+            envelope: XybridEnvelope.decode(from: &reader),
+            outputType: XybridOutputType(rawValue: reader.readI32())!,
+            latencyMs: reader.readU32(),
+            stages: reader.readArray { reader in XybridStageResult.decode(from: &reader) }
+        )
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        self.envelope.encode(to: &writer)
+        writer.writeI32(self.outputType.rawValue)
+        writer.writeU32(self.latencyMs)
+        writer.writeArray(self.stages) { writer, boltffiValue0 in boltffiValue0.encode(to: &writer) }
+    }
+}
+
+public struct XybridStreamToken: Hashable, Equatable, Sendable {
+    public var token: String
+    public var tokenId: Int64?
+    public var index: UInt64
+    public var cumulativeText: String
+    /// `"tool_calls"` when the turn ended on a parseable tool-call block.
+    public var finishReason: String?
+    /// Tool calls parsed from the completed turn — populated on the
+    /// **terminal** token only (the one carrying `finish_reason`).
+    ///
+    /// Tool-call blocks are suppressed from the emitted stream, so there is
+    /// nothing in the token text to parse: a streaming caller halts here,
+    /// runs the tools, then continues the turn by streaming a
+    /// [`tool_results_envelope`] through the same call. Empty on every
+    /// mid-stream token and on turns that emitted no call.
+    public var toolCalls: [XybridToolCall]
+    /// The completed turn's raw output text, tool-call block included — pass
+    /// it to [`tool_results_envelope`] as `prior_assistant_text`.
+    ///
+    /// Present only alongside a non-empty [`Self::tool_calls`]. Not the same
+    /// as `cumulative_text`, which reports the *emitted* text with the
+    /// protocol blocks suppressed — which is why this field exists at all.
+    public var rawText: String?
+
+    public init(
+        token: String,
+        tokenId: Int64?,
+        index: UInt64,
+        cumulativeText: String,
+        finishReason: String?,
+        toolCalls: [XybridToolCall],
+        rawText: String?
+    ) {
+        self.token = token
+        self.tokenId = tokenId
+        self.index = index
+        self.cumulativeText = cumulativeText
+        self.finishReason = finishReason
+        self.toolCalls = toolCalls
+        self.rawText = rawText
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridStreamToken {
+        XybridStreamToken(
+            token: reader.readString(),
+            tokenId: reader.readOptional { reader in reader.readI64() },
+            index: reader.readU64(),
+            cumulativeText: reader.readString(),
+            finishReason: reader.readOptional { reader in reader.readString() },
+            toolCalls: reader.readArray { reader in XybridToolCall.decode(from: &reader) },
+            rawText: reader.readOptional { reader in reader.readString() }
+        )
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeString(self.token)
+        writer.writeOptional(self.tokenId) { writer, boltffiValue0 in writer.writeI64(boltffiValue0) }
+        writer.writeU64(self.index)
+        writer.writeString(self.cumulativeText)
+        writer.writeOptional(self.finishReason) { writer, boltffiValue0 in writer.writeString(boltffiValue0) }
+        writer.writeArray(self.toolCalls) { writer, boltffiValue0 in boltffiValue0.encode(to: &writer) }
+        writer.writeOptional(self.rawText) { writer, boltffiValue0 in writer.writeString(boltffiValue0) }
+    }
+}
+
+/// One pull from a streaming inference session.
+///
+/// This is a flat record instead of a data-carrying enum because the pinned
+/// C# generator cannot lower that enum shape reliably. `kind` selects the one
+/// populated payload: `token` for `Token`, none for `Complete`. A `Complete`
+/// event is followed by [`XybridModel::stream_result`] to retrieve the final
+/// result. Inference failures are returned as typed [`XybridError`] values by
+/// [`XybridModel::stream_next`].
+public struct XybridStreamEvent: Hashable, Equatable, Sendable {
+    public var kind: XybridStreamEventKind
+    public var token: XybridStreamToken?
+
+    public init(kind: XybridStreamEventKind, token: XybridStreamToken?) {
+        self.kind = kind
+        self.token = token
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridStreamEvent {
+        XybridStreamEvent(kind: XybridStreamEventKind(rawValue: reader.readI32())!, token: reader.readOptional { reader in XybridStreamToken.decode(from: &reader) })
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeI32(self.kind.rawValue)
+        writer.writeOptional(self.token) { writer, boltffiValue0 in boltffiValue0.encode(to: &writer) }
+    }
+}
+
+public struct XybridVoiceInfo: Hashable, Equatable, Sendable {
+    public var id: String
+    public var name: String
+    public var gender: String?
+    public var language: String?
+    public var style: String?
+
+    public init(
+        id: String,
+        name: String,
+        gender: String?,
+        language: String?,
+        style: String?
+    ) {
+        self.id = id
+        self.name = name
+        self.gender = gender
+        self.language = language
+        self.style = style
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridVoiceInfo {
+        XybridVoiceInfo(
+            id: reader.readString(),
+            name: reader.readString(),
+            gender: reader.readOptional { reader in reader.readString() },
+            language: reader.readOptional { reader in reader.readString() },
+            style: reader.readOptional { reader in reader.readString() }
+        )
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeString(self.id)
+        writer.writeString(self.name)
+        writer.writeOptional(self.gender) { writer, boltffiValue0 in writer.writeString(boltffiValue0) }
+        writer.writeOptional(self.language) { writer, boltffiValue0 in writer.writeString(boltffiValue0) }
+        writer.writeOptional(self.style) { writer, boltffiValue0 in writer.writeString(boltffiValue0) }
+    }
+}
+
+public struct XybridCacheEntry: Hashable, Equatable, Sendable {
+    public var modelId: String
+    public var location: XybridCacheEntryLocation
+    public var path: String
+    public var sizeBytes: UInt64
+
+    public init(
+        modelId: String,
+        location: XybridCacheEntryLocation,
+        path: String,
+        sizeBytes: UInt64
+    ) {
+        self.modelId = modelId
+        self.location = location
+        self.path = path
+        self.sizeBytes = sizeBytes
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridCacheEntry {
+        XybridCacheEntry(
+            modelId: reader.readString(),
+            location: XybridCacheEntryLocation(rawValue: reader.readI32())!,
+            path: reader.readString(),
+            sizeBytes: reader.readU64()
+        )
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeString(self.modelId)
+        writer.writeI32(self.location.rawValue)
+        writer.writeString(self.path)
+        writer.writeU64(self.sizeBytes)
+    }
+}
+
+public struct XybridCacheStatus: Hashable, Equatable, Sendable {
+    public var totalSizeBytes: UInt64
+    public var entryCount: UInt32
+    public var modelCount: UInt32
+    public var extractedModelCount: UInt32
+    public var cacheRoot: String
+
+    public init(
+        totalSizeBytes: UInt64,
+        entryCount: UInt32,
+        modelCount: UInt32,
+        extractedModelCount: UInt32,
+        cacheRoot: String
+    ) {
+        self.totalSizeBytes = totalSizeBytes
+        self.entryCount = entryCount
+        self.modelCount = modelCount
+        self.extractedModelCount = extractedModelCount
+        self.cacheRoot = cacheRoot
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridCacheStatus {
+        XybridCacheStatus(
+            totalSizeBytes: reader.readU64(),
+            entryCount: reader.readU32(),
+            modelCount: reader.readU32(),
+            extractedModelCount: reader.readU32(),
+            cacheRoot: reader.readString()
+        )
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeU64(self.totalSizeBytes)
+        writer.writeU32(self.entryCount)
+        writer.writeU32(self.modelCount)
+        writer.writeU32(self.extractedModelCount)
+        writer.writeString(self.cacheRoot)
+    }
+}
+
+/// Configuration for a live ASR session.
+///
+/// The model is not named here — it comes from the loaded `XybridModel` the
+/// session is opened on. This only configures *how* the audio is chunked.
+public struct XybridStreamingConfig: Hashable, Equatable, Sendable {
+    /// Sample rate of the audio you will feed. Must be 16000; the ASR
+    /// backends are fixed there, so anything else is rejected rather than
+    /// silently resampled.
+    public var sampleRate: UInt32
+    /// Voice-activity-detection mode.
+    public var vad: XybridVadMode
+    /// VAD sensitivity, 0.0–1.0. Ignored when `vad` is `Off`.
+    public var vadThreshold: Float
+    /// Language hint (e.g. `"en"`); null uses the model default.
+    public var language: String?
+    /// Whisper encoder context in mel frames; null uses the model default.
+    public var audioCtx: UInt32?
+
+    public init(
+        sampleRate: UInt32,
+        vad: XybridVadMode,
+        vadThreshold: Float,
+        language: String?,
+        audioCtx: UInt32?
+    ) {
+        self.sampleRate = sampleRate
+        self.vad = vad
+        self.vadThreshold = vadThreshold
+        self.language = language
+        self.audioCtx = audioCtx
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridStreamingConfig {
+        XybridStreamingConfig(
+            sampleRate: reader.readU32(),
+            vad: XybridVadMode.decode(from: &reader),
+            vadThreshold: reader.readF32(),
+            language: reader.readOptional { reader in reader.readString() },
+            audioCtx: reader.readOptional { reader in reader.readU32() }
+        )
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeU32(self.sampleRate)
+        self.vad.encode(to: &writer)
+        writer.writeF32(self.vadThreshold)
+        writer.writeOptional(self.language) { writer, boltffiValue0 in writer.writeString(boltffiValue0) }
+        writer.writeOptional(self.audioCtx) { writer, boltffiValue0 in writer.writeU32(boltffiValue0) }
+    }
+}
+
+/// A partial transcript emitted while audio is streaming.
+public struct XybridPartialResult: Hashable, Equatable, Sendable {
+    /// Best-effort transcript so far. Cumulative, not a delta — render it in
+    /// place of the previous partial rather than appending.
+    public var text: String
+    /// `true` once this span is committed and will not change.
+    public var isStable: Bool
+    /// Monotonic chunk sequence number this result corresponds to.
+    public var chunkSequence: UInt64
+    /// Audio covered so far, in milliseconds.
+    public var audioDurationMs: UInt64
+
+    public init(
+        text: String,
+        isStable: Bool,
+        chunkSequence: UInt64,
+        audioDurationMs: UInt64
+    ) {
+        self.text = text
+        self.isStable = isStable
+        self.chunkSequence = chunkSequence
+        self.audioDurationMs = audioDurationMs
+    }
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridPartialResult {
+        XybridPartialResult(
+            text: reader.readString(),
+            isStable: reader.readBool(),
+            chunkSequence: reader.readU64(),
+            audioDurationMs: reader.readU64()
+        )
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        writer.writeString(self.text)
+        writer.writeBool(self.isStable)
+        writer.writeU64(self.chunkSequence)
+        writer.writeU64(self.audioDurationMs)
+    }
+}
+
+/// Errors surfaced across the FFI boundary. Variants mirror
+/// [`facade::Error`] — the facade owns the SDK→FFI translation; this enum
+/// only re-decorates it for the BoltFFI generator (proc macros must live
+/// on the type definition).
+///
+/// Named `XybridError` (not `Error`) so the emitted Swift type doesn't
+/// shadow / collide with Swift's stdlib `Error` protocol, and so the
+/// Kotlin sealed-hierarchy name matches the existing uniffi consumer
+/// expectations.
+///
+/// **Variant order is part of the wire contract.** BoltFFI encodes `#[error]`
+/// (and `#[data]`) enums by ordinal tag, so reordering or inserting a variant
+/// renumbers every variant after it and breaks already-built foreign clients.
+/// Only ever append at the tail, and keep this order in lockstep with
+/// [`facade::Error`] and its `code()` table.
+public enum XybridError: Hashable, Equatable, Sendable, Error {
+    case modelNotFound(id: String)
+    case directoryNotFound(path: String)
+    case metadataNotFound(path: String)
+    case metadataInvalid(message: String)
+    case loadError(message: String)
+    case inferenceError(message: String)
+    case abortedForCloudFallback(reason: String)
+    case streamingNotSupported
+    case notLoaded
+    case configError(message: String)
+    case networkError(message: String)
+    case offline(message: String)
+    case ioError(message: String)
+    case cacheError(message: String)
+    case pipelineError(message: String)
+    case circuitOpen(message: String)
+    case rateLimited(retryAfterSecs: UInt64)
+    case timeout(timeoutMs: UInt64)
+    case missingArtifact(message: String)
+    case unsupportedModelCapability(message: String)
+    case unsupportedBackendCapability(message: String)
+    case invalidImage(message: String)
+    /// The host called `cancel` — today, on a model download.
+    case cancelled(message: String)
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridError {
+        let tag = reader.readU32()
+        switch tag {
+        case 0:
+            return .modelNotFound(id: reader.readString())
+        case 1:
+            return .directoryNotFound(path: reader.readString())
+        case 2:
+            return .metadataNotFound(path: reader.readString())
+        case 3:
+            return .metadataInvalid(message: reader.readString())
+        case 4:
+            return .loadError(message: reader.readString())
+        case 5:
+            return .inferenceError(message: reader.readString())
+        case 6:
+            return .abortedForCloudFallback(reason: reader.readString())
+        case 7:
+            return .streamingNotSupported
+        case 8:
+            return .notLoaded
+        case 9:
+            return .configError(message: reader.readString())
+        case 10:
+            return .networkError(message: reader.readString())
+        case 11:
+            return .offline(message: reader.readString())
+        case 12:
+            return .ioError(message: reader.readString())
+        case 13:
+            return .cacheError(message: reader.readString())
+        case 14:
+            return .pipelineError(message: reader.readString())
+        case 15:
+            return .circuitOpen(message: reader.readString())
+        case 16:
+            return .rateLimited(retryAfterSecs: reader.readU64())
+        case 17:
+            return .timeout(timeoutMs: reader.readU64())
+        case 18:
+            return .missingArtifact(message: reader.readString())
+        case 19:
+            return .unsupportedModelCapability(message: reader.readString())
+        case 20:
+            return .unsupportedBackendCapability(message: reader.readString())
+        case 21:
+            return .invalidImage(message: reader.readString())
+        case 22:
+            return .cancelled(message: reader.readString())
+        default:
+            fatalError("Invalid XybridError tag: \(tag)")
+        }
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        switch self {
+        case let .modelNotFound(id):
+            writer.writeU32(0)
+            writer.writeString(id)
+        case let .directoryNotFound(path):
+            writer.writeU32(1)
+            writer.writeString(path)
+        case let .metadataNotFound(path):
+            writer.writeU32(2)
+            writer.writeString(path)
+        case let .metadataInvalid(message):
+            writer.writeU32(3)
+            writer.writeString(message)
+        case let .loadError(message):
+            writer.writeU32(4)
+            writer.writeString(message)
+        case let .inferenceError(message):
+            writer.writeU32(5)
+            writer.writeString(message)
+        case let .abortedForCloudFallback(reason):
+            writer.writeU32(6)
+            writer.writeString(reason)
+        case .streamingNotSupported:
+            writer.writeU32(7)
+        case .notLoaded:
+            writer.writeU32(8)
+        case let .configError(message):
+            writer.writeU32(9)
+            writer.writeString(message)
+        case let .networkError(message):
+            writer.writeU32(10)
+            writer.writeString(message)
+        case let .offline(message):
+            writer.writeU32(11)
+            writer.writeString(message)
+        case let .ioError(message):
+            writer.writeU32(12)
+            writer.writeString(message)
+        case let .cacheError(message):
+            writer.writeU32(13)
+            writer.writeString(message)
+        case let .pipelineError(message):
+            writer.writeU32(14)
+            writer.writeString(message)
+        case let .circuitOpen(message):
+            writer.writeU32(15)
+            writer.writeString(message)
+        case let .rateLimited(retryAfterSecs):
+            writer.writeU32(16)
+            writer.writeU64(retryAfterSecs)
+        case let .timeout(timeoutMs):
+            writer.writeU32(17)
+            writer.writeU64(timeoutMs)
+        case let .missingArtifact(message):
+            writer.writeU32(18)
+            writer.writeString(message)
+        case let .unsupportedModelCapability(message):
+            writer.writeU32(19)
+            writer.writeString(message)
+        case let .unsupportedBackendCapability(message):
+            writer.writeU32(20)
+            writer.writeString(message)
+        case let .invalidImage(message):
+            writer.writeU32(21)
+            writer.writeString(message)
+        case let .cancelled(message):
+            writer.writeU32(22)
+            writer.writeString(message)
+        }
+    }
+}
+
+public enum XybridEnvelopeKind: Hashable, Equatable, Sendable {
+    case text(text: String)
+    case audio(bytes: Data)
+    case embedding(values: [Float])
+    case image(bytes: Data, format: String)
+    case multiPart(parts: [XybridEnvelope])
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridEnvelopeKind {
+        let tag = reader.readU32()
+        switch tag {
+        case 0:
+            return .text(text: reader.readString())
+        case 1:
+            return .audio(bytes: reader.readBytes())
+        case 2:
+            return .embedding(values: reader.readArray { reader in reader.readF32() })
+        case 3:
+            return .image(bytes: reader.readBytes(), format: reader.readString())
+        case 4:
+            return .multiPart(parts: reader.readArray { reader in XybridEnvelope.decode(from: &reader) })
+        default:
+            fatalError("Invalid XybridEnvelopeKind tag: \(tag)")
+        }
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        switch self {
+        case let .text(text):
+            writer.writeU32(0)
+            writer.writeString(text)
+        case let .audio(bytes):
+            writer.writeU32(1)
+            writer.writeBytes(bytes)
+        case let .embedding(values):
+            writer.writeU32(2)
+            writer.writeArray(values) { writer, boltffiValue0 in writer.writeF32(boltffiValue0) }
+        case let .image(bytes, format):
+            writer.writeU32(3)
+            writer.writeBytes(bytes)
+            writer.writeString(format)
+        case let .multiPart(parts):
+            writer.writeU32(4)
+            writer.writeArray(parts) { writer, boltffiValue0 in boltffiValue0.encode(to: &writer) }
+        }
+    }
+}
+
+public enum XybridMessageRole: Int32, Hashable, Sendable, CaseIterable {
+    case system = 0
+    case user = 1
+    case assistant = 2
+
+    @usableFromInline init(fromC c: Int32) {
+        self = XybridMessageRole(rawValue: c)!
+    }
+
+    @usableFromInline var cValue: Int32 {
+        rawValue
+    }
+}
+
+public enum XybridAbortSignal: Int32, Hashable, Sendable, CaseIterable {
+    case memoryPressureWarn = 0
+    case memoryPressureCritical = 1
+    case thermalHot = 2
+    case thermalCritical = 3
+
+    @usableFromInline init(fromC c: Int32) {
+        self = XybridAbortSignal(rawValue: c)!
+    }
+
+    @usableFromInline var cValue: Int32 {
+        rawValue
+    }
+}
+
+public enum XybridOutputType: Int32, Hashable, Sendable, CaseIterable {
+    case text = 0
+    case audio = 1
+    case embedding = 2
+    case unknown = 3
+
+    @usableFromInline init(fromC c: Int32) {
+        self = XybridOutputType(rawValue: c)!
+    }
+
+    @usableFromInline var cValue: Int32 {
+        rawValue
+    }
+}
+
+/// Where a result was produced — observed fact, not a routing preference.
+public enum XybridExecutionTarget: Int32, Hashable, Sendable, CaseIterable {
+    case local = 0
+    case cloud = 1
+
+    @usableFromInline init(fromC c: Int32) {
+        self = XybridExecutionTarget(rawValue: c)!
+    }
+
+    @usableFromInline var cValue: Int32 {
+        rawValue
+    }
+}
+
+/// Lifecycle of a model download — a standalone [`XybridDownload`] or
+/// the background download behind a speculative load.
+public enum XybridDownloadState: Int32, Hashable, Sendable, CaseIterable {
+    case downloading = 0
+    case ready = 1
+    /// Download failed; for a speculative load the cloud keeps serving and
+    /// `isLoaded` never flips.
+    case failed = 2
+    /// The host called `cancel`.
+    case cancelled = 3
+
+    @usableFromInline init(fromC c: Int32) {
+        self = XybridDownloadState(rawValue: c)!
+    }
+
+    @usableFromInline var cValue: Int32 {
+        rawValue
+    }
+}
+
+public enum XybridStreamEventKind: Int32, Hashable, Sendable, CaseIterable {
+    case token = 0
+    case complete = 1
+
+    @usableFromInline init(fromC c: Int32) {
+        self = XybridStreamEventKind(rawValue: c)!
+    }
+
+    @usableFromInline var cValue: Int32 {
+        rawValue
+    }
+}
+
+public enum XybridCacheEntryLocation: Int32, Hashable, Sendable, CaseIterable {
+    case registry = 0
+    case extracted = 1
+    case huggingFace = 2
+    case huggingFaceHub = 3
+
+    @usableFromInline init(fromC c: Int32) {
+        self = XybridCacheEntryLocation(rawValue: c)!
+    }
+
+    @usableFromInline var cValue: Int32 {
+        rawValue
+    }
+}
+
+public enum XybridThermalState: Int32, Hashable, Sendable, CaseIterable {
+    case normal = 0
+    case warm = 1
+    case hot = 2
+    case critical = 3
+
+    @usableFromInline init(fromC c: Int32) {
+        self = XybridThermalState(rawValue: c)!
+    }
+
+    @usableFromInline var cValue: Int32 {
+        rawValue
+    }
+}
+
+/// How voice-activity detection (VAD) chunking is resolved for a session.
+///
+/// There is deliberately no "on, with the default model" variant: nothing
+/// ships a bundled Silero model, and the core handles VAD-enabled-without-a-
+/// directory by warning and silently falling back to fixed-window chunking.
+/// Enabling VAD therefore requires naming a directory.
+public enum XybridVadMode: Hashable, Equatable, Sendable {
+    /// Fixed time-window chunking; no voice-activity detection.
+    case off
+    /// VAD on, using the Silero model in this directory, which must contain a
+    /// `model.onnx`.
+    case enabled(modelDir: String)
+
+    @inlinable static func decode(from reader: inout WireReader) -> XybridVadMode {
+        let tag = reader.readU32()
+        switch tag {
+        case 0:
+            return .off
+        case 1:
+            return .enabled(modelDir: reader.readString())
+        default:
+            fatalError("Invalid XybridVadMode tag: \(tag)")
+        }
+    }
+
+    @inlinable func encode(to writer: inout WireWriter) {
+        switch self {
+        case .off:
+            writer.writeU32(0)
+        case let .enabled(modelDir):
+            writer.writeU32(1)
+            writer.writeString(modelDir)
+        }
+    }
+}
+
+public final class XybridDownload {
+    @usableFromInline let handle: UInt64
+
+    @usableFromInline init(handle: UInt64) {
+        self.handle = handle
+    }
+
+    deinit {
+        boltffi_release_class_xybrid_bolt_xybrid_download(handle)
+    }
+
+    /// Start downloading a registry model. Returns immediately.
+    public init(fromRegistry id: String) {
+        let boltffiIdBytes = boltffiEncode { boltffiIdWriter in boltffiIdWriter.writeString(id) }
+        let boltffiHandle = boltffiIdBytes.withUnsafeBufferPointer { boltffiIdBuffer in
+            return boltffi_init_class_xybrid_bolt_xybrid_download_from_registry(boltffiIdBuffer.baseAddress!, UInt(boltffiIdBuffer.count))
+        }
+        self.handle = boltffiHandle
+    }
+
+    /// Start downloading a registry model resolved for a specific platform.
+    public init(fromRegistryWithPlatform id: String, platform: String) {
+        let boltffiIdBytes = boltffiEncode { boltffiIdWriter in boltffiIdWriter.writeString(id) }
+        let boltffiHandle = boltffiIdBytes.withUnsafeBufferPointer { boltffiIdBuffer in
+            let boltffiPlatformBytes = boltffiEncode { boltffiPlatformWriter in boltffiPlatformWriter.writeString(platform) }
+            return boltffiPlatformBytes.withUnsafeBufferPointer { boltffiPlatformBuffer in
+                return boltffi_init_class_xybrid_bolt_xybrid_download_from_registry_with_platform(
+                    boltffiIdBuffer.baseAddress!,
+                    UInt(boltffiIdBuffer.count),
+                    boltffiPlatformBuffer.baseAddress!,
+                    UInt(boltffiPlatformBuffer.count)
+                )
+            }
+        }
+        self.handle = boltffiHandle
+    }
+
+    /// Current snapshot. Never blocks — safe from a UI thread or a per-frame
+    /// render loop.
+    public func status() -> XybridDownloadStatus {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_download_status(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in XybridDownloadStatus.decode(from: &boltffiReader) }
+    }
+
+    /// Whether the download reached a terminal state.
+    public func isFinished() -> Bool {
+        return boltffi_method_class_xybrid_bolt_xybrid_download_is_finished(self.handle)
+    }
+
+    /// The failure message once the download ended in `Failed` or
+    /// `Cancelled`; null otherwise. The stream carries the terminal *state*,
+    /// this carries the reason.
+    public func error() -> String? {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_download_error(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readOptional { boltffiReader in boltffiReader.readString() } }
+    }
+
+    /// Ask the download to stop. Takes effect within one chunk read, discards
+    /// the partial file, and moves the status to `Cancelled`. Idempotent, and
+    /// a no-op once the download is terminal.
+    public func cancel() {
+        boltffi_method_class_xybrid_bolt_xybrid_download_cancel(self.handle)
+    }
+}
+
+public final class XybridStreamingSession {
+    @usableFromInline let handle: UInt64
+
+    @usableFromInline init(handle: UInt64) {
+        self.handle = handle
+    }
+
+    deinit {
+        boltffi_release_class_xybrid_bolt_xybrid_streaming_session(handle)
+    }
+
+    /// Open a session on an already-loaded ASR model.
+    ///
+    /// Starts a worker thread and warms the weights, so the first spoken
+    /// words do not pay the cold-start cost. Returns an error for a model
+    /// that does not support streaming, or a sample rate other than 16000.
+    public init(forModel model: XybridModel, config: XybridStreamingConfig) throws {
+        let boltffiConfigBytes = boltffiEncode { boltffiConfigWriter in config.encode(to: &boltffiConfigWriter) }
+        let boltffiHandle = try boltffiConfigBytes.withUnsafeBufferPointer { boltffiConfigBuffer in
+            var boltffiResult: UInt64 = UInt64()
+            let boltffiError = boltffi_init_class_xybrid_bolt_xybrid_streaming_session_for_model(
+                model.handle,
+                boltffiConfigBuffer.baseAddress!,
+                UInt(boltffiConfigBuffer.count),
+                &boltffiResult
+            )
+            if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                defer { boltffi_free_buf(boltffiError) }
+                throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+            }
+            return boltffiResult
+        }
+        self.handle = boltffiHandle
+    }
+
+    /// Feed PCM f32 mono 16 kHz samples.
+    ///
+    /// Hands the buffer to the worker and returns; transcription happens
+    /// there, never on the caller's thread. Blocks only when the queue is
+    /// full, which back-pressures a producer feeding faster than the model
+    /// can keep up.
+    public func feed(samples: [Float]) throws {
+        try samples.withUnsafeBufferPointer { boltffiSamplesBuffer in
+            let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_streaming_session_feed(self.handle, boltffiSamplesBuffer.baseAddress, UInt(boltffiSamplesBuffer.count))
+            if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                defer { boltffi_free_buf(boltffiError) }
+                throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+            }
+        }
+    }
+
+    /// Finalize: drain buffered audio and return the complete transcript.
+    ///
+    /// The session is over afterwards — `feed` fails and the partial stream
+    /// closes. Blocks until the last chunk is transcribed, so call it off the
+    /// UI thread.
+    public func flush() throws -> String {
+        var boltffiResult: FfiBuf_u8 = FfiBuf_u8()
+        let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_streaming_session_flush(self.handle, &boltffiResult)
+        if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+            defer { boltffi_free_buf(boltffiError) }
+            throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+        }
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readString() }
+    }
+
+    /// Reset to transcribe fresh audio without reloading the model.
+    public func reset() throws {
+        let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_streaming_session_reset(self.handle)
+        if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+            defer { boltffi_free_buf(boltffiError) }
+            throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+        }
+    }
+
+    /// Stop the session and release the model, discarding buffered audio.
+    ///
+    /// Idempotent. Use [`Self::flush`] when you want the transcript — this is
+    /// the "user walked away" path. Named `cancel` rather than `close`
+    /// because BoltFFI already gives every handle a generated `close()` for
+    /// the host's disposal idiom.
+    public func cancel() {
+        boltffi_method_class_xybrid_bolt_xybrid_streaming_session_cancel(self.handle)
+    }
+
+    /// Whether the session is still accepting audio.
+    public func isRunning() -> Bool {
+        return boltffi_method_class_xybrid_bolt_xybrid_streaming_session_is_running(self.handle)
+    }
+}
+
+public final class XybridCancellationToken {
+    @usableFromInline let handle: UInt64
+
+    @usableFromInline init(handle: UInt64) {
+        self.handle = handle
+    }
+
+    deinit {
+        boltffi_release_class_xybrid_bolt_xybrid_cancellation_token(handle)
+    }
+
+    /// Create a fresh, un-cancelled token.
+    public init() {
+        self.handle = boltffi_init_class_xybrid_bolt_xybrid_cancellation_token_new()
+    }
+
+    /// Request cancellation. Idempotent, and safe to call from any thread.
+    public func cancel() {
+        boltffi_method_class_xybrid_bolt_xybrid_cancellation_token_cancel(self.handle)
+    }
+
+    /// Whether [`Self::cancel`] has been called on this token.
+    public func isCancelled() -> Bool {
+        return boltffi_method_class_xybrid_bolt_xybrid_cancellation_token_is_cancelled(self.handle)
+    }
+}
+
+public final class XybridModel {
+    @usableFromInline let handle: UInt64
+
+    @usableFromInline init(handle: UInt64) {
+        self.handle = handle
+    }
+
+    deinit {
+        boltffi_release_class_xybrid_bolt_xybrid_model(handle)
+    }
+
+    /// Load from the xybrid registry. Recommended path.
+    public init(fromRegistry id: String) throws {
+        let boltffiIdBytes = boltffiEncode { boltffiIdWriter in boltffiIdWriter.writeString(id) }
+        let boltffiHandle = try boltffiIdBytes.withUnsafeBufferPointer { boltffiIdBuffer in
+            var boltffiResult: UInt64 = UInt64()
+            let boltffiError = boltffi_init_class_xybrid_bolt_xybrid_model_from_registry(boltffiIdBuffer.baseAddress!, UInt(boltffiIdBuffer.count), &boltffiResult)
+            if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                defer { boltffi_free_buf(boltffiError) }
+                throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+            }
+            return boltffiResult
+        }
+        self.handle = boltffiHandle
+    }
+
+    /// Load from the registry, serving from the cloud gateway while the weights
+    /// download in the background.
+    ///
+    /// Returns almost immediately instead of blocking on the download. Requires
+    /// a resolvable API key and an uncached model; otherwise it behaves exactly
+    /// like `from_registry`. Poll `download_status` for progress and
+    /// `is_cloud_serving` to know which leg is answering. LLM/chat models only.
+    public init(fromRegistrySpeculative id: String) throws {
+        let boltffiIdBytes = boltffiEncode { boltffiIdWriter in boltffiIdWriter.writeString(id) }
+        let boltffiHandle = try boltffiIdBytes.withUnsafeBufferPointer { boltffiIdBuffer in
+            var boltffiResult: UInt64 = UInt64()
+            let boltffiError = boltffi_init_class_xybrid_bolt_xybrid_model_from_registry_speculative(boltffiIdBuffer.baseAddress!, UInt(boltffiIdBuffer.count), &boltffiResult)
+            if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                defer { boltffi_free_buf(boltffiError) }
+                throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+            }
+            return boltffiResult
+        }
+        self.handle = boltffiHandle
+    }
+
+    /// Load from a local model directory (must contain `model_metadata.json`).
+    public init(fromDirectory path: String) throws {
+        let boltffiPathBytes = boltffiEncode { boltffiPathWriter in boltffiPathWriter.writeString(path) }
+        let boltffiHandle = try boltffiPathBytes.withUnsafeBufferPointer { boltffiPathBuffer in
+            var boltffiResult: UInt64 = UInt64()
+            let boltffiError = boltffi_init_class_xybrid_bolt_xybrid_model_from_directory(boltffiPathBuffer.baseAddress!, UInt(boltffiPathBuffer.count), &boltffiResult)
+            if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                defer { boltffi_free_buf(boltffiError) }
+                throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+            }
+            return boltffiResult
+        }
+        self.handle = boltffiHandle
+    }
+
+    /// Load from a local `.xyb` bundle.
+    public init(fromBundle path: String) throws {
+        let boltffiPathBytes = boltffiEncode { boltffiPathWriter in boltffiPathWriter.writeString(path) }
+        let boltffiHandle = try boltffiPathBytes.withUnsafeBufferPointer { boltffiPathBuffer in
+            var boltffiResult: UInt64 = UInt64()
+            let boltffiError = boltffi_init_class_xybrid_bolt_xybrid_model_from_bundle(boltffiPathBuffer.baseAddress!, UInt(boltffiPathBuffer.count), &boltffiResult)
+            if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                defer { boltffi_free_buf(boltffiError) }
+                throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+            }
+            return boltffiResult
+        }
+        self.handle = boltffiHandle
+    }
+
+    /// Resolve and load from a HuggingFace repo (`org/repo` or `org/repo:variant`).
+    public init(fromHuggingface repo: String) throws {
+        let boltffiRepoBytes = boltffiEncode { boltffiRepoWriter in boltffiRepoWriter.writeString(repo) }
+        let boltffiHandle = try boltffiRepoBytes.withUnsafeBufferPointer { boltffiRepoBuffer in
+            var boltffiResult: UInt64 = UInt64()
+            let boltffiError = boltffi_init_class_xybrid_bolt_xybrid_model_from_huggingface(boltffiRepoBuffer.baseAddress!, UInt(boltffiRepoBuffer.count), &boltffiResult)
+            if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                defer { boltffi_free_buf(boltffiError) }
+                throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+            }
+            return boltffiResult
+        }
+        self.handle = boltffiHandle
+    }
+
+    /// Resolve and load a HuggingFace repository pinned to a revision.
+    public init(fromHuggingfaceWithRevision repo: String, revision: String) throws {
+        let boltffiRepoBytes = boltffiEncode { boltffiRepoWriter in boltffiRepoWriter.writeString(repo) }
+        let boltffiHandle = try boltffiRepoBytes.withUnsafeBufferPointer { boltffiRepoBuffer in
+            let boltffiRevisionBytes = boltffiEncode { boltffiRevisionWriter in boltffiRevisionWriter.writeString(revision) }
+            return try boltffiRevisionBytes.withUnsafeBufferPointer { boltffiRevisionBuffer in
+                var boltffiResult: UInt64 = UInt64()
+                let boltffiError = boltffi_init_class_xybrid_bolt_xybrid_model_from_huggingface_with_revision(
+                    boltffiRepoBuffer.baseAddress!,
+                    UInt(boltffiRepoBuffer.count),
+                    boltffiRevisionBuffer.baseAddress!,
+                    UInt(boltffiRevisionBuffer.count),
+                    &boltffiResult
+                )
+                if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                    defer { boltffi_free_buf(boltffiError) }
+                    throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+                }
+                return boltffiResult
+            }
+        }
+        self.handle = boltffiHandle
+    }
+
+    /// Load from a raw GGUF file, auto-generating `model_metadata.json` from the
+    /// GGUF header (written next to the file if absent).
+    public init(fromModelFile path: String) throws {
+        let boltffiPathBytes = boltffiEncode { boltffiPathWriter in boltffiPathWriter.writeString(path) }
+        let boltffiHandle = try boltffiPathBytes.withUnsafeBufferPointer { boltffiPathBuffer in
+            var boltffiResult: UInt64 = UInt64()
+            let boltffiError = boltffi_init_class_xybrid_bolt_xybrid_model_from_model_file(boltffiPathBuffer.baseAddress!, UInt(boltffiPathBuffer.count), &boltffiResult)
+            if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                defer { boltffi_free_buf(boltffiError) }
+                throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+            }
+            return boltffiResult
+        }
+        self.handle = boltffiHandle
+    }
+
+    public func modelId() -> String {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_model_model_id(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readString() }
+    }
+
+    public func version() -> String {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_model_version(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readString() }
+    }
+
+    public func outputType() -> XybridOutputType {
+        return XybridOutputType(fromC: boltffi_method_class_xybrid_bolt_xybrid_model_output_type(self.handle))
+    }
+
+    public func isLoaded() -> Bool {
+        return boltffi_method_class_xybrid_bolt_xybrid_model_is_loaded(self.handle)
+    }
+
+    /// Whether runs are currently answered by the cloud because the local
+    /// weights are not ready yet. `false` for ordinary local models.
+    public func isCloudServing() -> Bool {
+        return boltffi_method_class_xybrid_bolt_xybrid_model_is_cloud_serving(self.handle)
+    }
+
+    /// Download progress + state in one read — poll this to drive a progress
+    /// bar. Reports `Ready` at 1.0 for an ordinary local model, so hosts need
+    /// no special case.
+    public func downloadStatus() -> XybridDownloadStatus {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_model_download_status(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in XybridDownloadStatus.decode(from: &boltffiReader) }
+    }
+
+    /// Block until the download finishes or `timeout_ms` elapses, then report
+    /// the status. Call it off the UI thread (the same place `from_registry` is
+    /// already called). `timeout_ms = 0` makes it a non-blocking read.
+    public func awaitDownload(timeoutMs: UInt64) -> XybridDownloadStatus {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_model_await_download(self.handle, timeoutMs)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in XybridDownloadStatus.decode(from: &boltffiReader) }
+    }
+
+    public func supportsStreaming() -> Bool {
+        return boltffi_method_class_xybrid_bolt_xybrid_model_supports_streaming(self.handle)
+    }
+
+    /// Whether this model emits true token-by-token output.
+    public func supportsTokenStreaming() -> Bool {
+        return boltffi_method_class_xybrid_bolt_xybrid_model_supports_token_streaming(self.handle)
+    }
+
+    /// Return the model's resolved generation defaults.
+    public func defaultGenerationConfig() -> XybridGenerationConfig {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_model_default_generation_config(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in XybridGenerationConfig.decode(from: &boltffiReader) }
+    }
+
+    public func isLlm() -> Bool {
+        return boltffi_method_class_xybrid_bolt_xybrid_model_is_llm(self.handle)
+    }
+
+    /// Whether the model bundle declares local tool-calling support.
+    ///
+    /// Advisory tri-state: `null` means the bundle says nothing, so the host
+    /// cannot tell. Gate tool UI on it; enforcement stays at run time — a
+    /// tools-bearing request against a model whose chat template has no tool
+    /// support fails as invalid input regardless of what this reports.
+    public func supportsToolCalling() -> Bool? {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_model_supports_tool_calling(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readOptional { reader in reader.readBool() } }
+    }
+
+    public func hasVoices() -> Bool {
+        return boltffi_method_class_xybrid_bolt_xybrid_model_has_voices(self.handle)
+    }
+
+    public func voices() -> [XybridVoiceInfo] {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_model_voices(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readArray { boltffiReader in XybridVoiceInfo.decode(from: &boltffiReader) } }
+    }
+
+    public func defaultVoice() -> XybridVoiceInfo? {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_model_default_voice(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readOptional { boltffiReader in XybridVoiceInfo.decode(from: &boltffiReader) } }
+    }
+
+    public func voice(voiceId: String) -> XybridVoiceInfo? {
+        let boltffiVoiceIdBytes = boltffiEncode { boltffiVoiceIdWriter in boltffiVoiceIdWriter.writeString(voiceId) }
+        return boltffiVoiceIdBytes.withUnsafeBufferPointer { boltffiVoiceIdBuffer in
+            let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_model_voice(self.handle, boltffiVoiceIdBuffer.baseAddress!, UInt(boltffiVoiceIdBuffer.count))
+            defer { boltffi_free_buf(boltffiResult) }
+            return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readOptional { boltffiReader in XybridVoiceInfo.decode(from: &boltffiReader) } }
+        }
+    }
+
+    /// Run inference, optionally with [`XybridRunOptions`] (generation config,
+    /// abort signals, cloud-fallback). Pass `None` for the model's defaults.
+    ///
+    /// The hand-written wrappers add a one-arg `run(envelope)` convenience that
+    /// forwards `None`, so simple call sites stay ergonomic.
+    /// Pass a [`XybridCancellationToken`] to keep a stop button on the run;
+    /// `None` means the run cannot be cancelled.
+    public func run(envelope: XybridEnvelope, options: XybridRunOptions?, cancel: XybridCancellationToken) throws -> XybridResult {
+        let boltffiEnvelopeBytes = boltffiEncode { boltffiEnvelopeWriter in envelope.encode(to: &boltffiEnvelopeWriter) }
+        return try boltffiEnvelopeBytes.withUnsafeBufferPointer { boltffiEnvelopeBuffer in
+            let boltffiOptionsBytes = boltffiEncode { boltffiOptionsWriter in boltffiOptionsWriter.writeOptional(options) { boltffiOptionsWriter, boltffiValue0 in boltffiValue0.encode(to: &boltffiOptionsWriter) } }
+            return try boltffiOptionsBytes.withUnsafeBufferPointer { boltffiOptionsBuffer in
+                var boltffiResult: FfiBuf_u8 = FfiBuf_u8()
+                let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_model_run(
+                    self.handle,
+                    boltffiEnvelopeBuffer.baseAddress!,
+                    UInt(boltffiEnvelopeBuffer.count),
+                    boltffiOptionsBuffer.baseAddress!,
+                    UInt(boltffiOptionsBuffer.count),
+                    cancel.handle,
+                    &boltffiResult
+                )
+                if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                    defer { boltffi_free_buf(boltffiError) }
+                    throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+                }
+                defer { boltffi_free_buf(boltffiResult) }
+                return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in XybridResult.decode(from: &boltffiReader) }
+            }
+        }
+    }
+
+    /// Start token streaming and return a model-scoped session identifier.
+    ///
+    /// The identifier remains valid until the final result is taken, an error
+    /// is returned, or [`Self::stream_close`] is called.
+    /// Pass a [`XybridCancellationToken`] to keep a stop button on the run;
+    /// `None` means the run cannot be cancelled.
+    public func runStream(envelope: XybridEnvelope, options: XybridRunOptions?, cancel: XybridCancellationToken) throws -> UInt64 {
+        let boltffiEnvelopeBytes = boltffiEncode { boltffiEnvelopeWriter in envelope.encode(to: &boltffiEnvelopeWriter) }
+        return try boltffiEnvelopeBytes.withUnsafeBufferPointer { boltffiEnvelopeBuffer in
+            let boltffiOptionsBytes = boltffiEncode { boltffiOptionsWriter in boltffiOptionsWriter.writeOptional(options) { boltffiOptionsWriter, boltffiValue0 in boltffiValue0.encode(to: &boltffiOptionsWriter) } }
+            return try boltffiOptionsBytes.withUnsafeBufferPointer { boltffiOptionsBuffer in
+                var boltffiResult: UInt64 = UInt64()
+                let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_model_run_stream(
+                    self.handle,
+                    boltffiEnvelopeBuffer.baseAddress!,
+                    UInt(boltffiEnvelopeBuffer.count),
+                    boltffiOptionsBuffer.baseAddress!,
+                    UInt(boltffiOptionsBuffer.count),
+                    cancel.handle,
+                    &boltffiResult
+                )
+                if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                    defer { boltffi_free_buf(boltffiError) }
+                    throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+                }
+                return boltffiResult
+            }
+        }
+    }
+
+    /// Block until the next item for `stream_id` is ready.
+    public func streamNext(streamId: UInt64) throws -> XybridStreamEvent {
+        var boltffiResult: FfiBuf_u8 = FfiBuf_u8()
+        let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_model_stream_next(self.handle, streamId, &boltffiResult)
+        if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+            defer { boltffi_free_buf(boltffiError) }
+            throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+        }
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in XybridStreamEvent.decode(from: &boltffiReader) }
+    }
+
+    /// Take the final result after receiving a `Complete` event.
+    public func streamResult(streamId: UInt64) throws -> XybridResult {
+        var boltffiResult: FfiBuf_u8 = FfiBuf_u8()
+        let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_model_stream_result(self.handle, streamId, &boltffiResult)
+        if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+            defer { boltffi_free_buf(boltffiError) }
+            throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+        }
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in XybridResult.decode(from: &boltffiReader) }
+    }
+
+    /// Forget a streaming session.
+    public func streamClose(streamId: UInt64) {
+        boltffi_method_class_xybrid_bolt_xybrid_model_stream_close(self.handle, streamId)
+    }
+
+    /// Run inference seeded with a conversation `context` (multi-turn chat).
+    ///
+    /// Only the generation config from `options` is applied — abort signals and
+    /// cloud fallback are not wired on the context path (matches the facade's
+    /// `run_with_context`).
+    /// Pass a [`XybridCancellationToken`] to keep a stop button on the run;
+    /// `None` means the run cannot be cancelled.
+    ///
+    /// Routes through the facade's options path, so abort signals and cloud
+    /// fallback on `options` are honoured rather than dropped.
+    public func runWithContext(
+        envelope: XybridEnvelope,
+        context: XybridConversationContext,
+        options: XybridRunOptions?,
+        cancel: XybridCancellationToken
+    ) throws -> XybridResult {
+        let boltffiEnvelopeBytes = boltffiEncode { boltffiEnvelopeWriter in envelope.encode(to: &boltffiEnvelopeWriter) }
+        return try boltffiEnvelopeBytes.withUnsafeBufferPointer { boltffiEnvelopeBuffer in
+            let boltffiOptionsBytes = boltffiEncode { boltffiOptionsWriter in boltffiOptionsWriter.writeOptional(options) { boltffiOptionsWriter, boltffiValue0 in boltffiValue0.encode(to: &boltffiOptionsWriter) } }
+            return try boltffiOptionsBytes.withUnsafeBufferPointer { boltffiOptionsBuffer in
+                var boltffiResult: FfiBuf_u8 = FfiBuf_u8()
+                let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_model_run_with_context(
+                    self.handle,
+                    boltffiEnvelopeBuffer.baseAddress!,
+                    UInt(boltffiEnvelopeBuffer.count),
+                    context.handle,
+                    boltffiOptionsBuffer.baseAddress!,
+                    UInt(boltffiOptionsBuffer.count),
+                    cancel.handle,
+                    &boltffiResult
+                )
+                if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                    defer { boltffi_free_buf(boltffiError) }
+                    throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+                }
+                defer { boltffi_free_buf(boltffiResult) }
+                return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in XybridResult.decode(from: &boltffiReader) }
+            }
+        }
+    }
+
+    /// Start context-aware token streaming; returns a model-scoped session id.
+    /// The pull protocol is identical to [`Self::run_stream`]
+    /// (`stream_next` / `stream_result` / `stream_close`).
+    /// Pass a [`XybridCancellationToken`] to keep a stop button on the run;
+    /// `None` means the run cannot be cancelled.
+    public func runStreamWithContext(
+        envelope: XybridEnvelope,
+        context: XybridConversationContext,
+        options: XybridRunOptions?,
+        cancel: XybridCancellationToken
+    ) throws -> UInt64 {
+        let boltffiEnvelopeBytes = boltffiEncode { boltffiEnvelopeWriter in envelope.encode(to: &boltffiEnvelopeWriter) }
+        return try boltffiEnvelopeBytes.withUnsafeBufferPointer { boltffiEnvelopeBuffer in
+            let boltffiOptionsBytes = boltffiEncode { boltffiOptionsWriter in boltffiOptionsWriter.writeOptional(options) { boltffiOptionsWriter, boltffiValue0 in boltffiValue0.encode(to: &boltffiOptionsWriter) } }
+            return try boltffiOptionsBytes.withUnsafeBufferPointer { boltffiOptionsBuffer in
+                var boltffiResult: UInt64 = UInt64()
+                let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_model_run_stream_with_context(
+                    self.handle,
+                    boltffiEnvelopeBuffer.baseAddress!,
+                    UInt(boltffiEnvelopeBuffer.count),
+                    context.handle,
+                    boltffiOptionsBuffer.baseAddress!,
+                    UInt(boltffiOptionsBuffer.count),
+                    cancel.handle,
+                    &boltffiResult
+                )
+                if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                    defer { boltffi_free_buf(boltffiError) }
+                    throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+                }
+                return boltffiResult
+            }
+        }
+    }
+
+    public func warmup() throws {
+        let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_model_warmup(self.handle)
+        if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+            defer { boltffi_free_buf(boltffiError) }
+            throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+        }
+    }
+
+    public func unload() throws {
+        let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_model_unload(self.handle)
+        if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+            defer { boltffi_free_buf(boltffiError) }
+            throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+        }
+    }
+}
+
+public final class XybridPipeline {
+    @usableFromInline let handle: UInt64
+
+    @usableFromInline init(handle: UInt64) {
+        self.handle = handle
+    }
+
+    deinit {
+        boltffi_release_class_xybrid_bolt_xybrid_pipeline(handle)
+    }
+
+    /// Parse and load a pipeline from YAML content.
+    public init(fromYaml yaml: String) throws {
+        let boltffiYamlBytes = boltffiEncode { boltffiYamlWriter in boltffiYamlWriter.writeString(yaml) }
+        let boltffiHandle = try boltffiYamlBytes.withUnsafeBufferPointer { boltffiYamlBuffer in
+            var boltffiResult: UInt64 = UInt64()
+            let boltffiError = boltffi_init_class_xybrid_bolt_xybrid_pipeline_from_yaml(boltffiYamlBuffer.baseAddress!, UInt(boltffiYamlBuffer.count), &boltffiResult)
+            if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                defer { boltffi_free_buf(boltffiError) }
+                throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+            }
+            return boltffiResult
+        }
+        self.handle = boltffiHandle
+    }
+
+    /// Read, parse, and load a pipeline from a YAML file.
+    public init(fromFile path: String) throws {
+        let boltffiPathBytes = boltffiEncode { boltffiPathWriter in boltffiPathWriter.writeString(path) }
+        let boltffiHandle = try boltffiPathBytes.withUnsafeBufferPointer { boltffiPathBuffer in
+            var boltffiResult: UInt64 = UInt64()
+            let boltffiError = boltffi_init_class_xybrid_bolt_xybrid_pipeline_from_file(boltffiPathBuffer.baseAddress!, UInt(boltffiPathBuffer.count), &boltffiResult)
+            if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                defer { boltffi_free_buf(boltffiError) }
+                throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+            }
+            return boltffiResult
+        }
+        self.handle = boltffiHandle
+    }
+
+    /// Load a pipeline bundle.
+    public init(fromBundle path: String) throws {
+        let boltffiPathBytes = boltffiEncode { boltffiPathWriter in boltffiPathWriter.writeString(path) }
+        let boltffiHandle = try boltffiPathBytes.withUnsafeBufferPointer { boltffiPathBuffer in
+            var boltffiResult: UInt64 = UInt64()
+            let boltffiError = boltffi_init_class_xybrid_bolt_xybrid_pipeline_from_bundle(boltffiPathBuffer.baseAddress!, UInt(boltffiPathBuffer.count), &boltffiResult)
+            if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                defer { boltffi_free_buf(boltffiError) }
+                throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+            }
+            return boltffiResult
+        }
+        self.handle = boltffiHandle
+    }
+
+    /// Execute every stage, downloading any missing models first, and return
+    /// each stage's output alongside the final one.
+    ///
+    /// Of `options`, only `correlation_id` applies to a pipeline run. Setting
+    /// `generation_config` or `abort_on` fails with `ConfigError` rather than
+    /// being ignored; per-stage generation settings belong in the YAML.
+    public func run(envelope: XybridEnvelope, options: XybridRunOptions?) throws -> XybridPipelineResult {
+        let boltffiEnvelopeBytes = boltffiEncode { boltffiEnvelopeWriter in envelope.encode(to: &boltffiEnvelopeWriter) }
+        return try boltffiEnvelopeBytes.withUnsafeBufferPointer { boltffiEnvelopeBuffer in
+            let boltffiOptionsBytes = boltffiEncode { boltffiOptionsWriter in boltffiOptionsWriter.writeOptional(options) { boltffiOptionsWriter, boltffiValue0 in boltffiValue0.encode(to: &boltffiOptionsWriter) } }
+            return try boltffiOptionsBytes.withUnsafeBufferPointer { boltffiOptionsBuffer in
+                var boltffiResult: FfiBuf_u8 = FfiBuf_u8()
+                let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_pipeline_run(
+                    self.handle,
+                    boltffiEnvelopeBuffer.baseAddress!,
+                    UInt(boltffiEnvelopeBuffer.count),
+                    boltffiOptionsBuffer.baseAddress!,
+                    UInt(boltffiOptionsBuffer.count),
+                    &boltffiResult
+                )
+                if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                    defer { boltffi_free_buf(boltffiError) }
+                    throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+                }
+                defer { boltffi_free_buf(boltffiResult) }
+                return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in XybridPipelineResult.decode(from: &boltffiReader) }
+            }
+        }
+    }
+
+    /// Pipeline name from the YAML definition, if present.
+    public func name() -> String? {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_pipeline_name(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readOptional { boltffiReader in boltffiReader.readString() } }
+    }
+
+    /// Stage identifiers in execution order.
+    public func stageNames() -> [String] {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_pipeline_stage_names(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readArray { boltffiReader in boltffiReader.readString() } }
+    }
+
+    /// Number of stages in the pipeline.
+    public func stageCount() -> UInt32 {
+        return boltffi_method_class_xybrid_bolt_xybrid_pipeline_stage_count(self.handle)
+    }
+}
+
+public final class XybridConversationContext {
+    @usableFromInline let handle: UInt64
+
+    @usableFromInline init(handle: UInt64) {
+        self.handle = handle
+    }
+
+    deinit {
+        boltffi_release_class_xybrid_bolt_xybrid_conversation_context(handle)
+    }
+
+    /// Create an empty conversation context (fresh id).
+    public init() {
+        self.handle = boltffi_init_class_xybrid_bolt_xybrid_conversation_context_new()
+    }
+
+    /// Create a context with a caller-supplied id (for telemetry correlation
+    /// across turns).
+    public init(withId id: String) {
+        let boltffiIdBytes = boltffiEncode { boltffiIdWriter in boltffiIdWriter.writeString(id) }
+        let boltffiHandle = boltffiIdBytes.withUnsafeBufferPointer { boltffiIdBuffer in
+            return boltffi_init_class_xybrid_bolt_xybrid_conversation_context_with_id(boltffiIdBuffer.baseAddress!, UInt(boltffiIdBuffer.count))
+        }
+        self.handle = boltffiHandle
+    }
+
+    /// Append a turn — typically a user or assistant message envelope.
+    public func push(envelope: XybridEnvelope) throws {
+        let boltffiEnvelopeBytes = boltffiEncode { boltffiEnvelopeWriter in envelope.encode(to: &boltffiEnvelopeWriter) }
+        try boltffiEnvelopeBytes.withUnsafeBufferPointer { boltffiEnvelopeBuffer -> Void in
+            let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_conversation_context_push(self.handle, boltffiEnvelopeBuffer.baseAddress!, UInt(boltffiEnvelopeBuffer.count))
+            if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                defer { boltffi_free_buf(boltffiError) }
+                throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+            }
+        }
+    }
+
+    /// Set the persistent system-prompt envelope (survives [`clear`](Self::clear)).
+    public func setSystem(envelope: XybridEnvelope) throws {
+        let boltffiEnvelopeBytes = boltffiEncode { boltffiEnvelopeWriter in envelope.encode(to: &boltffiEnvelopeWriter) }
+        try boltffiEnvelopeBytes.withUnsafeBufferPointer { boltffiEnvelopeBuffer -> Void in
+            let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_conversation_context_set_system(self.handle, boltffiEnvelopeBuffer.baseAddress!, UInt(boltffiEnvelopeBuffer.count))
+            if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                defer { boltffi_free_buf(boltffiError) }
+                throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+            }
+        }
+    }
+
+    /// Drop the history; the system envelope (if any) is preserved.
+    public func clear() {
+        boltffi_method_class_xybrid_bolt_xybrid_conversation_context_clear(self.handle)
+    }
+
+    /// The context id.
+    public func id() -> String {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_conversation_context_id(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readString() }
+    }
+
+    /// Number of history turns (excludes the system envelope).
+    public func historyLen() -> UInt32 {
+        return boltffi_method_class_xybrid_bolt_xybrid_conversation_context_history_len(self.handle)
+    }
+
+    /// Return history turns, excluding the persistent system envelope.
+    public func history() -> [XybridEnvelope] {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_conversation_context_history(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readArray { boltffiReader in XybridEnvelope.decode(from: &boltffiReader) } }
+    }
+
+    /// Whether a persistent system-prompt envelope is set.
+    public func hasSystem() -> Bool {
+        return boltffi_method_class_xybrid_bolt_xybrid_conversation_context_has_system(self.handle)
+    }
+
+    /// Set the max history length before FIFO pruning.
+    public func setMaxHistoryLen(len: UInt32) {
+        boltffi_method_class_xybrid_bolt_xybrid_conversation_context_set_max_history_len(self.handle, len)
+    }
+}
+
+public final class XybridTelemetryConfig {
+    @usableFromInline let handle: UInt64
+
+    @usableFromInline init(handle: UInt64) {
+        self.handle = handle
+    }
+
+    deinit {
+        boltffi_release_class_xybrid_bolt_xybrid_telemetry_config(handle)
+    }
+
+    /// A new config bound to the default ingest endpoint and the given API key.
+    public init(apiKey: String) {
+        let boltffiApiKeyBytes = boltffiEncode { boltffiApiKeyWriter in boltffiApiKeyWriter.writeString(apiKey) }
+        let boltffiHandle = boltffiApiKeyBytes.withUnsafeBufferPointer { boltffiApiKeyBuffer in
+            return boltffi_init_class_xybrid_bolt_xybrid_telemetry_config_new(boltffiApiKeyBuffer.baseAddress!, UInt(boltffiApiKeyBuffer.count))
+        }
+        self.handle = boltffiHandle
+    }
+
+    /// Override the ingest endpoint (self-hosted collector / non-prod).
+    public func setEndpoint(endpoint: String) {
+        let boltffiEndpointBytes = boltffiEncode { boltffiEndpointWriter in boltffiEndpointWriter.writeString(endpoint) }
+        boltffiEndpointBytes.withUnsafeBufferPointer { boltffiEndpointBuffer -> Void in
+            boltffi_method_class_xybrid_bolt_xybrid_telemetry_config_set_endpoint(self.handle, boltffiEndpointBuffer.baseAddress!, UInt(boltffiEndpointBuffer.count))
+        }
+    }
+
+    /// Set the app version reported with every event.
+    public func setAppVersion(version: String) {
+        let boltffiVersionBytes = boltffiEncode { boltffiVersionWriter in boltffiVersionWriter.writeString(version) }
+        boltffiVersionBytes.withUnsafeBufferPointer { boltffiVersionBuffer -> Void in
+            boltffi_method_class_xybrid_bolt_xybrid_telemetry_config_set_app_version(self.handle, boltffiVersionBuffer.baseAddress!, UInt(boltffiVersionBuffer.count))
+        }
+    }
+
+    /// Set the human-friendly device label reported with every event.
+    public func setDeviceLabel(label: String) {
+        let boltffiLabelBytes = boltffiEncode { boltffiLabelWriter in boltffiLabelWriter.writeString(label) }
+        boltffiLabelBytes.withUnsafeBufferPointer { boltffiLabelBuffer -> Void in
+            boltffi_method_class_xybrid_bolt_xybrid_telemetry_config_set_device_label(self.handle, boltffiLabelBuffer.baseAddress!, UInt(boltffiLabelBuffer.count))
+        }
+    }
+
+    /// Attach an app-provided device attribute (stored under `device.custom`).
+    public func setDeviceAttribute(key: String, value: String) {
+        let boltffiKeyBytes = boltffiEncode { boltffiKeyWriter in boltffiKeyWriter.writeString(key) }
+        boltffiKeyBytes.withUnsafeBufferPointer { boltffiKeyBuffer -> Void in
+            let boltffiValueBytes = boltffiEncode { boltffiValueWriter in boltffiValueWriter.writeString(value) }
+            boltffiValueBytes.withUnsafeBufferPointer { boltffiValueBuffer -> Void in
+                boltffi_method_class_xybrid_bolt_xybrid_telemetry_config_set_device_attribute(
+                    self.handle,
+                    boltffiKeyBuffer.baseAddress!,
+                    UInt(boltffiKeyBuffer.count),
+                    boltffiValueBuffer.baseAddress!,
+                    UInt(boltffiValueBuffer.count)
+                )
+            }
+        }
+    }
+
+    /// Set the number of events buffered before a flush.
+    public func setBatchSize(batchSize: UInt32) {
+        boltffi_method_class_xybrid_bolt_xybrid_telemetry_config_set_batch_size(self.handle, batchSize)
+    }
+
+    /// Set the background flush interval, in seconds.
+    public func setFlushIntervalSecs(secs: UInt32) {
+        boltffi_method_class_xybrid_bolt_xybrid_telemetry_config_set_flush_interval_secs(self.handle, secs)
+    }
+
+    /// Start the process-global telemetry exporter from this config.
+    ///
+    /// Consumes the config: subsequent setters no-op and a second `init` on the
+    /// same handle errors. Modeled as a method (not a free `telemetry_init`)
+    /// because boltffi 0.25.3 drops free functions that take a handle
+    /// parameter, but lowers a handle self-method fine (same reason the
+    /// generated `run` lives on `XybridModel`).
+    ///
+    /// # Errors
+    /// Errors if this config was already consumed, or if telemetry is already
+    /// initialized without an intervening [`telemetry_shutdown`].
+    public func `init`() throws {
+        let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_telemetry_config_init(self.handle)
+        if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+            defer { boltffi_free_buf(boltffiError) }
+            throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+        }
+    }
+}
+
+public final class XybridBundle {
+    @usableFromInline let handle: UInt64
+
+    @usableFromInline init(handle: UInt64) {
+        self.handle = handle
+    }
+
+    deinit {
+        boltffi_release_class_xybrid_bolt_xybrid_bundle(handle)
+    }
+
+    /// Open and parse a `.xyb` bundle (decompress zstd, parse tar, validate the
+    /// manifest).
+    public init(`open` path: String) throws {
+        let boltffiPathBytes = boltffiEncode { boltffiPathWriter in boltffiPathWriter.writeString(path) }
+        let boltffiHandle = try boltffiPathBytes.withUnsafeBufferPointer { boltffiPathBuffer in
+            var boltffiResult: UInt64 = UInt64()
+            let boltffiError = boltffi_init_class_xybrid_bolt_xybrid_bundle_open(boltffiPathBuffer.baseAddress!, UInt(boltffiPathBuffer.count), &boltffiResult)
+            if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                defer { boltffi_free_buf(boltffiError) }
+                throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+            }
+            return boltffiResult
+        }
+        self.handle = boltffiHandle
+    }
+
+    /// The model identifier from the manifest.
+    public func modelId() -> String {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_bundle_model_id(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readString() }
+    }
+
+    /// The version string from the manifest.
+    public func version() -> String {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_bundle_version(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readString() }
+    }
+
+    /// The target platform from the manifest.
+    public func target() -> String {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_bundle_target(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readString() }
+    }
+
+    /// The SHA-256 hash from the manifest.
+    public func hash() -> String {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_bundle_hash(self.handle)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readString() }
+    }
+
+    /// Whether the bundle carries a `model_metadata.json`.
+    public func hasMetadata() -> Bool {
+        return boltffi_method_class_xybrid_bolt_xybrid_bundle_has_metadata(self.handle)
+    }
+
+    /// Number of files in the bundle (excludes `manifest.json`).
+    public func fileCount() -> UInt32 {
+        return boltffi_method_class_xybrid_bolt_xybrid_bundle_file_count(self.handle)
+    }
+
+    /// The file name at `index`, or `None` if out of bounds.
+    public func fileName(index: UInt32) -> String? {
+        let boltffiResult = boltffi_method_class_xybrid_bolt_xybrid_bundle_file_name(self.handle, index)
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readOptional { boltffiReader in boltffiReader.readString() } }
+    }
+
+    /// The full bundle manifest serialized as JSON.
+    public func manifestJson() throws -> String {
+        var boltffiResult: FfiBuf_u8 = FfiBuf_u8()
+        let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_bundle_manifest_json(self.handle, &boltffiResult)
+        if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+            defer { boltffi_free_buf(boltffiError) }
+            throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+        }
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readString() }
+    }
+
+    /// The `model_metadata.json` contents, or `None` if the bundle has none.
+    public func metadataJson() throws -> String? {
+        var boltffiResult: FfiBuf_u8 = FfiBuf_u8()
+        let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_bundle_metadata_json(self.handle, &boltffiResult)
+        if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+            defer { boltffi_free_buf(boltffiError) }
+            throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+        }
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readOptional { boltffiReader in boltffiReader.readString() } }
+    }
+
+    /// Extract every bundle file to `output_dir` (created if absent).
+    public func extract(outputDir: String) throws {
+        let boltffiOutputDirBytes = boltffiEncode { boltffiOutputDirWriter in boltffiOutputDirWriter.writeString(outputDir) }
+        try boltffiOutputDirBytes.withUnsafeBufferPointer { boltffiOutputDirBuffer -> Void in
+            let boltffiError = boltffi_method_class_xybrid_bolt_xybrid_bundle_extract(self.handle, boltffiOutputDirBuffer.baseAddress!, UInt(boltffiOutputDirBuffer.count))
+            if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                defer { boltffi_free_buf(boltffiError) }
+                throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+            }
+        }
+    }
+}
+
+/// Build the continuation envelope for the turn after the model asked for
+/// tools.
+///
+/// One `run` is one model turn, so the loop lives in your code: run a
+/// tools-bearing request, execute every [`XybridToolCall`] it returns, then
+/// run this envelope to feed the outcomes back. Pass the same tools on the
+/// continuation's [`XybridGenerationConfig`] as on the original turn.
+///
+/// A free function rather than a constructor because `XybridEnvelope` is a
+/// `#[data]` record, not a handle type — records carry no methods across the
+/// generated bindings.
+public func toolResultsEnvelope(userText: String, priorAssistantText: String, results: [XybridToolResult]) throws -> XybridEnvelope {
+    let boltffiUserTextBytes = boltffiEncode { boltffiUserTextWriter in boltffiUserTextWriter.writeString(userText) }
+    return try boltffiUserTextBytes.withUnsafeBufferPointer { boltffiUserTextBuffer in
+        let boltffiPriorAssistantTextBytes = boltffiEncode { boltffiPriorAssistantTextWriter in boltffiPriorAssistantTextWriter.writeString(priorAssistantText) }
+        return try boltffiPriorAssistantTextBytes.withUnsafeBufferPointer { boltffiPriorAssistantTextBuffer in
+            let boltffiResultsBytes = boltffiEncode { boltffiResultsWriter in boltffiResultsWriter.writeArray(results) { boltffiResultsWriter, boltffiValue0 in boltffiValue0.encode(to: &boltffiResultsWriter) } }
+            return try boltffiResultsBytes.withUnsafeBufferPointer { boltffiResultsBuffer in
+                var boltffiResult: FfiBuf_u8 = FfiBuf_u8()
+                let boltffiError = boltffi_function_xybrid_bolt_tool_results_envelope(
+                    boltffiUserTextBuffer.baseAddress!,
+                    UInt(boltffiUserTextBuffer.count),
+                    boltffiPriorAssistantTextBuffer.baseAddress!,
+                    UInt(boltffiPriorAssistantTextBuffer.count),
+                    boltffiResultsBuffer.baseAddress!,
+                    UInt(boltffiResultsBuffer.count),
+                    &boltffiResult
+                )
+                if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+                    defer { boltffi_free_buf(boltffiError) }
+                    throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+                }
+                defer { boltffi_free_buf(boltffiResult) }
+                return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in XybridEnvelope.decode(from: &boltffiReader) }
+            }
+        }
+    }
+}
+
+/// Convert a JSON Schema (as a JSON string) into a GBNF grammar for
+/// [`XybridGenerationConfig::grammar`]. Fails on invalid JSON or schema
+/// constructs outside the supported subset.
+public func jsonSchemaToGbnf(schemaJson: String) throws -> String {
+    let boltffiSchemaJsonBytes = boltffiEncode { boltffiSchemaJsonWriter in boltffiSchemaJsonWriter.writeString(schemaJson) }
+    return try boltffiSchemaJsonBytes.withUnsafeBufferPointer { boltffiSchemaJsonBuffer in
+        var boltffiResult: FfiBuf_u8 = FfiBuf_u8()
+        let boltffiError = boltffi_function_xybrid_bolt_json_schema_to_gbnf(boltffiSchemaJsonBuffer.baseAddress!, UInt(boltffiSchemaJsonBuffer.count), &boltffiResult)
+        if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+            defer { boltffi_free_buf(boltffiError) }
+            throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+        }
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readString() }
+    }
+}
+
+public func setThermalState(state: XybridThermalState) {
+    boltffi_function_xybrid_bolt_set_thermal_state(state.cValue)
+}
+
+public func clearThermalState() {
+    boltffi_function_xybrid_bolt_clear_thermal_state()
+}
+
+public func setBatteryLevel(percent: UInt8) {
+    boltffi_function_xybrid_bolt_set_battery_level(percent)
+}
+
+public func clearBatteryLevel() {
+    boltffi_function_xybrid_bolt_clear_battery_level()
+}
+
+/// One-stop SDK initialization: API key + gateway/ingest URL overrides in
+/// one call. Delegates to [`facade::configure_runtime`]; blank strings are
+/// treated as absent. This is the canonical init the Swift
+/// `Xybrid.initialize(apiKey:gatewayUrl:ingestUrl:)` and Kotlin
+/// `Xybrid.init(context, apiKey, gatewayUrl, ingestUrl)` wrappers call.
+public func configureRuntime(apiKey: String?, gatewayUrl: String?, ingestUrl: String?) {
+    let boltffiApiKeyBytes = boltffiEncode { boltffiApiKeyWriter in boltffiApiKeyWriter.writeOptional(apiKey) { boltffiApiKeyWriter, boltffiValue0 in boltffiApiKeyWriter.writeString(boltffiValue0) } }
+    boltffiApiKeyBytes.withUnsafeBufferPointer { boltffiApiKeyBuffer -> Void in
+        let boltffiGatewayUrlBytes = boltffiEncode { boltffiGatewayUrlWriter in boltffiGatewayUrlWriter.writeOptional(gatewayUrl) { boltffiGatewayUrlWriter, boltffiValue0 in boltffiGatewayUrlWriter.writeString(boltffiValue0) } }
+        boltffiGatewayUrlBytes.withUnsafeBufferPointer { boltffiGatewayUrlBuffer -> Void in
+            let boltffiIngestUrlBytes = boltffiEncode { boltffiIngestUrlWriter in boltffiIngestUrlWriter.writeOptional(ingestUrl) { boltffiIngestUrlWriter, boltffiValue0 in boltffiIngestUrlWriter.writeString(boltffiValue0) } }
+            boltffiIngestUrlBytes.withUnsafeBufferPointer { boltffiIngestUrlBuffer -> Void in
+                boltffi_function_xybrid_bolt_configure_runtime(
+                    boltffiApiKeyBuffer.baseAddress!,
+                    UInt(boltffiApiKeyBuffer.count),
+                    boltffiGatewayUrlBuffer.baseAddress!,
+                    UInt(boltffiGatewayUrlBuffer.count),
+                    boltffiIngestUrlBuffer.baseAddress!,
+                    UInt(boltffiIngestUrlBuffer.count)
+                )
+            }
+        }
+    }
+}
+
+public func initSdkCacheDir(cacheDir: String) {
+    let boltffiCacheDirBytes = boltffiEncode { boltffiCacheDirWriter in boltffiCacheDirWriter.writeString(cacheDir) }
+    boltffiCacheDirBytes.withUnsafeBufferPointer { boltffiCacheDirBuffer -> Void in
+        boltffi_function_xybrid_bolt_init_sdk_cache_dir(boltffiCacheDirBuffer.baseAddress!, UInt(boltffiCacheDirBuffer.count))
+    }
+}
+
+/// Returns aggregate storage usage across every managed model-cache location.
+public func cacheStatus() throws -> XybridCacheStatus {
+    var boltffiResult: FfiBuf_u8 = FfiBuf_u8()
+    let boltffiError = boltffi_function_xybrid_bolt_cache_status(&boltffiResult)
+    if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+        defer { boltffi_free_buf(boltffiError) }
+        throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+    }
+    defer { boltffi_free_buf(boltffiResult) }
+    return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in XybridCacheStatus.decode(from: &boltffiReader) }
+}
+
+/// Lists every physical model entry occupying managed cache storage.
+public func cacheEntries() throws -> [XybridCacheEntry] {
+    var boltffiResult: FfiBuf_u8 = FfiBuf_u8()
+    let boltffiError = boltffi_function_xybrid_bolt_cache_entries(&boltffiResult)
+    if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+        defer { boltffi_free_buf(boltffiError) }
+        throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+    }
+    defer { boltffi_free_buf(boltffiResult) }
+    return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readArray { boltffiReader in XybridCacheEntry.decode(from: &boltffiReader) } }
+}
+
+/// Returns whether a model occupies any managed cache entry.
+public func cacheIsModelCached(modelId: String) throws -> Bool {
+    let boltffiModelIdBytes = boltffiEncode { boltffiModelIdWriter in boltffiModelIdWriter.writeString(modelId) }
+    return try boltffiModelIdBytes.withUnsafeBufferPointer { boltffiModelIdBuffer in
+        var boltffiResult: Bool = Bool()
+        let boltffiError = boltffi_function_xybrid_bolt_cache_is_model_cached(boltffiModelIdBuffer.baseAddress!, UInt(boltffiModelIdBuffer.count), &boltffiResult)
+        if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+            defer { boltffi_free_buf(boltffiError) }
+            throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+        }
+        return boltffiResult
+    }
+}
+
+/// Resolves the preferred local cache path for a model, if present.
+public func cacheModelPath(modelId: String) throws -> String? {
+    let boltffiModelIdBytes = boltffiEncode { boltffiModelIdWriter in boltffiModelIdWriter.writeString(modelId) }
+    return try boltffiModelIdBytes.withUnsafeBufferPointer { boltffiModelIdBuffer in
+        var boltffiResult: FfiBuf_u8 = FfiBuf_u8()
+        let boltffiError = boltffi_function_xybrid_bolt_cache_model_path(boltffiModelIdBuffer.baseAddress!, UInt(boltffiModelIdBuffer.count), &boltffiResult)
+        if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+            defer { boltffi_free_buf(boltffiError) }
+            throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+        }
+        defer { boltffi_free_buf(boltffiResult) }
+        return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readOptional { boltffiReader in boltffiReader.readString() } }
+    }
+}
+
+/// Lists model IDs extracted, validated, and ready to run offline.
+public func cacheListExtractedModelIds() throws -> [String] {
+    var boltffiResult: FfiBuf_u8 = FfiBuf_u8()
+    let boltffiError = boltffi_function_xybrid_bolt_cache_list_extracted_model_ids(&boltffiResult)
+    if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+        defer { boltffi_free_buf(boltffiError) }
+        throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+    }
+    defer { boltffi_free_buf(boltffiResult) }
+    return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readArray { boltffiReader in boltffiReader.readString() } }
+}
+
+/// Removes every managed cache entry for one model.
+///
+/// Do not call concurrently with a load of the same model.
+public func cacheRemoveModel(modelId: String) throws -> UInt32 {
+    let boltffiModelIdBytes = boltffiEncode { boltffiModelIdWriter in boltffiModelIdWriter.writeString(modelId) }
+    return try boltffiModelIdBytes.withUnsafeBufferPointer { boltffiModelIdBuffer in
+        var boltffiResult: UInt32 = UInt32()
+        let boltffiError = boltffi_function_xybrid_bolt_cache_remove_model(boltffiModelIdBuffer.baseAddress!, UInt(boltffiModelIdBuffer.count), &boltffiResult)
+        if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+            defer { boltffi_free_buf(boltffiError) }
+            throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+        }
+        return boltffiResult
+    }
+}
+
+/// Clears all managed model-cache storage.
+///
+/// Do not call concurrently with any model load.
+public func cacheClear() throws -> UInt32 {
+    var boltffiResult: UInt32 = UInt32()
+    let boltffiError = boltffi_function_xybrid_bolt_cache_clear(&boltffiResult)
+    if boltffiError.ptr != nil || Int(boltffiError.len) != 0 {
+        defer { boltffi_free_buf(boltffiError) }
+        throw boltffiDecodeOwnedBuf(boltffiError.ptr, Int(boltffiError.len)) { boltffiErrorReader in XybridError.decode(from: &boltffiErrorReader) }
+    }
+    return boltffiResult
+}
+
+public func setBinding(binding: String) {
+    let boltffiBindingBytes = boltffiEncode { boltffiBindingWriter in boltffiBindingWriter.writeString(binding) }
+    boltffiBindingBytes.withUnsafeBufferPointer { boltffiBindingBuffer -> Void in
+        boltffi_function_xybrid_bolt_set_binding(boltffiBindingBuffer.baseAddress!, UInt(boltffiBindingBuffer.count))
+    }
+}
+
+public func setApiKey(apiKey: String) {
+    let boltffiApiKeyBytes = boltffiEncode { boltffiApiKeyWriter in boltffiApiKeyWriter.writeString(apiKey) }
+    boltffiApiKeyBytes.withUnsafeBufferPointer { boltffiApiKeyBuffer -> Void in
+        boltffi_function_xybrid_bolt_set_api_key(boltffiApiKeyBuffer.baseAddress!, UInt(boltffiApiKeyBuffer.count))
+    }
+}
+
+public func setProviderApiKey(provider: String, apiKey: String) {
+    let boltffiProviderBytes = boltffiEncode { boltffiProviderWriter in boltffiProviderWriter.writeString(provider) }
+    boltffiProviderBytes.withUnsafeBufferPointer { boltffiProviderBuffer -> Void in
+        let boltffiApiKeyBytes = boltffiEncode { boltffiApiKeyWriter in boltffiApiKeyWriter.writeString(apiKey) }
+        boltffiApiKeyBytes.withUnsafeBufferPointer { boltffiApiKeyBuffer -> Void in
+            boltffi_function_xybrid_bolt_set_provider_api_key(
+                boltffiProviderBuffer.baseAddress!,
+                UInt(boltffiProviderBuffer.count),
+                boltffiApiKeyBuffer.baseAddress!,
+                UInt(boltffiApiKeyBuffer.count)
+            )
+        }
+    }
+}
+
+/// Point the cloud gateway at a platform base URL (staging, self-hosted).
+/// Pass a bare base URL — the `/v1` suffix is applied internally.
+public func setPlatformUrl(url: String) {
+    let boltffiUrlBytes = boltffiEncode { boltffiUrlWriter in boltffiUrlWriter.writeString(url) }
+    boltffiUrlBytes.withUnsafeBufferPointer { boltffiUrlBuffer -> Void in
+        boltffi_function_xybrid_bolt_set_platform_url(boltffiUrlBuffer.baseAddress!, UInt(boltffiUrlBuffer.count))
+    }
+}
+
+/// Enable speculative cloud fallback globally: a registry model that isn't
+/// downloaded yet is served from the gateway while the weights download.
+///
+/// LLM/chat only — prefer `XybridModel.fromRegistrySpeculative` when the app
+/// also loads ASR/TTS models, which cannot be served this way.
+public func setSpeculativeCloud(enabled: Bool) {
+    boltffi_function_xybrid_bolt_set_speculative_cloud(enabled)
+}
+
+/// Whether a Xybrid gateway API key is resolvable (in-memory or env).
+public func hasApiKey() -> Bool {
+    return boltffi_function_xybrid_bolt_has_api_key()
+}
+
+/// Whether the global speculative-cloud default is on.
+public func isSpeculativeCloudEnabled() -> Bool {
+    return boltffi_function_xybrid_bolt_is_speculative_cloud_enabled()
+}
+
+/// Whether `XybridModel::from_registry_speculative(model_id)` would actually
+/// speculate: an API key resolves and the model is not already cached.
+///
+/// Lets the hand-written Swift/Kotlin loader facades answer "will this
+/// speculate?" before loading. Never touches the network.
+public func willSpeculateForModel(modelId: String) -> Bool {
+    let boltffiModelIdBytes = boltffiEncode { boltffiModelIdWriter in boltffiModelIdWriter.writeString(modelId) }
+    return boltffiModelIdBytes.withUnsafeBufferPointer { boltffiModelIdBuffer in
+        return boltffi_function_xybrid_bolt_will_speculate_for_model(boltffiModelIdBuffer.baseAddress!, UInt(boltffiModelIdBuffer.count))
+    }
+}
+
+/// The SDK version string (tracks `CARGO_PKG_VERSION`).
+public func version() -> String {
+    let boltffiResult = boltffi_function_xybrid_bolt_version()
+    defer { boltffi_free_buf(boltffiResult) }
+    return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readString() }
+}
+
+/// Release every idle loaded model's memory; returns how many were released.
+///
+/// Call this from the platform's low-memory hook (`didReceiveMemoryWarning`
+/// on iOS, `onTrimMemory` on Android). Models with a run in flight are
+/// skipped, and a released model reloads itself on next use — no reload call,
+/// no new error to handle.
+public func releaseMemory() -> UInt32 {
+    return boltffi_function_xybrid_bolt_release_memory()
+}
+
+/// Enable or disable automatic model release for subsequent loads.
+///
+/// When enabled, loading a model under device memory pressure first releases
+/// least-recently-used idle models. Off by default; [`release_memory`] works
+/// either way.
+public func setAutoRelease(enabled: Bool) {
+    boltffi_function_xybrid_bolt_set_auto_release(enabled)
+}
+
+/// Whether automatic model release is enabled process-wide.
+public func isAutoReleaseEnabled() -> Bool {
+    return boltffi_function_xybrid_bolt_is_auto_release_enabled()
+}
+
+/// The SDK's default telemetry ingest endpoint (for display alongside a config).
+public func telemetryDefaultEndpoint() -> String {
+    let boltffiResult = boltffi_function_xybrid_bolt_telemetry_default_endpoint()
+    defer { boltffi_free_buf(boltffiResult) }
+    return boltffiDecodeOwnedBuf(boltffiResult.ptr, Int(boltffiResult.len)) { boltffiReader in boltffiReader.readString() }
+}
+
+/// Flush pending telemetry events. Safe before init / after shutdown.
+public func telemetryFlush() {
+    boltffi_function_xybrid_bolt_telemetry_flush()
+}
+
+/// Shut down the telemetry exporter. Idempotent.
+public func telemetryShutdown() {
+    boltffi_function_xybrid_bolt_telemetry_shutdown()
+}
+
+
+extension XybridDownload {
+    /// Pushed progress updates, closing once the download is terminal.
+    ///
+    /// Generated as an `AsyncStream` in Swift, a `Flow` in Kotlin, an
+    /// `IAsyncEnumerable` in C# and a subscription object in Python.
+    /// Cancelling the consuming task / scope / token unsubscribes; it does
+    /// **not** cancel the download itself — call [`Self::cancel`] for that.
+    ///
+    /// The current snapshot is delivered first, so subscribing late still
+    /// yields a frame, and a download that already finished closes at once
+    /// instead of hanging.
+    public func progress() -> _Concurrency.AsyncStream<XybridDownloadStatus> {
+        _Concurrency.AsyncStream<XybridDownloadStatus>(bufferingPolicy: .unbounded) { continuation in
+            let boltffiSubscription = boltffi_stream_xybrid_bolt_xybrid_download_progress_subscribe(self.handle)
+            guard boltffiSubscription != 0 else {
+                continuation.finish()
+                return
+            }
+            let context = BoltFFIStreamContext<XybridDownloadStatus>(
+                subscription: boltffiSubscription,
+                batchSize: 16,
+                readBatch: { subscription, batchSize in
+                    return boltffiReadWireStreamBatch(
+                        subscription: subscription,
+                        batchSize: batchSize,
+                        popBatch: boltffi_stream_xybrid_bolt_xybrid_download_progress_pop_batch,
+                        freeBuf: boltffi_free_buf
+                    ) { reader in
+                        let boltffiStreamCount = Int(reader.readU32())
+                        var boltffiStreamBatch = [XybridDownloadStatus]()
+                        boltffiStreamBatch.reserveCapacity(boltffiStreamCount)
+                        for _ in 0..<boltffiStreamCount {
+                            boltffiStreamBatch.append(XybridDownloadStatus.decode(from: &reader))
+                        }
+                        return boltffiStreamBatch
+                    }
+                },
+                poll: boltffi_stream_xybrid_bolt_xybrid_download_progress_poll,
+                unsubscribe: boltffi_stream_xybrid_bolt_xybrid_download_progress_unsubscribe,
+                free: boltffi_stream_xybrid_bolt_xybrid_download_progress_free,
+                atomicCompareExchange: boltffi_atomic_u8_cas,
+                yieldItem: { item in _ = continuation.yield(item) },
+                finish: { continuation.finish() }
+            )
+            continuation.onTermination = { @Sendable _ in context.requestTermination() }
+            context.start()
+        }
+    }
+}
+
+
+extension XybridStreamingSession {
+    /// Pushed partial transcripts, closing once the session ends.
+    ///
+    /// Generated as an `AsyncStream` in Swift, a `Flow` in Kotlin, an
+    /// `IAsyncEnumerable` in C# and an iterable subscription in Python.
+    ///
+    /// A partial produced before subscribing is delivered immediately, so
+    /// audio fed before the stream is attached is never silently lost, and
+    /// subscribing to a finished session closes at once instead of hanging.
+    public func partials() -> _Concurrency.AsyncStream<XybridPartialResult> {
+        _Concurrency.AsyncStream<XybridPartialResult>(bufferingPolicy: .unbounded) { continuation in
+            let boltffiSubscription = boltffi_stream_xybrid_bolt_xybrid_streaming_session_partials_subscribe(self.handle)
+            guard boltffiSubscription != 0 else {
+                continuation.finish()
+                return
+            }
+            let context = BoltFFIStreamContext<XybridPartialResult>(
+                subscription: boltffiSubscription,
+                batchSize: 16,
+                readBatch: { subscription, batchSize in
+                    return boltffiReadWireStreamBatch(
+                        subscription: subscription,
+                        batchSize: batchSize,
+                        popBatch: boltffi_stream_xybrid_bolt_xybrid_streaming_session_partials_pop_batch,
+                        freeBuf: boltffi_free_buf
+                    ) { reader in
+                        let boltffiStreamCount = Int(reader.readU32())
+                        var boltffiStreamBatch = [XybridPartialResult]()
+                        boltffiStreamBatch.reserveCapacity(boltffiStreamCount)
+                        for _ in 0..<boltffiStreamCount {
+                            boltffiStreamBatch.append(XybridPartialResult.decode(from: &reader))
+                        }
+                        return boltffiStreamBatch
+                    }
+                },
+                poll: boltffi_stream_xybrid_bolt_xybrid_streaming_session_partials_poll,
+                unsubscribe: boltffi_stream_xybrid_bolt_xybrid_streaming_session_partials_unsubscribe,
+                free: boltffi_stream_xybrid_bolt_xybrid_streaming_session_partials_free,
+                atomicCompareExchange: boltffi_atomic_u8_cas,
+                yieldItem: { item in _ = continuation.yield(item) },
+                finish: { continuation.finish() }
+            )
+            continuation.onTermination = { @Sendable _ in context.requestTermination() }
+            context.start()
+        }
+    }
+}
+
+
+extension XybridModel {
+    /// Pushed download updates for a speculatively-loaded model — the stream
+    /// counterpart of [`Self::await_download`], and what issue #504 asks for.
+    ///
+    /// Emits the current snapshot first, then every update, then closes on
+    /// the terminal state. An ordinary local model is already `Ready`, so its
+    /// stream yields one frame and ends.
+    public func downloadProgress() -> _Concurrency.AsyncStream<XybridDownloadStatus> {
+        _Concurrency.AsyncStream<XybridDownloadStatus>(bufferingPolicy: .unbounded) { continuation in
+            let boltffiSubscription = boltffi_stream_xybrid_bolt_xybrid_model_download_progress_subscribe(self.handle)
+            guard boltffiSubscription != 0 else {
+                continuation.finish()
+                return
+            }
+            let context = BoltFFIStreamContext<XybridDownloadStatus>(
+                subscription: boltffiSubscription,
+                batchSize: 16,
+                readBatch: { subscription, batchSize in
+                    return boltffiReadWireStreamBatch(
+                        subscription: subscription,
+                        batchSize: batchSize,
+                        popBatch: boltffi_stream_xybrid_bolt_xybrid_model_download_progress_pop_batch,
+                        freeBuf: boltffi_free_buf
+                    ) { reader in
+                        let boltffiStreamCount = Int(reader.readU32())
+                        var boltffiStreamBatch = [XybridDownloadStatus]()
+                        boltffiStreamBatch.reserveCapacity(boltffiStreamCount)
+                        for _ in 0..<boltffiStreamCount {
+                            boltffiStreamBatch.append(XybridDownloadStatus.decode(from: &reader))
+                        }
+                        return boltffiStreamBatch
+                    }
+                },
+                poll: boltffi_stream_xybrid_bolt_xybrid_model_download_progress_poll,
+                unsubscribe: boltffi_stream_xybrid_bolt_xybrid_model_download_progress_unsubscribe,
+                free: boltffi_stream_xybrid_bolt_xybrid_model_download_progress_free,
+                atomicCompareExchange: boltffi_atomic_u8_cas,
+                yieldItem: { item in _ = continuation.yield(item) },
+                finish: { continuation.finish() }
+            )
+            continuation.onTermination = { @Sendable _ in context.requestTermination() }
+            context.start()
+        }
+    }
+}
+
+private enum BoltFFIStreamPollResult: Int8 {
+    case ready = 0
+    case closed = 1
+}
+
+@inline(__always)
+private func boltffiReadDirectStreamBatch<Element, Item>(
+    subscription: UInt64,
+    batchSize: UInt,
+    popBatch: (UInt64, UnsafeMutablePointer<Element>?, UInt) -> UInt,
+    mapItems: (UnsafeBufferPointer<Element>) -> [Item]
+) -> [Item] {
+    if batchSize == 0 {
+        return []
+    }
+    let items = UnsafeMutablePointer<Element>.allocate(capacity: Int(batchSize))
+    defer { items.deallocate() }
+    let count = popBatch(subscription, items, batchSize)
+    if count == 0 {
+        return []
+    }
+    return mapItems(UnsafeBufferPointer(start: items, count: Int(count)))
+}
+
+private class BoltFFIStreamPollContext: @unchecked Sendable {
+    func handlePoll(_ result: Int8) {
+        preconditionFailure("invalid BoltFFI stream poll context")
+    }
+}
+
+private let boltffiStreamPollCallback: @convention(c) (UInt64, Int8) -> Void = { data, result in
+    Unmanaged<BoltFFIStreamPollContext>.fromOpaque(UnsafeRawPointer(bitPattern: UInt(data))!).takeRetainedValue().handlePoll(result)
+}
+
+private final class BoltFFIStreamContext<Item>: BoltFFIStreamPollContext, @unchecked Sendable {
+    private let subscription: UInt64
+    private let batchSize: UInt
+    private let readBatch: (UInt64, UInt) -> [Item]
+    private let poll: (UInt64, UInt64, StreamContinuationCallback?) -> Void
+    private let unsubscribe: (UInt64) -> Void
+    private let free: (UInt64) -> Void
+    private let atomicCompareExchange: (UnsafeMutablePointer<UInt8>?, UInt8, UInt8) -> Bool
+    private let yieldItem: (Item) -> Void
+    private let finish: () -> Void
+    private var lifecycle = UInt8(0)
+    private var processing = UInt8(0)
+
+    init(
+        subscription: UInt64,
+        batchSize: UInt,
+        readBatch: @escaping (UInt64, UInt) -> [Item],
+        poll: @escaping (UInt64, UInt64, StreamContinuationCallback?) -> Void,
+        unsubscribe: @escaping (UInt64) -> Void,
+        free: @escaping (UInt64) -> Void,
+        atomicCompareExchange: @escaping (UnsafeMutablePointer<UInt8>?, UInt8, UInt8) -> Bool,
+        yieldItem: @escaping (Item) -> Void,
+        finish: @escaping () -> Void
+    ) {
+        self.subscription = subscription
+        self.batchSize = batchSize
+        self.readBatch = readBatch
+        self.poll = poll
+        self.unsubscribe = unsubscribe
+        self.free = free
+        self.atomicCompareExchange = atomicCompareExchange
+        self.yieldItem = yieldItem
+        self.finish = finish
+    }
+
+    func start() {
+        registerPoll()
+    }
+
+    func requestTermination() {
+        let started = withUnsafeMutablePointer(to: &lifecycle) {
+            atomicCompareExchange($0, 0, 1)
+        }
+        if started {
+            unsubscribe(subscription)
+            _ = withUnsafeMutablePointer(to: &lifecycle) {
+                atomicCompareExchange($0, 1, 2)
+            }
+        }
+        finalizeIfIdle()
+    }
+
+    private func registerPoll() {
+        guard withUnsafeMutablePointer(to: &lifecycle, { atomicCompareExchange($0, 0, 0) }) else {
+            finalizeIfIdle()
+            return
+        }
+        let data = UInt64(UInt(bitPattern: Unmanaged.passRetained(self).toOpaque()))
+        poll(subscription, data, boltffiStreamPollCallback)
+    }
+
+    override func handlePoll(_ result: Int8) {
+        guard withUnsafeMutablePointer(to: &processing, { atomicCompareExchange($0, 0, 1) }) else {
+            finalizeIfIdle()
+            return
+        }
+        let reschedule = processPoll(result)
+        _ = withUnsafeMutablePointer(to: &processing) { atomicCompareExchange($0, 1, 0) }
+        finalizeIfIdle()
+        if reschedule {
+            schedulePoll()
+        }
+    }
+
+    private func processPoll(_ result: Int8) -> Bool {
+        guard withUnsafeMutablePointer(to: &lifecycle, { atomicCompareExchange($0, 0, 0) }) else {
+            return false
+        }
+        drain()
+        if result == BoltFFIStreamPollResult.closed.rawValue {
+            requestTermination()
+            return false
+        }
+        return withUnsafeMutablePointer(to: &lifecycle) { atomicCompareExchange($0, 0, 0) }
+    }
+
+    private func drain() {
+        while true {
+            let items = readBatch(subscription, batchSize)
+            if items.isEmpty {
+                return
+            }
+            for item in items {
+                yieldItem(item)
+            }
+        }
+    }
+
+    private func schedulePoll() {
+        _Concurrency.Task { [self] in
+            await _Concurrency.Task.yield()
+            registerPoll()
+        }
+    }
+
+    private func finalizeIfIdle() {
+        guard withUnsafeMutablePointer(to: &processing, { atomicCompareExchange($0, 0, 0) }) else {
+            return
+        }
+        guard withUnsafeMutablePointer(to: &lifecycle, { atomicCompareExchange($0, 2, 3) }) else {
+            return
+        }
+        free(subscription)
+        finish()
+    }
+}
+
+@usableFromInline struct WireReader {
+    @usableFromInline let data: Data
+    @usableFromInline var position: Int
+
+    @inlinable init(data: Data, position: Int = 0) {
+        self.data = data
+        self.position = position
+    }
+
+    @inlinable init(ptr: UnsafePointer<UInt8>, len: Int) {
+        self.data = Data(bytes: ptr, count: len)
+        self.position = 0
+    }
+
+    @inlinable mutating func readU8() -> UInt8 {
+        let value = data[position]
+        position += 1
+        return value
+    }
+
+    @inlinable mutating func readI8() -> Int8 {
+        Int8(bitPattern: readU8())
+    }
+
+    @inlinable mutating func readU16() -> UInt16 {
+        let value = data.withUnsafeBytes { buffer in
+            buffer.loadUnaligned(fromByteOffset: position, as: UInt16.self)
+        }
+        position += 2
+        return UInt16(littleEndian: value)
+    }
+
+    @inlinable mutating func readI16() -> Int16 {
+        Int16(bitPattern: readU16())
+    }
+
+    @inlinable mutating func readU32() -> UInt32 {
+        let value = data.withUnsafeBytes { buffer in
+            buffer.loadUnaligned(fromByteOffset: position, as: UInt32.self)
+        }
+        position += 4
+        return UInt32(littleEndian: value)
+    }
+
+    @inlinable mutating func readI32() -> Int32 {
+        Int32(bitPattern: readU32())
+    }
+
+    @inlinable mutating func readU64() -> UInt64 {
+        let value = data.withUnsafeBytes { buffer in
+            buffer.loadUnaligned(fromByteOffset: position, as: UInt64.self)
+        }
+        position += 8
+        return UInt64(littleEndian: value)
+    }
+
+    @inlinable mutating func readI64() -> Int64 {
+        Int64(bitPattern: readU64())
+    }
+
+    @inlinable mutating func readF32() -> Float {
+        Float(bitPattern: readU32())
+    }
+
+    @inlinable mutating func readF64() -> Double {
+        Double(bitPattern: readU64())
+    }
+
+    @inlinable mutating func readBool() -> Bool {
+        readU8() != 0
+    }
+
+    @inlinable mutating func readString() -> String {
+        let length = Int(readU32())
+        guard length > 0 else { return "" }
+        let start = position
+        position += length
+        return data.withUnsafeBytes { bytes in
+            let pointer = bytes.baseAddress!.advanced(by: start).assumingMemoryBound(to: UInt8.self)
+            let buffer = UnsafeBufferPointer(start: pointer, count: length)
+            return String(decoding: buffer, as: UTF8.self)
+        }
+    }
+
+    @inlinable mutating func readBytes() -> Data {
+        let length = Int(readU32())
+        guard length > 0 else { return Data() }
+        let start = position
+        position += length
+        return Data(data[start..<(start + length)])
+    }
+
+    @inlinable mutating func readDuration() -> TimeInterval {
+        let seconds = readU64()
+        let nanoseconds = readU32()
+        return Double(seconds) + (Double(nanoseconds) / 1.0e9)
+    }
+
+    @inlinable mutating func readTimestamp() -> Date {
+        let seconds = readI64()
+        let nanoseconds = readU32()
+        let delta = Double(seconds) + (Double(nanoseconds) / 1.0e9)
+        return Date(timeIntervalSince1970: delta)
+    }
+
+    @inlinable mutating func readUuid() -> UUID {
+        let hi = readU64()
+        let lo = readU64()
+        var uuid: uuid_t = (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
+        var hiBe = hi.bigEndian
+        var loBe = lo.bigEndian
+        withUnsafeMutableBytes(of: &uuid) { uuidBytes in
+            Swift.withUnsafeBytes(of: &hiBe) { uuidBytes[0..<8].copyBytes(from: $0) }
+            Swift.withUnsafeBytes(of: &loBe) { uuidBytes[8..<16].copyBytes(from: $0) }
+        }
+        return UUID(uuid: uuid)
+    }
+
+    @inlinable mutating func readUrl() -> URL {
+        guard let url = URL(string: readString()) else { fatalError("Invalid URL") }
+        return url
+    }
+
+    @inlinable mutating func readOptional<T>(_ body: (inout WireReader) -> T) -> T? {
+        switch readU8() {
+        case 0:
+            return nil
+        case 1:
+            return body(&self)
+        default:
+            fatalError("Invalid optional wire tag")
+        }
+    }
+
+    @inlinable mutating func readSequence<T>(_ body: (inout WireReader) -> T) -> [T] {
+        let count = Int(readU32())
+        guard count > 0 else { return [] }
+        var result = [T]()
+        result.reserveCapacity(count)
+        for _ in 0..<count {
+            result.append(body(&self))
+        }
+        return result
+    }
+
+    @inlinable mutating func readArray<T>(_ body: (inout WireReader) -> T) -> [T] {
+        readSequence(body)
+    }
+
+    @inlinable mutating func readResult<Success, Failure: Swift.Error>(
+        _ success: (inout WireReader) -> Success,
+        _ failure: (inout WireReader) -> Failure
+    ) -> Swift.Result<Success, Failure> {
+        switch readU8() {
+        case 0:
+            return .success(success(&self))
+        case 1:
+            return .failure(failure(&self))
+        default:
+            fatalError("Invalid result wire tag")
+        }
+    }
+
+    @inlinable mutating func readMap<K: Hashable, V>(
+        _ key: (inout WireReader) -> K,
+        _ value: (inout WireReader) -> V
+    ) -> [K: V] {
+        let count = Int(readU32())
+        var result = [K: V]()
+        result.reserveCapacity(count)
+        for _ in 0..<count {
+            let decodedKey = key(&self)
+            let decodedValue = value(&self)
+            if result.updateValue(decodedValue, forKey: decodedKey) != nil {
+                fatalError("Duplicate map key")
+            }
+        }
+        return result
+    }
+}
+
+@usableFromInline struct WireWriter {
+    @usableFromInline var data: Data
+
+    @inlinable init(capacity: Int = 64) {
+        self.data = Data(capacity: capacity)
+    }
+
+    @inlinable mutating func writeU8(_ value: UInt8) {
+        data.append(value)
+    }
+
+    @inlinable mutating func writeI8(_ value: Int8) {
+        writeU8(UInt8(bitPattern: value))
+    }
+
+    @inlinable mutating func writeU16(_ value: UInt16) {
+        var value = value.littleEndian
+        Swift.withUnsafeBytes(of: &value) { bytes in
+            data.append(contentsOf: bytes)
+        }
+    }
+
+    @inlinable mutating func writeI16(_ value: Int16) {
+        writeU16(UInt16(bitPattern: value))
+    }
+
+    @inlinable mutating func writeU32(_ value: UInt32) {
+        var value = value.littleEndian
+        Swift.withUnsafeBytes(of: &value) { bytes in
+            data.append(contentsOf: bytes)
+        }
+    }
+
+    @inlinable mutating func writeI32(_ value: Int32) {
+        writeU32(UInt32(bitPattern: value))
+    }
+
+    @inlinable mutating func writeU64(_ value: UInt64) {
+        var value = value.littleEndian
+        Swift.withUnsafeBytes(of: &value) { bytes in
+            data.append(contentsOf: bytes)
+        }
+    }
+
+    @inlinable mutating func writeI64(_ value: Int64) {
+        writeU64(UInt64(bitPattern: value))
+    }
+
+    @inlinable mutating func writeF32(_ value: Float) {
+        writeU32(value.bitPattern)
+    }
+
+    @inlinable mutating func writeF64(_ value: Double) {
+        writeU64(value.bitPattern)
+    }
+
+    @inlinable mutating func writeBool(_ value: Bool) {
+        writeU8(value ? 1 : 0)
+    }
+
+    @inlinable mutating func writeString(_ value: String) {
+        var value = value
+        value.withUTF8 { utf8 in
+            writeU32(UInt32(utf8.count))
+            data.append(contentsOf: utf8)
+        }
+    }
+
+    @inlinable mutating func writeBytes(_ value: Data) {
+        writeU32(UInt32(value.count))
+        data.append(contentsOf: value)
+    }
+
+    @inlinable mutating func writeDuration(_ value: TimeInterval) {
+        if value.rounded(.down) > Double(Int64.max) { fatalError("Duration overflow") }
+        if value < 0 { fatalError("Invalid duration") }
+        let seconds = UInt64(value)
+        let nanoseconds = UInt32((value - Double(seconds)) * 1.0e9)
+        writeU64(seconds)
+        writeU32(nanoseconds)
+    }
+
+    @inlinable mutating func writeTimestamp(_ value: Date) {
+        let delta = value.timeIntervalSince1970
+        let secondsDouble = delta.rounded(.down)
+        if secondsDouble < Double(Int64.min) || secondsDouble > Double(Int64.max) { fatalError("Timestamp overflow") }
+        let seconds = Int64(secondsDouble)
+        let nanoseconds = UInt32((delta - secondsDouble) * 1.0e9)
+        writeI64(seconds)
+        writeU32(nanoseconds)
+    }
+
+    @inlinable mutating func writeUuid(_ value: UUID) {
+        var uuid = value.uuid
+        let (hi, lo) = Swift.withUnsafeBytes(of: &uuid) { raw -> (UInt64, UInt64) in
+            let hiBe = raw.loadUnaligned(fromByteOffset: 0, as: UInt64.self)
+            let loBe = raw.loadUnaligned(fromByteOffset: 8, as: UInt64.self)
+            return (UInt64(bigEndian: hiBe), UInt64(bigEndian: loBe))
+        }
+        writeU64(hi)
+        writeU64(lo)
+    }
+
+    @inlinable mutating func writeUrl(_ value: URL) {
+        writeString(value.absoluteString)
+    }
+
+    @inlinable mutating func writeOptional<T>(_ value: T?, _ body: (inout WireWriter, T) -> Void) {
+        switch value {
+        case .some(let value):
+            writeU8(1)
+            body(&self, value)
+        case .none:
+            writeU8(0)
+        }
+    }
+
+    @inlinable mutating func writeSequence<T>(_ value: [T], _ body: (inout WireWriter, T) -> Void) {
+        writeU32(UInt32(value.count))
+        for item in value {
+            body(&self, item)
+        }
+    }
+
+    @inlinable mutating func writeArray<T>(_ value: [T], _ body: (inout WireWriter, T) -> Void) {
+        writeSequence(value, body)
+    }
+
+    @inlinable mutating func writeResult<Success, Failure: Swift.Error>(
+        _ value: Swift.Result<Success, Failure>,
+        _ success: (inout WireWriter, Success) -> Void,
+        _ failure: (inout WireWriter, Failure) -> Void
+    ) {
+        switch value {
+        case .success(let value):
+            writeU8(0)
+            success(&self, value)
+        case .failure(let value):
+            writeU8(1)
+            failure(&self, value)
+        }
+    }
+
+    @inlinable mutating func writeMap<K: Hashable, V>(
+        _ value: [K: V],
+        _ key: (inout WireWriter, K) -> Void,
+        _ writeValue: (inout WireWriter, V) -> Void
+    ) {
+        writeU32(UInt32(value.count))
+        for entry in value {
+            key(&self, entry.key)
+            writeValue(&self, entry.value)
+        }
+    }
+
+    @inlinable func finalize() -> Data {
+        data
+    }
+}
+
+@inlinable func boltffiDecodeOwnedBuf<T>(
+    _ pointer: UnsafePointer<UInt8>?,
+    _ length: Int,
+    _ decode: (inout WireReader) -> T
+) -> T {
+    var reader = WireReader(ptr: pointer!, len: length)
+    return decode(&reader)
+}
+
+@inlinable func boltffiEncode(_ body: (inout WireWriter) -> Void) -> [UInt8] {
+    var writer = WireWriter()
+    body(&writer)
+    return [UInt8](writer.finalize())
+}
+
+/// Reserved marker for an error that does not match a callback's declared error type.
+private let boltffiUnexpectedCallbackErrorMarker = Array("BOLTFFI_CALLBACK".utf8)
+
+/// Version of the unexpected callback error payload written by this generated binding.
+private let boltffiUnexpectedCallbackErrorVersion: UInt8 = 1
+
+/// Encodes an unexpected host-language callback error for conversion by the Rust error owner.
+///
+/// Declared callback errors keep their normal wire representation. The marker lets Rust detect this
+/// fallback before decoding the payload as the declared error type.
+func boltffiEncodeUnexpectedCallbackError(_ error: Error) -> [UInt8] {
+    var writer = WireWriter()
+    writer.data.append(contentsOf: boltffiUnexpectedCallbackErrorMarker)
+    writer.writeU8(boltffiUnexpectedCallbackErrorVersion)
+    writer.writeString(String(describing: error))
+    return [UInt8](writer.finalize())
+}
+
+@inline(__always)
+private func boltffiReadWireStreamBatch<Item>(
+    subscription: UInt64,
+    batchSize: UInt,
+    popBatch: (UInt64, UInt) -> FfiBuf_u8,
+    freeBuf: (FfiBuf_u8) -> Void,
+    decodeItems: (inout WireReader) -> [Item]
+) -> [Item] {
+    let buffer = popBatch(subscription, batchSize)
+    defer { freeBuf(buffer) }
+    guard buffer.len > 0, let pointer = buffer.ptr else {
+        return []
+    }
+    var reader = WireReader(ptr: pointer, len: Int(buffer.len))
+    return decodeItems(&reader)
+}
+