Skip to content

Release checkpoints can silently restore pre-#539 ORG outputs: materializer version not bumped #543

Description

@MaxGhenis

Post-merge audit finding on #539 (6e462ca), cross-family (sol adversarial pass; mechanics independently verified against main). Severity: HIGH, operational.

Defect

#539's ORG full-year-equivalence stage runs inside the release builderwith_us_org_wages_inputs(base_frame, ...) mutates the staged frame post-base-load (tools/build_us_fiscal_refresh_release.py ~:8301) — but TARGET_FRAME_CHECKPOINT_MATERIALIZER_VERSION was not bumped (still 7, :322).

The checkpoint identity hashes the on-disk base dataset plus the version constant (materializer_version enters the identity at :1600); staged-frame contents are not hashed — a documented limitation, per the constant's own comment history ("the checkpoint identity hashes the on-disk base dataset, not the staged frame, and would otherwise silently reuse pre-stage frames"). Consequence: a release run resuming a warm target-frame checkpoint written before #539 presents an identical identity, _load_or_materialize_target_frame returns the old serialized entity tables, and the new ORG stage's output is silently discarded after it runs. Same class as PR #477 review finding 2 (the v6→7 bump for SSI assignment).

Current exposure (checked 2026-07-25)

Fix (PR incoming)

  1. Bump TARGET_FRAME_CHECKPOINT_MATERIALIZER_VERSION 7 → 8 with the conventional comment line documenting why (Concept-align the ORG QRF income feature: full-year equivalent for part-year workers #539 ORG stage mutates the staged frame pre-materialization).
  2. Update the identity test pin.
  3. Regression: a stored checkpoint whose identity differs only in materializer_version is rejected (rematerialization path taken), so the next missed bump has a named failure shape.

Durable follow-up (kept open after the bump lands)

Include a staged-frame/stage-code fingerprint in the checkpoint identity so this discipline stops being manual — the comment at :300–322 already concedes the gap; #539 is the second production instance of the class (after #477's SSI finding). Also fold in the audit's MEDIUM: the regeneration contract for in-release staged changes (checkpoint invalidation + explicit clean rebuild) should be a documented requirement in the PR template for release-builder stages.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions