Skip to content

feat: CCR content-cached retrieval — content store + acp_retrieve primitive - #358

Merged
ranxianglei merged 2 commits into
masterfrom
2026-09-23_ccr-content-store
Sep 23, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
2026-09-23_ccr-content-store

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #352

来源: ranxianglei/billion-context#1097 分析 content-addressed message store + acp_retrieve(built-in CCR)时发现 — 内核侧设计请求的内核先行实现(v1 phase)。

What this adds

Kernel-side foundation for lossless tool-result offload (billion-context#1097): oversized tool results are stored verbatim in a per-session content-addressed store and replaced by a deterministic placeholder at arrival; the model retrieves originals on demand through a new kernel primitive behind acp_retrieve.

New modules

  • src/content-store.ts — MessageContentStore: per-session store, sha256 content-addressed dedup (byHash) + ref index (byRef). Per-ref append-only with first-write-wins: stored originals survive fold/edit/truncate and any later messageRefs pruning (e.g. billion-context archive compaction), which is what makes the id-never-reused contract safe. Host persists the JSON envelope {version, byHash, byRef} alongside CompressionState via its own StateStore path — kernel stays zero-I/O.
  • src/ccr.ts — placeholder contract + pipeline node + retrieval primitive:
    • Deterministic placeholder, no model call, byte-stable across turns (prefix-cache friendly):
      📦 [acp-stored #m00423 · shell output · 4,213 tok] \npm run build`+→ acp_retrieve("m00423") returns the full text`
    • ccrStoreNode (ccr-store, canonical order after prune, before filter): stores + replaces once at arrival; idempotent on re-sight (tag-tolerant marker check); skips ACP tools, its own retrieve tool, excludeTools globs, protected tools, missing/BLOCKED refs.
    • retrieveByRef / applyRetrieve → core.retrieve(store, ref): hit returns {ok:true, text, ackText, injection, entry} where injection is an ephemeral acp_retrieved_* trailing message that consumes no ref (skipped by assignRefsNode/rebuild) and never enters fold space (excluded in resolveBoundaries); hallucinated refs → not-found ack (cost: one tool call, by design).
    • noteRetrieval bumps stats.retrievalCount; status breakdown gains storedMessages/retrievals (retrieval-rate metric for the "model never retrieves" risk).
    • storeCoveredOriginals(store, messages, state, blockIds) — exported host-callable primitive so folded-range originals become retrievable after applyCompression (v2 groundwork; v1 does not auto-wire it into applyCompression).

Wiring: processTurn accepts optional input.contentStore (omitted = empty store, pre-CCR sessions unaffected) and always returns result.contentStore; RETRIEVE_TOOL(+_OPENAI/_RESPONSES) follow the absorb opt-in pattern — NOT in ACP_TOOL_NAMES/ACP_TOOLS_* arrays.

⚠️ Behavior change (disclosed per policy)

DEFAULT_ABSORB_CONFIG.minToolTokens: 1000 → 4000 (src/absorb.ts:29, mirrored in src/config.ts defaultConfig).

  • Why: raise the forced-distillation bar so lossless CCR handles large results first; less unnecessary lossy churn.
  • Regression surface: none for current users — DEFAULT_ABSORB_CONFIG.enabled remains false (absorb is off by default; only explicit opt-in configs are affected, and those can pin their own threshold). CCR itself is also disabled by default (config.ccr.enabled: false).

Contracts honored (issue checklist)

  1. Replace-once-at-arrival, byte-stable ✓ (tests assert cross-turn equality)
  2. Tool-pair integrity ✓ (only tool-result content shrinks; assistant tool_calls untouched)
  3. Ephemeral retrieve injection ✓ (no ref, outside fold space, survives prune/hide nodes)
  4. Placeholder signal ✓ (kind label, token count, command/path head ≤ maxHeadChars)
  5. id-never-reused ✓ (per-ref append-only; first-write-wins keeps arrival originals even after fold; test simulates archive-style ref-map pruning then retrieves successfully)
  6. Absorb coexistence ✓ (placeholder-marked results are excluded from absorb candidacy — ID-reference priority)

Verification

  • npm run typecheck clean · npm test 798/798 pass (32 new tests in tests/ccr.test.ts) · npm run build OK
  • New files prettier-clean; pre-existing formatting debt in other files left untouched (my hunks verified locally style-consistent)

中文摘要:实现了 issue #352 请求的内核侧 CCR 基础(内容寻址存储 + 确定性占位符 + acp_retrieve 检索原语),纯增量、默认关闭;唯一行为变更是 absorb 的 minToolTokens 从 1000 提到 4000(absorb 本身仍默认关闭,无回归)。可以合并评审。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到 PR #358(CCR content-cached retrieval)。已按 [PR] 流程处理:不重做,直接拉取分支 2026-09-23_ccr-content-store 核对代码 + 跑 typecheck/test/build + 回归审查。该分支是单 commit(48a1ea6)、基于当前 master(8ee1801)、线性无 rebase 债。完整审查结论稍后回复。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR #358 review complete — verified, regression-audited, one weak test fixed directly on the branch (pushed). Mergeable from my side.

What I did

  • Checked out 2026-09-23_ccr-content-store (48a1ea6) on master 8ee1801, ran full pre-flight: typecheck clean, full test suite green (0 fail), build OK.
  • Read all 18 changed files (+1710/−16) against the six declared contracts.

Gate 1 — diff cleanliness: PASS. Every hunk is CCR-related (3 new files + targeted edits); no off-topic, generated, or whitespace noise.

Gate 2 — regression audit (touched existing behavior → verdict):

  1. absorb.minToolTokens default 1000 → 4000 (src/absorb.ts:29, src/config.ts) — intentional, disclosed in PR body ⚠️ section; enabled stays false; pinned by the disclosure test (tests/ccr.test.ts:807). ✅ disclosed
  2. Absorb/CCR coexistence — isAbsorbCandidate now skips placeholder-marked results (ID-reference priority); tested at tests/ccr.test.ts:635. ✅ guarded
  3. Pipeline order — ccr-store sits after prune, before filter as documented; tests/pipeline.test.ts asserts the chain. ✅
  4. Legacy persisted snapshots — storedCount/retrievalCount optional; generic mergeCompressionState shallow-merge yields zeros without any persist-source change; ?? 0 guards everywhere; tests/persist.test.ts updated. ✅
  5. StatusReport.breakdown — open Record<string, number>; two additive keys only. ✅
  6. Tool registries — ACP_TOOL_NAMES unchanged; retrieve tools are opt-in exactly like absorb (tests/ccr.test.ts:848). ✅
  7. Ephemeral injections — skipped by ref assignment, excluded from fold space via isRetrievedMessage; mirrors the proven acp_summary_ exclusion path. ✅
  8. Disabled config — zero mutation (node enabled() gate + early return); pre-CCR sessions omitting input.contentStore are byte-identical. ✅
  9. PipelineContext.contentStore became required — hosts building custom pipelines through the public runPipeline get a compile-time requirement. Acceptable 0.x minor break, flagging it explicitly.

Contract checklist: replace-once byte-stability (cross-turn equality), tool-pair integrity (id/toolCallId/assistant args untouched), ephemeral injection (no ref, survives pipeline, outside fold space), placeholder wire shape (exact string match), archive resilience, absorb coexistence — all substantively tested, not just named.

Fixed directly on the branch (commit 2bd7eeb, pushed): the "archive resilience" test claimed to simulate host-side ref-map pruning but never actually pruned anything — it retrieved straight after one processTurn. It now empties messageRefs before retrieving and asserts the ref lookup is gone while retrieval still returns the original bytes, matching what the PR description claims. Pre-flight re-run green.

Nits (flagged, non-blocking):

  • storeCoveredOriginals (v2 groundwork, not wired into applyCompression yet) labels non-tool messages kind "tool result" via classifyKind(undefined) — cosmetic header mislabel for user/assistant text once v2 lands; worth deciding intentionally then.
  • README's "(nudge channel)" parenthetical is slightly off — the nudge is a separate result field, not a message.
  • Repeated acp_retrieve of the same ref across turns yields two injections sharing one id (acp_retrieved_<ref>); harmless today (structurally ignored everywhere) but worth a sentence in the v2 design notes.
  • Pre-existing doc staleness: README/DESIGN canonical order still lists merge-blocks, removed long ago — not introduced here.

Verdict: the design fits the architecture — content-addressed store decoupled from the ref map is the right call for archive resilience, and ephemeral injections reuse the established exclusion machinery rather than inventing a parallel one. One weak test fixed and pushed; everything else verified as described. Mergeable (merging itself is yours, per house rules).

中文摘要:修复了 archive-resilience 测试名不副实的问题(测试声称模拟了 ref-map 剪枝但实际未剪枝,已补上真实的剪枝断言并推送为 2bd7eeb),其余六项契约与全部回归面核查通过、无意外行为漂移,可以合并。

ework-agent added 2 commits September 23, 2026 17:03
…mitive

Issue #352 (from billion-context#1097): kernel-side foundation for
lossless tool-result offload. Oversized tool results are stored verbatim
in a per-session content-addressed store and replaced by a deterministic
placeholder at arrival; the model retrieves originals on demand via a
new kernel primitive behind acp_retrieve.

New modules:
- src/content-store.ts: MessageContentStore — per-session, content-addressed
  (sha256) dedup store; per-ref append-only (first write wins), so stored
  originals survive fold/edit/truncate and messageRefs pruning (the
  id-never-reused contract). Host-persisted JSON ({version,byHash,byRef}).
- src/ccr.ts: placeholder contract (deterministic, no model call,
  byte-stable), storeLargeResults pipeline node (ccr-store, after prune),
  retrieveByRef / applyRetrieve (ephemeral acp_retrieved_* injection that
  consumes no ref and never enters fold space), noteRetrieval stats,
  storeCoveredOriginals host-callable primitive for folded ranges.

Wiring: processTurn accepts optional input.contentStore and always returns
result.contentStore; CompressionCore.retrieve(store, ref); status breakdown
gains storedMessages/retrievals; RETRIEVE_TOOL 3 wire shapes (opt-in, same
pattern as absorb — not in ACP_TOOL_NAMES).

Behavior change (disclosed): DEFAULT_ABSORB_CONFIG.minToolTokens raised
1000 -> 4000 (src/absorb.ts, src/config.ts). absorb stays disabled by
default (enabled: false), so no regression for current users; the raise
hands large-result handling to lossless CCR first. CCR itself is also
disabled by default (config.ccr.enabled).

Tests: tests/ccr.test.ts (32 tests) covering store primitives, placeholder
contract/determinism, threshold/exclusion/idempotency rules, ref-safety vs
archive pruning, ephemeral injection, fold-space exclusion, stats/status,
config validation, tool wire shapes. Full suite 798/798.
@ranxianglei
ranxianglei force-pushed the 2026-09-23_ccr-content-store branch from 2bd7eeb to 4dd2c97 Compare September 23, 2026 09:03
@ranxianglei

Copy link
Copy Markdown
Owner Author

Rebased onto current master (v0.0.83 + #359 crush gate + #363 image-compress). All 16 conflict hunks resolved as a union — CCR coexists with crush and imageCompression:

  • src/config.ts / src/types.ts: crush + imageCompression + ccr all present in defaults, merge, validation, stats counters, and KernelConfig
  • src/compress.ts: pipeline order assign-refs → sync-blocks → prune → ccr-store → absorb-hide → crush → absorb-prompt → filter → …; contentStore echo + crush effects both returned
  • src/compress-tools.ts: both IMAGE_FULL_* and RETRIEVE_* tool-def families kept
  • src/absorb.ts: ccr placeholder check + full protected.js imports
  • tests: initial-stats assertions extended with storedCount/retrievalCount

Pre-flight on the rebased head: typecheck ✅ / 984 tests pass ✅ / build ✅

@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-23_ccr-content-store (4dd2c97)

Option A — Install from npm PR tag (recommended)

In your adapter project:

npm install acp-kernel@pr-358

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

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf acp-kernel-pr358.tgz
npm install ./package

This comment is automatically updated on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Rebase verified — independent pre-flight on the new head is green, and I audited every union-resolved hunk against master. No lost behavior found.

Base check

Independent pre-flight on rebased head: typecheck clean · 984/984 tests pass, 0 fail · build OK. Matches your numbers exactly.

Union hunk audit (file by file):

  1. src/compress.ts — pipeline order is exactly as declared: assign-refs → sync-blocks → prune → ccr-store → absorb-hide → crush → absorb-prompt → …; contentStore: ccrEffect?.store ?? input echo added; crush's reporting path (master) untouched — it writes state.stats.crushCount/crushDistilledCount, so nothing was dropped in the union; retrieve() primitive and status breakdown keys additive-only.
  2. src/config.ts / src/types.ts — crush + imageCompression + ccr all present in defaults, merge (ccr follows the same overrides ? {...base, ...overrides} : base pattern as imageCompression), validation, stats counters, and Config. Stats additions optional → legacy snapshots safe; createInitialState seeds both the image counters (master) and storedCount/retrievalCount.
  3. src/compress-tools.ts — both IMAGE_FULL_* and RETRIEVE_* families present; ACP_TOOL_NAMES doc updated to cover both opt-in tools.
  4. src/absorb.ts — placeholder guard + master's protected.js imports intact; minToolTokens 1000→4000 disclosure comment kept at both sites.
  5. src/boundaries.ts / src/rebuild.ts / src/pipeline.ts / src/index.ts — fold-space exclusion covers both summary and retrieval messages; rebuild skips retrieved ids; PipelineContext.contentStore required; exports union complete.
  6. Tests — tests/image-compress.test.ts initial-state assertion extended with the two CCR counters (this was the cross-feature hunk); tests/persist.test.ts asserts legacy-snapshot merge yields zeros; tests/pipeline.test.ts canonical-order assertion includes ccr-store in position.

Coexistence safety (the part that actually matters): verified structurally — ccr-store runs before crush, and crush has a size gate at src/crush.ts:1755 (rawTokens < absorb.minToolTokens → skip). A stored result becomes a ~40-token placeholder before crush sees it, so it can never get crushed/distilled; results CCR excludes (excludeTools/protected/below-threshold) still flow to crush as before. The two features compose cleanly with no double-processing path.

One observation (non-blocking): there's no explicit test for both ccr and crush+absorb enabled in one turn — the guarantee above is structural (order + size gate), not pinned by a test. A small coexistence test would lock it down; happy to add one if you want it in this PR, or leave it as follow-up.

中文摘要:独立复验了 rebase 后的新头(4dd2c97,直接基于 master 58e4fe0),typecheck/984 测试/build 全绿,逐文件核对了全部 union 冲突块未发现丢失 crush 或 image-compress 的行为,CCR 与 crush 的共存顺序和大小门限也确认无双重处理路径,rebase 验证通过、可以合并。

@ranxianglei
ranxianglei merged commit 6bb38a8 into master Sep 23, 2026
4 checks passed
@ranxianglei ranxianglei mentioned this pull request Sep 23, 2026
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.

Content-addressed message store + on-demand retrieval (acp_retrieve) — CCR foundation (from billion-context#1097)

1 participant