Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion kernel/package.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
2 changes: 1 addition & 1 deletion kernel/src/compress.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
6 changes: 6 additions & 0 deletions kernel/src/persist/state-merge.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
};
}
137 changes: 137 additions & 0 deletions kernel/tests/state-clone-fidelity.test.ts
Original file line number Diff line number Diff line change
@@ -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<keyof CompressionState> {
const missing = new Set<keyof CompressionState>();
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()),
[],
);
});
2 changes: 1 addition & 1 deletion package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion src/persist.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 —
Expand Down
82 changes: 82 additions & 0 deletions tests/state-clone-fidelity.test.ts
Original file line number Diff line number Diff line change
@@ -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<keyof CompressionState> {
const missing = new Set<keyof CompressionState>();
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.
*/
Loading