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
1 change: 0 additions & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@
| [how-it-works](how-it-works.en.svg) / [中文](how-it-works.zh-CN.svg) | One diagram: request flow + the injected context tools |
| [README](README.md) / [中文](README.zh-CN.md) / [日本語](README.ja.md) | Directory landing page: section map + the rules that keep this directory live |
| [storage-relations](storage-relations.en.svg) / [中文](storage-relations.zh.svg) | One diagram: every storage table — what it stores, when it is written/read, which feature it serves (snapshot-table foundation #5901) |

## Identity & protocol

| Doc | What it is |
Expand Down
1 change: 0 additions & 1 deletion docs/index.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@
| [how-it-works](how-it-works.zh-CN.svg) / [English](how-it-works.en.svg) | 一张图:请求流转 + 注入的上下文工具 |
| [README](README.zh-CN.md) / [English](README.md) / [日本語](README.ja.md) | 目录落地页:分区地图 + 保持本目录不再变乱的规则 |
| [storage-relations](storage-relations.zh.svg) / [English](storage-relations.en.svg) | 一张图:存储关系——每张表存什么、何时写/读、对接哪个功能(快照表底座 #5901) |

## 身份与协议

| 文档 | 说明 |
Expand Down
74 changes: 74 additions & 0 deletions pr-body-6299.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# #5874 2×2 — 2×2 snapshot egress modes (M1–M4): stage-0 world match, kernel-input assembly, delta outbound

References **#6181** (rebase → msgid+snapshot, Proposal 6).

## Stacking structure

**This PR is stacked on #5901** (base branch `2026-11-07_snapshot-table-foundation`, head `f0001977a`). The diff is exactly the 2×2 work — nothing from the foundation is duplicated here:

| commit | content |
|---|---|
| `8f4c89cda` | feat: 2×2 modes — stage-0 world match (M1), kernel-input assembly (M2), delta outbound (M3/M4) |
| `be8990d61` | fix: `ACP_KEEP_RESPONSE_ID` semantics on delta rounds (#1954 pin: id kept on delta rounds, stripped only on full re-seeds) |
| `b9b3f0e9e` | fix: review round 1 — B0 plane-protection bypass, B1 400 fault exit, B3 pure-continuation routing, B4 frontier commit at accept, M1 rollout tie, M2 R3 arbiter, M3 latch persistence |
| `2fc593afd` | fix: review round 2 — Residual 1a no-op classification, Residual 1b replay guard, Residual 2 first-chained-round frontier seed |
| `256b27b48` | fix: Residual 2 hardening — seed only for an id THIS proxy minted, persisted-frontier id mismatch forces a plain re-seed, B3 latent `resetAfterSuccess` fix |
| `5b6ac48b3` | rebase hygiene: drop the duplicate `getStore` import (already on the #5901 base) |
| `e3409963b` | fix: guard untagged saves against a live tagged plane (see below) |

Proposal 6 = foundation (#5901) + these 2×2 modes; merging this PR into #5901 delivers the complete proposal. Rebasing #5901 onto master remains the owner's call (#5901 is currently CONFLICTING on 3 doc files; the code auto-merges).

## e3409963b — the durability-persist vs tagged-plane interaction (needs owner awareness)

Re-testing on the current #5901 head (which now includes #6326 "durability-before-render") exposed a real interaction: #6326 persists the session **before** the model call so a crash can't lose the turn. That pre-render save carries no tagged plane view (the transcript at that moment is the pre-turn world). Against a session whose snapshot plane already holds the pinned-id rows (2×2 cohort traffic), that save ran the legacy final-state diff, which could not address the pinned ids and **deleted the plane rows** — the next round then had no history to serve (context loss).

The fix (`e3409963b`, 6 lines in `UnifiedStore.snapShadowSync`): an untagged save against a sid that already has active plane rows is a no-op for the plane (the disk record still lands, so #6326's crash-durability win is untouched) — the plane is only ever updated by tagged saves, which is the existing addressing doctrine (R2). Repro + pin: the p3 B4 e2e test (fails without the guard on this base, passes with it).

## What the 2×2 modes are

Four combinations of **inbound mode** (how the client sends history) and **outbound mode** (what the proxy forwards to the provider), all served from one source of truth — the snapshot table (the l1 world + the plane rows):

| | snapshot out (M1 / M2) | delta out (M3 / M4) |
|---|---|---|
| **full in** | **M1** — today's behavior: kernel re-renders the full world every round, the plane is re-served whole | **M4** — full world in, but the provider only receives the new spans (chain intact) |
| **incremental in** (msgid + seqs declared) | **M2** — the kernel input is ASSEMBLED from the plane (old rows) + new spans; byte-identical to M1's input | **M3** — both sides incremental |

The kernel is untouched (a CI guard asserts it). Inbound mode is chosen per request at stage 0 (world match: `issue` / `probe` / `echo` / `scatter` / `diverge` / `resync` / `replay`); outbound mode is chosen at the protocol rewrite for the responses lane (the only lane with provider-side retention), gated on the existing `ACP_KEEP_RESPONSE_ID`.

## Review history

### Round 1 (five Blockers + six Majors) — all fixed in `b9b3f0e9e`

- **B0** chained-turn plane collapse — a non-cohort chained turn's kernel view is a delta, not the world; flushing it destroyed plane history. Fix: `skipPlaneFlush` (one-shot, one write seam) + egress `bypass` → the plane is neither written nor served for those turns; next full turn re-syncs (one-round convergence).
- **B1** R3 identity fault must be a 400 — the lane swallow catches now rethrow `FoundationRejectError`; the server funnel maps it to `400` + `x-bili-snapshot: identity` before the generic 503 path. E2E-pinned (real 400 over HTTP, zero side effects).
- **B3** no-op chained round produced a BLIND provider response (empty input + dev message + stripped id). Fix: (a) pure-continuation rounds (chained, empty input) route to the raw-body passthrough — bytes unchanged, no kernel, no dev, no plane touch; (b) delta no-op rounds keep the id and skip the dev message (`noopServed`). Both e2e-pinned.
- **B4** the delta frontier was advanced at egress-build time with no rollback. Fix: `pendingResponsesDelta` on the prepared request; committed to the session only after the upstream accepts (status < 400), dropped on failure.
- **M1** R3 arming now rides the same rollout as the pin (`pluginLaneServerHistory`), so R3 is reachable whenever the cohort is. **M2** `checkR3Identity` is the single R3 arbiter (was dead code). **M3** the R3 latch persists (`l1_world.r3_latched_at`, upsert so it survives before the l1 row exists). **M4** the M1-vs-M2 byte pin now runs both legs through the real `openaiToCore` codec (wireIndex stripped — legitimately position-dependent). **M6** every `snapStage0Reset` also clears the delta frontier.

### Round 2 (three residuals) — fixed in `2fc593afd` + hardened in `256b27b48`

- **Residual 1a** same-body retry of an M1 round → no-op (id kept, empty input, no dev) — e2e-pinned.
- **Residual 1b** same-body retry of an M2 round would have hit `diverge` and **wiped the plane** (the retry's seqs are ≤ frontier but its id is known → headMoved). Fix: stage-0 **replay guard** — all-unknown-free incoming with all seqs at/behind the frontier is classified `echo` with `replay: true`, zero writes.
- **Residual 2** the first CHAINED round of a keepResponseId chain re-seeded the full view although the provider chain already held it (2× tokens, one-time). Fix: seed the delta frontier at the stored world when stage-0 proves a strict extension AND the chain id is **one this proxy minted** (recorded in the relay from the bytes actually forwarded — `response.created`/`response.completed` scan for streaming, `json.id` otherwise, status < 400 only). If a persisted frontier's recorded id doesn't match the incoming `previous_response_id` (fork/rewind on a stale id), the frontier is voided and the round takes the plain re-seed (id kept, full view, dev) — the status quo, which never loses. E2E-pinned including a fork round that asserts the full re-seed.

Round 2 also surfaced and fixed a latent bug the review didn't name: the pure-continuation (B3) route used the compact base which hard-codes `resetAfterSuccess: true` → the relay would mark a native compaction boundary on every B3 round and reset the session's compression state with no compaction ever happening. `pureChainContinuation` now sets `resetAfterSuccess: false`.

### Residual 3 (body note, no code)

The openai lane deliberately has **no** `skipPlaneFlush`/bypass: chat-completions providers keep no server-side history, so there is no collapse to protect against — an untagged non-cohort openai turn's kernel view IS the full client array.

## Config surface

**No new config keys.** Reused: `ACP_KEEP_RESPONSE_ID` (outbound mode for the responses lane), the existing `pluginLaneServerHistory` rollout (gates R3 arming + pin validation), the plane/e2e rollout already on the #5901 base. Two owner rulings remain (flagged since round 1): (a) whether the keepResponseId-upgrade policy (chained cohort rounds are delta by default) should be a separate key; (b) the D-lane (snapshot-render) yield policy for cohort turns.

## Acceptance evidence

Local (stack head `e3409963b`):

- `tests/issue5874-2x2-p3.test.ts` — **42/42** (verdict pairs ±6, assembly incl. M1-vs-M2 codec-level byte pin, delta seed/delta/noop/full-resend, R3 gates + latch persistence, store round trip, #1954 native, B0 flush-skip + egress bypass, B1 400 over real HTTP, B3 pure-continuation over real HTTP, B4 frontier commit incl. the 400-drop, Residual 1a/1b/2 unit + e2e incl. fork)
- regression battery: snapbase p0 10/10, snaplane p1 4/4 + p2 17/17 + fastpath 2/2, snapshot-render 13/13 + shadow-chain 6/6, storage-engine-proofs 12/12, opencode-rolling-cache-marks 10/10, responses-previous-response-id 7/7
- `tsc --noEmit` clean; unused-exports gate clean; architecture-docs guard green (`src/snapshot/stage0.ts` mapped)

CI: full run on `e3409963b` — https://github.com/ranxianglei/billion-context/actions/runs/43126815381 (dispatched; result pending). Prior full runs on the master-based equivalent: 48 success / 0 failed (43108701003).

Not done: acceptance item 10's real-client leg (a real codex CLI end-to-end) — marked out of scope for this PR, e2e coverage stands in via the fake-upstream harness.
8 changes: 8 additions & 0 deletions reference/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,14 @@ billion-context/
│ ├── session-gc.ts # Session-file GC, opt-in (sessions.gc.* / BILI_SESSION_GC*) (#1082)
│ ├── persist.ts # On-disk session persistence (kernel StateStore)
│ ├── persist-eperm.ts # EPERM/EACCES write-failure alert layer (#362)
│ ├── snapshot/ # 2×2 snapshot plane logic: stage-0 world match, assembly, delta egress (#6181)
│ │ ├── assemble.ts # Stage-0 kernel-input assembly: plane rows + new spans + anchors, envelope order (#6181)
│ │ ├── checksums.ts # Snapshot checksums (lowercase hex sha256) + canon digests (#5874)
│ │ ├── delta.ts # Outbound delta selection: seed/delta/no-op + full-resend detection (#6181)
│ │ ├── identity.ts # matchWorld verdicts (echo/probe/scatter/issue/diverge/resync) + canon parse (#5874)
│ │ ├── plane.ts # Stage-0 decision glue: R3 identity check, 400 fault breaker, lane decide (#6181)
│ │ ├── stage0.ts # Lane-agnostic stage-0 entry: pin + R3 + stage-0 decision + assembly, shared by the openai and responses lanes (#6181)
│ │ └── types.ts # Shared stage-0 types (type-only, kernel-public-types only) (#6181)
│ ├── storage/ # Unified storage layer (schema, SQLite engine ladder, backends) (#2671)
│ │ ├── backend.ts # Storage backend contract: sqlite + mysql operation seam (#3931)
│ │ ├── canonical.ts # Shared canonicalization for storage digests (#2671)
Expand Down
14 changes: 14 additions & 0 deletions src/msgid-pin.ts
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,20 @@ export function incomingMsgIdsHeader(headerValue: string | string[] | undefined)

type SeqValidation = { ok: true; seqs: number[] } | { ok: false; reason: string };

// #5874 2×2 (brief 19544722, Part A): the SEQS half of the dual-channel
// identity (biliLedgerSeqs, #4316 layer 3 transport). Lenient read like
// incomingMsgIdsOf — absent/malformed → undefined → callers take exactly
// the pre-2×2 path (the strict pin stays with validateMsgSeqs).
export function incomingSeqsOf(body: unknown): number[] | undefined {
if (typeof body !== "object" || body === null) return undefined;
const raw = (body as Record<string, unknown>)[MSG_SEQS_BODY_FIELD];
if (!Array.isArray(raw) || raw.length === 0) return undefined;
for (const v of raw) {
if (typeof v !== "number" || !Number.isSafeInteger(v) || v < 1) return undefined;
}
return raw as number[];
}

/** Strict validation for the seq stamp array: 1-based positive integers,
* exactly one per message. Non-monotonic or non-contiguous values are
* ACCEPTED on purpose — the branch pointers pick arbitrary row subsets
Expand Down
45 changes: 45 additions & 0 deletions src/persist.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2442,6 +2442,51 @@ export class SessionStore {
}
}

// #5874 2×2 stage 0 (brief 19544722): errors PROPAGATE (the lane maps the
// R3 reject to a hard 400 and any other fault to the legacy full path) —
// the egress-view swallow above must not be copied here.

/** Stage 0 (element world match) for one turn. null when the unified
* store is unavailable — the lane keeps the legacy path. */
snapStage0(sessionId: string, incoming: string[], opts?: { resync?: boolean, seqs?: number[] | null }): import("./snapshot/plane.js").Stage0Result | null {
if (!this.replicasAvailable()) return null;
return this.liveShadow().snapStage0(sessionId, incoming, opts);
}

/** The plane's ACTIVE cores, pos-ordered (the "old cores from the
* table" half of the kernel-input assembly). */
snapStage0Cores(sessionId: string): { rows: { pos: number; ids: string[]; postJson: string }[]; coverMax: Record<string, number> } | null {
if (!this.replicasAvailable()) return null;
return this.liveShadow().snapStage0Cores(sessionId);
}

/** #6181 round 2, Residual 2 hardening: the plane's max ACTIVE pos
* (-1 when empty) — see UnifiedStore.snapPlaneMaxPos. */
snapPlaneMaxPos(sessionId: string): number {
if (!this.replicasAvailable()) return -1;
return this.liveShadow().snapPlaneMaxPos(sessionId);
}

/** The stage-0 resync (R4 / table behind): reset the session plane so
* the next turn re-issues from the client's current array. */
snapStage0Reset(sessionId: string): void {
if (!this.replicasAvailable()) return;
this.liveShadow().snapStage0Reset(sessionId);
}

/** #6181 M3: whether this sid's R3 breaker latch persisted from a
* previous process (a restart must not re-arm a misbehaving host). */
snapR3Latched(sessionId: string): boolean {
if (!this.replicasAvailable()) return false;
return this.liveShadow().snapR3Latched(sessionId);
}

/** #6181 M3: persist the R3 breaker latch (best-effort). */
snapR3Latch(sessionId: string): void {
if (!this.replicasAvailable()) return;
this.liveShadow().snapR3Latch(sessionId);
}

/** #3928: physical index.db shrink after deletions (`bili sessions rm`).
* Throws on failure — the deletion itself is already committed, callers
* report the shrink as partial. Throws in legacy-only lanes — check
Expand Down
31 changes: 31 additions & 0 deletions src/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -165,6 +165,7 @@ import { artifactSeedHit, detectAcpArtifacts } from "./server/chain-artifacts.js
import { droppedOpenaiParts } from "./wire-drop-warn.js";
import { BP_MAX, ROLLOUT_FEATURES, rolloutDecisions, rolloutInstallId, warnRolloutConfigProblems } from "./rollout.js";
import { SnapshotAnchorFallbackError, WS_ANCHORED_REQ_PROP } from "./server/snapshot-render.js";
import { FoundationRejectError } from "./snapshot/plane.js";
export { forward } from "./server/relay.js";

// #1086/#1218: the per-session chain-verdict memory moved to plugin.ts
Expand Down Expand Up @@ -780,6 +781,21 @@ export async function startServer(opts: ProxyOptions): Promise<http.Server> {
// The rethrow rides ONLY the request the WS session stamped
// (WS_ANCHORED_REQ_PROP); plain-HTTP lanes keep the 503 shape.
if (err instanceof SnapshotAnchorFallbackError && (req as unknown as Record<symbol, unknown>)[WS_ANCHORED_REQ_PROP] !== undefined) throw err;
// #6181 B1/B2: an R3 identity fault (the client declared a
// snapshot envelope that fails the identity gates) is a HARD 400
// with the identity marker — NOT the generic 503, NOT a silent
// raw forward: the host must learn that the envelope is broken.
// Both lanes rethrow FoundationRejectError into this funnel; it
// throws before processTurn, so the session is untouched.
if (err instanceof FoundationRejectError) {
if (!res.headersSent) {
res.writeHead(400, { "content-type": "application/json", "x-bili-snapshot": "identity" });
res.end(JSON.stringify({ error: { message: err.message, type: "snapshot_identity_fault" } }));
} else {
res.end();
}
return;
}
const msg = String(err);
const e = err as { name?: string; message?: string };
// #411: a client cancel aborts the upstream fetch via
Expand Down Expand Up @@ -2001,6 +2017,21 @@ export type Prepared = {
responsesTextProtocol?: boolean;
resetAfterSuccess?: boolean;
responsesProjection?: ResponsesProjection;
/** #6181 B4: the delta frontier selected for THIS turn's outbound —
* COMMITTED to the session only AFTER the upstream ACCEPTS the request
* (relay.ts, first forward, status < 400). A failed/4xx forward drops
* it (null) so the next round RE-SEEDS (at-least-once: over-serving is
* safe, under-serving is the context loss). Absent (undefined) = no
* delta was selected this turn. */
pendingResponsesDelta?: { state: { frontierPos: number; servedAnchors: string[] }; kind: "full" | "noop" | "partial" } | null;
/** #6181 round 2, Residual 2 hardening: the plane max pos (post
* in-request flush) the provider chain will hold once THIS forward is
* accepted — the relay pairs it with the response id it observes on
* the outbound stream and records session.lastMintedResponse (accepted
* forwards only; a refused round mints nothing). Set by the responses
* lane on every round whose accepted forward leaves the provider
* holding the full world. */
mintFrontierPos?: number;
anthropicSystem?: AnthropicRequestBody["system"];
/** #2189: the client's billing-attribution block captured from the INBOUND
* anthropic system (pre-anchor). Preflight summary calls must carry it —
Expand Down
Loading
Loading