Skip to content
Closed
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
14 changes: 14 additions & 0 deletions FORK-NOTES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# 引擎治理备忘(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 程序。

P2.7 终审(2026-10-23):CCR 取消立项。实测全工具族均已有超大输出保护:keel-bash(fullOutputPath 截断+文件指针)、pi 内置 read/grep(有保护)、MCP(script-mode 与原生均有保护)。无缺口,CCR 收益为零,且与各工具自责机制双头管理。
52 changes: 52 additions & 0 deletions src/branch-awareness.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
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>,
): string[] {
const present = new Set<string>();
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;
}
53 changes: 52 additions & 1 deletion src/compress.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -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<string>;
}

export interface ApplyCompressionInput {
Expand Down Expand Up @@ -711,6 +723,26 @@ 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 <acp> tag.
Expand All @@ -721,7 +753,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,
Expand Down
175 changes: 175 additions & 0 deletions tests/branch-awareness.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,175 @@
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],
);
});
Loading