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
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,
)
: [];
const offSet = new Set(offBranch);
if (offSet.size > 0) {
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 (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) => offSet.has(b.blockId))
.map((b): [string, boolean | undefined] => [b.blockId, b.expanded]),
);
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