Remove checkpoint_version from checkpoint metadata

[pfleidi]

https://entire.io/gh/entireio/cli/trails/744

Why

The checkpoint_version stamp in each checkpoint's root metadata.json was a pure label: which storage backend serves a checkpoint is decided by the settings topology, and nothing ever dispatched on the stored value. The EnsureCanReadVersion read gates at resume/explain/rewind/export were forward-compat tripwires that could only fire for checkpoint formats that never shipped. Both are dead complexity — every reader had to thread a version through code that had exactly one possible answer.

Existing checkpoints' stored checkpoint_version values are handled by an external migration, so no backward-compat handling for the stored attribute is needed here.

What changed

Removed the read gates first (they read the field), then the field itself: WriteOptions.CheckpointVersion, CheckpointSummary.CheckpointVersion, the stamping plumbing through the write chain, the read-side backfill (normalizeCheckpointSummary), and the now-unused CheckpointVersionRefsV1 constant. Two follow-up cleanups: the hidden entire checkpoint policy help text now describes checkpoint_version as a write guard rather than a format selector, and the branch↔refs seam test regained a primary-read discriminator.

Decisions made during development

• The checkpoint policy subsystem is intentionally untouched. Its checkpoint_version field remains a checkpoint-data write guard (CanSatisfyPolicy): a repo can still block writes from CLIs that don't support the configured version. It just no longer feeds a stamp into new summaries. attach switched from the deleted checkpointVersionForNewCheckpoint to the shared ensureCheckpointPolicyAllowsCheckpointData gate that explain and import already use.
• CheckpointVersionBranchV1 stays — it anchors the policy defaults (DefaultPolicy, Normalize); only the refs-v1 constant became unused.
• The seam test needed a new probe. Dropping the version assert removed the only signal distinguishing a read served by the git-refs primary from one served by the git-branch mirror. The test now deletes the mirror's v1 branch and asserts the composed store still serves full reads — something only the primary can do.

Reviewer notes

• Existing checkpoints and existing policy refs are left as-is; the stored-field cleanup ships as an external migration.
• Commits are ordered to be reviewable independently (gates → field → help text → seam test) and can be split into a stack if preferred.

---

Note

Medium Risk
Touches resume/rewind/explain/export and checkpoint persistence; behavior change is intentional but broad across user-facing flows. Stored-field cleanup for old checkpoints is assumed to happen outside this PR.

Overview
Removes checkpoint_version from checkpoint root metadata.json and from the write path: WriteOptions, CheckpointSummary, stamping in branch/refs stores, and normalizeCheckpointSummary backfill on read. Drops CheckpointVersionRefsV1 and checkpointpolicy.EnsureCanReadVersion / IsUnsupportedVersion, so resume, rewind, explain, and export no longer fail on per-checkpoint format labels.

entire session attach now uses ensureCheckpointPolicyAllowsCheckpointData instead of checkpointVersionForNewCheckpoint (policy still gates writes via CanSatisfyPolicy, but no longer chooses a version to stamp). Manual-commit condensation stops passing CheckpointVersion into writes.

Docs and entire checkpoint policy help describe checkpoint_version as a write guard, not a metadata format selector. The branch↔refs seam test deletes the v1 mirror branch and asserts reads still work via the git-refs primary.

^{Reviewed by Cursor Bugbot for commit dca2300. Configure here.}

[Copilot]

Pull request overview

This PR removes the checkpoint_version field from checkpoint root metadata.json summaries and deletes the associated “read gate” logic that previously rejected checkpoints based on a stored per-checkpoint version. The repository-level checkpoint policy remains in place as a write guard (enforcing whether this CLI can write checkpoint data under the configured policy), but no longer drives any per-checkpoint stamping or read-time dispatch.

Changes:

• Removed read-side version gating from resume/explain/rewind/export paths (and deleted the gating implementation).
• Removed checkpoint_version from checkpoint summary/write plumbing (WriteOptions, summary stamping, legacy backfill/normalization) and dropped the now-unused refs-v1 constant.
• Updated documentation/help text to clarify checkpoint_version is a checkpoint-data write guard, and updated the refs↔branch seam test to validate primary-read behavior via mirror deletion.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docs/architecture/sessions-and-checkpoints.md	Removes checkpoint_version from root metadata example; clarifies policy semantics and removes read-gate language.
cmd/entire/cli/strategy/manual_commit_rewind.go	Removes checkpoint-version read gate during logs-only restore.
cmd/entire/cli/strategy/manual_commit_condensation.go	Stops stamping checkpoint version into written summaries.
cmd/entire/cli/rewind.go	Removes per-checkpoint version gating in rewind restore path.
cmd/entire/cli/resume.go	Removes unsupported-version branching and read gates; restores directly from stored transcript bytes.
cmd/entire/cli/resume_test.go	Deletes tests asserting unsupported per-checkpoint version handling.
cmd/entire/cli/explain.go	Removes read gate before reading checkpoint content for explain.
cmd/entire/cli/explain_test.go	Deletes unsupported checkpoint-version rejection test.
cmd/entire/cli/explain_export.go	Removes read gates for transcript/JSON export.
cmd/entire/cli/explain_export_test.go	Removes helper and tests that rewrote/stubbed unsupported checkpoint versions.
cmd/entire/cli/checkpointpolicy/version.go	Deletes the unsupported-version sentinel + EnsureCanReadVersion implementation.
cmd/entire/cli/checkpoint/refs_store.go	Removes version stamping parameter from write path into refs store.
cmd/entire/cli/checkpoint/refs_store_test.go	Removes assertion on summary checkpoint version in refs store tests.
cmd/entire/cli/checkpoint/refs_store_seam_test.go	Updates seam assertions and adds a “reads resolve from primary” probe by deleting the mirror branch.
cmd/entire/cli/checkpoint/persistent.go	Removes checkpoint-version stamping and legacy normalization/backfill in summary reads/writes.
cmd/entire/cli/checkpoint/persistent_write_test.go	Removes tests asserting written checkpoint_version behavior.
cmd/entire/cli/checkpoint/persistent_update_test.go	Removes helpers/tests that rewrote or backfilled legacy checkpoint_version.
cmd/entire/cli/checkpoint/persistent_tripwire_test.go	Updates call signature after removing checkpointVersion parameter.
cmd/entire/cli/checkpoint/persistent_reader.go	Removes normalizeCheckpointSummary (legacy checkpoint_version backfill).
cmd/entire/cli/checkpoint/aliases.go	Drops CheckpointVersionRefsV1 alias.
cmd/entire/cli/checkpoint_policy.go	Updates help text to describe checkpoint_version as a write guard.
cmd/entire/cli/checkpoint_policy_write.go	Removes helper that derived a “new checkpoint version”; relies on existing policy gate instead.
cmd/entire/cli/checkpoint_policy_test.go	Updates help-text assertion accordingly.
cmd/entire/cli/checkpoint_policy_read_test.go	Removes test that asserted read-side rejection of unsupported checkpoint versions.
cmd/entire/cli/attach.go	Switches attach flow to policy gate without selecting/stamping a checkpoint version.
api/checkpoint/metadata.go	Removes CheckpointVersion from WriteOptions and CheckpointSummary JSON schema.
api/checkpoint/errors.go	Removes CheckpointVersionRefsV1 constant.

[pfleidi]

Bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit dca2300. Configure here.}

[Copilot]

Pull request overview

Copilot reviewed 34 out of 34 changed files in this pull request and generated no new comments.