From 15da941c1800c06a7b618681f1b7ed75ac41f451 Mon Sep 17 00:00:00 2001 From: SeniorHan Date: Fri, 23 Oct 2026 13:59:56 +0800 Subject: [PATCH 1/4] docs: engine governance memo (fork triggers T1/T2/T3) --- FORK-NOTES.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 FORK-NOTES.md diff --git a/FORK-NOTES.md b/FORK-NOTES.md new file mode 100644 index 0000000..83da1c1 --- /dev/null +++ b/FORK-NOTES.md @@ -0,0 +1,11 @@ +# 引擎治理备忘(2026-10-23) + +决策:日常依赖 npm 上游 acp-kernel,不 fork;本仓(SeniorHan/acp-kernel)是保险仓。 +基线:v0.0.101 = 4d38906,与运行时零漂移,测试基线 1233/1233。 + +三条触发器——每次升级内核版本或出现新需求时**人工对照**,不建自动监控: +- T1 停更:上游 ≥2 个月无提交 → 保险仓转正(我们接盘维护) +- T2 需求被拒:需要改内核默认行为且上游不接受(例:CCR 默认开)→ 转 fork +- T3 破坏性变更:内核仍在 0.x,minor 版本带破坏性变更 → 升级前对照变更日志评估,必要时锁版本 + +附注:CCR(ccr-store 节点,配置默认关)激活属适配层接线;若未来需要改其默认值,走 T2 程序。 From 4913fe8ee8e4a8266d58b1775c99b8089e62a649 Mon Sep 17 00:00:00 2001 From: SeniorHan Date: Fri, 23 Oct 2026 14:07:41 +0800 Subject: [PATCH 2/4] docs: P2.7 final verdict - all tool families already self-protect --- FORK-NOTES.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/FORK-NOTES.md b/FORK-NOTES.md index 83da1c1..ffe3308 100644 --- a/FORK-NOTES.md +++ b/FORK-NOTES.md @@ -9,3 +9,5 @@ - T3 破坏性变更:内核仍在 0.x,minor 版本带破坏性变更 → 升级前对照变更日志评估,必要时锁版本 附注:CCR(ccr-store 节点,配置默认关)激活属适配层接线;若未来需要改其默认值,走 T2 程序。 + +P2.7 终审(2026-10-23):CCR 取消立项。实测全工具族均已有超大输出保护:keel-bash(fullOutputPath 截断+文件指针)、pi 内置 read/grep(有保护)、MCP(script-mode 与原生均有保护)。无缺口,CCR 收益为零,且与各工具自责机制双头管理。 From 857b39fcca1b9b16874c383a1f028239ac2b73be Mon Sep 17 00:00:00 2001 From: SeniorHan Date: Fri, 23 Oct 2026 22:21:16 +0800 Subject: [PATCH 3/4] 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 24acd85901a3bc992714c44dec659d8dfb8dd66c Mon Sep 17 00:00:00 2001 From: SeniorHan Date: Sat, 24 Oct 2026 00:29:27 +0800 Subject: [PATCH 4/4] style: prettier formatting --- FORK-NOTES.md | 1 + src/branch-awareness.ts | 3 +- src/compress.ts | 6 +- tests/branch-awareness.test.ts | 110 +++++++++++++++++++++++++++------ 4 files changed, 100 insertions(+), 20 deletions(-) diff --git a/FORK-NOTES.md b/FORK-NOTES.md index ffe3308..1f283ca 100644 --- a/FORK-NOTES.md +++ b/FORK-NOTES.md @@ -4,6 +4,7 @@ 基线:v0.0.101 = 4d38906,与运行时零漂移,测试基线 1233/1233。 三条触发器——每次升级内核版本或出现新需求时**人工对照**,不建自动监控: + - T1 停更:上游 ≥2 个月无提交 → 保险仓转正(我们接盘维护) - T2 需求被拒:需要改内核默认行为且上游不接受(例:CCR 默认开)→ 转 fork - T3 破坏性变更:内核仍在 0.x,minor 版本带破坏性变更 → 升级前对照变更日志评估,必要时锁版本 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], + ); });