checkpoint: extract persistent contract to api/checkpoint

[Soph]

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

Stacked on #1495 (the persistent/ephemeral split + scope-based read/write API). Review/merge that first; this diff is against that branch. Carries the same latest-main merge as #1495.

What

The final step of the #1433 reorder: extract the persistent-checkpoint contract into a new github.com/entireio/cli/api/checkpoint package — born with the persistent vocabulary and scope-based names (the whole reason we did the rename before relocating).

Moved to api/checkpoint:

• Persisted document types: Metadata, CheckpointSummary, Summary/LearningsSummary/CodeLearning, Attribution, SessionFilePaths, SessionMetrics, CheckpointInfo, SessionContent.
• Option types: WriteOptions, UpdateOptions, PrecomputedTranscriptBlobs.
• Contract surface:
  • read tiers CheckpointReader (Read, List) + SessionReader (the four session reads), composed into PersistentStore;
  • Writer + the sealed WriteRequest union (Session / SessionTranscript / SessionSummary / CheckpointAttribution);
  • the reader helpers (ReadCheckpoint, ReadLatestSessionContent, ReadRawSessionLogForCheckpoint), the sentinel errors, and CheckpointVersionBranchV1.

The contract depends only on leaf packages (agent/types, checkpoint/id, redact, go-git plumbing) — a backend can implement it without the CLI's agent/TUI/git machinery.

Stays in cmd/entire/cli/checkpoint: GitStore + methods, Open, the Stores facade, PersistentRefs, AuthorReader, normalizeCheckpointSummary, and the entire git-only ephemeral surface.

Zero call-site churn

cmd/entire/cli/checkpoint imports the contract and re-exports every moved symbol via aliases (aliases.go):

type CheckpointSummary = apicheckpoint.CheckpointSummary
var  ErrCheckpointNotFound = apicheckpoint.ErrCheckpointNotFound
func ReadCheckpoint(...) (...) { return apicheckpoint.ReadCheckpoint(...) }

All existing importers compile unchanged; the backend imports api/checkpoint directly. (Helpers are thin wrapper funcs, not mutable vars — addressing the earlier review note.)

Cleanup (post-review /simplify pass)

• Extracted a shared getSessionTree helper: the four SessionReader methods each repeated the same context-check → fetching-tree → checkpoint-tree → session-subtree navigation (with identical ErrCheckpointNotFound wrapping) before reading their files. Behavior unchanged.

Notes

• PrecomputedTranscriptBlobs.isUsable → exported IsUsable (its one caller is now across the package boundary).
• The Write union is sealed to api/checkpoint, so the impl-package unknown-request test was dropped (no longer expressible); per-request dispatch coverage remains.
• Doc-comment terminology aligned to "persistent" (was "committed") on the moved option types.

Verification

go build ./..., full go test ./..., and mise run lint (0 issues) green; validated with codex exec review (which confirmed errors.Is still works across the alias boundary) and a 4-agent /simplify review (reuse / simplification / efficiency / altitude).

[Copilot]

Pull request overview

Extracts the persistent-checkpoint storage contract into a new github.com/entireio/cli/api/checkpoint package so non-CLI backends can implement persistence without depending on the CLI’s git/TUI/runtime packages, while preserving existing CLI imports via re-exports.

Changes:

• Introduces api/checkpoint containing persistent metadata types, read/write interfaces, the sealed WriteRequest union, helper readers, and sentinel errors.
• Re-exports the new contract from cmd/entire/cli/checkpoint via aliases.go to avoid call-site churn.
• Updates the git-backed persistent implementation and tests to use the exported PrecomputedTranscriptBlobs.IsUsable and the updated “persistent” error message.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
cmd/entire/cli/checkpoint/persistent.go	Updates transcript replacement flow to use exported IsUsable on precomputed transcript blobs.
cmd/entire/cli/checkpoint/persistent_write.go	Removes local contract types/docs and relies on the re-exported api/checkpoint request union for write dispatch.
cmd/entire/cli/checkpoint/persistent_write_test.go	Drops now-unreachable in-package “unknown request” test and keeps per-request dispatch coverage.
cmd/entire/cli/checkpoint/persistent_reader.go	Keeps implementation-only helpers/capabilities (AuthorReader, summary normalization) after contract extraction.
cmd/entire/cli/checkpoint/persistent_reader_test.go	Updates expected error text to “read persistent checkpoint”.
cmd/entire/cli/checkpoint/checkpoint.go	Removes persistent-contract definitions from the implementation package, leaving the generic/ephemeral surface.
cmd/entire/cli/checkpoint/aliases.go	Re-exports api/checkpoint symbols (types, interfaces, helpers, sentinel errors) to preserve existing imports.
api/checkpoint/doc.go	Adds package docs explaining the extracted persistent contract and why it exists.
api/checkpoint/errors.go	Defines sentinel errors and the persistent metadata format constant in the contract package.
api/checkpoint/interfaces.go	Defines persistent reader/store interfaces, sealed write union, and helper read functions.
api/checkpoint/metadata.go	Hosts persistent metadata/options/types moved out of the CLI implementation package, including IsUsable.