Files
ComfyUI-H3-Continuum-Tiled/docs/N2B_BRANCH_PROVENANCE_CONTRACT_V1.md

2.8 KiB

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.