Macro-4 Standard IO Contract Versioning — R2-B2 (2026-06-19)

Date: 2026-06-19 · Workstream: R2-B2-MACRO-4-STAGING-WORKBENCH-IO-CONTRACT-TD-ENTRY-GATE-2026-06-19 (Deliverable 20 of 90) · Editorial revision: rev1 Class: IO contract versioning · READ-ONLY · NON-ENACTING · NON-AUTHORIZING · NO write performed.

Metadata convention. Editorial revision (rev1) only. Storage revision/content_length authoritative at read time.

---

0. Status and non-authorization

STATUS: PASS — engineering / design-only. How contract_version works so contracts evolve without breaking consumers or losing audit. Engineering PASS ≠ authority PASS. Default: HOLD.

1. Purpose

Define a versioned contract envelope so a block contract can change deliberately, traceably, and compatibly.

2. Sources / evidence read

Điều 32 §3.1 audit-preservation ("đổi tên code = tạo code mới, deprecate cũ"); TD-readiness §4 (F-1/F-2 frozen contracts); inspect-producer §4. Main process, no reader-agents.

3. Accepted baseline (carried)

A contract is designed to by TD; a moving contract makes TD unverifiable. So contract changes are versioned and audit-preserving, mirroring Điều 32's "create new code, deprecate old; never update a PK in use."

4. Evidence / analysis — versioning rules (VC)

#	Rule
VC-1	contract_version is immutable once published; a change = a new version
VC-2	Consumers pin a version; a producer change requires a coordinated bump (e.g. B2+B4 for the B3 stud)
VC-3	Audit-preserving: old versions are deprecated/retired, never silently overwritten
VC-4	A frozen contract (F-1/F-2) is a precondition for TD; freezing = agreeing a version
VC-5	Editorial vs storage revision are distinct (this package's own convention)

5. Contract / requirement / matrix / result

Versioning makes "born/replaced separately" safe at the contract layer: a new contract version is a new LEGO interface, not a mutation of the old one. No version is bound or enforced at runtime here.

6. Owner-gated future work

Publishing/enforcing a contract version in runtime is Owner-gated; forbidden now.

7. What remains unresolved

The version-store mechanism is FUTURE_TECHNICAL_DESIGN_REQUIRED (and must not become a mega-registry).

8. Ready for GPT/Codex review

Yes — Codex should confirm versioning stays audit-preserving and non-centralizing.