Decision
HarnessCheckpointV1 is an immutable envelope that records:
- a pseudonymous topology-root, canonical target identity, and platform provenance scope;
- one topology-root-relative artifact-run reference;
- bounded list/show facts;
- typed topology-root-relative artifact references and exact-byte digests;
- four semantic anchor rows with explicit availability and access; and
- a digest over the complete envelope.
Creating a checkpoint proves only that the envelope and referenced artifacts were readable, topology-root-contained, and valid at creation time. It does not prove report quality beyond the validators actually run and does not retain old artifact bytes.
Mapping from Entire CLI
| Entire CLI | Better Harness |
|---|---|
| Session | One analysis lifecycle that may publish an artifact run |
| Checkpoint | One sealed post-run state anchor |
| Ephemeral checkpoint | Existing process or caller-owned scratch; not persisted by the MVP |
| Persistent checkpoint | Local HarnessCheckpointV1 envelope under Better Harness user state |
| Summary | Bounded envelope summary read without opening run artifacts |
| Session content | Typed artifact references plus digests; bodies are not copied |
| Resume | Validated loading of an allowlisted analysis-context projection |
| Rewind/restore | Unsupported; no worktree, Git, config, or native-session mutation |
Rejected alternatives
- Clone Entire's shadow branches and Git refs. Better Harness anchors analysis evidence; it does not intercept commits or preserve code state.
- Make component snapshot the checkpoint owner. Component snapshot owns one evidence class. A checkpoint references it without absorbing its schema, diff behavior, or non-authorizing rollback contract.
- Inline every artifact body. Reports and private selection snapshots can be large or sensitive. V1 remains a bounded index.
- Call profile and snapshot digests selection resume. Reproducing the selected subset also needs the normalized plan or a private selected-id result. V1 records only the identity of the frozen population artifacts.
- Auto-create after
harness analyze. Analyze is intentionally read-only and often has no durable run directory. - Put the store in a host namespace or accept a per-command store. Host directories can dirty the worktree and turn a partial host slice into a checkpoint claim; arbitrary stores become undiscoverable. V1 uses one Better Harness state-home resolver, with a process-wide environment override for tests/admin policy, while custom run directories remain supported.