Skip to content

document the kernel id-immutability contract in AGENTS.md #600

Closed

Description

@ranxianglei

Problem

The kernel guarantees that a raw content-hash id and a ref number (mNNNNN) denote exactly one message forever — never reused, never duplicated. billion-context relies on this (decompress misattribution otherwise), and host code must not prune/repack session.state.messageRefs in ways that let a freed number be re-issued (kernel assignRefsNode computes its cursor as highestUsedIndex(map)+1).

This contract is documented nowhere in this repo. Known residual risk: applyCompactionArchive prunes byRaw/byRef to live raw ids on native-compaction boundaries (src/session.ts).

Suggested fix

Record the contract as an AGENTS.md section. PR #494 carries the text (+22) but needs an edit before merge: it still says "do not bump acp-kernel to ≥0.0.48/0.0.49 (ref-slot reclamation, reverted in kernel #191)" — that hold expired; master is on 0.0.54 and the revert landed. Keep the id-immutability contract + the map-prune residual note, drop the version hold.

Activity

  1. ranxianglei commented on Sep 7, 2026

    @ranxianglei
    OwnerAuthor

    Follow-up: #494 merged with the stale "do not bump kernel >=0.0.48" paragraph intact while master pins 0.0.56 — fix up as PR (link below). This issue stays open for the contract itself.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions