docs: record kernel id-immutability contract (ids/refs never reused)

[ranxianglei]

Closes #600 — tracking issue for this PR.

Adds a "Kernel Contract" subsection to AGENTS.md §2, paired with kernel revert ranxianglei/acp-kernel#191:

Within a session, a raw content-hash id and a ref number (mNNNNN) denote exactly one message forever — never reused, never duplicated, even after the message dies. Capacity is solved by widening the ref space, never by recycling numbers.

Records for this repo:

• Host code must not prune/repack messageRefs in ways that let a freed number be re-issued (kernel cursor = highestUsedIndex(map)+1, so a shrinking map can re-issue).
• Known residual: applyCompactionArchive (fix: archive blocks across omp native compaction instead of silently deactivating them (#395) #421) map-prune has a theoretical re-issue window — drop it once kernel ref-space widening lands.
• Do not bump acp-kernel to 0.0.48/0.0.49 (contain the reverted reclamation); resume bumping at the revert release.

Docs-only change; no code touched.

[github-actions]

📦 Built Package Artifact

Branch: 2026-09-03_agents-id-invariant (61cfa3d)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-494

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

Option B — Download artifact

1. Download the artifact from the Actions run
2. Extract the tarball and install:

tar xzf billion-context-pr494.tgz
npm install -g package

---

This comment is automatically updated on each push.

[ranxianglei]

🤖 ework agent · qwen3.8-27b

[bot] 🏷 Reviewed — all claims check out. Verdict below.

What I verified

1. Kernel cursor mechanism (the load-bearing claim) — confirmed against installed acp-kernel 0.0.47 (dist/index.js): assignRefsNode runs assignRefs(..., { existing: io.state.messageRefs, nextIndex: highestUsedIndex(io.state.messageRefs) + 1 }) every turn, and highestUsedIndex scans the current byRaw values. So the persisted nextIndex field is not a monotonic counter — the cursor is derived from the live map each turn, and any host-side shrink of byRaw/byRef can drop it and re-issue freed numbers to different-content messages. The contract as written is accurate.

2. applyCompactionArchive provenance & residual window — exists at src/session.ts:338 on base bac8d91, prunes messageRefs.byRaw/byRef to live raw ids on native-compaction boundaries, called from src/server.ts:1473 and :1640. Introduced by PR #421 (merge 1000c12, branch 2026-08-31_omp-native-compact-archive) which fixed issue #395 — so the code comment's "(#395)" (issue) and your "(#421)" (PR) are both correct under their own conventions; not an error.
The "theoretical" framing matches mechanics: re-issue needs the highest-numbered mapped message to leave the live set at prune time; native compaction keeps the newest tail resident, so the window is narrow. One minor observation (report-only, not blocking): the comment above applyCompactionArchive in src/session.ts ("nextIndex is left alone so a freed ref slot is never re-allocated") reads more confident than reality given the kernel recomputes the cursor from the map — worth a one-line comment fix whenever you touch that file.

3. No-bump guard vs 0.0.48/0.0.49 — current pin is 0.0.47 (package.json:47), guard coherent. I pulled the npm tarballs and diffed the bundles:

• 0.0.49's assignRefsNode contains the fix(compress): accept JSON-string content in parseCompressInput #176 reclamation: per-turn pruneDeadRefs(messageRefs, view ∪ active-block effectiveMessageIds) + cursor from the pruned map. Unsafe path present. ✓
• Kernel PR chore: bump acp-kernel to 0.0.34 #191 ("Revert 'fix: reclaim dead message refs…'", reverting merge 4d0b61f2) merged 2026-09-03T14:03Z; 0.0.50 published 14:06Z with assignRefsNode restored to the pre-fix(compress): accept JSON-string content in parseCompressInput #176 form (no pruneDeadRefs, no reclaim markers anywhere in the bundle). Revert is live on npm.
• So "resume bumping at the release that lands the revert" concretely means 0.0.50 as of today.

Assessment

Docs-only (+22 lines, AGENTS.md §2), CI artifact already posted, typecheck/test/build untouched by markdown. Layering judgment: this records a host-side duty (don't shrink the map in ways that lower the kernel's derived cursor) plus a dependency constraint (skip 0.0.48/0.0.49) — both correctly attributed, neither overclaiming what the kernel guarantees.

One optional nit, your call: since the revert release now exists, the final line could say "resume bumping at 0.0.50 (first post-revert release, 2026-09-03)" to make the doc self-contained without re-investigation. Leaving it version-free is also fine since the line gets deleted at bump time anyway.

LGTM. Merging stays human-side per repo rules — ready when you are: #494

[ranxianglei]

Review vs master 3cd85b6: ⚠️ correct content, but one stale paragraph must be dropped before merge.

Still accurate (verified on master):

• applyCompactionArchive byRaw/byRef prune is still present (src/session.ts:396-406, comment cites 幽灵 ref 永不回收:编号单调膨胀、逼近 99999 时 throw 并静默停摆该请求压缩;orphan-gc 失活块同样泄漏映射 #390 additive leak).
• The id-immutability contract text matches kernel 0.0.56 behavior (assignRefsNode cursor = highestUsedIndex(map)+1).

Stale and must be removed/rewritten before merging:

Do not bump acp-kernel to ≥0.0.48/0.0.49 (contain ref-slot reclamation, reverted in kernel #191); resume bumping at the release that lands the revert.

Master is on acp-kernel 0.0.56 (PR#607) — the reclamation was reverted long ago and five kernel releases have shipped since. This paragraph, if merged, would directly contradict the current pin and mislead the next kernel bump.

Suggested replacement: one line noting the ref-slot reclamation experiment was reverted in kernel #191 and the guard is historical.

(tracking: #600)