Import-entry unit family P1: ledger ingest of official trade margins (#615)

[MaxGhenis]

Import-entry unit family P1: ledger ingest of official trade margins

First phase of #615 — the synthetic import-entry unit family. This PR is the ledger leg: official Census/CBP series admitted as ledger-contract facts with full retrieval provenance. No entries are generated here (that is P2, stacked on this).

Source switch (2026-08-05)

P1's primary source is the Census monthly bulk imports database (IMDB), not the International Trade API. Census publishes the complete U.S. Imports of Merchandise database monthly as public no-auth ZIPs:

https://www.census.gov/trade/downloads/{YEAR}/Merch/im_m/IMDB{YY}{MM}.ZIP

(URL pattern verified live 2026-08-05: all 18 archives 2025-01→2026-06 HEAD-checked 200, 118–292 MB each, ~3.3 GB total.) Eighteen GETs replace thousands of 500-prone per-chapter API queries — the API's biggest chapters (84/85/87) time out server-side after ~150 s and need recursive prefix-splitting to materialize at all. The bulk archives carry strictly more detail, and each one ships with the publisher's own control-total files and record layouts, so reconciliation runs against the archive's own published totals.

The API ingest stays in the tree as the independent cross-check leg (census_imports.py, including the prefix-split machinery): the same series fetched over a second official channel, compared cell-for-cell on a stratified sample. Two official channels agreeing is stronger provenance than either alone. The bulk path does not depend on any API code.

Reference implementation for the file geometry: Yale Budget Lab's tariff model parses these exact ZIPs (src/io/build_import_weights.R, HS10 × country consumption imports); its six parsed field positions match the layouts shipped inside the archives (Documentation/IMP_DETL.lay), which are what imdb_bulk.py transcribes.

What's in the box

packages/populace-build/src/populace/build/us_runtime/us_trade/:

• imdb_bulk.py — the primary ingest. Streams each monthly archive's fixed-width IMP_DETL detail (HTS-10 × Schedule C country × country subcode × district of entry × district of unlading × rate provision) with 22 monthly measures: customs value (con_val_mo), dutiable value, calculated duty, charges, CIF value, both unit quantities, card counts, and air/vessel/containerized-vessel transport splits (value/weight/charges). Every row's embedded statistical period must equal the archive month (a mislabeled row fails the ingest, never silently drops). Reconciliation is exact-integer against the publisher's own in-archive control totals on three independent axes: by country (IMP_CTY), by commodity (IMP_COMM, also the source of units of quantity), and by district of entry (IMP_DE) — any difference fails the build.
• census_imports.py — the API cross-check leg (unchanged from the lane-G implementation: byte-cached responses, sha-256 manifests, key elision, DET/CGP handling, publisher - totals, prefix splitting for the giant chapters).
• census_country_bridge.py — the Schedule C → ISO-2 bridge vendored verbatim from axiom-oracles reference/us-tariff-panel/census_iso_bridge.csv (241 rows), hash-pinned and verified at load. Fail-closed: an unmapped country code aborts the assembly. Both legs bridge through the same table.
• cbp_entry_stats.py — CBP fiscal-year entry-summary anchors (total/informal entry summaries, import value, duty collected) parsed from archived bytes of the public CBP Trade Statistics page; only exact-integer cells become facts. In-progress fiscal years are encoded as fiscal-year-to-date record sets with an explicit as-of endpoint parsed from the page's own "updated as of" note (…fytd.fy2026_as_of_2026_07_27, period.type = fiscal_year_to_date with start/as_of); only completed fiscal years mint fiscal_year facts. The as-of parse fails closed (round 3): the scan is scoped to the text between the entry-summaries table and the next table — the live page carries three "updated as of" notes and the Trade Remedy table's differently-dated one must never become this table's endpoint — and any as-of wording the strict pattern cannot read, conflicting dates, or a missing table note while as-of wording exists elsewhere on the page raises instead of falling back to the retrieval date. The retrieval-date fallback survives only for pages with no as-of wording at all, and the fact builder independently refuses stats carrying a note without a parsed date. Still the only public entry-count series located; the P2 size distribution stays an explicit assumption anchored to these totals.
• import_entry_facts.py — consumer-artifact emission (policyengine_ledger.consumer_artifact.v1 / ledger.consumer_fact.v1) at five grains now: national, chapter, country, chapter × country, and district of entry (new, from the publisher's own district table, carrying its own IMP_DE source leg — round 3: district values come from the IMP_DE control file, and both source_table members say so; the margins feed keeps its IMP_DETL identity). Source identity is channel-parameterized (FactSourceLeg): record-set ids and populace-namespace fact keys are identical whichever channel supplied the bytes (P3 selector stability), while each row's source block records the actual retrieval channel, file, and sha. Customs value carries concept_alignment to the composed tariff spine's #input.customs_value (exact, Census definition quoted); calculated duty aligns to the total ad-valorem rate as related, never gating (Synthetic import-entry unit family: ledger-margin-generated trade entries, engine-runnable #615).

Plus tools/build_us_import_entry_margins.py (end-to-end bulk build: verify/adopt archives → parse → reconcile → staged, atomically published margins/totals/district parquets + per-month full-detail parquet + consumer artifact + build report; publication is windowless on every steady path — a single-syscall directory exchange (renamex_np(RENAME_SWAP) on macOS, renameat2(RENAME_EXCHANGE) on Linux) where the filesystem offers one, and a symlink layout elsewhere (the public name is a symlink retargeted by one atomic rename of a prepared sibling link, so it never vacates on any POSIX filesystem; round 4 replaced round 3's windowed two-rename fallback). Every destructive step is preceded by a durable fsynced recovery marker — written before the exchange too, so a set displaced by a crash mid-cleanup is reclaimed — and a publisher lockfile refuses concurrent builds toward the same destination, taking over only dead same-host holders) and tools/crosscheck_us_import_margins_api.py (the stratified, gated API comparison), and 103 trade tests (bulk ingest 35 incl. a synthetic in-test archive builder, a rename spy proving the public path resolves across every publisher rename, and subprocess kills at the retarget, inside the legacy migration, and between exchange and cleanup; archive-fidelity goldens 13, facts 26, crosscheck 17, API leg 12 — parse, reconciliation-failure, duplicate-control-key, off-period, truncation, bad-country, adoption, atomic-publication interruption/recovery, lock refusal/takeover, FYTD, as-of fail-closed mutations incl. HTML entities and impossible dates, golden-layout machine-checks, write-spied cache reuse, and offline CLI subprocess paths).

What the bulk source upgrades (previously documented gaps)

1. District splits — lane G recorded "district/mode splits: not free at this grain; skipped." The archives carry district of entry and unlading in the detail grain. This PR emits the publisher's district-of-entry table as a parquet artifact + feed facts (census_intltrade.imports_district_entry.*), reconciled exactly against the detail.
2. Mode/transport splits — air, vessel, and containerized-vessel value/weight/charges now ride the margins and detail parquets as published columns.

What the bulk source does and does not ground (all source-verified; corrected in review round 1)

• No postal/informal/entry-type marker. Rate-provision codes classify free vs dutiable status only (census.gov/foreign-trade/reference/rpcodes.html — codes 00–19 free variants, 61–79 dutiable variants). The transport splits are air/vessel/containerized. is_postal_shipment therefore remains a documented P2 assumption.
• cty_subco is the published Country SubCode — the special trade-agreement / preference-program claim (0 = no program, A = GSP, S = USMCA, …; census.gov/foreign-trade/reference/codes/csc.html). Carried through the detail parquet as an analytic dimension; aggregated over for margins. (Round-1 correction: originally described as unenumerated.)
• cards_mo is defined: "Number of Detailed Records, Current Month" (the published import detail file structure). It counts detail records, not entry summaries, so it is still never used as an entry-count anchor — but it now also serves as a reconciled control measure that protects every detail row with current-month activity. (Round-1 correction: originally described as undefined.)
• District 70 is Schedule D "LOW-VALUED IMPORTS AND EXPORTS" — the publisher's own low-valued-shipments aggregation, present in all 18 months of the district margins (~$2.0–3.4 B/month customs value, zero calculated duty). Not postal, not an entry-type flag, but a real published low-value split the earlier draft wrongly implied did not exist. (Round-1 correction.)

Review round 1 (sol, adversarial): REQUEST-CHANGES → hardening landed

The round-1 review found real weaknesses, all addressed in c05884de: reconciliation expanded from 4–6 measures to every measure each control file publishes (22 commodity / 18 country / 18 district) plus two-directional key-set equality; fact provenance made fail-closed (months without manifest coverage refuse to mint, empty retrieval manifests refuse to write, channel-correct observed_measure, bridge hash pinned in the artifact generator); CBP's volatile "as of" note moved out of identity dimensions; CBP semantic keys made fiscal-year-invariant; district facts keyed on code only; the cross-check tool now gates on API-leg reconciliation failures and publisher-total drift with an offline test battery; the build CLI streams months (bounded memory) and clears stale outputs; the fixture's full-width row makes one-character colspec shifts fail reconciliation; and three overclaimed "no published definition" statements were corrected against the sources (previous section). The checkpoint string-dtype environment-stability fix (45089b27) repairs a latent #614-class defect the new pyarrow dependency surfaced in every venv.

Structure facts established empirically (recorded, tested)

• The monthly archives are year-to-date cell unions: a cell active in any earlier month of the statistical year persists with all-zero monthly measures (2025-12: 3.51 M detail rows, ~0.81 M with monthly activity). The margins table keeps one row per cell with monthly activity (matching the API leg's semantics); the full published union rides the per-month detail parquet.
• Every archive in the window is a single-period snapshot (all rows carry the archive's statistical period — scanned across all 18 files) and measures are explicit integers in every row (zero blank measure cells in a full-file scan), which is what the fail-closed parse assumes.
• 2026 archives name members *.TXT (2025: *.txt); member lookup is case-insensitive and requires exactly one match.
• Prior-year archives are re-generated by Census with revised statistics (the 2025-01 archive's inner files are dated 2026-03), i.e. the bulk channel serves the current revision like the API does; the cross-check leg tests this directly.

Decisions to note

1. Producer identity / repo home (unchanged from lane G): facts are populace-minted in a populace_us_trade.* key namespace — not an export of a PolicyEngine/ledger build — and every row's extraction_method plus the artifact generator block say so. The ledger repo's declarative source-package harness hand-enumerates selector rows per fact and cannot express a 10⁵–10⁶-cell series; if it grows a bulk contract, these facts relocate by reproducing the same rows there.
2. Channel-invariant fact identity. record_set_id stays census_intltrade.imports_hs10.* under the source switch — the statistical series and publisher are unchanged; the channel is provenance, not identity. Semantic fact keys are therefore stable across lane G's API pulls, this build, and any future channel.
3. Volume split. The JSONL feed carries the five coarse grains; the full HTS-10 × country × month margins and the complete per-month publication-grain detail ride parquet artifacts (runtime inputs, sha-pinned in the build report — not committed, household-feed convention).
4. USITC DataWeb: still no API token (documented gap); Census calculated-duty/dutiable-value series cover the duties validation leg from official data. CBP entry counts: FY national totals only.

Build evidence (full 18-month window, built at the hardened ingest)

• Window 2025-01 → 2026-06 (18 monthly archives, ~3.3 GB, each sha256-recorded with retrieval timestamps).
• 38,841,305 detail rows parsed → 3,070,851 margin cells (HTS10 × country × month with monthly activity), 325,524 publisher commodity-total rows, 792 district rows; 19,224 distinct HTS10, 233 countries (all bridged to ISO-2, zero unmapped), 44 districts.
• Reconciliation: 0 failures across all 18 months under the full gates — every published measure on all three control axes (22 commodity / 18 country / 18 district) plus two-directional key-set equality and duplicate-control-key rejection, exact-integer. Machine-readable per-month evidence is committed in-branch (below).
• 302,318 consumer facts (national + chapter + country + chapter × country + 1,584 district facts + 4 CBP anchors, the FY2026 ones FYTD-labeled); artifact round-trips populace's loader against facts_sha256 and the manifest hash.
• Determinism: four independent full builds across the review rounds produced byte-identical margins/totals/district parquets and per-month detail parquets (identical sha256s below — the round-3 build reproduced every data artifact byte-for-byte through all seven review changes); the facts file changed only through the review rounds' designed provenance changes (round 3: request-time CBP retrieved_at, IMP_DE district source tables; current sha below). The round-3 build re-archived the live CBP page: its boilerplate bytes differ from the round-2 capture but the entry-summaries table and as-of note are byte-identical — same four exact cells, same fy2026_as_of_2026_07_27 record set, no fact-identity drift.
• Plausibility: monthly national customs value $250–340 B; effective calculated-duty rate 2.2 % (2025-01) rising to ~10.5 % (fall 2025), easing to ~6.8 % (2026) — the known tariff trajectory.

margins_hts10_country_month.parquet  f7f88f5824112d1a9c6beaaf4addc9b15f795f6ba6d6e4447e72957731c29607
census_totals_hts10_month.parquet    62f9fd431e86c14525c4e30fb3456670e5591c8e9720e9395ddec17edc4480d8
district_entry_month.parquet         5d508ba6cd8c719567060dcde5885ad58beb654563cf1df0254e9230edd3f652
consumer_facts.jsonl                 7cd155161ebb77ea4b5145a1d5f61c5e28a85345ea0a18dad729a34afa8179f8
consumer manifest.json               75dc57a69f44731718078bfc2bdfbed926eff14903fa90f25fdf35f2dbd73da0

Committed evidence pack (docs/evidence/us-import-entry-margins/)

The run's claims are reviewable and recomputable in-branch, not prose: build_report.json (per-artifact sha256s incl. all 18 per-month detail parquets and per-month reconciliation-evidence hashes), source_manifest.jsonl (18 archives + the archived CBP page: URL, sha256, size, retrieval timestamps), reconciliation/period=YYYY-MM.json × 18 (per-axis key sets, duplicate-key verdicts, per-measure compared/matched cell counts with both sides' integer totals), and crosscheck_api_report.json (below). Chain of custody: the golden pack's archive sha256s equal the source-manifest rows for both golden months; heavyweight artifacts (3.3 GB of archives, ~1 GB of parquet) stay outside the repo with every byte pinned here.

Cross-check evidence (API leg, gated — exit 0)

Stratified sample of 16 (month × chapter) pairs covering the 500-prone giants (84/85/87), small and mid chapters, both statistical years, and both window endpoints (2025-01, 2026-06): 108,977 HTS10 × country cells compared exact-integer on all four dollar measures — 0 mismatches, 0 publisher-total mismatches, 0 API-leg internal reconciliation failures, 0 absent-totals pairs. The report pins both input parquets by sha256 (equal to the build report's) and every pair's fetched API retrieval manifest. The gate fails on any mismatch, missing counterparty, or an empty comparison.

One comparator defect surfaced by the live run and fixed (ce6753da): the API serves YTD-union rows — after January it returns cells (and - totals) with all-zero month measures for pairs active earlier in the statistical year, which the bulk detail legitimately omits. Zero on one channel with silence on the other is agreement, not divergence; these are now counted per side in the report (45,220 zero-union cells; 427 = 427 zero-carrier totals per side across the sample — the two channels carry identical carrier sets), while one-sided cells or totals carrying any nonzero measure still gate.

Round 3 hardened the comparator's predicates and re-ran the gated check against the round-3 build (exit 0, same 108,977 cells, 0 everything): activity is one predicate on both legs — any nonzero dollar measure OR any published nonzero quantity — so a zero-dollar quantity-bearing total can never be misfiled as a zero carrier (F3), and an active pair with no API totals slice gates even when the bulk totals slice is empty too — the totals leg can never pass by comparing nothing (F4); both r2 probes are committed tests. The committed report also carries repaired retrieval provenance (F7): the pre-fix code had rewritten every cached split marker's retrieved_at on each reuse, so the cached values corresponded to no actual request; the stale markers were deleted and the overloads re-observed live, meaning every timestamp in the committed report is the moment of a real HTTP event (markers from this run's live probes; split-response descendants keep their original cached retrieval timestamps).

Review round 2 (sol, adversarial, on the filed PR): REQUEST-CHANGES → all findings closed

1. Archive fidelity (F1) — committed an 84 K golden pack: the four official .lay layout members × both golden months verbatim plus feature-selected raw records with expected literals, sha-bound to the download manifest; a machine-check test re-derives the colspecs from the official .lay bytes, and raw records run through the real parser (8c6f6e39).
2. Atomic publication (F2, critical) — the build now stages to a temp directory and rename-swaps; a failure test with a pre-populated output dir proves byte-identical survival of prior outputs, and a success test proves stale-file removal (fcab9332).
3. Reconciliation evidence + duplicate control keys (F3) — machine-readable per-month reconciliation records committed in-branch; duplicate control keys now reject per axis, including sol's byte-identical-duplicate repro (fcab9332, 575a4833).
4. FYTD (F4, critical) — partial fiscal years no longer mint completed-annual facts (see cbp_entry_stats.py above; tests re-encoded, plus complete-year/disjointness/fallback tests) (468d0337).
5. Provenance (F5) — observed_measure is channel-correct for bulk facts; CBP source_file names the actual archived filename; verified_at/retrieved_at split (adopted archives without a download manifest record no retrieved_at rather than a wrong one); the artifact writer refuses manifest entries without retrieval timestamps; the build report hashes the consumer manifest (fcab9332).
6. Bridge pinning (F6) — provenance cites the immutable axiom-oracles commit URL (9310d19b…), the vendored CSV is verified byte-identical to that commit, and bridge_provenance.json is vendored, pinned, and cross-bound in the loader (8c6f6e39).
7. Crosscheck gates + evidence (F7) — absent API totals and empty comparisons now gate (exit 1); the report carries input parquet sha256s and per-pair API retrieval manifests; the sample covers the 2026-06 endpoint; live gated run committed (previous section) (fcab9332, ce6753da).
8. CI + lint + changelog (F8, blocking) — the two 3.14 full-suite failures were Canonicalize string dtypes at every pool serialization boundary (#578: run-7 publication failure) #614's raw-HDFStore assertions demanding storage pandas fixed-format HDF does not persist; tests re-pinned to the persistable contract with an option-pinned exact form and a pyarrow-default regression test (c1bc2de5); ruff I001 ×2 fixed; changelog fragments added.

Nits: measure counts corrected here to 22/18/18, window-endpoint sample now includes 2026-06, test count corrected (74 then; 91 after round 3; 103 after round 4), the district grain now rides ALL_IMPORT_ENTRY_FACT_GRAINS beside the four margins grains (documented: it is emitted from the publisher's district table, not the margins), and strict key-shape gates added (hts10 exactly \d{10}, country/district code shapes).

Review round 3 (sol, adversarial): REQUEST-CHANGES → all seven findings closed

1. Atomic publication had a crash window (F1, high) — the double rename let readers observe ENOENT between the renames, and a kill inside the window stranded the previous publication under .previous-*. Publication now exchanges staging and destination in one syscall (renamex_np(RENAME_SWAP) / renameat2(RENAME_EXCHANGE); the test suite asserts the swap wherever the filesystem offers it, verified live on the build machine's APFS), so the published path exists at every instant. Filesystems without an exchange fall back to a two-rename swap guarded by a durable recovery marker; _recover_interrupted_publication rolls any interruption forward (staged set intact — it was complete by construction) or back (previous publication restored) at the next build. The interruption test kills the fallback swap between its two renames with os._exit(9) in a subprocess and proves recovery republishes the staged set; in-process second-rename failure restores the previous publication immediately (1cb72f85).
2. As-of parsing could fail open (F2, high) — unrecognized note wording parsed as "no note", after which the fact builder substituted the retrieval date; rewording the note to a single fiscal year silently recreated the partial-FY bug. The parse now fails closed (scoped scan, unreadable-wording/conflicting-dates/displaced-note raises — details in the cbp_entry_stats.py bullet above); the single-fiscal-year wording itself now parses, so the r2 probe yields correctly-labeled FYTD facts, which is the committed mutation test. Developing this against the real archived page immediately caught the Trade Remedy table's unparseable "All programs updated as of:" note — the fail-closed design had to be scoped to the entry table's own note to be honest (130b92b9).
3. Totals activity ignored quantities (F3, high) — one shared activity mask (dollars OR published nonzero quantities) now serves the cell leg and both totals legs; sol's zero-dollar quantity-7 probe is a test both ways (absent API slice → api_totals_absent; present slice lacking the commodity → one-sided total mismatch) (e2f0b928).
4. The totals leg could pass with no evidence (F4, high) — api_totals_absent now fires for any pair with detail activity (compared cells or active one-sided cells) even when the bulk totals slice is empty; sol's matching-detail/empty-totals probe is a test, plus a no-false-gate test for genuinely inactive pairs (e2f0b928).
5. CBP retrieved_at predated the retrieval (F5, medium) — the archiver captures the timestamp at the HTTP read (its signature no longer accepts an outside timestamp at all) and that manifest value feeds the facts; the round-3 build's committed evidence shows retrieved_at 23:41:40Z vs build start 23:34:50Z (1cb72f85).
6. District facts named the wrong source member (F6, medium) — a dedicated IMDB_DISTRICT_SOURCE_LEG names the IMP_DE district-of-entry control totals in both observed_measure.source_table and source.source_table (and the extraction-method text); the margins feed keeps IMP_DETL, with the contrast asserted in tests, and the committed round-3 facts carry the corrected identity (365fcf14).
7. Cache reuse rewrote provenance (F7, medium) — resuming over a warm cache re-minted every split marker with a fresh retrieved_at and rewrote its sidecar despite making no request. The cached overload verdict now travels with its on-disk marker and is reused verbatim — original timestamp, zero writes; the test resumes the split tree against a chmod 555 cache directory with a fetch stub that refuses to be called and proves every cache byte unchanged. The already-rewritten markers on disk were deleted and re-observed live so the committed crosscheck evidence carries only real request timestamps (365fcf14).

Review round 4 (sol, adversarial): REQUEST-CHANGES → all seven findings closed

Sol's next pass audited the closures above and returned seven edge-case refinements; each is closed with machinery and a test that re-runs sol's own probe.

1. Fallback publication still non-atomic (high) — the exchange-less two-rename swap preserved the ENOENT window, the marker was not durable, and nothing serialized concurrent publishers. Steady-state publication is now windowless everywhere: exchange where the filesystem offers it, otherwise a symlink layout whose public name is only ever touched by one atomic rename of a prepared sibling link. First publication probes the filesystem and starts exchange-less deployments symlink-based; the only remaining window is the one-time migration of a legacy real directory on an exchange-less filesystem (plain renames cannot atomically replace a populated directory), marker-guarded with both kill points tested to roll forward. Markers are durable before every destructive step (bytes fsynced → renamed in → directory entry fsynced); an O_EXCL publisher lockfile refuses live same-host and all foreign-host holders and takes over dead same-host ones. A rename spy asserts the public path resolves before and after every rename the publisher issues (ebe3b3f6).
2. Post-exchange strand (medium) — a hard exit between the exchange syscall and staging cleanup left the displaced previous set under .staging-* with nothing recording it. The marker is now written before the exchange, naming the staging path the syscall will park the displaced set under; a subprocess killed inside the cleanup proves recovery reclaims the orphan (ebe3b3f6).
3. As-of parsing failed open on HTML entities (high) — updated as of stripped to unmatchable text and re-created the completed-year mislabeling. _collapse_text/_clean now HTML-unescape after tag-stripping so matching runs against rendered text; the entity variant parses identically and entity-unreadable wording fails closed (d2cb2552).
4. Impossible dates accepted (high) — September 31, 2026 parsed lexically and could mark an incomplete year complete. The parser mints a real datetime.date (Sep 31 / Feb 29 in a non-leap year raise) and the fact builder compares date objects, refusing non-date endpoints including malformed retrieved_at (d2cb2552).
5. Zero-carrier API totals counted as evidence (high) — absence was tested before the activity mask, so a totals slice of all-zero carriers passed the totals leg. Absence is now judged on active API totals gated on pair activity, and the census reconciliation leg gains the coverage half: active detail without a '-' total row is a failure, while zero-carrier detail remains agreement-by-absence (9cb22a84).
6. Truly-empty pair false-gated (medium) — the early empty-API branch set api_totals_absent even with nothing on either side. The branch is deleted — empty slices are typed to the comparison columns and flow the one shared path; a genuinely empty pair (API 204) is asserted not to gate (9cb22a84).
7. Write-free reuse test proved nothing (medium) — a 0555 directory still allows 0644 sidecar rewrites, and one-second timestamp precision let the pre-fix rewrite reproduce identical bytes. The test now spies every write primitive the module can reach and asserts zero write calls plus verbatim marker provenance; spy strength verified against the pre-fix ingest, where it catches the rewrite the 0555 probe missed (eaee47de).

No rebuild this round: the fixes change fail-closed paths, crosscheck gating, tests, and publication machinery — none alter ingest semantics for the archived real inputs, so the committed round-3 evidence pack remains the record (the live page and cached responses parse and aggregate identically under the new code, which is what the batteries assert).

Validation

• Detail sums reconcile exactly (integer USD) against the publisher's own control totals on three axes (country, commodity, district) for every month — enforced in-build, zero tolerance, and the commodity axis also covers both first-unit quantity measures.
• Consumer artifact round-trips through populace's real loader with hash verification; facts compile into ledger target specs with correct value/unit/period metadata (existing battery).
• Vendored bridge byte-identical to upstream axiom-oracles main (sha 4a5a9698…), 241 rows, fail-closed on unmapped codes; the bulk leg's full window bridges with zero unmapped countries.

Part of #615 (P1). P2 (generator) is stacked and follows.