open-multi-agent-kit 0.90.7 → 0.90.9

package/dist/core/context-budget-reserved-tokens.js

@@ -0,0 +1,188 @@
+/**
+ * Pure, deterministic reserved-token budget arithmetic.
+ *
+ * This module is host-API-free: it relies only on plain ECMAScript value
+ * semantics. Invalid input and unsafe arithmetic that would lose integer
+ * precision both fail closed by throwing {@link ReservedTokenBudgetError}.
+ *
+ * The budget is one exact subtraction:
+ *
+ *   effectiveBudget = modelContextWindow
+ *                       - systemPromptTokens
+ *                       - reservedOutputTokens
+ *                       - reservedToolResultTokens
+ *                       - safetyMarginTokens
+ *                       - imageReserveTokens
+ *
+ * The four reserve terms (output, tool result, safety margin, image reserve)
+ * are summed into `totalReserved` first; the final budget is the single
+ * subtraction `modelContextWindow - (systemPromptTokens + totalReserved)`.
+ */
+/**
+ * The complete, frozen set of supported tool-result classes. The literal union
+ * {@link ToolResultClass} is derived from this tuple. Frozen at runtime so the
+ * supported set cannot be mutated after import; the `as const` tuple type is
+ * preserved (freeze returns `Readonly` of the same tuple).
+ */
+export const TOOL_RESULT_CLASSES = Object.freeze(["text", "image", "large-output"]);
+/**
+ * Fixed upper bound on the number of per-class requests accepted by
+ * {@link estimateToolResultReserve}. Request arrays longer than this cap are
+ * rejected before any iteration or arithmetic, keeping the estimator's loop
+ * bounded and predictable. A deliberately conservative constant.
+ */
+export const MAX_TOOL_RESULT_RESERVE_REQUESTS = 64;
+const TOOL_RESULT_CLASS_SET = new Set(TOOL_RESULT_CLASSES);
+const REQUEST_KEYS = ["class", "count", "tokensPerResult"];
+const BUDGET_INPUT_KEYS = [
+    "modelContextWindow",
+    "systemPromptTokens",
+    "reservedOutputTokens",
+    "reservedToolResultTokens",
+    "safetyMarginTokens",
+    "imageReserveTokens",
+];
+export class ReservedTokenBudgetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ReservedTokenBudgetError";
+    }
+}
+/**
+ * Validate that `value` is a plain data record with exactly the expected keys.
+ *
+ * A plain data record is a non-null, non-array object whose prototype is
+ * `Object.prototype` or `null` (null-prototype data objects are accepted) and
+ * whose own properties are all data properties (no getters/setters). This
+ * rejects arrays, class instances / other non-standard prototypes, accessor
+ * properties, and records with missing or unexpected keys — all via
+ * {@link ReservedTokenBudgetError} so callers fail closed consistently.
+ */
+function assertPlainDataRecord(value, label, expected) {
+    if (typeof value !== "object" || value === null) {
+        throw new ReservedTokenBudgetError(`${label} must be a non-null object`);
+    }
+    if (Array.isArray(value)) {
+        throw new ReservedTokenBudgetError(`${label} must be a plain object, not an array`);
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== null && proto !== Object.prototype) {
+        throw new ReservedTokenBudgetError(`${label} must be a plain data record (unexpected prototype)`);
+    }
+    for (const key of Object.getOwnPropertyNames(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor !== undefined && (typeof descriptor.get === "function" || typeof descriptor.set === "function")) {
+            throw new ReservedTokenBudgetError(`${label} must not have accessor property "${key}"`);
+        }
+    }
+    const expectedSet = new Set(expected);
+    const actual = Object.keys(value);
+    for (const key of actual) {
+        if (!expectedSet.has(key)) {
+            throw new ReservedTokenBudgetError(`${label} has unexpected key "${key}"`);
+        }
+    }
+    if (actual.length !== expected.length) {
+        const missing = expected.filter((key) => !(key in value));
+        throw new ReservedTokenBudgetError(`${label} is missing required key(s): ${missing.join(", ")}`);
+    }
+}
+function assertNonNegativeSafeInteger(value, label) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new ReservedTokenBudgetError(`${label} must be a finite number (got ${String(value)})`);
+    }
+    if (!Number.isSafeInteger(value)) {
+        throw new ReservedTokenBudgetError(`${label} must be a safe integer (got ${value})`);
+    }
+    if (value < 0) {
+        throw new ReservedTokenBudgetError(`${label} must be nonnegative (got ${value})`);
+    }
+}
+/** Add two nonnegative safe integers, failing closed before precision loss. */
+function safeAdd(a, b, label) {
+    if (b > Number.MAX_SAFE_INTEGER - a) {
+        throw new ReservedTokenBudgetError(`arithmetic overflow while ${label}: ${a} + ${b}`);
+    }
+    return a + b;
+}
+/** Multiply two nonnegative safe integers, failing closed if the product is unsafe. */
+function safeMultiply(a, b, label) {
+    if (a === 0 || b === 0) {
+        return 0;
+    }
+    const product = a * b;
+    if (!Number.isSafeInteger(product) || product / a !== b || product / b !== a) {
+        throw new ReservedTokenBudgetError(`arithmetic overflow while ${label}: ${a} * ${b}`);
+    }
+    return product;
+}
+function deepFreeze(value) {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value)) {
+        return value;
+    }
+    for (const child of Object.values(value)) {
+        deepFreeze(child);
+    }
+    return Object.freeze(value);
+}
+/**
+ * Estimate reserved tool-result tokens from bounded per-class requests using
+ * safe-integer arithmetic. Returns the exact total. Empty input yields 0.
+ * Throws {@link ReservedTokenBudgetError} on any invalid/overflowing input.
+ */
+export function estimateToolResultReserve(requests) {
+    if (!Array.isArray(requests)) {
+        throw new ReservedTokenBudgetError("requests must be an array");
+    }
+    if (requests.length > MAX_TOOL_RESULT_RESERVE_REQUESTS) {
+        throw new ReservedTokenBudgetError(`requests length ${requests.length} exceeds maximum ${MAX_TOOL_RESULT_RESERVE_REQUESTS}`);
+    }
+    let total = 0;
+    for (let i = 0; i < requests.length; i += 1) {
+        const request = requests[i];
+        const itemLabel = `requests[${i}]`;
+        assertPlainDataRecord(request, itemLabel, REQUEST_KEYS);
+        if (!TOOL_RESULT_CLASS_SET.has(request.class)) {
+            throw new ReservedTokenBudgetError(`${itemLabel}.class must be one of ${TOOL_RESULT_CLASSES.join(", ")} (got ${String(request.class)})`);
+        }
+        assertNonNegativeSafeInteger(request.count, `${itemLabel}.count`);
+        assertNonNegativeSafeInteger(request.tokensPerResult, `${itemLabel}.tokensPerResult`);
+        const perClassTotal = safeMultiply(request.count, request.tokensPerResult, `${itemLabel} count*tokensPerResult`);
+        total = safeAdd(total, perClassTotal, `summing tool result reserves at ${itemLabel}`);
+    }
+    return total;
+}
+/**
+ * Compute the effective reserved-token budget via a single exact subtraction.
+ * All inputs must be nonnegative safe integers. The returned object (and its
+ * nested `terms`) is deeply frozen and independent of the caller's input.
+ */
+export function computeReservedTokenBudget(input) {
+    assertPlainDataRecord(input, "input", BUDGET_INPUT_KEYS);
+    assertNonNegativeSafeInteger(input.modelContextWindow, "modelContextWindow");
+    assertNonNegativeSafeInteger(input.systemPromptTokens, "systemPromptTokens");
+    assertNonNegativeSafeInteger(input.reservedOutputTokens, "reservedOutputTokens");
+    assertNonNegativeSafeInteger(input.reservedToolResultTokens, "reservedToolResultTokens");
+    assertNonNegativeSafeInteger(input.safetyMarginTokens, "safetyMarginTokens");
+    assertNonNegativeSafeInteger(input.imageReserveTokens, "imageReserveTokens");
+    const totalReserved = safeAdd(safeAdd(safeAdd(input.reservedOutputTokens, input.reservedToolResultTokens, "output+toolResult"), input.safetyMarginTokens, "+safetyMargin"), input.imageReserveTokens, "+imageReserve");
+    const consumed = safeAdd(input.systemPromptTokens, totalReserved, "systemPrompt+totalReserved");
+    const rawEffective = input.modelContextWindow - consumed;
+    const overflow = rawEffective < 0;
+    const effectiveBudget = overflow ? 0 : rawEffective;
+    const terms = {
+        modelContextWindow: input.modelContextWindow,
+        systemPromptTokens: input.systemPromptTokens,
+        reservedOutputTokens: input.reservedOutputTokens,
+        reservedToolResultTokens: input.reservedToolResultTokens,
+        safetyMarginTokens: input.safetyMarginTokens,
+        imageReserveTokens: input.imageReserveTokens,
+    };
+    return deepFreeze({
+        terms,
+        totalReserved,
+        effectiveBudget,
+        overflow,
+    });
+}
+//# sourceMappingURL=context-budget-reserved-tokens.js.map

package/dist/core/context-budget-reserved-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-reserved-tokens.js","sourceRoot":"","sources":["../../src/core/context-budget-reserved-tokens.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure, deterministic reserved-token budget arithmetic.\n *\n * This module is host-API-free: it relies only on plain ECMAScript value\n * semantics. Invalid input and unsafe arithmetic that would lose integer\n * precision both fail closed by throwing {@link ReservedTokenBudgetError}.\n *\n * The budget is one exact subtraction:\n *\n *   effectiveBudget = modelContextWindow\n *                       - systemPromptTokens\n *                       - reservedOutputTokens\n *                       - reservedToolResultTokens\n *                       - safetyMarginTokens\n *                       - imageReserveTokens\n *\n * The four reserve terms (output, tool result, safety margin, image reserve)\n * are summed into `totalReserved` first; the final budget is the single\n * subtraction `modelContextWindow - (systemPromptTokens + totalReserved)`.\n */\n\n/**\n * The complete, frozen set of supported tool-result classes. The literal union\n * {@link ToolResultClass} is derived from this tuple. Frozen at runtime so the\n * supported set cannot be mutated after import; the `as const` tuple type is\n * preserved (freeze returns `Readonly` of the same tuple).\n */\nexport const TOOL_RESULT_CLASSES = Object.freeze([\"text\", \"image\", \"large-output\"] as const);\nexport type ToolResultClass = (typeof TOOL_RESULT_CLASSES)[number];\n\n/**\n * Fixed upper bound on the number of per-class requests accepted by\n * {@link estimateToolResultReserve}. Request arrays longer than this cap are\n * rejected before any iteration or arithmetic, keeping the estimator's loop\n * bounded and predictable. A deliberately conservative constant.\n */\nexport const MAX_TOOL_RESULT_RESERVE_REQUESTS = 64;\n\nconst TOOL_RESULT_CLASS_SET: ReadonlySet<string> = new Set(TOOL_RESULT_CLASSES);\n\nconst REQUEST_KEYS = [\"class\", \"count\", \"tokensPerResult\"] as const;\n\nconst BUDGET_INPUT_KEYS = [\n\t\"modelContextWindow\",\n\t\"systemPromptTokens\",\n\t\"reservedOutputTokens\",\n\t\"reservedToolResultTokens\",\n\t\"safetyMarginTokens\",\n\t\"imageReserveTokens\",\n] as const;\n\n/**\n * A bounded per-class reserve request for tool results.\n *\n * `count` results of `class`, each reserving `tokensPerResult` tokens.\n */\nexport interface ToolResultReserveRequest {\n\treadonly class: ToolResultClass;\n\treadonly count: number;\n\treadonly tokensPerResult: number;\n}\n\n/** Exact inputs to {@link computeReservedTokenBudget}. All terms are nonnegative safe integers. */\nexport interface ReservedTokenBudgetInput {\n\treadonly modelContextWindow: number;\n\treadonly systemPromptTokens: number;\n\t/** A single output-reserve term. No implicit ratio or default is applied. */\n\treadonly reservedOutputTokens: number;\n\t/**\n\t * Single term for reserved tool-result tokens. Pass\n\t * {@link estimateToolResultReserve} here. Empty/zero is allowed.\n\t */\n\treadonly reservedToolResultTokens: number;\n\treadonly safetyMarginTokens: number;\n\t/**\n\t * Reserve for image content. Distinct from the tool-result `image` class:\n\t * account image tokens in exactly one of these two places to avoid\n\t * double-accounting.\n\t */\n\treadonly imageReserveTokens: number;\n}\n\n/** A deeply frozen copy of the terms used in the budget computation. */\nexport interface ReservedTokenBudgetTerms {\n\treadonly modelContextWindow: number;\n\treadonly systemPromptTokens: number;\n\treadonly reservedOutputTokens: number;\n\treadonly reservedToolResultTokens: number;\n\treadonly safetyMarginTokens: number;\n\treadonly imageReserveTokens: number;\n}\n\nexport interface ReservedTokenBudgetResult {\n\treadonly terms: ReservedTokenBudgetTerms;\n\t/** reservedOutput + reservedToolResult + safetyMargin + imageReserve (excludes systemPrompt and the window). */\n\treadonly totalReserved: number;\n\t/**\n\t * `modelContextWindow - systemPromptTokens - totalReserved`, clamped at 0.\n\t *\n\t * Exact-zero semantics: when the raw subtraction is exactly 0 the budget is\n\t * 0 and {@link overflow} is `false` — the window is exactly filled, not\n\t * exceeded. {@link overflow} is `true` only when the raw subtraction is\n\t * strictly negative (see {@link overflow}).\n\t */\n\treadonly effectiveBudget: number;\n\t/**\n\t * `true` only when the raw subtraction\n\t * `modelContextWindow - systemPromptTokens - totalReserved` is strictly\n\t * negative (reserves exceed the window). A raw result of exactly 0 is NOT\n\t * overflow: {@link effectiveBudget} is 0 but this flag stays `false`.\n\t */\n\treadonly overflow: boolean;\n}\n\nexport class ReservedTokenBudgetError extends Error {\n\tconstructor(message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"ReservedTokenBudgetError\";\n\t}\n}\n\n/**\n * Validate that `value` is a plain data record with exactly the expected keys.\n *\n * A plain data record is a non-null, non-array object whose prototype is\n * `Object.prototype` or `null` (null-prototype data objects are accepted) and\n * whose own properties are all data properties (no getters/setters). This\n * rejects arrays, class instances / other non-standard prototypes, accessor\n * properties, and records with missing or unexpected keys — all via\n * {@link ReservedTokenBudgetError} so callers fail closed consistently.\n */\nfunction assertPlainDataRecord(value: unknown, label: string, expected: readonly string[]): void {\n\tif (typeof value !== \"object\" || value === null) {\n\t\tthrow new ReservedTokenBudgetError(`${label} must be a non-null object`);\n\t}\n\tif (Array.isArray(value)) {\n\t\tthrow new ReservedTokenBudgetError(`${label} must be a plain object, not an array`);\n\t}\n\tconst proto = Object.getPrototypeOf(value);\n\tif (proto !== null && proto !== Object.prototype) {\n\t\tthrow new ReservedTokenBudgetError(`${label} must be a plain data record (unexpected prototype)`);\n\t}\n\tfor (const key of Object.getOwnPropertyNames(value)) {\n\t\tconst descriptor = Object.getOwnPropertyDescriptor(value, key);\n\t\tif (descriptor !== undefined && (typeof descriptor.get === \"function\" || typeof descriptor.set === \"function\")) {\n\t\t\tthrow new ReservedTokenBudgetError(`${label} must not have accessor property \"${key}\"`);\n\t\t}\n\t}\n\tconst expectedSet = new Set(expected);\n\tconst actual = Object.keys(value);\n\tfor (const key of actual) {\n\t\tif (!expectedSet.has(key)) {\n\t\t\tthrow new ReservedTokenBudgetError(`${label} has unexpected key \"${key}\"`);\n\t\t}\n\t}\n\tif (actual.length !== expected.length) {\n\t\tconst missing = expected.filter((key) => !(key in value));\n\t\tthrow new ReservedTokenBudgetError(`${label} is missing required key(s): ${missing.join(\", \")}`);\n\t}\n}\n\nfunction assertNonNegativeSafeInteger(value: unknown, label: string): void {\n\tif (typeof value !== \"number\" || !Number.isFinite(value)) {\n\t\tthrow new ReservedTokenBudgetError(`${label} must be a finite number (got ${String(value)})`);\n\t}\n\tif (!Number.isSafeInteger(value)) {\n\t\tthrow new ReservedTokenBudgetError(`${label} must be a safe integer (got ${value})`);\n\t}\n\tif (value < 0) {\n\t\tthrow new ReservedTokenBudgetError(`${label} must be nonnegative (got ${value})`);\n\t}\n}\n\n/** Add two nonnegative safe integers, failing closed before precision loss. */\nfunction safeAdd(a: number, b: number, label: string): number {\n\tif (b > Number.MAX_SAFE_INTEGER - a) {\n\t\tthrow new ReservedTokenBudgetError(`arithmetic overflow while ${label}: ${a} + ${b}`);\n\t}\n\treturn a + b;\n}\n\n/** Multiply two nonnegative safe integers, failing closed if the product is unsafe. */\nfunction safeMultiply(a: number, b: number, label: string): number {\n\tif (a === 0 || b === 0) {\n\t\treturn 0;\n\t}\n\tconst product = a * b;\n\tif (!Number.isSafeInteger(product) || product / a !== b || product / b !== a) {\n\t\tthrow new ReservedTokenBudgetError(`arithmetic overflow while ${label}: ${a} * ${b}`);\n\t}\n\treturn product;\n}\n\nfunction deepFreeze<T>(value: T): T {\n\tif (typeof value !== \"object\" || value === null || Object.isFrozen(value)) {\n\t\treturn value;\n\t}\n\tfor (const child of Object.values(value)) {\n\t\tdeepFreeze(child);\n\t}\n\treturn Object.freeze(value);\n}\n\n/**\n * Estimate reserved tool-result tokens from bounded per-class requests using\n * safe-integer arithmetic. Returns the exact total. Empty input yields 0.\n * Throws {@link ReservedTokenBudgetError} on any invalid/overflowing input.\n */\nexport function estimateToolResultReserve(requests: readonly ToolResultReserveRequest[]): number {\n\tif (!Array.isArray(requests)) {\n\t\tthrow new ReservedTokenBudgetError(\"requests must be an array\");\n\t}\n\tif (requests.length > MAX_TOOL_RESULT_RESERVE_REQUESTS) {\n\t\tthrow new ReservedTokenBudgetError(\n\t\t\t`requests length ${requests.length} exceeds maximum ${MAX_TOOL_RESULT_RESERVE_REQUESTS}`,\n\t\t);\n\t}\n\tlet total = 0;\n\tfor (let i = 0; i < requests.length; i += 1) {\n\t\tconst request = requests[i];\n\t\tconst itemLabel = `requests[${i}]`;\n\t\tassertPlainDataRecord(request, itemLabel, REQUEST_KEYS);\n\t\tif (!TOOL_RESULT_CLASS_SET.has(request.class)) {\n\t\t\tthrow new ReservedTokenBudgetError(\n\t\t\t\t`${itemLabel}.class must be one of ${TOOL_RESULT_CLASSES.join(\", \")} (got ${String(request.class)})`,\n\t\t\t);\n\t\t}\n\t\tassertNonNegativeSafeInteger(request.count, `${itemLabel}.count`);\n\t\tassertNonNegativeSafeInteger(request.tokensPerResult, `${itemLabel}.tokensPerResult`);\n\t\tconst perClassTotal = safeMultiply(request.count, request.tokensPerResult, `${itemLabel} count*tokensPerResult`);\n\t\ttotal = safeAdd(total, perClassTotal, `summing tool result reserves at ${itemLabel}`);\n\t}\n\treturn total;\n}\n\n/**\n * Compute the effective reserved-token budget via a single exact subtraction.\n * All inputs must be nonnegative safe integers. The returned object (and its\n * nested `terms`) is deeply frozen and independent of the caller's input.\n */\nexport function computeReservedTokenBudget(input: ReservedTokenBudgetInput): ReservedTokenBudgetResult {\n\tassertPlainDataRecord(input, \"input\", BUDGET_INPUT_KEYS);\n\tassertNonNegativeSafeInteger(input.modelContextWindow, \"modelContextWindow\");\n\tassertNonNegativeSafeInteger(input.systemPromptTokens, \"systemPromptTokens\");\n\tassertNonNegativeSafeInteger(input.reservedOutputTokens, \"reservedOutputTokens\");\n\tassertNonNegativeSafeInteger(input.reservedToolResultTokens, \"reservedToolResultTokens\");\n\tassertNonNegativeSafeInteger(input.safetyMarginTokens, \"safetyMarginTokens\");\n\tassertNonNegativeSafeInteger(input.imageReserveTokens, \"imageReserveTokens\");\n\n\tconst totalReserved = safeAdd(\n\t\tsafeAdd(\n\t\t\tsafeAdd(input.reservedOutputTokens, input.reservedToolResultTokens, \"output+toolResult\"),\n\t\t\tinput.safetyMarginTokens,\n\t\t\t\"+safetyMargin\",\n\t\t),\n\t\tinput.imageReserveTokens,\n\t\t\"+imageReserve\",\n\t);\n\tconst consumed = safeAdd(input.systemPromptTokens, totalReserved, \"systemPrompt+totalReserved\");\n\tconst rawEffective = input.modelContextWindow - consumed;\n\tconst overflow = rawEffective < 0;\n\tconst effectiveBudget = overflow ? 0 : rawEffective;\n\n\tconst terms: ReservedTokenBudgetTerms = {\n\t\tmodelContextWindow: input.modelContextWindow,\n\t\tsystemPromptTokens: input.systemPromptTokens,\n\t\treservedOutputTokens: input.reservedOutputTokens,\n\t\treservedToolResultTokens: input.reservedToolResultTokens,\n\t\tsafetyMarginTokens: input.safetyMarginTokens,\n\t\timageReserveTokens: input.imageReserveTokens,\n\t};\n\treturn deepFreeze({\n\t\tterms,\n\t\ttotalReserved,\n\t\teffectiveBudget,\n\t\toverflow,\n\t});\n}\n"]}

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

@@ -0,0 +1,133 @@
+/**
+ * Browser-safe, pure context-cache invalidation snapshot helper.
+ *
+ * Every public function is side-effect free and depends only on
+ * platform-agnostic primitives. Returned snapshots are always
+ * independently deep-frozen copies of the caller-supplied data, so
+ * callers cannot mutate cached state through retained references.
+ *
+ * Snapshots are cache-key material for invalidation tracking, not an
+ * authorization or authentication primitive.
+ *
+ * Schema: context-cache-invalidation-v1.
+ */
+export declare const CONTEXT_CACHE_INVALIDATION_SCHEMA_VERSION: "context-cache-invalidation-v1";
+export declare const CONTEXT_CACHE_INVALIDATION_SAFE_ID_MAX_LENGTH = 256;
+/** Event counters tracked by an invalidation snapshot. */
+export interface ContextCacheInvalidationCounters {
+    readonly transcriptRepair: number;
+    readonly toolResultDisposition: number;
+    readonly evidenceReceipt: number;
+    readonly userSteering: number;
+    readonly settings: number;
+}
+/** Immutable schema-v1 invalidation snapshot. */
+export interface ContextCacheInvalidationSnapshot {
+    readonly schemaVersion: typeof CONTEXT_CACHE_INVALIDATION_SCHEMA_VERSION;
+    readonly forkId: string;
+    readonly globalEpoch: number;
+    readonly counters: ContextCacheInvalidationCounters;
+    readonly worktreeFingerprint: string;
+    readonly activeModelId: string;
+    readonly compactionModelId: string;
+}
+/** Constructor input for a fresh snapshot. Counters and epoch default to 0. */
+export interface ContextCacheInvalidationSnapshotInit {
+    readonly forkId: string;
+    readonly worktreeFingerprint: string;
+    readonly activeModelId: string;
+    readonly compactionModelId: string;
+    readonly globalEpoch?: number;
+    readonly transcriptRepair?: number;
+    readonly toolResultDisposition?: number;
+    readonly evidenceReceipt?: number;
+    readonly userSteering?: number;
+    readonly settings?: number;
+}
+/**
+ * Strict union covering all eight invalidation events. The five counter
+ * events increment their counter; the three identity events set a value.
+ */
+export type ContextCacheInvalidationEvent = {
+    readonly type: "transcriptRepair";
+} | {
+    readonly type: "toolResultDisposition";
+} | {
+    readonly type: "evidenceReceipt";
+} | {
+    readonly type: "userSteering";
+} | {
+    readonly type: "settings";
+} | {
+    readonly type: "worktreeFingerprint";
+    readonly value: string;
+} | {
+    readonly type: "activeModelId";
+    readonly value: string;
+} | {
+    readonly type: "compactionModelId";
+    readonly value: string;
+};
+export type ContextCacheInvalidationStatus = "applied" | "unchanged" | "overflow";
+export interface ContextCacheInvalidationResult {
+    readonly status: ContextCacheInvalidationStatus;
+    readonly snapshot: ContextCacheInvalidationSnapshot;
+}
+export type ContextCacheMergeStatus = "equal" | "dominant" | "divergent";
+export type ContextCacheMergeResult = {
+    readonly status: "equal";
+    readonly snapshot: ContextCacheInvalidationSnapshot;
+} | {
+    readonly status: "dominant";
+    readonly snapshot: ContextCacheInvalidationSnapshot;
+} | {
+    readonly status: "divergent";
+    readonly left: ContextCacheInvalidationSnapshot;
+    readonly right: ContextCacheInvalidationSnapshot;
+};
+/**
+ * Strictly validate that {@link input} is a structurally correct snapshot.
+ * Rejects extra keys, missing keys, malformed counters, unsafe integers,
+ * and control/credential-unsafe identifier strings. Does not require the
+ * object to be frozen.
+ */
+export declare function validateContextCacheInvalidationSnapshot(input: unknown): asserts input is ContextCacheInvalidationSnapshot;
+/** Non-throwing variant of {@link validateContextCacheInvalidationSnapshot}. */
+export declare function isContextCacheInvalidationSnapshot(input: unknown): input is ContextCacheInvalidationSnapshot;
+/** Build a validated, deep-frozen initial snapshot. */
+export declare function createContextCacheInvalidationSnapshot(init: ContextCacheInvalidationSnapshotInit): ContextCacheInvalidationSnapshot;
+/**
+ * Apply a single invalidation event. Increments the global epoch and the
+ * relevant counter, or sets an identity. A same-value identity set is a
+ * no-op and returns {@link ContextCacheInvalidationStatus.unchanged} without
+ * an epoch bump. Any counter or epoch overflow returns
+ * {@link ContextCacheInvalidationStatus.overflow} with the snapshot unchanged
+ * and never wraps.
+ */
+export declare function applyContextCacheInvalidation(current: ContextCacheInvalidationSnapshot, event: ContextCacheInvalidationEvent): ContextCacheInvalidationResult;
+/**
+ * Fork a snapshot: keep all event counters and identity values, change the
+ * fork id, and reset the global epoch to 0. The caller supplies the new fork
+ * id. Rejects an id equal to the current fork id.
+ */
+export declare function forkContextCacheSnapshot(current: ContextCacheInvalidationSnapshot, nextForkId: string): ContextCacheInvalidationSnapshot;
+/**
+ * Fail-closed merge of two snapshots.
+ *
+ * - Different fork ids, or two snapshots that are not on a shared linear
+ *   history, yield {@link ContextCacheMergeStatus.divergent}. Disjoint
+ *   changes are never max-merged.
+ * - Structurally equal snapshots yield {@link ContextCacheMergeStatus.equal}.
+ * - When one snapshot componentwise-dominates the other (epoch and every
+ *   counter greater-or-equal, and all identity values equal), the dominant
+ *   snapshot is chosen via {@link ContextCacheMergeStatus.dominant}.
+ */
+export declare function mergeContextCacheSnapshots(a: ContextCacheInvalidationSnapshot, b: ContextCacheInvalidationSnapshot): ContextCacheMergeResult;
+/**
+ * Canonical, fixed-order JSON serialization of a snapshot, suitable as
+ * future cache-key material. The field order is fixed and every distinct
+ * field participates, so any distinct field change alters the result.
+ * Returns a deterministic string with no hash claim.
+ */
+export declare function serializeContextCacheSnapshot(snapshot: ContextCacheInvalidationSnapshot): string;
+//# sourceMappingURL=context-budget-v2-cache-invalidation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-v2-cache-invalidation.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-cache-invalidation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Browser-safe, pure context-cache invalidation snapshot helper.\n *\n * Every public function is side-effect free and depends only on\n * platform-agnostic primitives. Returned snapshots are always\n * independently deep-frozen copies of the caller-supplied data, so\n * callers cannot mutate cached state through retained references.\n *\n * Snapshots are cache-key material for invalidation tracking, not an\n * authorization or authentication primitive.\n *\n * Schema: context-cache-invalidation-v1.\n */\n\nexport const CONTEXT_CACHE_INVALIDATION_SCHEMA_VERSION = \"context-cache-invalidation-v1\" as const;\nexport const CONTEXT_CACHE_INVALIDATION_SAFE_ID_MAX_LENGTH = 256;\n\n/** Event counters tracked by an invalidation snapshot. */\nexport interface ContextCacheInvalidationCounters {\n\treadonly transcriptRepair: number;\n\treadonly toolResultDisposition: number;\n\treadonly evidenceReceipt: number;\n\treadonly userSteering: number;\n\treadonly settings: number;\n}\n\n/** Immutable schema-v1 invalidation snapshot. */\nexport interface ContextCacheInvalidationSnapshot {\n\treadonly schemaVersion: typeof CONTEXT_CACHE_INVALIDATION_SCHEMA_VERSION;\n\treadonly forkId: string;\n\treadonly globalEpoch: number;\n\treadonly counters: ContextCacheInvalidationCounters;\n\treadonly worktreeFingerprint: string;\n\treadonly activeModelId: string;\n\treadonly compactionModelId: string;\n}\n\n/** Constructor input for a fresh snapshot. Counters and epoch default to 0. */\nexport interface ContextCacheInvalidationSnapshotInit {\n\treadonly forkId: string;\n\treadonly worktreeFingerprint: string;\n\treadonly activeModelId: string;\n\treadonly compactionModelId: string;\n\treadonly globalEpoch?: number;\n\treadonly transcriptRepair?: number;\n\treadonly toolResultDisposition?: number;\n\treadonly evidenceReceipt?: number;\n\treadonly userSteering?: number;\n\treadonly settings?: number;\n}\n\n/**\n * Strict union covering all eight invalidation events. The five counter\n * events increment their counter; the three identity events set a value.\n */\nexport type ContextCacheInvalidationEvent =\n\t| { readonly type: \"transcriptRepair\" }\n\t| { readonly type: \"toolResultDisposition\" }\n\t| { readonly type: \"evidenceReceipt\" }\n\t| { readonly type: \"userSteering\" }\n\t| { readonly type: \"settings\" }\n\t| { readonly type: \"worktreeFingerprint\"; readonly value: string }\n\t| { readonly type: \"activeModelId\"; readonly value: string }\n\t| { readonly type: \"compactionModelId\"; readonly value: string };\n\nexport type ContextCacheInvalidationStatus = \"applied\" | \"unchanged\" | \"overflow\";\n\nexport interface ContextCacheInvalidationResult {\n\treadonly status: ContextCacheInvalidationStatus;\n\treadonly snapshot: ContextCacheInvalidationSnapshot;\n}\n\nexport type ContextCacheMergeStatus = \"equal\" | \"dominant\" | \"divergent\";\n\nexport type ContextCacheMergeResult =\n\t| { readonly status: \"equal\"; readonly snapshot: ContextCacheInvalidationSnapshot }\n\t| { readonly status: \"dominant\"; readonly snapshot: ContextCacheInvalidationSnapshot }\n\t| {\n\t\t\treadonly status: \"divergent\";\n\t\t\treadonly left: ContextCacheInvalidationSnapshot;\n\t\t\treadonly right: ContextCacheInvalidationSnapshot;\n\t  };\n\ntype CounterKey = \"transcriptRepair\" | \"toolResultDisposition\" | \"evidenceReceipt\" | \"userSteering\" | \"settings\";\n\ntype IdentityKey = \"worktreeFingerprint\" | \"activeModelId\" | \"compactionModelId\";\n\nconst MAX_REPRESENTABLE = Number.MAX_SAFE_INTEGER;\nconst SAFE_ID_PATTERN = /^[\\w.\\-:+]+$/u;\n\n/**\n * High-confidence credential markers, checked in addition to the\n * safe-character gate. A value already consists only of safe characters\n * before it is tested here. Each pattern is anchored to the whole string\n * to keep the false-positive rate low; identifiers and fingerprints in\n * this domain never legitimately take these shapes.\n */\nconst CREDENTIAL_MARKERS: ReadonlyArray<RegExp> = [\n\t/^sk-[A-Za-z0-9_-]{8,}$/i, // OpenAI / generic \"sk-\" secret keys\n\t/^gh[pousr]_[A-Za-z0-9]{16,}$/i, // GitHub classic tokens (ghp_ gho_ ghu_ ghs_ ghr_)\n\t/^github_pat_[A-Za-z0-9_]{20,}$/i, // GitHub fine-grained PATs\n\t/^xox[pabrse]-[A-Za-z0-9-]{10,}$/i, // Slack tokens (xoxp xoxb xoxa xoxs xoxr xoxe)\n\t/^AKIA[0-9A-Z]{16}$/, // AWS access key id (20 chars, uppercase)\n\t/^eyJ[A-Za-z0-9_-]{8,}\\.[A-Za-z0-9_-]{8,}\\.[A-Za-z0-9_-]{8,}$/, // JWT (three base64url segments)\n\t/^bearer$/i, // literal Bearer token marker\n];\n\nfunction looksLikeCredential(value: string): boolean {\n\tfor (const marker of CREDENTIAL_MARKERS) {\n\t\tif (marker.test(value)) return true;\n\t}\n\treturn false;\n}\n\nconst TOP_LEVEL_KEYS: ReadonlySet<string> = new Set([\n\t\"schemaVersion\",\n\t\"forkId\",\n\t\"globalEpoch\",\n\t\"counters\",\n\t\"worktreeFingerprint\",\n\t\"activeModelId\",\n\t\"compactionModelId\",\n]);\n\nconst COUNTER_KEYS: ReadonlySet<string> = new Set([\n\t\"transcriptRepair\",\n\t\"toolResultDisposition\",\n\t\"evidenceReceipt\",\n\t\"userSteering\",\n\t\"settings\",\n]);\n\nfunction fail(reason: string): never {\n\tthrow new Error(`context-cache-invalidation: ${reason}`);\n}\n\nfunction assertSafeId(value: unknown, field: string): asserts value is string {\n\tif (typeof value !== \"string\") fail(`${field} must be a string`);\n\tif (value.length === 0) fail(`${field} must not be empty`);\n\tif (value.length > CONTEXT_CACHE_INVALIDATION_SAFE_ID_MAX_LENGTH) {\n\t\tfail(`${field} exceeds ${CONTEXT_CACHE_INVALIDATION_SAFE_ID_MAX_LENGTH} characters`);\n\t}\n\tif (!SAFE_ID_PATTERN.test(value)) fail(`${field} contains unsafe characters`);\n\tif (looksLikeCredential(value)) fail(`${field} looks like a credential and was rejected`);\n}\n\nfunction assertNonNegativeSafeInt(value: unknown, field: string): asserts value is number {\n\tif (typeof value !== \"number\") fail(`${field} must be a number`);\n\tif (!Number.isFinite(value)) fail(`${field} must be finite`);\n\tif (!Number.isInteger(value)) fail(`${field} must be an integer`);\n\tif (value < 0) fail(`${field} must be nonnegative`);\n\tif (!Number.isSafeInteger(value)) fail(`${field} must be a safe integer`);\n}\n\nfunction assertExactKeys(record: Record<string, unknown>, allowed: ReadonlySet<string>, scope: string): void {\n\tconst keys = Object.keys(record);\n\tif (keys.length !== allowed.size) fail(`${scope} has unexpected keys`);\n\tfor (const key of keys) {\n\t\tif (!allowed.has(key)) fail(`${scope} has unknown key \"${key}\"`);\n\t}\n}\n\n/** Reject non-plain inputs: null, arrays, primitives, and class instances. */\nfunction assertPlainObject(value: unknown, scope: string): asserts value is Record<string, unknown> {\n\tif (value === null || typeof value !== \"object\") fail(`${scope} must be a plain object`);\n\tif (Array.isArray(value)) fail(`${scope} must be a plain object`);\n\tconst proto = Object.getPrototypeOf(value);\n\tif (proto !== null && proto !== Object.prototype) fail(`${scope} must be a plain object`);\n}\n\n/** Reject getter/setter accessors, whose reads are not stable. */\nfunction assertNoAccessors(record: object, scope: string): void {\n\tfor (const key of Object.getOwnPropertyNames(record)) {\n\t\tconst desc = Object.getOwnPropertyDescriptor(record, key);\n\t\tif (desc !== undefined && (typeof desc.get === \"function\" || typeof desc.set === \"function\")) {\n\t\t\tfail(`${scope} must not define accessors`);\n\t\t}\n\t}\n}\n\nconst INIT_REQUIRED_KEYS: ReadonlySet<string> = new Set([\n\t\"forkId\",\n\t\"worktreeFingerprint\",\n\t\"activeModelId\",\n\t\"compactionModelId\",\n]);\n\nconst INIT_OPTIONAL_KEYS: ReadonlySet<string> = new Set([\n\t\"globalEpoch\",\n\t\"transcriptRepair\",\n\t\"toolResultDisposition\",\n\t\"evidenceReceipt\",\n\t\"userSteering\",\n\t\"settings\",\n]);\n\nconst INIT_ALLOWED_KEYS: ReadonlySet<string> = new Set([...INIT_REQUIRED_KEYS, ...INIT_OPTIONAL_KEYS]);\n\n/**\n * Strictly validate a snapshot constructor input: a plain data object with\n * exactly the required identity/fork keys plus optional counters/epoch, and\n * no accessor properties. Rejects null, arrays, class instances, unknown\n * keys, and getters/setters with a stable error.\n */\nfunction assertInitShape(input: unknown): asserts input is ContextCacheInvalidationSnapshotInit {\n\tassertPlainObject(input, \"init\");\n\tassertNoAccessors(input, \"init\");\n\tfor (const key of Object.keys(input)) {\n\t\tif (!INIT_ALLOWED_KEYS.has(key)) fail(`init has unknown key \"${key}\"`);\n\t}\n\tfor (const required of INIT_REQUIRED_KEYS) {\n\t\tif (!Object.hasOwn(input, required)) {\n\t\t\tfail(`init is missing required key \"${required}\"`);\n\t\t}\n\t}\n}\n\nconst COUNTER_EVENT_TYPES: ReadonlySet<string> = new Set([\n\t\"transcriptRepair\",\n\t\"toolResultDisposition\",\n\t\"evidenceReceipt\",\n\t\"userSteering\",\n\t\"settings\",\n]);\n\nconst IDENTITY_EVENT_TYPES: ReadonlySet<string> = new Set([\n\t\"worktreeFingerprint\",\n\t\"activeModelId\",\n\t\"compactionModelId\",\n]);\n\nconst COUNTER_EVENT_KEYS: ReadonlySet<string> = new Set([\"type\"]);\nconst IDENTITY_EVENT_KEYS: ReadonlySet<string> = new Set([\"type\", \"value\"]);\n\n/**\n * Strictly validate a runtime invalidation event before dispatch. The event\n * must be a plain data object carrying exactly the keys its discriminant\n * allows (counter events: `{ type }`; identity events: `{ type, value }`),\n * a known `type` string, and (for identity events) a safe value. Forged or\n * malformed events always throw here and can never fall through to an\n * undefined result.\n */\nfunction validateEvent(input: unknown): asserts input is ContextCacheInvalidationEvent {\n\tassertPlainObject(input, \"event\");\n\tassertNoAccessors(input, \"event\");\n\tconst type = input.type;\n\tif (type === undefined) fail(\"event is missing type\");\n\tif (typeof type !== \"string\") fail(\"event type must be a string\");\n\tif (COUNTER_EVENT_TYPES.has(type)) {\n\t\tassertExactKeys(input, COUNTER_EVENT_KEYS, \"event\");\n\t\treturn;\n\t}\n\tif (IDENTITY_EVENT_TYPES.has(type)) {\n\t\tassertExactKeys(input, IDENTITY_EVENT_KEYS, \"event\");\n\t\tassertSafeId(input.value, type);\n\t\treturn;\n\t}\n\tfail(`event type \"${type}\" is unknown`);\n}\n\n/**\n * Strictly validate that {@link input} is a structurally correct snapshot.\n * Rejects extra keys, missing keys, malformed counters, unsafe integers,\n * and control/credential-unsafe identifier strings. Does not require the\n * object to be frozen.\n */\nexport function validateContextCacheInvalidationSnapshot(\n\tinput: unknown,\n): asserts input is ContextCacheInvalidationSnapshot {\n\tif (input === null || typeof input !== \"object\" || Array.isArray(input)) {\n\t\tfail(\"snapshot must be a plain object\");\n\t}\n\tconst obj = input as Record<string, unknown>;\n\tassertExactKeys(obj, TOP_LEVEL_KEYS, \"snapshot\");\n\tif (obj.schemaVersion !== CONTEXT_CACHE_INVALIDATION_SCHEMA_VERSION) {\n\t\tfail(`schemaVersion must be ${CONTEXT_CACHE_INVALIDATION_SCHEMA_VERSION}`);\n\t}\n\tassertSafeId(obj.forkId, \"forkId\");\n\tassertNonNegativeSafeInt(obj.globalEpoch, \"globalEpoch\");\n\tif (obj.counters === null || typeof obj.counters !== \"object\" || Array.isArray(obj.counters)) {\n\t\tfail(\"counters must be a plain object\");\n\t}\n\tconst counters = obj.counters as Record<string, unknown>;\n\tassertExactKeys(counters, COUNTER_KEYS, \"counters\");\n\tassertNonNegativeSafeInt(counters.transcriptRepair, \"counters.transcriptRepair\");\n\tassertNonNegativeSafeInt(counters.toolResultDisposition, \"counters.toolResultDisposition\");\n\tassertNonNegativeSafeInt(counters.evidenceReceipt, \"counters.evidenceReceipt\");\n\tassertNonNegativeSafeInt(counters.userSteering, \"counters.userSteering\");\n\tassertNonNegativeSafeInt(counters.settings, \"counters.settings\");\n\tassertSafeId(obj.worktreeFingerprint, \"worktreeFingerprint\");\n\tassertSafeId(obj.activeModelId, \"activeModelId\");\n\tassertSafeId(obj.compactionModelId, \"compactionModelId\");\n}\n\n/** Non-throwing variant of {@link validateContextCacheInvalidationSnapshot}. */\nexport function isContextCacheInvalidationSnapshot(input: unknown): input is ContextCacheInvalidationSnapshot {\n\ttry {\n\t\tvalidateContextCacheInvalidationSnapshot(input);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\ninterface SnapshotBuilder {\n\tschemaVersion: typeof CONTEXT_CACHE_INVALIDATION_SCHEMA_VERSION;\n\tforkId: string;\n\tglobalEpoch: number;\n\tcounters: ContextCacheInvalidationCounters;\n\tworktreeFingerprint: string;\n\tactiveModelId: string;\n\tcompactionModelId: string;\n}\n\nfunction freezeSnapshot(builder: SnapshotBuilder): ContextCacheInvalidationSnapshot {\n\tObject.freeze(builder.counters);\n\treturn Object.freeze(builder) as ContextCacheInvalidationSnapshot;\n}\n\nfunction copyCounters(counters: ContextCacheInvalidationCounters): Record<CounterKey, number> {\n\treturn {\n\t\ttranscriptRepair: counters.transcriptRepair,\n\t\ttoolResultDisposition: counters.toolResultDisposition,\n\t\tevidenceReceipt: counters.evidenceReceipt,\n\t\tuserSteering: counters.userSteering,\n\t\tsettings: counters.settings,\n\t};\n}\n\nfunction cloneAndFreeze(snapshot: ContextCacheInvalidationSnapshot): ContextCacheInvalidationSnapshot {\n\treturn freezeSnapshot({\n\t\tschemaVersion: snapshot.schemaVersion,\n\t\tforkId: snapshot.forkId,\n\t\tglobalEpoch: snapshot.globalEpoch,\n\t\tcounters: copyCounters(snapshot.counters),\n\t\tworktreeFingerprint: snapshot.worktreeFingerprint,\n\t\tactiveModelId: snapshot.activeModelId,\n\t\tcompactionModelId: snapshot.compactionModelId,\n\t});\n}\n\nfunction resolveOptionalCounter(value: number | undefined, field: string): number {\n\tif (value === undefined) return 0;\n\tassertNonNegativeSafeInt(value, field);\n\treturn value;\n}\n\n/** Build a validated, deep-frozen initial snapshot. */\nexport function createContextCacheInvalidationSnapshot(\n\tinit: ContextCacheInvalidationSnapshotInit,\n): ContextCacheInvalidationSnapshot {\n\tassertInitShape(init);\n\tassertSafeId(init.forkId, \"forkId\");\n\tassertSafeId(init.worktreeFingerprint, \"worktreeFingerprint\");\n\tassertSafeId(init.activeModelId, \"activeModelId\");\n\tassertSafeId(init.compactionModelId, \"compactionModelId\");\n\tconst globalEpoch = init.globalEpoch ?? 0;\n\tassertNonNegativeSafeInt(globalEpoch, \"globalEpoch\");\n\treturn freezeSnapshot({\n\t\tschemaVersion: CONTEXT_CACHE_INVALIDATION_SCHEMA_VERSION,\n\t\tforkId: init.forkId,\n\t\tglobalEpoch,\n\t\tcounters: {\n\t\t\ttranscriptRepair: resolveOptionalCounter(init.transcriptRepair, \"transcriptRepair\"),\n\t\t\ttoolResultDisposition: resolveOptionalCounter(init.toolResultDisposition, \"toolResultDisposition\"),\n\t\t\tevidenceReceipt: resolveOptionalCounter(init.evidenceReceipt, \"evidenceReceipt\"),\n\t\t\tuserSteering: resolveOptionalCounter(init.userSteering, \"userSteering\"),\n\t\t\tsettings: resolveOptionalCounter(init.settings, \"settings\"),\n\t\t},\n\t\tworktreeFingerprint: init.worktreeFingerprint,\n\t\tactiveModelId: init.activeModelId,\n\t\tcompactionModelId: init.compactionModelId,\n\t});\n}\n\nfunction applyCounterEvent(current: ContextCacheInvalidationSnapshot, key: CounterKey): ContextCacheInvalidationResult {\n\tconst value = current.counters[key];\n\tif (value >= MAX_REPRESENTABLE || current.globalEpoch >= MAX_REPRESENTABLE) {\n\t\treturn Object.freeze({ status: \"overflow\", snapshot: cloneAndFreeze(current) } as const);\n\t}\n\tconst nextCounters = copyCounters(current.counters);\n\tnextCounters[key] = value + 1;\n\treturn Object.freeze({\n\t\tstatus: \"applied\",\n\t\tsnapshot: freezeSnapshot({\n\t\t\tschemaVersion: current.schemaVersion,\n\t\t\tforkId: current.forkId,\n\t\t\tglobalEpoch: current.globalEpoch + 1,\n\t\t\tcounters: nextCounters,\n\t\t\tworktreeFingerprint: current.worktreeFingerprint,\n\t\t\tactiveModelId: current.activeModelId,\n\t\t\tcompactionModelId: current.compactionModelId,\n\t\t}),\n\t} as const);\n}\n\nfunction applyIdentityEvent(\n\tcurrent: ContextCacheInvalidationSnapshot,\n\tkey: IdentityKey,\n\tvalue: string,\n): ContextCacheInvalidationResult {\n\tassertSafeId(value, key);\n\tif (current[key] === value) {\n\t\treturn Object.freeze({ status: \"unchanged\", snapshot: cloneAndFreeze(current) } as const);\n\t}\n\tif (current.globalEpoch >= MAX_REPRESENTABLE) {\n\t\treturn Object.freeze({ status: \"overflow\", snapshot: cloneAndFreeze(current) } as const);\n\t}\n\treturn Object.freeze({\n\t\tstatus: \"applied\",\n\t\tsnapshot: freezeSnapshot({\n\t\t\tschemaVersion: current.schemaVersion,\n\t\t\tforkId: current.forkId,\n\t\t\tglobalEpoch: current.globalEpoch + 1,\n\t\t\tcounters: copyCounters(current.counters),\n\t\t\tworktreeFingerprint: key === \"worktreeFingerprint\" ? value : current.worktreeFingerprint,\n\t\t\tactiveModelId: key === \"activeModelId\" ? value : current.activeModelId,\n\t\t\tcompactionModelId: key === \"compactionModelId\" ? value : current.compactionModelId,\n\t\t}),\n\t} as const);\n}\n\n/**\n * Apply a single invalidation event. Increments the global epoch and the\n * relevant counter, or sets an identity. A same-value identity set is a\n * no-op and returns {@link ContextCacheInvalidationStatus.unchanged} without\n * an epoch bump. Any counter or epoch overflow returns\n * {@link ContextCacheInvalidationStatus.overflow} with the snapshot unchanged\n * and never wraps.\n */\nexport function applyContextCacheInvalidation(\n\tcurrent: ContextCacheInvalidationSnapshot,\n\tevent: ContextCacheInvalidationEvent,\n): ContextCacheInvalidationResult {\n\tvalidateContextCacheInvalidationSnapshot(current);\n\tvalidateEvent(event);\n\tswitch (event.type) {\n\t\tcase \"transcriptRepair\":\n\t\tcase \"toolResultDisposition\":\n\t\tcase \"evidenceReceipt\":\n\t\tcase \"userSteering\":\n\t\tcase \"settings\":\n\t\t\treturn applyCounterEvent(current, event.type);\n\t\tcase \"worktreeFingerprint\":\n\t\tcase \"activeModelId\":\n\t\tcase \"compactionModelId\":\n\t\t\treturn applyIdentityEvent(current, event.type, event.value);\n\t\tdefault: {\n\t\t\t// Exhaustiveness guard: a new event variant without a matching\n\t\t\t// case becomes a compile error on the assignment below.\n\t\t\tconst _exhaustive: never = event;\n\t\t\tfail(`unhandled event type ${_exhaustive}`);\n\t\t}\n\t}\n}\n\n/**\n * Fork a snapshot: keep all event counters and identity values, change the\n * fork id, and reset the global epoch to 0. The caller supplies the new fork\n * id. Rejects an id equal to the current fork id.\n */\nexport function forkContextCacheSnapshot(\n\tcurrent: ContextCacheInvalidationSnapshot,\n\tnextForkId: string,\n): ContextCacheInvalidationSnapshot {\n\tvalidateContextCacheInvalidationSnapshot(current);\n\tassertSafeId(nextForkId, \"forkId\");\n\tif (nextForkId === current.forkId) {\n\t\tfail(\"forkId must differ from current fork\");\n\t}\n\treturn freezeSnapshot({\n\t\tschemaVersion: current.schemaVersion,\n\t\tforkId: nextForkId,\n\t\tglobalEpoch: 0,\n\t\tcounters: copyCounters(current.counters),\n\t\tworktreeFingerprint: current.worktreeFingerprint,\n\t\tactiveModelId: current.activeModelId,\n\t\tcompactionModelId: current.compactionModelId,\n\t});\n}\n\nfunction snapshotsEqual(a: ContextCacheInvalidationSnapshot, b: ContextCacheInvalidationSnapshot): boolean {\n\treturn (\n\t\ta.globalEpoch === b.globalEpoch &&\n\t\ta.counters.transcriptRepair === b.counters.transcriptRepair &&\n\t\ta.counters.toolResultDisposition === b.counters.toolResultDisposition &&\n\t\ta.counters.evidenceReceipt === b.counters.evidenceReceipt &&\n\t\ta.counters.userSteering === b.counters.userSteering &&\n\t\ta.counters.settings === b.counters.settings &&\n\t\ta.worktreeFingerprint === b.worktreeFingerprint &&\n\t\ta.activeModelId === b.activeModelId &&\n\t\ta.compactionModelId === b.compactionModelId\n\t);\n}\n\nfunction dominates(x: ContextCacheInvalidationSnapshot, y: ContextCacheInvalidationSnapshot): boolean {\n\treturn (\n\t\tx.globalEpoch >= y.globalEpoch &&\n\t\tx.counters.transcriptRepair >= y.counters.transcriptRepair &&\n\t\tx.counters.toolResultDisposition >= y.counters.toolResultDisposition &&\n\t\tx.counters.evidenceReceipt >= y.counters.evidenceReceipt &&\n\t\tx.counters.userSteering >= y.counters.userSteering &&\n\t\tx.counters.settings >= y.counters.settings &&\n\t\tx.worktreeFingerprint === y.worktreeFingerprint &&\n\t\tx.activeModelId === y.activeModelId &&\n\t\tx.compactionModelId === y.compactionModelId\n\t);\n}\n\n/**\n * Fail-closed merge of two snapshots.\n *\n * - Different fork ids, or two snapshots that are not on a shared linear\n *   history, yield {@link ContextCacheMergeStatus.divergent}. Disjoint\n *   changes are never max-merged.\n * - Structurally equal snapshots yield {@link ContextCacheMergeStatus.equal}.\n * - When one snapshot componentwise-dominates the other (epoch and every\n *   counter greater-or-equal, and all identity values equal), the dominant\n *   snapshot is chosen via {@link ContextCacheMergeStatus.dominant}.\n */\nexport function mergeContextCacheSnapshots(\n\ta: ContextCacheInvalidationSnapshot,\n\tb: ContextCacheInvalidationSnapshot,\n): ContextCacheMergeResult {\n\tvalidateContextCacheInvalidationSnapshot(a);\n\tvalidateContextCacheInvalidationSnapshot(b);\n\tif (a.forkId !== b.forkId) {\n\t\treturn Object.freeze({ status: \"divergent\", left: cloneAndFreeze(a), right: cloneAndFreeze(b) } as const);\n\t}\n\tif (snapshotsEqual(a, b)) {\n\t\treturn Object.freeze({ status: \"equal\", snapshot: cloneAndFreeze(a) } as const);\n\t}\n\tconst aDominates = dominates(a, b);\n\tconst bDominates = dominates(b, a);\n\tif (aDominates && !bDominates) {\n\t\treturn Object.freeze({ status: \"dominant\", snapshot: cloneAndFreeze(a) } as const);\n\t}\n\tif (bDominates && !aDominates) {\n\t\treturn Object.freeze({ status: \"dominant\", snapshot: cloneAndFreeze(b) } as const);\n\t}\n\treturn Object.freeze({ status: \"divergent\", left: cloneAndFreeze(a), right: cloneAndFreeze(b) } as const);\n}\n\n/**\n * Canonical, fixed-order JSON serialization of a snapshot, suitable as\n * future cache-key material. The field order is fixed and every distinct\n * field participates, so any distinct field change alters the result.\n * Returns a deterministic string with no hash claim.\n */\nexport function serializeContextCacheSnapshot(snapshot: ContextCacheInvalidationSnapshot): string {\n\tvalidateContextCacheInvalidationSnapshot(snapshot);\n\treturn JSON.stringify({\n\t\tschemaVersion: snapshot.schemaVersion,\n\t\tforkId: snapshot.forkId,\n\t\tglobalEpoch: snapshot.globalEpoch,\n\t\tcounters: {\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\tworktreeFingerprint: snapshot.worktreeFingerprint,\n\t\tactiveModelId: snapshot.activeModelId,\n\t\tcompactionModelId: snapshot.compactionModelId,\n\t});\n}\n"]}