Files
DumasNodes/docs/N2B_BRANCH_PROVENANCE_CONTRACT_V1.md
T
chris.dumas bf8f76505f Squashed 'vendor/dumas_h3_continuum/' content from commit d07ed31
git-subtree-dir: vendor/dumas_h3_continuum
git-subtree-split: d07ed31b442d283d6a1740f875a843b9feda4c91
2026-10-20 13:43:38 +00:00

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.