feat(0090): blueprint format forward-compat — Tier-1 tolerance pinned, two-tier discipline codified (closes #156)

The blueprint data format (C24) extends additively under one codified
two-tier discipline:
- Tier-1 (additive-optional): a new optional field/section is tolerated by an
  older reader (serde ignores unknown fields — no deny_unknown_fields), with no
  format_version bump; by C1 a new optional field defaults to prior behaviour,
  so an old blueprint reproduces the same graph.
- Tier-2 (must-understand: a new node type, edge semantics, or structural-axis
  kind): bumps format_version, so an old reader refuses cleanly
  (LoadError::UnsupportedVersion / UnknownNodeType) rather than silently
  building a different graph.

Most of #156 already shipped with #155 (cycle 0087): the envelope, omit-defaults
canonical form, and both Tier-2 load-path refusals were present and green. This
cycle pins the one previously-unproven property — Tier-1 forward-tolerance of an
unknown optional field on the current loader — and codifies the discipline.

Changes:
- New characterization pin (in-crate, blueprint_serde.rs):
  unknown_optional_field_is_tolerated_byte_identically — an unknown optional key
  at doc and primitive level loads byte-identically and runs bit-identically.
- Two public-seam E2E pins (blueprint_serde_e2e.rs, added by the E2E phase):
  unknown_envelope_field_tolerated_through_public_api and
  unknown_primitive_field_tolerated_through_public_api — split the two distinct
  tolerance surfaces (envelope vs primitive) across the World/cdylib crate
  boundary, where a deny_unknown_fields added to one would break forward-compat
  while leaving the in-crate test green.
- LoadError::UnsupportedVersion doc reworded from the deferred "is #156" note to
  the settled two-tier discipline statement.
- C24 ledger (docs/design/INDEX.md): Status codification sentence added; #156
  dropped from Remaining (#158/#159 stay).

Derived fork (recorded on #156): the per-section required-flag mechanism (PNG
critical-vs-ancillary) is NOT built — the version envelope already gives the
must-understand refusal at version granularity, no current Tier-2 section
validates a finer scheme, and C1 holds either way.

The pin is a characterization test (GREEN on first run) — it documents existing
serde silent-ignore behaviour, no production code changed. Verified: cargo test
-p aura-engine green (all targets, three new tests confirmed by name); cargo
clippy --workspace --all-targets -- -D warnings clean.
This commit is contained in:
2026-06-30 13:28:25 +02:00
parent ead064df50
commit cdd2da6337
3 changed files with 129 additions and 4 deletions
+10 -1
View File
@@ -1820,8 +1820,17 @@ rejected at construction. The holistic *finalize* faults now also read
(`UnconnectedPort` / `RoleKindMismatch` / `UnboundRootRole`) into by-identifier
`OpError` variants — still *calling* the unchanged holistic gates (the
no-second-validator lockstep preserved), only translating their result.
**Cycle 0090 (#156) codifies the forward-compat two-tier discipline.** Tier-1
(additive-optional) is serde-default silent-ignore with no `format_version` bump
(a new optional field defaults to prior behaviour, C1) — now proven by
`unknown_optional_field_is_tolerated_byte_identically` (an unknown optional key
loads byte-identically and runs bit-identically). Tier-2 (must-understand: a new
node type, edge semantics, or structural-axis kind) bumps `format_version` so an
old reader refuses cleanly (`LoadError::UnsupportedVersion` / `UnknownNodeType`,
already green). The per-section required-flag scheme is deferred (no current
Tier-2 section to validate it; recorded on #156).
**Remaining**
(each its own milestone issue): the forward-compat *must-understand* gate (#156);
(each its own milestone issue):
content-addressed topology identity in the manifest (#158, C18); retiring the pre-C24
hard-wired `aura-cli` harnesses (`HarnessKind`, `run_stage1_r`, `*_sweep_family`) once
the project-as-crate layer lands (#159, paired with #157's data-authoring surface). **Out of the first cut's round-trippable set**