Skip to content
Merged
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
143 changes: 132 additions & 11 deletions src/prefix-affinity.ts
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,28 @@ const MAX_TRACKED_SESSIONS = 256;
/** Chains unused for this long stop matching (sessions may outlive tracking). */
const TTL_MS = 7 * 24 * 60 * 60 * 1000;

/** Tail-window reattach window (#316 / PR-B): the incoming's LEADING items
* are searched for as a contiguous run at ANY offset inside each stored
* chain's per-item hashes (the incoming head is the retained suffix of the
* stored history, but a rolling-window client may retain any number of
* items, so the match offset must be free — not pinned to the stored tail). */
const TAIL_WINDOW = 8;

/** Minimum window size (items) for a tail-window reattach to be trusted. A
* 1-2 item window is too weak a signal (a single shared message is common);
* below this the request falls through to a new session as before. */
const MIN_TAIL_MATCH = 3;

/** Per tracked chain, store at most this many per-item hashes (the trailing
* ones). Bounds memory (256 chains × 128 × 64B ≈ 2MB) and keeps the tail
* window (8) comfortably available. Chains deeper than this lose their head,
* so fork-lineage prefix detection is best-effort for very long chains. */
const MAX_STORED_ITEMS = 128;

/** Minimum shared prefix (items) to record a "forked" lineage on a new
* session. UI/debug only — never used for matching. */
const MIN_FORK_PREFIX = 3;

export interface AnonymousAffinity {
/** Stable session id: "pfa-" + short hash of (tail, depth). */
sessionId: string;
Expand All @@ -56,13 +78,26 @@ export interface AnonymousAffinity {
incomingDepth: number;
/** Chain hash of the incoming tail (log correlation). */
tailHash: string;
/** How the session was resolved: a full-prefix match, a tail-window
* reattach (truncated replay), or a brand-new session. */
via: "prefix" | "tail-window" | "new";
/** Per-item hashes of the incoming (trailing, capped at MAX_STORED_ITEMS) —
* passed to note() so the tracked chain can serve future tail-window
* reattach + fork-lineage lookups. */
itemHashes: string[];
/** Lineage for a NEW session: the discarded match candidates and why they
* were abandoned. Recorded for UI/debug only — NEVER used for matching. */
lineage?: { parents: string[]; reason: "truncated" | "forked"; sharedPrefix?: number };
}

interface ChainEntry {
sessionId: string;
depth: number;
tailHash: string;
lastSeen: number;
/** Per-item hashes (position-independent sha256 of each canonical
* message), trailing, capped at MAX_STORED_ITEMS. */
itemHashes: string[];
}

/** Deterministic JSON with recursively sorted object keys, so two replays
Expand Down Expand Up @@ -104,6 +139,22 @@ function chainHashes(messages: unknown[]): string[] {
return bytes >= MIN_CANONICAL_BYTES ? hashes : [];
}

/** Position-INDEPENDENT per-item hashes: itemHashes[i] = sha256(canonical(msg_i)).
* Unlike the progressive chainHashes (which depend on the full prefix and so
* cannot match across a truncation), these let a window of the incoming head
* be compared against a window of a stored tail item-for-item. */
function perItemHashes(messages: unknown[]): string[] {
return messages.map((m) => sha256(stableStringify(m)));
}

/** Length of the longest common prefix of two per-item hash arrays. */
function lcpLength(a: string[], b: string[]): number {
const n = Math.min(a.length, b.length);
let i = 0;
while (i < n && a[i] === b[i]) i++;
return i;
}

export class PrefixAffinityResolver {
private trackedChains = new Map<string, ChainEntry>();

Expand All @@ -115,40 +166,110 @@ export class PrefixAffinityResolver {
resolve(messages: unknown[]): AnonymousAffinity | null {
const hashes = chainHashes(messages);
if (hashes.length === 0 || !hasUserMessage(messages)) return null;
const tailHash = hashes[hashes.length - 1]!;
const incomingDepth = hashes.length;
const tailHash = hashes[incomingDepth - 1]!;
const incItemHashes = perItemHashes(messages);
const storedItemHashes = incItemHashes.slice(-MAX_STORED_ITEMS);
const tracked = this.trackedChains;
this.expire(tracked);

// 1. Full-depth prefix match (the original radix-style resolution).
let best: ChainEntry | undefined;
for (const entry of tracked.values()) {
if (entry.depth > hashes.length) continue;
if (entry.depth > incomingDepth) continue;
if (hashes[entry.depth - 1] !== entry.tailHash) continue;
if (!best || entry.depth > best.depth || (entry.depth === best.depth && entry.lastSeen > best.lastSeen)) best = entry;
}

if (best) {
return {
sessionId: best.sessionId,
matchedDepth: best.depth,
storedDepth: best.depth,
incomingDepth: hashes.length,
incomingDepth,
tailHash,
via: "prefix",
itemHashes: storedItemHashes,
};
}

// 2. Tail-window reattach (#316 / PR-B): a client that dropped its
// oldest messages replays a retained suffix of the stored history
// (plus new appends), so the incoming's LEADING items must appear
// as a contiguous run somewhere inside the stored chain's item
// hashes — at any offset, not just the stored tail (a rolling-window
// client may retain more items than TAIL_WINDOW).
const w = Math.min(TAIL_WINDOW, incomingDepth);
const candidates: ChainEntry[] = [];
if (w >= MIN_TAIL_MATCH) {
for (const entry of tracked.values()) {
const stored = entry.itemHashes;
for (let j = 0; j + w <= stored.length; j++) {
let match = true;
for (let i = 0; i < w; i++) {
if (incItemHashes[i] !== stored[j + i]) {
match = false;
break;
}
}
if (match) {
candidates.push(entry);
break;
}
}
}
}
if (candidates.length === 1) {
const entry = candidates[0]!;
const w = Math.min(TAIL_WINDOW, incomingDepth, entry.depth);
return {
sessionId: entry.sessionId,
matchedDepth: w,
storedDepth: entry.depth,
incomingDepth,
tailHash,
via: "tail-window",
itemHashes: storedItemHashes,
};
}

// No stored chain is a prefix of the incoming history: this request
// starts a session, anchored deterministically on its current tail so
// an identical replay after a proxy restart reattaches the same id.
const sessionId = `pfa-${sha256(`${tailHash}\u0000${hashes.length}`).slice(0, 16)}`;
return { sessionId, matchedDepth: 0, storedDepth: 0, incomingDepth: hashes.length, tailHash };
// 3. New session, anchored deterministically on its current tail so an
// identical replay after a proxy restart reattaches the same id.
// Record lineage (UI/debug only) for the discarded candidates.
let lineage: AnonymousAffinity["lineage"];
if (candidates.length > 1) {
lineage = { parents: candidates.map((c) => c.sessionId), reason: "truncated" };
} else {
let forkParent: ChainEntry | undefined;
let forkLcp = 0;
for (const entry of tracked.values()) {
if (entry.depth > MAX_STORED_ITEMS) continue;
const lcp = lcpLength(incItemHashes, entry.itemHashes);
if (lcp >= MIN_FORK_PREFIX && lcp > forkLcp) {
forkLcp = lcp;
forkParent = entry;
}
}
if (forkParent) lineage = { parents: [forkParent.sessionId], reason: "forked", sharedPrefix: forkLcp };
}
const sessionId = `pfa-${sha256(`${tailHash}\u0000${incomingDepth}`).slice(0, 16)}`;
return {
sessionId,
matchedDepth: 0,
storedDepth: 0,
incomingDepth,
tailHash,
via: "new",
itemHashes: storedItemHashes,
...(lineage ? { lineage } : {}),
};
}

/** Record the chain of a session (on creation and after every anonymous
* request — the incoming history is the truth, appends extend it). */
note(sessionId: string, depth: number, tailHash: string): void {
note(sessionId: string, depth: number, tailHash: string, itemHashes: string[]): void {
const tracked = this.trackedChains;
tracked.delete(sessionId);
tracked.set(sessionId, { sessionId, depth, tailHash, lastSeen: Date.now() });
tracked.set(sessionId, { sessionId, depth, tailHash, itemHashes, lastSeen: Date.now() });
while (tracked.size > MAX_TRACKED_SESSIONS) {
const oldest = [...tracked.values()].sort((a, b) => a.lastSeen - b.lastSeen)[0];
if (!oldest) break;
Expand Down
14 changes: 10 additions & 4 deletions src/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -900,12 +900,16 @@ async function handle(
: { error: { type: "invalid_request_error", message: NO_IDENTITY_MESSAGE } }));
return;
}
if (anonAffinity.matchedDepth > 0) {
if (anonAffinity.via === "tail-window") {
log("info", `[prefix-affinity] anonymous ${protocol} request → session ${anonAffinity.sessionId} (tail-window reattach window=${anonAffinity.matchedDepth}/${anonAffinity.incomingDepth}, tail=${anonAffinity.tailHash.slice(0, 8)}; truncated replay reattached, kernel reconciles by message id)`);
loggerLog("info", `[prefix-affinity] session ${anonAffinity.sessionId} reattached via tail-window (window ${anonAffinity.matchedDepth}/${anonAffinity.incomingDepth}, tail=${anonAffinity.tailHash.slice(0, 8)})`);
} else if (anonAffinity.matchedDepth > 0) {
log("info", `[prefix-affinity] anonymous ${protocol} request → session ${anonAffinity.sessionId} (prefix match depth=${anonAffinity.matchedDepth}/${anonAffinity.incomingDepth}, tail=${anonAffinity.tailHash.slice(0, 8)}; fork semantics: diverged histories split on their next request)`);
loggerLog("info", `[prefix-affinity] session ${anonAffinity.sessionId} matched at depth ${anonAffinity.matchedDepth}/${anonAffinity.incomingDepth} (tail=${anonAffinity.tailHash.slice(0, 8)})`);
} else {
log("info", `[prefix-affinity] new anonymous session ${anonAffinity.sessionId} (depth=${anonAffinity.incomingDepth}, tail=${anonAffinity.tailHash.slice(0, 8)})`);
loggerLog("info", `[prefix-affinity] new session ${anonAffinity.sessionId} at depth ${anonAffinity.incomingDepth} (tail=${anonAffinity.tailHash.slice(0, 8)})`);
const lineage = anonAffinity.lineage ? `; lineage=${anonAffinity.lineage.reason} of ${anonAffinity.lineage.parents.join(",")}` : "";
log("info", `[prefix-affinity] new anonymous session ${anonAffinity.sessionId} (depth=${anonAffinity.incomingDepth}, tail=${anonAffinity.tailHash.slice(0, 8)}${lineage})`);
loggerLog("info", `[prefix-affinity] new session ${anonAffinity.sessionId} at depth ${anonAffinity.incomingDepth} (tail=${anonAffinity.tailHash.slice(0, 8)}${lineage})`);
}
}
const sessionId = anonAffinity ? anonAffinity.sessionId : conversation;
Expand All @@ -929,10 +933,12 @@ async function handle(
: clientConversationHeader(req.headers);
const session = getSession(sessionId, { protocol, upstreamOrigin, label: clientLabel ?? (anonAffinity ? "prefix-affinity" : undefined) });
if (anonAffinity) {
prefixAffinity.note(sessionId, anonAffinity.incomingDepth, anonAffinity.tailHash);
prefixAffinity.note(sessionId, anonAffinity.incomingDepth, anonAffinity.tailHash, anonAffinity.itemHashes);
session.metadata.anonymousPrefixAffinity = {
depth: anonAffinity.incomingDepth,
tailHash: anonAffinity.tailHash,
via: anonAffinity.via,
...(anonAffinity.lineage ? { lineage: anonAffinity.lineage } : {}),
};
}
// Launcher-mode binding (#162): prefer identity — claude code sends
Expand Down
20 changes: 10 additions & 10 deletions tests/prefix-affinity.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ test("prefix-affinity: append-only continuation resolves to the same session", (
assert.ok(a);
assert.equal(a.matchedDepth, 0);
assert.match(a.sessionId, /^pfa-[0-9a-f]{16}$/);
r.note(a.sessionId, a.incomingDepth, a.tailHash);
r.note(a.sessionId, a.incomingDepth, a.tailHash, a.itemHashes);

const b = r.resolve([user("hello there friend"), { role: "assistant", content: "hi" }, user("second question")]);
assert.ok(b);
Expand All @@ -27,7 +27,7 @@ test("prefix-affinity: append-only continuation resolves to the same session", (
test("prefix-affinity: different conversations with distinct roots stay separate", () => {
const r = new PrefixAffinityResolver();
const a = r.resolve([user("project one setup question")]);
r.note(a!.sessionId, a!.incomingDepth, a!.tailHash);
r.note(a!.sessionId, a!.incomingDepth, a!.tailHash, a!.itemHashes);
const b = r.resolve([user("totally different topic opener")]);
assert.notEqual(b!.sessionId, a!.sessionId, "different content must not collide");
assert.equal(b!.matchedDepth, 0);
Expand All @@ -37,12 +37,12 @@ test("prefix-affinity: shared opening, divergent continuation forks on the next
const r = new PrefixAffinityResolver();
const shared = [user("same opening message with substance"), { role: "assistant", content: "ok" }];
const a = r.resolve(shared);
r.note(a!.sessionId, a!.incomingDepth, a!.tailHash);
r.note(a!.sessionId, a!.incomingDepth, a!.tailHash, a!.itemHashes);

// Branch A extends first — it keeps the session.
const aNext = r.resolve([...shared, user("branch A continuation")]);
assert.equal(aNext!.sessionId, a!.sessionId);
r.note(aNext!.sessionId, aNext!.incomingDepth, aNext!.tailHash);
r.note(aNext!.sessionId, aNext!.incomingDepth, aNext!.tailHash, aNext!.itemHashes);

// Branch B diverges: its history does not extend the stored chain (hash
// at stored depth differs), so it starts its own session.
Expand All @@ -54,7 +54,7 @@ test("prefix-affinity: shared opening, divergent continuation forks on the next
test("prefix-affinity: identical replay after restart reattaches the same deterministic id", () => {
const first = new PrefixAffinityResolver();
const a = first.resolve([user("persistent conversation anchor")]);
first.note(a!.sessionId, a!.incomingDepth, a!.tailHash);
first.note(a!.sessionId, a!.incomingDepth, a!.tailHash, a!.itemHashes);

// Fresh process: no in-memory index, same first-turn content.
const second = new PrefixAffinityResolver();
Expand All @@ -66,7 +66,7 @@ test("prefix-affinity: trimmed history no longer matches — safe new session",
const r = new PrefixAffinityResolver();
const full = [user("first message with content"), { role: "assistant", content: "r1" }, user("second message")];
const a = r.resolve(full);
r.note(a!.sessionId, a!.incomingDepth, a!.tailHash);
r.note(a!.sessionId, a!.incomingDepth, a!.tailHash, a!.itemHashes);

// Client-side microcompact drops the middle turn: the stored 3-deep chain
// is NOT a prefix of the trimmed history (it is longer).
Expand All @@ -80,7 +80,7 @@ test("prefix-affinity: no environmental partitioning — same content survives c
const r = new PrefixAffinityResolver();
const history = [user("same words across rotating credentials")];
const a = r.resolve(history);
r.note(a!.sessionId, a!.incomingDepth, a!.tailHash);
r.note(a!.sessionId, a!.incomingDepth, a!.tailHash, a!.itemHashes);
// #286 lesson: bearer rotation / relay switching / protocol translation
// happen MID-CONVERSATION. There is no partition surface at all, so the
// identical replay keeps resolving to the same session.
Expand All @@ -106,7 +106,7 @@ test("prefix-affinity: system+user openai shape (shared system must not collide)
const r = new PrefixAffinityResolver();
const sys = { role: "system", content: "You are ZCode, a shared IDE system prompt injected into every conversation." };
const a = r.resolve([sys, user("question about project A")]);
r.note(a!.sessionId, a!.incomingDepth, a!.tailHash);
r.note(a!.sessionId, a!.incomingDepth, a!.tailHash, a!.itemHashes);
const b = r.resolve([sys, user("question about project B")]);
assert.notEqual(b!.sessionId, a!.sessionId, "identical system prefix must not merge distinct conversations");
});
Expand All @@ -115,7 +115,7 @@ test("prefix-affinity: LRU cap bounds tracked sessions", () => {
const r = new PrefixAffinityResolver();
for (let i = 0; i < 262; i++) {
const a = r.resolve([user(`unique conversation number ${i} with filler content`)]);
r.note(a!.sessionId, a!.incomingDepth, a!.tailHash);
r.note(a!.sessionId, a!.incomingDepth, a!.tailHash, a!.itemHashes);
}
assert.equal(r.trackedSessionIds().length, 256);
});
Expand All @@ -130,7 +130,7 @@ test("prefix-affinity: stableStringify sorts keys recursively", () => {
test("prefix-affinity: key-order differences across replays still match", () => {
const r = new PrefixAffinityResolver();
const a = r.resolve([{ role: "user", content: "key order robustness check", meta: { x: 1, y: 2 } }]);
r.note(a!.sessionId, a!.incomingDepth, a!.tailHash);
r.note(a!.sessionId, a!.incomingDepth, a!.tailHash, a!.itemHashes);
const b = r.resolve([{ meta: { y: 2, x: 1 }, content: "key order robustness check", role: "user" }]);
assert.equal(b!.sessionId, a!.sessionId, "same logical message in different key order must match");
});
Loading
Loading