@vincemakes/kiso-runtime 0.1.37 → 0.2.0

package/dist/trace/record.js

@@ -0,0 +1,237 @@
+/**
+ * E1 (1.2.0) — the Request Trace record schema (proposal §1.1 as adopted
+ * by the R1 ruling: "adopt as-is, keep ts, per-round additive"). This is
+ * the 1.2.0 field-set lock: every field below is spec'd, and the
+ * closed-field-set gate (ruling R1a) pins the shape bidirectionally —
+ * `TRACE_RECORD_FIELDS`/`TRACE_SEGMENT_FIELDS` must stay in exact
+ * agreement with the interfaces, or trace-schema.test.ts goes red.
+ *
+ * R1a: `schemaVersion` pins BOTH the record shape AND the hash /
+ * fingerprint algorithms (`HASH_SPEC_BY_VERSION`). A version bump must
+ * pin a spec for the new version before any writer can use it
+ * (`hashSpecFor` throws otherwise).
+ *
+ * The ledger is OUT-side (ADR-0051 §6): versionable, never part of the
+ * correctness ABI. These types are runtime-internal.
+ *
+ * E2 (1.3.0) — schemaVersion 2: the record gains the `canonical` block
+ * (E2 proposal §1.5 Case A — the nested block, ruled 2026-08-13; raw
+ * quartet stays as provider observation above it). The validators accept
+ * BOTH generations (R1d-1): a v1 sidecar has no canonical block and reads
+ * as defaults at every consumer — never a crash.
+ */
+/** schemaVersion: 2 for 1.3.0 (the canonical block). Version 1 = the 1.2.0
+ *  shape, kept for generation-compat reads (R1d-1). Algorithm and shape
+ *  changes bump it (ADR-0051 §6 OUT-side versioning). */
+export const TRACE_SCHEMA_VERSION = 2;
+/** The versions a reader may meet in a ledger. v1 records are accepted
+ *  (generation-compat, R1d-1) and read as defaults — no canonical block. */
+export const TRACE_SCHEMA_VERSIONS = new Set([1, TRACE_SCHEMA_VERSION]);
+import { PRICING_TABLE_V1, priceFor, pricingTableFor, validateCanonicalUsage } from "../usage/canonical.js";
+export const HASH_SPEC_BY_VERSION = {
+    1: { algorithm: "sha-256", output: "full-hex" },
+    2: { algorithm: "sha-256", output: "full-hex" }, // E2 — the algorithms do not change
+};
+export function hashSpecFor(version) {
+    const spec = HASH_SPEC_BY_VERSION[version];
+    if (spec === undefined)
+        throw new Error(`no hash spec pinned for trace schemaVersion ${version}`);
+    return spec;
+}
+// ── The closed-field-set gate (R1a) ───────────────────────────────────────
+// Trace-schema.test.ts asserts Object.keys of a fully populated record is
+// EXACTLY this set (both directions).
+/** The 1.2.0 field set (schemaVersion 1) — kept verbatim for
+ *  generation-compat reads of old sidecars (R1d-1): a v1 record has no
+ *  canonical block and reads as defaults at every consumer. */
+export const TRACE_RECORD_FIELDS_V1 = [
+    "schemaVersion",
+    "kind",
+    "requestId",
+    "runId",
+    "requestIndex",
+    "retryAttempt",
+    "provider",
+    "model",
+    "adapterVersion",
+    "systemPromptHash",
+    "toolSchemaHash",
+    "contextHash",
+    "contextManifest",
+    "segmentHashes",
+    "stablePrefixFingerprint",
+    "freshInput",
+    "cacheRead",
+    "cacheWrite",
+    "output",
+    "latencyMs",
+    "ttftMs",
+    "toolCalls",
+    "outcome",
+    "lineageLink",
+    "ts",
+];
+/** The 1.3.0 field set (schemaVersion 2) = the v1 set + `canonical`. */
+export const TRACE_RECORD_FIELDS = [...TRACE_RECORD_FIELDS_V1, "canonical"];
+export const TRACE_SEGMENT_FIELDS = ["role", "seqRange", "estTokens", "freshness"];
+// ── Validators ────────────────────────────────────────────────────────────
+// Strict by design: extra keys are rejected (the closed set), so a
+// misspelled field can never silently enter the ledger.
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const keysOf = (v) => (isRecord(v) ? Object.keys(v) : []);
+const isNonNegInt = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
+const isNumber = (v) => typeof v === "number" && Number.isFinite(v);
+const isHex64 = (v) => typeof v === "string" && /^[0-9a-f]{64}$/.test(v);
+/** The closed set, both directions: no key outside the spec, and every
+ *  spec'd key present except the explicit optional ones. */
+const hasClosedKeys = (v, spec, optional = []) => {
+    const keys = keysOf(v);
+    if (keys.some((k) => !spec.includes(k)))
+        return false;
+    const optionalSet = new Set(optional);
+    return spec.every((k) => optionalSet.has(k) || keys.includes(k));
+};
+const VALID_SEGMENT_ROLES = new Set(["system", "tools", "turn", "current_turn"]);
+const VALID_FRESHNESS = new Set(["fresh", "cache_read", "cache_write"]);
+const VALID_OUTCOMES = new Set(["ok", "provider_error", "aborted"]);
+function isValidSeqRange(v) {
+    if (v === null)
+        return true;
+    if (!Array.isArray(v) || v.length !== 2)
+        return false;
+    const [a, b] = v;
+    return isNonNegInt(a) && isNonNegInt(b) && a <= b;
+}
+export function validateTraceSegment(v) {
+    if (!isRecord(v) || !hasClosedKeys(v, TRACE_SEGMENT_FIELDS))
+        return false;
+    if (typeof v.role !== "string" || !VALID_SEGMENT_ROLES.has(v.role))
+        return false;
+    if (!isValidSeqRange(v.seqRange))
+        return false;
+    if (!isNonNegInt(v.estTokens))
+        return false;
+    if (!VALID_FRESHNESS.has(v.freshness))
+        return false;
+    return true;
+}
+export function validateTraceRecord(v) {
+    if (!isRecord(v))
+        return false;
+    const version = v.schemaVersion;
+    // generation-compat (R1d-1): a v1 sidecar has no canonical block and
+    // reads as defaults — accepted, never a crash; the current version is
+    // fully checked (shape + the canonical block + its consistency).
+    if (version !== 1 && version !== TRACE_SCHEMA_VERSION)
+        return false;
+    const fields = version === 1 ? TRACE_RECORD_FIELDS_V1 : TRACE_RECORD_FIELDS;
+    if (!hasClosedKeys(v, fields, ["lineageLink"]))
+        return false;
+    if (v.kind !== "request")
+        return false;
+    if (typeof v.requestId !== "string" || typeof v.runId !== "string")
+        return false;
+    if (!isNonNegInt(v.requestIndex) || !isNonNegInt(v.retryAttempt))
+        return false;
+    if (typeof v.provider !== "string" || typeof v.model !== "string")
+        return false;
+    if (v.adapterVersion !== null && typeof v.adapterVersion !== "string")
+        return false;
+    if (!isHex64(v.systemPromptHash) || !isHex64(v.toolSchemaHash) || !isHex64(v.contextHash))
+        return false;
+    if (!isHex64(v.stablePrefixFingerprint))
+        return false;
+    if (!Array.isArray(v.contextManifest) || !v.contextManifest.every(validateTraceSegment))
+        return false;
+    // segmentHashes must mirror the manifest 1:1 — a misaligned list
+    // would silently corrupt the break derivation (R4b)
+    if (!Array.isArray(v.segmentHashes) ||
+        v.segmentHashes.length !== v.contextManifest.length ||
+        !v.segmentHashes.every(isHex64))
+        return false;
+    if (!isNumber(v.freshInput) || !isNumber(v.cacheRead))
+        return false;
+    if (v.cacheWrite !== null && !isNumber(v.cacheWrite))
+        return false;
+    if (!isNumber(v.output) || !isNumber(v.latencyMs))
+        return false;
+    if (!isNumber(v.ttftMs))
+        return false; // 0 = unknown, never null (locked set)
+    if (!Array.isArray(v.toolCalls) || !v.toolCalls.every((t) => typeof t === "string"))
+        return false;
+    if (typeof v.outcome !== "string" || !VALID_OUTCOMES.has(v.outcome))
+        return false;
+    if (v.lineageLink !== undefined) {
+        const l = v.lineageLink;
+        if (!isRecord(l))
+            return false;
+        if (typeof l.parentSessionId !== "string" || typeof l.parentRunId !== "string")
+            return false;
+        if (!isNonNegInt(l.parentInvocationSeq))
+            return false;
+        if (typeof l.role !== "string")
+            return false;
+    }
+    if (version !== 1) {
+        // the canonical block: the schema's invariants machine-checked
+        if (!validateCanonicalUsage(v.canonical))
+            return false;
+        const c = v.canonical;
+        // the block formalizes the raw quartet — a divergence means the
+        // derivation drifted (a future bug, caught at the ledger)
+        if (c.input !== v.freshInput || c.cacheRead !== v.cacheRead || c.output !== v.output || c.cacheWrite !== v.cacheWrite)
+            return false;
+        // cost consistency: recomputed from the components × the version's
+        // pinned table, at the record's own route (the route context lives
+        // in the record; the standalone schema cannot check this). A null
+        // costUsd is the R5b-④c absent stamp (the table has no rate for
+        // this route) — nothing to recompute against, accepted. The
+        // cross-check runs only for builtin-id records: a foreign table's
+        // consistency is the billing layer's accounting, not the ledger's.
+        if (c.costUsd !== null && c.pricingTableId === PRICING_TABLE_V1.id) {
+            const expected = priceFor(v.provider, { input: c.input, output: c.output, cacheRead: c.cacheRead, cacheWrite: c.cacheWrite }, pricingTableFor(c.pricingTableVersion));
+            // non-null for the builtin table by construction (both real
+            // routes + the mirror fallback) — a null here is a code bug,
+            // and an epsilon check has nothing to compare
+            if (expected !== null && Math.abs(c.costUsd - expected) > 1e-6)
+                return false;
+        }
+    }
+    if (!isNumber(v.ts))
+        return false;
+    return true;
+}
+export function validateTraceLine(v) {
+    if (!isRecord(v))
+        return false;
+    // both ledger generations are readable (R1d-1); the per-kind shapes are
+    // identical across 1 → 2 — only the request line's field set differs
+    // (v1 lacks the canonical block), handled by validateTraceRecord's
+    // version dispatch
+    if (!TRACE_SCHEMA_VERSIONS.has(v.schemaVersion))
+        return false;
+    switch (v.kind) {
+        case "header":
+            return (hasClosedKeys(v, ["schemaVersion", "kind", "sessionId", "kisoVersion", "createdAt"]) &&
+                typeof v.sessionId === "string" &&
+                typeof v.kisoVersion === "string" &&
+                isNumber(v.createdAt));
+        case "request":
+            return validateTraceRecord(v);
+        case "run_end":
+            return (hasClosedKeys(v, ["schemaVersion", "kind", "runId", "ts", "lastRequestIndex"]) &&
+                typeof v.runId === "string" &&
+                isNumber(v.ts) &&
+                // -1 = the run made no adapter calls (an empty run still
+                // settles cleanly); anything below that is not a request index
+                typeof v.lastRequestIndex === "number" &&
+                Number.isInteger(v.lastRequestIndex) &&
+                v.lastRequestIndex >= -1);
+        case "crash":
+            return (hasClosedKeys(v, ["schemaVersion", "kind", "ts", "note"]) &&
+                isNumber(v.ts) &&
+                typeof v.note === "string");
+        default:
+            return false;
+    }
+}

package/dist/trace/writer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * E1 (1.2.0) — slice 2, the trace writer (proposal §1.2 + §6).
+ *
+ * The ledger is OUT-side (ADR-0051 §6): a versionable observation
+ * artifact, never part of the correctness ABI. The soft-fail law
+ * (work-order): trace loss costs ONE stderr line, then the session runs
+ * on — the writer degrades to a no-op on its first I/O failure and
+ * never throws into the caller.
+ *
+ * Async discipline (work-order §9): request lines are ENQUEUED (a sync
+ * push, sub-microsecond) and flushed on setImmediate — the model hot
+ * path never blocks on the ledger. The run_end line is flushed
+ * SYNCHRONOUSLY from the run's finally block: clean-settle marking is
+ * where the ledger's story (every hole reconciles as a crash, never as
+ * a writer bug) needs the write to have happened before the run ends.
+ */
+import { type TraceLine } from "./record.js";
+/** The runtime's own version, read from the package.json next to the
+ *  build; null on failure (soft-fail — the header still ships). */
+export declare function runtimeVersion(): string | null;
+export interface TraceWriterDeps {
+    /** The sessions dir (store.root). The ledger lives in <root>/traces/ —
+     *  NOT flat in root: a flat `<sid>.trace.jsonl` would be enumerated as
+     *  a phantom session by SessionStore.list() and corrupt the bench
+     *  sessions glob (proposal §3.2; the R3a gate pins it). */
+    root: string;
+    sessionId: string;
+}
+export declare class TraceWriter {
+    #private;
+    constructor(deps: TraceWriterDeps);
+    /** One-time setup: mkdir the ledger dir, mark a previous run that left
+     *  no run_end (crash), write the header — the header once per ledger
+     *  file (session-level, §1.2), so a resume appends markers, never a
+     *  second header. Never throws. */
+    init(): void;
+    /** Enqueue a line for the next flush — the hot path's only cost.
+     *  Never throws; after a degradation the line is dropped. */
+    enqueue(line: TraceLine): void;
+    /** Clean-settle marking: the run_end line lands NOW (synchronous),
+     *  together with any still-pending request lines. */
+    finishRun(runId: string, lastRequestIndex: number): void;
+}

package/dist/trace/writer.js

@@ -0,0 +1,154 @@
+/**
+ * E1 (1.2.0) — slice 2, the trace writer (proposal §1.2 + §6).
+ *
+ * The ledger is OUT-side (ADR-0051 §6): a versionable observation
+ * artifact, never part of the correctness ABI. The soft-fail law
+ * (work-order): trace loss costs ONE stderr line, then the session runs
+ * on — the writer degrades to a no-op on its first I/O failure and
+ * never throws into the caller.
+ *
+ * Async discipline (work-order §9): request lines are ENQUEUED (a sync
+ * push, sub-microsecond) and flushed on setImmediate — the model hot
+ * path never blocks on the ledger. The run_end line is flushed
+ * SYNCHRONOUSLY from the run's finally block: clean-settle marking is
+ * where the ledger's story (every hole reconciles as a crash, never as
+ * a writer bug) needs the write to have happened before the run ends.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { TRACE_SCHEMA_VERSION } from "./record.js";
+let cachedRuntimeVersion;
+/** The runtime's own version, read from the package.json next to the
+ *  build; null on failure (soft-fail — the header still ships). */
+export function runtimeVersion() {
+    if (cachedRuntimeVersion === undefined) {
+        cachedRuntimeVersion = (() => {
+            try {
+                const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json"), "utf8"));
+                return pkg.version ?? null;
+            }
+            catch {
+                return null;
+            }
+        })();
+    }
+    return cachedRuntimeVersion;
+}
+export class TraceWriter {
+    #root;
+    #sessionId;
+    #path;
+    #pending = [];
+    #flushScheduled = false;
+    #degraded = false;
+    constructor(deps) {
+        this.#root = deps.root;
+        this.#sessionId = deps.sessionId;
+        this.#path = join(deps.root, "traces", `${deps.sessionId}.jsonl`);
+    }
+    /** One-time setup: mkdir the ledger dir, mark a previous run that left
+     *  no run_end (crash), write the header — the header once per ledger
+     *  file (session-level, §1.2), so a resume appends markers, never a
+     *  second header. Never throws. */
+    init() {
+        if (this.#degraded)
+            return;
+        try {
+            mkdirSync(join(this.#root, "traces"), { recursive: true });
+            const fresh = !existsSync(this.#path);
+            if (this.#crashDetect()) {
+                this.#writeSync([
+                    { schemaVersion: TRACE_SCHEMA_VERSION, kind: "crash", ts: Date.now(), note: "previous run left no run_end" },
+                ]);
+            }
+            if (fresh) {
+                this.#writeSync([
+                    {
+                        schemaVersion: TRACE_SCHEMA_VERSION,
+                        kind: "header",
+                        sessionId: this.#sessionId,
+                        kisoVersion: runtimeVersion() ?? "?",
+                        createdAt: Date.now(),
+                    },
+                ]);
+            }
+        }
+        catch (err) {
+            this.#degrade(err);
+        }
+    }
+    /** Enqueue a line for the next flush — the hot path's only cost.
+     *  Never throws; after a degradation the line is dropped. */
+    enqueue(line) {
+        if (this.#degraded)
+            return;
+        this.#pending.push(line);
+        if (!this.#flushScheduled) {
+            this.#flushScheduled = true;
+            setImmediate(() => {
+                this.#flushScheduled = false;
+                this.#flushSync();
+            });
+        }
+    }
+    /** Clean-settle marking: the run_end line lands NOW (synchronous),
+     *  together with any still-pending request lines. */
+    finishRun(runId, lastRequestIndex) {
+        this.enqueue({
+            schemaVersion: TRACE_SCHEMA_VERSION,
+            kind: "run_end",
+            runId,
+            ts: Date.now(),
+            lastRequestIndex,
+        });
+        this.#flushSync();
+    }
+    /** True when the ledger already exists and its LAST line is neither
+     *  run_end nor crash — an un-terminated run (killed mid-run), to be
+     *  marked. A crash-marked ledger is not re-marked. */
+    #crashDetect() {
+        if (!existsSync(this.#path))
+            return false;
+        let last;
+        try {
+            for (const line of readFileSync(this.#path, "utf8").split("\n")) {
+                if (line.trim() === "")
+                    continue;
+                last = JSON.parse(line);
+            }
+        }
+        catch {
+            return false; // unreadable ledger — do not compound the failure
+        }
+        if (last === undefined)
+            return false;
+        return last.kind !== "run_end" && last.kind !== "crash";
+    }
+    #writeSync(lines) {
+        if (lines.length === 0)
+            return;
+        try {
+            appendFileSync(this.#path, `${lines.map((l) => JSON.stringify(l)).join("\n")}\n`);
+        }
+        catch (err) {
+            this.#degrade(err);
+        }
+    }
+    #flushSync() {
+        if (this.#pending.length === 0)
+            return;
+        const lines = this.#pending;
+        this.#pending = [];
+        this.#writeSync(lines);
+    }
+    /** The soft-fail law: one stderr line, then the ledger is dropped and
+     *  the session runs on. Idempotent. */
+    #degrade(err) {
+        if (this.#degraded)
+            return;
+        this.#degraded = true;
+        this.#pending = [];
+        console.error(`[kiso] trace writer degraded (${err instanceof Error ? err.message : String(err)}); request traces dropped`);
+    }
+}

package/dist/usage/canonical.d.ts

@@ -0,0 +1,123 @@
+/**
+ * E2 (1.3.0) — Canonical Usage: the reconciled usage schema (proposal §1
+ * as ruled 2026-08-13; R1a-R5 all adopted).
+ *
+ * THE PINNED SENTENCE (R1a): one canonical meaning for `input`, everywhere
+ * in kiso, forever: `input` is FRESH-ONLY — the tokens NOT served from
+ * cache. `total = input + cacheRead + cacheWrite` is the derived quantity,
+ * never a reported one. A cache ratio is always `cacheRead / total` — the
+ * numerator can never exceed the denominator. The >100% disease is
+ * structurally impossible under the canonical schema.
+ *
+ * The mapping keys on the ROUTE, not the provider (R2a): DeepSeek serves
+ * both routes and reports input fresh-only on one (anthropic-compat) and
+ * TOTAL on the other (openai-compat) — the SAME canonical meaning falls
+ * out of the route key (the dual-endpoint closure). The route string is
+ * the config adapter identity the guard already holds (`"anthropic" |
+ * "openai-compat"`).
+ *
+ * Cost comes from the versioned pricing table — every cost carries the
+ * table version it was computed with (R1c). The built-in v1 table prices
+ * both routes at DeepSeek's published rates; the caveat sentence from the
+ * bench README carries forward verbatim ("an approximation, not a bill").
+ * The commercial table is the product's Phase 10 (the table is injectable;
+ * the version travels with every cost).
+ *
+ * The frozen usage union stays provider-raw — this module derives at the
+ * accounting boundary (R4 Case B, pure derivation; the union does not
+ * move). Raw is provider observation; canonical is the accounting truth.
+ */
+/** The union's usage shape (provider-raw — core protocol `events.Usage`). */
+export interface RawUsage {
+    readonly inputTokens: number | null;
+    readonly outputTokens: number | null;
+    readonly cacheRead: number | null;
+    readonly cacheWrite: number | null;
+}
+/** The ONE canonical usage record. Every field has exactly one meaning
+ *  (proposal §1.2). wall/ttft live in the trace record (latencyMs/ttftMs)
+ *  — one source, never duplicated here. */
+export interface CanonicalUsage {
+    /** FRESH-ONLY — the pinned sentence above. total = input + cacheRead +
+     *  cacheWrite is the derived quantity, never a reported one. */
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    /** null = the provider reports none (openai-compat honestly does). */
+    readonly cacheWrite: number | null;
+    /** null = no reasoning split reported (reserved — every provider today). */
+    readonly reasoning: number | null;
+    /** USD from the pricing table below — null is the R5b-④c ABSENT stamp:
+     *  the table has no rate for this route (an injected table's hole is
+     *  explicit absent, never backfilled from the builtin table). The
+     *  builtin v1 table covers both real routes, so the null branch is
+     *  unreachable today — but the type must be able to express it.
+     *  Never reported without its (pricingTableId, pricingTableVersion)
+     *  tuple — the billing-basis ground. */
+    readonly costUsd: number | null;
+    /** The table the cost was computed with (R5b-④b): the (id, version)
+     *  two-tuple stamp — cross-table version reconciliation and billing
+     *  disputes answerable. "builtin" = the pinned in-repo table below;
+     *  injected tables carry their own id. */
+    readonly pricingTableId: string;
+    readonly pricingTableVersion: number;
+}
+/** The versioned pricing table — a rate change is a version bump, never an
+ *  edit; every cost records the version it was computed with (R1c). The
+ *  id is the table's identity (R5b-④b): "builtin" for the pinned in-repo
+ *  table, anything else for an injected commercial table. */
+export interface PricingTable {
+    readonly id: string;
+    readonly version: number;
+    readonly entries: Readonly<Record<string, PricingEntry>>;
+}
+export interface PricingEntry {
+    /** USD per 1M FRESH input tokens. */
+    readonly inputPerM: number;
+    readonly outputPerM: number;
+    readonly cacheReadPerM: number;
+    /** USD per 1M cache-creation tokens. 0 = the provider does not price
+     *  cache writes separately (DeepSeek's automatic caching). */
+    readonly cacheWritePerM: number;
+}
+/** The route → input-convention table (R2a). `input` semantics differ
+ *  between the two routes; the convention is a property of the ROUTE, not
+ *  the provider. Unknown routes fall back to "total" — exactly the
+ *  incumbent guard behavior (the guard's else-branch: non-anthropic =
+ *  total), preserved by construction. */
+export declare const INPUT_CONVENTIONS: Readonly<Record<string, "fresh" | "total">>;
+/** Pricing table v1. Freeze date 2026-08-13 (the E2 ruling). Rates:
+ *  DeepSeek's published rates (https://api-docs.deepseek.com/quick_start/pricing),
+ *  the 0.1 cache-hit ratio the bench has used since the 0.1.23 round. The
+ *  caveat sentence carries forward verbatim (bench README): "an
+ *  approximation, not a bill." */
+export declare const PRICING_TABLE_V1: PricingTable;
+export declare const PRICING_TABLES: Readonly<Record<number, PricingTable>>;
+/** The table pinned for a version; throws when none is pinned (a cost
+ *  recorded against an unpinned version is a ledger corruption). */
+export declare function pricingTableFor(version: number): PricingTable;
+export declare function priceFor(route: string, u: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number | null;
+}, table: PricingTable): number | null;
+/** Raw → canonical (the accounting boundary). Behavior-preserving against
+ *  the guard's incumbent per-provider branch (guard.ts settle): anthropic
+ *  input is fresh as-is; every other route subtracts cacheRead.
+ *
+ *  The trailing `table` parameter is the injection slot (R5b-④a): the
+ *  R5a-1-commercial table rides it on day one, defaulting to the pinned
+ *  builtin v1 table so the export's default behavior is the pinned one
+ *  and a future injection never widens this frozen signature. */
+export declare function canonicalizeUsage(route: string, raw: RawUsage, table?: PricingTable): CanonicalUsage;
+/** The canonical schema's invariants, machine-checked: closed key set;
+ *  non-negative numbers; cacheWrite/reasoning null-or-number; the pinned
+ *  sentence — cacheRead can never exceed total (= input + cacheRead +
+ *  cacheWrite) — structurally true for non-negatives but pinned against
+ *  future edits; costUsd null-or-number (R5b-④c — null is the injected
+ *  table's absent stamp); the (pricingTableId, pricingTableVersion)
+ *  tuple, with the registry pin scoped to the builtin id (R5b-④b) — an
+ *  injected table's version is the injector's accounting, the ledger
+ *  cannot know tables it does not carry. */
+export declare function validateCanonicalUsage(v: unknown): v is CanonicalUsage;