Disambiguate checkpoint basis evidence from current-buffer evidence

[flyingrobots]

Classification

Response-contract correctness and semantic clarity.

Problem

A checkpoint may lawfully name any retained rope head that belongs to the stated worldline, including a noncanonical historical head.

The native response currently combines two coordinate sets:

• basisHeadId and basisByteLength describe the retained checkpoint basis;
• the embedded BufferResponse describes the current canonical buffer snapshot, including headId, rootNodeId, byteLength, lineCount, and bufferVersion.

The TypeScript adapter then constructs textBasis from the retained basis but places the current canonical bufferVersion beside it in CreateTextBufferCheckpointResult. Nothing in the type names tells a consumer that those values may refer to different heads.

Evidence

• Checkpoint outcome extends current buffer evidence
• TypeScript mixes basis and current version into one result
• Native host reads current buffer after admitting the retained-basis checkpoint
• Basis/worldline validation permits a retained noncanonical head

Why it matters

A caller can incorrectly interpret bufferVersion as the version of textBasis.headId, which would produce a false coordinate claim. The implementation is authoritative; the response vocabulary is underspecified.

Constraints

• Do not change checkpoint identity or mint a text mutation.
• Do not require the checkpoint basis to be the canonical head.
• Do not synthesize a historical buffer version if Echo/Jim does not store one.
• Preserve opaque checkpoint, receipt, and tick identities.
• Any compatibility alias must state exactly which head it describes.

Acceptance criteria

• Choose and document explicit roles such as checkpointBasis and currentBuffer, or rename/omit fields that do not share a basis.
• Make it impossible, or at least conspicuously difficult, to pair the current canonical version with a retained historical basis accidentally.
• Add a deterministic test where the checkpoint basis is retained and noncanonical while the current buffer has a different head/version.
• Assert the declared checkpoint still names the requested retained basis.
• Assert no RopeHead, RopeRewrite, RopeDiff, root, length, line count, or version is mutated.
• Update process JSONL and TypeScript schemas together if the response shape changes.
• Preserve restart reconstruction from Echo history/WAL.

Related

• Route checkpoint declarations through Echo #282 established retained-basis checkpoint declaration.
• WF-0109: Historical Basis Preview #134 consumes historical bases and will benefit from unambiguous coordinates.

[coderabbitai]

🔗 Related PRs

#265 - CR-01: Separate checkpoints from Echo anchor authority [merged]
#268 - WF-0154 - E-Brake: Observed Absurdity Fixes (cycle) [merged]
#277 - CR-05: Render receipt-backed causal gutter evidence [merged]
#280 - Add runtime-backed causal range evidence [merged]
#282 - Route checkpoint declarations through Echo [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!