usertrust 1.4.0 → 2.0.0

package/dist/govern.js

@@ -30,12 +30,12 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync } from "node:fs";
 import { readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { CreateTransferError } from "tigerbeetle-node";
+import { CreateTransferStatus } from "tigerbeetle-node";
 import { createAuditWriter } from "./audit/chain.js";
 import { writeReceipt } from "./audit/rotation.js";
-import { detectClientKind } from "./detect.js";
+import { classifyEndpoint, detectClientKind } from "./detect.js";
 import { TBTransferError, TrustTBClient, XFER_SPEND } from "./ledger/client.js";
-import { estimateCost, estimateInputTokens } from "./ledger/pricing.js";
+import { costFromRates, estimateInputTokens, resolveRates, warnUnknownModel, } from "./ledger/pricing.js";
 import { recordPattern } from "./memory/patterns.js";
 import { DEFAULT_RULES, mergePolicies } from "./policy/default-rules.js";
 import { evaluatePolicy, loadPolicies } from "./policy/gate.js";
@@ -66,6 +66,86 @@ class AsyncMutex {
         return release;
     }
 }
+// ── M2 unknown-model policy (A5) ──
+/** USD value of one usertoken: 1 usertoken = $0.0001 (one basis point of a cent). */
+const USERTOKENS_PER_DOLLAR = 10_000;
+/**
+ * Enforce config.unknownModelPolicy at AUTHORIZE time (A5). Only cloud-scope
+ * resolutions can be unknown — local scope always resolves to local rates.
+ * "deny" throws before any PENDING hold; "warn" logs once per model string per
+ * process via the shared warnUnknownModel helper (receipts carry
+ * meter.rateSource "fallback" regardless of warn dedup); "fallback" is silent.
+ */
+function enforceUnknownModelPolicy(model, resolution, config) {
+    if (!resolution.unknown)
+        return;
+    if (config.unknownModelPolicy === "deny") {
+        throw new PolicyDeniedError(`unknown_model: ${model} not in pricing table`);
+    }
+    if (config.unknownModelPolicy === "warn") {
+        warnUnknownModel(model);
+    }
+}
+/**
+ * A4: build forward-args for a local openai stream call with
+ * stream_options.include_usage merged in. The caller's other stream_options
+ * fields survive; an explicit include_usage (true OR false) is respected —
+ * only a missing/null value injects. Returns null when no injection applies.
+ */
+function withInjectedUsageOptions(args) {
+    const params = (args[0] ?? {});
+    if (params.stream !== true)
+        return null;
+    const rawOptions = params.stream_options;
+    const streamOptions = rawOptions != null && typeof rawOptions === "object"
+        ? rawOptions
+        : undefined;
+    if (streamOptions?.include_usage != null)
+        return null;
+    return [
+        { ...params, stream_options: { ...streamOptions, include_usage: true } },
+        ...args.slice(1),
+    ];
+}
+/** Message shapes an OpenAI-compat server emits when it rejects an unknown field. */
+const STREAM_OPTIONS_REJECTION_RE = /stream_options|include_usage|unrecognized|unknown.{0,20}(field|argument|parameter|option)/i;
+/**
+ * A4 retry heuristic: does `err` plausibly indicate that the server rejected the
+ * injected `stream_options.include_usage`? We only retry-without-injection for
+ * these — a blanket retry on ANY error would double the provider call on
+ * transient failures (ECONNRESET, timeouts, 5xx) and mask the real root cause,
+ * so everything else rethrows the ORIGINAL error immediately. Matches the
+ * rejection message on the error, its nested `error.message`, or a cheaply
+ * reachable `response` body; or an HTTP-shaped 400/422 status on the error
+ * object. Tradeoff: a server that rejects the field with an opaque 500 and no
+ * telltale text is NOT retried — acceptable, since include_usage is widely
+ * supported and the caller still receives the original error.
+ */
+function looksLikeStreamOptionsRejection(err) {
+    if (err == null || typeof err !== "object") {
+        return err instanceof Error && STREAM_OPTIONS_REJECTION_RE.test(err.message);
+    }
+    const e = err;
+    const status = e.status ?? e.statusCode;
+    if (status === 400 || status === 422)
+        return true;
+    const candidates = [e.message, e.body];
+    if (err instanceof Error)
+        candidates.push(err.message);
+    const nested = e.error;
+    if (nested != null && typeof nested === "object") {
+        candidates.push(nested.message);
+    }
+    const response = e.response;
+    if (typeof response === "string") {
+        candidates.push(response);
+    }
+    else if (response != null && typeof response === "object") {
+        const r = response;
+        candidates.push(r.data, r.body);
+    }
+    return candidates.some((c) => typeof c === "string" && STREAM_OPTIONS_REJECTION_RE.test(c));
+}
 async function loadSpendLedger(vaultBase) {
     const ledgerPath = join(vaultBase, VAULT_DIR, "spend-ledger.json");
     try {
@@ -139,7 +219,6 @@ export async function trust(client, opts) {
             budget: opts?.budget ?? DEFAULT_BUDGET,
         });
     }
-    const customRates = config.pricing === "custom" ? config.customRates : undefined;
     const isDryRun = opts?.dryRun ?? process.env.USERTRUST_DRY_RUN === "true";
     // AUD-470: Only accept injected _engine/_audit in test environments.
     // In production, silently ignore them to prevent governance bypass.
@@ -189,8 +268,12 @@ export async function trust(client, opts) {
     else {
         engine = null;
     }
-    // 5. Detect client kind
+    // 5. Detect client kind (transport) + classify the endpoint (settlement
+    // regime, M2). classifyEndpoint runs BESIDE detectClientKind — the endpoint
+    // class, not the model string, picks local vs cloud metering (A3: this scope
+    // is captured once here and used verbatim at every authorize/settle below).
     const kind = detectClientKind(client);
+    const endpoint = classifyEndpoint(client, config, opts?.endpoint);
     // 6. Track state
     let destroyed = false;
     const budgetMutex = new AsyncMutex(); // AUD-453: serialise budget-check + hold
@@ -199,9 +282,43 @@ export async function trust(client, opts) {
     let inFlightHoldTotal = 0; // Track estimated cost of in-flight pending holds
     // Streaming anomaly detector — shared across calls so injection-cascade
     // can track signals across the conversation. Disabled when config.anomaly.enabled=false.
-    const anomalyDetector = createAnomalyDetector(config.anomaly, { provider: kind });
+    // M2 seam fix: the injected costCalculator prices spend-velocity with the
+    // SAME scoped rates as settlement, using the observed event's
+    // model/endpointClass (the detector is shared while the model varies per
+    // call). Denominations differ by design: cloud events → DOLLARS against
+    // thresholdDollarsPerMin; local events → nominal usertokens against
+    // localThresholdUsertokensPerMin, WITHOUT the per-call >=1 settlement floor.
+    // Settlement floors per call; the anomaly signal measures flow — so a
+    // default {0,0}-rate local stream contributes 0 and can never false-trip
+    // spend_velocity (rejected-merge design note, pinned by Task 3 tests).
+    const anomalyDetector = createAnomalyDetector(config.anomaly, {
+        provider: kind,
+        costCalculator: (calcModel, inputTokens, outputTokens, event) => {
+            const scope = event?.endpointClass ?? "cloud";
+            const resolution = resolveRates(event?.model ?? calcModel, scope, config);
+            if (scope === "local") {
+                const inTok = Number.isFinite(inputTokens) && inputTokens > 0 ? inputTokens : 0;
+                const outTok = Number.isFinite(outputTokens) && outputTokens > 0 ? outputTokens : 0;
+                return ((inTok / 1000) * resolution.rates.inputPer1k +
+                    (outTok / 1000) * resolution.rates.outputPer1k);
+            }
+            return costFromRates(resolution.rates, inputTokens, outputTokens) / USERTOKENS_PER_DOLLAR;
+        },
+    });
     // 7. Two-phase intercept
-    async function interceptCall(originalFn, thisArg, args) {
+    async function interceptCall(originalFn, thisArg, args, 
+    // A1: which provider surface this call arrived through. "create" is the
+    // default request/response (and create-stream) path. "stream-helper" is the
+    // Anthropic messages.stream / beta.messages.stream convenience helper, whose
+    // forwarded call returns a self-driving MessageStream we settle via
+    // NON-CONSUMING emitter events instead of routing through
+    // createGovernedStream (A1) — consuming its single-owner async iterator would
+    // steal it from the caller. "openai-responses" (Task 3, A6) is the OpenAI
+    // Responses API (create, stream and non-stream): it shares the create request/
+    // response lifecycle and the generic createGovernedStream streaming path (A7),
+    // but MUST NOT receive the chat.completions-only stream_options.include_usage
+    // injection (A6) — the surface flag suppresses it below.
+    surfaceKind = "create") {
         if (destroyed) {
             throw new Error("TrustedClient has been destroyed");
         }
@@ -224,11 +341,22 @@ export async function trust(client, opts) {
             // a. Circuit breaker check
             const cb = breaker.get(kind);
             cb.allowRequest();
-            // b. Estimate cost (before policy, so cost fields are available in context)
+            // b. Estimate cost (before policy, so cost fields are available in context).
+            // M2: rates resolve within the endpoint scope CAPTURED AT AUTHORIZE (A3) —
+            // this one resolution prices the hold, both settlement paths, and the
+            // receipt's meter provenance. unknownModelPolicy is enforced here, at
+            // authorize time, before any PENDING hold (A5).
             const transferId = trustId("tx");
             const estimatedInputTokens = estimateInputTokens(promptParts);
-            const maxOutputTokens = params.max_tokens ?? 4096;
-            const estimatedCost = estimateCost(model, estimatedInputTokens, maxOutputTokens, customRates);
+            // F1: size the output estimate to the caller's ACTUAL cap. Responses callers
+            // set `max_output_tokens`; chat.completions set `max_tokens`. Read the
+            // Responses field first, then chat, then the 4096 default — each only when it
+            // is a finite positive number (a 0/negative/NaN cap never shrinks the hold).
+            const finitePositiveCap = (value) => typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+            const maxOutputTokens = finitePositiveCap(params.max_output_tokens) ?? finitePositiveCap(params.max_tokens) ?? 4096;
+            const rateResolution = resolveRates(model, endpoint.class, config);
+            enforceUnknownModelPolicy(model, rateResolution, config);
+            const estimatedCost = costFromRates(rateResolution.rates, estimatedInputTokens, maxOutputTokens);
             // AUD-453: Acquire mutex to serialise budget-check + PENDING hold.
             // This prevents concurrent calls from both passing the budget check
             // and overshooting the budget.
@@ -352,187 +480,555 @@ export async function trust(client, opts) {
                 // AUD-453: Release lock after budget check + hold are complete
                 releaseBudgetLock();
             }
+            // e0. M2 usage injection (A4): for local openai streams, opt in to the
+            // server's final usage chunk (Ollama emits /v1 streaming usage ONLY when
+            // stream_options.include_usage is set). The merge preserves the caller's
+            // other stream_options fields and respects an explicit include_usage.
+            // The resulting usage chunk is FORWARDED to the consumer unmodified
+            // (transparent middleware). Task 3/A6: the OpenAI Responses API is EXCLUDED
+            // — stream_options.include_usage is chat.completions-only; Responses carries
+            // usage automatically on the terminal `response.completed` event, and
+            // injecting the param would be an unknown field on the Responses request.
+            let preInjectionArgs = null;
+            if (kind === "openai" &&
+                surfaceKind !== "openai-responses" &&
+                endpoint.class === "local" &&
+                config.local.injectUsageOptions) {
+                const injected = withInjectedUsageOptions(forwardArgs);
+                if (injected != null) {
+                    preInjectionArgs = forwardArgs;
+                    forwardArgs = injected;
+                }
+            }
             // e. Forward to original SDK. P3-PII-REDACT-EGRESS: forwardArgs is the
             // redacted clone in redact mode, or the original args otherwise.
             let settled = true;
-            try {
-                const response = await originalFn.apply(thisArg, forwardArgs);
-                // e2. Streaming detection: if response is an async iterable, wrap with
-                // token accumulation. Settlement and audit happen when the stream ends.
-                if (response != null &&
-                    typeof response === "object" &&
-                    Symbol.asyncIterator in response) {
-                    const stream = response;
-                    const governedStream = createGovernedStream(stream, kind, async (completion) => {
-                        // Determine cost: use provider usage if reported, else fall back to estimate
-                        let streamCost;
-                        let usageSource;
-                        if (completion.usageReported) {
-                            streamCost = estimateCost(model, completion.usage.inputTokens, completion.usage.outputTokens, customRates);
-                            usageSource = "provider";
-                        }
-                        else {
-                            streamCost = estimatedCost;
-                            usageSource = "estimated";
-                        }
-                        // Release in-flight hold and commit budget under mutex
-                        // AUD-468: holdActive guard prevents double-release if the
-                        // outer catch also fires (e.g. from a synchronous exception
-                        // during stream construction).
-                        if (holdActive) {
-                            holdActive = false;
-                            const releaseLock = await budgetMutex.acquire();
-                            inFlightHoldTotal -= estimatedCost;
-                            budgetSpent += streamCost;
-                            releaseLock();
-                        }
-                        else {
-                            // Hold already released — still need to record the spend.
-                            const releaseLock = await budgetMutex.acquire();
-                            budgetSpent += streamCost;
-                            releaseLock();
-                        }
-                        // AUD-457: Persist cumulative spend to disk
-                        await persistSpendLedger(vaultBase, budgetSpent);
-                        cb.recordSuccess();
-                        if (proxyConn != null && !isDryRun) {
-                            try {
-                                // AUD-460: Use the proxy's transferId for settlement
-                                await proxyConn.settle(proxyTransferId ?? transferId, streamCost);
-                            }
-                            catch (postErr) {
-                                settled = false;
-                                await audit
-                                    .appendEvent({
-                                    kind: "settlement_ambiguous",
-                                    actor: "local",
-                                    data: {
-                                        model,
-                                        cost: streamCost,
-                                        transferId,
-                                        error: postErr instanceof Error
-                                            ? postErr.message.slice(0, 200)
-                                            : String(postErr).slice(0, 200),
-                                    },
-                                })
-                                    .catch(() => {
-                                    callAuditDegraded = true;
-                                });
-                            }
-                        }
-                        else if (engine != null && !isDryRun) {
-                            try {
-                                // Post the ACTUAL consumed cost (RECON #3).
-                                await engine.postPendingSpend(transferId, streamCost);
-                            }
-                            catch (postErr) {
-                                settled = false;
-                                await audit
-                                    .appendEvent({
-                                    kind: "settlement_ambiguous",
-                                    actor: "local",
-                                    data: {
-                                        model,
-                                        cost: streamCost,
-                                        transferId,
-                                        error: postErr instanceof Error
-                                            ? postErr.message.slice(0, 200)
-                                            : String(postErr).slice(0, 200),
-                                    },
-                                })
-                                    .catch(() => {
-                                    callAuditDegraded = true;
-                                });
-                            }
-                        }
-                        const syntheticHash = createHash("sha256").update(transferId).digest("hex");
-                        let auditHash = syntheticHash;
-                        try {
-                            const auditEventData = {
+            // A2: one idempotent finalize gate per hold. The FIRST terminal signal for
+            // this authorization wins and claims the single ledger outcome (settle XOR
+            // void); every later signal returns false and MUST NOT mutate the ledger.
+            // Every terminal path routes through it: the non-stream settle + its
+            // outer-catch void, the stream onComplete/onError closures below, and
+            // (Tasks 2/3) any new surface's emitter/iterator/error/abort listeners. A
+            // duplicate terminal signal can neither double-settle nor double-void.
+            let finalizeState = "pending";
+            function finalizeOnce(outcome) {
+                if (finalizeState !== "pending")
+                    return false;
+                finalizeState = outcome === "settle" ? "settled" : "voided";
+                return true;
+            }
+            // Estimate-priced stream receipt (settled:false). Serves as the initial
+            // handle returned to the caller AND the idempotent fallback a duplicate
+            // stream terminal returns after the hold was already resolved.
+            const buildEstimatedStreamReceipt = () => {
+                const streamEstimateHash = createHash("sha256").update(transferId).digest("hex");
+                return {
+                    transferId,
+                    cost: estimatedCost,
+                    budgetRemaining: config.budget - budgetSpent - inFlightHoldTotal,
+                    auditHash: callAuditDegraded ? "AUDIT_DEGRADED" : streamEstimateHash,
+                    chainPath: join(VAULT_DIR, "audit"),
+                    receiptUrl: opts?.proxy != null ? `${VERIFY_URL_BASE}/${transferId}` : null,
+                    settled: false, // AUD-454: not settled yet — stream hasn't been consumed
+                    model,
+                    provider: kind,
+                    timestamp: new Date().toISOString(),
+                    // M2: authorize-time scope, already fixed for the eventual settle (A3).
+                    endpoint: { class: endpoint.class, runtime: endpoint.runtime },
+                    meter: {
+                        costBasis: rateResolution.costBasis,
+                        rateSource: rateResolution.rateSource,
+                    },
+                    ...(callAuditDegraded ? { auditDegraded: true } : {}),
+                    // AUD-456: Flag proxy stub receipts
+                    ...(proxyConn != null ? { proxyStub: true } : {}),
+                };
+            };
+            // Terminal stream settlement (A2 settle branch). Idempotent via
+            // finalizeOnce: budget commit + ledger POST + llm_call audit happen AT MOST
+            // ONCE per hold. Tasks 2/3 reuse this verbatim — the
+            // Anthropic MessageStream 'finalMessage' listener and any new stream surface
+            // call it with a StreamCompletion built from final usage. Does NOT touch
+            // inFlightStreamCount — the caller (createGovernedStream wiring, or a new
+            // surface's listener) owns that counter.
+            let streamSettledReceipt;
+            const finalizeStreamSettle = async (completion) => {
+                if (!finalizeOnce("settle")) {
+                    // A duplicate terminal (e.g. 'finalMessage' after 'end', or a settle
+                    // racing an abort-void): never mutate the ledger again.
+                    return streamSettledReceipt ?? buildEstimatedStreamReceipt();
+                }
+                // Determine cost: use provider usage if reported, else fall back to
+                // estimate. A3: priced with the rate resolution captured at authorize;
+                // A11: costFromRates floors at 1 even for 0/0 usage.
+                let streamCost;
+                let usageSource;
+                if (completion.usageReported) {
+                    streamCost = costFromRates(rateResolution.rates, completion.usage.inputTokens, completion.usage.outputTokens);
+                    usageSource = "provider";
+                }
+                else {
+                    streamCost = estimatedCost;
+                    usageSource = "estimated";
+                }
+                // Release in-flight hold and commit budget under mutex.
+                // AUD-468: holdActive guard prevents double-release.
+                if (holdActive) {
+                    holdActive = false;
+                    const releaseLock = await budgetMutex.acquire();
+                    inFlightHoldTotal -= estimatedCost;
+                    budgetSpent += streamCost;
+                    releaseLock();
+                }
+                else {
+                    // Hold already released — still need to record the spend.
+                    const releaseLock = await budgetMutex.acquire();
+                    budgetSpent += streamCost;
+                    releaseLock();
+                }
+                // AUD-457: Persist cumulative spend to disk
+                await persistSpendLedger(vaultBase, budgetSpent);
+                cb.recordSuccess();
+                if (proxyConn != null && !isDryRun) {
+                    try {
+                        // AUD-460: Use the proxy's transferId for settlement
+                        await proxyConn.settle(proxyTransferId ?? transferId, streamCost);
+                    }
+                    catch (postErr) {
+                        settled = false;
+                        await audit
+                            .appendEvent({
+                            kind: "settlement_ambiguous",
+                            actor: "local",
+                            data: {
                                 model,
                                 cost: streamCost,
-                                settled,
                                 transferId,
-                                usageSource,
-                                chunksDelivered: completion.chunksDelivered,
-                            };
-                            if (config.pii === "warn" || config.pii === "redact") {
-                                const piiResult = redactPII(promptParts);
-                                if (piiResult.detection.found) {
-                                    auditEventData.piiDetected = piiResult.detection.types;
-                                    auditEventData.piiPaths = piiResult.detection.paths;
-                                }
-                            }
-                            const auditEvent = await audit.appendEvent({
-                                kind: "llm_call",
-                                actor: "local",
-                                data: auditEventData,
-                            });
-                            auditHash = auditEvent.hash;
-                        }
-                        catch {
+                                error: postErr instanceof Error
+                                    ? postErr.message.slice(0, 200)
+                                    : String(postErr).slice(0, 200),
+                            },
+                        })
+                            .catch(() => {
                             callAuditDegraded = true;
+                        });
+                    }
+                }
+                else if (engine != null && !isDryRun) {
+                    try {
+                        // Post the ACTUAL consumed cost (RECON #3).
+                        await engine.postPendingSpend(transferId, streamCost);
+                    }
+                    catch (postErr) {
+                        settled = false;
+                        await audit
+                            .appendEvent({
+                            kind: "settlement_ambiguous",
+                            actor: "local",
+                            data: {
+                                model,
+                                cost: streamCost,
+                                transferId,
+                                error: postErr instanceof Error
+                                    ? postErr.message.slice(0, 200)
+                                    : String(postErr).slice(0, 200),
+                            },
+                        })
+                            .catch(() => {
+                            callAuditDegraded = true;
+                        });
+                    }
+                }
+                const syntheticHash = createHash("sha256").update(transferId).digest("hex");
+                let auditHash = syntheticHash;
+                try {
+                    const auditEventData = {
+                        model,
+                        cost: streamCost,
+                        settled,
+                        transferId,
+                        usageSource,
+                        chunksDelivered: completion.chunksDelivered,
+                        // M2: metering provenance mirrors the receipt (A3 authorize-time scope).
+                        endpointClass: endpoint.class,
+                        costBasis: rateResolution.costBasis,
+                        rateSource: rateResolution.rateSource,
+                    };
+                    if (config.pii === "warn" || config.pii === "redact") {
+                        const piiResult = redactPII(promptParts);
+                        if (piiResult.detection.found) {
+                            auditEventData.piiDetected = piiResult.detection.types;
+                            auditEventData.piiPaths = piiResult.detection.paths;
                         }
-                        // P3-AUDIT-FAILCLOSED (streaming): chunks were already delivered,
-                        // so the strongest post-delivery signal is to REJECT `.receipt`.
-                        // Decrement the stream counter first so destroy() never blocks.
-                        if (config.audit.failClosed && (callAuditDegraded || audit.isDegraded())) {
-                            inFlightStreamCount--;
-                            throw new AuditDegradedError(`audit unavailable (writeFailures=${audit.getWriteFailures()}) for ${transferId}`);
-                        }
-                        const streamReceipt = {
-                            transferId,
-                            cost: streamCost,
-                            budgetRemaining: config.budget - budgetSpent - inFlightHoldTotal,
-                            auditHash: callAuditDegraded ? "AUDIT_DEGRADED" : auditHash,
-                            chainPath: join(VAULT_DIR, "audit"),
-                            receiptUrl: opts?.proxy != null ? `${VERIFY_URL_BASE}/${transferId}` : null,
-                            settled,
-                            model,
-                            provider: kind,
-                            timestamp: new Date().toISOString(),
-                            usageSource,
-                            chunksDelivered: completion.chunksDelivered,
-                            ...(callAuditDegraded ? { auditDegraded: true } : {}),
-                            // AUD-456: Flag proxy stub receipts
-                            ...(proxyConn != null ? { proxyStub: true } : {}),
-                        };
-                        inFlightStreamCount--;
-                        return streamReceipt;
-                    }, async (error, partial) => {
-                        // Release in-flight hold under mutex
-                        // AUD-468: holdActive guard prevents double-release.
-                        await releaseInFlightHold();
-                        cb.recordFailure();
-                        // Best-effort audit of partial delivery
+                    }
+                    const auditEvent = await audit.appendEvent({
+                        kind: "llm_call",
+                        actor: "local",
+                        data: auditEventData,
+                    });
+                    auditHash = auditEvent.hash;
+                }
+                catch {
+                    callAuditDegraded = true;
+                }
+                // P3-AUDIT-FAILCLOSED (streaming): chunks were already delivered, so the
+                // strongest post-delivery signal is to REJECT `.receipt`. The caller's
+                // finally decrements inFlightStreamCount so destroy() never blocks.
+                if (config.audit.failClosed && (callAuditDegraded || audit.isDegraded())) {
+                    throw new AuditDegradedError(`audit unavailable (writeFailures=${audit.getWriteFailures()}) for ${transferId}`);
+                }
+                const streamReceipt = {
+                    transferId,
+                    cost: streamCost,
+                    budgetRemaining: config.budget - budgetSpent - inFlightHoldTotal,
+                    auditHash: callAuditDegraded ? "AUDIT_DEGRADED" : auditHash,
+                    chainPath: join(VAULT_DIR, "audit"),
+                    receiptUrl: opts?.proxy != null ? `${VERIFY_URL_BASE}/${transferId}` : null,
+                    settled,
+                    model,
+                    provider: kind,
+                    timestamp: new Date().toISOString(),
+                    usageSource,
+                    chunksDelivered: completion.chunksDelivered,
+                    // M2 provenance (A6: computeMs omitted — no compute-time source here).
+                    endpoint: { class: endpoint.class, runtime: endpoint.runtime },
+                    meter: {
+                        costBasis: rateResolution.costBasis,
+                        rateSource: rateResolution.rateSource,
+                    },
+                    ...(callAuditDegraded ? { auditDegraded: true } : {}),
+                    // AUD-456: Flag proxy stub receipts
+                    ...(proxyConn != null ? { proxyStub: true } : {}),
+                };
+                streamSettledReceipt = streamReceipt;
+                return streamReceipt;
+            };
+            // Terminal stream void (A2 void branch). Idempotent via finalizeOnce:
+            // releases the hold and voids the ledger AT MOST ONCE. Tasks 2/3 reuse this
+            // for the Anthropic MessageStream 'error'/'abort' listeners and any new
+            // stream surface's error path. Does NOT touch inFlightStreamCount.
+            const finalizeStreamVoid = async (error, partial) => {
+                if (!finalizeOnce("void"))
+                    return;
+                // Release in-flight hold under mutex (AUD-468: guarded).
+                await releaseInFlightHold();
+                cb.recordFailure();
+                // Best-effort audit of partial delivery
+                audit
+                    .appendEvent({
+                    kind: "stream_partial_delivery",
+                    actor: "local",
+                    data: {
+                        transferId,
+                        model,
+                        chunksDelivered: partial.chunksDelivered,
+                        partialInputTokens: partial.usage.inputTokens,
+                        partialOutputTokens: partial.usage.outputTokens,
+                        usageReported: partial.usageReported,
+                        error: (() => {
+                            const raw = error instanceof Error ? error.message : String(error);
+                            return config.pii === "warn" || config.pii === "redact"
+                                ? redactPII(raw).data.slice(0, 200)
+                                : raw.slice(0, 200);
+                        })(),
+                    },
+                })
+                    .catch(() => { });
+                if (proxyConn != null && !isDryRun) {
+                    // AUD-460: Use the proxy's transferId for void
+                    proxyConn.void(proxyTransferId ?? transferId).catch(() => { });
+                }
+                else if (engine != null && !isDryRun) {
+                    engine.voidPendingSpend(transferId).catch(() => { });
+                }
+            };
+            // A1: settle an Anthropic MessageStream (messages.stream /
+            // beta.messages.stream) via its MULTICAST event emitter, never by consuming
+            // its single-owner async iterator (that belongs to the caller). The stream
+            // self-drives, so finalMessage/error/abort fire even if the caller never
+            // consumes (A4); the TigerBeetle PENDING 300s timeout (see destroy() and
+            // createPendingTransfer) is the last-resort backstop for a hold whose
+            // terminal event never arrives. finalizeOnce makes the six-mode consumption
+            // matrix safe: settle XOR void, exactly one ledger mutation.
+            const settleViaMessageStream = (streamObj) => {
+                // The initial handle: estimate-priced, settled:false — identical to the
+                // generic stream path. The caller reads the real receipt off `.receipt`.
+                const estimatedReceipt = buildEstimatedStreamReceipt();
+                const emitter = streamObj != null && typeof streamObj === "object"
+                    ? streamObj
+                    : null;
+                // This closure OWNS inFlightStreamCount for the stream's lifetime; the
+                // finalize* gates never touch it. Release it EXACTLY ONCE no matter how
+                // many terminal events fire (finalMessage-then-abort race, error-after-
+                // end, …) so destroy() never blocks and the counter never drifts.
+                inFlightStreamCount++;
+                let streamCountReleased = false;
+                const releaseStreamCount = () => {
+                    if (streamCountReleased)
+                        return;
+                    streamCountReleased = true;
+                    inFlightStreamCount--;
+                };
+                // `.receipt`: resolves with the settled receipt, rejects on a genuine
+                // stream error / failClosed. Built BEFORE the feature-detect branch so BOTH
+                // the emitter path and the non-emitter fallback expose a live `.receipt` the
+                // caller can await for the settled outcome. F8: governance never SILENTLY
+                // swallows a stream failure — a consumer who awaits `.receipt` always sees
+                // the error (the pre-attached catch below is a SEPARATE branch: promises are
+                // multicast, so it silences the unhandled-rejection ONLY for a fire-and-forget
+                // consumer that never awaits `.receipt`, never registers an error handler, and
+                // never calls done()/finalMessage() — that narrow gap is documented).
+                let receiptResolve;
+                let receiptReject;
+                const receiptPromise = new Promise((res, rej) => {
+                    receiptResolve = res;
+                    receiptReject = rej;
+                });
+                receiptPromise.catch(() => { });
+                // Expose `.receipt` on the returned stream object (best-effort — a frozen or
+                // non-object stream simply omits it; the terminal events still settle
+                // governance).
+                const attachReceipt = () => {
+                    if (streamObj == null || typeof streamObj !== "object")
+                        return;
+                    try {
+                        Object.assign(streamObj, { receipt: receiptPromise });
+                    }
+                    catch {
+                        // non-extensible target — skip
+                    }
+                };
+                // A3: a helper that connected is a billable SUCCESS. If the forwarded
+                // object is not an event-emitter MessageStream (feature-detect miss / an
+                // SDK too old to return one), we cannot tap emitter events — settle at
+                // ESTIMATE now so the hold never dangles, resolve `.receipt` from that
+                // background settle (mirroring the finalMessage path), and hand the object
+                // back raw.
+                if (emitter == null || typeof emitter.on !== "function") {
+                    finalizeStreamSettle({
+                        usage: { inputTokens: 0, outputTokens: 0 },
+                        chunksDelivered: 0,
+                        usageReported: false,
+                    })
+                        .then(receiptResolve, receiptReject)
+                        .finally(releaseStreamCount);
+                    attachReceipt();
+                    return { response: streamObj, receipt: estimatedReceipt };
+                }
+                // Non-consuming chunk accounting: streamEvent is multicast, so tapping it
+                // does not steal the caller's iterator. Mirrors the wrapStream tap so
+                // partial-void audits and a usage-less finalMessage both carry real
+                // numbers, and (best-effort, A1) trips the shared anomaly detector.
+                let chunksDelivered = 0;
+                let accInput = 0;
+                let accOutput = 0;
+                let accUsageReported = false;
+                // R1: set TRUE before governance calls emitter.abort() on an anomaly trip,
+                // so the 'abort' handler can distinguish a governance cutoff (void + breaker
+                // failure) from a genuine consumer abort (F9 settle-partial).
+                let anomalyAbort = false;
+                const partial = () => ({
+                    usage: { inputTokens: accInput, outputTokens: accOutput },
+                    chunksDelivered,
+                    usageReported: accUsageReported,
+                });
+                emitter.on("streamEvent", (event) => {
+                    chunksDelivered++;
+                    const tokens = extractAnthropicStreamUsage(event);
+                    let deltaTokens = 0;
+                    if (tokens.inputTokens > accInput) {
+                        deltaTokens += tokens.inputTokens - accInput;
+                        accInput = tokens.inputTokens;
+                        accUsageReported = true;
+                    }
+                    if (tokens.outputTokens > accOutput) {
+                        deltaTokens += tokens.outputTokens - accOutput;
+                        accOutput = tokens.outputTokens;
+                        accUsageReported = true;
+                    }
+                    if (!config.anomaly.enabled)
+                        return;
+                    anomalyDetector.observe({
+                        kind: "chunk",
+                        deltaTokens,
+                        cumulativeInputTokens: accInput,
+                        cumulativeOutputTokens: accOutput,
+                        // M2: stamp the per-call scope so the SHARED detector prices this
+                        // event with the same scoped rates as settlement.
+                        model,
+                        endpointClass: endpoint.class,
+                    });
+                    const verdict = anomalyDetector.check();
+                    if (verdict.tripped) {
                         audit
                             .appendEvent({
-                            kind: "stream_partial_delivery",
+                            kind: "anomaly_detected",
                             actor: "local",
                             data: {
-                                transferId,
+                                anomalyKind: verdict.kind,
+                                message: verdict.message,
+                                metric: verdict.metric,
+                                threshold: verdict.threshold,
                                 model,
-                                chunksDelivered: partial.chunksDelivered,
-                                partialInputTokens: partial.usage.inputTokens,
-                                partialOutputTokens: partial.usage.outputTokens,
-                                usageReported: partial.usageReported,
-                                error: (() => {
-                                    const raw = error instanceof Error ? error.message : String(error);
-                                    return config.pii === "warn" || config.pii === "redact"
-                                        ? redactPII(raw).data.slice(0, 200)
-                                        : raw.slice(0, 200);
-                                })(),
+                                transferId,
+                                provider: kind,
                             },
                         })
                             .catch(() => { });
-                        if (proxyConn != null && !isDryRun) {
-                            // AUD-460: Use the proxy's transferId for void
-                            proxyConn.void(proxyTransferId ?? transferId).catch(() => { });
+                        // A1 best-effort mid-stream cutoff (full parity deferred). R1: flag
+                        // this as a GOVERNANCE abort BEFORE aborting so the 'abort' handler
+                        // VOIDs + records a breaker failure — same ledger + breaker outcome as
+                        // the generic createGovernedStream anomaly path (which throws
+                        // AnomalyError → finalizeStreamVoid). finalizeOnce keeps it safe if a
+                        // finalMessage is already in flight.
+                        anomalyAbort = true;
+                        if (typeof emitter.abort === "function")
+                            emitter.abort();
+                    }
+                });
+                emitter.on("finalMessage", (msg) => {
+                    // A3: usage-extraction failure after a successful stream settles at
+                    // ESTIMATE, never voids. F3: MERGE per-field — a finalMessage that
+                    // carries only one field (or null for the other) keeps the counter
+                    // accumulated from streamEvent for the MISSING field, rather than
+                    // zeroing it. Reported when EITHER source carried a real number;
+                    // otherwise settle on the estimate.
+                    const finalUsage = readFinalMessageUsage(msg);
+                    const usageReported = finalUsage.reported || accUsageReported;
+                    const completion = usageReported
+                        ? {
+                            usage: {
+                                inputTokens: finalUsage.inputTokens ?? accInput,
+                                outputTokens: finalUsage.outputTokens ?? accOutput,
+                            },
+                            chunksDelivered,
+                            usageReported: true,
                         }
-                        else if (engine != null && !isDryRun) {
-                            engine.voidPendingSpend(transferId).catch(() => { });
+                        : {
+                            usage: { inputTokens: 0, outputTokens: 0 },
+                            chunksDelivered,
+                            usageReported: false,
+                        };
+                    finalizeStreamSettle(completion)
+                        .then(receiptResolve, receiptReject)
+                        .finally(releaseStreamCount);
+                });
+                const voidVia = (error) => {
+                    // finalizeStreamVoid claims finalizeOnce("void") SYNCHRONOUSLY at its
+                    // top, so finalizeState reflects the outcome the moment it returns.
+                    finalizeStreamVoid(error, partial()).finally(releaseStreamCount);
+                    // Only surface the void on `.receipt` when THIS terminal actually won
+                    // the gate. A late abort after a settle is a ledger no-op (finalizeOnce
+                    // already granted "settle") — it must not reject a receipt the settle
+                    // path will resolve, even though that settle's async is still in flight.
+                    if (finalizeState === "voided")
+                        receiptReject(error);
+                };
+                // F9: a consumer-initiated abort surfaces as the SDK's 'abort' event
+                // (APIUserAbortError), distinct from the provider-failure 'error' event. It
+                // is an early EXIT, not a failure: settle at the PARTIAL accumulated usage
+                // (mirroring the generic governed-stream break-out-of-for-await path) instead
+                // of voiding, and never record a circuit-breaker failure — a caller who
+                // aborts N streams must not trip the breaker. finalizeStreamSettle records
+                // success. The `pending` guard makes a LATE abort after a real terminal a
+                // clean no-op: without it the no-op settle would resolve `.receipt` with a
+                // stale estimate, racing (and beating) the winning terminal's async settle.
+                const settlePartialVia = () => {
+                    if (finalizeState !== "pending")
+                        return;
+                    finalizeStreamSettle(partial())
+                        .then(receiptResolve, receiptReject)
+                        .finally(releaseStreamCount);
+                };
+                emitter.on("error", (err) => voidVia(err ?? new Error("stream error")));
+                // R1: a GOVERNANCE anomaly cutoff (anomalyAbort) is a provider-side FAILURE —
+                // void the hold + record a breaker failure, matching the generic path. A
+                // genuine consumer abort is an early exit — settle the partial usage (F9).
+                emitter.on("abort", (err) => {
+                    if (anomalyAbort) {
+                        voidVia(err ?? new Error("anomaly cutoff"));
+                    }
+                    else {
+                        settlePartialVia();
+                    }
+                });
+                // F6: the real MessageStream emits NO 'finalMessage' on a clean SSE close
+                // that lacks a message_stop (receivedMessages stays empty → _emitFinal emits
+                // nothing) — only 'end' fires. Without an 'end' catch-all the PENDING hold
+                // would dangle until the TigerBeetle 300s timeout. When 'end' is the SOLE
+                // terminal (gate still pending) settle at ESTIMATE so the hold releases; on
+                // every other terminal ('end' always fires last, after the winning settle/
+                // void) the guard makes this a no-op that must NOT touch `.receipt`.
+                emitter.on("end", () => {
+                    if (finalizeState !== "pending")
+                        return;
+                    finalizeStreamSettle({
+                        usage: { inputTokens: 0, outputTokens: 0 },
+                        chunksDelivered,
+                        usageReported: false,
+                    })
+                        .then(receiptResolve, receiptReject)
+                        .finally(releaseStreamCount);
+                });
+                attachReceipt();
+                return { response: streamObj, receipt: estimatedReceipt };
+            };
+            try {
+                let response;
+                try {
+                    response = await originalFn.apply(thisArg, forwardArgs);
+                }
+                catch (callErr) {
+                    // A4: some OpenAI-compat servers reject unknown stream_options. When
+                    // WE injected them AND the error plausibly says so (message/HTTP-status
+                    // heuristic), retry ONCE without the injection; the retried stream
+                    // simply settles on the estimate if no usage tail arrives (A7). Any
+                    // other error — transient network failures, unrelated 5xx — rethrows
+                    // the ORIGINAL immediately rather than duplicating compute and masking
+                    // the root cause.
+                    if (preInjectionArgs == null || !looksLikeStreamOptionsRejection(callErr)) {
+                        throw callErr;
+                    }
+                    response = await originalFn.apply(thisArg, preInjectionArgs);
+                }
+                // A1: Anthropic messages.stream / beta.messages.stream helper. The
+                // forwarded call returned a MessageStream (event-emitter + AsyncIterable)
+                // owned by the CALLER. Settle via its multicast emitter — this branch
+                // runs BEFORE the generic Symbol.asyncIterator path because a
+                // MessageStream matches that check too but must NEVER be routed through
+                // createGovernedStream (that would steal the caller's single async
+                // iterator, A1). A synchronous throw from stream() (bad params, connect
+                // failure before the object is returned) never reaches here — it lands in
+                // the outer catch, which voids the still-PENDING hold once.
+                if (surfaceKind === "stream-helper") {
+                    return settleViaMessageStream(response);
+                }
+                // e2. Streaming detection: if response is an async iterable, wrap with
+                // token accumulation. Settlement and audit happen when the stream ends.
+                if (response != null &&
+                    typeof response === "object" &&
+                    Symbol.asyncIterator in response) {
+                    const stream = response;
+                    const governedStream = createGovernedStream(stream, kind, async (completion) => {
+                        // A2: route the createGovernedStream terminal through the shared
+                        // idempotent settle gate. The finally decrements the stream counter on
+                        // BOTH the receipt return and the failClosed throw.
+                        try {
+                            return await finalizeStreamSettle(completion);
+                        }
+                        finally {
+                            inFlightStreamCount--;
+                        }
+                    }, async (error, partial) => {
+                        // A2: route the createGovernedStream error terminal through the shared
+                        // idempotent void gate. The finally decrements the stream counter exactly
+                        // as the success path does.
+                        try {
+                            await finalizeStreamVoid(error, partial);
+                        }
+                        finally {
+                            inFlightStreamCount--;
                         }
-                        inFlightStreamCount--;
                     }, 
                     // onChunk: streaming anomaly detector hook. Observe each chunk;
                     // if a signal trips, throw AnomalyError to abort the stream.
@@ -546,6 +1042,10 @@ export async function trust(client, opts) {
                             deltaTokens: obs.deltaTokens,
                             cumulativeInputTokens: obs.cumulativeInputTokens,
                             cumulativeOutputTokens: obs.cumulativeOutputTokens,
+                            // M2: stamp the per-call scope so the SHARED detector prices
+                            // this event with the same scoped rates as settlement.
+                            model,
+                            endpointClass: endpoint.class,
                         });
                         const verdict = anomalyDetector.check();
                         if (verdict.tripped) {
@@ -570,29 +1070,17 @@ export async function trust(client, opts) {
                         }
                     });
                     // AUD-454: For streaming responses, settlement has NOT happened yet.
-                    // Set settled: false — the real settlement status will be on
-                    // governedStream.receipt after the stream is fully consumed.
-                    const streamEstimateHash = createHash("sha256").update(transferId).digest("hex");
-                    const estimatedReceipt = {
-                        transferId,
-                        cost: estimatedCost,
-                        budgetRemaining: config.budget - budgetSpent - inFlightHoldTotal,
-                        auditHash: callAuditDegraded ? "AUDIT_DEGRADED" : streamEstimateHash,
-                        chainPath: join(VAULT_DIR, "audit"),
-                        receiptUrl: opts?.proxy != null ? `${VERIFY_URL_BASE}/${transferId}` : null,
-                        settled: false, // AUD-454: not settled yet — stream hasn't been consumed
-                        model,
-                        provider: kind,
-                        timestamp: new Date().toISOString(),
-                        ...(callAuditDegraded ? { auditDegraded: true } : {}),
-                        // AUD-456: Flag proxy stub receipts
-                        ...(proxyConn != null ? { proxyStub: true } : {}),
-                    };
+                    // The initial handle carries settled:false at the estimate — the real
+                    // settlement status lands on governedStream.receipt after consumption.
+                    const estimatedReceipt = buildEstimatedStreamReceipt();
                     inFlightStreamCount++;
                     return { response: governedStream, receipt: estimatedReceipt };
                 }
-                // f. Compute actual cost from response usage
+                // f. Compute actual cost from response usage. A3: priced with the rate
+                // resolution captured at authorize. costFromRates clamps NaN/negative
+                // counts (A7) and floors at 1 even for 0/0 provider usage (A11).
                 let actualCost = estimatedCost;
+                let usageSource = "estimated";
                 if (response != null && typeof response === "object" && "usage" in response) {
                     const usage = response.usage;
                     if (usage != null) {
@@ -602,7 +1090,8 @@ export async function trust(client, opts) {
                         const outputTokens = usage.output_tokens ??
                             usage.completion_tokens ??
                             0;
-                        actualCost = estimateCost(model, inputTokens, outputTokens, customRates);
+                        actualCost = costFromRates(rateResolution.rates, inputTokens, outputTokens);
+                        usageSource = "provider";
                     }
                 }
                 // h. Audit the llm_call FIRST (P3-AUDIT-FAILCLOSED). The settlement-
@@ -619,6 +1108,11 @@ export async function trust(client, opts) {
                         cost: actualCost,
                         settled: true,
                         transferId,
+                        usageSource,
+                        // M2: metering provenance mirrors the receipt (A3 authorize-time scope).
+                        endpointClass: endpoint.class,
+                        costBasis: rateResolution.costBasis,
+                        rateSource: rateResolution.rateSource,
                     };
                     if (config.pii === "warn" || config.pii === "redact") {
                         const piiResult = redactPII(promptParts);
@@ -647,6 +1141,11 @@ export async function trust(client, opts) {
                 if (config.audit.failClosed && llmAuditFailed) {
                     throw new AuditDegradedError(`audit unavailable (writeFailures=${audit.getWriteFailures()}) for ${transferId}`);
                 }
+                // A2: claim the single settle outcome for this hold BEFORE money moves.
+                // Always granted here (no other terminal path runs for a non-stream call);
+                // the claim exists so a post-commit throw routes to the outer catch WITHOUT
+                // double-voiding an already-settled hold.
+                finalizeOnce("settle");
                 // Release in-flight hold and commit budget under mutex — money moves only
                 // AFTER the spend is audited. AUD-468: mark hold released before the commit
                 // so a later throw cannot double-decrement inFlightHoldTotal via the catch.
@@ -750,6 +1249,13 @@ export async function trust(client, opts) {
                     model,
                     provider: kind,
                     timestamp: new Date().toISOString(),
+                    usageSource,
+                    // M2 provenance (A6: computeMs omitted — no compute-time source here).
+                    endpoint: { class: endpoint.class, runtime: endpoint.runtime },
+                    meter: {
+                        costBasis: rateResolution.costBasis,
+                        rateSource: rateResolution.rateSource,
+                    },
                     ...(callAuditDegraded ? { auditDegraded: true } : {}),
                     // AUD-456: Flag proxy stub receipts
                     ...(proxyConn != null ? { proxyStub: true } : {}),
@@ -764,23 +1270,32 @@ export async function trust(client, opts) {
                 await releaseInFlightHold();
                 // j. Circuit breaker: record failure
                 cb.recordFailure();
-                // j2. Failure mode 15.2: LLM fails — VOID the pending hold
-                if (engine != null && !isDryRun) {
-                    try {
-                        await engine.voidPendingSpend(transferId);
-                    }
-                    catch {
-                        // Best-effort void — log and continue
-                    }
-                }
-                // j3. Proxy void
-                if (proxyConn != null && !isDryRun) {
-                    try {
-                        // AUD-460: Use the proxy's transferId for void
-                        await proxyConn.void(proxyTransferId ?? transferId);
+                // j2/j3. VOID the pending hold — but ONLY if this hold has not already
+                // claimed a settle outcome (A2). A pre-commit throw (provider/transport
+                // error, PII/policy deny, failClosed-before-commit) reaches here with the
+                // hold still PENDING → finalizeOnce("void") is granted and the ledger is
+                // voided. A post-commit throw (failClosed belt-and-suspenders) already
+                // settled the spend → the claim is refused and no spurious void is issued
+                // against an already-posted transfer.
+                if (finalizeOnce("void")) {
+                    // Failure mode 15.2: LLM fails — VOID the pending hold
+                    if (engine != null && !isDryRun) {
+                        try {
+                            await engine.voidPendingSpend(transferId);
+                        }
+                        catch {
+                            // Best-effort void — log and continue
+                        }
                     }
-                    catch {
-                        // Best-effort void
+                    // Proxy void
+                    if (proxyConn != null && !isDryRun) {
+                        try {
+                            // AUD-460: Use the proxy's transferId for void
+                            await proxyConn.void(proxyTransferId ?? transferId);
+                        }
+                        catch {
+                            // Best-effort void
+                        }
                     }
                 }
                 // k. Audit the failure
@@ -1191,13 +1706,46 @@ export async function trust(client, opts) {
  * Without this, a Google `generateContent({ model, contents })` call has an empty
  * `messages` array, so every PII/injection scan sees nothing and PII egresses.
  */
-function extractPromptParts(params, kind) {
+/**
+ * Normalize the prompt-bearing payload across providers into a flat parts array
+ * that PII/injection scanning, token estimation, redaction, and pattern hashing
+ * all consume. Exported for the A8 byte-exact regression test (kept internal to
+ * the package — not re-exported from index.ts).
+ *
+ * Branch order is load-bearing (A8): the OpenAI Responses branch is shape-
+ * discriminated (`kind === "openai"` AND no `messages` key) and placed so it can
+ * NEVER preempt the chat.completions / Anthropic `messages` branch — every
+ * chat.completions or Anthropic call carries `messages` and skips it, so existing
+ * extraction stays byte-unchanged.
+ */
+export function extractPromptParts(params, kind) {
     if (kind === "google") {
         const contents = params.contents;
         if (Array.isArray(contents))
             return contents;
         return contents != null ? [contents] : [];
     }
+    // A8: OpenAI Responses API uses `input`/`instructions`, not `messages`. Wrap the
+    // input so BOTH the token estimator (which walks a message's `content`) and the
+    // recursive PII/injection scanners (which deep-walk every string) cover it,
+    // whether `input` is a plain string, a message array, or a content-part array.
+    if (kind === "openai" && params.messages === undefined) {
+        const parts = [];
+        const input = params.input;
+        if (typeof input === "string") {
+            parts.push({ role: "user", content: input });
+        }
+        else if (Array.isArray(input)) {
+            parts.push({ role: "user", content: input });
+        }
+        else if (input != null && typeof input === "object") {
+            parts.push({ role: "user", content: [input] });
+        }
+        if (typeof params.instructions === "string") {
+            parts.push({ role: "system", content: params.instructions });
+        }
+        return parts;
+    }
     const messages = params.messages;
     const parts = Array.isArray(messages) ? [...messages] : [];
     if (typeof params.system === "string") {
@@ -1205,14 +1753,68 @@ function extractPromptParts(params, kind) {
     }
     return parts;
 }
+// ── Anthropic MessageStream helpers (Task 2, A1/A3) ──
+/**
+ * A1/A3: read provider usage off an Anthropic final Message (the `finalMessage`
+ * event payload). Each field is returned PER-FIELD: a finite, non-negative count
+ * when present, else `undefined` (so the caller can fall back to the counter it
+ * accumulated from streamEvent for THAT field, rather than zeroing it — F3).
+ * `reported` is true when at least one field carried a real number; when false the
+ * caller settles at ESTIMATE rather than voiding a billable success (A3).
+ */
+function readFinalMessageUsage(msg) {
+    if (msg != null && typeof msg === "object") {
+        const usage = msg.usage;
+        if (usage != null && typeof usage === "object") {
+            const u = usage;
+            const inTok = typeof u.input_tokens === "number" && Number.isFinite(u.input_tokens) && u.input_tokens >= 0
+                ? u.input_tokens
+                : undefined;
+            const outTok = typeof u.output_tokens === "number" &&
+                Number.isFinite(u.output_tokens) &&
+                u.output_tokens >= 0
+                ? u.output_tokens
+                : undefined;
+            if (inTok !== undefined || outTok !== undefined) {
+                return { inputTokens: inTok, outputTokens: outTok, reported: true };
+            }
+        }
+    }
+    return { inputTokens: undefined, outputTokens: undefined, reported: false };
+}
+/**
+ * A1: incremental token extraction from a raw Anthropic stream event, for the
+ * non-consuming messages.stream tap. Kept local to govern.ts (Task 2 does not
+ * touch streaming.ts); mirrors streaming.ts extractAnthropicTokens — message_start
+ * carries input_tokens, message_delta carries cumulative output_tokens.
+ */
+function extractAnthropicStreamUsage(event) {
+    if (event == null || typeof event !== "object")
+        return { inputTokens: 0, outputTokens: 0 };
+    const c = event;
+    if (c.type === "message_start" && c.message != null && typeof c.message === "object") {
+        const msg = c.message;
+        if (msg.usage != null && typeof msg.usage === "object") {
+            const usage = msg.usage;
+            const inTok = typeof usage.input_tokens === "number" ? usage.input_tokens : 0;
+            return { inputTokens: inTok > 0 ? inTok : 0, outputTokens: 0 };
+        }
+    }
+    if (c.type === "message_delta" && c.usage != null && typeof c.usage === "object") {
+        const usage = c.usage;
+        const outTok = typeof usage.output_tokens === "number" ? usage.output_tokens : 0;
+        return { inputTokens: 0, outputTokens: outTok > 0 ? outTok : 0 };
+    }
+    return { inputTokens: 0, outputTokens: 0 };
+}
 // ── TigerBeetle engine factory ──
 /** TigerBeetle codes that mean "this debit would exceed the account's credits". */
 function isTBInsufficientBalance(err) {
     if (!(err instanceof TBTransferError))
         return false;
-    return (err.code === CreateTransferError.exceeds_credits ||
-        err.code === CreateTransferError.overflows_debits ||
-        err.code === CreateTransferError.overflows_debits_pending);
+    return (err.code === CreateTransferStatus.exceeds_credits ||
+        err.code === CreateTransferStatus.overflows_debits ||
+        err.code === CreateTransferStatus.overflows_debits_pending);
 }
 /**
  * Create a balance-enforcing TrustEngine backed by a real TigerBeetle client.
@@ -1307,24 +1909,173 @@ async function createTBEngine(config, seedBudget) {
         },
     };
 }
-function buildAnthropicProxy(client, intercept, destroy, governAction) {
-    const original = client;
-    const messages = original.messages;
+/**
+ * F4: mirror the Anthropic SDK's `parseMessage` / `parseBetaMessage` transform for a
+ * governed `messages.parse()` / `beta.messages.parse()`. The SDK's `parse()` is
+ * `this.create(params).then((m) => parseMessage(m, params))` — routed through our
+ * proxy, `this.create` is the GOVERNED create, which returns a `{ response, receipt }`
+ * wrapper the SDK parser crashes on (`wrapper.content` is undefined) AFTER the spend
+ * has already settled. So the proxy runs the governed create itself and applies the
+ * transform to the raw Message here.
+ *
+ * Faithful to the SDK for the modern `parsed_output` API: each `text` block gains a
+ * NON-ENUMERABLE `parsed_output` (parsed via the caller-provided
+ * `output_config.format.parse` when structured outputs are requested, else `JSON.parse`,
+ * else null), and the message carries the first text block's `parsed_output` at the top
+ * level. Reads the deprecated beta `output_format` too, so ONE transform covers the
+ * stable and beta surfaces (stable params simply lack `output_format`). A structured
+ * parse failure throws, matching the SDK. The deprecated per-block `parsed` getter is
+ * intentionally not reproduced (superseded by `parsed_output`).
+ */
+function applyAnthropicParseTransform(message, params) {
+    if (message == null || typeof message !== "object")
+        return message;
+    const p = (params ?? {});
+    const outputConfig = p.output_config;
+    const format = (p.output_format ?? outputConfig?.format);
+    const hasSchema = format != null && typeof format === "object" && format.type === "json_schema";
+    const parseText = (text) => {
+        if (!hasSchema)
+            return null;
+        try {
+            return typeof format?.parse === "function"
+                ? format.parse(text)
+                : JSON.parse(text);
+        }
+        catch (err) {
+            throw new Error(`Failed to parse structured output: ${err}`);
+        }
+    };
+    const msg = message;
+    let firstParsed = null;
+    const content = Array.isArray(msg.content)
+        ? msg.content.map((block) => {
+            if (block != null &&
+                typeof block === "object" &&
+                block.type === "text") {
+                const parsed = parseText(String(block.text ?? ""));
+                if (firstParsed === null)
+                    firstParsed = parsed;
+                const parsedBlock = { ...block };
+                Object.defineProperty(parsedBlock, "parsed_output", {
+                    value: parsed,
+                    enumerable: false,
+                });
+                return parsedBlock;
+            }
+            return block;
+        })
+        : msg.content;
+    return { ...msg, content, parsed_output: firstParsed };
+}
+/**
+ * A1/A5: build a governed proxy over an Anthropic `messages` resource (stable or
+ * beta — both share the create/stream shape). `create` routes through
+ * interceptCall (surface "create"). `stream`, when present as a function (A5
+ * feature-detect), routes through interceptCall (surface "stream-helper") bound to
+ * the RAW `messages` target (A5) so the helper's internal
+ * `messages.create({stream:true}).withResponse()` runs against the un-proxied
+ * create and never re-enters the governed create trap. The governed `stream` is
+ * async (it authorizes before forwarding), so callers `await` the handle, then use
+ * `.on()` / `.finalMessage()` / `.abort()` / `.receipt`. `parse`, when present (A5
+ * feature-detect), routes its create through governance and applies the SDK parse
+ * transform (F4). Everything else (countTokens, batches, …) falls through to
+ * Reflect.get untouched.
+ */
+function buildAnthropicMessagesProxy(messages, intercept) {
     const originalCreate = messages.create;
-    // Proxy on the messages object: intercept `create`
-    const messagesProxy = new Proxy(messages, {
+    // A5: feature-detect `stream` as a FUNCTION before wrapping it — an older SDK
+    // without the helper leaves it absent and it stays a raw pass-through.
+    const originalStream = typeof messages.stream === "function"
+        ? messages.stream
+        : undefined;
+    // A5/F4: feature-detect `parse` the same way — absent on older SDKs.
+    const hasParse = typeof messages.parse === "function";
+    return new Proxy(messages, {
         get(target, prop, receiver) {
             if (prop === "create") {
                 return (...args) => intercept(originalCreate, target, args);
             }
+            if (prop === "stream" && originalStream !== undefined) {
+                return async (...args) => {
+                    const { response } = await intercept(originalStream, target, args, "stream-helper");
+                    return response;
+                };
+            }
+            if (prop === "parse" && hasParse) {
+                // F4: run the governed create ONCE, then apply the SDK parse transform to
+                // the settled Message and hand back the parsed Message (SDK-shaped) with
+                // the settlement receipt attached.
+                return async (...args) => {
+                    const { response, receipt } = await intercept(originalCreate, target, args);
+                    const parsed = applyAnthropicParseTransform(response, args[0]);
+                    if (parsed != null && typeof parsed === "object") {
+                        try {
+                            Object.defineProperty(parsed, "receipt", {
+                                value: receipt,
+                                enumerable: true,
+                                configurable: true,
+                            });
+                        }
+                        catch {
+                            // non-extensible parsed object — skip
+                        }
+                    }
+                    return parsed;
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
+/**
+ * A5: build a governed proxy over `client.beta` when it exposes a create-shaped
+ * `beta.messages`. Returns undefined on any miss (no beta, non-object beta, a beta
+ * getter that throws, or a beta.messages without a create function) so the caller
+ * falls back to raw Reflect.get and NOTHING throws at wrap time (peerDep-range
+ * compatibility). beta.models / beta.files / beta.messages.batches stay documented
+ * pass-throughs — create, stream, and parse on beta.messages are governed.
+ */
+function buildAnthropicBetaProxy(original, intercept) {
+    let beta;
+    try {
+        beta = original.beta;
+    }
+    catch {
+        return undefined;
+    }
+    if (beta == null || typeof beta !== "object")
+        return undefined;
+    const betaObj = beta;
+    const betaMessages = betaObj.messages;
+    if (betaMessages == null ||
+        typeof betaMessages !== "object" ||
+        typeof betaMessages.create !== "function") {
+        return undefined;
+    }
+    const betaMessagesProxy = buildAnthropicMessagesProxy(betaMessages, intercept);
+    return new Proxy(betaObj, {
+        get(target, prop, receiver) {
+            if (prop === "messages")
+                return betaMessagesProxy;
             return Reflect.get(target, prop, receiver);
         },
     });
-    // Proxy on the client: intercept `messages` to return our proxy, add `destroy`
+}
+function buildAnthropicProxy(client, intercept, destroy, governAction) {
+    const original = client;
+    const messages = original.messages;
+    // Stable messages: governed `create` + (feature-detected) `stream`.
+    const messagesProxy = buildAnthropicMessagesProxy(messages, intercept);
+    // beta.messages.create/stream/parse — governed identically when present (A5); a
+    // client without `beta` yields undefined and `beta` stays a raw pass-through.
+    const betaProxy = buildAnthropicBetaProxy(original, intercept);
     const clientProxy = new Proxy(original, {
         get(target, prop, receiver) {
             if (prop === "messages")
                 return messagesProxy;
+            if (prop === "beta" && betaProxy !== undefined)
+                return betaProxy;
             if (prop === "destroy")
                 return destroy;
             if (prop === "governAction")
@@ -1334,6 +2085,42 @@ function buildAnthropicProxy(client, intercept, destroy, governAction) {
     });
     return clientProxy;
 }
+/**
+ * Task 3 (A5): build a governed proxy over `client.responses` when the OpenAI SDK
+ * exposes a create-shaped Responses API. Returns undefined on any miss (no
+ * `responses`, non-object `responses`, a getter that throws, or a `responses`
+ * without a `create` function) so the caller falls back to raw Reflect.get and
+ * NOTHING throws at wrap time — the peer range (`openai >=4.70.0`) predates the
+ * Responses API (~4.87), so older clients must keep working untouched.
+ *
+ * `responses.create` routes through interceptCall on the SEPARATE "openai-responses"
+ * surface (A6: no stream_options.include_usage injection; A7: streaming still flows
+ * through the generic createGovernedStream path). `this` binds to the RAW `responses`
+ * object. Everything else (retrieve / cancel / delete / …) stays a pass-through.
+ */
+function buildOpenAIResponsesProxy(original, intercept) {
+    let responses;
+    try {
+        responses = original.responses;
+    }
+    catch {
+        return undefined;
+    }
+    if (responses == null || typeof responses !== "object")
+        return undefined;
+    const responsesObj = responses;
+    if (typeof responsesObj.create !== "function")
+        return undefined;
+    const originalCreate = responsesObj.create;
+    return new Proxy(responsesObj, {
+        get(target, prop, receiver) {
+            if (prop === "create") {
+                return (...args) => intercept(originalCreate, target, args, "openai-responses");
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
 function buildOpenAIProxy(client, intercept, destroy, governAction) {
     const original = client;
     const chat = original.chat;
@@ -1354,10 +2141,15 @@ function buildOpenAIProxy(client, intercept, destroy, governAction) {
             return Reflect.get(target, prop, receiver);
         },
     });
+    // responses.create — governed when present (A5); an older client without the
+    // Responses API yields undefined and `responses` stays a raw pass-through.
+    const responsesProxy = buildOpenAIResponsesProxy(original, intercept);
     const clientProxy = new Proxy(original, {
         get(target, prop, receiver) {
             if (prop === "chat")
                 return chatProxy;
+            if (prop === "responses" && responsesProxy !== undefined)
+                return responsesProxy;
             if (prop === "destroy")
                 return destroy;
             if (prop === "governAction")