Repository navigation
Causal object retention
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.
Run the upgraded CLI in any worktree of the repository:
- Inspect the existing facts with
cst metadata validate --json. - 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. - Run
cst metadata retain --apply --json.changed: truemeans the shared retention root moved to retain the eligible facts. All linked worktrees share this root. - Repeat apply. With unchanged notes, it reports
changed: falseand 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.
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 --jsonName 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.