Checkpoints, Commits, and Restore

NoKV exposes two different ways to freeze workspace state. A leased snapshot is a short-lived recovery point. An immutable commit, optionally named by a durable tag, is the long-lived reuse boundary. They are not interchangeable.

Leased Snapshots

A snapshot freezes one workspace incarnation at a metadata read version and creates a HistoryHold. Its optional name is only an alias to the numeric snapshot id; naming a snapshot does not turn it into a durable tag.

Snapshots have a durable lifecycle: mint, renew, retire, and reap race through typed metadata transitions. Once reaping wins, the history hold is gone and renewal fails. A restore consuming the snapshot holds an exact consumer until publication or terminal abort releases it.

Use a snapshot for bounded operational recovery. Do not use its lease as a permanent archive contract.

Durable Commits And Tags

A commit freezes the source under a temporary history hold, constructs an ordered tree closure, and adds exact commit-owned revision references. The closure and reference seals are verified before the commit becomes Sealed, then the temporary history hold is released. Commits retain revisions rather than pinning global metadata history.

The canonical Workbench projection is published at metadata/run_manifest.json in the same final fenced command that seals the commit, updates the typed commit head, advances WorkspaceCurrent, and emits the change event. Readers observe the old manifest and head or the new pair, never a mixture.

Tags are CAS-protected names for immutable commits. Commit retirement is explicit and checks heads, tags, leases, lineage children, restore consumers, and exact revision references before releasing the sealed closure.

Restore

Restore can read either an active leased snapshot or a sealed durable commit. It is:

• same-root and same-logical-shard;
• source-preserving and destination-creating, never an in-place rollback;
• invisible until one final workspace marker command;
• zero-copy for immutable artifact revisions within that root and shard;
• idempotent through a deterministic operation identity;
• recoverable after process or owner failure.

claim destination WorkspaceCurrent(Staging) and source hold
  -> copy PathCurrent rows and add destination RevisionRefs in bounded batches
  -> seal and verify the ordered member closure
  -> atomically publish WorkspaceCurrent(Visible), event, and terminal result
  -> release the source hold or commit consumer

Staged paths already hold their revisions but remain absent from point, list, search, aggregate, catalog, snapshot, and watch results. Cleanup is driven by the durable operation member index, not a path or object listing. Publication and abort CAS the same operation phase, so only one terminal path can win.

metadata/restore_manifest.json records whether the frozen source was a snapshot id or commit id. A decision point that must outlive a snapshot lease should restore from a commit.

Failure And Replay Rules

• object upload failure never publishes metadata;
• metadata publication failure leaves operation-owned staged records for recoverable cleanup;
• exact request replay returns the stored deterministic result;
• retained revision references, not bucket listing, protect reachable bytes;
• uncertain provider deletion enters quarantine and reconciliation.

These lifecycle operations reuse the same owner-fenced metadata command and recovery path as ordinary namespace publication; they are not a second state machine.