From d645698f21b139d78fdf2932dc0ff0c8faa2d51f Mon Sep 17 00:00:00 2001 From: SeniorHan Date: Fri, 23 Oct 2026 22:21:16 +0800 Subject: [PATCH 1/3] feat: opt-in branch-aware block masking via persistedMessageIds --- src/branch-awareness.ts | 51 +++++++++++++++++ src/compress.ts | 49 +++++++++++++++- tests/branch-awareness.test.ts | 101 +++++++++++++++++++++++++++++++++ 3 files changed, 200 insertions(+), 1 deletion(-) create mode 100644 src/branch-awareness.ts create mode 100644 tests/branch-awareness.test.ts diff --git a/src/branch-awareness.ts b/src/branch-awareness.ts new file mode 100644 index 0000000..ba3af6c --- /dev/null +++ b/src/branch-awareness.ts @@ -0,0 +1,51 @@ +import type { CompressionState, CoreMessage } from "./types.js"; + +/** + * Branch-aware block activity. + * + * The kernel's syncBlocks keeps a block active while ANY of its covered + * messages is still in view. After a host-side rewind into the middle of a + * block's range (e.g. pi's `/tree` navigation), the block's summary — which + * describes messages that now live on another branch — would replace the few + * messages still in view, showing the model decisions from a future it has + * not reached. + * + * A block is "off-branch" when some of its covered messages are in view and + * some are known-persisted session entries that are NOT on the current + * branch. The host declares the persisted id set per turn via + * `ProcessTurnInput.persistedMessageIds`; `processTurn` then masks such + * blocks as expanded for the turn (their in-view messages show raw) and + * restores the original `expanded` flag on the result, so nothing is + * persisted: returning to the full branch reactivates the block. Messages + * missing for other reasons (never persisted, host-side live ids) keep the + * kernel's default behaviour. + */ + +/** Strip a live-instance subid: `"e3#k2"` and `"e3"` share the base `"e3"`. */ +function baseIdOf(id: string): string { + const hash = id.indexOf("#"); + return hash > 0 ? id.substring(0, hash) : id; +} + +export function findOffBranchBlocks( + messages: readonly CoreMessage[], + state: CompressionState, + persistedIds: ReadonlySet, +): string[] { + const present = new Set(); + for (const m of messages) if (typeof m.id === "string") present.add(baseIdOf(m.id)); + const off: string[] = []; + for (const block of state.blocks) { + if (block.expanded) continue; + let inView = false; + let elsewhere = false; + for (const id of block.effectiveMessageIds) { + const base = baseIdOf(id); + if (present.has(base)) inView = true; + else if (persistedIds.has(base)) elsewhere = true; + if (inView && elsewhere) break; + } + if (inView && elsewhere) off.push(block.blockId); + } + return off; +} diff --git a/src/compress.ts b/src/compress.ts index f95f76d..b39d0dc 100644 --- a/src/compress.ts +++ b/src/compress.ts @@ -2,6 +2,7 @@ import { assignRefs, highestUsedIndex, indexToRef } from "./refs.js"; import { remintCoveredLiveIds } from "./instance-reid.js"; import { prune, isSummaryMessageId } from "./prune.js"; import { syncBlocks } from "./sync.js"; +import { findOffBranchBlocks } from "./branch-awareness.js"; import { advanceSurvival, activeBlocks, blockById } from "./state.js"; import { allocateBlockId, allocateRunId, createInitialState } from "./state.js"; import { countMessageTokens, defaultCountTokens } from "./tokenize.js"; @@ -107,6 +108,17 @@ export interface ProcessTurnInput { /** Per-session CCR content store (pass result.contentStore back here). * Omit for pre-CCR sessions — an empty store is used. */ contentStore?: MessageContentStore; + /** Opt-in branch awareness: the ids of all session entries the host has + * persisted (the full session tree, not just the current branch). When + * provided, blocks whose covered messages are partly in view and partly + * persisted-but-elsewhere (a rewind into a block's range, e.g. pi's + * `/tree`) are masked as expanded for this turn — their in-view messages + * show raw instead of being replaced by a summary that describes the + * other branch. The mask is not persisted: the result state keeps the + * original `expanded` flags, so returning to the full branch reactivates + * the block. Omit for hosts without rewindable session trees — zero + * behaviour change. */ + persistedMessageIds?: ReadonlySet; } export interface ApplyCompressionInput { @@ -711,6 +723,22 @@ export function createCore(ports: Ports = {}): CompressionCore { state: input.state, effects: {}, }; + // Branch-aware masking (opt-in): force off-branch blocks expanded so + // syncBlocks keeps their in-view messages raw this turn. The mask is + // never persisted — the original expanded flags are restored on the + // result state below. + const offBranch = input.persistedMessageIds + ? findOffBranchBlocks(input.messages, input.state, input.persistedMessageIds) + : []; + if (offBranch.length > 0) { + const offSet = new Set(offBranch); + initial.state = { + ...input.state, + blocks: input.state.blocks.map((b) => + offSet.has(b.blockId) && !b.expanded ? { ...b, expanded: true } : b, + ), + }; + } // Conversion (assign-refs) and rendering (render-refs) are separate // concerns. Refs are always assigned; renderTags only controls which // message texts receive an tag. @@ -721,7 +749,26 @@ export function createCore(ports: Ports = {}): CompressionCore { // returned state carries THIS pass's snapshot for the next one. const inboundIds = input.messages.map((m) => m.id); const result = runPipeline(nodes, initial, ctx); - const state = { ...result.state, lastPassIds: inboundIds }; + let outState = result.state; + if (offBranch.length > 0) { + // Restore the original expanded flags: the mask is turn-scoped, so a + // later turn back on the full branch reactivates the block. + const originalExpanded = new Map( + input.state.blocks + .filter((b) => offBranch.includes(b.blockId)) + .map((b) => [b.blockId, b.expanded as boolean | undefined]), + ); + outState = { + ...outState, + blocks: outState.blocks.map((b) => { + if (!originalExpanded.has(b.blockId)) return b; + const { expanded: _masked, ...rest } = b; + const orig = originalExpanded.get(b.blockId); + return orig === undefined ? rest : { ...rest, expanded: orig }; + }), + }; + } + const state = { ...outState, lastPassIds: inboundIds }; const ccrEffect = result.effects.ccr as CcrEffect | undefined; return { messages: result.messages, diff --git a/tests/branch-awareness.test.ts b/tests/branch-awareness.test.ts new file mode 100644 index 0000000..1d23c83 --- /dev/null +++ b/tests/branch-awareness.test.ts @@ -0,0 +1,101 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { + createCore, + createInitialState, + defaultConfig, + defaultCountTokens, + type CoreMessage, +} from "../src/index.js"; +import { findOffBranchBlocks } from "../src/branch-awareness.js"; + +// Branch-aware masking (ProcessTurnInput.persistedMessageIds): after a +// rewind into a block's range (pi `/tree`), the block's summary — which +// describes messages now on another branch — must not stand in for the few +// messages still in view. + +const L = 200_000; +const FUTURE = "FUTURE-DECISION: switch to SiUD412ED (made after the rewind point)"; +const filler = (tag: string) => `${tag} ` + "lorem ipsum dolor sit amet ".repeat(60); + +function u(id: string, text: string): CoreMessage { + return { id, role: "user", contentType: "text", text } as CoreMessage; +} +function a(id: string, text: string): CoreMessage { + return { id, role: "assistant", contentType: "text", text } as CoreMessage; +} + +/** Compress e1..e4 into one block whose summary leaks a "future" decision. */ +function compressedState() { + const core = createCore({ countTokens: defaultCountTokens }); + const config = defaultConfig(L); + const full = [ + u("e1", filler("q1")), a("e2", filler("a1")), u("e3", filler("q2")), a("e4", filler("a2")), + u("e5", "tail-1"), a("e6", "tail-2"), u("e7", "tail-3"), a("e8", "tail-4"), u("e9", "tail-5"), a("e10", "tail-6"), + ]; + const turn = core.processTurn({ messages: full, state: createInitialState(), config, tokenCount: 5_000 }); + const ref = (id: string) => turn.state.messageRefs.byRaw[id]!; + const applied = core.applyCompression({ + ranges: [{ startRef: ref("e1"), endRef: ref("e4"), summary: `Block summary. ${FUTURE}. Padding to clear the minimum summary length.` }], + messages: turn.messages, + state: turn.state, + config, + protectedMessageIds: new Set(), + }); + assert.equal(applied.result.blocksCreated, 1, JSON.stringify(applied.result.errors)); + return { core, config, state: applied.state, allIds: new Set(full.map((m) => m.id)) }; +} + +const textOf = (messages: CoreMessage[]) => + messages.map((m) => String((m as { text?: unknown }).text ?? "")).join("\n"); + +test("a block partly on another branch is masked; its in-view messages show raw", () => { + const { core, config, state, allIds } = compressedState(); + // Rewound to e2: e3/e4 (and the tail) are persisted but on another branch. + const view = [u("e1", filler("q1")), a("e2", filler("a1")), u("e11", "new question on the new branch")]; + assert.deepEqual(findOffBranchBlocks(view, state, allIds), [state.blocks[0]!.blockId]); + + // Opt-out host (field omitted): the summary (with the future decision) + // replaces e1/e2 — unchanged baseline behaviour. + const plain = core.processTurn({ messages: view, state, config, tokenCount: 5_000 }); + assert.match(textOf(plain.messages), /FUTURE-DECISION/, "baseline: kernel leaks the future summary"); + + // Opt-in host: the block is masked for the turn; e1/e2 show raw. + const guarded = core.processTurn({ messages: view, state, config, tokenCount: 5_000, persistedMessageIds: allIds }); + const text = textOf(guarded.messages); + assert.doesNotMatch(text, /FUTURE-DECISION/); + assert.match(text, /^q1 lorem/m, "e1 is shown raw"); + assert.equal(guarded.state.blocks[0]!.active, false); + assert.equal(guarded.state.blocks[0]!.expanded, undefined, "the mask is not persisted"); + // The input state was not mutated by the masking. + assert.equal(state.blocks[0]!.expanded, undefined); +}); + +test("back on the full branch the block stays active", () => { + const { core, config, state, allIds } = compressedState(); + const full = [u("e1", ""), a("e2", ""), u("e3", ""), a("e4", ""), u("e5", "tail-1")]; + assert.deepEqual(findOffBranchBlocks(full, state, allIds), []); + const turn = core.processTurn({ messages: full, state, config, tokenCount: 5_000, persistedMessageIds: allIds }); + assert.equal(turn.state.blocks[0]!.active, true); +}); + +test("ids missing but never persisted keep the kernel's default behaviour", () => { + const { core, config, state } = compressedState(); + // e3/e4 absent from the view but unknown to the persisted set: that is a + // live-id situation, not a branch rewind — the summary stays in charge. + const view = [u("e1", ""), a("e2", "")]; + const turn = core.processTurn({ + messages: view, + state, + config, + tokenCount: 5_000, + persistedMessageIds: new Set(["e1", "e2"]), + }); + assert.match(textOf(turn.messages), /FUTURE-DECISION/); +}); + +test("live-instance subids share the base id for both view and persisted matching", () => { + const { state } = compressedState(); + const view = [u("e1#l1", filler("q1")), a("e2#l1", filler("a1")), u("e11", "new")]; + assert.deepEqual(findOffBranchBlocks(view, state, new Set(["e1", "e2", "e3", "e4"])), [state.blocks[0]!.blockId]); +}); From 9c95e7663db4ebf5869e8d9d57058461318d37cb Mon Sep 17 00:00:00 2001 From: SeniorHan Date: Sat, 24 Oct 2026 00:29:27 +0800 Subject: [PATCH 2/3] style: prettier formatting --- src/branch-awareness.ts | 3 +- src/compress.ts | 6 +- tests/branch-awareness.test.ts | 110 +++++++++++++++++++++++++++------ 3 files changed, 99 insertions(+), 20 deletions(-) diff --git a/src/branch-awareness.ts b/src/branch-awareness.ts index ba3af6c..e8a5980 100644 --- a/src/branch-awareness.ts +++ b/src/branch-awareness.ts @@ -33,7 +33,8 @@ export function findOffBranchBlocks( persistedIds: ReadonlySet, ): string[] { const present = new Set(); - for (const m of messages) if (typeof m.id === "string") present.add(baseIdOf(m.id)); + for (const m of messages) + if (typeof m.id === "string") present.add(baseIdOf(m.id)); const off: string[] = []; for (const block of state.blocks) { if (block.expanded) continue; diff --git a/src/compress.ts b/src/compress.ts index b39d0dc..fe65a6d 100644 --- a/src/compress.ts +++ b/src/compress.ts @@ -728,7 +728,11 @@ export function createCore(ports: Ports = {}): CompressionCore { // never persisted — the original expanded flags are restored on the // result state below. const offBranch = input.persistedMessageIds - ? findOffBranchBlocks(input.messages, input.state, input.persistedMessageIds) + ? findOffBranchBlocks( + input.messages, + input.state, + input.persistedMessageIds, + ) : []; if (offBranch.length > 0) { const offSet = new Set(offBranch); diff --git a/tests/branch-awareness.test.ts b/tests/branch-awareness.test.ts index 1d23c83..b574818 100644 --- a/tests/branch-awareness.test.ts +++ b/tests/branch-awareness.test.ts @@ -15,8 +15,10 @@ import { findOffBranchBlocks } from "../src/branch-awareness.js"; // messages still in view. const L = 200_000; -const FUTURE = "FUTURE-DECISION: switch to SiUD412ED (made after the rewind point)"; -const filler = (tag: string) => `${tag} ` + "lorem ipsum dolor sit amet ".repeat(60); +const FUTURE = + "FUTURE-DECISION: switch to SiUD412ED (made after the rewind point)"; +const filler = (tag: string) => + `${tag} ` + "lorem ipsum dolor sit amet ".repeat(60); function u(id: string, text: string): CoreMessage { return { id, role: "user", contentType: "text", text } as CoreMessage; @@ -30,20 +32,48 @@ function compressedState() { const core = createCore({ countTokens: defaultCountTokens }); const config = defaultConfig(L); const full = [ - u("e1", filler("q1")), a("e2", filler("a1")), u("e3", filler("q2")), a("e4", filler("a2")), - u("e5", "tail-1"), a("e6", "tail-2"), u("e7", "tail-3"), a("e8", "tail-4"), u("e9", "tail-5"), a("e10", "tail-6"), + u("e1", filler("q1")), + a("e2", filler("a1")), + u("e3", filler("q2")), + a("e4", filler("a2")), + u("e5", "tail-1"), + a("e6", "tail-2"), + u("e7", "tail-3"), + a("e8", "tail-4"), + u("e9", "tail-5"), + a("e10", "tail-6"), ]; - const turn = core.processTurn({ messages: full, state: createInitialState(), config, tokenCount: 5_000 }); + const turn = core.processTurn({ + messages: full, + state: createInitialState(), + config, + tokenCount: 5_000, + }); const ref = (id: string) => turn.state.messageRefs.byRaw[id]!; const applied = core.applyCompression({ - ranges: [{ startRef: ref("e1"), endRef: ref("e4"), summary: `Block summary. ${FUTURE}. Padding to clear the minimum summary length.` }], + ranges: [ + { + startRef: ref("e1"), + endRef: ref("e4"), + summary: `Block summary. ${FUTURE}. Padding to clear the minimum summary length.`, + }, + ], messages: turn.messages, state: turn.state, config, protectedMessageIds: new Set(), }); - assert.equal(applied.result.blocksCreated, 1, JSON.stringify(applied.result.errors)); - return { core, config, state: applied.state, allIds: new Set(full.map((m) => m.id)) }; + assert.equal( + applied.result.blocksCreated, + 1, + JSON.stringify(applied.result.errors), + ); + return { + core, + config, + state: applied.state, + allIds: new Set(full.map((m) => m.id)), + }; } const textOf = (messages: CoreMessage[]) => @@ -52,30 +82,67 @@ const textOf = (messages: CoreMessage[]) => test("a block partly on another branch is masked; its in-view messages show raw", () => { const { core, config, state, allIds } = compressedState(); // Rewound to e2: e3/e4 (and the tail) are persisted but on another branch. - const view = [u("e1", filler("q1")), a("e2", filler("a1")), u("e11", "new question on the new branch")]; - assert.deepEqual(findOffBranchBlocks(view, state, allIds), [state.blocks[0]!.blockId]); + const view = [ + u("e1", filler("q1")), + a("e2", filler("a1")), + u("e11", "new question on the new branch"), + ]; + assert.deepEqual(findOffBranchBlocks(view, state, allIds), [ + state.blocks[0]!.blockId, + ]); // Opt-out host (field omitted): the summary (with the future decision) // replaces e1/e2 — unchanged baseline behaviour. - const plain = core.processTurn({ messages: view, state, config, tokenCount: 5_000 }); - assert.match(textOf(plain.messages), /FUTURE-DECISION/, "baseline: kernel leaks the future summary"); + const plain = core.processTurn({ + messages: view, + state, + config, + tokenCount: 5_000, + }); + assert.match( + textOf(plain.messages), + /FUTURE-DECISION/, + "baseline: kernel leaks the future summary", + ); // Opt-in host: the block is masked for the turn; e1/e2 show raw. - const guarded = core.processTurn({ messages: view, state, config, tokenCount: 5_000, persistedMessageIds: allIds }); + const guarded = core.processTurn({ + messages: view, + state, + config, + tokenCount: 5_000, + persistedMessageIds: allIds, + }); const text = textOf(guarded.messages); assert.doesNotMatch(text, /FUTURE-DECISION/); assert.match(text, /^q1 lorem/m, "e1 is shown raw"); assert.equal(guarded.state.blocks[0]!.active, false); - assert.equal(guarded.state.blocks[0]!.expanded, undefined, "the mask is not persisted"); + assert.equal( + guarded.state.blocks[0]!.expanded, + undefined, + "the mask is not persisted", + ); // The input state was not mutated by the masking. assert.equal(state.blocks[0]!.expanded, undefined); }); test("back on the full branch the block stays active", () => { const { core, config, state, allIds } = compressedState(); - const full = [u("e1", ""), a("e2", ""), u("e3", ""), a("e4", ""), u("e5", "tail-1")]; + const full = [ + u("e1", ""), + a("e2", ""), + u("e3", ""), + a("e4", ""), + u("e5", "tail-1"), + ]; assert.deepEqual(findOffBranchBlocks(full, state, allIds), []); - const turn = core.processTurn({ messages: full, state, config, tokenCount: 5_000, persistedMessageIds: allIds }); + const turn = core.processTurn({ + messages: full, + state, + config, + tokenCount: 5_000, + persistedMessageIds: allIds, + }); assert.equal(turn.state.blocks[0]!.active, true); }); @@ -96,6 +163,13 @@ test("ids missing but never persisted keep the kernel's default behaviour", () = test("live-instance subids share the base id for both view and persisted matching", () => { const { state } = compressedState(); - const view = [u("e1#l1", filler("q1")), a("e2#l1", filler("a1")), u("e11", "new")]; - assert.deepEqual(findOffBranchBlocks(view, state, new Set(["e1", "e2", "e3", "e4"])), [state.blocks[0]!.blockId]); + const view = [ + u("e1#l1", filler("q1")), + a("e2#l1", filler("a1")), + u("e11", "new"), + ]; + assert.deepEqual( + findOffBranchBlocks(view, state, new Set(["e1", "e2", "e3", "e4"])), + [state.blocks[0]!.blockId], + ); }); From 32ecaf8aa430425bc5fa74411c44b1c9605b413d Mon Sep 17 00:00:00 2001 From: ework-agent Date: Sat, 24 Oct 2026 01:03:28 +0800 Subject: [PATCH 3/3] style: share off-branch block set between mask and restore paths MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review cleanup for #518 (no behavior change): hoist the Set built from findOffBranchBlocks so the restore path reuses it instead of an O(n^2) Array.includes scan, and drop a redundant type assertion — CompressionBlock.expanded is already typed boolean | undefined. --- src/compress.ts | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/compress.ts b/src/compress.ts index fe65a6d..6eb5ceb 100644 --- a/src/compress.ts +++ b/src/compress.ts @@ -734,8 +734,8 @@ export function createCore(ports: Ports = {}): CompressionCore { input.persistedMessageIds, ) : []; - if (offBranch.length > 0) { - const offSet = new Set(offBranch); + const offSet = new Set(offBranch); + if (offSet.size > 0) { initial.state = { ...input.state, blocks: input.state.blocks.map((b) => @@ -754,13 +754,13 @@ export function createCore(ports: Ports = {}): CompressionCore { const inboundIds = input.messages.map((m) => m.id); const result = runPipeline(nodes, initial, ctx); let outState = result.state; - if (offBranch.length > 0) { + if (offSet.size > 0) { // Restore the original expanded flags: the mask is turn-scoped, so a // later turn back on the full branch reactivates the block. const originalExpanded = new Map( input.state.blocks - .filter((b) => offBranch.includes(b.blockId)) - .map((b) => [b.blockId, b.expanded as boolean | undefined]), + .filter((b) => offSet.has(b.blockId)) + .map((b): [string, boolean | undefined] => [b.blockId, b.expanded]), ); outState = { ...outState,