diff --git a/kernel/package.json b/kernel/package.json index db30ddde37..3e057e1b3b 100644 --- a/kernel/package.json +++ b/kernel/package.json @@ -1,6 +1,6 @@ { "name": "acp-kernel", - "version": "0.0.126", + "version": "0.0.127", "description": "Framework-agnostic context-compression engine (model-driven, 3-tier LSM). Pure core: no host dependency.", "license": "MIT", "author": "ranxianglei", diff --git a/kernel/src/compress.ts b/kernel/src/compress.ts index deb8bb9b89..a51bb1c9e3 100644 --- a/kernel/src/compress.ts +++ b/kernel/src/compress.ts @@ -1804,7 +1804,7 @@ function computeContextBreakdown( return { system, tool, summaries, code, text, total, growth }; } -function cloneState(state: CompressionState): CompressionState { +export function cloneState(state: CompressionState): CompressionState { return { blocks: state.blocks.map((block) => ({ ...block, diff --git a/kernel/src/persist/state-merge.ts b/kernel/src/persist/state-merge.ts index 5ca3c3ac4e..f50b166fa7 100644 --- a/kernel/src/persist/state-merge.ts +++ b/kernel/src/persist/state-merge.ts @@ -25,5 +25,11 @@ export function mergeCompressionState( rules: parsed.rules ?? fresh.rules, nextRuleId: parsed.nextRuleId ?? fresh.nextRuleId, terminalStreak: parsed.terminalStreak, + // #2388/#2370: bare passthrough like terminalStreak above — none of these + // three optional fields is seeded by createInitialState, and without a line + // here a standalone acp-kernel consumer loses it on restart. + hiddenOrphanRefs: parsed.hiddenOrphanRefs, + deadRefs: parsed.deadRefs, + lastPassIds: parsed.lastPassIds, }; } diff --git a/kernel/tests/state-clone-fidelity.test.ts b/kernel/tests/state-clone-fidelity.test.ts new file mode 100644 index 0000000000..b4e330ebc5 --- /dev/null +++ b/kernel/tests/state-clone-fidelity.test.ts @@ -0,0 +1,137 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import type { CompressionState } from "../src/types.js"; +import { createInitialState } from "../src/state.js"; +import { syncBlocks } from "../src/sync.js"; +import { cloneState } from "../src/compress.js"; +import { mergeCompressionState } from "../src/persist/state-merge.js"; + +/** + * Clone-fidelity guard (#2388). + * + * CompressionState's clone/hydrate points rebuild the object with EXPLICIT + * field lists. Every time a new OPTIONAL field lands, any point whose list did + * not keep up silently drops it — no compile error, no log, no runtime warning; + * `deadRefs` (#2362/#2370) hit three such points. This suite makes that drift + * RED instead of silent, with two independent layers: + * + * 1. COMPILE-TIME — FIELD_INVENTORY is a mapped type over `keyof + * CompressionState` with optionality stripped (`-?`). Adding a field (esp. + * an optional one) without listing it here is a TYPE ERROR, so the omission + * surfaces at `tsc` before any test runs. + * 2. RUNTIME — each point runs on a fully-populated reference state and its + * actually-missing keys are compared for EXACT equality against the + * documented EXPECTED_MISSING set below. A point silently dropping or + * gaining a field flips one of those sets and fails, naming the field. + * + * EXPECTED_MISSING therefore doubles as the LIVING DOCUMENTATION of each + * point's known gap list + why it is safe today. Keep it exact: when a gap is + * fixed (or a new field added), update the set in the SAME change. + */ + +/** Compile-time inventory: every CompressionState field, listed exactly once. + * `-?` strips optionality so omitting even an optional field is a type error. */ +type FieldInventory = { [K in keyof CompressionState]-?: K }; +const FIELD_INVENTORY: FieldInventory = { + blocks: "blocks", + messageRefs: "messageRefs", + tokenSnapshot: "tokenSnapshot", + nudge: "nudge", + stats: "stats", + absorbed: "absorbed", + terminalStreak: "terminalStreak", + rules: "rules", + nextRuleId: "nextRuleId", + hiddenOrphanRefs: "hiddenOrphanRefs", + deadRefs: "deadRefs", + lastPassIds: "lastPassIds", + nextBlockId: "nextBlockId", + nextRunId: "nextRunId", +}; +const ALL_KEYS = Object.keys(FIELD_INVENTORY) as (keyof CompressionState)[]; + +/** Populate EVERY field so presence is detectable: a clone omits a field iff + * out[k] === undefined here. The four fields createInitialState does not seed + * get non-empty sentinels so a conditional copy (cloneState's + * `hiddenOrphanRefs ? [...] : undefined`) still counts them as carried. */ +function fullyPopulated(): CompressionState { + const s = createInitialState(); + s.terminalStreak = 3; + s.hiddenOrphanRefs = ["m00001"]; + s.deadRefs = ["m00002"]; + s.lastPassIds = ["rawA"]; + return s; +} + +function missingKeys(out: CompressionState): Set { + const missing = new Set(); + for (const k of ALL_KEYS) if (out[k] === undefined) missing.add(k); + return missing; +} + +function assertFidelity( + point: string, + out: CompressionState, + expectedMissing: readonly (keyof CompressionState)[], +): void { + const expected = new Set(expectedMissing); + const actual = missingKeys(out); + const droppedUndocumented = [...actual].filter((k) => !expected.has(k)); + const carriedStaleAllowlist = [...expected].filter((k) => !actual.has(k)); + assert.equal( + droppedUndocumented.length + carriedStaleAllowlist.length, + 0, + `${point} clone-fidelity drift:\n` + + ` dropped but not documented here: ${JSON.stringify(droppedUndocumented)}\n` + + ` now carried but still listed as expected-missing: ${JSON.stringify(carriedStaleAllowlist)}`, + ); +} + +test("field inventory covers every populated-state key", () => { + const extra = Object.keys(fullyPopulated()).filter( + (k) => !(ALL_KEYS as readonly string[]).includes(k), + ); + assert.deepEqual(extra, [], `fullyPopulated() has keys outside FIELD_INVENTORY: ${extra.join(", ")}`); +}); + +// syncBlocks runs every request (pipeline node #3). Its two documented gaps are +// both safe TODAY, which is why they stay omitted rather than being carried: +// - hiddenOrphanRefs: self-heals — hideCompressCallsNode (buildNodes #10, after +// syncBlocks #3) re-derives it every pass (compress.ts writes +// state.hiddenOrphanRefs unconditionally). +// - lastPassIds: inert — reconcile-live-ids (#1) consumes the host-passed prior +// pass BEFORE syncBlocks (#3), and processTurn re-stamps result.state.lastPassIds +// post-pipeline (compress.ts inboundIds snapshot + re-stamp). +// (deadRefs is carried by syncBlocks, so it is not a gap.) +test("syncBlocks carries its documented field set", () => { + const { state } = syncBlocks([], fullyPopulated()); + assertFidelity( + "syncBlocks (kernel/src/sync.ts)", + state, + ["hiddenOrphanRefs", "lastPassIds"], + ); +}); + +// cloneState (only call site: applyCompression) copies EVERY field, including +// the conditional optional refs (hiddenOrphanRefs/deadRefs/lastPassIds), so its +// gap set is empty. +test("cloneState carries its documented field set", () => { + assertFidelity( + "cloneState (kernel/src/compress.ts)", + cloneState(fullyPopulated()), + [], + ); +}); + +// mergeCompressionState is the forward-compat HYDRATOR for standalone acp-kernel +// consumers. Unlike the pipeline clones above it must carry EVERY field: a real +// consumer's restart must not lose optional state. Its explicit list carries all +// three optional ref fields (hiddenOrphanRefs, deadRefs, lastPassIds) as bare +// passthrough, so its gap set is empty. +test("mergeCompressionState carries every field (forward-compat hydrator)", () => { + assertFidelity( + "mergeCompressionState (kernel/src/persist/state-merge.ts)", + mergeCompressionState(fullyPopulated()), + [], + ); +}); diff --git a/package-lock.json b/package-lock.json index 903dd1659e..14529301c6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -45,7 +45,7 @@ }, "kernel": { "name": "acp-kernel", - "version": "0.0.126", + "version": "0.0.127", "dev": true, "license": "MIT", "devDependencies": { diff --git a/src/persist.ts b/src/persist.ts index 6c9ea94fdc..9013977c80 100644 --- a/src/persist.ts +++ b/src/persist.ts @@ -200,7 +200,7 @@ type Logger = (level: "info" | "warn" | "error", msg: string) => void; /** Forward-compat: merge a parsed state with a fresh one so missing fields * (added in later versions) get sane defaults instead of `undefined`. */ -function mergeState(parsed: CompressionState): CompressionState { +export function mergeState(parsed: CompressionState): CompressionState { const fresh = createInitialState(); return { // #2627: heal persisted state written before the turn-separator fix — diff --git a/tests/state-clone-fidelity.test.ts b/tests/state-clone-fidelity.test.ts new file mode 100644 index 0000000000..b49c4c02e4 --- /dev/null +++ b/tests/state-clone-fidelity.test.ts @@ -0,0 +1,82 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import type { CompressionState } from "acp-kernel"; +import { createInitialState } from "acp-kernel"; +import { mergeState } from "../src/persist.js"; + +/** + * Clone-fidelity guard — HOST side (#2388). Companion to + * kernel/tests/state-clone-fidelity.test.ts (which covers the kernel's own + * clone/hydrate points). Same two-layer idea: a compile-time field inventory + * (mapped over `keyof CompressionState`, optionality stripped, so adding a + * field without listing it is a TYPE ERROR) plus a runtime EXACT match between + * the fields a point actually carries and the documented expected set. + */ + +type FieldInventory = { [K in keyof CompressionState]-?: K }; +const FIELD_INVENTORY: FieldInventory = { + blocks: "blocks", + messageRefs: "messageRefs", + tokenSnapshot: "tokenSnapshot", + nudge: "nudge", + stats: "stats", + absorbed: "absorbed", + terminalStreak: "terminalStreak", + rules: "rules", + nextRuleId: "nextRuleId", + hiddenOrphanRefs: "hiddenOrphanRefs", + deadRefs: "deadRefs", + lastPassIds: "lastPassIds", + nextBlockId: "nextBlockId", + nextRunId: "nextRunId", +}; +const ALL_KEYS = Object.keys(FIELD_INVENTORY) as (keyof CompressionState)[]; + +function fullyPopulated(): CompressionState { + const s = createInitialState(); + s.terminalStreak = 3; + s.hiddenOrphanRefs = ["m00001"]; + s.deadRefs = ["m00002"]; + s.lastPassIds = ["rawA"]; + return s; +} + +function missingKeys(out: CompressionState): Set { + const missing = new Set(); + for (const k of ALL_KEYS) if (out[k] === undefined) missing.add(k); + return missing; +} + +// mergeState is the host restart hydrator (src/persist.ts). It already carries +// every field — #2370 added deadRefs here when it landed. Its expected-missing +// set is therefore empty; this pins that completeness against regression. +test("mergeState carries every field (host hydrator)", () => { + const out = mergeState(fullyPopulated()); + const expectedMissing: readonly (keyof CompressionState)[] = []; + const expected = new Set(expectedMissing); + const actual = missingKeys(out); + const droppedUndocumented = [...actual].filter((k) => !expected.has(k)); + const carriedStaleAllowlist = [...expected].filter((k) => !actual.has(k)); + assert.equal( + droppedUndocumented.length + carriedStaleAllowlist.length, + 0, + `mergeState (src/persist.ts) clone-fidelity drift:\n` + + ` dropped but not documented: ${JSON.stringify(droppedUndocumented)}\n` + + ` now carried but still listed as expected-missing: ${JSON.stringify(carriedStaleAllowlist)}`, + ); +}); + +/** + * NOT auto-guarded here: the subagent fork (src/plugin.ts protocolVersion-2 + * child-session handler) is TARGETED inheritance, not a full-state clone — it + * inherits prefix-scoped subsets per field (blocks / tokenSnapshot / + * hiddenOrphanRefs / deadRefs / absorbed / rules filtered or cloned for the + * forked prefix), recomputes others (lastPassIds from the prefix, stats from + * inherited blocks, nudge only on a full-prefix fork), and skips terminalStreak. + * Its failure mode is different: every NEW CompressionState field needs a + * conscious inherit-or-skip decision at that site, and an unmade decision = + * silent skip. Driving the handler requires the full session/lock/snapshot + * harness, so it is documented rather than asserted here. If the owner wants it + * covered, extract the parent→child state mapping into a pure function and add + * it to this suite. + */