Start Building

Lesson 165: Governance Packet Footer Metadata Schema Semver and Replay Parser Contract (2026)

Direct answer: Lesson 164 aligned leadership and partner numbers—yet replay ingestion still fails when footer metadata JSON quietly forks between pipelines. This lesson ships footer_schema_semver, classifies breaking versus additive fields, publishes a replay-parser allow-list contract, and gives you a mixed-archive migration runbook so RC rehearsals ingest history without hand-editing tarballs.

Safari animal illustration suggesting many labeled species sharing one catalog—the metaphor for one footer schema family with explicit versions

Why this matters now (2026)

Late 2026 release-candidate rehearsals attach automated replay jobs to multi-week archives. Partner annex exporters and leadership BI dumps often emit footers from different template branches; parsers written during Lesson 158 drills assume a single shape. When tuple_revision_hash matches but footer_schema_semver does not, ingestion fails—or worse, silently drops carve-out columns—right before certification uploads.

Pair this lesson with the Unity preflight chapter Unity 6.6 LTS OpenXR Governance Evidence Packet Footer Metadata Schema Versioning Preflight so editor-side export hooks emit semver-compatible footers before packets reach ops stores.

Prerequisites

  • Lesson 164 metric dictionary IDs, UTC windows, bypass audit columns, epsilon gates, and readback projections
  • Lesson 158 replay drills with deterministic reviewer-response templates (parser assumptions surfaced there)
  • Artifact store where you can attach JSON sidecars next to PDF or CSV packets

Outcome for this lesson

You will implement:

  • a footer_schema_semver triple carried beside tuple manifests (MAJOR.MINOR.PATCH) with documented bump rules
  • a published matrix of breaking versus additive footer keys tied to parser versions
  • a signed or checksum-stable replay_parser_contract document listing allowed keys, types, and coercion rules
  • a mixed-version archive migration path that rewrites or wraps legacy footers without falsifying evidence dates

1) Declare semver ownership on footer metadata

Treat packet footers as an API surface consumers replay programmatically:

  • reserve footer_schema_semver as mandatory string on every footer JSON fragment you ingest
  • store footer_schema_family (opaque slug) when teams accidentally reuse semver sequences across products
  • bump PATCH for typo fixes and documentation-only clarifications that do not alter parser behavior
  • bump MINOR for additive keys parsers must ignore safely using forward-compat rules
  • bump MAJOR for renamed keys, unit changes, removed keys, or altered coercion semantics

Success check: two exporters disagreeing on display labels still show identical footer_schema_semver when their JSON normalizes to the same semantic intent.

2) Classify breaking versus additive fields explicitly

Maintain a table consumed by engineering and replay CI:

  • Breaking — requires parser bump and archive migration (examples: renaming bypass_audit_id, changing numeric precision units, removing nullable carve-out fields)
  • Additive — older parsers must accept unknown keys without failing (examples: optional exec_readback_pointer, extra attribution URLs)

Embed the classification beside each key in your metric dictionary companion doc so Lessons 163–164 columns stay aligned with footer lineage.

Success check: a replay parser version v3 rejects footer_schema_semver 2.x packets unless migration shim shim_id is present—no silent truncation.

3) Publish the replay-parser allow-list contract

Author replay_parser_contract as versioned markdown or JSON Schema checked into the same repo as parsers:

  • canonical allow-list of keys with types (string, int, nullable_uuid, rfc3339_utc)
  • explicit unknown_key_policy — fail closed for RC lanes; warn-only for sandbox
  • coercion_rules — trimming whitespace, uppercase UUID normalization, baseline epsilon references for floats pulled from Lesson 164
  • minimum_exporter_versions referencing CI packages that emit compliant footers

Ship contract hashes beside nightly replay jobs so auditors verify parsers and contracts drift together.

Success check: injecting a forbidden key fails CI with contract ID and expected semver floor, not a stack trace.

4) Migrate mixed-version archives without rewriting evidence facts

When archives span weeks with divergent footer schemas:

  1. inventory packets by footer_schema_semver and tuple ranges
  2. choose strategy per cohort: rewrite footer JSON with appended migration_audit_id, wrap legacy fragments inside legacy_footer_blob plus transformer note, or split archives at semver boundaries
  3. never alter tuple_revision_hash or underlying aggregates—only metadata envelopes
  4. attach migration_manifest.json listing source semver, target semver, tooling version, operator identity

Success check: golden replay on a migrated archive matches hashes from pre-migration runs modulo explicitly documented additive fields.

Mini challenge

  1. Pick two footer keys from Lesson 163 carve-outs and classify them additive versus breaking with semver bump examples.
  2. Extend your replay parser to fail closed when footer_schema_semver is newer than parser contract_max_semver.
  3. Run a migration dry-run on five historical packets with mismatched footers; verify migration_audit_id appears in reviewer drill scripts.

Pro tips

  • Keep semver bump discussions in the same forum as dictionary semver from Lesson 164—footer drift often tracks KPI definition drift.
  • Add parser_capability_vector to nightly exporter manifests so CI routes packets to compatible parser lanes automatically.
  • When partners lag leadership exporters, ship read-only shims rather than forked parsers; forks multiply audit surface area.

Key takeaways

  • Footer semver makes mixed pipelines legible to automation, not only humans.
  • Breaking versus additive discipline prevents “helpful” silent ignores during RC ingest.
  • Contracts tie reviewer-facing replay credibility to machine-verifiable rules.
  • Migration manifests preserve audit narrative when envelopes must change.

FAQ

Can one packet carry multiple footer fragments?
Yes—require each fragment to carry its own footer_schema_semver and explicitly declare merge precedence in the contract.

Do we semver PDF footers?
Treat PDF as rendered projection; canonical semver applies to machine-readable JSON sidecars extracted during ingest.

What if partners refuse semver bumps?
Block tuple publication until annex exporters emit compliant JSON—leadership-only semver creates asymmetric replay failure modes Lesson 164 already warns about.

Next lesson teaser

Continue with Lesson 166 - Weekly SLA Snapshot Reconciliation Job and Signer Acknowledgment Routing (2026) to schedule weekly partner versus leadership rollup diffs, route signer acknowledgments through job_run_id artifacts, and flip red governance state when the job skips twice.

Continuity:

Semantic versions on footers keep replay automation honest when leadership and partner exporters evolve on slightly different clocks.