Series catalog: canonical registry for the thesis fact ledger

[MaxGhenis]

Adds ledger/series_catalog.json — the canonical series registry the observation file never had — plus its generator.

Why: ThesisInstitute/thesis#112. Thesis's docket (75 series) has been acting as a second identity system; bill metrics could only wire to those 75. The catalog makes the ledger the single identity home: one row per series family with a UUID minted exactly once, so downstream consumers (docket, bill mappers, permalinks) reference series by UUID/concept instead of minting their own.

What's in a row: uuid, canonical concept, family_patterns (period tokens {P}-stripped from observed concepts: fy2026, 2026-05, may_2026, q1_2026/2026_q1, week_…), modal unit/cadence/geography/entity, aliases (observed concept spellings + source labels like UNRATE), rid_patterns (source_record_id families, for grading linkage), first/last observed period, count, status (observed | docket-only).

Deliberate non-moves: release vintages (first_print, third_estimate) and concept-spelling drift (abs.cpi.all_groups.yoy vs abs.cpi_indicator.allgroups.yoy) are never merged mechanically — those are curation judgments done by hand-merging rows (survivor keeps its UUID, absorbed spellings become aliases).

Determinism: regeneration is byte-identical for the same inputs; UUIDs persist keyed by concept; --check mode verifies currency (CI can adopt it); observations_sha256 binds the catalog to the exact observation bytes it was built from. Families differing only in {P} placement merge (same series, two period formattings) — the 168 rows' 107 raw concepts collapse to 93 observed series + 48 docket-only = 141.

Consumer side (lands in thesis after this): pin_ledger.py pins the catalog alongside the observations; every docket entry gains ledger: {uuid, concept}; a build-time containment test enforces docket ⊆ catalog; the bill mapper matches hints against catalog ∪ docket.

🤖 Generated with Claude Code

[MaxGhenis]

An adversarial sol review of the first commit returned BLOCK with six findings; the two follow-ups respond to all of them. Review highlights and dispositions:

1. Untracked docket seed / bare --check broken → the seed is now committed at ledger/seeds/thesis_docket_series.json and digest-bound in the header (docket_seed_sha256); bare --check covers the full input set and runs in CI.
2. 29 live period spellings unrecognized, already splitting UUIDs (2026_06, 2026_06_18, feb_2026, week_ending_…, week_2026_06_13, after_june_2026, after_mpc_june_2026, february_to_april_2026) → the token grammar covers every one, plus a semantic pass derives expected tokens from each row's own period, and any surviving year-bearing segment lands in suspect_segments (committed catalog: zero). The M3 and initial-claims duplicate UUIDs heal; BoE's two rate spellings merge.
3. Rename/curation/collision loses or remints identity; --check trusts blindly → UUIDs inherit by identity key, then by unique concept/alias match; curated aliases persist across regeneration and keep the prior row's canonical concept; ambiguous matches and UUID collisions are hard errors; --check validates UUID syntax/version/uniqueness.
4. Concept-only key collapses 54 geography subseries (vs the fact-identity ADR) → identity is now (concept, geography, entity): FNS error rates split into national + per-state rows; Eurostat flash (EA21/economy) and final (EA/household) separate. 141 rows → 201.
5. Modal masking → _modal is gone; unit/cadence conflicts within an identity are hard errors, never a silent pick.
6. Provenance → header binds observations digest + seed digest; the PR-body claim about field derivation is corrected: UUIDs are minted state preserved across regenerations, not derived from inputs; docket rows without a declared country carry null geography rather than a fabricated default.

Regression tests (tests/test_build_series_catalog.py, 34 cases incl. the review's full token table) + CI step added. A focused re-review of the v2 diff runs next; merge only on green + agreement.

🤖 Generated with Claude Code

[MaxGhenis]

Focused re-review — series-catalog v2

Reviewed range: 9b4329e..HEAD (6ab4fbe, 2859ecb)
Verdict: BLOCK
Risk: CRITICAL — the committed artifact has discarded every previously minted UUID, the checker accepts multiple UUID-disjoint catalogs for the same inputs, and the new alias fallback can move or merge identities across the dimensions that are supposed to define them.

The seed, current period spellings, FNS geography split, BoE merge, M3 normalization, observed-row unit/cadence rejection, and ordinary stale-catalog CI check all improved. Those passes do not offset the identity failures below.

Ranked findings

1. [CRITICAL] The commits wholesale remint the registry, and --check cannot detect the remint

The catalog promises that a UUID is “minted once and never re-minted” (ledger/series_catalog.json:2; also scripts/build_series_catalog.py:5-7,41-44). The committed history does the opposite:

• From 9b4329e to 6ab4fbe, the builder's own identity projection (concept, geography level/id, entity name/role) has 116 common identities; 0 of 116 UUIDs survive. The total UUID-value intersection is 0 of 141.
• From 6ab4fbe to 2859ecb, all 201 identity keys are unchanged and 0 of 201 UUIDs survive. The catalog diff consists only of 201 removed UUID lines and 201 added UUID lines; observations hash, seed hash, row counts, concepts, and metadata are unchanged.
• Example: unchanged ABS building approvals is 0a67f2eb-… at 9b4329e:ledger/series_catalog.json:8, e344ff46-… at 6ab4fbe:ledger/series_catalog.json:18, and efbb2901-… now (ledger/series_catalog.json:18). The unchanged docket-only abs.labour.unemployment_rate similarly moves from 843e5bab-… (9b4329e:ledger/series_catalog.json:168-183) to 443cb1bf-… (ledger/series_catalog.json:183-198).
• The merged BoE row now uses 8fb890ac-… (ledger/series_catalog.json:1619-1650), preserving neither prior BoE identity. M3 orders now uses 294d82e8-… (ledger/series_catalog.json:1805-1835), preserving neither the prior docket nor observed UUID.

This is not forced by the final algorithm. Running the HEAD builder against a temporary copy of the 6ab4fbe catalog reports catalog current: 201 series and exits 0; running it against HEAD also exits 0. Thus two completely UUID-disjoint 201-row catalogs are accepted for the same observation and seed bytes.

The reason is circular state: the file under check first supplies the prior UUIDs (scripts/build_series_catalog.py:555-557, reused at :387-390), and the generated result is then compared with that same file (:565-577). Syntax/version validation cannot establish historical continuity. This directly fails disposition 3 and means the new CI step would not have caught the actual 201-ID remint in 2859ecb.

2. [HIGH] Alias fallback bypasses geography/entity identity and omits geography vintage

An exact identity match uses the full derived key (scripts/build_series_catalog.py:290-294), but the fallback searches global concept and alias indexes without filtering candidates to the incoming geography/entity (:295-300). The matched prior UUID is then applied to the incoming geography/entity (:329-332,387-390).

Adversarial results:

• With one prior US row and a later California-only row of the same name, the California row silently inherits the US UUID: the UUID moves to a different geography.
• If both old US and new California rows are present, claim_uuid eventually errors because both claim the same raw UUID. That prevents corruption but also prevents an ordinary new geography.
• Once a concept has several prior geographies (for example the 54 FNS rows), adding a new geography fails earlier as an ambiguous global name match.

The fallback is useful for enriching a docket-only placeholder whose entity is not yet known, but it is too broad for already observed identities. There is no regression test for geography movement or incremental geography addition; tests/test_build_series_catalog.py:119-130 only builds two geographies from an empty catalog.

The key is also not actually the full geography object claimed by the disposition. _geo_key includes only level|id (scripts/build_series_catalog.py:193-195), while the observation object also carries vintage. Two synthetic rows with the same level/id and vintages v1 and v2 merged into one bucket; reversing input order changed which vintage was emitted. The first geography object is retained at scripts/build_series_catalog.py:230,344,404. This conflicts with the ADR requirement that relevant boundary vintage participate in identity (docs/adr-arch-fact-identity-v2.md:175,350-351). Disposition 4 therefore passes for current IDs but not for the claimed identity mechanics.

3. [HIGH] Automatically generated aliases can merge distinct concepts and flip the canonical concept without curation

The fallback treats aliases as identity-authoritative, but the catalog does not distinguish curated aliases from mechanically copied measure.source_concept values:

• source_concepts participate in matching (scripts/build_series_catalog.py:329).
• A unique global name hit is accepted (:295-300).
• The prior concept becomes canonical (:330-332), and buckets landing on that key merge (:333-368).
• Raw concepts, source concepts, and curated aliases are all unioned into the same alias list (:391-395).
• claim_uuid runs only after this merge (:373-390), so it sees one bucket and cannot report that another concept was absorbed.

Reproduction without any hand edit:

1. Build agency.rate_a with source concept OFFICIAL_SHARED; the generator automatically records OFFICIAL_SHARED as an alias.
2. On the next build, supply only genuinely different agency.rate_b with that same source concept. The output silently remains canonical agency.rate_a and inherits its UUID.
3. Supply A and B together. They silently become one A row with observation_count: 2.

So the answers to both adversarial questions are yes: a bad unique alias can merge distinct identities, and canonicalization can flip a concept without curation. This contradicts the manual-curation claim at scripts/build_series_catalog.py:25-33 and ledger/series_catalog.json:2. The current tests cover a manually inserted alias with one incoming bucket (tests/test_build_series_catalog.py:145-155), not an automatically derived alias, two-bucket merge, or uncurated concept flip.

The committed data demonstrate that source_concept is not necessarily a synonym. Raw row 104 is the derived concept fns.snap.share_jurisdictions_at_or_above_6pct but declares fns.snap.total_payment_error_rate as its source concept (ledger/official_observations.jsonl:104). The catalog emits the base measure as an alias on the derived share (ledger/series_catalog.json:2813-2836). That name is also canonical for 54 different FNS rows, yet it is absent from the six-item ambiguous_aliases header (ledger/series_catalog.json:8-14) because ambiguity counts alias occurrences only, not alias-versus-canonical collisions (scripts/build_series_catalog.py:481-484).

Alias healing is also incomplete in the opposite direction. Exact identity wins before aliases are considered (scripts/build_series_catalog.py:292-294), so two prior rows remain separate even when one explicitly aliases the other's canonical concept. Three live same-geography/entity pairs do this:

• initial claims: ledger/series_catalog.json:2181-2210 versus :5553-5584;
• housing starts: :1739-1769 versus :5487-5518 (raw row 31 calls this a duplicate Thesis target ID);
• industrial production: :2648-2678 versus :5618-5649 (raw row 27 calls this a duplicate Thesis target ID).

This is why the initial-claims “heal” is only partial, not complete.

4. [HIGH] Logical UUID collisions pass claim_uuid, validation, and CI

Both collision mechanisms key on the UUID's raw JSON string (scripts/build_series_catalog.py:373-381,518-531). uuid.UUID accepts uppercase, hyphenless, and braced representations, but the uniqueness map never keys on the parsed 128-bit value and never requires canonical str(parsed) spelling.

In temporary copies, row 2 was assigned an uppercase, hyphenless, and then braced spelling of row 1's UUID. Each variant represented the same UUID after parsing; bare --check nevertheless printed catalog current: 201 series and exited 0. tests/test_build_series_catalog.py:198-208 covers only byte-identical duplicate strings.

The current 201 committed values are canonical lowercase UUIDv4 strings and unique by parsed value, so this is a verifier/collision-surface defect rather than a current catalog collision.

5. [MEDIUM] The seed digest is load-bearing, but the default seed is not required to exist

Positive result: the tracked seed hashes to 930424fb48c0be4c9e2ce17d4e0f2a6be886408e814c80324174a7a303fa0271, exactly matching ledger/series_catalog.json:6. A one-byte seed change makes --check fail. The digest is therefore genuinely load-bearing (scripts/build_series_catalog.py:414-417,500-504,565-576).

Residual failure: a missing path is silently treated as “no docket” (scripts/build_series_catalog.py:414-417), with a null digest (:502-504). In a temporary checkout with the seed absent, bare regeneration succeeded and wrote 155 observed/0 docket-only rows; the subsequent bare --check passed against that reduced catalog. The committed-catalog test does not assert seed existence, a non-null seed digest, or 201 rows (tests/test_build_series_catalog.py:211-220). Thus deleting/losing the seed and committing the regenerated reduced artifact reopens the original omission path while CI remains green.

6. [MEDIUM] Period coverage is fixed for current data, but “only period tokens” is still not enforced

All previously missed live spellings now normalize and the committed suspect_segments list is empty (ledger/series_catalog.json:7). BoE and M3 demonstrate useful fixes. However, stripping remains shape OR derived (scripts/build_series_catalog.py:173-177), and the shape grammar is independent of row.period (:94-105). It still strips impossible or mismatched strings such as 2026_13 or 2025_12 on a row whose period is 2026-06, with no suspect signal because suspect scanning only sees surviving segments (:185-190). A legitimate table, statute, cohort, or edition segment equal to a recognized period spelling is therefore silently removed.

The claimed semantic safety pass does not mitigate current normal forms: every token derived for normal fiscal-year/month/quarter/week values is already accepted by the shape grammar. In particular, the test comment saying the grammar does not know june_2026 (tests/test_build_series_catalog.py:63-69) is false; the month regex already recognizes it (scripts/build_series_catalog.py:99).

This is an acceptable residual only if date-shaped dotted segments are explicitly reserved for periods by contract. Under the present categorical “period tokens (and nothing else)” statement (scripts/build_series_catalog.py:11-17), it is not acceptable: a mismatch should at least fail/flag, or the format needs an escape/curation mechanism.

Catalog audit

The committed artifact contains 201 rows: 155 observed and 46 docket-only. All 168 observations are accounted for in observed-row counts. The 75 seed entries yield 46 docket-only rows; 29 match observed names. All 46 direct seed rows match their declared cadence, target unit, and country mapping; entries without a country retain null geography. Both input digests are exact, and all current UUIDs are parseable canonical UUIDv4 values unique by parsed value.

Twelve-row raw-data spot-check

Catalog identity	Raw/seed evidence	Result
BoE Bank Rate (ledger/series_catalog.json:1619-1650)	raw ledger/official_observations.jsonl:39-40	Correct GB/government/bank-rate identity; both spellings merge, count 2.
Census M3 orders (ledger/series_catalog.json:1805-1835)	raw :157; seed ledger/seeds/thesis_docket_series.json:546-568	Correct US/economy identity; dated concept and docket seed heal to one observed row.
Census M3 shipments (ledger/series_catalog.json:1838-1868)	raw :158; seed :571-592	Correct US/economy identity; one observed row.
FNS national (ledger/series_catalog.json:2845-2873)	raw ledger/official_observations.jsonl:6,103	Correct US-country/household identity; FY2024+FY2025, count 2.
FNS California (ledger/series_catalog.json:2995-3024)	raw :54	Exact state ID/name and household entity.
FNS District of Columbia (ledger/series_catalog.json:3115-3144)	raw :58	Exact state-level DC ID/name and household entity.
FNS Guam (ledger/series_catalog.json:4405-4434)	raw :61	Faithfully retains the raw state-level Guam ID/entity.
Eurostat May final (ledger/series_catalog.json:2312-2341)	raw :33	Correct EA/household/HICP-all-items identity.
Eurostat June flash (ledger/series_catalog.json:2344-2374)	raw :134	Correct EA21/economy identity; no longer collapsed with May final.
Old DOL initial claims (ledger/series_catalog.json:2181-2210)	raw :18	Faithful US/ui_initial_claimant/month metadata.
Standard weekly initial claims (ledger/series_catalog.json:5520-5551)	raw :105-106,144,148,162	Correct US/ui_claimant/week-ending identity, count 5.
Second old initial-claims spelling (ledger/series_catalog.json:5552-5584)	raw :44	Period token strips, but row remains separate despite aliasing the first old-DOL concept.

FNS now splits correctly: 55 observations become 54 geographic identities — one national identity with two periods plus 53 state-level jurisdiction identities. The raw and catalog geography/entity sets agree exactly.

The initial-claims three-row split reflects inconsistent raw metadata rather than three cleanly distinct economic concepts:

1. raw row 18: dol.eta..., entity role ui_initial_claimant, period type month;
2. raw row 44: us.dol..., the same ui_initial_claimant/month dimensions, and an alias back to the first concept;
3. raw rows 105-106, 144, 148, 162: us.dol..., role ui_claimant, proper week_ending cadence.

The year-bearing token defect is fixed, and future observations matching each normalized bucket will not mint a UUID per week. But the existing semantic duplication is not healed: rows 1 and 2 still have separate UUIDs even though one aliases the other's canonical concept.

Six prior dispositions

Prior issue	Re-review result
1. Untracked seed / bare check	Partial pass. Seed is tracked, hashed, and bare check uses it; a byte change fails. Missing seed plus regenerated reduced catalog still passes.
2. Period spellings	Qualified pass. All live spellings normalize; BoE and M3 heal and suspects are zero. Initial claims remains three rows, and false-positive stripping is still possible/unflagged.
3. Rename/curation/collision	Fail. The commits remint every UUID; auto aliases can merge/flip concepts; geography can move; parsed-equivalent UUID collisions pass; current alias-linked duplicates persist.
4. Concept-only geography collapse	Partial pass. Current FNS and Eurostat rows are correctly split, but fallback ignores dimensions and geography vintage is absent from the key.
5. Modal unit/cadence	Pass. _modal is gone and synthetic observation unit and cadence conflicts both hard-fail through _sole (scripts/build_series_catalog.py:257-266,402-403).
6. Provenance / no fabricated default geography	Pass narrowly. Both digests match exact bytes; seed-only undeclared countries remain null; UUID state is correctly described as catalog state rather than input derivation.

CI and validation

The CI step is wired correctly and unconditional for pushes and pull requests: it runs bare --check and the focused tests with no error suppression (.github/workflows/ci.yml:37-40). An ordinary stale derived field, one-byte seed change, observation change, or missing seed against the current 201-row catalog exits 1 and fails the step.

Its boundary is material: because the catalog under check supplies UUID/alias/canonical state, valid UUID remints and persisted alias changes are considered current. Both the 6ab4fbe and HEAD UUID-disjoint catalogs pass the HEAD checker. Missing seed plus a consistently regenerated 155-row catalog also passes. Therefore CI is a derived-data freshness check, not an identity-continuity or required-seed check.

Validation record:

python3 scripts/build_series_catalog.py --check                  PASS (201)
pytest tests/test_build_series_catalog.py -q                    PASS (34)
python3 -m doctest scripts/build_series_catalog.py               PASS
ruff check script + focused tests                               PASS
git diff --check 9b4329e..HEAD                                  PASS
one-byte seed change vs current catalog                         FAIL as stale (correct)
missing seed vs current catalog                                 FAIL as stale (correct)
missing seed + regenerated 155-row catalog                      INCORRECT PASS
uppercase/hyphenless/braced duplicate UUID                      INCORRECT PASS
HEAD checker against 6ab4fbe UUID catalog                       INCORRECT PASS (201)
current FNS split                                                PASS (54 identities / 55 observations)
current UUID syntax/version/parsed uniqueness                   PASS (201)
final worktree                                                   CLEAN

Merge gate

Do not merge until, at minimum:

1. The surviving UUID for every pre-existing/merged identity is explicitly curated and the catalog is rebuilt without wholesale reminting; continuity must be checked against the prior committed registry, not only against itself.
2. Alias fallback is scoped to compatible identity dimensions (with an explicit docket-placeholder enrichment rule), and derived source concepts are not treated as curated synonyms without provenance or review.
3. UUIDs are required to use canonical text and uniqueness is keyed by parsed UUID value.
4. Geography boundary vintage participates in identity and required seed absence is a hard error.
5. Period normalization either reserves date-shaped segments by contract or flags mismatches/false-positive candidates.

Final recommendation: BLOCK.

[MaxGhenis]

Disposition — series-catalog v3 (3cb0c8a)

Response to the second adversarial review (BLOCK). Core change: UUID authority moves out of the catalog file into ledger/series_uuid_registry.jsonl, an append-only minting ledger (one JSON line per identity→UUID binding; re-bindings must chain via supersedes + note). The catalog is now a derived view that embeds the registry digest. The circular-state defect — "the file under check first supplies the prior UUIDs, and the generated result is then compared with that same file" — is gone: the builder inherits from the registry (scripts/build_series_catalog.py:840-866), and --check verifies catalog↔registry agreement binding-for-binding (:1063-1083).

Finding-by-finding

1. [CRITICAL] Wholesale remint undetectable by --check — fixed, and the committed UUIDs are frozen.
The registry was bootstrapped from the 2859ecb catalog's 201 bindings (the prior committed registry state); v3 regeneration preserved 201/201 UUIDs (identity-key → UUID map verified equal). Your exact repro now fails: swapping the 6ab4fbe catalog in and running the HEAD checker exits 1 with per-identity registry agreement errors (one per reminted UUID). Layers, all exercised by tests:

• catalog row ≠ registry binding → --check fails (registry_agreement_problems, test test_check_rejects_uuid_disjoint_catalog);
• registry edited in a working tree → --check fails the git-HEAD byte-prefix check (:1113-1125);
• registry edited across commits → the new CI step fails the PR (.github/workflows/ci.yml:41-63, --verify-registry-append-only against github.event.pull_request.base.sha);
• write mode refuses to change or drop any existing identity's UUID absent --allow-remint --remint-note "..."; a permitted remint appends a chained supersede line, so every identity change is a reviewable event (:1245-1263, tests test_main_remint_guard_and_ceremony, test_main_dropped_identity_requires_allow_remint).

2. [HIGH] Alias fallback bypasses geography/entity; vintage missing from key — fixed.
ExistingCatalog.match searches only rows with the same (geography, entity) key (:554-609); your cross-geography repro now mints fresh (test test_cross_geography_name_match_never_inherits), and incremental geography addition no longer trips the global-ambiguity error (test test_new_geography_added_incrementally). The documented exception is docket-placeholder enrichment: docket-only row, entity None, geography absent or equal on (level, id) (tests test_docket_placeholder_enrichment_keeps_uuid, test_docket_placeholder_never_enriches_across_country). Geography vintage joins the identity key (_geo_key, :421-423) and the registry stores it per binding; same level/id with different vintages now yields two identities, order-independent (test test_geography_vintage_splits_identity). All 168 live observations carry vintage: "current", so no live identity moved.

3. [HIGH] Auto source-concept aliases merge/flip concepts — fixed.
measure.source_concept values are provenance now: recorded per row in a new source_concepts field, excluded from aliases, excluded from match names (:817, :894). Your OFFICIAL_SHARED repro: rate_b mints fresh, and A+B together stay two rows with no canonical flip (test test_source_concept_never_drives_inheritance). Row 104's derived share no longer aliases fns.snap.total_payment_error_rate — it cites it as source_concepts provenance. The one-time cleanup of the 85 machine aliases was done as reviewed data curation (not version-gated code); the two docket links that genuinely were identity statements — bls.ces.average_hourly_earnings_private, statcan.employment_insurance.regular_beneficiaries — were re-added as explicit curated aliases. ambiguous_aliases is now empty. The three alias-linked live pairs (initial claims, housing starts, industrial production) deliberately remain separate rows: with source labels demoted to provenance, no alias relation links them any more; folding each pair is a curation judgment (delete absorbed row + curated alias + --allow-remint, per the module docstring recipe) that should be its own reviewed change, not a mechanical side effect of this one.

4. [HIGH] Logical UUID collisions pass — fixed.
Canonical lowercase form is required everywhere (canonical_uuid_problem, :447-460) and uniqueness keys on the parsed 128-bit value (validate_uuids, :1035-1060; claim_uuid, :824-838; registry load). Your uppercase/hyphenless/braced variants each produce two findings — non-canonical form and same-128-bit-value duplicate (test test_uuid_validation_requires_canonical_and_parsed_uniqueness).

5. [MEDIUM] Missing seed silently accepted — fixed.
A missing seed path is a hard error in write and check modes alike (:1190-1195, test test_main_missing_seed_is_a_hard_error), and the committed-catalog test additionally pins docket_seed_sha256 is not None, seed existence, and the 201-row count.

6. [MEDIUM] Shape-pass strips mismatched/impossible tokens — fixed.
Stripping is no longer "shape OR derived": a segment strips only when it is a direct spelling of the row's own period or parses to a calendar window overlapping that period (family_pattern + _matches_period, :337-398) — this covers all eight live shape-only strips (day-in-month, week-overlapping-month, after_-qualified month, month-range covering the period month; fiscal-year tokens must match the fiscal-year period exactly). 2025_12 on a 2026-06 row and impossible tokens like 2026_13 are kept in the identity and flagged in suspect_segments (tests test_mismatched_tokens_flagged_not_stripped, doctests). The false test comment about june_2026 is gone. Bonus: fixed a latent v2 bug where MONTHS_ABBREV held 13 entries, silently shifting derived abbreviations for October–December rows.

Regenerated artifact (all v2 heals retained)

201 series — 155 observed, 46 docket-only; FNS 54-way split (national row with FY2024+FY2025, 53 state rows); BoE one row, count 2; both M3 rows observed; Eurostat May-final (EA/household) and June-flash (EA21/economy) separate; suspect_segments: []; ambiguous_aliases: []; minted=0, superseded=0 on the migration build.

Validation record

uv run pytest tests/test_build_series_catalog.py -q        63 passed
uv run ruff check script + tests                           clean
python3 -m doctest scripts/build_series_catalog.py         clean
python3 scripts/build_series_catalog.py --check            PASS (201)
identity continuity 2859ecb -> 3cb0c8a                     201/201 UUIDs preserved
HEAD checker vs 6ab4fbe catalog copy                       FAILS (registry agreement, exit 1)
missing seed (write / check)                               FAILS (hard error, both)
uppercase / hyphenless / braced duplicate uuid             FAILS validation
registry line edited                                       FAILS --check + --verify-registry-append-only
catalog uuid edited, no flag                               build REFUSES, nothing written
--allow-remint without --remint-note                       REFUSES
--allow-remint + note                                      writes chained supersede line; --check green after
seed entry dropped, no flag                                build REFUSES
byte idempotence (catalog + registry)                      PASS

Registry bootstrap is reproducible: one mint line per 2859ecb catalog row, in row order (script preserved at ~/thesis-wave-0731/catalog-v3-migration.py; the agreement check makes the equivalence machine-verifiable).

A third adversarial review is being dispatched against 3cb0c8a.

[MaxGhenis]

v3 addendum (45fcc10 — self-found gap, fixed before third review): rebuilding from a bare registry (committed catalog deleted or empty) would lose curated naming/alias memory; after any future rename curation, the renamed identity would re-key away from its binding and silently fresh-mint — passing agreement and append-only checks, since the registry only grows. Not reachable in the current artifact (canonical == derived concept for all 201 rows), but the builder now treats a bare-registry rebuild as a gated identity event requiring --allow-remint --remint-note (test test_rebuild_without_prior_catalog_is_gated; suite now 64 tests). The third adversarial review is being dispatched against the branch head including this commit.

[MaxGhenis]

Third-review attempt 1 crashed mid-run (harness stall on a full-suite pytest invocation) after surfacing four reproducible findings; all four are fixed in 2c31ae4, and a fresh full review is dispatched against that head:

1. Lossy dimension keys — _geo_key/_entity_key were pipe-joins, so crafted values could collide across fields and None collided with "None". Now JSON-encoded (injective). Test test_dimension_keys_are_injective + doctest. Only visible artifact effect: the two Eurostat rows now sort in natural EA < EA21 order.
2. Partial-catalog rebuild could silently re-mint — the bare-registry gate only fired on a zero-row catalog. The registry now tracks binding liveness with explicit retired/revived events: a dropped row appends a noted retire line (gated by --allow-remint); a returning identity revives its original UUID automatically; and agreement is now checked in both directions — every live binding's UUID must appear on a catalog row, so deleting any subset of rows fails --check and the write guard (test_partial_catalog_deletion_cannot_silently_remint, test_main_dropped_identity_retires_then_revives).
3. Overlap strips were silent — a statute/cohort/edition label spelling a window overlapping the row's own period is mechanically indistinguishable from a period label, so every overlap-based strip is now published in a new overlap_stripped_segments audit list (exactly the eight live segments today; pinned in the committed-catalog test).
4. Push-event bypass — the CI append-only gate ran only on pull_request; it now also verifies pushes against github.event.before, and an unfetchable before-sha (history rewrite) fails loudly.

Also correcting a disposition count: the one-time migration removed 82 machine alias instances, not 85 as written.

State at 2c31ae4: 201 series, UUID/identity map unchanged (201/201 from 2859ecb), registry untouched at 201 mint lines, 66 tests, ruff/doctest/--check/byte-idempotence green.

[MaxGhenis]

Third adversarial review (sol, ultra) — against 2c31ae4

Posted verbatim from the reviewer's REPORT block. Dispositions follow in a separate comment.

REPORT
verdict: BLOCK
risk: CRITICAL
findings:

1. [CRITICAL] Shared UUIDs defeat identity liveness and permit ungated UUID reassignment.
   - Evidence: `scripts/build_series_catalog.py:672-675,969-998,1117-1150,1235-1262,1383-1405`.
   - Reproduction: re-key two identities, swap their prior-catalog UUIDs, and run the writer without `--allow-remint`. It returned `minted=2, superseded=0`; `--check`, HEAD-prefix, and base-prefix verification all passed. The registry retained the old bindings and added swapped bindings as ordinary mints.
   - Live-artifact variant: appending a new identity with an existing row’s UUID produced 202 live bindings but only 201 catalog rows; writer and `--check` passed and `registry_agreement_problems=[]`.
   - Ordinary mints must forbid UUID reuse. Legitimate merge/enrichment sharing needs an explicit linked event and identity-aware liveness.

2. [HIGH] The current PR’s registry bootstrap has no CI-enforced historical continuity.
   - Evidence: `.github/workflows/ci.yml:50-69`; `scripts/build_series_catalog.py:1284-1287,1352-1359`.
   - PR #128 targets `73e4287`, which has no registry; `2859ecb` likewise has no registry. The workflow substitutes an empty base, and every registry extends empty bytes.
   - Reproduction: coherently reminting all 201 catalog and registry UUIDs yielded `66 passed`, bare `--check` success, and append-only success against the empty base. Only comparison with the original registry blob detected it.
   - New-branch pushes have the same gap because all-zero `github.event.before` skips the gate at `.github/workflows/ci.yml:51-54`.

3. [HIGH] Global docket name claiming silently discards dimension-distinct seed identities.
   - Evidence: `scripts/build_series_catalog.py:1036-1052,1053-1086`.
   - Reproduction against the live artifact: add a US docket entry named `boe.bank_rate`. The existing GB observation globally claims that name, so regeneration remains at 201 rows, changes only the seed digest, and passes `--check`; the US identity is absent.
   - Two same-name docket entries for different countries are order-dependent: only the first survives. A curated alias on an unrelated geography can similarly suppress a docket entry.

4. [HIGH] Placeholder enrichment ignores an explicitly conflicting geography vintage.
   - Evidence: `scripts/build_series_catalog.py:602-608,626-640,963-998`; vintage is otherwise identity-bearing at `:443-457`.
   - Reproduction: a docket-only US/vintage-2020 placeholder followed by a US/vintage-2024 observation inherited the same UUID without approval. The writer returned `minted=1, superseded=0`; two live bindings shared the UUID and `--check` passed.
   - Unknown placeholder vintage may enrich, but two present and unequal vintages must conflict.

5. [HIGH] Direct period spellings can still silently erase semantic identity dimensions.
   - Evidence: direct variants are generated at `scripts/build_series_catalog.py:257-284` and stripped before parsing/auditing at `:399-405`; only overlap-classified strips reach the audit header at `:540-545`.
   - Reproduction: `agency.statute.2026_06.rate` for June and `agency.statute.rate` for July merged into one two-observation row. `suspect_segments` and `overlap_stripped_segments` were both empty.
   - Impossible direct variants also bypass detection when the declared period is malformed: `week_2026_13_40` and `q5_2026` were stripped and merged without suspects.

6. [MEDIUM] A remint of a returning retired identity writes an invalid registry while reporting success.
   - Evidence: UUID mismatch is handled before retired-state revival at `scripts/build_series_catalog.py:969-993`; registry validation rejects superseding a retired binding at `:723-728`, but `stage()` does not revalidate at `:834-842` before writes at `:1469-1485`.
   - Reproduction: retire an identity, restore it with an edited prior-catalog UUID, then run `--allow-remint --remint-note`. The writer returned 0 and appended a supersede; immediate registry reload failed because the predecessor was retired.

7. [MEDIUM] Duplicate JSON member names make registry events parser-dependent.
   - Evidence: registry lines use ordinary `json.loads` at `scripts/build_series_catalog.py:684-702`.
   - Reproduction: a supersede line containing duplicate `uuid` and `supersedes` members passed under Python’s last-value interpretation; writer and `--check` passed. A first-value consumer sees a different UUID and invalid chain.
   - Duplicate members should be rejected during parsing.

8. [MEDIUM] Registry byte handling is not line-ending safe.
   - Evidence: `scripts/build_series_catalog.py:684,839-842,1266-1305`; `.gitattributes:1-5` omits the registry.
   - A valid registry lacking its final LF accepted a new mint, returned success, and wrote `...}{...`; immediate reload failed.
   - A clean `core.autocrlf=true` checkout converted the registry to CRLF while `git status` remained clean, but the HEAD byte-prefix guard falsely rejected it.

9. [LOW] Remint evidence can be visually empty or semantically false.
   - Evidence: `scripts/build_series_catalog.py:711,723-737,1457-1461`.
   - A U+200B-only note satisfied the nonblank requirement for a real remint. A no-op supersede with `uuid == supersedes` also validated and passed `--check`.

disposition-audit:

- Registry bootstrap preserves all 201 UUIDs from `2859ecb`: CONFIRMED.
- Registry sequence exactly reproduces the 201 prior rows: CONFIRMED.
- Actual `6ab4fbe` catalog swap fails: CONFIRMED.
- Uncommitted registry rewrites fail the HEAD-prefix guard: CONFIRMED.
- Cross-commit/PR registry rewrites are always caught: REFUTED — the current registry-introduction PR compares against empty bytes.
- Ordinary same-key remint and drop ceremonies are gated and chain correctly: CONFIRMED.
- Every identity change or UUID loss requires that ceremony: REFUTED — re-keyed/shared-UUID states bypass it.
- Bare-registry rebuild is gated: CONFIRMED.
- Dimension keys are injective for delimiter/null variants: CONFIRMED.
- Ordinary alias inheritance is geography/entity/vintage scoped: CONFIRMED.
- Docket processing and placeholder enrichment preserve that scope: REFUTED.
- `source_concept` is provenance rather than identity: CONFIRMED.
- Migration removed 82 machine alias instances and retained only two source-label-only curated links: CONFIRMED.
- Row 104 records the FNS base concept only in `source_concepts`: CONFIRMED.
- Catalog UUID spelling/version/parsed uniqueness enforcement: CONFIRMED.
- Registry UUID uniqueness enforcement: REFUTED — canonical duplicate values across identities are accepted.
- Missing docket seed fails write and check modes: CONFIRMED.
- Valid disjoint/impossible tokens are retained and suspect-flagged: CONFIRMED.
- Statute/cohort/edition-like tokens can never be silently stripped: REFUTED.
- All non-direct live overlap strips are audited, with exactly eight current entries: CONFIRMED.
- Partial deletion of an ordinary unique-UUID row is detected: CONFIRMED.
- Shared-UUID liveness prevents silent partial re-keying: REFUTED.
- Push append-only enforcement covers ordinary nonzero-before pushes and fails on unfetchable bases: CONFIRMED.
- Push enforcement covers new branches: REFUTED.
- Current artifact counts and heals—201/155/46, FNS 54-way, BoE count 2, both M3 observed, Eurostat separation, zero suspects, empty ambiguous aliases: CONFIRMED.
- No identity moved geography/entity/vintage versus `2859ecb`: CONFIRMED.
- Unit and cadence conflicts remain hard errors: CONFIRMED.
- Observation, seed, and registry digests bind exact bytes; undeclared-country docket rows retain null geography: CONFIRMED.

residuals-judgment:

- Initial-claims pair left separate: ACCEPTABLE — inconsistent raw naming/metadata remains visible, and conservative separation avoids an unreviewed merge.
- Housing-starts pair left separate: ACCEPTABLE — likely duplication is transparent and can be curated separately.
- Industrial-production pair left separate: ACCEPTABLE — same rationale; no UUID is silently absorbed.
- Dormant retired registry bindings: ACCEPTABLE — explicit retire/revive events preserve history and the original UUID.
- Enrichment creating a second live binding for one UUID: UNACCEPTABLE — it powers the forged-binding, liveness, re-key, and UUID-permutation attacks.
- One-time offline alias migration: ACCEPTABLE — the final diff independently verifies the 82 removals, two curated retentions, and unchanged UUID/dimension map, though archiving the migration script would improve provenance.

validation-record:

- `UV_CACHE_DIR=/tmp/ledger-review-uv uv run pytest tests/test_build_series_catalog.py -q` — PASS, 66 tests.
- `UV_CACHE_DIR=/tmp/ledger-review-uv uv run ruff check scripts/build_series_catalog.py tests/test_build_series_catalog.py` — PASS.
- `python3 -m doctest scripts/build_series_catalog.py` — PASS.
- `python3 scripts/build_series_catalog.py --check` — PASS, 201 series.
- `git diff --check 2859ecb..2c31ae4` — PASS.
- Temporary-copy regeneration — catalog and registry byte-identical; SHA-256 values unchanged; `minted=0, superseded=0`.
- `2859ecb` continuity audit — 201 common identities, 201 UUIDs preserved, zero additions/drops/mismatches.
- Historical `6ab4fbe` swap — correctly failed with remint, stale-catalog, and registry-agreement errors.
- Missing seed — correctly failed in write and check modes.
- Uppercase, hyphenless, and braced UUID duplicates — correctly rejected; direct validation reported noncanonical form and parsed-value duplication.
- Registry line rewrite — correctly failed both HEAD-prefix and explicit base-prefix verification.
- Normal remint ceremony — refusal/no-write without flag, note required, valid supersede appended, chain reload and final check passed.
- Drop/retire/revive ceremony — refusal without approval; allowed retirement and same-UUID revival both checked green.
- Ordinary partial catalog deletion — stale/liveness failure, followed by same-UUID restoration.
- FNS, BoE, M3, Eurostat, initial-claims, housing, and industrial-production raw-data spot checks — faithful dimensions, units, cadence, sources, source concepts, and counts.
- Live artifact UUID audit — 201 canonical unique catalog UUIDs and 201 canonical unique registry UUIDs; no current shared values.
- Adversarial temporary Git/copy experiments reproduced every ranked finding above; no command exceeded the runtime limit and the full repository suite was not launched.
- Final `git status --short --branch` — no tracked changes; only the four permitted `review-context-*.md` files are untracked.

[MaxGhenis]

Disposition — third review answered (971c032, tidy 7b6daf0)

All nine findings fixed; the identity map is unchanged again (201/201, minted=0, superseded=0, registry still exactly the 201 bootstrap mint lines). A fourth adversarial review is dispatched against the branch head.

1 [CRITICAL] Shared UUIDs / ungated reassignment. Ordinary mints can no longer reuse any bound UUID: the registry keeps a parsed-128-bit ownership map, rejects forged shared-UUID mint lines at load, and the builder refuses to mint an owned UUID (test_mint_never_reuses_a_bound_uuid reproduces your swap attack; test_registry_rejects_forged_shared_uuid_mint your forged-binding attack). The single sanctioned reuse is the new retire + succeeds event pair for docket-placeholder enrichment (test_enrichment_records_retire_and_succeeds_events), live bindings' UUIDs must be unique, and liveness/agreement are identity-aware bijections — each live binding needs a catalog row at exactly its identity with exactly its UUID, both directions (test_agreement_is_identity_aware). Your residual judgment ("second live binding per UUID: UNACCEPTABLE") is thereby adopted: enrichment retires the placeholder binding in the same staged append.

2 [HIGH] Bootstrap continuity + new-branch pushes. The introduction commit genuinely cannot be append-gated (nothing precedes it); the reviewed 201-binding identity→UUID map is now pinned as a sha256 anchor in the test suite (test_identity_uuid_map_matches_reviewed_anchor) — any binding change must edit that constant in the same diff, so a wholesale remint can no longer masquerade as regeneration noise; the anchor's provenance is your own attempt-2 continuity audit. New-branch pushes (all-zero before) now verify against the canonical branch's registry instead of skipping (ci.yml).

3 [HIGH] Global docket claiming. Name claims are dimension-scoped: an entry declaring a country is only claimed by rows in that country (your boe.bank_rate-US repro now mints the US docket-only row), and duplicate docket series ids are hard errors (test_docket_claim_is_dimension_scoped).

4 [HIGH] Enrichment vintage. A placeholder declaring a boundary vintage only enriches observations of that vintage; a conflict mints fresh and leaves the stranded placeholder binding as a gated retire, never silent (test_placeholder_with_conflicting_vintage_never_enriches).

5 [HIGH] Silent direct-spelling strips / malformed periods. The audit now covers every stripped spelling: stripped_segments (27 live entries) replaces the overlap-only list, so a statute/edition label colliding with the row's own period spelling is stripped but published (test_statute_spelling_stripped_but_audited). Malformed periods (month 13, q5, impossible week dates) are hard errors and can no longer manufacture strippable tokens (test_malformed_periods_are_hard_errors).

6 [MEDIUM] Invalid staged chain on retired-identity remint. The writer stages revive-then-supersede for that path, and stage() now revalidates the entire registry grammar over the staged bytes before anything is written — no writer path can put an invalid chain on disk while reporting success (test_remint_of_retired_identity_stages_valid_chain).

7 [MEDIUM] Duplicate JSON members rejected at parse (object_pairs_hook; test_registry_rejects_duplicate_json_members).

8 [MEDIUM] Line endings. Registry bytes must be LF-only and newline-terminated (both hard errors), and .gitattributes pins text eol=lf for the catalog, registry, and seed so autocrlf checkouts can't diverge from blob bytes (test_registry_requires_lf_discipline).

9 [LOW] Note quality. Notes must contain alphanumeric content (zero-width padding rejected) and no-op supersedes (uuid == supersedes) are invalid (test_registry_rejects_hollow_notes_and_noop_supersedes).

Housekeeping: 7b6daf0 removes four review-briefing scratch files an over-broad git add had swept into 971c032, and ignores the pattern.

Validation at head: 81 tests, ruff, doctest, --check (201), byte-idempotence (catalog + registry), and the committed-catalog test now also pins the 27-entry strip audit and the identity-map anchor.