open-multi-agent-kit 0.95.1 → 0.95.2

package/dist/core/context-budget-v2-cache-disk.js

@@ -0,0 +1,343 @@
+/**
+ * Workspace-layer disk persistence for the context-budget-v2 representation
+ * cache.
+ *
+ * The in-memory provider (`context-budget-v2-cache-provider.ts`) dies with the
+ * process, so every new session re-renders and re-compresses context it already
+ * paid for. This provider keeps the same synchronous
+ * `ContextBudgetCacheProviderV2` contract and adds a bounded, atomically
+ * written JSON snapshot on disk.
+ *
+ * Scope: representation entries and negative entries only. Plan entries stay in
+ * memory on purpose — a plan is session-scoped (its key folds in the
+ * invalidation snapshot), so persisting it would only ever store misses.
+ *
+ * Safety: reads go through the same validator as the memory provider
+ * (`validateContextBudgetRepresentationCacheEntryV2`), which re-checks source
+ * hash, representation fingerprint, model, tokenizer, policy version and TTL.
+ * A corrupt, truncated, oversized, or schema-mismatched snapshot is discarded
+ * and the cache simply starts empty; a cache is never load-bearing for
+ * correctness.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { containsCredentialShape } from "./compaction/transaction.js";
+import { createContextCacheInvalidationSnapshot, } from "./context-budget-v2-cache-invalidation.js";
+export const CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION = "context-budget-v2-diskcache-1";
+/** Default cap on persisted representation entries. */
+export const DEFAULT_DISK_CACHE_MAX_ENTRIES = 2048;
+/** Default cap on the persisted snapshot size. Oversized snapshots are dropped on load. */
+export const DEFAULT_DISK_CACHE_MAX_BYTES = 32 * 1024 * 1024;
+/** Default write-behind debounce. Collapses a burst of writes into a single flush. */
+export const DEFAULT_DISK_CACHE_FLUSH_DEBOUNCE_MS = 750;
+/** Default cap on a single persisted representation's text length. */
+export const DEFAULT_DISK_CACHE_MAX_ENTRY_TEXT_LENGTH = 512 * 1024;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function containsCredentialShapeInValue(value) {
+    const pending = [value];
+    const seen = new Set();
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (typeof current === "string") {
+            if (containsCredentialShape(current))
+                return true;
+            continue;
+        }
+        if (typeof current !== "object" || current === null || seen.has(current))
+            continue;
+        seen.add(current);
+        if (Array.isArray(current)) {
+            pending.push(...current);
+            continue;
+        }
+        for (const [key, nested] of Object.entries(current)) {
+            if (containsCredentialShape(key))
+                return true;
+            pending.push(nested);
+        }
+    }
+    return false;
+}
+function isPersistableRepresentation(value, maxEntryTextLength) {
+    if (!isRecord(value))
+        return false;
+    if (typeof value.kind !== "string")
+        return false;
+    if (typeof value.text !== "string" || value.text.length > maxEntryTextLength)
+        return false;
+    if (containsCredentialShapeInValue(value))
+        return false;
+    const estimated = value.estimatedTokens;
+    if (typeof estimated !== "number" || !Number.isFinite(estimated) || estimated < 0)
+        return false;
+    if (typeof value.fidelity !== "string")
+        return false;
+    if (typeof value.sourceHash !== "string" || value.sourceHash.length === 0)
+        return false;
+    if (typeof value.representationFingerprint !== "string")
+        return false;
+    if (typeof value.modelId !== "string")
+        return false;
+    if (typeof value.tokenizerId !== "string")
+        return false;
+    if (typeof value.policyVersion !== "string")
+        return false;
+    return true;
+}
+function isPersistableNegative(value) {
+    return isRecord(value) && typeof value.reason === "string" && !containsCredentialShapeInValue(value);
+}
+function readLru(store, key) {
+    const entry = store.get(key);
+    if (entry === undefined)
+        return undefined;
+    store.delete(key);
+    store.set(key, entry);
+    return entry;
+}
+function writeLru(store, key, entry, maxEntries) {
+    store.delete(key);
+    store.set(key, entry);
+    while (store.size > maxEntries) {
+        const oldestKey = store.keys().next().value;
+        if (oldestKey === undefined)
+            return;
+        store.delete(oldestKey);
+    }
+}
+/**
+ * Create a disk backed workspace cache provider. Loading is synchronous and
+ * best-effort: any failure yields an empty in-memory cache rather than throwing,
+ * because a cache miss is always a legal outcome.
+ */
+export function createDiskContextBudgetCacheProviderV2(options) {
+    return new DiskContextBudgetCacheProviderV2(options);
+}
+export class DiskContextBudgetCacheProviderV2 {
+    representations = new Map();
+    negatives = new Map();
+    /** Plans stay in memory: their keys are session-scoped, so persisting them stores only misses. */
+    plans = new Map();
+    layer;
+    maxEntries;
+    maxBytes;
+    maxEntryTextLength;
+    flushDebounceMs;
+    now;
+    snapshotPath;
+    invalidationSnapshot;
+    dirty = false;
+    flushTimer;
+    loadError;
+    constructor(options) {
+        this.layer = options.layer ?? "workspace";
+        this.maxEntries = Math.max(1, options.maxEntries ?? DEFAULT_DISK_CACHE_MAX_ENTRIES);
+        this.maxBytes = Math.max(1024, options.maxBytes ?? DEFAULT_DISK_CACHE_MAX_BYTES);
+        this.maxEntryTextLength = Math.max(1, options.maxEntryTextLength ?? DEFAULT_DISK_CACHE_MAX_ENTRY_TEXT_LENGTH);
+        this.flushDebounceMs = Math.max(0, options.flushDebounceMs ?? DEFAULT_DISK_CACHE_FLUSH_DEBOUNCE_MS);
+        this.now = options.now ?? Date.now;
+        this.snapshotPath = path.join(options.dir, "representations.json");
+        this.load();
+    }
+    /** Absolute path of the persisted snapshot. */
+    get snapshotFilePath() {
+        return this.snapshotPath;
+    }
+    /** Reason the on-disk snapshot was rejected, if it was. `undefined` on a clean load or a cold start. */
+    get lastLoadError() {
+        return this.loadError;
+    }
+    /** Number of representation entries currently held. */
+    get size() {
+        return this.representations.size;
+    }
+    load() {
+        let raw;
+        try {
+            const stat = fs.statSync(this.snapshotPath);
+            if (stat.size > this.maxBytes) {
+                this.loadError = `snapshot exceeds maxBytes (${stat.size} > ${this.maxBytes})`;
+                return;
+            }
+            raw = fs.readFileSync(this.snapshotPath, "utf8");
+        }
+        catch {
+            // Cold start: no snapshot yet, or it is unreadable. Both are normal.
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            this.loadError = "snapshot is not valid JSON";
+            return;
+        }
+        if (!isRecord(parsed) || parsed.schemaVersion !== CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION) {
+            this.loadError = "snapshot schema mismatch";
+            return;
+        }
+        if (containsCredentialShapeInValue(parsed)) {
+            this.loadError = "snapshot contains credential-shaped text";
+            try {
+                fs.rmSync(this.snapshotPath, { force: true });
+            }
+            catch {
+                // The unsafe snapshot remains unreadable to this provider.
+            }
+            return;
+        }
+        const representations = Array.isArray(parsed.representations) ? parsed.representations : [];
+        for (const pair of representations) {
+            if (!Array.isArray(pair) || pair.length !== 2)
+                continue;
+            const [key, entry] = pair;
+            if (typeof key !== "string" || key.length === 0)
+                continue;
+            if (!isPersistableRepresentation(entry, this.maxEntryTextLength))
+                continue;
+            writeLru(this.representations, key, entry, this.maxEntries);
+        }
+        const negatives = Array.isArray(parsed.negatives) ? parsed.negatives : [];
+        for (const pair of negatives) {
+            if (!Array.isArray(pair) || pair.length !== 2)
+                continue;
+            const [key, entry] = pair;
+            if (typeof key !== "string" || key.length === 0)
+                continue;
+            if (!isPersistableNegative(entry))
+                continue;
+            writeLru(this.negatives, key, entry, this.maxEntries);
+        }
+    }
+    markDirty() {
+        this.dirty = true;
+        if (this.flushDebounceMs === 0) {
+            this.flush();
+            return;
+        }
+        if (this.flushTimer !== undefined)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = undefined;
+            this.flush();
+        }, this.flushDebounceMs);
+        this.flushTimer.unref?.();
+    }
+    /**
+     * Write the snapshot to disk atomically (temp file + rename). Best-effort:
+     * a failed flush leaves the previous snapshot intact and keeps the entries
+     * in memory. Returns `true` when a snapshot was written.
+     */
+    flush() {
+        if (this.flushTimer !== undefined) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        if (!this.dirty)
+            return false;
+        const snapshot = {
+            schemaVersion: CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION,
+            representations: [...this.representations.entries()]
+                .filter(([key, entry]) => !containsCredentialShape(key) && isPersistableRepresentation(entry, this.maxEntryTextLength))
+                .map(([key, entry]) => [key, entry]),
+            negatives: [...this.negatives.entries()]
+                .filter(([key, entry]) => !containsCredentialShape(key) && isPersistableNegative(entry))
+                .map(([key, entry]) => [key, entry]),
+        };
+        let serialized;
+        try {
+            serialized = JSON.stringify(snapshot);
+        }
+        catch {
+            return false;
+        }
+        if (Buffer.byteLength(serialized, "utf8") > this.maxBytes) {
+            // Drop the oldest half and retry once rather than growing forever.
+            const keys = [...this.representations.keys()];
+            if (keys.length === 0)
+                return false;
+            const dropCount = Math.max(1, Math.ceil(keys.length / 2));
+            for (const key of keys.slice(0, dropCount))
+                this.representations.delete(key);
+            return this.flush();
+        }
+        const tempPath = `${this.snapshotPath}.${process.pid}.tmp`;
+        try {
+            fs.mkdirSync(path.dirname(this.snapshotPath), { recursive: true });
+            fs.writeFileSync(tempPath, serialized, { encoding: "utf8", mode: 0o600 });
+            fs.renameSync(tempPath, this.snapshotPath);
+            this.dirty = false;
+            return true;
+        }
+        catch {
+            try {
+                fs.rmSync(tempPath, { force: true });
+            }
+            catch {
+                // The temp file is unlinkable; nothing further to do.
+            }
+            return false;
+        }
+    }
+    /** Cancel any pending flush and persist immediately. Safe to call more than once. */
+    close() {
+        this.flush();
+    }
+    getInvalidationSnapshot() {
+        return this.invalidationSnapshot;
+    }
+    setInvalidationSnapshot(snapshot) {
+        this.invalidationSnapshot = createContextCacheInvalidationSnapshot({
+            forkId: snapshot.forkId,
+            worktreeFingerprint: snapshot.worktreeFingerprint,
+            activeModelId: snapshot.activeModelId,
+            compactionModelId: snapshot.compactionModelId,
+            globalEpoch: snapshot.globalEpoch,
+            transcriptRepair: snapshot.counters.transcriptRepair,
+            toolResultDisposition: snapshot.counters.toolResultDisposition,
+            evidenceReceipt: snapshot.counters.evidenceReceipt,
+            userSteering: snapshot.counters.userSteering,
+            settings: snapshot.counters.settings,
+        });
+    }
+    readRepresentation(key) {
+        const entry = readLru(this.representations, key);
+        return entry ? { entry, layer: this.layer } : undefined;
+    }
+    writeRepresentation(input) {
+        writeLru(this.representations, input.key, input.entry, this.maxEntries);
+        if ((!containsCredentialShape(input.key) && isPersistableRepresentation(input.entry, this.maxEntryTextLength)) ||
+            fs.existsSync(this.snapshotPath)) {
+            this.markDirty();
+        }
+    }
+    deleteRepresentation(key) {
+        if (this.representations.delete(key))
+            this.markDirty();
+    }
+    readNegativeRepresentation(key) {
+        return readLru(this.negatives, key);
+    }
+    writeNegativeRepresentation(input) {
+        writeLru(this.negatives, input.key, { reason: input.reason, createdAtEpochMs: this.now(), layer: this.layer }, this.maxEntries);
+        this.markDirty();
+    }
+    deleteNegativeRepresentation(key) {
+        if (this.negatives.delete(key))
+            this.markDirty();
+    }
+    readPlan(key) {
+        const entry = readLru(this.plans, key);
+        return entry ? { entry, layer: "session" } : undefined;
+    }
+    writePlan(input) {
+        writeLru(this.plans, input.key, input.entry, this.maxEntries);
+    }
+    deletePlan(key) {
+        this.plans.delete(key);
+    }
+}
+//# sourceMappingURL=context-budget-v2-cache-disk.js.map

package/dist/core/context-budget-v2-cache-disk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-v2-cache-disk.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-cache-disk.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Workspace-layer disk persistence for the context-budget-v2 representation\n * cache.\n *\n * The in-memory provider (`context-budget-v2-cache-provider.ts`) dies with the\n * process, so every new session re-renders and re-compresses context it already\n * paid for. This provider keeps the same synchronous\n * `ContextBudgetCacheProviderV2` contract and adds a bounded, atomically\n * written JSON snapshot on disk.\n *\n * Scope: representation entries and negative entries only. Plan entries stay in\n * memory on purpose — a plan is session-scoped (its key folds in the\n * invalidation snapshot), so persisting it would only ever store misses.\n *\n * Safety: reads go through the same validator as the memory provider\n * (`validateContextBudgetRepresentationCacheEntryV2`), which re-checks source\n * hash, representation fingerprint, model, tokenizer, policy version and TTL.\n * A corrupt, truncated, oversized, or schema-mismatched snapshot is discarded\n * and the cache simply starts empty; a cache is never load-bearing for\n * correctness.\n */\n\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport { containsCredentialShape } from \"./compaction/transaction.ts\";\nimport {\n\ttype ContextCacheInvalidationSnapshot,\n\tcreateContextCacheInvalidationSnapshot,\n} from \"./context-budget-v2-cache-invalidation.ts\";\nimport type {\n\tContextBudgetCacheLayerV2,\n\tContextBudgetCacheProviderV2,\n\tContextBudgetNegativeCacheEntryV2,\n\tContextBudgetPlanCacheEntryV2,\n\tContextBudgetPlanCacheReadV2,\n\tContextBudgetRepresentationCacheEntryV2,\n\tContextBudgetRepresentationCacheReadV2,\n} from \"./context-budget-v2-types.ts\";\n\nexport const CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION = \"context-budget-v2-diskcache-1\" as const;\n\n/** Default cap on persisted representation entries. */\nexport const DEFAULT_DISK_CACHE_MAX_ENTRIES = 2048;\n/** Default cap on the persisted snapshot size. Oversized snapshots are dropped on load. */\nexport const DEFAULT_DISK_CACHE_MAX_BYTES = 32 * 1024 * 1024;\n/** Default write-behind debounce. Collapses a burst of writes into a single flush. */\nexport const DEFAULT_DISK_CACHE_FLUSH_DEBOUNCE_MS = 750;\n/** Default cap on a single persisted representation's text length. */\nexport const DEFAULT_DISK_CACHE_MAX_ENTRY_TEXT_LENGTH = 512 * 1024;\n\nexport interface DiskContextBudgetCacheOptionsV2 {\n\t/** Directory holding the snapshot file. Created on first flush. */\n\treadonly dir: string;\n\t/** Cache layer reported on reads. Defaults to `workspace`. */\n\treadonly layer?: ContextBudgetCacheLayerV2;\n\t/** Max persisted representation entries (LRU). */\n\treadonly maxEntries?: number;\n\t/** Max accepted snapshot size in bytes. */\n\treadonly maxBytes?: number;\n\t/** Max persisted text length for a single entry. */\n\treadonly maxEntryTextLength?: number;\n\t/** Write-behind debounce in ms. `0` flushes synchronously on every write. */\n\treadonly flushDebounceMs?: number;\n\t/** Injectable clock, for tests. */\n\treadonly now?: () => number;\n}\n\ninterface DiskSnapshotFileV2 {\n\treadonly schemaVersion: typeof CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION;\n\treadonly representations: readonly (readonly [string, ContextBudgetRepresentationCacheEntryV2])[];\n\treadonly negatives: readonly (readonly [string, ContextBudgetNegativeCacheEntryV2])[];\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction containsCredentialShapeInValue(value: unknown): boolean {\n\tconst pending: unknown[] = [value];\n\tconst seen = new Set<object>();\n\twhile (pending.length > 0) {\n\t\tconst current = pending.pop();\n\t\tif (typeof current === \"string\") {\n\t\t\tif (containsCredentialShape(current)) return true;\n\t\t\tcontinue;\n\t\t}\n\t\tif (typeof current !== \"object\" || current === null || seen.has(current)) continue;\n\t\tseen.add(current);\n\t\tif (Array.isArray(current)) {\n\t\t\tpending.push(...current);\n\t\t\tcontinue;\n\t\t}\n\t\tfor (const [key, nested] of Object.entries(current)) {\n\t\t\tif (containsCredentialShape(key)) return true;\n\t\t\tpending.push(nested);\n\t\t}\n\t}\n\treturn false;\n}\n\nfunction isPersistableRepresentation(\n\tvalue: unknown,\n\tmaxEntryTextLength: number,\n): value is ContextBudgetRepresentationCacheEntryV2 {\n\tif (!isRecord(value)) return false;\n\tif (typeof value.kind !== \"string\") return false;\n\tif (typeof value.text !== \"string\" || value.text.length > maxEntryTextLength) return false;\n\tif (containsCredentialShapeInValue(value)) return false;\n\tconst estimated = value.estimatedTokens;\n\tif (typeof estimated !== \"number\" || !Number.isFinite(estimated) || estimated < 0) return false;\n\tif (typeof value.fidelity !== \"string\") return false;\n\tif (typeof value.sourceHash !== \"string\" || value.sourceHash.length === 0) return false;\n\tif (typeof value.representationFingerprint !== \"string\") return false;\n\tif (typeof value.modelId !== \"string\") return false;\n\tif (typeof value.tokenizerId !== \"string\") return false;\n\tif (typeof value.policyVersion !== \"string\") return false;\n\treturn true;\n}\n\nfunction isPersistableNegative(value: unknown): value is ContextBudgetNegativeCacheEntryV2 {\n\treturn isRecord(value) && typeof value.reason === \"string\" && !containsCredentialShapeInValue(value);\n}\n\nfunction readLru<T>(store: Map<string, T>, key: string): T | undefined {\n\tconst entry = store.get(key);\n\tif (entry === undefined) return undefined;\n\tstore.delete(key);\n\tstore.set(key, entry);\n\treturn entry;\n}\n\nfunction writeLru<T>(store: Map<string, T>, key: string, entry: T, maxEntries: number): void {\n\tstore.delete(key);\n\tstore.set(key, entry);\n\twhile (store.size > maxEntries) {\n\t\tconst oldestKey = store.keys().next().value;\n\t\tif (oldestKey === undefined) return;\n\t\tstore.delete(oldestKey);\n\t}\n}\n\n/**\n * Create a disk backed workspace cache provider. Loading is synchronous and\n * best-effort: any failure yields an empty in-memory cache rather than throwing,\n * because a cache miss is always a legal outcome.\n */\nexport function createDiskContextBudgetCacheProviderV2(\n\toptions: DiskContextBudgetCacheOptionsV2,\n): DiskContextBudgetCacheProviderV2 {\n\treturn new DiskContextBudgetCacheProviderV2(options);\n}\n\nexport class DiskContextBudgetCacheProviderV2 implements ContextBudgetCacheProviderV2 {\n\tprivate readonly representations = new Map<string, ContextBudgetRepresentationCacheEntryV2>();\n\tprivate readonly negatives = new Map<string, ContextBudgetNegativeCacheEntryV2>();\n\t/** Plans stay in memory: their keys are session-scoped, so persisting them stores only misses. */\n\tprivate readonly plans = new Map<string, ContextBudgetPlanCacheEntryV2>();\n\tprivate readonly layer: ContextBudgetCacheLayerV2;\n\tprivate readonly maxEntries: number;\n\tprivate readonly maxBytes: number;\n\tprivate readonly maxEntryTextLength: number;\n\tprivate readonly flushDebounceMs: number;\n\tprivate readonly now: () => number;\n\tprivate readonly snapshotPath: string;\n\tprivate invalidationSnapshot: ContextCacheInvalidationSnapshot | undefined;\n\tprivate dirty = false;\n\tprivate flushTimer: ReturnType<typeof setTimeout> | undefined;\n\tprivate loadError: string | undefined;\n\n\tconstructor(options: DiskContextBudgetCacheOptionsV2) {\n\t\tthis.layer = options.layer ?? \"workspace\";\n\t\tthis.maxEntries = Math.max(1, options.maxEntries ?? DEFAULT_DISK_CACHE_MAX_ENTRIES);\n\t\tthis.maxBytes = Math.max(1024, options.maxBytes ?? DEFAULT_DISK_CACHE_MAX_BYTES);\n\t\tthis.maxEntryTextLength = Math.max(1, options.maxEntryTextLength ?? DEFAULT_DISK_CACHE_MAX_ENTRY_TEXT_LENGTH);\n\t\tthis.flushDebounceMs = Math.max(0, options.flushDebounceMs ?? DEFAULT_DISK_CACHE_FLUSH_DEBOUNCE_MS);\n\t\tthis.now = options.now ?? Date.now;\n\t\tthis.snapshotPath = path.join(options.dir, \"representations.json\");\n\t\tthis.load();\n\t}\n\n\t/** Absolute path of the persisted snapshot. */\n\tget snapshotFilePath(): string {\n\t\treturn this.snapshotPath;\n\t}\n\n\t/** Reason the on-disk snapshot was rejected, if it was. `undefined` on a clean load or a cold start. */\n\tget lastLoadError(): string | undefined {\n\t\treturn this.loadError;\n\t}\n\n\t/** Number of representation entries currently held. */\n\tget size(): number {\n\t\treturn this.representations.size;\n\t}\n\n\tprivate load(): void {\n\t\tlet raw: string;\n\t\ttry {\n\t\t\tconst stat = fs.statSync(this.snapshotPath);\n\t\t\tif (stat.size > this.maxBytes) {\n\t\t\t\tthis.loadError = `snapshot exceeds maxBytes (${stat.size} > ${this.maxBytes})`;\n\t\t\t\treturn;\n\t\t\t}\n\t\t\traw = fs.readFileSync(this.snapshotPath, \"utf8\");\n\t\t} catch {\n\t\t\t// Cold start: no snapshot yet, or it is unreadable. Both are normal.\n\t\t\treturn;\n\t\t}\n\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(raw);\n\t\t} catch {\n\t\t\tthis.loadError = \"snapshot is not valid JSON\";\n\t\t\treturn;\n\t\t}\n\t\tif (!isRecord(parsed) || parsed.schemaVersion !== CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION) {\n\t\t\tthis.loadError = \"snapshot schema mismatch\";\n\t\t\treturn;\n\t\t}\n\n\t\tif (containsCredentialShapeInValue(parsed)) {\n\t\t\tthis.loadError = \"snapshot contains credential-shaped text\";\n\t\t\ttry {\n\t\t\t\tfs.rmSync(this.snapshotPath, { force: true });\n\t\t\t} catch {\n\t\t\t\t// The unsafe snapshot remains unreadable to this provider.\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\n\t\tconst representations = Array.isArray(parsed.representations) ? parsed.representations : [];\n\t\tfor (const pair of representations) {\n\t\t\tif (!Array.isArray(pair) || pair.length !== 2) continue;\n\t\t\tconst [key, entry] = pair as [unknown, unknown];\n\t\t\tif (typeof key !== \"string\" || key.length === 0) continue;\n\t\t\tif (!isPersistableRepresentation(entry, this.maxEntryTextLength)) continue;\n\t\t\twriteLru(this.representations, key, entry, this.maxEntries);\n\t\t}\n\n\t\tconst negatives = Array.isArray(parsed.negatives) ? parsed.negatives : [];\n\t\tfor (const pair of negatives) {\n\t\t\tif (!Array.isArray(pair) || pair.length !== 2) continue;\n\t\t\tconst [key, entry] = pair as [unknown, unknown];\n\t\t\tif (typeof key !== \"string\" || key.length === 0) continue;\n\t\t\tif (!isPersistableNegative(entry)) continue;\n\t\t\twriteLru(this.negatives, key, entry, this.maxEntries);\n\t\t}\n\t}\n\n\tprivate markDirty(): void {\n\t\tthis.dirty = true;\n\t\tif (this.flushDebounceMs === 0) {\n\t\t\tthis.flush();\n\t\t\treturn;\n\t\t}\n\t\tif (this.flushTimer !== undefined) return;\n\t\tthis.flushTimer = setTimeout(() => {\n\t\t\tthis.flushTimer = undefined;\n\t\t\tthis.flush();\n\t\t}, this.flushDebounceMs);\n\t\tthis.flushTimer.unref?.();\n\t}\n\n\t/**\n\t * Write the snapshot to disk atomically (temp file + rename). Best-effort:\n\t * a failed flush leaves the previous snapshot intact and keeps the entries\n\t * in memory. Returns `true` when a snapshot was written.\n\t */\n\tflush(): boolean {\n\t\tif (this.flushTimer !== undefined) {\n\t\t\tclearTimeout(this.flushTimer);\n\t\t\tthis.flushTimer = undefined;\n\t\t}\n\t\tif (!this.dirty) return false;\n\t\tconst snapshot: DiskSnapshotFileV2 = {\n\t\t\tschemaVersion: CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION,\n\t\t\trepresentations: [...this.representations.entries()]\n\t\t\t\t.filter(\n\t\t\t\t\t([key, entry]) =>\n\t\t\t\t\t\t!containsCredentialShape(key) && isPersistableRepresentation(entry, this.maxEntryTextLength),\n\t\t\t\t)\n\t\t\t\t.map(([key, entry]) => [key, entry] as const),\n\t\t\tnegatives: [...this.negatives.entries()]\n\t\t\t\t.filter(([key, entry]) => !containsCredentialShape(key) && isPersistableNegative(entry))\n\t\t\t\t.map(([key, entry]) => [key, entry] as const),\n\t\t};\n\t\tlet serialized: string;\n\t\ttry {\n\t\t\tserialized = JSON.stringify(snapshot);\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t\tif (Buffer.byteLength(serialized, \"utf8\") > this.maxBytes) {\n\t\t\t// Drop the oldest half and retry once rather than growing forever.\n\t\t\tconst keys = [...this.representations.keys()];\n\t\t\tif (keys.length === 0) return false;\n\t\t\tconst dropCount = Math.max(1, Math.ceil(keys.length / 2));\n\t\t\tfor (const key of keys.slice(0, dropCount)) this.representations.delete(key);\n\t\t\treturn this.flush();\n\t\t}\n\t\tconst tempPath = `${this.snapshotPath}.${process.pid}.tmp`;\n\t\ttry {\n\t\t\tfs.mkdirSync(path.dirname(this.snapshotPath), { recursive: true });\n\t\t\tfs.writeFileSync(tempPath, serialized, { encoding: \"utf8\", mode: 0o600 });\n\t\t\tfs.renameSync(tempPath, this.snapshotPath);\n\t\t\tthis.dirty = false;\n\t\t\treturn true;\n\t\t} catch {\n\t\t\ttry {\n\t\t\t\tfs.rmSync(tempPath, { force: true });\n\t\t\t} catch {\n\t\t\t\t// The temp file is unlinkable; nothing further to do.\n\t\t\t}\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Cancel any pending flush and persist immediately. Safe to call more than once. */\n\tclose(): void {\n\t\tthis.flush();\n\t}\n\n\tgetInvalidationSnapshot(): ContextCacheInvalidationSnapshot | undefined {\n\t\treturn this.invalidationSnapshot;\n\t}\n\n\tsetInvalidationSnapshot(snapshot: ContextCacheInvalidationSnapshot): void {\n\t\tthis.invalidationSnapshot = createContextCacheInvalidationSnapshot({\n\t\t\tforkId: snapshot.forkId,\n\t\t\tworktreeFingerprint: snapshot.worktreeFingerprint,\n\t\t\tactiveModelId: snapshot.activeModelId,\n\t\t\tcompactionModelId: snapshot.compactionModelId,\n\t\t\tglobalEpoch: snapshot.globalEpoch,\n\t\t\ttranscriptRepair: snapshot.counters.transcriptRepair,\n\t\t\ttoolResultDisposition: snapshot.counters.toolResultDisposition,\n\t\t\tevidenceReceipt: snapshot.counters.evidenceReceipt,\n\t\t\tuserSteering: snapshot.counters.userSteering,\n\t\t\tsettings: snapshot.counters.settings,\n\t\t});\n\t}\n\n\treadRepresentation(key: string): ContextBudgetRepresentationCacheReadV2 | undefined {\n\t\tconst entry = readLru(this.representations, key);\n\t\treturn entry ? { entry, layer: this.layer } : undefined;\n\t}\n\n\twriteRepresentation(input: { readonly key: string; readonly entry: ContextBudgetRepresentationCacheEntryV2 }): void {\n\t\twriteLru(this.representations, input.key, input.entry, this.maxEntries);\n\t\tif (\n\t\t\t(!containsCredentialShape(input.key) && isPersistableRepresentation(input.entry, this.maxEntryTextLength)) ||\n\t\t\tfs.existsSync(this.snapshotPath)\n\t\t) {\n\t\t\tthis.markDirty();\n\t\t}\n\t}\n\n\tdeleteRepresentation(key: string): void {\n\t\tif (this.representations.delete(key)) this.markDirty();\n\t}\n\n\treadNegativeRepresentation(key: string): ContextBudgetNegativeCacheEntryV2 | undefined {\n\t\treturn readLru(this.negatives, key);\n\t}\n\n\twriteNegativeRepresentation(input: { readonly key: string; readonly reason: string }): void {\n\t\twriteLru(\n\t\t\tthis.negatives,\n\t\t\tinput.key,\n\t\t\t{ reason: input.reason, createdAtEpochMs: this.now(), layer: this.layer },\n\t\t\tthis.maxEntries,\n\t\t);\n\t\tthis.markDirty();\n\t}\n\n\tdeleteNegativeRepresentation(key: string): void {\n\t\tif (this.negatives.delete(key)) this.markDirty();\n\t}\n\n\treadPlan(key: string): ContextBudgetPlanCacheReadV2 | undefined {\n\t\tconst entry = readLru(this.plans, key);\n\t\treturn entry ? { entry, layer: \"session\" } : undefined;\n\t}\n\n\twritePlan(input: { readonly key: string; readonly entry: ContextBudgetPlanCacheEntryV2 }): void {\n\t\twriteLru(this.plans, input.key, input.entry, this.maxEntries);\n\t}\n\n\tdeletePlan(key: string): void {\n\t\tthis.plans.delete(key);\n\t}\n}\n"]}

package/dist/core/context-budget-v2-cache-keys.d.ts

@@ -3,6 +3,24 @@ import { type ContextCacheInvalidationSnapshot } from "./context-budget-v2-cache
 export declare const DEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2 = "context-budget-v2-default-compressor";
 export declare const DEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2 = "context-budget-v2-default-quality";
 type ContextBudgetRepresentationFingerprintInputV2 = Pick<ContextRepresentationCandidateV2, "compressorId" | "estimatedTokens" | "fidelity" | "kind" | "sourceRef" | "summaryHash" | "text">;
+/**
+ * Cache-key inputs shared by the plan cache and the representation cache.
+ *
+ * Scope contract (deliberate asymmetry — see the two builders below):
+ * - **Plan keys are session-scoped.** A plan is a selection over the whole
+ *   transcript and runtime state, so {@link invalidationSnapshotHash} (fork id,
+ *   worktree fingerprint, steering/repair/settings counters) is part of the key.
+ * - **Representation keys are content-addressed.** A rendered representation is
+ *   fully identified by its source content plus the rendering policy, so the
+ *   invalidation snapshot is deliberately *excluded*. Folding a per-session
+ *   `forkId` into representation keys made every new session miss every entry
+ *   (structurally unreachable reuse, not a cold cache), while adding no safety:
+ *   `validateContextBudgetRepresentationCacheEntryV2` independently re-checks
+ *   source hash, fingerprint, model, tokenizer, policy version, and
+ *   TTL on every read, and worktree/model/redaction/safety changes already move
+ *   the key through `sourceHash` / `modelId` / `redactionPolicyHash` /
+ *   `safetyProfileHash`.
+ */
 export interface ContextBudgetCacheKeyBaseV2 {
     readonly namespace: string;
     readonly modelId: string;
@@ -39,6 +57,10 @@ export declare function buildContextBudgetRepresentationCacheKeyV2(input: Contex
     readonly representationFingerprint?: string;
     readonly compressorId?: string;
 }): string;
+/**
+ * Exact representation key. Content-addressed: identical content + rendering
+ * policy yields one key across queries, budgets, sessions, forks, and worktrees.
+ */
 export declare function buildContextBudgetExactRepresentationCacheKeyV2(input: ContextBudgetCacheKeyBaseV2 & {
     readonly representationKind: ContextRepresentationKindV2;
     readonly sourceHash: string;

package/dist/core/context-budget-v2-cache-keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget-v2-cache-keys.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-cache-keys.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ContextRepresentationCandidateV2, ContextRepresentationKindV2 } from \"./context-budget-headroom.ts\";\nimport { sha256Canonical, sha256Hex } from \"./context-budget-v2-cache-hash.ts\";\nimport {\n\ttype ContextCacheInvalidationSnapshot,\n\tserializeContextCacheSnapshot,\n} from \"./context-budget-v2-cache-invalidation.ts\";\n\nconst DEFAULT_CACHE_NAMESPACE = \"context-budget-v2\";\nconst DEFAULT_TOKENIZER_ID = \"heuristic-v1\";\nconst DEFAULT_REDACTION_POLICY_HASH = \"none\";\nconst DEFAULT_SAFETY_PROFILE_HASH = \"default\";\nconst NO_COMPRESSOR_ID = \"none\";\nexport const DEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2 = \"context-budget-v2-default-compressor\";\nexport const DEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2 = \"context-budget-v2-default-quality\";\nconst MATERIALIZED_TARGET_TOKEN_BUCKET_SIZE = 100;\n\ntype ContextBudgetRepresentationFingerprintInputV2 = Pick<\n\tContextRepresentationCandidateV2,\n\t\"compressorId\" | \"estimatedTokens\" | \"fidelity\" | \"kind\" | \"sourceRef\" | \"summaryHash\" | \"text\"\n>;\n\nexport interface ContextBudgetCacheKeyBaseV2 {\n\treadonly namespace: string;\n\treadonly modelId: string;\n\treadonly tokenizerId: string;\n\treadonly policyVersion: string;\n\treadonly queryIntentHash: string;\n\treadonly queryIntentCluster?: string;\n\treadonly budgetBucket: string;\n\treadonly redactionPolicyHash: string;\n\treadonly safetyProfileHash: string;\n\treadonly compressorPolicyHash?: string;\n\treadonly qualityPolicyHash?: string;\n\treadonly invalidationSnapshotHash?: string;\n}\n\nexport function createContextBudgetCacheKeyBaseV2(input: {\n\treadonly namespace?: string;\n\treadonly modelId: string;\n\treadonly tokenizerId?: string;\n\treadonly policyVersion: string;\n\treadonly query?: string;\n\treadonly queryIntentHash?: string;\n\treadonly queryIntentCluster?: string;\n\treadonly budgetBucket?: string;\n\treadonly redactionPolicyHash?: string;\n\treadonly safetyProfileHash?: string;\n\treadonly compressorPolicyHash?: string;\n\treadonly qualityPolicyHash?: string;\n\treadonly cacheInvalidationSnapshot?: ContextCacheInvalidationSnapshot;\n}): ContextBudgetCacheKeyBaseV2 {\n\tconst queryIntentHash = input.queryIntentHash ?? computeContextBudgetQueryIntentHashV2(input.query);\n\treturn {\n\t\tnamespace: input.namespace ?? DEFAULT_CACHE_NAMESPACE,\n\t\tmodelId: input.modelId,\n\t\ttokenizerId: input.tokenizerId ?? DEFAULT_TOKENIZER_ID,\n\t\tpolicyVersion: input.policyVersion,\n\t\tqueryIntentHash,\n\t\tqueryIntentCluster: input.queryIntentCluster ?? queryIntentHash,\n\t\tbudgetBucket: input.budgetBucket ?? \"unknown\",\n\t\tredactionPolicyHash: input.redactionPolicyHash ?? DEFAULT_REDACTION_POLICY_HASH,\n\t\tsafetyProfileHash: input.safetyProfileHash ?? DEFAULT_SAFETY_PROFILE_HASH,\n\t\tcompressorPolicyHash: input.compressorPolicyHash ?? DEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2,\n\t\tqualityPolicyHash: input.qualityPolicyHash ?? DEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2,\n\t\tinvalidationSnapshotHash:\n\t\t\tinput.cacheInvalidationSnapshot === undefined\n\t\t\t\t? \"none\"\n\t\t\t\t: sha256Hex(serializeContextCacheSnapshot(input.cacheInvalidationSnapshot)),\n\t};\n}\n\nexport function computeContextBudgetQueryIntentHashV2(query: string | undefined): string {\n\tconst normalized = (query ?? \"\")\n\t\t.toLowerCase()\n\t\t.split(/[\\s,.;:!?()[\\]{}\"'`]+/u)\n\t\t.map((term) => term.trim())\n\t\t.filter((term) => term.length > 0)\n\t\t.sort()\n\t\t.join(\" \");\n\treturn sha256Hex(normalized.length > 0 ? normalized : \"none\");\n}\n\nexport function buildContextBudgetRepresentationCacheKeyV2(\n\tinput: ContextBudgetCacheKeyBaseV2 & {\n\t\treadonly representationKind: ContextRepresentationKindV2;\n\t\treadonly sourceHash: string;\n\t\treadonly representationFingerprint?: string;\n\t\treadonly compressorId?: string;\n\t},\n): string {\n\treturn buildContextBudgetExactRepresentationCacheKeyV2(input);\n}\n\nexport function buildContextBudgetExactRepresentationCacheKeyV2(\n\tinput: ContextBudgetCacheKeyBaseV2 & {\n\t\treadonly representationKind: ContextRepresentationKindV2;\n\t\treadonly sourceHash: string;\n\t\treadonly representationFingerprint?: string;\n\t\treadonly compressorId?: string;\n\t},\n): string {\n\treturn `context-representation-exact:${sha256Canonical({\n\t\tbudgetBucket: input.budgetBucket,\n\t\tcompressorId: input.compressorId ?? NO_COMPRESSOR_ID,\n\t\tinvalidationSnapshotHash: input.invalidationSnapshotHash ?? \"none\",\n\t\tmodelId: input.modelId,\n\t\tnamespace: input.namespace,\n\t\tpolicyVersion: input.policyVersion,\n\t\tqueryIntentHash: input.queryIntentHash,\n\t\tredactionPolicyHash: input.redactionPolicyHash,\n\t\trepresentationFingerprint: input.representationFingerprint ?? \"none\",\n\t\trepresentationKind: input.representationKind,\n\t\tsafetyProfileHash: input.safetyProfileHash,\n\t\tsourceHash: input.sourceHash,\n\t\ttokenizerId: input.tokenizerId,\n\t})}`;\n}\n\nexport function buildContextBudgetMaterializedRepresentationCacheKeyV2(\n\tinput: ContextBudgetCacheKeyBaseV2 & {\n\t\treadonly representationKind: ContextRepresentationKindV2;\n\t\treadonly sourceHash: string;\n\t\treadonly compressorId?: string;\n\t\treadonly targetTokenBucket: number;\n\t},\n): string {\n\treturn `context-representation-materialized:${sha256Canonical({\n\t\tbudgetBucket: input.budgetBucket,\n\t\tcompressorId: input.compressorId ?? NO_COMPRESSOR_ID,\n\t\tcompressorPolicyHash: input.compressorPolicyHash ?? DEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2,\n\t\tinvalidationSnapshotHash: input.invalidationSnapshotHash ?? \"none\",\n\t\tmodelId: input.modelId,\n\t\tnamespace: input.namespace,\n\t\tpolicyVersion: input.policyVersion,\n\t\tqualityPolicyHash: input.qualityPolicyHash ?? DEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2,\n\t\tqueryIntentCluster: input.queryIntentCluster ?? input.queryIntentHash,\n\t\tqueryIntentHash: input.queryIntentHash,\n\t\tredactionPolicyHash: input.redactionPolicyHash,\n\t\trepresentationKind: input.representationKind,\n\t\tsafetyProfileHash: input.safetyProfileHash,\n\t\tsourceHash: input.sourceHash,\n\t\ttargetTokenBucket: input.targetTokenBucket,\n\t\ttokenizerId: input.tokenizerId,\n\t})}`;\n}\n\nexport function computeContextBudgetRepresentationFingerprintV2(\n\tcandidate: ContextBudgetRepresentationFingerprintInputV2,\n): string {\n\treturn sha256Canonical({\n\t\tcompressorId: candidate.compressorId ?? NO_COMPRESSOR_ID,\n\t\testimatedTokens: candidate.estimatedTokens,\n\t\tfidelity: candidate.fidelity,\n\t\tkind: candidate.kind,\n\t\tsourceRef: fingerprintSourceRef(candidate.sourceRef),\n\t\tsummaryHash: candidate.summaryHash ?? null,\n\t\ttextHash: sha256Hex(candidate.text),\n\t});\n}\n\nexport function buildContextBudgetRepresentationCandidateKeyV2(\n\tkeyBase: ContextBudgetCacheKeyBaseV2,\n\tcandidate: ContextBudgetRepresentationFingerprintInputV2,\n\tsourceHash: string,\n): string {\n\treturn buildContextBudgetExactRepresentationCacheKeyV2({\n\t\t...keyBase,\n\t\tcompressorId: candidate.compressorId ?? NO_COMPRESSOR_ID,\n\t\trepresentationFingerprint: computeContextBudgetRepresentationFingerprintV2(candidate),\n\t\trepresentationKind: candidate.kind,\n\t\tsourceHash,\n\t});\n}\n\nexport function buildContextBudgetMaterializedRepresentationCandidateKeyV2(\n\tkeyBase: ContextBudgetCacheKeyBaseV2,\n\tcandidate: ContextBudgetRepresentationFingerprintInputV2,\n\tsourceHash: string,\n): string {\n\treturn buildContextBudgetMaterializedRepresentationCacheKeyV2({\n\t\t...keyBase,\n\t\tcompressorId: candidate.compressorId ?? NO_COMPRESSOR_ID,\n\t\trepresentationKind: candidate.kind,\n\t\tsourceHash,\n\t\ttargetTokenBucket: computeContextBudgetTargetTokenBucketV2(candidate.estimatedTokens),\n\t});\n}\n\nexport function computeContextBudgetTargetTokenBucketV2(tokens: number): number {\n\tif (!Number.isFinite(tokens) || tokens <= 0) {\n\t\treturn MATERIALIZED_TARGET_TOKEN_BUCKET_SIZE;\n\t}\n\treturn MATERIALIZED_TARGET_TOKEN_BUCKET_SIZE * Math.ceil(tokens / MATERIALIZED_TARGET_TOKEN_BUCKET_SIZE);\n}\n\nexport function computeContextBudgetOutputTextHashV2(text: string): string {\n\treturn sha256Hex(text);\n}\n\nexport function fingerprintSourceRef(sourceRef: ContextRepresentationCandidateV2[\"sourceRef\"]): unknown {\n\tif (!sourceRef) return null;\n\treturn {\n\t\tcontentHash: sourceRef.contentHash,\n\t\trange: sourceRef.range\n\t\t\t? {\n\t\t\t\t\tendLine: sourceRef.range.endLine,\n\t\t\t\t\tstartLine: sourceRef.range.startLine,\n\t\t\t\t}\n\t\t\t: null,\n\t\tretrievable: sourceRef.retrievable,\n\t\tsymbol: sourceRef.symbol ?? null,\n\t\turi: sourceRef.uri,\n\t};\n}\n"]}
+{"version":3,"file":"context-budget-v2-cache-keys.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-cache-keys.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ContextRepresentationCandidateV2, ContextRepresentationKindV2 } from \"./context-budget-headroom.ts\";\nimport { sha256Canonical, sha256Hex } from \"./context-budget-v2-cache-hash.ts\";\nimport {\n\ttype ContextCacheInvalidationSnapshot,\n\tserializeContextCacheSnapshot,\n} from \"./context-budget-v2-cache-invalidation.ts\";\n\nconst DEFAULT_CACHE_NAMESPACE = \"context-budget-v2\";\nconst DEFAULT_TOKENIZER_ID = \"heuristic-v1\";\nconst DEFAULT_REDACTION_POLICY_HASH = \"none\";\nconst DEFAULT_SAFETY_PROFILE_HASH = \"default\";\nconst NO_COMPRESSOR_ID = \"none\";\nexport const DEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2 = \"context-budget-v2-default-compressor\";\nexport const DEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2 = \"context-budget-v2-default-quality\";\nconst MATERIALIZED_TARGET_TOKEN_BUCKET_SIZE = 100;\n\ntype ContextBudgetRepresentationFingerprintInputV2 = Pick<\n\tContextRepresentationCandidateV2,\n\t\"compressorId\" | \"estimatedTokens\" | \"fidelity\" | \"kind\" | \"sourceRef\" | \"summaryHash\" | \"text\"\n>;\n\n/**\n * Cache-key inputs shared by the plan cache and the representation cache.\n *\n * Scope contract (deliberate asymmetry — see the two builders below):\n * - **Plan keys are session-scoped.** A plan is a selection over the whole\n *   transcript and runtime state, so {@link invalidationSnapshotHash} (fork id,\n *   worktree fingerprint, steering/repair/settings counters) is part of the key.\n * - **Representation keys are content-addressed.** A rendered representation is\n *   fully identified by its source content plus the rendering policy, so the\n *   invalidation snapshot is deliberately *excluded*. Folding a per-session\n *   `forkId` into representation keys made every new session miss every entry\n *   (structurally unreachable reuse, not a cold cache), while adding no safety:\n *   `validateContextBudgetRepresentationCacheEntryV2` independently re-checks\n *   source hash, fingerprint, model, tokenizer, policy version, and\n *   TTL on every read, and worktree/model/redaction/safety changes already move\n *   the key through `sourceHash` / `modelId` / `redactionPolicyHash` /\n *   `safetyProfileHash`.\n */\nexport interface ContextBudgetCacheKeyBaseV2 {\n\treadonly namespace: string;\n\treadonly modelId: string;\n\treadonly tokenizerId: string;\n\treadonly policyVersion: string;\n\treadonly queryIntentHash: string;\n\treadonly queryIntentCluster?: string;\n\treadonly budgetBucket: string;\n\treadonly redactionPolicyHash: string;\n\treadonly safetyProfileHash: string;\n\treadonly compressorPolicyHash?: string;\n\treadonly qualityPolicyHash?: string;\n\treadonly invalidationSnapshotHash?: string;\n}\n\nexport function createContextBudgetCacheKeyBaseV2(input: {\n\treadonly namespace?: string;\n\treadonly modelId: string;\n\treadonly tokenizerId?: string;\n\treadonly policyVersion: string;\n\treadonly query?: string;\n\treadonly queryIntentHash?: string;\n\treadonly queryIntentCluster?: string;\n\treadonly budgetBucket?: string;\n\treadonly redactionPolicyHash?: string;\n\treadonly safetyProfileHash?: string;\n\treadonly compressorPolicyHash?: string;\n\treadonly qualityPolicyHash?: string;\n\treadonly cacheInvalidationSnapshot?: ContextCacheInvalidationSnapshot;\n}): ContextBudgetCacheKeyBaseV2 {\n\tconst queryIntentHash = input.queryIntentHash ?? computeContextBudgetQueryIntentHashV2(input.query);\n\treturn {\n\t\tnamespace: input.namespace ?? DEFAULT_CACHE_NAMESPACE,\n\t\tmodelId: input.modelId,\n\t\ttokenizerId: input.tokenizerId ?? DEFAULT_TOKENIZER_ID,\n\t\tpolicyVersion: input.policyVersion,\n\t\tqueryIntentHash,\n\t\tqueryIntentCluster: input.queryIntentCluster ?? queryIntentHash,\n\t\tbudgetBucket: input.budgetBucket ?? \"unknown\",\n\t\tredactionPolicyHash: input.redactionPolicyHash ?? DEFAULT_REDACTION_POLICY_HASH,\n\t\tsafetyProfileHash: input.safetyProfileHash ?? DEFAULT_SAFETY_PROFILE_HASH,\n\t\tcompressorPolicyHash: input.compressorPolicyHash ?? DEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2,\n\t\tqualityPolicyHash: input.qualityPolicyHash ?? DEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2,\n\t\tinvalidationSnapshotHash:\n\t\t\tinput.cacheInvalidationSnapshot === undefined\n\t\t\t\t? \"none\"\n\t\t\t\t: sha256Hex(serializeContextCacheSnapshot(input.cacheInvalidationSnapshot)),\n\t};\n}\n\nexport function computeContextBudgetQueryIntentHashV2(query: string | undefined): string {\n\tconst normalized = (query ?? \"\")\n\t\t.toLowerCase()\n\t\t.split(/[\\s,.;:!?()[\\]{}\"'`]+/u)\n\t\t.map((term) => term.trim())\n\t\t.filter((term) => term.length > 0)\n\t\t.sort()\n\t\t.join(\" \");\n\treturn sha256Hex(normalized.length > 0 ? normalized : \"none\");\n}\n\nexport function buildContextBudgetRepresentationCacheKeyV2(\n\tinput: ContextBudgetCacheKeyBaseV2 & {\n\t\treadonly representationKind: ContextRepresentationKindV2;\n\t\treadonly sourceHash: string;\n\t\treadonly representationFingerprint?: string;\n\t\treadonly compressorId?: string;\n\t},\n): string {\n\treturn buildContextBudgetExactRepresentationCacheKeyV2(input);\n}\n\n/**\n * Exact representation key. Content-addressed: identical content + rendering\n * policy yields one key across queries, budgets, sessions, forks, and worktrees.\n */\nexport function buildContextBudgetExactRepresentationCacheKeyV2(\n\tinput: ContextBudgetCacheKeyBaseV2 & {\n\t\treadonly representationKind: ContextRepresentationKindV2;\n\t\treadonly sourceHash: string;\n\t\treadonly representationFingerprint?: string;\n\t\treadonly compressorId?: string;\n\t},\n): string {\n\treturn `context-representation-exact:${sha256Canonical({\n\t\tcompressorId: input.compressorId ?? NO_COMPRESSOR_ID,\n\t\tmodelId: input.modelId,\n\t\tnamespace: input.namespace,\n\t\tpolicyVersion: input.policyVersion,\n\t\tredactionPolicyHash: input.redactionPolicyHash,\n\t\trepresentationFingerprint: input.representationFingerprint ?? \"none\",\n\t\trepresentationKind: input.representationKind,\n\t\tsafetyProfileHash: input.safetyProfileHash,\n\t\tsourceHash: input.sourceHash,\n\t\ttokenizerId: input.tokenizerId,\n\t})}`;\n}\n\nexport function buildContextBudgetMaterializedRepresentationCacheKeyV2(\n\tinput: ContextBudgetCacheKeyBaseV2 & {\n\t\treadonly representationKind: ContextRepresentationKindV2;\n\t\treadonly sourceHash: string;\n\t\treadonly compressorId?: string;\n\t\treadonly targetTokenBucket: number;\n\t},\n): string {\n\treturn `context-representation-materialized:${sha256Canonical({\n\t\tbudgetBucket: input.budgetBucket,\n\t\tcompressorId: input.compressorId ?? NO_COMPRESSOR_ID,\n\t\tcompressorPolicyHash: input.compressorPolicyHash ?? DEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2,\n\t\tmodelId: input.modelId,\n\t\tnamespace: input.namespace,\n\t\tpolicyVersion: input.policyVersion,\n\t\tqualityPolicyHash: input.qualityPolicyHash ?? DEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2,\n\t\tqueryIntentCluster: input.queryIntentCluster ?? input.queryIntentHash,\n\t\tqueryIntentHash: input.queryIntentHash,\n\t\tredactionPolicyHash: input.redactionPolicyHash,\n\t\trepresentationKind: input.representationKind,\n\t\tsafetyProfileHash: input.safetyProfileHash,\n\t\tsourceHash: input.sourceHash,\n\t\ttargetTokenBucket: input.targetTokenBucket,\n\t\ttokenizerId: input.tokenizerId,\n\t})}`;\n}\n\nexport function computeContextBudgetRepresentationFingerprintV2(\n\tcandidate: ContextBudgetRepresentationFingerprintInputV2,\n): string {\n\treturn sha256Canonical({\n\t\tcompressorId: candidate.compressorId ?? NO_COMPRESSOR_ID,\n\t\testimatedTokens: candidate.estimatedTokens,\n\t\tfidelity: candidate.fidelity,\n\t\tkind: candidate.kind,\n\t\tsourceRef: fingerprintSourceRef(candidate.sourceRef),\n\t\tsummaryHash: candidate.summaryHash ?? null,\n\t\ttextHash: sha256Hex(candidate.text),\n\t});\n}\n\nexport function buildContextBudgetRepresentationCandidateKeyV2(\n\tkeyBase: ContextBudgetCacheKeyBaseV2,\n\tcandidate: ContextBudgetRepresentationFingerprintInputV2,\n\tsourceHash: string,\n): string {\n\treturn buildContextBudgetExactRepresentationCacheKeyV2({\n\t\t...keyBase,\n\t\tcompressorId: candidate.compressorId ?? NO_COMPRESSOR_ID,\n\t\trepresentationFingerprint: computeContextBudgetRepresentationFingerprintV2(candidate),\n\t\trepresentationKind: candidate.kind,\n\t\tsourceHash,\n\t});\n}\n\nexport function buildContextBudgetMaterializedRepresentationCandidateKeyV2(\n\tkeyBase: ContextBudgetCacheKeyBaseV2,\n\tcandidate: ContextBudgetRepresentationFingerprintInputV2,\n\tsourceHash: string,\n): string {\n\treturn buildContextBudgetMaterializedRepresentationCacheKeyV2({\n\t\t...keyBase,\n\t\tcompressorId: candidate.compressorId ?? NO_COMPRESSOR_ID,\n\t\trepresentationKind: candidate.kind,\n\t\tsourceHash,\n\t\ttargetTokenBucket: computeContextBudgetTargetTokenBucketV2(candidate.estimatedTokens),\n\t});\n}\n\nexport function computeContextBudgetTargetTokenBucketV2(tokens: number): number {\n\tif (!Number.isFinite(tokens) || tokens <= 0) {\n\t\treturn MATERIALIZED_TARGET_TOKEN_BUCKET_SIZE;\n\t}\n\treturn MATERIALIZED_TARGET_TOKEN_BUCKET_SIZE * Math.ceil(tokens / MATERIALIZED_TARGET_TOKEN_BUCKET_SIZE);\n}\n\nexport function computeContextBudgetOutputTextHashV2(text: string): string {\n\treturn sha256Hex(text);\n}\n\nexport function fingerprintSourceRef(sourceRef: ContextRepresentationCandidateV2[\"sourceRef\"]): unknown {\n\tif (!sourceRef) return null;\n\treturn {\n\t\tcontentHash: sourceRef.contentHash,\n\t\trange: sourceRef.range\n\t\t\t? {\n\t\t\t\t\tendLine: sourceRef.range.endLine,\n\t\t\t\t\tstartLine: sourceRef.range.startLine,\n\t\t\t\t}\n\t\t\t: null,\n\t\tretrievable: sourceRef.retrievable,\n\t\tsymbol: sourceRef.symbol ?? null,\n\t\turi: sourceRef.uri,\n\t};\n}\n"]}

package/dist/core/context-budget-v2-cache-keys.js

@@ -40,15 +40,16 @@ export function computeContextBudgetQueryIntentHashV2(query) {
 export function buildContextBudgetRepresentationCacheKeyV2(input) {
     return buildContextBudgetExactRepresentationCacheKeyV2(input);
 }
+/**
+ * Exact representation key. Content-addressed: identical content + rendering
+ * policy yields one key across queries, budgets, sessions, forks, and worktrees.
+ */
 export function buildContextBudgetExactRepresentationCacheKeyV2(input) {
     return `context-representation-exact:${sha256Canonical({
-        budgetBucket: input.budgetBucket,
         compressorId: input.compressorId ?? NO_COMPRESSOR_ID,
-        invalidationSnapshotHash: input.invalidationSnapshotHash ?? "none",
         modelId: input.modelId,
         namespace: input.namespace,
         policyVersion: input.policyVersion,
-        queryIntentHash: input.queryIntentHash,
         redactionPolicyHash: input.redactionPolicyHash,
         representationFingerprint: input.representationFingerprint ?? "none",
         representationKind: input.representationKind,
@@ -62,7 +63,6 @@ export function buildContextBudgetMaterializedRepresentationCacheKeyV2(input) {
         budgetBucket: input.budgetBucket,
         compressorId: input.compressorId ?? NO_COMPRESSOR_ID,
         compressorPolicyHash: input.compressorPolicyHash ?? DEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2,
-        invalidationSnapshotHash: input.invalidationSnapshotHash ?? "none",
         modelId: input.modelId,
         namespace: input.namespace,
         policyVersion: input.policyVersion,

package/dist/core/context-budget-v2-cache-keys.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget-v2-cache-keys.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-cache-keys.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ContextRepresentationCandidateV2, ContextRepresentationKindV2 } from \"./context-budget-headroom.ts\";\nimport { sha256Canonical, sha256Hex } from \"./context-budget-v2-cache-hash.ts\";\nimport {\n\ttype ContextCacheInvalidationSnapshot,\n\tserializeContextCacheSnapshot,\n} from \"./context-budget-v2-cache-invalidation.ts\";\n\nconst DEFAULT_CACHE_NAMESPACE = \"context-budget-v2\";\nconst DEFAULT_TOKENIZER_ID = \"heuristic-v1\";\nconst DEFAULT_REDACTION_POLICY_HASH = \"none\";\nconst DEFAULT_SAFETY_PROFILE_HASH = \"default\";\nconst NO_COMPRESSOR_ID = \"none\";\nexport const DEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2 = \"context-budget-v2-default-compressor\";\nexport const DEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2 = \"context-budget-v2-default-quality\";\nconst MATERIALIZED_TARGET_TOKEN_BUCKET_SIZE = 100;\n\ntype ContextBudgetRepresentationFingerprintInputV2 = Pick<\n\tContextRepresentationCandidateV2,\n\t\"compressorId\" | \"estimatedTokens\" | \"fidelity\" | \"kind\" | \"sourceRef\" | \"summaryHash\" | \"text\"\n>;\n\nexport interface ContextBudgetCacheKeyBaseV2 {\n\treadonly namespace: string;\n\treadonly modelId: string;\n\treadonly tokenizerId: string;\n\treadonly policyVersion: string;\n\treadonly queryIntentHash: string;\n\treadonly queryIntentCluster?: string;\n\treadonly budgetBucket: string;\n\treadonly redactionPolicyHash: string;\n\treadonly safetyProfileHash: string;\n\treadonly compressorPolicyHash?: string;\n\treadonly qualityPolicyHash?: string;\n\treadonly invalidationSnapshotHash?: string;\n}\n\nexport function createContextBudgetCacheKeyBaseV2(input: {\n\treadonly namespace?: string;\n\treadonly modelId: string;\n\treadonly tokenizerId?: string;\n\treadonly policyVersion: string;\n\treadonly query?: string;\n\treadonly queryIntentHash?: string;\n\treadonly queryIntentCluster?: string;\n\treadonly budgetBucket?: string;\n\treadonly redactionPolicyHash?: string;\n\treadonly safetyProfileHash?: string;\n\treadonly compressorPolicyHash?: string;\n\treadonly qualityPolicyHash?: string;\n\treadonly cacheInvalidationSnapshot?: ContextCacheInvalidationSnapshot;\n}): ContextBudgetCacheKeyBaseV2 {\n\tconst queryIntentHash = input.queryIntentHash ?? computeContextBudgetQueryIntentHashV2(input.query);\n\treturn {\n\t\tnamespace: input.namespace ?? DEFAULT_CACHE_NAMESPACE,\n\t\tmodelId: input.modelId,\n\t\ttokenizerId: input.tokenizerId ?? DEFAULT_TOKENIZER_ID,\n\t\tpolicyVersion: input.policyVersion,\n\t\tqueryIntentHash,\n\t\tqueryIntentCluster: input.queryIntentCluster ?? queryIntentHash,\n\t\tbudgetBucket: input.budgetBucket ?? \"unknown\",\n\t\tredactionPolicyHash: input.redactionPolicyHash ?? DEFAULT_REDACTION_POLICY_HASH,\n\t\tsafetyProfileHash: input.safetyProfileHash ?? DEFAULT_SAFETY_PROFILE_HASH,\n\t\tcompressorPolicyHash: input.compressorPolicyHash ?? DEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2,\n\t\tqualityPolicyHash: input.qualityPolicyHash ?? DEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2,\n\t\tinvalidationSnapshotHash:\n\t\t\tinput.cacheInvalidationSnapshot === undefined\n\t\t\t\t? \"none\"\n\t\t\t\t: sha256Hex(serializeContextCacheSnapshot(input.cacheInvalidationSnapshot)),\n\t};\n}\n\nexport function computeContextBudgetQueryIntentHashV2(query: string | undefined): string {\n\tconst normalized = (query ?? \"\")\n\t\t.toLowerCase()\n\t\t.split(/[\\s,.;:!?()[\\]{}\"'`]+/u)\n\t\t.map((term) => term.trim())\n\t\t.filter((term) => term.length > 0)\n\t\t.sort()\n\t\t.join(\" \");\n\treturn sha256Hex(normalized.length > 0 ? normalized : \"none\");\n}\n\nexport function buildContextBudgetRepresentationCacheKeyV2(\n\tinput: ContextBudgetCacheKeyBaseV2 & {\n\t\treadonly representationKind: ContextRepresentationKindV2;\n\t\treadonly sourceHash: string;\n\t\treadonly representationFingerprint?: string;\n\t\treadonly compressorId?: string;\n\t},\n): string {\n\treturn buildContextBudgetExactRepresentationCacheKeyV2(input);\n}\n\nexport function buildContextBudgetExactRepresentationCacheKeyV2(\n\tinput: ContextBudgetCacheKeyBaseV2 & {\n\t\treadonly representationKind: ContextRepresentationKindV2;\n\t\treadonly sourceHash: string;\n\t\treadonly representationFingerprint?: string;\n\t\treadonly compressorId?: string;\n\t},\n): string {\n\treturn `context-representation-exact:${sha256Canonical({\n\t\tbudgetBucket: input.budgetBucket,\n\t\tcompressorId: input.compressorId ?? NO_COMPRESSOR_ID,\n\t\tinvalidationSnapshotHash: input.invalidationSnapshotHash ?? \"none\",\n\t\tmodelId: input.modelId,\n\t\tnamespace: input.namespace,\n\t\tpolicyVersion: input.policyVersion,\n\t\tqueryIntentHash: input.queryIntentHash,\n\t\tredactionPolicyHash: input.redactionPolicyHash,\n\t\trepresentationFingerprint: input.representationFingerprint ?? \"none\",\n\t\trepresentationKind: input.representationKind,\n\t\tsafetyProfileHash: input.safetyProfileHash,\n\t\tsourceHash: input.sourceHash,\n\t\ttokenizerId: input.tokenizerId,\n\t})}`;\n}\n\nexport function buildContextBudgetMaterializedRepresentationCacheKeyV2(\n\tinput: ContextBudgetCacheKeyBaseV2 & {\n\t\treadonly representationKind: ContextRepresentationKindV2;\n\t\treadonly sourceHash: string;\n\t\treadonly compressorId?: string;\n\t\treadonly targetTokenBucket: number;\n\t},\n): string {\n\treturn `context-representation-materialized:${sha256Canonical({\n\t\tbudgetBucket: input.budgetBucket,\n\t\tcompressorId: input.compressorId ?? NO_COMPRESSOR_ID,\n\t\tcompressorPolicyHash: input.compressorPolicyHash ?? DEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2,\n\t\tinvalidationSnapshotHash: input.invalidationSnapshotHash ?? \"none\",\n\t\tmodelId: input.modelId,\n\t\tnamespace: input.namespace,\n\t\tpolicyVersion: input.policyVersion,\n\t\tqualityPolicyHash: input.qualityPolicyHash ?? DEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2,\n\t\tqueryIntentCluster: input.queryIntentCluster ?? input.queryIntentHash,\n\t\tqueryIntentHash: input.queryIntentHash,\n\t\tredactionPolicyHash: input.redactionPolicyHash,\n\t\trepresentationKind: input.representationKind,\n\t\tsafetyProfileHash: input.safetyProfileHash,\n\t\tsourceHash: input.sourceHash,\n\t\ttargetTokenBucket: input.targetTokenBucket,\n\t\ttokenizerId: input.tokenizerId,\n\t})}`;\n}\n\nexport function computeContextBudgetRepresentationFingerprintV2(\n\tcandidate: ContextBudgetRepresentationFingerprintInputV2,\n): string {\n\treturn sha256Canonical({\n\t\tcompressorId: candidate.compressorId ?? NO_COMPRESSOR_ID,\n\t\testimatedTokens: candidate.estimatedTokens,\n\t\tfidelity: candidate.fidelity,\n\t\tkind: candidate.kind,\n\t\tsourceRef: fingerprintSourceRef(candidate.sourceRef),\n\t\tsummaryHash: candidate.summaryHash ?? null,\n\t\ttextHash: sha256Hex(candidate.text),\n\t});\n}\n\nexport function buildContextBudgetRepresentationCandidateKeyV2(\n\tkeyBase: ContextBudgetCacheKeyBaseV2,\n\tcandidate: ContextBudgetRepresentationFingerprintInputV2,\n\tsourceHash: string,\n): string {\n\treturn buildContextBudgetExactRepresentationCacheKeyV2({\n\t\t...keyBase,\n\t\tcompressorId: candidate.compressorId ?? NO_COMPRESSOR_ID,\n\t\trepresentationFingerprint: computeContextBudgetRepresentationFingerprintV2(candidate),\n\t\trepresentationKind: candidate.kind,\n\t\tsourceHash,\n\t});\n}\n\nexport function buildContextBudgetMaterializedRepresentationCandidateKeyV2(\n\tkeyBase: ContextBudgetCacheKeyBaseV2,\n\tcandidate: ContextBudgetRepresentationFingerprintInputV2,\n\tsourceHash: string,\n): string {\n\treturn buildContextBudgetMaterializedRepresentationCacheKeyV2({\n\t\t...keyBase,\n\t\tcompressorId: candidate.compressorId ?? NO_COMPRESSOR_ID,\n\t\trepresentationKind: candidate.kind,\n\t\tsourceHash,\n\t\ttargetTokenBucket: computeContextBudgetTargetTokenBucketV2(candidate.estimatedTokens),\n\t});\n}\n\nexport function computeContextBudgetTargetTokenBucketV2(tokens: number): number {\n\tif (!Number.isFinite(tokens) || tokens <= 0) {\n\t\treturn MATERIALIZED_TARGET_TOKEN_BUCKET_SIZE;\n\t}\n\treturn MATERIALIZED_TARGET_TOKEN_BUCKET_SIZE * Math.ceil(tokens / MATERIALIZED_TARGET_TOKEN_BUCKET_SIZE);\n}\n\nexport function computeContextBudgetOutputTextHashV2(text: string): string {\n\treturn sha256Hex(text);\n}\n\nexport function fingerprintSourceRef(sourceRef: ContextRepresentationCandidateV2[\"sourceRef\"]): unknown {\n\tif (!sourceRef) return null;\n\treturn {\n\t\tcontentHash: sourceRef.contentHash,\n\t\trange: sourceRef.range\n\t\t\t? {\n\t\t\t\t\tendLine: sourceRef.range.endLine,\n\t\t\t\t\tstartLine: sourceRef.range.startLine,\n\t\t\t\t}\n\t\t\t: null,\n\t\tretrievable: sourceRef.retrievable,\n\t\tsymbol: sourceRef.symbol ?? null,\n\t\turi: sourceRef.uri,\n\t};\n}\n"]}
+{"version":3,"file":"context-budget-v2-cache-keys.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-cache-keys.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ContextRepresentationCandidateV2, ContextRepresentationKindV2 } from \"./context-budget-headroom.ts\";\nimport { sha256Canonical, sha256Hex } from \"./context-budget-v2-cache-hash.ts\";\nimport {\n\ttype ContextCacheInvalidationSnapshot,\n\tserializeContextCacheSnapshot,\n} from \"./context-budget-v2-cache-invalidation.ts\";\n\nconst DEFAULT_CACHE_NAMESPACE = \"context-budget-v2\";\nconst DEFAULT_TOKENIZER_ID = \"heuristic-v1\";\nconst DEFAULT_REDACTION_POLICY_HASH = \"none\";\nconst DEFAULT_SAFETY_PROFILE_HASH = \"default\";\nconst NO_COMPRESSOR_ID = \"none\";\nexport const DEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2 = \"context-budget-v2-default-compressor\";\nexport const DEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2 = \"context-budget-v2-default-quality\";\nconst MATERIALIZED_TARGET_TOKEN_BUCKET_SIZE = 100;\n\ntype ContextBudgetRepresentationFingerprintInputV2 = Pick<\n\tContextRepresentationCandidateV2,\n\t\"compressorId\" | \"estimatedTokens\" | \"fidelity\" | \"kind\" | \"sourceRef\" | \"summaryHash\" | \"text\"\n>;\n\n/**\n * Cache-key inputs shared by the plan cache and the representation cache.\n *\n * Scope contract (deliberate asymmetry — see the two builders below):\n * - **Plan keys are session-scoped.** A plan is a selection over the whole\n *   transcript and runtime state, so {@link invalidationSnapshotHash} (fork id,\n *   worktree fingerprint, steering/repair/settings counters) is part of the key.\n * - **Representation keys are content-addressed.** A rendered representation is\n *   fully identified by its source content plus the rendering policy, so the\n *   invalidation snapshot is deliberately *excluded*. Folding a per-session\n *   `forkId` into representation keys made every new session miss every entry\n *   (structurally unreachable reuse, not a cold cache), while adding no safety:\n *   `validateContextBudgetRepresentationCacheEntryV2` independently re-checks\n *   source hash, fingerprint, model, tokenizer, policy version, and\n *   TTL on every read, and worktree/model/redaction/safety changes already move\n *   the key through `sourceHash` / `modelId` / `redactionPolicyHash` /\n *   `safetyProfileHash`.\n */\nexport interface ContextBudgetCacheKeyBaseV2 {\n\treadonly namespace: string;\n\treadonly modelId: string;\n\treadonly tokenizerId: string;\n\treadonly policyVersion: string;\n\treadonly queryIntentHash: string;\n\treadonly queryIntentCluster?: string;\n\treadonly budgetBucket: string;\n\treadonly redactionPolicyHash: string;\n\treadonly safetyProfileHash: string;\n\treadonly compressorPolicyHash?: string;\n\treadonly qualityPolicyHash?: string;\n\treadonly invalidationSnapshotHash?: string;\n}\n\nexport function createContextBudgetCacheKeyBaseV2(input: {\n\treadonly namespace?: string;\n\treadonly modelId: string;\n\treadonly tokenizerId?: string;\n\treadonly policyVersion: string;\n\treadonly query?: string;\n\treadonly queryIntentHash?: string;\n\treadonly queryIntentCluster?: string;\n\treadonly budgetBucket?: string;\n\treadonly redactionPolicyHash?: string;\n\treadonly safetyProfileHash?: string;\n\treadonly compressorPolicyHash?: string;\n\treadonly qualityPolicyHash?: string;\n\treadonly cacheInvalidationSnapshot?: ContextCacheInvalidationSnapshot;\n}): ContextBudgetCacheKeyBaseV2 {\n\tconst queryIntentHash = input.queryIntentHash ?? computeContextBudgetQueryIntentHashV2(input.query);\n\treturn {\n\t\tnamespace: input.namespace ?? DEFAULT_CACHE_NAMESPACE,\n\t\tmodelId: input.modelId,\n\t\ttokenizerId: input.tokenizerId ?? DEFAULT_TOKENIZER_ID,\n\t\tpolicyVersion: input.policyVersion,\n\t\tqueryIntentHash,\n\t\tqueryIntentCluster: input.queryIntentCluster ?? queryIntentHash,\n\t\tbudgetBucket: input.budgetBucket ?? \"unknown\",\n\t\tredactionPolicyHash: input.redactionPolicyHash ?? DEFAULT_REDACTION_POLICY_HASH,\n\t\tsafetyProfileHash: input.safetyProfileHash ?? DEFAULT_SAFETY_PROFILE_HASH,\n\t\tcompressorPolicyHash: input.compressorPolicyHash ?? DEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2,\n\t\tqualityPolicyHash: input.qualityPolicyHash ?? DEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2,\n\t\tinvalidationSnapshotHash:\n\t\t\tinput.cacheInvalidationSnapshot === undefined\n\t\t\t\t? \"none\"\n\t\t\t\t: sha256Hex(serializeContextCacheSnapshot(input.cacheInvalidationSnapshot)),\n\t};\n}\n\nexport function computeContextBudgetQueryIntentHashV2(query: string | undefined): string {\n\tconst normalized = (query ?? \"\")\n\t\t.toLowerCase()\n\t\t.split(/[\\s,.;:!?()[\\]{}\"'`]+/u)\n\t\t.map((term) => term.trim())\n\t\t.filter((term) => term.length > 0)\n\t\t.sort()\n\t\t.join(\" \");\n\treturn sha256Hex(normalized.length > 0 ? normalized : \"none\");\n}\n\nexport function buildContextBudgetRepresentationCacheKeyV2(\n\tinput: ContextBudgetCacheKeyBaseV2 & {\n\t\treadonly representationKind: ContextRepresentationKindV2;\n\t\treadonly sourceHash: string;\n\t\treadonly representationFingerprint?: string;\n\t\treadonly compressorId?: string;\n\t},\n): string {\n\treturn buildContextBudgetExactRepresentationCacheKeyV2(input);\n}\n\n/**\n * Exact representation key. Content-addressed: identical content + rendering\n * policy yields one key across queries, budgets, sessions, forks, and worktrees.\n */\nexport function buildContextBudgetExactRepresentationCacheKeyV2(\n\tinput: ContextBudgetCacheKeyBaseV2 & {\n\t\treadonly representationKind: ContextRepresentationKindV2;\n\t\treadonly sourceHash: string;\n\t\treadonly representationFingerprint?: string;\n\t\treadonly compressorId?: string;\n\t},\n): string {\n\treturn `context-representation-exact:${sha256Canonical({\n\t\tcompressorId: input.compressorId ?? NO_COMPRESSOR_ID,\n\t\tmodelId: input.modelId,\n\t\tnamespace: input.namespace,\n\t\tpolicyVersion: input.policyVersion,\n\t\tredactionPolicyHash: input.redactionPolicyHash,\n\t\trepresentationFingerprint: input.representationFingerprint ?? \"none\",\n\t\trepresentationKind: input.representationKind,\n\t\tsafetyProfileHash: input.safetyProfileHash,\n\t\tsourceHash: input.sourceHash,\n\t\ttokenizerId: input.tokenizerId,\n\t})}`;\n}\n\nexport function buildContextBudgetMaterializedRepresentationCacheKeyV2(\n\tinput: ContextBudgetCacheKeyBaseV2 & {\n\t\treadonly representationKind: ContextRepresentationKindV2;\n\t\treadonly sourceHash: string;\n\t\treadonly compressorId?: string;\n\t\treadonly targetTokenBucket: number;\n\t},\n): string {\n\treturn `context-representation-materialized:${sha256Canonical({\n\t\tbudgetBucket: input.budgetBucket,\n\t\tcompressorId: input.compressorId ?? NO_COMPRESSOR_ID,\n\t\tcompressorPolicyHash: input.compressorPolicyHash ?? DEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2,\n\t\tmodelId: input.modelId,\n\t\tnamespace: input.namespace,\n\t\tpolicyVersion: input.policyVersion,\n\t\tqualityPolicyHash: input.qualityPolicyHash ?? DEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2,\n\t\tqueryIntentCluster: input.queryIntentCluster ?? input.queryIntentHash,\n\t\tqueryIntentHash: input.queryIntentHash,\n\t\tredactionPolicyHash: input.redactionPolicyHash,\n\t\trepresentationKind: input.representationKind,\n\t\tsafetyProfileHash: input.safetyProfileHash,\n\t\tsourceHash: input.sourceHash,\n\t\ttargetTokenBucket: input.targetTokenBucket,\n\t\ttokenizerId: input.tokenizerId,\n\t})}`;\n}\n\nexport function computeContextBudgetRepresentationFingerprintV2(\n\tcandidate: ContextBudgetRepresentationFingerprintInputV2,\n): string {\n\treturn sha256Canonical({\n\t\tcompressorId: candidate.compressorId ?? NO_COMPRESSOR_ID,\n\t\testimatedTokens: candidate.estimatedTokens,\n\t\tfidelity: candidate.fidelity,\n\t\tkind: candidate.kind,\n\t\tsourceRef: fingerprintSourceRef(candidate.sourceRef),\n\t\tsummaryHash: candidate.summaryHash ?? null,\n\t\ttextHash: sha256Hex(candidate.text),\n\t});\n}\n\nexport function buildContextBudgetRepresentationCandidateKeyV2(\n\tkeyBase: ContextBudgetCacheKeyBaseV2,\n\tcandidate: ContextBudgetRepresentationFingerprintInputV2,\n\tsourceHash: string,\n): string {\n\treturn buildContextBudgetExactRepresentationCacheKeyV2({\n\t\t...keyBase,\n\t\tcompressorId: candidate.compressorId ?? NO_COMPRESSOR_ID,\n\t\trepresentationFingerprint: computeContextBudgetRepresentationFingerprintV2(candidate),\n\t\trepresentationKind: candidate.kind,\n\t\tsourceHash,\n\t});\n}\n\nexport function buildContextBudgetMaterializedRepresentationCandidateKeyV2(\n\tkeyBase: ContextBudgetCacheKeyBaseV2,\n\tcandidate: ContextBudgetRepresentationFingerprintInputV2,\n\tsourceHash: string,\n): string {\n\treturn buildContextBudgetMaterializedRepresentationCacheKeyV2({\n\t\t...keyBase,\n\t\tcompressorId: candidate.compressorId ?? NO_COMPRESSOR_ID,\n\t\trepresentationKind: candidate.kind,\n\t\tsourceHash,\n\t\ttargetTokenBucket: computeContextBudgetTargetTokenBucketV2(candidate.estimatedTokens),\n\t});\n}\n\nexport function computeContextBudgetTargetTokenBucketV2(tokens: number): number {\n\tif (!Number.isFinite(tokens) || tokens <= 0) {\n\t\treturn MATERIALIZED_TARGET_TOKEN_BUCKET_SIZE;\n\t}\n\treturn MATERIALIZED_TARGET_TOKEN_BUCKET_SIZE * Math.ceil(tokens / MATERIALIZED_TARGET_TOKEN_BUCKET_SIZE);\n}\n\nexport function computeContextBudgetOutputTextHashV2(text: string): string {\n\treturn sha256Hex(text);\n}\n\nexport function fingerprintSourceRef(sourceRef: ContextRepresentationCandidateV2[\"sourceRef\"]): unknown {\n\tif (!sourceRef) return null;\n\treturn {\n\t\tcontentHash: sourceRef.contentHash,\n\t\trange: sourceRef.range\n\t\t\t? {\n\t\t\t\t\tendLine: sourceRef.range.endLine,\n\t\t\t\t\tstartLine: sourceRef.range.startLine,\n\t\t\t\t}\n\t\t\t: null,\n\t\tretrievable: sourceRef.retrievable,\n\t\tsymbol: sourceRef.symbol ?? null,\n\t\turi: sourceRef.uri,\n\t};\n}\n"]}

package/dist/core/context-budget-v2-cache.d.ts

@@ -2,6 +2,7 @@ import type { ContextBudgetCacheKeyBaseV2 } from "./context-budget-v2-cache-keys
 import { type MutableTokenCacheTelemetryV2 } from "./context-budget-v2-cache-telemetry.ts";
 import type { PlannedItemV2 } from "./context-budget-v2-scoring.ts";
 import type { ContextBudgetCacheProviderV2, PromptContextBudgetPlanV2 } from "./context-budget-v2-types.ts";
+export { CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION, createDiskContextBudgetCacheProviderV2, DEFAULT_DISK_CACHE_FLUSH_DEBOUNCE_MS, DEFAULT_DISK_CACHE_MAX_BYTES, DEFAULT_DISK_CACHE_MAX_ENTRIES, type DiskContextBudgetCacheOptionsV2, DiskContextBudgetCacheProviderV2, } from "./context-budget-v2-cache-disk.ts";
 export { buildContextBudgetExactRepresentationCacheKeyV2, buildContextBudgetMaterializedRepresentationCacheKeyV2, buildContextBudgetMaterializedRepresentationCandidateKeyV2, buildContextBudgetRepresentationCacheKeyV2, type ContextBudgetCacheKeyBaseV2, computeContextBudgetOutputTextHashV2, computeContextBudgetQueryIntentHashV2, computeContextBudgetRepresentationFingerprintV2, computeContextBudgetTargetTokenBucketV2, createContextBudgetCacheKeyBaseV2, DEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2, DEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2, } from "./context-budget-v2-cache-keys.ts";
 export { createMemoryContextBudgetCacheProviderV2 } from "./context-budget-v2-cache-provider.ts";
 export { finalizeContextBudgetCacheTelemetryV2, type MutableTokenCacheTelemetryV2, withCacheTelemetry, } from "./context-budget-v2-cache-telemetry.ts";

package/dist/core/context-budget-v2-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget-v2-cache.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,mCAAmC,CAAC;AACrF,OAAO,EAEN,KAAK,4BAA4B,EAEjC,MAAM,wCAAwC,CAAC;AAKhD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,4BAA4B,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAE5G,OAAO,EACN,+CAA+C,EAC/C,sDAAsD,EACtD,0DAA0D,EAC1D,0CAA0C,EAC1C,KAAK,2BAA2B,EAChC,oCAAoC,EACpC,qCAAqC,EACrC,+CAA+C,EAC/C,uCAAuC,EACvC,iCAAiC,EACjC,8CAA8C,EAC9C,2CAA2C,GAC3C,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,wCAAwC,EAAE,MAAM,uCAAuC,CAAC;AACjG,OAAO,EACN,qCAAqC,EACrC,KAAK,4BAA4B,EACjC,kBAAkB,GAClB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,gCAAgC,EAAE,MAAM,wCAAwC,CAAC;AAC1F,OAAO,EACN,0BAA0B,EAC1B,gCAAgC,EAChC,0BAA0B,GAC1B,MAAM,6CAA6C,CAAC;AAIrD,MAAM,WAAW,6BAA6B;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,4BAA4B,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,2BAA2B,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,4BAA4B,CAAC;CACjD;AAED,wBAAgB,mCAAmC,CAAC,KAAK,EAAE;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,4BAA4B,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,2BAA2B,CAAC;IAC9C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,6BAA6B,CAQhC;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC3C,QAAQ,CAAC,KAAK,EAAE,6BAA6B,CAAC;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACjC,GAAG,yBAAyB,GAAG,SAAS,CAkBxC;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACvC,QAAQ,CAAC,KAAK,EAAE,6BAA6B,CAAC;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;CAC3C,GAAG,IAAI,CAWP","sourcesContent":["import type { ContextBudgetCacheKeyBaseV2 } from \"./context-budget-v2-cache-keys.ts\";\nimport {\n\tcreateMutableContextBudgetCacheTelemetryV2,\n\ttype MutableTokenCacheTelemetryV2,\n\twithCacheTelemetry,\n} from \"./context-budget-v2-cache-telemetry.ts\";\nimport {\n\tsourceHashesByContextBudgetItemIdV2,\n\tvalidateContextBudgetPlanCacheEntryV2,\n} from \"./context-budget-v2-cache-validation.ts\";\nimport type { PlannedItemV2 } from \"./context-budget-v2-scoring.ts\";\nimport type { ContextBudgetCacheProviderV2, PromptContextBudgetPlanV2 } from \"./context-budget-v2-types.ts\";\n\nexport {\n\tbuildContextBudgetExactRepresentationCacheKeyV2,\n\tbuildContextBudgetMaterializedRepresentationCacheKeyV2,\n\tbuildContextBudgetMaterializedRepresentationCandidateKeyV2,\n\tbuildContextBudgetRepresentationCacheKeyV2,\n\ttype ContextBudgetCacheKeyBaseV2,\n\tcomputeContextBudgetOutputTextHashV2,\n\tcomputeContextBudgetQueryIntentHashV2,\n\tcomputeContextBudgetRepresentationFingerprintV2,\n\tcomputeContextBudgetTargetTokenBucketV2,\n\tcreateContextBudgetCacheKeyBaseV2,\n\tDEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2,\n\tDEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2,\n} from \"./context-budget-v2-cache-keys.ts\";\nexport { createMemoryContextBudgetCacheProviderV2 } from \"./context-budget-v2-cache-provider.ts\";\nexport {\n\tfinalizeContextBudgetCacheTelemetryV2,\n\ttype MutableTokenCacheTelemetryV2,\n\twithCacheTelemetry,\n} from \"./context-budget-v2-cache-telemetry.ts\";\nexport { buildContextBudgetPlanCacheKeyV2 } from \"./context-budget-v2-plan-cache-keys.ts\";\nexport {\n\tapplyRepresentationCacheV2,\n\tisMaterializableRepresentationV2,\n\twriteRepresentationCacheV2,\n} from \"./context-budget-v2-representation-cache.ts\";\n\nconst DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;\n\nexport interface ContextBudgetSelectionCacheV2 {\n\treadonly provider?: ContextBudgetCacheProviderV2;\n\treadonly keyBase: ContextBudgetCacheKeyBaseV2;\n\treadonly nowEpochMs: number;\n\treadonly ttlMs: number;\n\treadonly telemetry: MutableTokenCacheTelemetryV2;\n}\n\nexport function createContextBudgetSelectionCacheV2(input: {\n\treadonly provider?: ContextBudgetCacheProviderV2;\n\treadonly keyBase: ContextBudgetCacheKeyBaseV2;\n\treadonly planCacheKey: string;\n\treadonly nowEpochMs?: number;\n\treadonly ttlMs?: number;\n}): ContextBudgetSelectionCacheV2 {\n\treturn {\n\t\tprovider: input.provider,\n\t\tkeyBase: input.keyBase,\n\t\tnowEpochMs: input.nowEpochMs ?? Date.now(),\n\t\tttlMs: input.ttlMs ?? DEFAULT_CACHE_TTL_MS,\n\t\ttelemetry: createMutableContextBudgetCacheTelemetryV2(input.planCacheKey),\n\t};\n}\n\nexport function readValidPlanCacheV2(input: {\n\treadonly cache: ContextBudgetSelectionCacheV2;\n\treadonly key: string;\n\treadonly planned: readonly PlannedItemV2[];\n\treadonly availableTokens: number;\n}): PromptContextBudgetPlanV2 | undefined {\n\tconst read = input.cache.provider?.readPlan(input.key);\n\tif (!read) return undefined;\n\tconst rejection = validateContextBudgetPlanCacheEntryV2({\n\t\tavailableTokens: input.availableTokens,\n\t\tcache: input.cache,\n\t\tentry: read.entry,\n\t\tplanned: input.planned,\n\t});\n\tif (rejection) {\n\t\tinput.cache.telemetry.planCache.rejectedReason = rejection;\n\t\tif (rejection === \"stale\") input.cache.provider?.deletePlan?.(input.key);\n\t\treturn undefined;\n\t}\n\tinput.cache.telemetry.planCache.hit = true;\n\tinput.cache.telemetry.planCache.layer = read.layer;\n\tinput.cache.telemetry.tokens.savedByCache = read.entry.plan.rawTokens;\n\treturn withCacheTelemetry(read.entry.plan, input.cache.telemetry);\n}\n\nexport function writePlanCacheV2(input: {\n\treadonly cache: ContextBudgetSelectionCacheV2;\n\treadonly key: string;\n\treadonly plan: PromptContextBudgetPlanV2;\n\treadonly planned: readonly PlannedItemV2[];\n}): void {\n\tif (!input.cache.provider || input.plan.emergency) return;\n\tif (input.plan.selectedRepresentations.some((representation) => representation.cache?.hit === true)) return;\n\tinput.cache.provider.writePlan({\n\t\tkey: input.key,\n\t\tentry: {\n\t\t\tcreatedAtEpochMs: input.cache.nowEpochMs,\n\t\t\tplan: input.plan,\n\t\t\tsourceHashes: sourceHashesByContextBudgetItemIdV2(input.planned),\n\t\t},\n\t});\n}\n"]}
+{"version":3,"file":"context-budget-v2-cache.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,mCAAmC,CAAC;AACrF,OAAO,EAEN,KAAK,4BAA4B,EAEjC,MAAM,wCAAwC,CAAC;AAKhD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,4BAA4B,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAE5G,OAAO,EACN,wCAAwC,EACxC,sCAAsC,EACtC,oCAAoC,EACpC,4BAA4B,EAC5B,8BAA8B,EAC9B,KAAK,+BAA+B,EACpC,gCAAgC,GAChC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACN,+CAA+C,EAC/C,sDAAsD,EACtD,0DAA0D,EAC1D,0CAA0C,EAC1C,KAAK,2BAA2B,EAChC,oCAAoC,EACpC,qCAAqC,EACrC,+CAA+C,EAC/C,uCAAuC,EACvC,iCAAiC,EACjC,8CAA8C,EAC9C,2CAA2C,GAC3C,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,wCAAwC,EAAE,MAAM,uCAAuC,CAAC;AACjG,OAAO,EACN,qCAAqC,EACrC,KAAK,4BAA4B,EACjC,kBAAkB,GAClB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,gCAAgC,EAAE,MAAM,wCAAwC,CAAC;AAC1F,OAAO,EACN,0BAA0B,EAC1B,gCAAgC,EAChC,0BAA0B,GAC1B,MAAM,6CAA6C,CAAC;AAIrD,MAAM,WAAW,6BAA6B;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,4BAA4B,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,2BAA2B,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,4BAA4B,CAAC;CACjD;AAED,wBAAgB,mCAAmC,CAAC,KAAK,EAAE;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,4BAA4B,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,2BAA2B,CAAC;IAC9C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,6BAA6B,CAQhC;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC3C,QAAQ,CAAC,KAAK,EAAE,6BAA6B,CAAC;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACjC,GAAG,yBAAyB,GAAG,SAAS,CAkBxC;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACvC,QAAQ,CAAC,KAAK,EAAE,6BAA6B,CAAC;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;CAC3C,GAAG,IAAI,CAWP","sourcesContent":["import type { ContextBudgetCacheKeyBaseV2 } from \"./context-budget-v2-cache-keys.ts\";\nimport {\n\tcreateMutableContextBudgetCacheTelemetryV2,\n\ttype MutableTokenCacheTelemetryV2,\n\twithCacheTelemetry,\n} from \"./context-budget-v2-cache-telemetry.ts\";\nimport {\n\tsourceHashesByContextBudgetItemIdV2,\n\tvalidateContextBudgetPlanCacheEntryV2,\n} from \"./context-budget-v2-cache-validation.ts\";\nimport type { PlannedItemV2 } from \"./context-budget-v2-scoring.ts\";\nimport type { ContextBudgetCacheProviderV2, PromptContextBudgetPlanV2 } from \"./context-budget-v2-types.ts\";\n\nexport {\n\tCONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION,\n\tcreateDiskContextBudgetCacheProviderV2,\n\tDEFAULT_DISK_CACHE_FLUSH_DEBOUNCE_MS,\n\tDEFAULT_DISK_CACHE_MAX_BYTES,\n\tDEFAULT_DISK_CACHE_MAX_ENTRIES,\n\ttype DiskContextBudgetCacheOptionsV2,\n\tDiskContextBudgetCacheProviderV2,\n} from \"./context-budget-v2-cache-disk.ts\";\nexport {\n\tbuildContextBudgetExactRepresentationCacheKeyV2,\n\tbuildContextBudgetMaterializedRepresentationCacheKeyV2,\n\tbuildContextBudgetMaterializedRepresentationCandidateKeyV2,\n\tbuildContextBudgetRepresentationCacheKeyV2,\n\ttype ContextBudgetCacheKeyBaseV2,\n\tcomputeContextBudgetOutputTextHashV2,\n\tcomputeContextBudgetQueryIntentHashV2,\n\tcomputeContextBudgetRepresentationFingerprintV2,\n\tcomputeContextBudgetTargetTokenBucketV2,\n\tcreateContextBudgetCacheKeyBaseV2,\n\tDEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2,\n\tDEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2,\n} from \"./context-budget-v2-cache-keys.ts\";\nexport { createMemoryContextBudgetCacheProviderV2 } from \"./context-budget-v2-cache-provider.ts\";\nexport {\n\tfinalizeContextBudgetCacheTelemetryV2,\n\ttype MutableTokenCacheTelemetryV2,\n\twithCacheTelemetry,\n} from \"./context-budget-v2-cache-telemetry.ts\";\nexport { buildContextBudgetPlanCacheKeyV2 } from \"./context-budget-v2-plan-cache-keys.ts\";\nexport {\n\tapplyRepresentationCacheV2,\n\tisMaterializableRepresentationV2,\n\twriteRepresentationCacheV2,\n} from \"./context-budget-v2-representation-cache.ts\";\n\nconst DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;\n\nexport interface ContextBudgetSelectionCacheV2 {\n\treadonly provider?: ContextBudgetCacheProviderV2;\n\treadonly keyBase: ContextBudgetCacheKeyBaseV2;\n\treadonly nowEpochMs: number;\n\treadonly ttlMs: number;\n\treadonly telemetry: MutableTokenCacheTelemetryV2;\n}\n\nexport function createContextBudgetSelectionCacheV2(input: {\n\treadonly provider?: ContextBudgetCacheProviderV2;\n\treadonly keyBase: ContextBudgetCacheKeyBaseV2;\n\treadonly planCacheKey: string;\n\treadonly nowEpochMs?: number;\n\treadonly ttlMs?: number;\n}): ContextBudgetSelectionCacheV2 {\n\treturn {\n\t\tprovider: input.provider,\n\t\tkeyBase: input.keyBase,\n\t\tnowEpochMs: input.nowEpochMs ?? Date.now(),\n\t\tttlMs: input.ttlMs ?? DEFAULT_CACHE_TTL_MS,\n\t\ttelemetry: createMutableContextBudgetCacheTelemetryV2(input.planCacheKey),\n\t};\n}\n\nexport function readValidPlanCacheV2(input: {\n\treadonly cache: ContextBudgetSelectionCacheV2;\n\treadonly key: string;\n\treadonly planned: readonly PlannedItemV2[];\n\treadonly availableTokens: number;\n}): PromptContextBudgetPlanV2 | undefined {\n\tconst read = input.cache.provider?.readPlan(input.key);\n\tif (!read) return undefined;\n\tconst rejection = validateContextBudgetPlanCacheEntryV2({\n\t\tavailableTokens: input.availableTokens,\n\t\tcache: input.cache,\n\t\tentry: read.entry,\n\t\tplanned: input.planned,\n\t});\n\tif (rejection) {\n\t\tinput.cache.telemetry.planCache.rejectedReason = rejection;\n\t\tif (rejection === \"stale\") input.cache.provider?.deletePlan?.(input.key);\n\t\treturn undefined;\n\t}\n\tinput.cache.telemetry.planCache.hit = true;\n\tinput.cache.telemetry.planCache.layer = read.layer;\n\tinput.cache.telemetry.tokens.savedByCache = read.entry.plan.rawTokens;\n\treturn withCacheTelemetry(read.entry.plan, input.cache.telemetry);\n}\n\nexport function writePlanCacheV2(input: {\n\treadonly cache: ContextBudgetSelectionCacheV2;\n\treadonly key: string;\n\treadonly plan: PromptContextBudgetPlanV2;\n\treadonly planned: readonly PlannedItemV2[];\n}): void {\n\tif (!input.cache.provider || input.plan.emergency) return;\n\tif (input.plan.selectedRepresentations.some((representation) => representation.cache?.hit === true)) return;\n\tinput.cache.provider.writePlan({\n\t\tkey: input.key,\n\t\tentry: {\n\t\t\tcreatedAtEpochMs: input.cache.nowEpochMs,\n\t\t\tplan: input.plan,\n\t\t\tsourceHashes: sourceHashesByContextBudgetItemIdV2(input.planned),\n\t\t},\n\t});\n}\n"]}