Skip to content

Causal object retention

Jerry Holland edited this page Oct 16, 2026 · 6 revisions

Retain published causal history

New publications retain their required Git objects under refs/causet/retention (refs/vcs-lab/retention in a repository that has not run cst migrate; see ADR-0039). Notes, retention, and new resolution refs publish in one checked transaction. Branch deletion, operation abort, and Git garbage collection do not expire these objects. Retained receipts prove coverage only when their attachments are reachable from the selected target.

The lifetime policy is ADR-0025, implemented by PR #75.

Existing repositories

Run the upgraded CLI in any worktree of the repository:

  1. Inspect the existing facts with cst metadata validate --json.
  2. Preview backfill with cst metadata retain --dry-run --json. Check eligible and quarantined record counts, dependency counts, and diagnostics. Preview creates no Git objects or refs.
  3. Run cst metadata retain --apply --json. changed: true means the shared retention root moved to retain the eligible facts. All linked worktrees share this root.
  4. Repeat apply. With unchanged notes, it reports changed: false and leaves refs unchanged. Run metadata validation again to check the facts.

Quarantined records are reported, not repaired. Backfill returns exit status 1 when quarantine remains, including when it successfully retained other valid facts. Restore missing objects from a trusted existing clone, backup, or validated metadata envelope, then validate and retry. Backfill cannot reconstruct history that no longer exists anywhere.

Do not delete the retention ref to reduce storage: it is the root that protects published dependencies. Selective reclamation requires a future, separately reviewed pruning contract. Unpublished private journals and forecasts are outside this retention policy.

Transfer between clones

Use cst metadata export <directory> and cst metadata import <directory> --dry-run, followed by --apply. The envelope carries the accepted facts and their required commits, trees, and independent blobs. It constructs its own carrier instead of exporting the local retention chain. Import publishes local retention with notes and resolution refs; repeated imports are no-ops.

Since causet 0.25 (ADR-0040), cst fetch, cst pull and cst clone bring a remote's records in, and cst push publishes them before the branch: the notes, the retention root and the resolution refs, each by name, through the same validated import as an envelope. That is the supported transfer between clones of one origin.

A plain git fetch of branches transfers no causal metadata. A manual notes-only fetch can expose a valid record without the retention carrier that keeps its attachment readable. In that state, cst metadata validate reports missing-attachment even when the origin has every required object. For a low-level read from the same origin with Git alone, fetch the notes, the retention root and the resolution refs together, each by name, then validate:

git fetch origin 'refs/notes/causet:refs/notes/causet' \
  'refs/causet/retention:refs/causet/retention' \
  'refs/causet/resolutions/*:refs/causet/resolutions/*'
cst metadata validate --json

Name each one: a refs/causet/* glob would also copy the publisher's checkpoints and parked conflicts, which belong to that clone alone (#258).

The notes supply the records; the retention ref keeps their attachments and other dependencies readable, and resolution refs retain reusable result objects. Direct ref fetching does not provide the envelope's validation, conflict preview, or quarantine, so use cst fetch or export/import for supported transfers.

Back to Home

Clone this wiki locally