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:
+10
-1
@@ -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**
|
||||
|
||||
Reference in New Issue
Block a user