git-subtree-dir: vendor/dumas_h3_continuum git-subtree-split: d07ed31b442d283d6a1740f875a843b9feda4c91
70 lines
2.8 KiB
Markdown
70 lines
2.8 KiB
Markdown
# Branch Provenance Contract v1
|
|
|
|
Status: V3.8 N2b implementation contract.
|
|
|
|
## Purpose
|
|
|
|
Branch Provenance records which immutable physical-group revision is active at
|
|
each point in a Run Storage chain. It allows a user to select an older Take and
|
|
generate only the physical groups after that Take without deleting the former
|
|
branch or confusing equal nonces with equal ancestry.
|
|
|
|
Take labels are presentation only. Internal identity is always `revision_id`.
|
|
|
|
## Physical-group revision
|
|
|
|
Every completed physical group records:
|
|
|
|
- `revision_id`: immutable SHA-256-derived identity;
|
|
- `parent_revision_id`: the immediately preceding physical-group revision;
|
|
- `group`: one-based `start`, `end`, and `physical_group` values;
|
|
- `variation_nonce` and `seed_identity`;
|
|
- `storage_revision_id` and `generation_contract_sha256`;
|
|
- `lineage_sha256` and immutable chunk record identities;
|
|
- `created_utc` plus deterministic `revision_order`;
|
|
- optional `branch_cut` metadata.
|
|
|
|
Terminal Merge `[N-1,N]` is one physical group. A chain that contains only one
|
|
logical half is invalid.
|
|
|
|
## Canonical chain
|
|
|
|
`project.json` has exactly one `canonical_chain`, one
|
|
`canonical_head_revision_id`, and an `active_revisions` map. Browsing Takes does
|
|
not change them. `Use This Take` or `Continue From Here`, followed by the normal
|
|
Queue action, creates a finalized Schema v3 storage revision and atomically
|
|
switches the canonical chain.
|
|
|
|
`Continue From Here` keeps the selected prefix exactly and starts a new existing
|
|
sampling nonce boundary at the next physical group. The Sampling Contract itself
|
|
remains version 5 and is not extended with provenance fields.
|
|
|
|
## Run Storage Schema v3
|
|
|
|
Schema v3 separates `revision_id` (storage execution identity) from
|
|
`sampling_revision_id` (the unchanged Sampling Contract identity). A finalized
|
|
manifest contains Branch Provenance v1 metadata with its complete active chain,
|
|
branch selection/cut when applicable, and a monotonic `canonical_sequence`.
|
|
|
|
The write order is:
|
|
|
|
1. save and fsync new chunk payloads;
|
|
2. validate all logical records in the completed physical group;
|
|
3. atomically write the finalized manifest and its active chain;
|
|
4. atomically replace `project.json` with the new canonical head.
|
|
|
|
A failure before step 4 leaves the preceding canonical project head intact.
|
|
If `project.json` is corrupt, the highest validated `canonical_sequence` in a
|
|
finalized manifest is the recovery source. In-progress and interrupted revisions
|
|
are not Render History Take candidates.
|
|
|
|
## Schema v2 compatibility
|
|
|
|
Schema v2 manifests remain readable and are never rewritten merely by loading
|
|
them. Their contiguous records are interpreted in memory as a legacy chain with
|
|
one canonical physical-group revision per group. The first Schema v3 save uses a
|
|
separate storage revision directory, so the legacy manifest and payloads remain
|
|
unchanged.
|
|
|
|
No automatic Take garbage collection is part of N2b.
|