03. Substrate versioning — V1–V6¶
Part of the RENAR Standard v1.0-draft · ← Table of contents
3.1 The six substrate capabilities¶
The Source-of-Truth inversion from chapter 2 — the requirement wins, not the code — rests on a single physical condition: the substrate MUST faithfully remember what changed and when. If a past state can be rewritten after the fact, the phrase "the implementation was accepted against the requirements of version X" loses its meaning, and with it the whole acceptance contract collapses. So the six capabilities V1–V6 are not an infrastructure detail but the foundation on which the RENAR idea stands at all; that is why we put them up front, before the chapters on artifacts.
This chapter gives a detailed normative formulation of each capability: preconditions, postconditions, the relation to the trace chain of the Source of Truth, and examples of mapping onto common substrates. The conceptual rationale is §2.5 (statement 3, "Positioning in the methodology typology").
The concrete versioning mechanism — distributed or centralized VCS, a document store with conflict resolution — is interchangeable. RENAR governs capabilities, not tools.
3.2 Rationale for mandatoriness¶
Let us examine, one by one, exactly what breaks without each capability. The relation here is structural, not operational: it is not about team discipline, but about the fact that without the capability the corresponding property of truth simply cannot be expressed.
| No capability | What becomes impossible | Relation in RENAR |
|---|---|---|
| V1 (immutable history) | "The implementation was built against the requirements as of date X" | provenance, audit log, acceptance gate |
| V2 (atomic change unit) | Guaranteed consistency of changes | delta-ADAPT as an atomic change unit (see §7.6) |
| V3 (diff & review) | Approval of requirements and specifications | QG QG-ADAPT-approve, QG-spec-approved |
| V4 (branching / change-set) | A draft is separable from approved truth | transitions draft → review → approved |
| V5 (cross-substrate version pin) | Pinning a requirement version from the implementation | the verifies[].requirement-version field in TC (§9) |
| V6 (author + timestamp) | provenance of every change | signatures in ADAPT, ai-provenance in SR/SPEC |
Therefore a substrate without V1–V6 — a flat file server with no history, a document store without conflict resolution, any mechanism without immutable change tracking — does not implement RENAR regardless of its other merits. This is a structural constraint, not a question of team discipline.
3.3 Normative definitions of V1–V6¶
Paragraphs §3.3.1–§3.3.6 are formulated independently of any concrete substrate. The names of specific products appear only in §3.4 (example) and §3.6 (language illustrations).
3.3.1 V1 — immutable history¶
Capability (immutable history): the substrate MUST ensure that, for any artifact, any past state is addressable and recoverable without loss.
Preconditions: the artifact is registered in the substrate as a versioned object.
Postconditions: for any point in time T in the artifact's history there exists a stable version identifier through which the state at moment T is fully recoverable.
Without V1 it is impossible to:
- Recover the artifact's state as of the contract-signing date.
- Compare the current state with a baseline.
- Build an audit log for conformance (chapter 13 §13.4).
- Set a baseline point for delta-ADAPT.
Concrete realizations on different substrates — §3.4.
3.3.2 V2 — atomic change unit¶
Capability (atomic change unit): the substrate MUST ensure that any change to an artifact (or to a consistent group of artifacts) is recorded as a single transaction: all or nothing. Intermediate inconsistent states are not observable from the outside.
Preconditions: the substrate has a notion of a transaction (atomic change).
Postconditions: after an atomic change, either all edits are visible to an observer or none are. An intermediate "inconsistent" state MUST NOT exist.
Without V2 it is impossible to:
- Update a BR and its related SR consistently in one transaction.
- Guarantee consistency between a requirement and its
linked-tasks[]metadata. - Carry out ADAPT approval as a single atomic action (dual signature + the
client-ready → approvedtransition in one transaction). - Roll back a change without a "half-applied" state.
3.3.3 V3 — diff & review¶
Capability (diff & review): the substrate MUST ensure that a proposed (but not yet integrated) change is representable as a diff against a baseline state, and that a human or AI agent with review authority can approve or reject it before it is included in approved truth.
Preconditions: the proposed change exists separately from approved truth (see V4).
Postconditions: before approval the change exists but is not considered part of the Source of Truth. After approval it becomes part of the Source of Truth as an atomic change unit (V2).
Without V3 it is impossible to:
- Run the quality gates QG-ADAPT-approve, QG-spec-approved, QG-sr-approved (see chapter 10).
- Apply the ADAPT dual signature (see §7.5).
- Review code and specification independently (see §2.3.3 (2)).
- Use adversarial review as a gate.
3.3.4 V4 — branching / change-set¶
Capability (branching / change-set): the substrate MUST separate work in progress (WIP) from approved truth (the Source of Truth) so that several independent changes can be developed in parallel without affecting the Source of Truth.
Preconditions: the artifact is registered in the substrate.
Postconditions: for any artifact at a given moment there MAY exist (a) exactly one approved version (the Source of Truth) and (b) zero or more drafts — each of which is either integrated through V3 or rejected.
Without V4 it is impossible to:
- Separate the
draftlifecycle status fromapproved(chapter 10). - Run several delta-ADAPTs in parallel.
- Hold backward findings in
asked-to-clientwithout blocking approved truth. - Evolve SPEC-* experimentally without affecting requirements derived from the implementation.
3.3.5 V5 — cross-substrate version pin¶
Capability (cross-substrate version pin): substrate A that uses an artifact of substrate B MUST be able to pin a specific version of substrate B's artifact as a stable cross-substrate identifier. This identifier MUST unambiguously recover the state of the artifact in substrate B.
Preconditions: substrate A and substrate B satisfy V1 (each has a stable version identifier).
Postconditions: for every pinned reference in substrate A to an artifact of substrate B there exists a pair (artifact-id, version-id), and through it the full state of substrate B's artifact at the moment of pinning is recovered.
Without V5 it is impossible to:
- Use the
verifies[].requirement-versionfield in TC (chapter 9 §9.4). - Tie the implementation substrate (code) to a specific version of the requirements substrate (SR/SPEC).
- Guarantee: "this implementation was accepted against the requirements of version X."
- Compute the TC freshness metric (a pinned version older than the current one — the TC is stale).
3.3.6 V6 — author + timestamp¶
Capability (author + timestamp): for every atomic change unit (V2) the substrate MUST register an identifiable author (a human or an AI agent with a unique id) and a timestamp with a precision no coarser than one second.
Preconditions: the substrate has an author identification system.
Postconditions: for any atomic change unit the query "who? when?" yields an unambiguous answer.
Without V6 it is impossible to:
- Apply the ADAPT dual signature (a signature = author + timestamp in the substrate's native form).
- Record
ai-provenancein artifact frontmatter. - Build an audit log for conformance.
- Compute the adversarially-found metric (the distribution of backward findings across authors).
3.4 Mapping V1–V6 onto concrete substrates (example)¶
Informative. The table shows how V1–V6 are usually realized on common substrates. It is not part of the normative contract. Any substrate that satisfies V1–V6 implements chapter 3 — whether or not it appears in the table.
| Capability | Git | Mercurial | SVN | Perforce | Document store (example) |
|---|---|---|---|---|---|
| V1 — immutable history | commits, hash-chain | changesets, hash-chain | revisions, sequential numbering | changelists | revision tree per doc (_rev) |
| V2 — atomic change unit | commit | commit | atomic revision | changelist submit | document update (single _rev advance) |
| V3 — diff & review | merge request / pull request | hg phabricator, mq | svn diff + commit gate | swarm review | API workflow + Hub UI approval |
| V4 — branching / change-set | branches | named branches, bookmarks | branches (copy semantic) | branches / streams | conflict branches / WIP docs / draft status |
| V5 — cross-substrate version pin | submodule SHA | subrepo changeset | externals (peg rev) | branches / streams reference | _rev reference + created_by_order |
| V6 — author + timestamp | commit metadata | commit metadata | revision properties | changelist metadata | doc fields (author, updated_at) |
Practical workflows for each substrate:
3.5 A substrate that does not satisfy V1–V6¶
The following configurations do not implement RENAR, because they violate one or more capabilities:
| Configuration | Violation |
|---|---|
| Flat file server; "version" = renaming the file | V1 (no stable history; renaming = loss of provenance) |
| Document store without conflict resolution | V2 (an inconsistent state is possible) |
| Wiki without revision history | V1, V6 |
| Wiki with revision history but no approval procedure | V3 |
VCS using mtime instead of an immutable identifier |
V1, V5 |
| Substrate that edits historical revisions in place | V1 (history is mutable — an audit log is impossible) |
A team adopting RENAR on a substrate from this list MUST either migrate to a suitable substrate or build a compensating layer that provides V1–V6 on top of the underlying storage. In both cases the conformance manifest MUST explicitly document how V1–V6 are realized.
3.6 Substrate-independent language¶
RENAR normative paragraphs use substrate-independent wording: "atomic change unit" (V2), "version pin" (V5), the approved state (after V3), "draft" (V4). Terms specific to a substrate (tool names and their primitives) are permitted only:
- in illustrative tables with an explicit marker (as in §3.4);
- in cross-references to a substrate-specific guide/;
- in appendices to normative chapters.
3.6.1 Examples: normative form and a git illustration¶
| Normative (substrate-independent) wording | Git illustration (not the norm) |
|---|---|
| "A requirement change is recorded as an atomic change unit with author and time (V2, V6)" | "The change is recorded as a commit" |
| "A change passes diff & review before integration (V3)" | "The change passes merge-request review before merge into main" |
| "The implementation substrate pins a specific version of the requirements substrate (V5)" | ".src pins the .req submodule SHA" |
| "The ADAPT dual signature — two independent author+timestamp events (V6)" | "The dual signature — two approvals in the merge-request UI" |
| "Editing an already-approved requirement outside an atomic change unit with review is a violation" | "A force-push to an approved branch is blocked by hooks" |
3.6.2 The substrate as a conformance parameter¶
Each team fixes its substrate choice in the conformance manifest with an explicit mapping V1–V6 → substrate-native primitives. When the substrate changes (for example, from git to a document store) the manifest is updated and a regression check of V1–V6 is run (§3.8).
3.7 Conformance manifest¶
The canonical schema is §13.4, the file RENAR-CONFORMANCE.yaml (YAML 1.2) at the root of the requirements substrate. Chapter 3 governs the substrate-related part: the declaration of the chosen substrate and the V1–V6 mapping (the substrate-capabilities field, §13.4.2).
# Fragment of RENAR-CONFORMANCE.yaml — the substrate-specific part
# (full schema — §13.4.2)
substrate:
requirements: { tool: "<name>", version: "<version>" }
implementation: { tool: "<name>", version: "<version>" }
v1-v6-mapping:
v1-immutable-history: { primitive: "<substrate-specific>", validation: "<CI check / manual>" }
v2-atomic-change-unit: { primitive: "<substrate-specific>", validation: "<CI check / manual>" }
v3-diff-review: { primitive: "<substrate-specific>", validation: "<CI check / manual>" }
v4-branching: { primitive: "<substrate-specific>", validation: "<CI check / manual>" }
v5-cross-substrate-pin: { primitive: "<substrate-specific>", validation: "<CI check / manual>" }
v6-author-timestamp: { primitive: "<substrate-specific>", validation: "<CI check / manual>" }
Confirmation of the mandatory clauses (§2.3 Source-of-Truth inversion, §7 ADAPT, §8 closed list of 9 SPEC types, §9 pos/neg, and others) goes in the mandatory-clauses-confirmed field (§13.3–§13.4).
The manifest is REQUIRED for any conformance claim at level RENAR-1 and above (chapter 13).
3.8 Substrate migration¶
When changing the substrate, the team MUST perform the steps in order:
- Pre-migration audit: the target substrate satisfies V1–V6; otherwise migration is prohibited until a compensating layer exists.
- Manifest draft: an updated
RENAR-CONFORMANCE.yamlwith the new mapping. - Isomorphism check: all artifacts (BR, SR, SPEC, ADAPT, TC) are transferable without loss of fields, ids, or provenance. All ids are immutable — renaming during migration is prohibited.
- Atomic switchover: the migration is an atomic change unit at the process level; a single-moment transfer of all artifacts. Using two substrates as the Source of Truth in parallel is prohibited (see §2.3.3 (1)).
- Post-migration check: a regression check of V1–V6 on real artifacts.
- Manifest registration: the updated
RENAR-CONFORMANCE.yamlis registered in the new substrate as an atomic change unit (V2).
After switchover the old substrate is an archive (a read-only snapshot) or is decommissioned. Working on two substrates as the Source of Truth in parallel is prohibited.
3.9 Relation to other chapters¶
| Chapter | Relation |
|---|---|
| 02 Positioning in the typology §2.5 | Conceptual rationale for V1–V6 |
| 06 Requirements hierarchy | frontmatter relies on V1 (immutable id), V5 (version pin) |
| 07 ADAPT | Approval by dual signature — V3 + V6; delta-ADAPT — V1 + V2 + V4 |
| 08 Specifications | constrained-by[], depends-on[], referenced-by[] — through V5 |
| 09 Test cases | verifies[].requirement-version — a direct application of V5 |
| 10 Lifecycle and QG | Status transitions — V2 + V3 + V4 |
| 11 Maturity model | RENAR-3+: V5 required; RENAR-4+: V6 + ai-provenance |
| 13 Conformance | RENAR-CONFORMANCE.yaml — a mandatory artifact |
| guide/03 | Practice on git |
| guide/04 | Practice on a document store |