usertrust 1.4.0 → 1.5.0

package/dist/detect.js

@@ -47,4 +47,128 @@ export function detectClientKind(client) {
     }
     throw new Error("Unsupported LLM client: could not detect Anthropic, OpenAI, or Google SDK");
 }
+// ── Endpoint classification (M2 local-model governance) ──
+// Compared against normalizeHostname(url.hostname) — the WHATWG-serialized,
+// bracket-stripped form. `::ffff:7f00:1` is how Node's URL serializes the
+// IPv4-mapped IPv6 loopback `::ffff:127.0.0.1` (the last 32 bits render as hex,
+// never dotted-quad), so the map entry MUST be the serialized form to match.
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "::ffff:7f00:1"]);
+/** Best-effort runtime hint by conventional default port (metadata only). */
+const RUNTIME_BY_PORT = {
+    "11434": "ollama",
+    "1234": "lmstudio",
+    "8000": "vllm",
+};
+const CLOUD_DEFAULT = { class: "cloud", runtime: "unknown" };
+function parseUrl(value) {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Normalize a URL hostname for comparison: lowercase, IPv6 brackets stripped
+ * (Node's WHATWG URL keeps brackets in `hostname` for IPv6 literals).
+ */
+function normalizeHostname(hostname) {
+    const lower = hostname.toLowerCase();
+    if (lower.startsWith("[") && lower.endsWith("]"))
+        return lower.slice(1, -1);
+    return lower;
+}
+/**
+ * Match a parsed baseURL against one config.endpoints[].match entry (A1).
+ * Exactly three entry forms — never raw string prefixing:
+ * (i)   scheme entry ("http://gpu-box:8000") → parsed; match iff origins are equal
+ *       (path/query/trailing slash ignored; kills "http://gpu-box:8000.evil.com"
+ *       and "http://gpu-box:8000@evil.com" bypass shapes);
+ * (ii)  leading-star entry ("*.gpu.internal") → hostname SUFFIX match: matches
+ *       "a.gpu.internal" and "x.y.gpu.internal", NOT "gpu.internal" itself;
+ * (iii) bare hostname → case-insensitive hostname equality (any port).
+ * Unparseable scheme entries never match (and never throw).
+ */
+function matchesEndpointEntry(entry, url) {
+    if (/^https?:\/\//i.test(entry)) {
+        const entryUrl = parseUrl(entry);
+        return entryUrl !== null && entryUrl.origin === url.origin;
+    }
+    const host = normalizeHostname(url.hostname);
+    if (entry.startsWith("*.")) {
+        const suffix = entry.slice(1).toLowerCase(); // ".gpu.internal"
+        return host.endsWith(suffix);
+    }
+    return host === entry.toLowerCase();
+}
+/** Read a string `baseURL` property off an SDK client instance, if present. */
+function readBaseURL(client) {
+    if (client != null && typeof client === "object" && "baseURL" in client) {
+        const value = client.baseURL;
+        if (typeof value === "string")
+            return value;
+    }
+    return undefined;
+}
+/**
+ * Classify the endpoint a client points at — local (self-hosted) or cloud —
+ * selecting the settlement regime for every governed call. Runs BESIDE
+ * `detectClientKind` (which stays the transport detector); the endpoint class,
+ * not the model string, picks local vs cloud metering, so model-name spoofing
+ * (`ollama cp llama3.2 gpt-4o`) cannot change the regime.
+ *
+ * Classification order:
+ * 1. `override.class` provided → override wins (runtime defaults to "unknown").
+ * 2. `client.baseURL` read when it is a string; absent or malformed (URL parse
+ *    failure) → treated as absent → cloud default. Never throws.
+ * 3. `config.endpoints[]` first match (origin / leading-star hostname suffix /
+ *    bare hostname — see matchesEndpointEntry).
+ * 4. Loopback autodetect (config.local.autoDetectLoopback): hostname
+ *    localhost | 127.0.0.1 | ::1 | ::ffff:127.0.0.1 (case-insensitive, IPv6
+ *    brackets stripped, IPv4-mapped form matched by its WHATWG serialization) →
+ *    local, runtime hinted by port (11434 ollama, 1234 lmstudio, 8000 vllm,
+ *    else "openai-compat").
+ * 5. Default `{ class: "cloud", runtime: "unknown" }` — fail-EXPENSIVE:
+ *    over-charging at cloud rates is recoverable, under-charging a paid
+ *    endpoint is not.
+ *
+ * **Security posture (trusted-operator boundary):** endpoint classification —
+ * config matchers, overrides, and loopback autodetect — is a TRUSTED-OPERATOR
+ * decision. Never wire it to end-user or request input. In server/multi-tenant
+ * deployments set `local.autoDetectLoopback: false` and classify via explicit
+ * `endpoints[]` config: loopback inside a container can be a forwarding sidecar
+ * to a paid API. This is the same trust boundary as `budget`/`customRates` —
+ * the config author already controls billing entirely. Note that a compromised
+ * local server can under-report usage; receipts expose `usageSource` and
+ * `meter.rateSource` precisely so that this is auditable.
+ */
+export function classifyEndpoint(client, config, override) {
+    const baseURL = readBaseURL(client);
+    // (1) Explicit override wins over everything.
+    if (override?.class !== undefined) {
+        const info = { class: override.class, runtime: override.runtime ?? "unknown" };
+        const overrideBase = override.baseURL ?? baseURL;
+        if (overrideBase !== undefined)
+            info.baseURL = overrideBase;
+        return info;
+    }
+    // (2) No readable baseURL → cloud default. Malformed → treat as absent, never throw.
+    if (baseURL === undefined)
+        return { ...CLOUD_DEFAULT };
+    const url = parseUrl(baseURL);
+    if (url === null)
+        return { ...CLOUD_DEFAULT };
+    // (3) config.endpoints[] — first match wins.
+    for (const entry of config.endpoints) {
+        if (matchesEndpointEntry(entry.match, url)) {
+            return { class: entry.class, runtime: entry.runtime, baseURL };
+        }
+    }
+    // (4) Loopback autodetect.
+    if (config.local.autoDetectLoopback && LOOPBACK_HOSTS.has(normalizeHostname(url.hostname))) {
+        return { class: "local", runtime: RUNTIME_BY_PORT[url.port] ?? "openai-compat", baseURL };
+    }
+    // (5) Cloud default.
+    return { class: "cloud", runtime: "unknown", baseURL };
+}
 //# sourceMappingURL=detect.js.map

package/dist/detect.js.map

@@ -1 +1 @@
-{"version":3,"file":"detect.js","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAuBjC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAe;IAC/C,IACC,MAAM,IAAI,IAAI;QACd,OAAO,MAAM,KAAK,QAAQ;QAC1B,UAAU,IAAI,MAAM;QACpB,MAAM,CAAC,QAAQ,IAAI,IAAI;QACvB,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;QACnC,QAAQ,IAAI,MAAM,CAAC,QAAQ;QAC3B,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,UAAU,EAC3C,CAAC;QACF,OAAO,WAAW,CAAC;IACpB,CAAC;IAED,IACC,MAAM,IAAI,IAAI;QACd,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,IAAI,MAAM;QAChB,MAAM,CAAC,IAAI,IAAI,IAAI;QACnB,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;QAC/B,aAAa,IAAI,MAAM,CAAC,IAAI;QAC5B,MAAM,CAAC,IAAI,CAAC,WAAW,IAAI,IAAI;QAC/B,OAAO,MAAM,CAAC,IAAI,CAAC,WAAW,KAAK,QAAQ;QAC3C,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW;QACnC,OAAO,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,UAAU,EACnD,CAAC;QACF,OAAO,QAAQ,CAAC;IACjB,CAAC;IAED,IACC,MAAM,IAAI,IAAI;QACd,OAAO,MAAM,KAAK,QAAQ;QAC1B,QAAQ,IAAI,MAAM;QAClB,MAAM,CAAC,MAAM,IAAI,IAAI;QACrB,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ;QACjC,iBAAiB,IAAI,MAAM,CAAC,MAAM;QAClC,OAAO,MAAM,CAAC,MAAM,CAAC,eAAe,KAAK,UAAU,EAClD,CAAC;QACF,OAAO,QAAQ,CAAC;IACjB,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,2EAA2E,CAAC,CAAC;AAC9F,CAAC"}
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"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"}

package/dist/govern.d.ts

@@ -1,5 +1,5 @@
 import { type AuditWriter } from "./audit/chain.js";
-import type { ActionDescriptor, GovernedActionResult } from "./shared/types.js";
+import type { ActionDescriptor, EndpointInfo, GovernedActionResult } from "./shared/types.js";
 export interface TrustOpts {
     /** Path to usertrust.config.json. Defaults to `.usertrust/usertrust.config.json`. */
     configPath?: string;
@@ -25,6 +25,13 @@ export interface TrustOpts {
     dryRun?: boolean;
     /** Vault directory override (default: cwd). */
     vaultBase?: string;
+    /**
+     * Explicit endpoint classification override (M2) — wins over config.endpoints
+     * matchers and loopback autodetect. TRUSTED-OPERATOR input, same trust
+     * boundary as budget/customRates: never derive it from end-user or request
+     * data (A10).
+     */
+    endpoint?: Partial<EndpointInfo> | undefined;
     /**
      * Inject a mock/test engine. When set, used instead of TigerBeetle.
      * Primarily for testing failure modes.

package/dist/govern.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"govern.d.ts","sourceRoot":"","sources":["../src/govern.ts"],"names":[],"mappings":"AAmCA,OAAO,EAAE,KAAK,WAAW,EAAqB,MAAM,kBAAkB,CAAC;AA0BvE,OAAO,KAAK,EACX,gBAAgB,EAChB,oBAAoB,EAKpB,MAAM,mBAAmB,CAAC;AAK3B,MAAM,WAAW,SAAS;IACzB,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7B;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC3B,YAAY,CAAC,MAAM,EAAE;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpC;;;OAGG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,gEAAgE;IAChE,cAAc,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO,CAAC,IAAI,IAAI,CAAC;CACjB;AAED,sEAAsE;AACtE,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG;IAClC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,YAAY,CAAC,CAAC,EACb,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;CACpC,CAAC;AAuFF,wBAAsB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAorCrF"}
+{"version":3,"file":"govern.d.ts","sourceRoot":"","sources":["../src/govern.ts"],"names":[],"mappings":"AAmCA,OAAO,EAAE,KAAK,WAAW,EAAqB,MAAM,kBAAkB,CAAC;AAgCvE,OAAO,KAAK,EACX,gBAAgB,EAChB,YAAY,EACZ,oBAAoB,EAKpB,MAAM,mBAAmB,CAAC;AAK3B,MAAM,WAAW,SAAS;IACzB,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC;IAC7C;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7B;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC3B,YAAY,CAAC,MAAM,EAAE;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpC;;;OAGG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,gEAAgE;IAChE,cAAc,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO,CAAC,IAAI,IAAI,CAAC;CACjB;AAED,sEAAsE;AACtE,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG;IAClC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,YAAY,CAAC,CAAC,EACb,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;CACpC,CAAC;AA6KF,wBAAsB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CA2xCrF"}

package/dist/govern.js

@@ -33,9 +33,9 @@ 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 { 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,7 +282,29 @@ 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) {
         if (destroyed) {
@@ -224,11 +329,17 @@ 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);
+            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,11 +463,41 @@ 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).
+            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, forwardArgs);
+                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 &&
@@ -364,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 {
@@ -455,6 +598,10 @@ 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(promptParts);
@@ -493,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 } : {}),
@@ -546,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) {
@@ -584,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 } : {}),
@@ -591,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) {
@@ -602,7 +768,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 +786,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);
@@ -750,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 } : {}),