open-multi-agent-kit 0.90.8 → 0.91.0

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"]}

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

@@ -0,0 +1,452 @@
+/**
+ * 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 const CONTEXT_CACHE_INVALIDATION_SCHEMA_VERSION = "context-cache-invalidation-v1";
+export const CONTEXT_CACHE_INVALIDATION_SAFE_ID_MAX_LENGTH = 256;
+const MAX_REPRESENTABLE = Number.MAX_SAFE_INTEGER;
+const SAFE_ID_PATTERN = /^[\w.\-:+]+$/u;
+/**
+ * High-confidence credential markers, checked in addition to the
+ * safe-character gate. A value already consists only of safe characters
+ * before it is tested here. Each pattern is anchored to the whole string
+ * to keep the false-positive rate low; identifiers and fingerprints in
+ * this domain never legitimately take these shapes.
+ */
+const CREDENTIAL_MARKERS = [
+    /^sk-[A-Za-z0-9_-]{8,}$/i, // OpenAI / generic "sk-" secret keys
+    /^gh[pousr]_[A-Za-z0-9]{16,}$/i, // GitHub classic tokens (ghp_ gho_ ghu_ ghs_ ghr_)
+    /^github_pat_[A-Za-z0-9_]{20,}$/i, // GitHub fine-grained PATs
+    /^xox[pabrse]-[A-Za-z0-9-]{10,}$/i, // Slack tokens (xoxp xoxb xoxa xoxs xoxr xoxe)
+    /^AKIA[0-9A-Z]{16}$/, // AWS access key id (20 chars, uppercase)
+    /^eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}$/, // JWT (three base64url segments)
+    /^bearer$/i, // literal Bearer token marker
+];
+function looksLikeCredential(value) {
+    for (const marker of CREDENTIAL_MARKERS) {
+        if (marker.test(value))
+            return true;
+    }
+    return false;
+}
+const TOP_LEVEL_KEYS = new Set([
+    "schemaVersion",
+    "forkId",
+    "globalEpoch",
+    "counters",
+    "worktreeFingerprint",
+    "activeModelId",
+    "compactionModelId",
+]);
+const COUNTER_KEYS = new Set([
+    "transcriptRepair",
+    "toolResultDisposition",
+    "evidenceReceipt",
+    "userSteering",
+    "settings",
+]);
+function fail(reason) {
+    throw new Error(`context-cache-invalidation: ${reason}`);
+}
+function assertSafeId(value, field) {
+    if (typeof value !== "string")
+        fail(`${field} must be a string`);
+    if (value.length === 0)
+        fail(`${field} must not be empty`);
+    if (value.length > CONTEXT_CACHE_INVALIDATION_SAFE_ID_MAX_LENGTH) {
+        fail(`${field} exceeds ${CONTEXT_CACHE_INVALIDATION_SAFE_ID_MAX_LENGTH} characters`);
+    }
+    if (!SAFE_ID_PATTERN.test(value))
+        fail(`${field} contains unsafe characters`);
+    if (looksLikeCredential(value))
+        fail(`${field} looks like a credential and was rejected`);
+}
+function assertNonNegativeSafeInt(value, field) {
+    if (typeof value !== "number")
+        fail(`${field} must be a number`);
+    if (!Number.isFinite(value))
+        fail(`${field} must be finite`);
+    if (!Number.isInteger(value))
+        fail(`${field} must be an integer`);
+    if (value < 0)
+        fail(`${field} must be nonnegative`);
+    if (!Number.isSafeInteger(value))
+        fail(`${field} must be a safe integer`);
+}
+function assertExactKeys(record, allowed, scope) {
+    const keys = Object.keys(record);
+    if (keys.length !== allowed.size)
+        fail(`${scope} has unexpected keys`);
+    for (const key of keys) {
+        if (!allowed.has(key))
+            fail(`${scope} has unknown key "${key}"`);
+    }
+}
+/** Reject non-plain inputs: null, arrays, primitives, and class instances. */
+function assertPlainObject(value, scope) {
+    if (value === null || typeof value !== "object")
+        fail(`${scope} must be a plain object`);
+    if (Array.isArray(value))
+        fail(`${scope} must be a plain object`);
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== null && proto !== Object.prototype)
+        fail(`${scope} must be a plain object`);
+}
+/** Reject getter/setter accessors, whose reads are not stable. */
+function assertNoAccessors(record, scope) {
+    for (const key of Object.getOwnPropertyNames(record)) {
+        const desc = Object.getOwnPropertyDescriptor(record, key);
+        if (desc !== undefined && (typeof desc.get === "function" || typeof desc.set === "function")) {
+            fail(`${scope} must not define accessors`);
+        }
+    }
+}
+const INIT_REQUIRED_KEYS = new Set([
+    "forkId",
+    "worktreeFingerprint",
+    "activeModelId",
+    "compactionModelId",
+]);
+const INIT_OPTIONAL_KEYS = new Set([
+    "globalEpoch",
+    "transcriptRepair",
+    "toolResultDisposition",
+    "evidenceReceipt",
+    "userSteering",
+    "settings",
+]);
+const INIT_ALLOWED_KEYS = new Set([...INIT_REQUIRED_KEYS, ...INIT_OPTIONAL_KEYS]);
+/**
+ * Strictly validate a snapshot constructor input: a plain data object with
+ * exactly the required identity/fork keys plus optional counters/epoch, and
+ * no accessor properties. Rejects null, arrays, class instances, unknown
+ * keys, and getters/setters with a stable error.
+ */
+function assertInitShape(input) {
+    assertPlainObject(input, "init");
+    assertNoAccessors(input, "init");
+    for (const key of Object.keys(input)) {
+        if (!INIT_ALLOWED_KEYS.has(key))
+            fail(`init has unknown key "${key}"`);
+    }
+    for (const required of INIT_REQUIRED_KEYS) {
+        if (!Object.hasOwn(input, required)) {
+            fail(`init is missing required key "${required}"`);
+        }
+    }
+}
+const COUNTER_EVENT_TYPES = new Set([
+    "transcriptRepair",
+    "toolResultDisposition",
+    "evidenceReceipt",
+    "userSteering",
+    "settings",
+]);
+const IDENTITY_EVENT_TYPES = new Set([
+    "worktreeFingerprint",
+    "activeModelId",
+    "compactionModelId",
+]);
+const COUNTER_EVENT_KEYS = new Set(["type"]);
+const IDENTITY_EVENT_KEYS = new Set(["type", "value"]);
+/**
+ * Strictly validate a runtime invalidation event before dispatch. The event
+ * must be a plain data object carrying exactly the keys its discriminant
+ * allows (counter events: `{ type }`; identity events: `{ type, value }`),
+ * a known `type` string, and (for identity events) a safe value. Forged or
+ * malformed events always throw here and can never fall through to an
+ * undefined result.
+ */
+function validateEvent(input) {
+    assertPlainObject(input, "event");
+    assertNoAccessors(input, "event");
+    const type = input.type;
+    if (type === undefined)
+        fail("event is missing type");
+    if (typeof type !== "string")
+        fail("event type must be a string");
+    if (COUNTER_EVENT_TYPES.has(type)) {
+        assertExactKeys(input, COUNTER_EVENT_KEYS, "event");
+        return;
+    }
+    if (IDENTITY_EVENT_TYPES.has(type)) {
+        assertExactKeys(input, IDENTITY_EVENT_KEYS, "event");
+        assertSafeId(input.value, type);
+        return;
+    }
+    fail(`event type "${type}" is unknown`);
+}
+/**
+ * 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 function validateContextCacheInvalidationSnapshot(input) {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        fail("snapshot must be a plain object");
+    }
+    const obj = input;
+    assertExactKeys(obj, TOP_LEVEL_KEYS, "snapshot");
+    if (obj.schemaVersion !== CONTEXT_CACHE_INVALIDATION_SCHEMA_VERSION) {
+        fail(`schemaVersion must be ${CONTEXT_CACHE_INVALIDATION_SCHEMA_VERSION}`);
+    }
+    assertSafeId(obj.forkId, "forkId");
+    assertNonNegativeSafeInt(obj.globalEpoch, "globalEpoch");
+    if (obj.counters === null || typeof obj.counters !== "object" || Array.isArray(obj.counters)) {
+        fail("counters must be a plain object");
+    }
+    const counters = obj.counters;
+    assertExactKeys(counters, COUNTER_KEYS, "counters");
+    assertNonNegativeSafeInt(counters.transcriptRepair, "counters.transcriptRepair");
+    assertNonNegativeSafeInt(counters.toolResultDisposition, "counters.toolResultDisposition");
+    assertNonNegativeSafeInt(counters.evidenceReceipt, "counters.evidenceReceipt");
+    assertNonNegativeSafeInt(counters.userSteering, "counters.userSteering");
+    assertNonNegativeSafeInt(counters.settings, "counters.settings");
+    assertSafeId(obj.worktreeFingerprint, "worktreeFingerprint");
+    assertSafeId(obj.activeModelId, "activeModelId");
+    assertSafeId(obj.compactionModelId, "compactionModelId");
+}
+/** Non-throwing variant of {@link validateContextCacheInvalidationSnapshot}. */
+export function isContextCacheInvalidationSnapshot(input) {
+    try {
+        validateContextCacheInvalidationSnapshot(input);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function freezeSnapshot(builder) {
+    Object.freeze(builder.counters);
+    return Object.freeze(builder);
+}
+function copyCounters(counters) {
+    return {
+        transcriptRepair: counters.transcriptRepair,
+        toolResultDisposition: counters.toolResultDisposition,
+        evidenceReceipt: counters.evidenceReceipt,
+        userSteering: counters.userSteering,
+        settings: counters.settings,
+    };
+}
+function cloneAndFreeze(snapshot) {
+    return freezeSnapshot({
+        schemaVersion: snapshot.schemaVersion,
+        forkId: snapshot.forkId,
+        globalEpoch: snapshot.globalEpoch,
+        counters: copyCounters(snapshot.counters),
+        worktreeFingerprint: snapshot.worktreeFingerprint,
+        activeModelId: snapshot.activeModelId,
+        compactionModelId: snapshot.compactionModelId,
+    });
+}
+function resolveOptionalCounter(value, field) {
+    if (value === undefined)
+        return 0;
+    assertNonNegativeSafeInt(value, field);
+    return value;
+}
+/** Build a validated, deep-frozen initial snapshot. */
+export function createContextCacheInvalidationSnapshot(init) {
+    assertInitShape(init);
+    assertSafeId(init.forkId, "forkId");
+    assertSafeId(init.worktreeFingerprint, "worktreeFingerprint");
+    assertSafeId(init.activeModelId, "activeModelId");
+    assertSafeId(init.compactionModelId, "compactionModelId");
+    const globalEpoch = init.globalEpoch ?? 0;
+    assertNonNegativeSafeInt(globalEpoch, "globalEpoch");
+    return freezeSnapshot({
+        schemaVersion: CONTEXT_CACHE_INVALIDATION_SCHEMA_VERSION,
+        forkId: init.forkId,
+        globalEpoch,
+        counters: {
+            transcriptRepair: resolveOptionalCounter(init.transcriptRepair, "transcriptRepair"),
+            toolResultDisposition: resolveOptionalCounter(init.toolResultDisposition, "toolResultDisposition"),
+            evidenceReceipt: resolveOptionalCounter(init.evidenceReceipt, "evidenceReceipt"),
+            userSteering: resolveOptionalCounter(init.userSteering, "userSteering"),
+            settings: resolveOptionalCounter(init.settings, "settings"),
+        },
+        worktreeFingerprint: init.worktreeFingerprint,
+        activeModelId: init.activeModelId,
+        compactionModelId: init.compactionModelId,
+    });
+}
+function applyCounterEvent(current, key) {
+    const value = current.counters[key];
+    if (value >= MAX_REPRESENTABLE || current.globalEpoch >= MAX_REPRESENTABLE) {
+        return Object.freeze({ status: "overflow", snapshot: cloneAndFreeze(current) });
+    }
+    const nextCounters = copyCounters(current.counters);
+    nextCounters[key] = value + 1;
+    return Object.freeze({
+        status: "applied",
+        snapshot: freezeSnapshot({
+            schemaVersion: current.schemaVersion,
+            forkId: current.forkId,
+            globalEpoch: current.globalEpoch + 1,
+            counters: nextCounters,
+            worktreeFingerprint: current.worktreeFingerprint,
+            activeModelId: current.activeModelId,
+            compactionModelId: current.compactionModelId,
+        }),
+    });
+}
+function applyIdentityEvent(current, key, value) {
+    assertSafeId(value, key);
+    if (current[key] === value) {
+        return Object.freeze({ status: "unchanged", snapshot: cloneAndFreeze(current) });
+    }
+    if (current.globalEpoch >= MAX_REPRESENTABLE) {
+        return Object.freeze({ status: "overflow", snapshot: cloneAndFreeze(current) });
+    }
+    return Object.freeze({
+        status: "applied",
+        snapshot: freezeSnapshot({
+            schemaVersion: current.schemaVersion,
+            forkId: current.forkId,
+            globalEpoch: current.globalEpoch + 1,
+            counters: copyCounters(current.counters),
+            worktreeFingerprint: key === "worktreeFingerprint" ? value : current.worktreeFingerprint,
+            activeModelId: key === "activeModelId" ? value : current.activeModelId,
+            compactionModelId: key === "compactionModelId" ? value : current.compactionModelId,
+        }),
+    });
+}
+/**
+ * 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 function applyContextCacheInvalidation(current, event) {
+    validateContextCacheInvalidationSnapshot(current);
+    validateEvent(event);
+    switch (event.type) {
+        case "transcriptRepair":
+        case "toolResultDisposition":
+        case "evidenceReceipt":
+        case "userSteering":
+        case "settings":
+            return applyCounterEvent(current, event.type);
+        case "worktreeFingerprint":
+        case "activeModelId":
+        case "compactionModelId":
+            return applyIdentityEvent(current, event.type, event.value);
+        default: {
+            // Exhaustiveness guard: a new event variant without a matching
+            // case becomes a compile error on the assignment below.
+            const _exhaustive = event;
+            fail(`unhandled event type ${_exhaustive}`);
+        }
+    }
+}
+/**
+ * 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 function forkContextCacheSnapshot(current, nextForkId) {
+    validateContextCacheInvalidationSnapshot(current);
+    assertSafeId(nextForkId, "forkId");
+    if (nextForkId === current.forkId) {
+        fail("forkId must differ from current fork");
+    }
+    return freezeSnapshot({
+        schemaVersion: current.schemaVersion,
+        forkId: nextForkId,
+        globalEpoch: 0,
+        counters: copyCounters(current.counters),
+        worktreeFingerprint: current.worktreeFingerprint,
+        activeModelId: current.activeModelId,
+        compactionModelId: current.compactionModelId,
+    });
+}
+function snapshotsEqual(a, b) {
+    return (a.globalEpoch === b.globalEpoch &&
+        a.counters.transcriptRepair === b.counters.transcriptRepair &&
+        a.counters.toolResultDisposition === b.counters.toolResultDisposition &&
+        a.counters.evidenceReceipt === b.counters.evidenceReceipt &&
+        a.counters.userSteering === b.counters.userSteering &&
+        a.counters.settings === b.counters.settings &&
+        a.worktreeFingerprint === b.worktreeFingerprint &&
+        a.activeModelId === b.activeModelId &&
+        a.compactionModelId === b.compactionModelId);
+}
+function dominates(x, y) {
+    return (x.globalEpoch >= y.globalEpoch &&
+        x.counters.transcriptRepair >= y.counters.transcriptRepair &&
+        x.counters.toolResultDisposition >= y.counters.toolResultDisposition &&
+        x.counters.evidenceReceipt >= y.counters.evidenceReceipt &&
+        x.counters.userSteering >= y.counters.userSteering &&
+        x.counters.settings >= y.counters.settings &&
+        x.worktreeFingerprint === y.worktreeFingerprint &&
+        x.activeModelId === y.activeModelId &&
+        x.compactionModelId === y.compactionModelId);
+}
+/**
+ * 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 function mergeContextCacheSnapshots(a, b) {
+    validateContextCacheInvalidationSnapshot(a);
+    validateContextCacheInvalidationSnapshot(b);
+    if (a.forkId !== b.forkId) {
+        return Object.freeze({ status: "divergent", left: cloneAndFreeze(a), right: cloneAndFreeze(b) });
+    }
+    if (snapshotsEqual(a, b)) {
+        return Object.freeze({ status: "equal", snapshot: cloneAndFreeze(a) });
+    }
+    const aDominates = dominates(a, b);
+    const bDominates = dominates(b, a);
+    if (aDominates && !bDominates) {
+        return Object.freeze({ status: "dominant", snapshot: cloneAndFreeze(a) });
+    }
+    if (bDominates && !aDominates) {
+        return Object.freeze({ status: "dominant", snapshot: cloneAndFreeze(b) });
+    }
+    return Object.freeze({ status: "divergent", left: cloneAndFreeze(a), right: cloneAndFreeze(b) });
+}
+/**
+ * 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 function serializeContextCacheSnapshot(snapshot) {
+    validateContextCacheInvalidationSnapshot(snapshot);
+    return JSON.stringify({
+        schemaVersion: snapshot.schemaVersion,
+        forkId: snapshot.forkId,
+        globalEpoch: snapshot.globalEpoch,
+        counters: {
+            transcriptRepair: snapshot.counters.transcriptRepair,
+            toolResultDisposition: snapshot.counters.toolResultDisposition,
+            evidenceReceipt: snapshot.counters.evidenceReceipt,
+            userSteering: snapshot.counters.userSteering,
+            settings: snapshot.counters.settings,
+        },
+        worktreeFingerprint: snapshot.worktreeFingerprint,
+        activeModelId: snapshot.activeModelId,
+        compactionModelId: snapshot.compactionModelId,
+    });
+}
+//# sourceMappingURL=context-budget-v2-cache-invalidation.js.map