open-multi-agent-kit 0.90.0 → 0.90.4

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

@@ -0,0 +1,50 @@
+import { createMutableContextBudgetCacheTelemetryV2, withCacheTelemetry, } from "./context-budget-v2-cache-telemetry.js";
+import { sourceHashesByContextBudgetItemIdV2, validateContextBudgetPlanCacheEntryV2, } from "./context-budget-v2-cache-validation.js";
+export { buildContextBudgetExactRepresentationCacheKeyV2, buildContextBudgetMaterializedRepresentationCacheKeyV2, buildContextBudgetMaterializedRepresentationCandidateKeyV2, buildContextBudgetRepresentationCacheKeyV2, computeContextBudgetOutputTextHashV2, computeContextBudgetQueryIntentHashV2, computeContextBudgetRepresentationFingerprintV2, computeContextBudgetTargetTokenBucketV2, createContextBudgetCacheKeyBaseV2, DEFAULT_MATERIALIZED_COMPRESSOR_POLICY_HASH_V2, DEFAULT_MATERIALIZED_QUALITY_POLICY_HASH_V2, } from "./context-budget-v2-cache-keys.js";
+export { createMemoryContextBudgetCacheProviderV2 } from "./context-budget-v2-cache-provider.js";
+export { finalizeContextBudgetCacheTelemetryV2, withCacheTelemetry, } from "./context-budget-v2-cache-telemetry.js";
+export { buildContextBudgetPlanCacheKeyV2 } from "./context-budget-v2-plan-cache-keys.js";
+export { applyRepresentationCacheV2, isMaterializableRepresentationV2, writeRepresentationCacheV2, } from "./context-budget-v2-representation-cache.js";
+const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;
+export function createContextBudgetSelectionCacheV2(input) {
+    return {
+        provider: input.provider,
+        keyBase: input.keyBase,
+        nowEpochMs: input.nowEpochMs ?? Date.now(),
+        ttlMs: input.ttlMs ?? DEFAULT_CACHE_TTL_MS,
+        telemetry: createMutableContextBudgetCacheTelemetryV2(input.planCacheKey),
+    };
+}
+export function readValidPlanCacheV2(input) {
+    const read = input.cache.provider?.readPlan(input.key);
+    if (!read)
+        return undefined;
+    const rejection = validateContextBudgetPlanCacheEntryV2({
+        availableTokens: input.availableTokens,
+        cache: input.cache,
+        entry: read.entry,
+        planned: input.planned,
+    });
+    if (rejection) {
+        input.cache.telemetry.planCache.rejectedReason = rejection;
+        return undefined;
+    }
+    input.cache.telemetry.planCache.hit = true;
+    input.cache.telemetry.planCache.layer = read.layer;
+    return withCacheTelemetry(read.entry.plan, input.cache.telemetry);
+}
+export function writePlanCacheV2(input) {
+    if (!input.cache.provider || input.plan.emergency)
+        return;
+    if (input.plan.selectedRepresentations.some((representation) => representation.cache?.hit === true))
+        return;
+    input.cache.provider.writePlan({
+        key: input.key,
+        entry: {
+            createdAtEpochMs: input.cache.nowEpochMs,
+            plan: input.plan,
+            sourceHashes: sourceHashesByContextBudgetItemIdV2(input.planned),
+        },
+    });
+}
+//# sourceMappingURL=context-budget-v2-cache.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-v2-cache.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-cache.ts"],"names":[],"mappings":"AACA,OAAO,EACN,0CAA0C,EAE1C,kBAAkB,GAClB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACN,mCAAmC,EACnC,qCAAqC,GACrC,MAAM,yCAAyC,CAAC;AAIjD,OAAO,EACN,+CAA+C,EAC/C,sDAAsD,EACtD,0DAA0D,EAC1D,0CAA0C,EAE1C,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,EAErC,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;AAErD,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAU3C,MAAM,UAAU,mCAAmC,CAAC,KAMnD,EAAiC;IACjC,OAAO;QACN,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,EAAE;QAC1C,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,oBAAoB;QAC1C,SAAS,EAAE,0CAA0C,CAAC,KAAK,CAAC,YAAY,CAAC;KACzE,CAAC;AAAA,CACF;AAED,MAAM,UAAU,oBAAoB,CAAC,KAKpC,EAAyC;IACzC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACvD,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,MAAM,SAAS,GAAG,qCAAqC,CAAC;QACvD,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,OAAO,EAAE,KAAK,CAAC,OAAO;KACtB,CAAC,CAAC;IACH,IAAI,SAAS,EAAE,CAAC;QACf,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,cAAc,GAAG,SAAS,CAAC;QAC3D,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,GAAG,IAAI,CAAC;IAC3C,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IACnD,OAAO,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;AAAA,CAClE;AAED,MAAM,UAAU,gBAAgB,CAAC,KAKhC,EAAQ;IACR,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,SAAS;QAAE,OAAO;IAC1D,IAAI,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC,cAAc,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;QAAE,OAAO;IAC5G,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC;QAC9B,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,KAAK,EAAE;YACN,gBAAgB,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU;YACxC,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,YAAY,EAAE,mCAAmC,CAAC,KAAK,CAAC,OAAO,CAAC;SAChE;KACD,CAAC,CAAC;AAAA,CACH","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\treturn undefined;\n\t}\n\tinput.cache.telemetry.planCache.hit = true;\n\tinput.cache.telemetry.planCache.layer = read.layer;\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"]}

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

@@ -0,0 +1,16 @@
+import type { HeadroomQualityPolicyV2 } from "./context-budget-headroom.ts";
+import { type ContextBudgetCacheKeyBaseV2 } from "./context-budget-v2-cache-keys.ts";
+import type { PlannedItemV2 } from "./context-budget-v2-scoring.ts";
+import type { TierBudgetPolicyV2 } from "./context-budget-v2-types.ts";
+export declare function buildContextBudgetPlanCacheKeyV2(input: {
+    readonly keyBase: ContextBudgetCacheKeyBaseV2;
+    readonly promptHash?: string;
+    readonly maxTokens: number;
+    readonly responseReserveTokens: number;
+    readonly safetyMarginTokens: number;
+    readonly availableTokens: number;
+    readonly planned: readonly PlannedItemV2[];
+    readonly tierPolicy: Readonly<Record<string, TierBudgetPolicyV2>>;
+    readonly qualityPolicy: HeadroomQualityPolicyV2;
+}): string;
+//# sourceMappingURL=context-budget-v2-plan-cache-keys.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-v2-plan-cache-keys.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-plan-cache-keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAE5E,OAAO,EACN,KAAK,2BAA2B,EAGhC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAEvE,wBAAgB,gCAAgC,CAAC,KAAK,EAAE;IACvD,QAAQ,CAAC,OAAO,EAAE,2BAA2B,CAAC;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAClE,QAAQ,CAAC,aAAa,EAAE,uBAAuB,CAAC;CAChD,GAAG,MAAM,CA6CT","sourcesContent":["import type { HeadroomQualityPolicyV2 } from \"./context-budget-headroom.ts\";\nimport { sha256Canonical } from \"./context-budget-v2-cache-hash.ts\";\nimport {\n\ttype ContextBudgetCacheKeyBaseV2,\n\tcomputeContextBudgetRepresentationFingerprintV2,\n\tfingerprintSourceRef,\n} from \"./context-budget-v2-cache-keys.ts\";\nimport type { PlannedItemV2 } from \"./context-budget-v2-scoring.ts\";\nimport type { TierBudgetPolicyV2 } from \"./context-budget-v2-types.ts\";\n\nexport function buildContextBudgetPlanCacheKeyV2(input: {\n\treadonly keyBase: ContextBudgetCacheKeyBaseV2;\n\treadonly promptHash?: string;\n\treadonly maxTokens: number;\n\treadonly responseReserveTokens: number;\n\treadonly safetyMarginTokens: number;\n\treadonly availableTokens: number;\n\treadonly planned: readonly PlannedItemV2[];\n\treadonly tierPolicy: Readonly<Record<string, TierBudgetPolicyV2>>;\n\treadonly qualityPolicy: HeadroomQualityPolicyV2;\n}): string {\n\treturn `context-plan:${sha256Canonical({\n\t\tavailableTokens: input.availableTokens,\n\t\tbudgetBucket: input.keyBase.budgetBucket,\n\t\titems: input.planned\n\t\t\t.map((planned) => ({\n\t\t\t\tageTurns: planned.item.ageTurns ?? null,\n\t\t\t\tbaseScore: planned.baseScore,\n\t\t\t\teffectiveScore: planned.effectiveScore,\n\t\t\t\tevidenceKind: planned.item.evidenceKind ?? null,\n\t\t\t\tevidenceValue: planned.item.evidenceValue ?? null,\n\t\t\t\tid: planned.item.id,\n\t\t\t\tpinReason: planned.item.pinReason ?? null,\n\t\t\t\tpriority: planned.item.priority,\n\t\t\t\trecency: planned.item.recency ?? null,\n\t\t\t\tredundancyKey: planned.item.redundancyKey ?? null,\n\t\t\t\tredundancyPenalty: planned.redundancyPenalty,\n\t\t\t\trelevance: planned.item.relevance ?? null,\n\t\t\t\trepresentations: (planned.item.representations ?? [])\n\t\t\t\t\t.map((candidate) => ({\n\t\t\t\t\t\tfingerprint: computeContextBudgetRepresentationFingerprintV2(candidate),\n\t\t\t\t\t\tkind: candidate.kind,\n\t\t\t\t\t}))\n\t\t\t\t\t.sort((a, b) => a.kind.localeCompare(b.kind) || a.fingerprint.localeCompare(b.fingerprint)),\n\t\t\t\trequired: planned.item.required === true,\n\t\t\t\tsourceRef: fingerprintSourceRef(planned.item.sourceRef),\n\t\t\t\tsourceHash: planned.contentHash,\n\t\t\t\ttier: planned.item.tier,\n\t\t\t\ttokenEstimate: planned.item.tokenEstimate ?? null,\n\t\t\t}))\n\t\t\t.sort((a, b) => a.id.localeCompare(b.id)),\n\t\tmaxTokens: input.maxTokens,\n\t\tmodelId: input.keyBase.modelId,\n\t\tnamespace: input.keyBase.namespace,\n\t\tpolicyVersion: input.keyBase.policyVersion,\n\t\tpromptHash: input.promptHash ?? null,\n\t\tqueryIntentHash: input.keyBase.queryIntentHash,\n\t\tredactionPolicyHash: input.keyBase.redactionPolicyHash,\n\t\tresponseReserveTokens: input.responseReserveTokens,\n\t\tsafetyMarginTokens: input.safetyMarginTokens,\n\t\tsafetyProfileHash: input.keyBase.safetyProfileHash,\n\t\ttierPolicy: input.tierPolicy,\n\t\tqualityPolicy: input.qualityPolicy,\n\t\ttokenizerId: input.keyBase.tokenizerId,\n\t})}`;\n}\n"]}

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

@@ -0,0 +1,49 @@
+import { sha256Canonical } from "./context-budget-v2-cache-hash.js";
+import { computeContextBudgetRepresentationFingerprintV2, fingerprintSourceRef, } from "./context-budget-v2-cache-keys.js";
+export function buildContextBudgetPlanCacheKeyV2(input) {
+    return `context-plan:${sha256Canonical({
+        availableTokens: input.availableTokens,
+        budgetBucket: input.keyBase.budgetBucket,
+        items: input.planned
+            .map((planned) => ({
+            ageTurns: planned.item.ageTurns ?? null,
+            baseScore: planned.baseScore,
+            effectiveScore: planned.effectiveScore,
+            evidenceKind: planned.item.evidenceKind ?? null,
+            evidenceValue: planned.item.evidenceValue ?? null,
+            id: planned.item.id,
+            pinReason: planned.item.pinReason ?? null,
+            priority: planned.item.priority,
+            recency: planned.item.recency ?? null,
+            redundancyKey: planned.item.redundancyKey ?? null,
+            redundancyPenalty: planned.redundancyPenalty,
+            relevance: planned.item.relevance ?? null,
+            representations: (planned.item.representations ?? [])
+                .map((candidate) => ({
+                fingerprint: computeContextBudgetRepresentationFingerprintV2(candidate),
+                kind: candidate.kind,
+            }))
+                .sort((a, b) => a.kind.localeCompare(b.kind) || a.fingerprint.localeCompare(b.fingerprint)),
+            required: planned.item.required === true,
+            sourceRef: fingerprintSourceRef(planned.item.sourceRef),
+            sourceHash: planned.contentHash,
+            tier: planned.item.tier,
+            tokenEstimate: planned.item.tokenEstimate ?? null,
+        }))
+            .sort((a, b) => a.id.localeCompare(b.id)),
+        maxTokens: input.maxTokens,
+        modelId: input.keyBase.modelId,
+        namespace: input.keyBase.namespace,
+        policyVersion: input.keyBase.policyVersion,
+        promptHash: input.promptHash ?? null,
+        queryIntentHash: input.keyBase.queryIntentHash,
+        redactionPolicyHash: input.keyBase.redactionPolicyHash,
+        responseReserveTokens: input.responseReserveTokens,
+        safetyMarginTokens: input.safetyMarginTokens,
+        safetyProfileHash: input.keyBase.safetyProfileHash,
+        tierPolicy: input.tierPolicy,
+        qualityPolicy: input.qualityPolicy,
+        tokenizerId: input.keyBase.tokenizerId,
+    })}`;
+}
+//# sourceMappingURL=context-budget-v2-plan-cache-keys.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-v2-plan-cache-keys.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-plan-cache-keys.ts"],"names":[],"mappings":"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","sourcesContent":["import type { HeadroomQualityPolicyV2 } from \"./context-budget-headroom.ts\";\nimport { sha256Canonical } from \"./context-budget-v2-cache-hash.ts\";\nimport {\n\ttype ContextBudgetCacheKeyBaseV2,\n\tcomputeContextBudgetRepresentationFingerprintV2,\n\tfingerprintSourceRef,\n} from \"./context-budget-v2-cache-keys.ts\";\nimport type { PlannedItemV2 } from \"./context-budget-v2-scoring.ts\";\nimport type { TierBudgetPolicyV2 } from \"./context-budget-v2-types.ts\";\n\nexport function buildContextBudgetPlanCacheKeyV2(input: {\n\treadonly keyBase: ContextBudgetCacheKeyBaseV2;\n\treadonly promptHash?: string;\n\treadonly maxTokens: number;\n\treadonly responseReserveTokens: number;\n\treadonly safetyMarginTokens: number;\n\treadonly availableTokens: number;\n\treadonly planned: readonly PlannedItemV2[];\n\treadonly tierPolicy: Readonly<Record<string, TierBudgetPolicyV2>>;\n\treadonly qualityPolicy: HeadroomQualityPolicyV2;\n}): string {\n\treturn `context-plan:${sha256Canonical({\n\t\tavailableTokens: input.availableTokens,\n\t\tbudgetBucket: input.keyBase.budgetBucket,\n\t\titems: input.planned\n\t\t\t.map((planned) => ({\n\t\t\t\tageTurns: planned.item.ageTurns ?? null,\n\t\t\t\tbaseScore: planned.baseScore,\n\t\t\t\teffectiveScore: planned.effectiveScore,\n\t\t\t\tevidenceKind: planned.item.evidenceKind ?? null,\n\t\t\t\tevidenceValue: planned.item.evidenceValue ?? null,\n\t\t\t\tid: planned.item.id,\n\t\t\t\tpinReason: planned.item.pinReason ?? null,\n\t\t\t\tpriority: planned.item.priority,\n\t\t\t\trecency: planned.item.recency ?? null,\n\t\t\t\tredundancyKey: planned.item.redundancyKey ?? null,\n\t\t\t\tredundancyPenalty: planned.redundancyPenalty,\n\t\t\t\trelevance: planned.item.relevance ?? null,\n\t\t\t\trepresentations: (planned.item.representations ?? [])\n\t\t\t\t\t.map((candidate) => ({\n\t\t\t\t\t\tfingerprint: computeContextBudgetRepresentationFingerprintV2(candidate),\n\t\t\t\t\t\tkind: candidate.kind,\n\t\t\t\t\t}))\n\t\t\t\t\t.sort((a, b) => a.kind.localeCompare(b.kind) || a.fingerprint.localeCompare(b.fingerprint)),\n\t\t\t\trequired: planned.item.required === true,\n\t\t\t\tsourceRef: fingerprintSourceRef(planned.item.sourceRef),\n\t\t\t\tsourceHash: planned.contentHash,\n\t\t\t\ttier: planned.item.tier,\n\t\t\t\ttokenEstimate: planned.item.tokenEstimate ?? null,\n\t\t\t}))\n\t\t\t.sort((a, b) => a.id.localeCompare(b.id)),\n\t\tmaxTokens: input.maxTokens,\n\t\tmodelId: input.keyBase.modelId,\n\t\tnamespace: input.keyBase.namespace,\n\t\tpolicyVersion: input.keyBase.policyVersion,\n\t\tpromptHash: input.promptHash ?? null,\n\t\tqueryIntentHash: input.keyBase.queryIntentHash,\n\t\tredactionPolicyHash: input.keyBase.redactionPolicyHash,\n\t\tresponseReserveTokens: input.responseReserveTokens,\n\t\tsafetyMarginTokens: input.safetyMarginTokens,\n\t\tsafetyProfileHash: input.keyBase.safetyProfileHash,\n\t\ttierPolicy: input.tierPolicy,\n\t\tqualityPolicy: input.qualityPolicy,\n\t\ttokenizerId: input.keyBase.tokenizerId,\n\t})}`;\n}\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"context-budget-v2-planner.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-planner.ts"],"names":[],"mappings":"AAmBA,OAAO,EAGN,KAAK,0BAA0B,EAE/B,KAAK,yBAAyB,EAI9B,MAAM,8BAA8B,CAAC;AAGtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,0BAA0B,GAAG,yBAAyB,CAoHtG","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetTierV2,\n\ttype ContextSourceRefV2,\n\tDEFAULT_HEADROOM_QUALITY_POLICY,\n} from \"./context-budget-headroom.ts\";\nimport { computePlanHash } from \"./context-budget-v2-plan-hash.ts\";\nimport { compareOptionalForSelection } from \"./context-budget-v2-scoring.ts\";\nimport {\n\tapplyPlannerRedundancyPenalties,\n\tbuildTierAllocations,\n\tcreatePlannedItems,\n\tcreateTierUsage,\n\temitCoverageDiagnostics,\n\temitOmissionDiagnostics,\n\tselectHardItem,\n\tselectOptionalItem,\n} from \"./context-budget-v2-selection.ts\";\nimport { allocateTiers, computeTierDemand } from \"./context-budget-v2-tiers.ts\";\nimport {\n\tCONTEXT_BUDGET_POLICY_VERSION_V2,\n\tDEFAULT_TIER_POLICY_V2,\n\ttype PromptContextBudgetInputV2,\n\ttype PromptContextBudgetObservabilityV2,\n\ttype PromptContextBudgetPlanV2,\n\ttype QualityDiagnosticV2,\n\ttype SelectedRepresentationV2,\n\ttype TierBudgetPolicyV2,\n} from \"./context-budget-v2-types.ts\";\nimport { getTokenOptimizerRuntimeStatus } from \"./token-optimizer.ts\";\n\nexport function planPromptContextBudgetV2(input: PromptContextBudgetInputV2): PromptContextBudgetPlanV2 {\n\tconst modelId = input.modelId ?? \"unknown\";\n\tconst qualityPolicy = input.qualityPolicy ?? DEFAULT_HEADROOM_QUALITY_POLICY;\n\tconst policyVersion = input.policyVersion ?? CONTEXT_BUDGET_POLICY_VERSION_V2;\n\tconst diagnostics: QualityDiagnosticV2[] = [];\n\n\tconst maxTokens = normalizeBudgetTokens(\"maxTokens\", input.maxTokens, diagnostics);\n\tconst responseReserve = normalizeBudgetTokens(\n\t\t\"responseReserveTokens\",\n\t\tinput.responseReserveTokens ?? 0,\n\t\tdiagnostics,\n\t);\n\tconst safetyMargin = normalizeBudgetTokens(\n\t\t\"safetyMarginTokens\",\n\t\tinput.safetyMarginTokens ?? Math.ceil(maxTokens * 0.05),\n\t\tdiagnostics,\n\t);\n\tconst available = Math.max(0, maxTokens - responseReserve - safetyMargin);\n\n\tconst tierPolicy: Readonly<Record<ContextBudgetTierV2, TierBudgetPolicyV2>> = {\n\t\t...DEFAULT_TIER_POLICY_V2,\n\t\t...(input.tierPolicy ?? {}),\n\t};\n\tconst basePlanned = createPlannedItems(input.items, input.tokenCounter, modelId);\n\tapplyPlannerRedundancyPenalties(basePlanned);\n\n\tconst demand = computeTierDemand(basePlanned);\n\tconst allocation = allocateTiers(available, tierPolicy, demand);\n\tconst selection = new Map<string, SelectedRepresentationV2>();\n\tconst tierUsed = createTierUsage();\n\tconst omitted: ContextBudgetItemV2[] = [];\n\tconst retrievalFallbacks: ContextSourceRefV2[] = [];\n\tlet usedTokens = 0;\n\n\tfor (const planned of basePlanned) {\n\t\tif (!planned.isHard) continue;\n\t\tusedTokens += selectHardItem(planned, selection, tierUsed);\n\t}\n\tif (usedTokens > available) {\n\t\tdiagnostics.push({\n\t\t\treason: \"hard_pin_over_capacity\",\n\t\t\tdetail: `hard-pinned context uses ${usedTokens} tokens against ${available} available tokens`,\n\t\t});\n\t}\n\n\tconst optionalPlanned = basePlanned.filter((planned) => !planned.isHard).sort(compareOptionalForSelection);\n\tfor (const planned of optionalPlanned) {\n\t\tusedTokens = selectOptionalItem(planned, {\n\t\t\tallocation,\n\t\t\tavailable,\n\t\t\tdiagnostics,\n\t\t\tomitted,\n\t\t\tqualityPolicy,\n\t\t\tretrievalFallbacks,\n\t\t\tselection,\n\t\t\ttierUsed,\n\t\t\tusedTokens,\n\t\t});\n\t}\n\n\tconst omittedHighPriority = omitted.some((item) => item.priority === \"high\" || item.required === true);\n\temitOmissionDiagnostics(omitted, diagnostics, retrievalFallbacks);\n\temitCoverageDiagnostics(input.query, selection, diagnostics);\n\n\tconst tierAllocations = buildTierAllocations(allocation, demand, tierUsed);\n\tconst rawTokens = basePlanned.reduce((sum, planned) => sum + planned.fullTokens, 0);\n\tconst omittedTokens = omitted.reduce(\n\t\t(sum, item) => sum + (basePlanned.find((planned) => planned.item.id === item.id)?.fullTokens ?? 0),\n\t\t0,\n\t);\n\tconst omittedItemIds = omitted.map((item) => item.id);\n\tconst planHash = computePlanHash({\n\t\tpolicyVersion,\n\t\tpromptHash: input.promptHash,\n\t\tplanned: basePlanned,\n\t\tselection,\n\t\tallocations: tierAllocations,\n\t\tomittedItemIds,\n\t});\n\tconst observability = buildObservability({\n\t\tavailable,\n\t\tdiagnostics,\n\t\tomittedItemIds,\n\t\tomittedTokens,\n\t\tplanHash,\n\t\trawTokens,\n\t\tretrievalFallbacks,\n\t\tselection,\n\t\tusedTokens,\n\t});\n\n\treturn {\n\t\tpolicyVersion,\n\t\tpromptHash: input.promptHash,\n\t\tplanHash,\n\t\tmaxTokens,\n\t\tresponseReserveTokens: responseReserve,\n\t\tsafetyMarginTokens: safetyMargin,\n\t\tavailableTokens: available,\n\t\tusedTokens,\n\t\tomittedTokens,\n\t\trawTokens,\n\t\ttokenSavingsRatio: rawTokens > 0 ? Math.max(0, 1 - usedTokens / rawTokens) : 0,\n\t\temergency: usedTokens > available || diagnostics.some((diagnostic) => diagnostic.reason === \"invalid_budget\"),\n\t\tomittedHighPriority,\n\t\ttierAllocations,\n\t\tselectedRepresentations: [...selection.values()].sort((a, b) => a.itemId.localeCompare(b.itemId)),\n\t\tincludedItemIds: basePlanned\n\t\t\t.map((planned) => planned.item.id)\n\t\t\t.filter((id) => selection.has(id))\n\t\t\t.sort(),\n\t\tomittedItemIds,\n\t\tdiagnostics,\n\t\tretrievalFallbacks,\n\t\tobservability,\n\t};\n}\n\nfunction normalizeBudgetTokens(field: string, value: number, diagnostics: QualityDiagnosticV2[]): number {\n\tif (!Number.isFinite(value) || value < 0) {\n\t\tdiagnostics.push({\n\t\t\treason: \"invalid_budget\",\n\t\t\tdetail: `${field} must be a non-negative finite number, got ${value}`,\n\t\t});\n\t\treturn 0;\n\t}\n\treturn Math.floor(value);\n}\n\nfunction buildObservability(input: {\n\treadonly available: number;\n\treadonly diagnostics: readonly QualityDiagnosticV2[];\n\treadonly omittedItemIds: readonly string[];\n\treadonly omittedTokens: number;\n\treadonly planHash: string;\n\treadonly rawTokens: number;\n\treadonly retrievalFallbacks: readonly ContextSourceRefV2[];\n\treadonly selection: ReadonlyMap<string, SelectedRepresentationV2>;\n\treadonly usedTokens: number;\n}): PromptContextBudgetObservabilityV2 {\n\tconst selected = [...input.selection.values()];\n\treturn {\n\t\tcounts: {\n\t\t\tselected: selected.length,\n\t\t\tomitted: input.omittedItemIds.length,\n\t\t\tpointer: selected.filter((representation) => representation.kind === \"pointer\").length,\n\t\t\tcompressed: selected.filter((representation) => representation.kind === \"headroom-compressed\").length,\n\t\t\tfull: selected.filter((representation) => representation.kind === \"full\").length,\n\t\t\tretrievalFallback: countUniqueRetrievalFallbacks(input.retrievalFallbacks),\n\t\t},\n\t\tdiagnosticReasons: [...new Set(input.diagnostics.map((diagnostic) => diagnostic.reason))].sort(),\n\t\ttokens: {\n\t\t\tavailable: input.available,\n\t\t\tused: input.usedTokens,\n\t\t\traw: input.rawTokens,\n\t\t\tomitted: input.omittedTokens,\n\t\t\ttokenSavings: Math.max(0, input.rawTokens - input.usedTokens),\n\t\t},\n\t\tplanHash: input.planHash,\n\t\ttokenOptimizer: getTokenOptimizerRuntimeStatus(),\n\t};\n}\n\nfunction countUniqueRetrievalFallbacks(retrievalFallbacks: readonly ContextSourceRefV2[]): number {\n\treturn new Set(\n\t\tretrievalFallbacks.map((ref) =>\n\t\t\t[ref.uri, ref.contentHash, ref.symbol ?? \"\", ref.range?.startLine ?? \"\", ref.range?.endLine ?? \"\"].join(\"\\0\"),\n\t\t),\n\t).size;\n}\n"]}
+{"version":3,"file":"context-budget-v2-planner.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-planner.ts"],"names":[],"mappings":"AA2BA,OAAO,EAGN,KAAK,0BAA0B,EAE/B,KAAK,yBAAyB,EAI9B,MAAM,8BAA8B,CAAC;AAGtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,0BAA0B,GAAG,yBAAyB,CAuKtG","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetTierV2,\n\ttype ContextSourceRefV2,\n\tDEFAULT_HEADROOM_QUALITY_POLICY,\n} from \"./context-budget-headroom.ts\";\nimport {\n\tbuildContextBudgetPlanCacheKeyV2,\n\tcreateContextBudgetCacheKeyBaseV2,\n\tcreateContextBudgetSelectionCacheV2,\n\tfinalizeContextBudgetCacheTelemetryV2,\n\treadValidPlanCacheV2,\n\twritePlanCacheV2,\n} from \"./context-budget-v2-cache.ts\";\nimport { computePlanHash } from \"./context-budget-v2-plan-hash.ts\";\nimport { compareOptionalForSelection } from \"./context-budget-v2-scoring.ts\";\nimport {\n\tapplyPlannerRedundancyPenalties,\n\tbuildTierAllocations,\n\tcreatePlannedItems,\n\tcreateTierUsage,\n\temitCoverageDiagnostics,\n\temitOmissionDiagnostics,\n\tselectHardItem,\n\tselectOptionalItem,\n} from \"./context-budget-v2-selection.ts\";\nimport { allocateTiers, computeTierDemand } from \"./context-budget-v2-tiers.ts\";\nimport {\n\tCONTEXT_BUDGET_POLICY_VERSION_V2,\n\tDEFAULT_TIER_POLICY_V2,\n\ttype PromptContextBudgetInputV2,\n\ttype PromptContextBudgetObservabilityV2,\n\ttype PromptContextBudgetPlanV2,\n\ttype QualityDiagnosticV2,\n\ttype SelectedRepresentationV2,\n\ttype TierBudgetPolicyV2,\n} from \"./context-budget-v2-types.ts\";\nimport { getTokenOptimizerRuntimeStatus } from \"./token-optimizer.ts\";\n\nexport function planPromptContextBudgetV2(input: PromptContextBudgetInputV2): PromptContextBudgetPlanV2 {\n\tconst modelId = input.modelId ?? \"unknown\";\n\tconst qualityPolicy = input.qualityPolicy ?? DEFAULT_HEADROOM_QUALITY_POLICY;\n\tconst policyVersion = input.policyVersion ?? CONTEXT_BUDGET_POLICY_VERSION_V2;\n\tconst diagnostics: QualityDiagnosticV2[] = [];\n\n\tconst maxTokens = normalizeBudgetTokens(\"maxTokens\", input.maxTokens, diagnostics);\n\tconst responseReserve = normalizeBudgetTokens(\n\t\t\"responseReserveTokens\",\n\t\tinput.responseReserveTokens ?? 0,\n\t\tdiagnostics,\n\t);\n\tconst safetyMargin = normalizeBudgetTokens(\n\t\t\"safetyMarginTokens\",\n\t\tinput.safetyMarginTokens ?? Math.ceil(maxTokens * 0.05),\n\t\tdiagnostics,\n\t);\n\tconst available = Math.max(0, maxTokens - responseReserve - safetyMargin);\n\n\tconst tierPolicy: Readonly<Record<ContextBudgetTierV2, TierBudgetPolicyV2>> = {\n\t\t...DEFAULT_TIER_POLICY_V2,\n\t\t...(input.tierPolicy ?? {}),\n\t};\n\tconst basePlanned = createPlannedItems(input.items, input.tokenCounter, modelId);\n\tapplyPlannerRedundancyPenalties(basePlanned);\n\tconst rawTokens = basePlanned.reduce((sum, planned) => sum + planned.fullTokens, 0);\n\n\tconst demand = computeTierDemand(basePlanned);\n\tconst allocation = allocateTiers(available, tierPolicy, demand);\n\tconst cacheKeyBase = createContextBudgetCacheKeyBaseV2({\n\t\tbudgetBucket: input.cacheBudgetBucket ?? String(available),\n\t\tmodelId,\n\t\tnamespace: input.cacheNamespace,\n\t\tpolicyVersion,\n\t\tquery: input.query,\n\t\tqueryIntentHash: input.queryIntentHash,\n\t\tredactionPolicyHash: input.redactionPolicyHash,\n\t\tsafetyProfileHash: input.safetyProfileHash,\n\t\ttokenizerId: input.tokenizerId,\n\t});\n\tconst planCacheKey = buildContextBudgetPlanCacheKeyV2({\n\t\tavailableTokens: available,\n\t\tkeyBase: cacheKeyBase,\n\t\tmaxTokens,\n\t\tplanned: basePlanned,\n\t\tpromptHash: input.promptHash,\n\t\tqualityPolicy,\n\t\tresponseReserveTokens: responseReserve,\n\t\tsafetyMarginTokens: safetyMargin,\n\t\ttierPolicy,\n\t});\n\tconst cache = createContextBudgetSelectionCacheV2({\n\t\tkeyBase: cacheKeyBase,\n\t\tnowEpochMs: input.cacheNowEpochMs,\n\t\tplanCacheKey,\n\t\tprovider: input.cacheProvider,\n\t\tttlMs: input.cacheTtlMs,\n\t});\n\tconst cachedPlan = readValidPlanCacheV2({\n\t\tavailableTokens: available,\n\t\tcache,\n\t\tkey: planCacheKey,\n\t\tplanned: basePlanned,\n\t});\n\tif (cachedPlan) {\n\t\treturn cachedPlan;\n\t}\n\tconst selection = new Map<string, SelectedRepresentationV2>();\n\tconst tierUsed = createTierUsage();\n\tconst omitted: ContextBudgetItemV2[] = [];\n\tconst retrievalFallbacks: ContextSourceRefV2[] = [];\n\tlet usedTokens = 0;\n\n\tfor (const planned of basePlanned) {\n\t\tif (!planned.isHard) continue;\n\t\tusedTokens += selectHardItem(planned, selection, tierUsed);\n\t}\n\tif (usedTokens > available) {\n\t\tdiagnostics.push({\n\t\t\treason: \"hard_pin_over_capacity\",\n\t\t\tdetail: `hard-pinned context uses ${usedTokens} tokens against ${available} available tokens`,\n\t\t});\n\t}\n\n\tconst optionalPlanned = basePlanned.filter((planned) => !planned.isHard).sort(compareOptionalForSelection);\n\tfor (const planned of optionalPlanned) {\n\t\tusedTokens = selectOptionalItem(planned, {\n\t\t\tallocation,\n\t\t\tavailable,\n\t\t\tcache,\n\t\t\tdiagnostics,\n\t\t\tomitted,\n\t\t\tqualityPolicy,\n\t\t\tretrievalFallbacks,\n\t\t\tselection,\n\t\t\ttierUsed,\n\t\t\tusedTokens,\n\t\t});\n\t}\n\n\tconst omittedHighPriority = omitted.some((item) => item.priority === \"high\" || item.required === true);\n\temitOmissionDiagnostics(omitted, diagnostics, retrievalFallbacks);\n\temitCoverageDiagnostics(input.query, selection, diagnostics);\n\n\tconst tierAllocations = buildTierAllocations(allocation, demand, tierUsed);\n\tconst omittedTokens = omitted.reduce(\n\t\t(sum, item) => sum + (basePlanned.find((planned) => planned.item.id === item.id)?.fullTokens ?? 0),\n\t\t0,\n\t);\n\tconst omittedItemIds = omitted.map((item) => item.id);\n\tconst planHash = computePlanHash({\n\t\tpolicyVersion,\n\t\tpromptHash: input.promptHash,\n\t\tplanned: basePlanned,\n\t\tselection,\n\t\tallocations: tierAllocations,\n\t\tomittedItemIds,\n\t});\n\tconst observability = buildObservability({\n\t\tavailable,\n\t\tdiagnostics,\n\t\tomittedItemIds,\n\t\tomittedTokens,\n\t\tplanHash,\n\t\trawTokens,\n\t\tretrievalFallbacks,\n\t\tselection,\n\t\tusedTokens,\n\t\tcacheTelemetry: finalizeContextBudgetCacheTelemetryV2(cache.telemetry, {\n\t\t\tomittedTokens,\n\t\t\trawTokens,\n\t\t\tusedTokens,\n\t\t}),\n\t});\n\n\tconst plan: PromptContextBudgetPlanV2 = {\n\t\tpolicyVersion,\n\t\tpromptHash: input.promptHash,\n\t\tplanHash,\n\t\tmaxTokens,\n\t\tresponseReserveTokens: responseReserve,\n\t\tsafetyMarginTokens: safetyMargin,\n\t\tavailableTokens: available,\n\t\tusedTokens,\n\t\tomittedTokens,\n\t\trawTokens,\n\t\ttokenSavingsRatio: rawTokens > 0 ? Math.max(0, 1 - usedTokens / rawTokens) : 0,\n\t\temergency: usedTokens > available || diagnostics.some((diagnostic) => diagnostic.reason === \"invalid_budget\"),\n\t\tomittedHighPriority,\n\t\ttierAllocations,\n\t\tselectedRepresentations: [...selection.values()].sort((a, b) => a.itemId.localeCompare(b.itemId)),\n\t\tincludedItemIds: basePlanned\n\t\t\t.map((planned) => planned.item.id)\n\t\t\t.filter((id) => selection.has(id))\n\t\t\t.sort(),\n\t\tomittedItemIds,\n\t\tdiagnostics,\n\t\tretrievalFallbacks,\n\t\tobservability,\n\t};\n\twritePlanCacheV2({\n\t\tcache,\n\t\tkey: planCacheKey,\n\t\tplan,\n\t\tplanned: basePlanned,\n\t});\n\treturn plan;\n}\n\nfunction normalizeBudgetTokens(field: string, value: number, diagnostics: QualityDiagnosticV2[]): number {\n\tif (!Number.isFinite(value) || value < 0) {\n\t\tdiagnostics.push({\n\t\t\treason: \"invalid_budget\",\n\t\t\tdetail: `${field} must be a non-negative finite number, got ${value}`,\n\t\t});\n\t\treturn 0;\n\t}\n\treturn Math.floor(value);\n}\n\nfunction buildObservability(input: {\n\treadonly available: number;\n\treadonly diagnostics: readonly QualityDiagnosticV2[];\n\treadonly omittedItemIds: readonly string[];\n\treadonly omittedTokens: number;\n\treadonly planHash: string;\n\treadonly rawTokens: number;\n\treadonly retrievalFallbacks: readonly ContextSourceRefV2[];\n\treadonly selection: ReadonlyMap<string, SelectedRepresentationV2>;\n\treadonly usedTokens: number;\n\treadonly cacheTelemetry: PromptContextBudgetObservabilityV2[\"cache\"];\n}): PromptContextBudgetObservabilityV2 {\n\tconst selected = [...input.selection.values()];\n\treturn {\n\t\tcounts: {\n\t\t\tselected: selected.length,\n\t\t\tomitted: input.omittedItemIds.length,\n\t\t\tpointer: selected.filter((representation) => representation.kind === \"pointer\").length,\n\t\t\tcompressed: selected.filter((representation) => representation.kind === \"headroom-compressed\").length,\n\t\t\tfull: selected.filter((representation) => representation.kind === \"full\").length,\n\t\t\tretrievalFallback: countUniqueRetrievalFallbacks(input.retrievalFallbacks),\n\t\t},\n\t\tdiagnosticReasons: [...new Set(input.diagnostics.map((diagnostic) => diagnostic.reason))].sort(),\n\t\ttokens: {\n\t\t\tavailable: input.available,\n\t\t\tused: input.usedTokens,\n\t\t\traw: input.rawTokens,\n\t\t\tomitted: input.omittedTokens,\n\t\t\ttokenSavings: Math.max(0, input.rawTokens - input.usedTokens),\n\t\t},\n\t\tplanHash: input.planHash,\n\t\tcache: input.cacheTelemetry,\n\t\ttokenOptimizer: getTokenOptimizerRuntimeStatus(),\n\t};\n}\n\nfunction countUniqueRetrievalFallbacks(retrievalFallbacks: readonly ContextSourceRefV2[]): number {\n\treturn new Set(\n\t\tretrievalFallbacks.map((ref) =>\n\t\t\t[ref.uri, ref.contentHash, ref.symbol ?? \"\", ref.range?.startLine ?? \"\", ref.range?.endLine ?? \"\"].join(\"\\0\"),\n\t\t),\n\t).size;\n}\n"]}

package/dist/core/context-budget-v2-planner.js

@@ -1,4 +1,5 @@
 import { DEFAULT_HEADROOM_QUALITY_POLICY, } from "./context-budget-headroom.js";
+import { buildContextBudgetPlanCacheKeyV2, createContextBudgetCacheKeyBaseV2, createContextBudgetSelectionCacheV2, finalizeContextBudgetCacheTelemetryV2, readValidPlanCacheV2, writePlanCacheV2, } from "./context-budget-v2-cache.js";
 import { computePlanHash } from "./context-budget-v2-plan-hash.js";
 import { compareOptionalForSelection } from "./context-budget-v2-scoring.js";
 import { applyPlannerRedundancyPenalties, buildTierAllocations, createPlannedItems, createTierUsage, emitCoverageDiagnostics, emitOmissionDiagnostics, selectHardItem, selectOptionalItem, } from "./context-budget-v2-selection.js";
@@ -20,8 +21,47 @@ export function planPromptContextBudgetV2(input) {
     };
     const basePlanned = createPlannedItems(input.items, input.tokenCounter, modelId);
     applyPlannerRedundancyPenalties(basePlanned);
+    const rawTokens = basePlanned.reduce((sum, planned) => sum + planned.fullTokens, 0);
     const demand = computeTierDemand(basePlanned);
     const allocation = allocateTiers(available, tierPolicy, demand);
+    const cacheKeyBase = createContextBudgetCacheKeyBaseV2({
+        budgetBucket: input.cacheBudgetBucket ?? String(available),
+        modelId,
+        namespace: input.cacheNamespace,
+        policyVersion,
+        query: input.query,
+        queryIntentHash: input.queryIntentHash,
+        redactionPolicyHash: input.redactionPolicyHash,
+        safetyProfileHash: input.safetyProfileHash,
+        tokenizerId: input.tokenizerId,
+    });
+    const planCacheKey = buildContextBudgetPlanCacheKeyV2({
+        availableTokens: available,
+        keyBase: cacheKeyBase,
+        maxTokens,
+        planned: basePlanned,
+        promptHash: input.promptHash,
+        qualityPolicy,
+        responseReserveTokens: responseReserve,
+        safetyMarginTokens: safetyMargin,
+        tierPolicy,
+    });
+    const cache = createContextBudgetSelectionCacheV2({
+        keyBase: cacheKeyBase,
+        nowEpochMs: input.cacheNowEpochMs,
+        planCacheKey,
+        provider: input.cacheProvider,
+        ttlMs: input.cacheTtlMs,
+    });
+    const cachedPlan = readValidPlanCacheV2({
+        availableTokens: available,
+        cache,
+        key: planCacheKey,
+        planned: basePlanned,
+    });
+    if (cachedPlan) {
+        return cachedPlan;
+    }
     const selection = new Map();
     const tierUsed = createTierUsage();
     const omitted = [];
@@ -43,6 +83,7 @@ export function planPromptContextBudgetV2(input) {
         usedTokens = selectOptionalItem(planned, {
             allocation,
             available,
+            cache,
             diagnostics,
             omitted,
             qualityPolicy,
@@ -56,7 +97,6 @@ export function planPromptContextBudgetV2(input) {
     emitOmissionDiagnostics(omitted, diagnostics, retrievalFallbacks);
     emitCoverageDiagnostics(input.query, selection, diagnostics);
     const tierAllocations = buildTierAllocations(allocation, demand, tierUsed);
-    const rawTokens = basePlanned.reduce((sum, planned) => sum + planned.fullTokens, 0);
     const omittedTokens = omitted.reduce((sum, item) => sum + (basePlanned.find((planned) => planned.item.id === item.id)?.fullTokens ?? 0), 0);
     const omittedItemIds = omitted.map((item) => item.id);
     const planHash = computePlanHash({
@@ -77,8 +117,13 @@ export function planPromptContextBudgetV2(input) {
         retrievalFallbacks,
         selection,
         usedTokens,
+        cacheTelemetry: finalizeContextBudgetCacheTelemetryV2(cache.telemetry, {
+            omittedTokens,
+            rawTokens,
+            usedTokens,
+        }),
     });
-    return {
+    const plan = {
         policyVersion,
         promptHash: input.promptHash,
         planHash,
@@ -103,6 +148,13 @@ export function planPromptContextBudgetV2(input) {
         retrievalFallbacks,
         observability,
     };
+    writePlanCacheV2({
+        cache,
+        key: planCacheKey,
+        plan,
+        planned: basePlanned,
+    });
+    return plan;
 }
 function normalizeBudgetTokens(field, value, diagnostics) {
     if (!Number.isFinite(value) || value < 0) {
@@ -134,6 +186,7 @@ function buildObservability(input) {
             tokenSavings: Math.max(0, input.rawTokens - input.usedTokens),
         },
         planHash: input.planHash,
+        cache: input.cacheTelemetry,
         tokenOptimizer: getTokenOptimizerRuntimeStatus(),
     };
 }

package/dist/core/context-budget-v2-planner.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget-v2-planner.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-planner.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetTierV2,\n\ttype ContextSourceRefV2,\n\tDEFAULT_HEADROOM_QUALITY_POLICY,\n} from \"./context-budget-headroom.ts\";\nimport { computePlanHash } from \"./context-budget-v2-plan-hash.ts\";\nimport { compareOptionalForSelection } from \"./context-budget-v2-scoring.ts\";\nimport {\n\tapplyPlannerRedundancyPenalties,\n\tbuildTierAllocations,\n\tcreatePlannedItems,\n\tcreateTierUsage,\n\temitCoverageDiagnostics,\n\temitOmissionDiagnostics,\n\tselectHardItem,\n\tselectOptionalItem,\n} from \"./context-budget-v2-selection.ts\";\nimport { allocateTiers, computeTierDemand } from \"./context-budget-v2-tiers.ts\";\nimport {\n\tCONTEXT_BUDGET_POLICY_VERSION_V2,\n\tDEFAULT_TIER_POLICY_V2,\n\ttype PromptContextBudgetInputV2,\n\ttype PromptContextBudgetObservabilityV2,\n\ttype PromptContextBudgetPlanV2,\n\ttype QualityDiagnosticV2,\n\ttype SelectedRepresentationV2,\n\ttype TierBudgetPolicyV2,\n} from \"./context-budget-v2-types.ts\";\nimport { getTokenOptimizerRuntimeStatus } from \"./token-optimizer.ts\";\n\nexport function planPromptContextBudgetV2(input: PromptContextBudgetInputV2): PromptContextBudgetPlanV2 {\n\tconst modelId = input.modelId ?? \"unknown\";\n\tconst qualityPolicy = input.qualityPolicy ?? DEFAULT_HEADROOM_QUALITY_POLICY;\n\tconst policyVersion = input.policyVersion ?? CONTEXT_BUDGET_POLICY_VERSION_V2;\n\tconst diagnostics: QualityDiagnosticV2[] = [];\n\n\tconst maxTokens = normalizeBudgetTokens(\"maxTokens\", input.maxTokens, diagnostics);\n\tconst responseReserve = normalizeBudgetTokens(\n\t\t\"responseReserveTokens\",\n\t\tinput.responseReserveTokens ?? 0,\n\t\tdiagnostics,\n\t);\n\tconst safetyMargin = normalizeBudgetTokens(\n\t\t\"safetyMarginTokens\",\n\t\tinput.safetyMarginTokens ?? Math.ceil(maxTokens * 0.05),\n\t\tdiagnostics,\n\t);\n\tconst available = Math.max(0, maxTokens - responseReserve - safetyMargin);\n\n\tconst tierPolicy: Readonly<Record<ContextBudgetTierV2, TierBudgetPolicyV2>> = {\n\t\t...DEFAULT_TIER_POLICY_V2,\n\t\t...(input.tierPolicy ?? {}),\n\t};\n\tconst basePlanned = createPlannedItems(input.items, input.tokenCounter, modelId);\n\tapplyPlannerRedundancyPenalties(basePlanned);\n\n\tconst demand = computeTierDemand(basePlanned);\n\tconst allocation = allocateTiers(available, tierPolicy, demand);\n\tconst selection = new Map<string, SelectedRepresentationV2>();\n\tconst tierUsed = createTierUsage();\n\tconst omitted: ContextBudgetItemV2[] = [];\n\tconst retrievalFallbacks: ContextSourceRefV2[] = [];\n\tlet usedTokens = 0;\n\n\tfor (const planned of basePlanned) {\n\t\tif (!planned.isHard) continue;\n\t\tusedTokens += selectHardItem(planned, selection, tierUsed);\n\t}\n\tif (usedTokens > available) {\n\t\tdiagnostics.push({\n\t\t\treason: \"hard_pin_over_capacity\",\n\t\t\tdetail: `hard-pinned context uses ${usedTokens} tokens against ${available} available tokens`,\n\t\t});\n\t}\n\n\tconst optionalPlanned = basePlanned.filter((planned) => !planned.isHard).sort(compareOptionalForSelection);\n\tfor (const planned of optionalPlanned) {\n\t\tusedTokens = selectOptionalItem(planned, {\n\t\t\tallocation,\n\t\t\tavailable,\n\t\t\tdiagnostics,\n\t\t\tomitted,\n\t\t\tqualityPolicy,\n\t\t\tretrievalFallbacks,\n\t\t\tselection,\n\t\t\ttierUsed,\n\t\t\tusedTokens,\n\t\t});\n\t}\n\n\tconst omittedHighPriority = omitted.some((item) => item.priority === \"high\" || item.required === true);\n\temitOmissionDiagnostics(omitted, diagnostics, retrievalFallbacks);\n\temitCoverageDiagnostics(input.query, selection, diagnostics);\n\n\tconst tierAllocations = buildTierAllocations(allocation, demand, tierUsed);\n\tconst rawTokens = basePlanned.reduce((sum, planned) => sum + planned.fullTokens, 0);\n\tconst omittedTokens = omitted.reduce(\n\t\t(sum, item) => sum + (basePlanned.find((planned) => planned.item.id === item.id)?.fullTokens ?? 0),\n\t\t0,\n\t);\n\tconst omittedItemIds = omitted.map((item) => item.id);\n\tconst planHash = computePlanHash({\n\t\tpolicyVersion,\n\t\tpromptHash: input.promptHash,\n\t\tplanned: basePlanned,\n\t\tselection,\n\t\tallocations: tierAllocations,\n\t\tomittedItemIds,\n\t});\n\tconst observability = buildObservability({\n\t\tavailable,\n\t\tdiagnostics,\n\t\tomittedItemIds,\n\t\tomittedTokens,\n\t\tplanHash,\n\t\trawTokens,\n\t\tretrievalFallbacks,\n\t\tselection,\n\t\tusedTokens,\n\t});\n\n\treturn {\n\t\tpolicyVersion,\n\t\tpromptHash: input.promptHash,\n\t\tplanHash,\n\t\tmaxTokens,\n\t\tresponseReserveTokens: responseReserve,\n\t\tsafetyMarginTokens: safetyMargin,\n\t\tavailableTokens: available,\n\t\tusedTokens,\n\t\tomittedTokens,\n\t\trawTokens,\n\t\ttokenSavingsRatio: rawTokens > 0 ? Math.max(0, 1 - usedTokens / rawTokens) : 0,\n\t\temergency: usedTokens > available || diagnostics.some((diagnostic) => diagnostic.reason === \"invalid_budget\"),\n\t\tomittedHighPriority,\n\t\ttierAllocations,\n\t\tselectedRepresentations: [...selection.values()].sort((a, b) => a.itemId.localeCompare(b.itemId)),\n\t\tincludedItemIds: basePlanned\n\t\t\t.map((planned) => planned.item.id)\n\t\t\t.filter((id) => selection.has(id))\n\t\t\t.sort(),\n\t\tomittedItemIds,\n\t\tdiagnostics,\n\t\tretrievalFallbacks,\n\t\tobservability,\n\t};\n}\n\nfunction normalizeBudgetTokens(field: string, value: number, diagnostics: QualityDiagnosticV2[]): number {\n\tif (!Number.isFinite(value) || value < 0) {\n\t\tdiagnostics.push({\n\t\t\treason: \"invalid_budget\",\n\t\t\tdetail: `${field} must be a non-negative finite number, got ${value}`,\n\t\t});\n\t\treturn 0;\n\t}\n\treturn Math.floor(value);\n}\n\nfunction buildObservability(input: {\n\treadonly available: number;\n\treadonly diagnostics: readonly QualityDiagnosticV2[];\n\treadonly omittedItemIds: readonly string[];\n\treadonly omittedTokens: number;\n\treadonly planHash: string;\n\treadonly rawTokens: number;\n\treadonly retrievalFallbacks: readonly ContextSourceRefV2[];\n\treadonly selection: ReadonlyMap<string, SelectedRepresentationV2>;\n\treadonly usedTokens: number;\n}): PromptContextBudgetObservabilityV2 {\n\tconst selected = [...input.selection.values()];\n\treturn {\n\t\tcounts: {\n\t\t\tselected: selected.length,\n\t\t\tomitted: input.omittedItemIds.length,\n\t\t\tpointer: selected.filter((representation) => representation.kind === \"pointer\").length,\n\t\t\tcompressed: selected.filter((representation) => representation.kind === \"headroom-compressed\").length,\n\t\t\tfull: selected.filter((representation) => representation.kind === \"full\").length,\n\t\t\tretrievalFallback: countUniqueRetrievalFallbacks(input.retrievalFallbacks),\n\t\t},\n\t\tdiagnosticReasons: [...new Set(input.diagnostics.map((diagnostic) => diagnostic.reason))].sort(),\n\t\ttokens: {\n\t\t\tavailable: input.available,\n\t\t\tused: input.usedTokens,\n\t\t\traw: input.rawTokens,\n\t\t\tomitted: input.omittedTokens,\n\t\t\ttokenSavings: Math.max(0, input.rawTokens - input.usedTokens),\n\t\t},\n\t\tplanHash: input.planHash,\n\t\ttokenOptimizer: getTokenOptimizerRuntimeStatus(),\n\t};\n}\n\nfunction countUniqueRetrievalFallbacks(retrievalFallbacks: readonly ContextSourceRefV2[]): number {\n\treturn new Set(\n\t\tretrievalFallbacks.map((ref) =>\n\t\t\t[ref.uri, ref.contentHash, ref.symbol ?? \"\", ref.range?.startLine ?? \"\", ref.range?.endLine ?? \"\"].join(\"\\0\"),\n\t\t),\n\t).size;\n}\n"]}
+{"version":3,"file":"context-budget-v2-planner.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-planner.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetTierV2,\n\ttype ContextSourceRefV2,\n\tDEFAULT_HEADROOM_QUALITY_POLICY,\n} from \"./context-budget-headroom.ts\";\nimport {\n\tbuildContextBudgetPlanCacheKeyV2,\n\tcreateContextBudgetCacheKeyBaseV2,\n\tcreateContextBudgetSelectionCacheV2,\n\tfinalizeContextBudgetCacheTelemetryV2,\n\treadValidPlanCacheV2,\n\twritePlanCacheV2,\n} from \"./context-budget-v2-cache.ts\";\nimport { computePlanHash } from \"./context-budget-v2-plan-hash.ts\";\nimport { compareOptionalForSelection } from \"./context-budget-v2-scoring.ts\";\nimport {\n\tapplyPlannerRedundancyPenalties,\n\tbuildTierAllocations,\n\tcreatePlannedItems,\n\tcreateTierUsage,\n\temitCoverageDiagnostics,\n\temitOmissionDiagnostics,\n\tselectHardItem,\n\tselectOptionalItem,\n} from \"./context-budget-v2-selection.ts\";\nimport { allocateTiers, computeTierDemand } from \"./context-budget-v2-tiers.ts\";\nimport {\n\tCONTEXT_BUDGET_POLICY_VERSION_V2,\n\tDEFAULT_TIER_POLICY_V2,\n\ttype PromptContextBudgetInputV2,\n\ttype PromptContextBudgetObservabilityV2,\n\ttype PromptContextBudgetPlanV2,\n\ttype QualityDiagnosticV2,\n\ttype SelectedRepresentationV2,\n\ttype TierBudgetPolicyV2,\n} from \"./context-budget-v2-types.ts\";\nimport { getTokenOptimizerRuntimeStatus } from \"./token-optimizer.ts\";\n\nexport function planPromptContextBudgetV2(input: PromptContextBudgetInputV2): PromptContextBudgetPlanV2 {\n\tconst modelId = input.modelId ?? \"unknown\";\n\tconst qualityPolicy = input.qualityPolicy ?? DEFAULT_HEADROOM_QUALITY_POLICY;\n\tconst policyVersion = input.policyVersion ?? CONTEXT_BUDGET_POLICY_VERSION_V2;\n\tconst diagnostics: QualityDiagnosticV2[] = [];\n\n\tconst maxTokens = normalizeBudgetTokens(\"maxTokens\", input.maxTokens, diagnostics);\n\tconst responseReserve = normalizeBudgetTokens(\n\t\t\"responseReserveTokens\",\n\t\tinput.responseReserveTokens ?? 0,\n\t\tdiagnostics,\n\t);\n\tconst safetyMargin = normalizeBudgetTokens(\n\t\t\"safetyMarginTokens\",\n\t\tinput.safetyMarginTokens ?? Math.ceil(maxTokens * 0.05),\n\t\tdiagnostics,\n\t);\n\tconst available = Math.max(0, maxTokens - responseReserve - safetyMargin);\n\n\tconst tierPolicy: Readonly<Record<ContextBudgetTierV2, TierBudgetPolicyV2>> = {\n\t\t...DEFAULT_TIER_POLICY_V2,\n\t\t...(input.tierPolicy ?? {}),\n\t};\n\tconst basePlanned = createPlannedItems(input.items, input.tokenCounter, modelId);\n\tapplyPlannerRedundancyPenalties(basePlanned);\n\tconst rawTokens = basePlanned.reduce((sum, planned) => sum + planned.fullTokens, 0);\n\n\tconst demand = computeTierDemand(basePlanned);\n\tconst allocation = allocateTiers(available, tierPolicy, demand);\n\tconst cacheKeyBase = createContextBudgetCacheKeyBaseV2({\n\t\tbudgetBucket: input.cacheBudgetBucket ?? String(available),\n\t\tmodelId,\n\t\tnamespace: input.cacheNamespace,\n\t\tpolicyVersion,\n\t\tquery: input.query,\n\t\tqueryIntentHash: input.queryIntentHash,\n\t\tredactionPolicyHash: input.redactionPolicyHash,\n\t\tsafetyProfileHash: input.safetyProfileHash,\n\t\ttokenizerId: input.tokenizerId,\n\t});\n\tconst planCacheKey = buildContextBudgetPlanCacheKeyV2({\n\t\tavailableTokens: available,\n\t\tkeyBase: cacheKeyBase,\n\t\tmaxTokens,\n\t\tplanned: basePlanned,\n\t\tpromptHash: input.promptHash,\n\t\tqualityPolicy,\n\t\tresponseReserveTokens: responseReserve,\n\t\tsafetyMarginTokens: safetyMargin,\n\t\ttierPolicy,\n\t});\n\tconst cache = createContextBudgetSelectionCacheV2({\n\t\tkeyBase: cacheKeyBase,\n\t\tnowEpochMs: input.cacheNowEpochMs,\n\t\tplanCacheKey,\n\t\tprovider: input.cacheProvider,\n\t\tttlMs: input.cacheTtlMs,\n\t});\n\tconst cachedPlan = readValidPlanCacheV2({\n\t\tavailableTokens: available,\n\t\tcache,\n\t\tkey: planCacheKey,\n\t\tplanned: basePlanned,\n\t});\n\tif (cachedPlan) {\n\t\treturn cachedPlan;\n\t}\n\tconst selection = new Map<string, SelectedRepresentationV2>();\n\tconst tierUsed = createTierUsage();\n\tconst omitted: ContextBudgetItemV2[] = [];\n\tconst retrievalFallbacks: ContextSourceRefV2[] = [];\n\tlet usedTokens = 0;\n\n\tfor (const planned of basePlanned) {\n\t\tif (!planned.isHard) continue;\n\t\tusedTokens += selectHardItem(planned, selection, tierUsed);\n\t}\n\tif (usedTokens > available) {\n\t\tdiagnostics.push({\n\t\t\treason: \"hard_pin_over_capacity\",\n\t\t\tdetail: `hard-pinned context uses ${usedTokens} tokens against ${available} available tokens`,\n\t\t});\n\t}\n\n\tconst optionalPlanned = basePlanned.filter((planned) => !planned.isHard).sort(compareOptionalForSelection);\n\tfor (const planned of optionalPlanned) {\n\t\tusedTokens = selectOptionalItem(planned, {\n\t\t\tallocation,\n\t\t\tavailable,\n\t\t\tcache,\n\t\t\tdiagnostics,\n\t\t\tomitted,\n\t\t\tqualityPolicy,\n\t\t\tretrievalFallbacks,\n\t\t\tselection,\n\t\t\ttierUsed,\n\t\t\tusedTokens,\n\t\t});\n\t}\n\n\tconst omittedHighPriority = omitted.some((item) => item.priority === \"high\" || item.required === true);\n\temitOmissionDiagnostics(omitted, diagnostics, retrievalFallbacks);\n\temitCoverageDiagnostics(input.query, selection, diagnostics);\n\n\tconst tierAllocations = buildTierAllocations(allocation, demand, tierUsed);\n\tconst omittedTokens = omitted.reduce(\n\t\t(sum, item) => sum + (basePlanned.find((planned) => planned.item.id === item.id)?.fullTokens ?? 0),\n\t\t0,\n\t);\n\tconst omittedItemIds = omitted.map((item) => item.id);\n\tconst planHash = computePlanHash({\n\t\tpolicyVersion,\n\t\tpromptHash: input.promptHash,\n\t\tplanned: basePlanned,\n\t\tselection,\n\t\tallocations: tierAllocations,\n\t\tomittedItemIds,\n\t});\n\tconst observability = buildObservability({\n\t\tavailable,\n\t\tdiagnostics,\n\t\tomittedItemIds,\n\t\tomittedTokens,\n\t\tplanHash,\n\t\trawTokens,\n\t\tretrievalFallbacks,\n\t\tselection,\n\t\tusedTokens,\n\t\tcacheTelemetry: finalizeContextBudgetCacheTelemetryV2(cache.telemetry, {\n\t\t\tomittedTokens,\n\t\t\trawTokens,\n\t\t\tusedTokens,\n\t\t}),\n\t});\n\n\tconst plan: PromptContextBudgetPlanV2 = {\n\t\tpolicyVersion,\n\t\tpromptHash: input.promptHash,\n\t\tplanHash,\n\t\tmaxTokens,\n\t\tresponseReserveTokens: responseReserve,\n\t\tsafetyMarginTokens: safetyMargin,\n\t\tavailableTokens: available,\n\t\tusedTokens,\n\t\tomittedTokens,\n\t\trawTokens,\n\t\ttokenSavingsRatio: rawTokens > 0 ? Math.max(0, 1 - usedTokens / rawTokens) : 0,\n\t\temergency: usedTokens > available || diagnostics.some((diagnostic) => diagnostic.reason === \"invalid_budget\"),\n\t\tomittedHighPriority,\n\t\ttierAllocations,\n\t\tselectedRepresentations: [...selection.values()].sort((a, b) => a.itemId.localeCompare(b.itemId)),\n\t\tincludedItemIds: basePlanned\n\t\t\t.map((planned) => planned.item.id)\n\t\t\t.filter((id) => selection.has(id))\n\t\t\t.sort(),\n\t\tomittedItemIds,\n\t\tdiagnostics,\n\t\tretrievalFallbacks,\n\t\tobservability,\n\t};\n\twritePlanCacheV2({\n\t\tcache,\n\t\tkey: planCacheKey,\n\t\tplan,\n\t\tplanned: basePlanned,\n\t});\n\treturn plan;\n}\n\nfunction normalizeBudgetTokens(field: string, value: number, diagnostics: QualityDiagnosticV2[]): number {\n\tif (!Number.isFinite(value) || value < 0) {\n\t\tdiagnostics.push({\n\t\t\treason: \"invalid_budget\",\n\t\t\tdetail: `${field} must be a non-negative finite number, got ${value}`,\n\t\t});\n\t\treturn 0;\n\t}\n\treturn Math.floor(value);\n}\n\nfunction buildObservability(input: {\n\treadonly available: number;\n\treadonly diagnostics: readonly QualityDiagnosticV2[];\n\treadonly omittedItemIds: readonly string[];\n\treadonly omittedTokens: number;\n\treadonly planHash: string;\n\treadonly rawTokens: number;\n\treadonly retrievalFallbacks: readonly ContextSourceRefV2[];\n\treadonly selection: ReadonlyMap<string, SelectedRepresentationV2>;\n\treadonly usedTokens: number;\n\treadonly cacheTelemetry: PromptContextBudgetObservabilityV2[\"cache\"];\n}): PromptContextBudgetObservabilityV2 {\n\tconst selected = [...input.selection.values()];\n\treturn {\n\t\tcounts: {\n\t\t\tselected: selected.length,\n\t\t\tomitted: input.omittedItemIds.length,\n\t\t\tpointer: selected.filter((representation) => representation.kind === \"pointer\").length,\n\t\t\tcompressed: selected.filter((representation) => representation.kind === \"headroom-compressed\").length,\n\t\t\tfull: selected.filter((representation) => representation.kind === \"full\").length,\n\t\t\tretrievalFallback: countUniqueRetrievalFallbacks(input.retrievalFallbacks),\n\t\t},\n\t\tdiagnosticReasons: [...new Set(input.diagnostics.map((diagnostic) => diagnostic.reason))].sort(),\n\t\ttokens: {\n\t\t\tavailable: input.available,\n\t\t\tused: input.usedTokens,\n\t\t\traw: input.rawTokens,\n\t\t\tomitted: input.omittedTokens,\n\t\t\ttokenSavings: Math.max(0, input.rawTokens - input.usedTokens),\n\t\t},\n\t\tplanHash: input.planHash,\n\t\tcache: input.cacheTelemetry,\n\t\ttokenOptimizer: getTokenOptimizerRuntimeStatus(),\n\t};\n}\n\nfunction countUniqueRetrievalFallbacks(retrievalFallbacks: readonly ContextSourceRefV2[]): number {\n\treturn new Set(\n\t\tretrievalFallbacks.map((ref) =>\n\t\t\t[ref.uri, ref.contentHash, ref.symbol ?? \"\", ref.range?.startLine ?? \"\", ref.range?.endLine ?? \"\"].join(\"\\0\"),\n\t\t),\n\t).size;\n}\n"]}

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

@@ -0,0 +1,27 @@
+import type { ContextRepresentationCandidateV2 } from "./context-budget-headroom.ts";
+import { type ContextBudgetCacheKeyBaseV2 } from "./context-budget-v2-cache-keys.ts";
+import type { MutableTokenCacheTelemetryV2 } from "./context-budget-v2-cache-telemetry.ts";
+import type { PlannedItemV2 } from "./context-budget-v2-scoring.ts";
+import type { ContextBudgetCacheProviderV2 } from "./context-budget-v2-types.ts";
+interface ContextBudgetRepresentationCacheRuntimeV2 {
+    readonly provider?: ContextBudgetCacheProviderV2;
+    readonly keyBase: ContextBudgetCacheKeyBaseV2;
+    readonly nowEpochMs: number;
+    readonly ttlMs: number;
+    readonly telemetry: MutableTokenCacheTelemetryV2;
+}
+export declare function applyRepresentationCacheV2(input: {
+    readonly planned: PlannedItemV2;
+    readonly candidates: readonly ContextRepresentationCandidateV2[];
+    readonly cache: ContextBudgetRepresentationCacheRuntimeV2;
+    readonly materializedEnabled?: boolean;
+}): readonly ContextRepresentationCandidateV2[];
+export declare function writeRepresentationCacheV2(input: {
+    readonly planned: PlannedItemV2;
+    readonly selected: ContextRepresentationCandidateV2;
+    readonly cache: ContextBudgetRepresentationCacheRuntimeV2;
+    readonly materializedEnabled?: boolean;
+}): void;
+export declare function isMaterializableRepresentationV2(candidate: ContextRepresentationCandidateV2): boolean;
+export {};
+//# sourceMappingURL=context-budget-v2-representation-cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-v2-representation-cache.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-representation-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,8BAA8B,CAAC;AACrF,OAAO,EAGN,KAAK,2BAA2B,EAIhC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,wCAAwC,CAAC;AAM3F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,8BAA8B,CAAC;AAEjF,UAAU,yCAAyC;IAClD,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,0BAA0B,CAAC,KAAK,EAAE;IACjD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,SAAS,gCAAgC,EAAE,CAAC;IACjE,QAAQ,CAAC,KAAK,EAAE,yCAAyC,CAAC;IAC1D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACvC,GAAG,SAAS,gCAAgC,EAAE,CAgE9C;AA6CD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IACjD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,gCAAgC,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,yCAAyC,CAAC;IAC1D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACvC,GAAG,IAAI,CAiEP;AAED,wBAAgB,gCAAgC,CAAC,SAAS,EAAE,gCAAgC,GAAG,OAAO,CAErG","sourcesContent":["import type { ContextRepresentationCandidateV2 } from \"./context-budget-headroom.ts\";\nimport {\n\tbuildContextBudgetMaterializedRepresentationCandidateKeyV2,\n\tbuildContextBudgetRepresentationCandidateKeyV2,\n\ttype ContextBudgetCacheKeyBaseV2,\n\tcomputeContextBudgetOutputTextHashV2,\n\tcomputeContextBudgetRepresentationFingerprintV2,\n\tcomputeContextBudgetTargetTokenBucketV2,\n} from \"./context-budget-v2-cache-keys.ts\";\nimport type { MutableTokenCacheTelemetryV2 } from \"./context-budget-v2-cache-telemetry.ts\";\nimport { recordContextBudgetRepresentationCacheHitV2 } from \"./context-budget-v2-cache-telemetry.ts\";\nimport {\n\tvalidateContextBudgetMaterializedRepresentationCacheEntryV2,\n\tvalidateContextBudgetRepresentationCacheEntryV2,\n} from \"./context-budget-v2-cache-validation.ts\";\nimport type { PlannedItemV2 } from \"./context-budget-v2-scoring.ts\";\nimport type { ContextBudgetCacheProviderV2 } from \"./context-budget-v2-types.ts\";\n\ninterface ContextBudgetRepresentationCacheRuntimeV2 {\n\treadonly provider?: ContextBudgetCacheProviderV2;\n\treadonly keyBase: ContextBudgetCacheKeyBaseV2;\n\treadonly nowEpochMs: number;\n\treadonly ttlMs: number;\n\treadonly telemetry: MutableTokenCacheTelemetryV2;\n}\n\nexport function applyRepresentationCacheV2(input: {\n\treadonly planned: PlannedItemV2;\n\treadonly candidates: readonly ContextRepresentationCandidateV2[];\n\treadonly cache: ContextBudgetRepresentationCacheRuntimeV2;\n\treadonly materializedEnabled?: boolean;\n}): readonly ContextRepresentationCandidateV2[] {\n\tconst provider = input.cache.provider;\n\tif (!provider) return input.candidates;\n\tconst sourceHash = input.planned.contentHash;\n\tconst resolved: ContextRepresentationCandidateV2[] = [];\n\tfor (const candidate of input.candidates) {\n\t\tif (candidate.kind === \"omit\") {\n\t\t\tresolved.push(candidate);\n\t\t\tcontinue;\n\t\t}\n\t\tconst exactKey = buildContextBudgetRepresentationCandidateKeyV2(input.cache.keyBase, candidate, sourceHash);\n\t\tconst negative = provider.readNegativeRepresentation(exactKey);\n\t\tif (negative) {\n\t\t\tinput.cache.telemetry.representationCache.negativeHits += 1;\n\t\t\tcontinue;\n\t\t}\n\t\tconst cached = provider.readRepresentation(exactKey);\n\t\tif (!cached) {\n\t\t\tconst materialized = readMaterializedRepresentationCacheV2({\n\t\t\t\tcache: input.cache,\n\t\t\t\tcandidate,\n\t\t\t\tmaterializedEnabled: input.materializedEnabled === true,\n\t\t\t\tprovider,\n\t\t\t\tsourceHash,\n\t\t\t});\n\t\t\tif (materialized) {\n\t\t\t\tresolved.push(materialized);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tinput.cache.telemetry.representationCache.misses += 1;\n\t\t\tresolved.push({ ...candidate, cache: { hit: false, key: exactKey, keyKind: \"exact\" } });\n\t\t\tcontinue;\n\t\t}\n\t\tconst rejection = validateContextBudgetRepresentationCacheEntryV2({\n\t\t\tcache: input.cache,\n\t\t\tcached,\n\t\t\tcandidate,\n\t\t\tsourceHash,\n\t\t});\n\t\tif (rejection) {\n\t\t\trecordRepresentationReject(input.cache.telemetry, rejection);\n\t\t\tresolved.push({\n\t\t\t\t...candidate,\n\t\t\t\tcache: { hit: false, key: exactKey, keyKind: \"exact\", rejectedReason: rejection },\n\t\t\t});\n\t\t\tcontinue;\n\t\t}\n\t\trecordContextBudgetRepresentationCacheHitV2(\n\t\t\tinput.cache.telemetry,\n\t\t\tcached.entry.kind,\n\t\t\tcached.entry.keyKind ?? \"exact\",\n\t\t);\n\t\tresolved.push({\n\t\t\t...candidate,\n\t\t\tcache: { hit: true, key: exactKey, keyKind: cached.entry.keyKind ?? \"exact\", layer: cached.layer },\n\t\t\tcompressorId: cached.entry.compressorId,\n\t\t\testimatedTokens: cached.entry.estimatedTokens,\n\t\t\tfidelity: cached.entry.fidelity,\n\t\t\tsourceRef: cached.entry.sourceRef ?? candidate.sourceRef,\n\t\t\tsummaryHash: cached.entry.summaryHash,\n\t\t\ttext: cached.entry.text,\n\t\t});\n\t}\n\treturn resolved;\n}\n\nfunction readMaterializedRepresentationCacheV2(input: {\n\treadonly cache: ContextBudgetRepresentationCacheRuntimeV2;\n\treadonly candidate: ContextRepresentationCandidateV2;\n\treadonly materializedEnabled: boolean;\n\treadonly provider: ContextBudgetCacheProviderV2;\n\treadonly sourceHash: string;\n}): ContextRepresentationCandidateV2 | undefined {\n\tif (!input.materializedEnabled || !isMaterializableRepresentationV2(input.candidate)) return undefined;\n\tconst key = buildContextBudgetMaterializedRepresentationCandidateKeyV2(\n\t\tinput.cache.keyBase,\n\t\tinput.candidate,\n\t\tinput.sourceHash,\n\t);\n\tconst negative = input.provider.readNegativeRepresentation(key);\n\tif (negative) {\n\t\tinput.cache.telemetry.representationCache.negativeHits += 1;\n\t\treturn undefined;\n\t}\n\tconst cached = input.provider.readRepresentation(key);\n\tif (!cached) return undefined;\n\tconst rejection = validateContextBudgetMaterializedRepresentationCacheEntryV2({\n\t\tcache: input.cache,\n\t\tcached,\n\t\tcandidate: input.candidate,\n\t\tsourceHash: input.sourceHash,\n\t});\n\tif (rejection) {\n\t\trecordRepresentationReject(input.cache.telemetry, rejection);\n\t\treturn { ...input.candidate, cache: { hit: false, key, keyKind: \"materialized\", rejectedReason: rejection } };\n\t}\n\trecordContextBudgetRepresentationCacheHitV2(input.cache.telemetry, cached.entry.kind, \"materialized\");\n\treturn {\n\t\t...input.candidate,\n\t\tcache: { hit: true, key, keyKind: \"materialized\", layer: cached.layer },\n\t\tcompressorId: cached.entry.compressorId,\n\t\testimatedTokens: cached.entry.estimatedTokens,\n\t\tfidelity: cached.entry.fidelity,\n\t\tsourceRef: cached.entry.sourceRef ?? input.candidate.sourceRef,\n\t\tsummaryHash: cached.entry.summaryHash,\n\t\ttext: cached.entry.text,\n\t};\n}\n\nexport function writeRepresentationCacheV2(input: {\n\treadonly planned: PlannedItemV2;\n\treadonly selected: ContextRepresentationCandidateV2;\n\treadonly cache: ContextBudgetRepresentationCacheRuntimeV2;\n\treadonly materializedEnabled?: boolean;\n}): void {\n\tif (!input.cache.provider || input.selected.kind === \"omit\" || input.selected.cache?.hit === true) return;\n\tconst sourceHash = input.planned.contentHash;\n\tconst exactKey =\n\t\tinput.selected.cache?.keyKind === \"exact\" && input.selected.cache.key !== undefined\n\t\t\t? input.selected.cache.key\n\t\t\t: buildContextBudgetRepresentationCandidateKeyV2(input.cache.keyBase, input.selected, sourceHash);\n\tinput.cache.provider.writeRepresentation({\n\t\tkey: exactKey,\n\t\tentry: {\n\t\t\tcompressorId: input.selected.compressorId,\n\t\t\tcreatedAtEpochMs: input.cache.nowEpochMs,\n\t\t\testimatedTokens: input.selected.estimatedTokens,\n\t\t\tfidelity: input.selected.fidelity,\n\t\t\tkeyKind: \"exact\",\n\t\t\tkind: input.selected.kind,\n\t\t\tmodelId: input.cache.keyBase.modelId,\n\t\t\tpolicyVersion: input.cache.keyBase.policyVersion,\n\t\t\trepresentationFingerprint: computeContextBudgetRepresentationFingerprintV2(input.selected),\n\t\t\tsourceHash,\n\t\t\tsourceRef: input.selected.sourceRef,\n\t\t\tsummaryHash: input.selected.summaryHash,\n\t\t\ttext: input.selected.text,\n\t\t\ttokenizerId: input.cache.keyBase.tokenizerId,\n\t\t},\n\t});\n\tinput.cache.telemetry.representationCache.writes += 1;\n\tif (input.materializedEnabled === true && isMaterializableRepresentationV2(input.selected)) {\n\t\tinput.cache.provider.writeRepresentation({\n\t\t\tkey: buildContextBudgetMaterializedRepresentationCandidateKeyV2(\n\t\t\t\tinput.cache.keyBase,\n\t\t\t\tinput.selected,\n\t\t\t\tsourceHash,\n\t\t\t),\n\t\t\tentry: {\n\t\t\t\tcompressorId: input.selected.compressorId,\n\t\t\t\tcompressorPolicyHash: input.cache.keyBase.compressorPolicyHash,\n\t\t\t\tcreatedAtEpochMs: input.cache.nowEpochMs,\n\t\t\t\testimatedTokens: input.selected.estimatedTokens,\n\t\t\t\tfidelity: input.selected.fidelity,\n\t\t\t\tkeyKind: \"materialized\",\n\t\t\t\tkind: input.selected.kind,\n\t\t\t\tmodelId: input.cache.keyBase.modelId,\n\t\t\t\toutputTextHash: computeContextBudgetOutputTextHashV2(input.selected.text),\n\t\t\t\tpolicyVersion: input.cache.keyBase.policyVersion,\n\t\t\t\tqualityPolicyHash: input.cache.keyBase.qualityPolicyHash,\n\t\t\t\tqueryIntentCluster: input.cache.keyBase.queryIntentCluster,\n\t\t\t\trepresentationFingerprint: computeContextBudgetRepresentationFingerprintV2(input.selected),\n\t\t\t\tsourceHash,\n\t\t\t\tsourceRef: input.selected.sourceRef,\n\t\t\t\tsummaryHash: input.selected.summaryHash,\n\t\t\t\ttargetTokenBucket: computeContextBudgetTargetTokenBucketV2(input.selected.estimatedTokens),\n\t\t\t\ttext: input.selected.text,\n\t\t\t\ttokenizerId: input.cache.keyBase.tokenizerId,\n\t\t\t\tverification: {\n\t\t\t\t\tpoisonScore: 0,\n\t\t\t\t\tqueryCoverage: 1,\n\t\t\t\t\tsecretLeakScore: 0,\n\t\t\t\t\tsourceCoverage: 1,\n\t\t\t\t\tvalidatorVersion: \"context-budget-v2-heuristic\",\n\t\t\t\t},\n\t\t\t},\n\t\t});\n\t\tinput.cache.telemetry.representationCache.writes += 1;\n\t}\n}\n\nexport function isMaterializableRepresentationV2(candidate: ContextRepresentationCandidateV2): boolean {\n\treturn candidate.kind === \"summary\" || candidate.kind === \"headroom-compressed\";\n}\n\nfunction recordRepresentationReject(telemetry: MutableTokenCacheTelemetryV2, rejection: string): void {\n\tif (rejection === \"stale\") {\n\t\ttelemetry.representationCache.staleRejects += 1;\n\t} else {\n\t\ttelemetry.representationCache.poisonRejects += 1;\n\t}\n}\n"]}

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

@@ -0,0 +1,173 @@
+import { buildContextBudgetMaterializedRepresentationCandidateKeyV2, buildContextBudgetRepresentationCandidateKeyV2, computeContextBudgetOutputTextHashV2, computeContextBudgetRepresentationFingerprintV2, computeContextBudgetTargetTokenBucketV2, } from "./context-budget-v2-cache-keys.js";
+import { recordContextBudgetRepresentationCacheHitV2 } from "./context-budget-v2-cache-telemetry.js";
+import { validateContextBudgetMaterializedRepresentationCacheEntryV2, validateContextBudgetRepresentationCacheEntryV2, } from "./context-budget-v2-cache-validation.js";
+export function applyRepresentationCacheV2(input) {
+    const provider = input.cache.provider;
+    if (!provider)
+        return input.candidates;
+    const sourceHash = input.planned.contentHash;
+    const resolved = [];
+    for (const candidate of input.candidates) {
+        if (candidate.kind === "omit") {
+            resolved.push(candidate);
+            continue;
+        }
+        const exactKey = buildContextBudgetRepresentationCandidateKeyV2(input.cache.keyBase, candidate, sourceHash);
+        const negative = provider.readNegativeRepresentation(exactKey);
+        if (negative) {
+            input.cache.telemetry.representationCache.negativeHits += 1;
+            continue;
+        }
+        const cached = provider.readRepresentation(exactKey);
+        if (!cached) {
+            const materialized = readMaterializedRepresentationCacheV2({
+                cache: input.cache,
+                candidate,
+                materializedEnabled: input.materializedEnabled === true,
+                provider,
+                sourceHash,
+            });
+            if (materialized) {
+                resolved.push(materialized);
+                continue;
+            }
+            input.cache.telemetry.representationCache.misses += 1;
+            resolved.push({ ...candidate, cache: { hit: false, key: exactKey, keyKind: "exact" } });
+            continue;
+        }
+        const rejection = validateContextBudgetRepresentationCacheEntryV2({
+            cache: input.cache,
+            cached,
+            candidate,
+            sourceHash,
+        });
+        if (rejection) {
+            recordRepresentationReject(input.cache.telemetry, rejection);
+            resolved.push({
+                ...candidate,
+                cache: { hit: false, key: exactKey, keyKind: "exact", rejectedReason: rejection },
+            });
+            continue;
+        }
+        recordContextBudgetRepresentationCacheHitV2(input.cache.telemetry, cached.entry.kind, cached.entry.keyKind ?? "exact");
+        resolved.push({
+            ...candidate,
+            cache: { hit: true, key: exactKey, keyKind: cached.entry.keyKind ?? "exact", layer: cached.layer },
+            compressorId: cached.entry.compressorId,
+            estimatedTokens: cached.entry.estimatedTokens,
+            fidelity: cached.entry.fidelity,
+            sourceRef: cached.entry.sourceRef ?? candidate.sourceRef,
+            summaryHash: cached.entry.summaryHash,
+            text: cached.entry.text,
+        });
+    }
+    return resolved;
+}
+function readMaterializedRepresentationCacheV2(input) {
+    if (!input.materializedEnabled || !isMaterializableRepresentationV2(input.candidate))
+        return undefined;
+    const key = buildContextBudgetMaterializedRepresentationCandidateKeyV2(input.cache.keyBase, input.candidate, input.sourceHash);
+    const negative = input.provider.readNegativeRepresentation(key);
+    if (negative) {
+        input.cache.telemetry.representationCache.negativeHits += 1;
+        return undefined;
+    }
+    const cached = input.provider.readRepresentation(key);
+    if (!cached)
+        return undefined;
+    const rejection = validateContextBudgetMaterializedRepresentationCacheEntryV2({
+        cache: input.cache,
+        cached,
+        candidate: input.candidate,
+        sourceHash: input.sourceHash,
+    });
+    if (rejection) {
+        recordRepresentationReject(input.cache.telemetry, rejection);
+        return { ...input.candidate, cache: { hit: false, key, keyKind: "materialized", rejectedReason: rejection } };
+    }
+    recordContextBudgetRepresentationCacheHitV2(input.cache.telemetry, cached.entry.kind, "materialized");
+    return {
+        ...input.candidate,
+        cache: { hit: true, key, keyKind: "materialized", layer: cached.layer },
+        compressorId: cached.entry.compressorId,
+        estimatedTokens: cached.entry.estimatedTokens,
+        fidelity: cached.entry.fidelity,
+        sourceRef: cached.entry.sourceRef ?? input.candidate.sourceRef,
+        summaryHash: cached.entry.summaryHash,
+        text: cached.entry.text,
+    };
+}
+export function writeRepresentationCacheV2(input) {
+    if (!input.cache.provider || input.selected.kind === "omit" || input.selected.cache?.hit === true)
+        return;
+    const sourceHash = input.planned.contentHash;
+    const exactKey = input.selected.cache?.keyKind === "exact" && input.selected.cache.key !== undefined
+        ? input.selected.cache.key
+        : buildContextBudgetRepresentationCandidateKeyV2(input.cache.keyBase, input.selected, sourceHash);
+    input.cache.provider.writeRepresentation({
+        key: exactKey,
+        entry: {
+            compressorId: input.selected.compressorId,
+            createdAtEpochMs: input.cache.nowEpochMs,
+            estimatedTokens: input.selected.estimatedTokens,
+            fidelity: input.selected.fidelity,
+            keyKind: "exact",
+            kind: input.selected.kind,
+            modelId: input.cache.keyBase.modelId,
+            policyVersion: input.cache.keyBase.policyVersion,
+            representationFingerprint: computeContextBudgetRepresentationFingerprintV2(input.selected),
+            sourceHash,
+            sourceRef: input.selected.sourceRef,
+            summaryHash: input.selected.summaryHash,
+            text: input.selected.text,
+            tokenizerId: input.cache.keyBase.tokenizerId,
+        },
+    });
+    input.cache.telemetry.representationCache.writes += 1;
+    if (input.materializedEnabled === true && isMaterializableRepresentationV2(input.selected)) {
+        input.cache.provider.writeRepresentation({
+            key: buildContextBudgetMaterializedRepresentationCandidateKeyV2(input.cache.keyBase, input.selected, sourceHash),
+            entry: {
+                compressorId: input.selected.compressorId,
+                compressorPolicyHash: input.cache.keyBase.compressorPolicyHash,
+                createdAtEpochMs: input.cache.nowEpochMs,
+                estimatedTokens: input.selected.estimatedTokens,
+                fidelity: input.selected.fidelity,
+                keyKind: "materialized",
+                kind: input.selected.kind,
+                modelId: input.cache.keyBase.modelId,
+                outputTextHash: computeContextBudgetOutputTextHashV2(input.selected.text),
+                policyVersion: input.cache.keyBase.policyVersion,
+                qualityPolicyHash: input.cache.keyBase.qualityPolicyHash,
+                queryIntentCluster: input.cache.keyBase.queryIntentCluster,
+                representationFingerprint: computeContextBudgetRepresentationFingerprintV2(input.selected),
+                sourceHash,
+                sourceRef: input.selected.sourceRef,
+                summaryHash: input.selected.summaryHash,
+                targetTokenBucket: computeContextBudgetTargetTokenBucketV2(input.selected.estimatedTokens),
+                text: input.selected.text,
+                tokenizerId: input.cache.keyBase.tokenizerId,
+                verification: {
+                    poisonScore: 0,
+                    queryCoverage: 1,
+                    secretLeakScore: 0,
+                    sourceCoverage: 1,
+                    validatorVersion: "context-budget-v2-heuristic",
+                },
+            },
+        });
+        input.cache.telemetry.representationCache.writes += 1;
+    }
+}
+export function isMaterializableRepresentationV2(candidate) {
+    return candidate.kind === "summary" || candidate.kind === "headroom-compressed";
+}
+function recordRepresentationReject(telemetry, rejection) {
+    if (rejection === "stale") {
+        telemetry.representationCache.staleRejects += 1;
+    }
+    else {
+        telemetry.representationCache.poisonRejects += 1;
+    }
+}
+//# sourceMappingURL=context-budget-v2-representation-cache.js.map