usertrust 1.3.0 → 1.5.0

package/dist/govern.js

@@ -26,17 +26,18 @@
  * await client.destroy();
  * ```
  */
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync } from "node:fs";
-import { readFile, rename, writeFile } from "node:fs/promises";
+import { readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { CreateTransferError } from "tigerbeetle-node";
 import { createAuditWriter } from "./audit/chain.js";
 import { writeReceipt } from "./audit/rotation.js";
-import { detectClientKind } from "./detect.js";
-import { TrustTBClient, XFER_SPEND } from "./ledger/client.js";
-import { estimateCost, estimateInputTokens } from "./ledger/pricing.js";
+import { classifyEndpoint, detectClientKind } from "./detect.js";
+import { TBTransferError, TrustTBClient, XFER_SPEND } from "./ledger/client.js";
+import { costFromRates, estimateInputTokens, resolveRates, warnUnknownModel, } from "./ledger/pricing.js";
 import { recordPattern } from "./memory/patterns.js";
-import { DEFAULT_RULES } from "./policy/default-rules.js";
+import { DEFAULT_RULES, mergePolicies } from "./policy/default-rules.js";
 import { evaluatePolicy, loadPolicies } from "./policy/gate.js";
 import { detectInjection } from "./policy/injection.js";
 import { detectPII, redactPII } from "./policy/pii.js";
@@ -45,7 +46,7 @@ import { DEFAULT_BUDGET, VAULT_DIR } from "./shared/constants.js";
 /** Base URL for receipt verification links (used in proxy mode). */
 const VERIFY_URL_BASE = "https://verify.usertrust.dev";
 import { createAnomalyDetector } from "./anomaly/detector.js";
-import { AnomalyError, LedgerUnavailableError, PolicyDeniedError } from "./shared/errors.js";
+import { AnomalyError, AuditDegradedError, InsufficientBalanceError, LedgerUnavailableError, PolicyDeniedError, } from "./shared/errors.js";
 import { trustId } from "./shared/ids.js";
 import { TrustConfigSchema } from "./shared/types.js";
 import { createGovernedStream } from "./streaming.js";
@@ -65,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 {
@@ -88,22 +169,36 @@ async function loadSpendLedger(vaultBase) {
 async function persistSpendLedger(vaultBase, budgetSpent) {
     const dir = join(vaultBase, VAULT_DIR);
     const ledgerPath = join(dir, "spend-ledger.json");
-    const tmpPath = join(dir, "spend-ledger.json.tmp");
-    const data = {
-        budgetSpent,
-        updatedAt: new Date().toISOString(),
-    };
+    // AUD-457 hardening (RECON #4): UNIQUE tmp path per write. A fixed
+    // `spend-ledger.json.tmp` lets two concurrent writers clobber each other's
+    // staging file, so a half-written record can be renamed into place. A pid +
+    // uuid suffix isolates every writer's staging file.
+    const tmpPath = join(dir, `spend-ledger.json.${process.pid}.${randomUUID()}.tmp`);
     try {
         // Ensure vault dir exists
         if (!existsSync(dir)) {
             mkdirSync(dir, { recursive: true });
         }
-        // Atomic write: write tmp then rename
+        // MONOTONIC guard (RECON #4): cumulative spend must never regress on disk.
+        // A stale/racing writer carrying a lower budgetSpent must not "un-spend"
+        // money that another writer already recorded. Skip the write if the
+        // persisted value is already >= ours.
+        const existing = await loadSpendLedger(vaultBase);
+        if (existing > budgetSpent) {
+            return;
+        }
+        const data = {
+            budgetSpent,
+            updatedAt: new Date().toISOString(),
+        };
+        // Atomic write: write UNIQUE tmp then rename over the target.
         await writeFile(tmpPath, JSON.stringify(data), "utf-8");
         await rename(tmpPath, ledgerPath);
     }
     catch {
-        // Best-effort — do not fail the LLM call over ledger persistence
+        // Best-effort — do not fail the LLM call over ledger persistence. Clean up
+        // our unique staging file if the rename never happened.
+        await unlink(tmpPath).catch(() => { });
     }
 }
 // ── trust() ──
@@ -124,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.
@@ -134,7 +228,12 @@ export async function trust(client, opts) {
     const audit = (isTestEnv ? opts?._audit : undefined) ?? createAuditWriter(vaultPath);
     const policiesPath = join(vaultPath, VAULT_DIR, config.policies);
     const loadedRules = existsSync(policiesPath) ? loadPolicies(policiesPath) : [];
-    const policyRules = loadedRules.length > 0 ? loadedRules : DEFAULT_RULES;
+    // P1-CUSTOM-POLICY-REPLACES (RECON #2): platform DEFAULT_RULES are ALWAYS
+    // enforced. mergePolicies is a safe concat — a custom policy file can only ADD
+    // deny/warn rules, never remove the budget/overshoot/exhausted guarantees. The
+    // gate is deny-wins with no "allow" effect, so appended user rules cannot weaken
+    // a default deny.
+    const policyRules = mergePolicies(DEFAULT_RULES, loadedRules);
     const breaker = new CircuitBreakerRegistry({
         failureThreshold: config.circuitBreaker.failureThreshold,
         resetTimeoutMs: config.circuitBreaker.resetTimeout,
@@ -147,6 +246,9 @@ export async function trust(client, opts) {
     // AUD-456: proxyConn is always null now — proxy mode throws above.
     // Cast keeps dead code paths type-safe for future re-enablement.
     const proxyConn = null;
+    // AUD-457: restore cumulative spend from disk BEFORE building the engine so the
+    // enforcing holding account can be seeded with the REMAINING budget.
+    let budgetSpent = await loadSpendLedger(vaultBase);
     // 4. Engine (injected for tests, real TB client in production, null in dry-run/proxy)
     // AUD-470: _engine injection only accepted in test environments
     let engine;
@@ -155,7 +257,9 @@ export async function trust(client, opts) {
     }
     else if (!isDryRun && proxyConn == null) {
         try {
-            engine = await createTBEngine(config);
+            // P1-LEDGER-ENFORCE (RECON #3): seed the enforcing holding account with the
+            // remaining budget so TigerBeetle atomically REJECTS an over-budget hold.
+            engine = await createTBEngine(config, Math.max(0, config.budget - budgetSpent));
         }
         catch (err) {
             throw new LedgerUnavailableError(err instanceof Error ? err.message : String(err));
@@ -164,18 +268,43 @@ 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;
-    let budgetSpent = await loadSpendLedger(vaultBase); // AUD-457: restore from disk
     const budgetMutex = new AsyncMutex(); // AUD-453: serialise budget-check + hold
     let inFlightCount = 0; // AUD-462: track in-flight calls for graceful destroy
     let inFlightStreamCount = 0; // AUD-462: track in-flight streams (consumed after interceptCall returns)
     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) {
         if (destroyed) {
@@ -186,17 +315,31 @@ export async function trust(client, opts) {
         try {
             const params = (args[0] ?? {});
             const model = params.model ?? "unknown";
-            const messages = params.messages ?? [];
+            // P3-PROVIDER-BLINDSPOT: normalize the prompt-bearing payload across
+            // providers (Anthropic/OpenAI `messages` + `system`, Google `contents`) so
+            // PII/injection scanning, token estimation, redaction, and pattern hashing
+            // all see the actual prompt — not an empty `messages` array on Google calls.
+            const promptParts = extractPromptParts(params, kind);
             // Per-call audit degradation flag (not sticky across calls)
             let callAuditDegraded = false;
+            // P3-PII-REDACT-EGRESS: `forwardArgs` is what we actually send to the
+            // provider. In redact mode it becomes a redacted deep clone so PII never
+            // egresses; block mode throws before any egress. Default: forward verbatim.
+            let forwardArgs = args;
             // 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(messages);
+            const estimatedInputTokens = estimateInputTokens(promptParts);
             const maxOutputTokens = params.max_tokens ?? 4096;
-            const estimatedCost = estimateCost(model, estimatedInputTokens, maxOutputTokens, customRates);
+            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.
@@ -217,28 +360,42 @@ export async function trust(client, opts) {
             }
             try {
                 // c. Policy gate
+                // P1-PARAM-SHADOW: caller `params` are spread FIRST so trusted
+                // governance fields (tier/estimated_cost/budget_remaining/
+                // budget_remaining_after) CANNOT be shadowed by request-supplied keys.
+                // P1-BUDGET-PREFLIGHT: budget_remaining_after is the derived field the
+                // single-field gate compares against zero to deny a single overshooting
+                // call (the `block-budget-overshoot` default rule).
                 const policyResult = evaluatePolicy(policyRules, {
+                    ...params,
                     model,
                     tier: config.tier,
                     estimated_cost: estimatedCost,
                     budget_remaining: config.budget - budgetSpent - inFlightHoldTotal,
-                    ...params,
+                    budget_remaining_after: config.budget - budgetSpent - inFlightHoldTotal - estimatedCost,
                 });
                 if (policyResult.decision === "deny") {
                     const reason = policyResult.reasons.length > 0 ? policyResult.reasons.join("; ") : "Policy denied";
                     throw new PolicyDeniedError(reason);
                 }
-                // d. PII check
+                // d. PII check + redact-egress
                 if (config.pii !== "off") {
-                    const piiResult = detectPII(messages);
+                    const piiResult = detectPII(promptParts);
                     if (piiResult.found && config.pii === "block") {
+                        // block mode: throw BEFORE any egress.
                         throw new PolicyDeniedError(`PII detected: ${piiResult.types.join(", ")}`);
                     }
-                    // "warn" and "redact" modes: continue (redact is not implemented at SDK level)
+                    if (config.pii === "redact" && piiResult.found) {
+                        // redact mode: forward a redacted DEEP CLONE so PII never egresses.
+                        // redactPII is pure — the caller's original object is never mutated.
+                        const redactedBody = redactPII(params).data;
+                        forwardArgs = [redactedBody, ...args.slice(1)];
+                    }
+                    // "warn" mode: continue, no transform (audit copy is redacted later).
                 }
                 // d2. Injection detection
                 if (config.injection !== "off") {
-                    const injectionResult = detectInjection(messages);
+                    const injectionResult = detectInjection(promptParts);
                     if (injectionResult.detected) {
                         if (config.injection === "block") {
                             throw new PolicyDeniedError(`Prompt injection detected: ${injectionResult.patterns.join(", ")}`);
@@ -285,7 +442,16 @@ export async function trust(client, opts) {
                         });
                     }
                     catch (holdErr) {
-                        // Ledger unreachable — do NOT forward to provider
+                        // P1-LEDGER-ENFORCE: an over-budget reservation is rejected
+                        // atomically by the ledger. Surface it as a hard budget DENY —
+                        // NOT as "ledger unavailable" (which would misreport a budget cap
+                        // as an outage). This throws out of the budget-section try, runs
+                        // its finally (releases the budget lock), and propagates without
+                        // a hold to void — exactly mirroring the policy-deny control flow.
+                        if (holdErr instanceof InsufficientBalanceError) {
+                            throw holdErr;
+                        }
+                        // Genuine ledger outage — do NOT forward to provider.
                         throw new LedgerUnavailableError(holdErr instanceof Error ? holdErr.message : String(holdErr));
                     }
                 }
@@ -297,10 +463,41 @@ export async function trust(client, opts) {
                 // AUD-453: Release lock after budget check + hold are complete
                 releaseBudgetLock();
             }
-            // e. Forward to original SDK
+            // 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).
+            let preInjectionArgs = null;
+            if (kind === "openai" && 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, args);
+                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);
+                }
                 // e2. Streaming detection: if response is an async iterable, wrap with
                 // token accumulation. Settlement and audit happen when the stream ends.
                 if (response != null &&
@@ -308,11 +505,13 @@ export async function trust(client, opts) {
                     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
+                        // 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 = estimateCost(model, completion.usage.inputTokens, completion.usage.outputTokens, customRates);
+                            streamCost = costFromRates(rateResolution.rates, completion.usage.inputTokens, completion.usage.outputTokens);
                             usageSource = "provider";
                         }
                         else {
@@ -366,7 +565,8 @@ export async function trust(client, opts) {
                         }
                         else if (engine != null && !isDryRun) {
                             try {
-                                await engine.postPendingSpend(transferId);
+                                // Post the ACTUAL consumed cost (RECON #3).
+                                await engine.postPendingSpend(transferId, streamCost);
                             }
                             catch (postErr) {
                                 settled = false;
@@ -398,9 +598,13 @@ export async function trust(client, opts) {
                                 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(messages);
+                                const piiResult = redactPII(promptParts);
                                 if (piiResult.detection.found) {
                                     auditEventData.piiDetected = piiResult.detection.types;
                                     auditEventData.piiPaths = piiResult.detection.paths;
@@ -416,6 +620,13 @@ export async function trust(client, opts) {
                         catch {
                             callAuditDegraded = true;
                         }
+                        // 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,
@@ -429,6 +640,12 @@ export async function trust(client, opts) {
                             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 } : {}),
@@ -482,6 +699,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) {
@@ -520,6 +741,12 @@ export async function trust(client, opts) {
                         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 } : {}),
@@ -527,8 +754,11 @@ export async function trust(client, opts) {
                     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) {
@@ -538,13 +768,60 @@ 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";
                     }
                 }
-                // Release in-flight hold and commit budget under mutex
-                // AUD-468: Mark hold released before the commit so that any
-                // throw in the post-commit window (audit/persist/etc.) cannot
-                // double-decrement inFlightHoldTotal via the outer catch.
+                // h. Audit the llm_call FIRST (P3-AUDIT-FAILCLOSED). The settlement-
+                // defining event is written BEFORE the irreversible budget commit and
+                // POST, so a fail-closed deployment never settles an unaudited spend.
+                // The event carries settled:true optimistically; a later POST failure
+                // appends the settlement_ambiguous correction and flips receipt.settled.
+                const syntheticHash = createHash("sha256").update(transferId).digest("hex");
+                let auditHash = syntheticHash;
+                let llmAuditFailed = false;
+                try {
+                    const auditData = {
+                        model,
+                        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);
+                        if (piiResult.detection.found) {
+                            auditData.piiDetected = piiResult.detection.types;
+                            auditData.piiPaths = piiResult.detection.paths;
+                        }
+                    }
+                    const auditEvent = await audit.appendEvent({
+                        kind: "llm_call",
+                        actor: "local",
+                        data: auditData,
+                    });
+                    auditHash = auditEvent.hash;
+                }
+                catch {
+                    // Failure mode 15.3: Audit degraded — mark + warn.
+                    llmAuditFailed = true;
+                    callAuditDegraded = true;
+                    process.stderr.write(`[usertrust] audit degraded: failed to write llm_call event for ${transferId}\n`);
+                }
+                // P3-AUDIT-FAILCLOSED: under failClosed a failed llm_call audit ABORTS the
+                // call before any money moves. Throwing here routes to the outer catch,
+                // which VOIDs the hold (once) and never POSTs — the internal ledger holds
+                // no unaudited spend, and the caller is told the call failed.
+                if (config.audit.failClosed && llmAuditFailed) {
+                    throw new AuditDegradedError(`audit unavailable (writeFailures=${audit.getWriteFailures()}) for ${transferId}`);
+                }
+                // 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.
                 if (holdActive) {
                     holdActive = false;
                     const releaseLock = await budgetMutex.acquire();
@@ -559,7 +836,8 @@ export async function trust(client, opts) {
                 // g2. Failure mode 15.1: POST fails after LLM success
                 if (engine != null && !isDryRun) {
                     try {
-                        await engine.postPendingSpend(transferId);
+                        // Post the ACTUAL consumed cost (RECON #3).
+                        await engine.postPendingSpend(transferId, actualCost);
                     }
                     catch (postErr) {
                         // POST failed — LLM call succeeded but settlement is ambiguous
@@ -607,34 +885,11 @@ export async function trust(client, opts) {
                         });
                     }
                 }
-                // h. Audit event — failure mode 15.3: audit write failure
-                const syntheticHash = createHash("sha256").update(transferId).digest("hex");
-                let auditHash = syntheticHash;
-                try {
-                    const auditData = {
-                        model,
-                        cost: actualCost,
-                        settled,
-                        transferId,
-                    };
-                    if (config.pii === "warn" || config.pii === "redact") {
-                        const piiResult = redactPII(messages);
-                        if (piiResult.detection.found) {
-                            auditData.piiDetected = piiResult.detection.types;
-                            auditData.piiPaths = piiResult.detection.paths;
-                        }
-                    }
-                    const auditEvent = await audit.appendEvent({
-                        kind: "llm_call",
-                        actor: "local",
-                        data: auditData,
-                    });
-                    auditHash = auditEvent.hash;
-                }
-                catch {
-                    // Failure mode 15.3: Audit degraded — do not fail the response
-                    callAuditDegraded = true;
-                    process.stderr.write(`[usertrust] audit degraded: failed to write llm_call event for ${transferId}\n`);
+                // P3-AUDIT-FAILCLOSED belt-and-suspenders: if ANY audit write during this
+                // call degraded the writer (including best-effort advisory writes), refuse
+                // to report success under failClosed so the caller cannot silently proceed.
+                if (config.audit.failClosed && (callAuditDegraded || audit.isDegraded())) {
+                    throw new AuditDegradedError(`audit unavailable (writeFailures=${audit.getWriteFailures()}) for ${transferId}`);
                 }
                 // i. Daily-rotated audit receipt (non-blocking)
                 if (config.audit.rotation !== "none") {
@@ -647,7 +902,7 @@ export async function trust(client, opts) {
                 }
                 // i2. Pattern memory
                 if (config.patterns.enabled) {
-                    const promptHash = createHash("sha256").update(JSON.stringify(messages)).digest("hex");
+                    const promptHash = createHash("sha256").update(JSON.stringify(promptParts)).digest("hex");
                     await recordPattern({
                         promptHash,
                         model,
@@ -667,6 +922,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 } : {}),
@@ -718,7 +980,7 @@ export async function trust(client, opts) {
                 });
                 // l. Pattern memory: record failure
                 if (config.patterns.enabled) {
-                    const promptHash = createHash("sha256").update(JSON.stringify(messages)).digest("hex");
+                    const promptHash = createHash("sha256").update(JSON.stringify(promptParts)).digest("hex");
                     await recordPattern({
                         promptHash,
                         model,
@@ -756,13 +1018,17 @@ export async function trust(client, opts) {
             let proxyTransferId;
             try {
                 // c. Policy gate — action fields available in context
-                // AUD-467: Caller params spread FIRST so governance fields cannot be shadowed
+                // AUD-467: Caller params spread FIRST so governance fields cannot be shadowed.
+                // P1-BUDGET-PREFLIGHT: budget_remaining_after is the derived field the
+                // block-budget-overshoot default rule compares against zero (a HARD rule
+                // that fails CLOSED if the governor omits it — so it MUST be supplied).
                 const policyResult = evaluatePolicy(policyRules, {
                     ...(action.params ?? {}),
                     action_kind: action.kind,
                     action_name: action.name,
                     estimated_cost: action.cost,
                     budget_remaining: config.budget - budgetSpent - inFlightHoldTotal,
+                    budget_remaining_after: config.budget - budgetSpent - inFlightHoldTotal - action.cost,
                     tier: config.tier,
                 });
                 if (policyResult.decision === "deny") {
@@ -820,6 +1086,11 @@ export async function trust(client, opts) {
                         });
                     }
                     catch (holdErr) {
+                        // P1-LEDGER-ENFORCE: over-budget reservation → hard budget DENY,
+                        // not a ledger-outage misreport.
+                        if (holdErr instanceof InsufficientBalanceError) {
+                            throw holdErr;
+                        }
                         throw new LedgerUnavailableError(holdErr instanceof Error ? holdErr.message : String(holdErr));
                     }
                 }
@@ -844,7 +1115,52 @@ export async function trust(client, opts) {
             }
             try {
                 const result = await execute();
-                // Release in-flight hold and commit budget under mutex
+                // i. Prepare params for audit — redact PII if configured.
+                let auditParams;
+                if (action.params != null) {
+                    if (config.pii === "warn" || config.pii === "redact") {
+                        const redacted = redactPII(action.params);
+                        auditParams = redacted.data;
+                    }
+                    else {
+                        auditParams = action.params;
+                    }
+                }
+                // i2. Audit the action FIRST (P3-AUDIT-FAILCLOSED). The settlement-
+                // defining event precedes the budget commit + POST, so a fail-closed
+                // deployment never settles an unaudited action. settled:true is
+                // optimistic; a later POST failure appends settlement_ambiguous.
+                const syntheticHash = createHash("sha256").update(transferId).digest("hex");
+                let auditHash = syntheticHash;
+                let actionAuditFailed = false;
+                try {
+                    const auditEvent = await audit.appendEvent({
+                        kind: action.kind,
+                        actor,
+                        data: {
+                            actionName: action.name,
+                            cost: action.cost,
+                            settled: true,
+                            transferId,
+                            ...(auditParams != null ? { params: auditParams } : {}),
+                        },
+                    });
+                    auditHash = auditEvent.hash;
+                }
+                catch {
+                    // Failure mode 15.3: Audit degraded — mark + warn.
+                    actionAuditFailed = true;
+                    callAuditDegraded = true;
+                    process.stderr.write(`[usertrust] audit degraded: failed to write ${action.kind} event for ${transferId}\n`);
+                }
+                // P3-AUDIT-FAILCLOSED: under failClosed a failed action audit ABORTS the
+                // call before any money moves — the outer catch VOIDs the hold (once) and
+                // never POSTs.
+                if (config.audit.failClosed && actionAuditFailed) {
+                    throw new AuditDegradedError(`audit unavailable (writeFailures=${audit.getWriteFailures()}) for ${transferId}`);
+                }
+                // Release in-flight hold and commit budget under mutex — money moves only
+                // AFTER the action is audited.
                 await releaseHoldAndCommit(action.cost);
                 await persistSpendLedger(vaultBase, budgetSpent);
                 // g. Circuit breaker: record success
@@ -853,7 +1169,8 @@ export async function trust(client, opts) {
                 let settled = true;
                 if (engine != null && !isDryRun) {
                     try {
-                        await engine.postPendingSpend(transferId);
+                        // Post the ACTUAL cost (RECON #3).
+                        await engine.postPendingSpend(transferId, action.cost);
                     }
                     catch (postErr) {
                         settled = false;
@@ -901,38 +1218,10 @@ export async function trust(client, opts) {
                         });
                     }
                 }
-                // i. Prepare params for audit — redact PII if configured
-                let auditParams;
-                if (action.params != null) {
-                    if (config.pii === "warn" || config.pii === "redact") {
-                        const redacted = redactPII(action.params);
-                        auditParams = redacted.data;
-                    }
-                    else {
-                        auditParams = action.params;
-                    }
-                }
-                // i2. Audit event
-                const syntheticHash = createHash("sha256").update(transferId).digest("hex");
-                let auditHash = syntheticHash;
-                try {
-                    const auditEvent = await audit.appendEvent({
-                        kind: action.kind,
-                        actor,
-                        data: {
-                            actionName: action.name,
-                            cost: action.cost,
-                            settled,
-                            transferId,
-                            ...(auditParams != null ? { params: auditParams } : {}),
-                        },
-                    });
-                    auditHash = auditEvent.hash;
-                }
-                catch {
-                    // Failure mode 15.3: Audit degraded — do not fail the response
-                    callAuditDegraded = true;
-                    process.stderr.write(`[usertrust] audit degraded: failed to write ${action.kind} event for ${transferId}\n`);
+                // P3-AUDIT-FAILCLOSED belt-and-suspenders: refuse to report success if any
+                // audit write during this call degraded the writer under failClosed.
+                if (config.audit.failClosed && (callAuditDegraded || audit.isDegraded())) {
+                    throw new AuditDegradedError(`audit unavailable (writeFailures=${audit.getWriteFailures()}) for ${transferId}`);
                 }
                 // j. Daily-rotated receipt
                 if (config.audit.rotation !== "none") {
@@ -1071,44 +1360,103 @@ export async function trust(client, opts) {
     process.on("beforeExit", beforeExitHandler);
     return governedClient;
 }
+// ── Provider-aware prompt extraction (P3-PROVIDER-BLINDSPOT) ──
+/**
+ * Normalize the prompt-bearing payload across providers so PII/injection scanning
+ * and token estimation cover ALL shapes, not just Anthropic/OpenAI `messages`:
+ *   - Anthropic/OpenAI: `params.messages` (+ Anthropic top-level `system` string)
+ *   - Google:           `params.contents` (the prompt lives here, not `messages`)
+ *
+ * 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) {
+    if (kind === "google") {
+        const contents = params.contents;
+        if (Array.isArray(contents))
+            return contents;
+        return contents != null ? [contents] : [];
+    }
+    const messages = params.messages;
+    const parts = Array.isArray(messages) ? [...messages] : [];
+    if (typeof params.system === "string") {
+        parts.push({ role: "system", content: params.system });
+    }
+    return parts;
+}
 // ── 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);
+}
 /**
- * Create a TrustEngine backed by a real TigerBeetle client.
- * Uses a simplified two-phase interface: pending transfers are created
- * directly against the TB client using escrow-style debit/credit accounts.
+ * Create a balance-enforcing TrustEngine backed by a real TigerBeetle client.
+ *
+ * P1-LEDGER-ENFORCE: the holding account is created with
+ * `debits_must_not_exceed_credits` and FUNDED with `seedBudget` usertokens, so a
+ * pending debit (hold) whose cumulative amount would exceed the remaining budget
+ * is REJECTED atomically by TigerBeetle. That rejection is surfaced as an
+ * {@link InsufficientBalanceError}, which the governor re-throws as a hard budget
+ * DENY (never as a ledger outage). The prior escrow account had no enforcing flag
+ * and no funding, so `spendPending` could never reject an over-budget hold.
+ *
+ * NOTE (cross-domain): RECON #3 designates `createLedgerEngine` /
+ * `createFundedBudgetWallet` (LEDGER-owned, in `ledger/engine.ts`) as the eventual
+ * home for this factory. Those symbols do not yet exist on disk, so this
+ * GOVERN-local factory implements the same funded-enforcing contract using the
+ * existing `TrustTBClient` primitives. When LEDGER ships `createLedgerEngine`,
+ * this factory is a drop-in replacement (identical `TrustEngine` shape).
  */
-async function createTBEngine(config) {
+async function createTBEngine(config, seedBudget) {
     const tbAddresses = config.tigerbeetle.addresses;
     const tbClusterId = BigInt(config.tigerbeetle.clusterId);
     const tbClient = new TrustTBClient({
         addresses: tbAddresses,
         clusterId: tbClusterId,
     });
-    // Initialize treasury and escrow accounts
+    // Treasury (unconstrained) funds a per-session enforcing holding wallet.
     await tbClient.createTreasury();
-    await tbClient.ensureEscrowAccount("trust:escrow");
+    const treasury = tbClient.getTreasuryId();
+    // Enforcing holding wallet (debits_must_not_exceed_credits), funded with the
+    // remaining session budget so cumulative pending debits cannot exceed it.
+    // A FRESH account id per session prevents double-funding a deterministic
+    // account across restarts (which would inflate the TB-enforced budget).
+    const holdingId = await tbClient.createFundedBudgetWallet(seedBudget);
     // Pending transfer ID mapping (trustId string -> TB bigint)
     const pendingMap = new Map();
     return {
         async spendPending(params) {
-            const treasury = tbClient.getTreasuryId();
-            // Use a deterministic escrow account for SDK-local holds
-            const escrowId = TrustTBClient.deriveAccountId("trust:escrow");
-            const tbTransferId = await tbClient.createPendingTransfer({
-                debitAccountId: escrowId,
-                creditAccountId: treasury,
-                amount: params.amount,
-                code: XFER_SPEND,
-            });
-            pendingMap.set(params.transferId, tbTransferId);
-            return { transferId: params.transferId };
+            try {
+                const tbTransferId = await tbClient.createPendingTransfer({
+                    debitAccountId: holdingId,
+                    creditAccountId: treasury,
+                    amount: params.amount,
+                    code: XFER_SPEND,
+                });
+                pendingMap.set(params.transferId, tbTransferId);
+                return { transferId: params.transferId };
+            }
+            catch (err) {
+                // Over-budget reservation → TB rejects the pending debit. Surface as a
+                // budget error so the governor reports a hard DENY, not an outage.
+                if (isTBInsufficientBalance(err)) {
+                    throw new InsufficientBalanceError("trust:hold", params.amount, seedBudget);
+                }
+                throw err;
+            }
         },
-        async postPendingSpend(transferId) {
+        async postPendingSpend(transferId, actualAmount) {
             const tbId = pendingMap.get(transferId);
             if (tbId === undefined) {
                 throw new Error(`No pending transfer found for ${transferId}`);
             }
-            await tbClient.postTransfer(tbId);
+            // Post the ACTUAL consumed amount (≤ the reserved estimate); omitting it
+            // posts the full pending amount.
+            await tbClient.postTransfer(tbId, actualAmount);
             pendingMap.delete(transferId);
         },
         async voidPendingSpend(transferId) {