aeat.core.compatibility_lifecycle module

Regime-switched compatibility-lifecycle policy for persisted formats.

Two operator directives pull apart across time. Pre-release, the no-legacy-compatibility rule stands unchanged: delete-not-migrate, durability floors chase the current version, no read-tolerance of pre-current shapes. Post-release, struct compatibility and multi-year persistence of a taxpayer’s filed data become MUSTs. This module owns the transition the durability substrate left ungoverned — WHEN the posture flips, WHAT flips, and WHAT enforces it — as a DORMANT, regime-switched policy that is a no-op today and activates on a one-line, ADR-gated flip.

COMPATIBILITY_REGIME is a one-way repo-committed constant. While it is CompatibilityRegime.PRE_RELEASE the policy predicates are behaviour-identical to the pre-release floors-chase-current posture — they read no old shapes, migrate nothing, and tolerate nothing. The CompatibilityRegime.RELEASED branch freezes each format’s durability floor at its released value and demands upgrader-chain completeness plus cross-version fixture coverage for any version above the frozen floor.

The predicates are PURE: every fact they judge on is an explicit parameter, so the RELEASED branch is proven correct by synthetic-input tests without monkeypatching the enforcing gate — the no-patching constraint the 2026-07-08-released-data-durability-adr set for its lineage gates.

Governing vault record

2026-07-09-compatibility-lifecycle-adr (regime-switched dormant durability governance), building on 2026-07-08-released-data-durability-adr (the per-format mechanism).

class CompatibilityRegime(*values)[source]

Bases: StrEnum

The codebase’s compatibility posture at a point in its lifecycle.

A property of the committed source, never of the runtime environment: it is deliberately NOT a setting, env var, or on-disk marker, so a compliance regime cannot vary per machine, be silently unset in CI, or be monkeypatched inside its own enforcing gate.

PRE_RELEASE

delete-not-migrate, floors chase current, no read-tolerance of pre-current shapes. The regime today.

Type:

Pre-release

RELEASED

durability floors frozen at their released values, older persisted shapes must remain readable through registered upgraders.

Type:

The released posture

COMPATIBILITY_REGIME: Final[CompatibilityRegime]

The one-way compatibility regime of this codebase commit. Flipped to CompatibilityRegime.RELEASED ONLY by an accepted checkpoint ADR whose flip commit also freezes RELEASED_FORMAT_FLOORS at the then-current per-format floors. There is no path back to PRE_RELEASE — release is a one-way door.

RELEASED_FORMAT_FLOORS: Final[Mapping[str, int] | None]

The per-format durability floors frozen at the release checkpoint, keyed by format ("secure_object", "bundle", "archive"). None while COMPATIBILITY_REGIME is PRE_RELEASE — populated ONLY in the flip commit with the then-current floors, e.g. {"secure_object": 1, "bundle": 3, "archive": 2}. Once populated, each floor is frozen: a version bump above it post-release requires a real upgrader and old-shape fixture, not a floor raise.

expected_floor(regime, format_key, current_version, released_floors)[source]

Return the durability floor a format’s lineage gate must assert.

Pure: judges only on its explicit parameters. Under PRE_RELEASE the floor chases the current version (older shapes are deleted, never migrated), so the expected floor IS current_version. Under RELEASED the floor is frozen at the released value recorded in released_floors and no longer tracks the current version.

Raises:

  • ValueError – When regime is RELEASED but released_floors is None — an incoherent state the coherence gate also rejects, guarded here so the predicate never indexes None.

  • KeyError – When released_floors has no entry for format_key under RELEASED — a format enrolled in a tier gate but absent from the frozen floors, which the enrollment gate rejects.

Return type:

int

Parameters:
lineage_obligations(regime, format_key, current_version, floor, released_floors, has_registered_upgraders_for_gap, has_fixture_coverage)[source]

Return the violated compatibility obligations for one format.

Pure: every fact is an explicit parameter, so the RELEASED branch is exercisable with synthetic inputs. An empty tuple means the format satisfies every obligation for the given regime.

Under PRE_RELEASE there is one obligation: the floor may not exceed the current version (a floor above current is incoherent — there is no version to read). A normal floor-raise (floor == current) is clean.

Under RELEASED three obligations bind: the floor MUST stay frozen at the released value (floor == released_floors[format_key]); and when the current version is above the frozen floor, the per-hop upgrader chain across the gap MUST be complete and cross-version fixture coverage MUST exist. A post-flip version bump without an upgrader or an old-shape fixture is a violation.

Return type:

tuple[str, ...]

Parameters: