Skip to content

fix(fork-adoption): adopt CCR content-store entries for covered/cited refs (#1341) - #1361

Merged
ranxianglei merged 2 commits into
masterfrom
2026-09-26_fork-ccr-store-adoption
Sep 26, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
2026-09-26_fork-ccr-store-adoption

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What / why

Fork adoption (src/fork-adoption.ts) cloned blocks, blockContents, and messageRefs from the parent — but not the kernel CCR content store. The forked session advertised refs as retrievable (adopted block summaries cite their covered refs; v2 covered-span display + placeholder citations in the incoming view) while every acp_retrieve on them missed. Until the kernel's placeholder-as-original fix lands, the child's first fold additionally stored placeholder text as "originals", converting those honest misses into invisible fake hits (storeCoveredOriginals is wired into the shared fold path at src/stream.ts:262 on current master).

This PR adopts a ref-filtered independent clone of the parent's store, seeded by the union of:

  • (a) refs of the adopted blocks' effectiveMessageIds (looked up directly in store.byRef) — catches arrival-time-stored entries whose messages were already folded pre-fork;
  • (b) refs cited by placeholder-shaped incoming messages (marker scan; the kernel exports no citation parser).

New cloneStoreForRefs() (src/store.ts): copies exactly the named byRef entries plus their byHash payloads (dedup inherent — content-addressed), shallow-copied entry objects (no shared mutable state with the parent), returns null when nothing matches so CCR-less/empty forks create no artifact and no dirty flag. The slice flows through the existing adoptContentStore, which sets contentStoreDirty → the child persists its own companion envelope.

Behavior change (flagged)

  • Old: forked child of a CCR-armed parent started with an empty content store — acp_retrieve on adopted covered/cited refs = miss (post-first-fold: fake hit returning placeholder text, pending kernel fix).
  • New: child inherits the ref-filtered slice (covered ∪ cited); those retrieves hit with the true original text.
  • Additive log line: [fork-adoption] … adopted N CCR content-store entr(y/ies) …. No wire-shape, config-schema, or persistence-format change. Parent store read-only (append-only / first-write-wins preserved). acp-kernel pin untouched (0.0.93).

Residual (kernel-side, out of scope here): the fold-path poison guard keys on the placeholder message's own ref, so folding a view containing placeholders can still record placeholder text under that message's own child-local ref; the kernel fix remains complementary for non-fork store-loss scenarios.

Tests

New tests/fork-ccr-adoption.test.ts (5 tests), mirroring the real request pipeline (processTurn + applyRanges):

  1. cloneStoreForRefs unit: filter, hash-dedup, mutation independence, null-on-empty;
  2. fold-then-fork regression (issue acceptance criterion 1): parent stores a large result → folds it → fork; child acp_retrieve on the covered ref hits with the exact true original; edited-tail ref deliberately NOT carried;
  3. placeholder-cited fork (union part b): cited ref lands byte-exact despite an offset child ref namespace; entry survives the child's own subsequent turn + fold (first-write-wins);
  4. restart survival: flush → exactly one .content-store.json companion → evict → reload → retrieve hits again;
  5. CCR-less parent: block adoption proceeds, no store materialized, no dirty flag.

Pre-flight

  • typecheck: clean
  • full suite: 2651 pass / 0 fail (11 skipped = gated e2e)
  • build: OK (dist-import-annotations OK)
  • e2e codex: zero-token preflight passes; full run blocked environmentally (suite's local loopback upstream refused connections at the warmup phase, before any compression/fork activity) — CI's e2e job covers it against its own upstream.

Closes #1341

… refs (#1341)

Fork adoption cloned blocks/blockContents/messageRefs but not the kernel
content store, so every ref the fork advertised as retrievable (adopted
block covered refs, placeholder-cited refs) was an acp_retrieve miss - or,
until the kernel placeholder-as-original fix lands, a fake hit after the
child's first fold.

Adopt a ref-filtered independent clone of the parent store seeded by the
union of (a) adopted blocks' effectiveMessageIds refs and (b) refs cited by
placeholder-shaped incoming messages. cloneStoreForRefs returns null when
nothing matches (no artifact/dirty flag for CCR-less forks); the slice goes
through adoptContentStore so the child persists its own companion.

Tests: tests/fork-ccr-adoption.test.ts (5) covering the issue's acceptance
criteria incl. fold-then-fork true-original retrieve and restart survival.
@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-26_fork-ccr-store-adoption (3597eb3)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-1361

Each push to this PR publishes a new version under the pr-1361 npm tag.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1361.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review complete — verdict: mergeable. CI 10/10 green; local typecheck + targeted suites pass on head ca97d990.

① Direction (vs #1341): implements exactly the issue's proposed fix at the root cause — the adoption path (maybeAdoptForkBlocks) now materializes a ref-filtered independent clone of the parent's CCR content store instead of silently dropping it. Seed = union of (a) adopted blocks' effectiveMessageIds refs ∪ (b) refs cited by placeholder-shaped incoming messages, per the design settled in-thread. Not a symptom mask: without it, every covered/cited ref in a fork is an honest miss (or an invisible fake hit once the child folds, until the kernel placeholder-as-original fix lands).

② Regression review — existing behaviors on touched paths, each checked:

  • incomingCoreIds (public export): kept, semantics identical (Set of core ids through the same strip+convert pipeline). Verified by grep on base and head: only consumer is internal to fork-adoption.ts; server.ts imports/calls only maybeAdoptForkBlocks, signature and call site unchanged.
  • planForkAdoption input: same id set as before (refactor to shared incomingCoreMessages, no semantic drift).
  • Adoption trigger (first request only, SUPPORTED = openai+anthropic, prefix affinity): unchanged.
  • src/store.ts: purely additive (+19); adoptContentStore / contentStoreOf / executeRetrieve byte-identical.
  • Parent store: read-only — cloneStoreForRefs never mutates the source (shallow {...entry} copies; strings immutable). Pinned by test (JSON equality + mutation independence).
  • Wire shape / config schema / persistence format: unchanged (same MessageContentStore v1 companion envelope). package.json + lockfile untouched in diff; version (0.1.153) and acp-kernel pin (0.0.93) identical on base and head.
  • Both compression modes considered: change is proxy-mode-only (fork adoption path); plugin mode has no wire impact.
  • Flagged behavior change (per policy, disclosed in PR body ✓): old = fork child starts with an empty store → acp_retrieve on covered/cited refs misses (fake hit after first fold pre-kernel-fix); new = inherits the (covered ∪ cited) slice → hits with the true original text. Plus one additive log line. No unintended regressions found.

③ Code: cloneStoreForRefs is pure and correct (dedup inherent to content-addressing; null-on-empty ⇒ no artifact / no dirty flag for CCR-less forks). citedPlaceholderRefs marker scan is sound; namespace reasoning holds against the kernel's id-never-reused contract — seeded refs push the assignRefs cursor above the adopted ref space, and store lookup keys on the ref string directly, so the placeholder's promise wins over any child-local number collision (intentionally asserted in test 3). Verified STORED_PLACEHOLDER_MARKER exists in the installed kernel 0.0.93 typings.
Non-blocking observation: citedPlaceholderRefs captures only the FIRST #mNNNNN after a marker per message; a hypothetical multi-citation message would under-seed (= pre-PR behavior, not a regression — one tool output maps to one placeholder per core message today). Left as-is deliberately; worth a kernel-side citation parser eventually (already noted in #1341).

④ Tests: all five have teeth — removing the adopt call fails tests 2–4; shared mutable state fails 1–2; restart survival (exactly one .content-store.json) pinned by test 4; CCR-less no-op by test 5. They mirror the real pipeline (processTurn + applyRanges), not mocks. Each of the issue's five acceptance criteria is pinned by an assertion that fails if the mechanism regresses.

⑤ Diff: 3 files, +425/−16, every line on-purpose (doc updates consistent with the change). Clean.

Evidence: CI 10/10 success (test ubuntu-22/24, windows-22/24, build-artifact, version-guard, hermetic registry e2e, codex/pi zero-token e2e, CODEX_HOME overlay). Local on head: typecheck clean; fork-ccr-adoption + fork-adoption + fork-nudge-trigger + ccr-v2 + ccr-plugin + store + store-marker-gate = 44/44 pass. Full suite already green via CI.

Residual (kernel-side, correctly scoped out): the fold-path poison guard keys on the placeholder message's own ref, so folding a view containing placeholders can still record placeholder text under that child-local ref — complementary to the pending kernel fix; AC2 "no worse than today" holds.

可以合并:fork 采纳时按引用过滤克隆父级 CCR 内容存储(覆盖 ∪ 被引用),修复分叉子会话对 covered/cited refs 的 retrieve 全 miss(及内核修复前的假命中)问题;既有行为已逐项清点、无意外回归,行为变更已在 PR 中披露,CI 10/10 与本地定向验证全绿。

@ranxianglei

Copy link
Copy Markdown
Owner Author

Deep review: ✅ merge. Verified on the triple-stacked tree (#1367+#1361+#1360, all merges clean; typecheck + full suite green on the stack; this PR's 6 tests pass in isolation AND on the stack).

Design holds up. The union seed — covered refs of adopted blocks ∪ refs cited by placeholder-shaped incoming messages — is exactly the retrievability surface the fork advertises: block summaries cite covered refs, and a placeholder's citation is the only link back to an original that left the view (arrival-time storing skips placeholder text by design, so nothing else can restore it). cloneStoreForRefs is a true independent clone (entries shallow-copied, payloads shared by value — strings immutable; byHash dedup keeps one payload for refs sharing a hash), parent untouched, null on empty so a no-op adoption materializes no artifact and no dirty flag.

Points I probed specifically:

  • The cross-session ref collision case (child's own m00007 is a different message than the parent's m00007 cited by a placeholder): retrieve honors the placeholder's promise, and first-write-wins protects the adopted true original when the child's own fold later stores its own m00007 — pinned by the test asserting hash stability across the child's processTurn + applyRanges. Correct until the kernel's placeholder-as-original fix supersedes.
  • incomingCoreIds stays exported as a wrapper over the new incomingCoreMessages — no API break.
  • Ref-filtering excludes the edited-branch ref (m00008) — the child self-heals its own next turn instead of inheriting a wrong-branch original. Right call.
  • CCR-less parent / adoption-disabled: no store, no envelope, blocks behave as before — unchanged paths pinned.
  • Companion persistence + reload: child writes its OWN envelope (exactly one), survives eviction+reload with true originals. ✅

Non-blocking observation: citedPlaceholderRefs captures the first #mNNNNN after the first marker per message (indexOf + single regex exec). The kernel emits one placeholder per tool-result message today, so this is complete; if a future kernel shape ever packs multiple markers into one message, the loop would need to scan all matches. Fine to leave as-is.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Thanks for the independent deep-review pass — the triple-stack verification (#1367+#1361+#1360, clean merges, typecheck + full suite green on the stack) is exactly the extra evidence my single-branch local run couldn't provide, since it covers the hot-file interplay between these three PRs.

We also converged independently on the same non-blocking observation (citedPlaceholderRefs first-citation-only scan): agreed it's complete against today's kernel placeholder shape, so leaving it as-is — the kernel-side citation parser remains its eventual home if multi-marker messages ever appear.

Nothing further from my side — the PR is ready for you to merge whenever you like: #1361

中文:双方独立复核结论一致(可合并),且你在 #1367+#1361+#1360 三方堆叠树上验证全绿,PR 已就绪,等待你合并。

@ranxianglei
ranxianglei merged commit c1a5c60 into master Sep 26, 2026
10 checks passed
@ranxianglei
ranxianglei deleted the 2026-09-26_fork-ccr-store-adoption branch October 15, 2026 05:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bug(ccr): fork adoption carries covered refs without adopting their content-store entries

1 participant