Accept chronicle-era Chronicle artifact schema ids and fact-key domains; CHRONICLE_* env names (chronicle#143 consumer side)

[MaxGhenis]

Consumer side of the Ledger→Chronicle epoch migration
(PolicyEngine/chronicle#143).
Chronicle will introduce chronicle-era hash domains (chronicle.aggregate_fact.v3,
chronicle.semantic_fact.v3, …) and chronicle-named schema ids
(policyengine_chronicle.consumer_artifact.v2, chronicle.consumer_fact.v2) for
newly emitted rows at a declared cutover; ledger-era ids stay valid history
forever. Dual-domain acceptance has to land in every validator before the emit
flip, so Microcosm accepts both eras starting now. The acceptance half on
Chronicle's side is landing in a parallel lane.

What changed

microcosm.build.chronicle_epoch — one place that knows which identity is which era.
Three rules, encoded rather than asserted:

1. Fact keys are opaque. Microcosm never reconstructs a Chronicle key from a
   payload, so it never needs to know how the domain string feeds the hash.
   Comparison stays exact string equality — correct in both eras. What goes
   dual-era is the question "is this a Chronicle fact key?".
2. No validator hard-codes an epoch. Epoch detection is structural — the
   namespace segment of <namespace>.<family>.v<n>:<digest> — not a lookup in a
   frozen list of domain strings. chronicle#143 declares the v3 spelling only
   for the aggregate and semantic fact families; the version numbers the other
   families will take are not declared yet, and this module deliberately does not
   guess them. chronicle.source_cell.v7:… resolves anyway.
3. Microcosm-minted keys are epoch-independent. They live in Microcosm-owned
   namespaces (microcosm.derived_fact.*, populace_us_trade.*), sit outside
   both eras, and must not move when a source row crosses the cutover.

Only identity strings the spec names explicitly are pinned as literals.

Loading accepts both eras and records which one arrived. The consumer-artifact
manifest's schema_version is a membership test over both eras. provenance()
now carries schema_epoch, fact_key_epochs, and fact_schema_versions
alongside the verbatim observed schema_version, so a release manifest witnesses
which era actually resolved its targets and flags a mixed-epoch feed instead of
silently reporting one era.

Acceptance widened; nothing narrowed. Only the manifest id is gated. The
per-row schema_version is carried and reported, never gated — real feeds stamp
rows from namespaces belonging to neither era, and gating it would fail the build
closed on its own pinned input. The pinned US fiscal-refresh feed
consumer_facts_buildn_v9_4.jsonl declares arch.consumer_fact.v1 on 37,006 of
its 37,405 rows and ledger.consumer_fact.v1 on the other 399;
test_uk_firm_generation.py:584 builds rows in that same arch.* namespace.
Epoch witnessing likewise reads every Chronicle key a published row carries
(nine single-key fields plus two lineage key lists in the captured feed fixture),
not just the four identifiers targets resolve by — Chronicle moves families
independently, so a row can straddle the cutover with a ledger-era aggregate key
and a chronicle-era source-release key.

microcosm.build.logbook_env — the Logbook env dual-read window. This is a
separate Logbook naming cleanup (microcosm#632) riding along on this branch, not
part of the chronicle#143 epoch migration above: POPULACE_LEDGER_URL /
_KEY / _API_KEY / _EXPORT_KEY are the Logbook store's own credentials
(Supabase logbook schema, logbook_writer / logbook_exporter roles), not
Chronicle names — naming the preferred spellings CHRONICLE_* would have
recreated the exact collision the Logbook rename fixed. LOGBOOK_* preferred,
the ledger-era name honored with one DeprecationWarning per process per name
(a build loop reads these repeatedly; one warning, not a storm). One helper,
one table; adding a variable to the window is one row.

Nothing renames on disk or in artifacts. Emitted schema ids, populace_* and
microcosm.* key namespaces, diagnostic field names (ledger_aggregate_fact_key,
ledger_member_fact_keys, ledger_fact_pin, ledger_commit), H5 attributes,
goldens, and fixtures all stay frozen at v1 (#639). No golden was regenerated.

Audit

I audited every site that compares, parses, or mints a Chronicle fact key or
schema id — ledger_targets.py and congressional_district_vintage.py read in
full, plus a repo-wide sweep for ledger.<family>.v<n>, policyengine_ledger,
consumer_artifact, consumer_fact, aggregate_fact_key, semantic_fact_key,
source_cell, dimension_set, concept_alignment, av2:, and every
os.environ read — across 8 surfaces with an adversarial verification pass on
every candidate.

Result: exactly three hard-coded epoch literals exist in non-test source, all
in the two files below. Everything else either carries keys opaquely or mints into
a Microcosm-owned namespace. Every other candidate site was refuted on
verification.

File:line	What it was	How it is epoch-tolerant now
ledger_artifact.py:58	CONSUMER_ARTIFACT_SCHEMA_VERSION = "policyengine_ledger.consumer_artifact.v1"	Now the shared LEDGER_CONSUMER_ARTIFACT_SCHEMA_VERSION, and it names only what Microcosm emits. Acceptance is the set, not this.
ledger_artifact.py:187	schema_version != CONSUMER_ARTIFACT_SCHEMA_VERSION → raise	is_accepted_consumer_artifact_schema_version(...) — membership over both eras; the error names both.
ledger_artifact.py:307	(no per-row schema check existed)	Still none, deliberately. The per-row id is carried and surfaced through fact_schema_versions; gating it would reject arch.consumer_fact.v1, which the pinned release feed stamps on 37,006 rows.
ledger_artifact.py:160-163	provenance() recorded schema_version only	Adds schema_epoch, fact_key_epochs, and fact_schema_versions; the observed id is still recorded verbatim.
import_entry_facts.py:164	"policyengine_ledger.consumer_artifact.v1" literal	From the shared module. write_consumer_artifact(…, schema_version=…) (:612) takes the declared id as an argument, membership-checked over both eras; the default is unchanged, so emitted bytes do not move.
import_entry_facts.py:165	"ledger.consumer_fact.v1" literal	From the shared module; the loader accepts either spelling on the way back in.
import_entry_facts.py:890	mints populace_us_trade.<kind>.v1:<digest>	Unchanged by design. Microcosm namespace, outside both eras, frozen by #639 — and these rows are minted from Census/CBP source bytes, not derived from a Chronicle row whose epoch they could inherit. Pinned by test.
congressional_district_vintage.py:399, 402, 636, 639	mints microcosm.derived_fact.*.v1 / microcosm.semantic_fact.*.v1	Unchanged by design. The digests cover the source row's semantic identity (_translated_fact_key) and the proxy's (source_record_id, geography, value) — never its Chronicle key — so a chronicle-era source mints byte-identical derived keys. Pinned by test; otherwise cutover day would silently re-identify every derived fact a target is pinned to.
ledger_targets.py (all 2203 lines)	—	No epoch literal anywhere in the module. Keys are read through _fact_key/_str_at and compared verbatim; _ledger_fact_index buckets a row under all five key slots, so a pin in either epoch resolves. Left alone, covered by new mixed-epoch tests.
logbook.py:839, 840, 843	os.environ.get("POPULACE_LEDGER_{URL,KEY,API_KEY}")	logbook_env(LOGBOOK_{URL,KEY,API_KEY}_ENV) dual-read.
logbook.py:110	LEDGER_API_KEY_ENV = "POPULACE_LEDGER_API_KEY"	= LEGACY_API_KEY_ENV; the name stays exported for callers and messages.
tools/logbook.py:260-262	os.environ.get("POPULACE_LEDGER_{URL,EXPORT_KEY,API_KEY}")	logbook_env(...); the "remote export requires …" error now names both spellings via describe_logbook_env.
tools/logbook.py:63-64	REMOTE_{EXPORT_KEY,API_KEY}_ENV literals	Bound to the shared legacy constants.
firm_generation.py:168-170	LEDGER_{ONS_TURNOVER,ONS_EMPLOYMENT,HMRC}_BANDS	These only look like env vars to a grep — they are band maps. Chronicle-named aliases added beside them; the ledger-era names stay, since they are what the generator imports.
source_coverage.py:41	LEDGER_US_SOURCE_COVERAGE_CONTRACT_COMMIT	Same: a git commit pin, not an env var. Alias added; the ledger-era name stays because the ledger_commit diagnostic field it feeds is frozen.

Two names from the brief that grep resolves differently, recorded so the next
reader does not go looking:

• LEDGER_TARGETS is not an environment variable. The only matches are the
  DIRECT_LEDGER_TARGETS / INDICATOR_LEDGER_TARGETS module dicts in
  us_runtime/fiscal_targets.py — mapping tables, no epoch, untouched.
• The env vars are spelled POPULACE_LEDGER_*, not bare LEDGER_*; there are
  exactly four (URL, KEY, API_KEY, EXPORT_KEY) and they are the ones the
  dual-read window covers.

Also verified absent, so nothing needed regenerating: no golden under
packages/*/tests/golden/** contains a Chronicle domain string, and no H5
attribute name in the repo embeds ledger.

Tests

New files (both engine-free; tools/ci_test_groups.py --verify places them in
rest / shared-spec, alongside test_ledger_artifact.py, and reports ok):

• test_chronicle_epoch.py (38 cases) — key parsing and epoch resolution for
  both eras, chronicle-era families with undeclared version numbers, Microcosm
  namespaces resolving to neither era, malformed keys returning None rather
  than raising, row/feed epoch reporting across source_cell_keys and
  concept_alignment_key, a synthetic consumer artifact loaded under each
  schema id, a mixed-epoch feed whose provenance witnesses both eras, bare
  feeds, rejection of an unknown manifest id naming both accepted spellings,
  a per-row id outside both eras still loading and being reported verbatim,
  every straddling key field witnessed for its own epoch, and an inventory check
  that grounds the witnessed field list in the captured feed fixture rather than
  in a guess.
• test_logbook_env.py (16 cases) — preferred name wins silently, legacy
  name honored with a warning naming both spellings, the warning fires once per
  process across repeated reads, per-name independence, empty-as-unset, and
  logbook._remote_config() reading both eras.

Added to existing suites:

• test_ledger_targets.py — a mixed-epoch feed compiles to targets whose names
  and metadata carry each row's own key verbatim, and a reference pinned to a
  chronicle-era key resolves.
• test_us_congressional_district_vintage.py — chronicle-era source rows mint
  byte-identical microcosm.derived_fact.* keys on both the vintage-translation
  and state-total-proxy paths.
• test_us_trade_facts.py — the minted artifact still declares the ledger-era id,
  loads under either, and the fact bytes are identical when only the declaration
  moves; a bogus declaration is refused.

uv sync --all-packages --extra us · uv run pytest packages/microcosm-build -q
· uv run ruff check . — all green; full output in the lane report. No
publish, promotion, or release action was taken.

Review fixes (round 2)

Eight findings from the Fable+Sol gate, all addressed. The identity half of
the original PR was wrong about which ids exist, so the correction is
structural rather than cosmetic — everything above this section that
describes a two-id accepted set or namespace-based epoch detection is
superseded here.

The ids were one generation off at both ends

Read from PolicyEngine/chronicle at origin/main this pass, not restated:

Identity	Source	Epoch
policyengine_ledger.consumer_artifact.v2	policyengine_chronicle/consumer.py:30, README line 299	ledger — what Chronicle emits today
policyengine_ledger.consumer_artifact.v1	import_entry_facts.py:164	ledger — what Microcosm mints
policyengine_chronicle.consumer_artifact.v3	chronicle-era successor	chronicle
ledger.consumer_fact.v1	chronicle/consumer_contract.py:28	ledger
chronicle.consumer_fact.v2	chronicle-era successor	chronicle

The accepted set was {policyengine_ledger.consumer_artifact.v1, policyengine_chronicle.consumer_artifact.v2}. That rejects every artifact
Chronicle publishes right now, and names a .v2 chronicle-era id that will
never exist. All three artifact ids are accepted now, and a test loads a
manifest built field for field from build_consumer_artifact on chronicle
main.

There is no origin/epoch-dual-domain branch on chronicle
(git ls-remote --heads origin | grep -i epoch → empty), so the chronicle-era
successors are declared here under the rename rule the spec states — same
family, new namespace, version bumped by one — with the two the consumer
migration pins spelled out. That rule puts source_cell at
ledger.source_cell.v1 → chronicle.source_cell.v2, a version behind the
derived families' v2 → v3.

Epoch is now a declaration, not a parse

DECLARED_IDENTITIES in chronicle_epoch.py is an explicit table of literal
identity strings; DECLARED_IDENTITY_EPOCHS keys it by
(namespace, family, version) → epoch. The ledger-era half is transcribed
from Chronicle's own hash-domain constants (chronicle/core.py,
chronicle/sources/*.py, chronicle/consumer_contract.py), with the file it
came from noted per block.

The previous structural rule read the namespace segment and answered
"chronicle" for chronicle.<anything>.vN. That reports where a key claims
to be from as though it were issued identity — the opposite of what pinning a
fact key is for. chronicle.source_cell.v3 and
chronicle.some_family_nobody_declared.v11 are now labelled undeclared:
parsed, reported in provenance with the domain named
(undeclared_fact_key_domains), never counted as an era. The tests that
certified those spellings as valid are corrected.

Two prose claims went with it. chronicle#143 does not "declare the v3
spelling for the aggregate and semantic fact families" — it lists
"dual-hash window or v3 domains" as open options. That sentence is gone from
the module, the tests, and (annotated in place, dated) the lane journal.

Tests could reach the live Logbook

_remote_config() returns ('https://example.invalid', 'x', 'x') under
LOGBOOK_URL + LOGBOOK_KEY alone. The per-module delenv lists named only
POPULACE_LEDGER_* — they predate the LOGBOOK_* spelling — so a
credentialed developer or runner shell walked straight past them into the
append path of an append-only store.

packages/microcosm-build/tests/conftest.py now carries an autouse fixture
with two independent guards: every variable in the dual-read window is
cleared in both generations (read from the window itself, so adding one there
cannot leave a hole here) plus POPULACE_LOGBOOK_PREV_ROW_DIGEST; and the
Logbook urlopen is replaced with one that raises — on every module holding
it, since tools/logbook.py binds the name at import, and on the opener it
delegates to, which closes the path for any importer the sweep does not find.
allow_logbook_network restores the real callables for a test that means it.
Nothing in the suite asks for it.

Proof, with the polluted environment the finding describes:

LOGBOOK_URL=https://example.invalid LOGBOOK_KEY=x LOGBOOK_API_KEY=y \
LOGBOOK_EXPORT_KEY=z POPULACE_LEDGER_URL=https://legacy.invalid \
POPULACE_LEDGER_KEY=k uv run pytest packages/microcosm-build -q

The rest

• UK release evidence. uk_runtime/calibration_run.py::_ledger_provenance
  rebuilt the block field by field and so recorded the hashes but not
  schema_epoch / fact_key_epochs / fact_schema_versions. It delegates to
  LedgerConsumerArtifact.provenance() now, keeping only the manifest
  sub-block UK-shaped (it feeds the run's identity digest). Covered by a real
  mixed-epoch artifact through run_uk_calibration, asserted in the build
  record and the signed diagnostics build block, plus a property test that
  every shared field reaches the UK block rather than a list that would go
  stale.
• import microcosm.build.logbook_env as env bound the function: the
  barrel re-exported it under its own module's name, and import a.b as c
  prefers an existing attribute. The barrel now re-exports only
  logbook_env_names; regression test included.
• CHRONICLE_US_SOURCE_COVERAGE_CONTRACT_COMMIT now reaches the
  microcosm.build.us_runtime barrel like its ledger-era sibling.
• Non-string schema_version. A JSON list or object raised
  TypeError: unhashable type out of the frozenset membership test, bypassing
  the loader's own message. The predicates are total over JSON; the loader
  raises the documented unsupported-schema ValueError. Parametrized over
  list, object, empty list, empty object, int, bool, and null.
• tools/logbook.py --remote help advertised POPULACE_LEDGER_URL alone,
  so an operator configuring from --help set up the spelling the dual-read
  window exists to retire and then got warned for it. LOGBOOK_* first,
  ledger-era names given as the fallback they are.

Round-2 verification

uv sync --all-packages --extra us                     ok
uv run pytest packages/microcosm-build -q             7116 passed, 47 skipped, 2 failed
  ... with LOGBOOK_* + POPULACE_LEDGER_* all exported 7116 passed, 47 skipped, 2 failed
uv run pytest <the other four shards> -q              all passed (2 engine skips)
uv run ruff check .                                   All checks passed!
uv run python tools/ci_test_groups.py --verify        verification=ok

The polluted-environment run is outcome-identical to the clean one, which
is the guarantee finding 2 asked for. It exports LOGBOOK_URL, LOGBOOK_KEY,
LOGBOOK_API_KEY, LOGBOOK_EXPORT_KEY and all four POPULACE_LEDGER_*
names.

The 2 failures are pre-existing and not this PR's. Both are
test_release_target_parity.py::TestRegeneration, and both fail identically
at this branch's previous head (1f78847c) and at origin/main
(47c74225), verified this session in a throwaway worktree of each:

ValueError: Ledger target reference
'cbo.revenue_projection.ty2024.income_by_source.adjusted_gross_income.projected_amount'
assertion_policy='observed_only' does not allow resolved fact assertion
'source_projection'.

They run only where the pinned feed exists — DEFAULT_FEED_PATH is
~/PolicyEngine/_buildh-runtime/inputs/consumer_facts_buildn_v9_4.jsonl,
outside the repo — and _feed_or_skip skips them everywhere else, so they do
not run in PR CI. Nothing in this PR touches ledger_targets.py,
fiscal_targets.py, tools/build_us_target_parity_manifest.py, or that
test. Recording it because the earlier lane reported this suite as "all
green", which on a machine holding that feed it is not.

uv run ruff format --check . reports 116 files as reformat candidates on
this branch and on its merge base — ruff 0.15.16's formatter against a
repo pinned only to ruff>=0.8, whose CI lint lane runs ruff check and not
ruff format --check. All seven source files this PR touches are clean
before and after. Reformatting the other 116 is not this PR's change to make.

tools/ci_test_groups.py --verify places the new test_logbook_isolation.py
in fast: rest / engine: shared-spec, alongside every other test_logbook_*
file, and reports verification=ok.

No golden was regenerated, nothing renamed on disk, and no publish,
promotion, or release action was taken.

🤖 Generated with Claude Code

[MaxGhenis]

Review (Fable, main): the epoch half is right and lands as specified — structural epoch detection, membership over both manifest ids, per-row ids carried not gated, Microcosm-minted namespaces outside both eras, provenance witnessing the observed era, no on-disk renames. Approving that half as is.

One correction before merge, and it is my brief's fault, not the implementation's: POPULACE_LEDGER_URL / _KEY / _API_KEY / _EXPORT_KEY are not Chronicle variables. They are the Logbook store's credentials (Supabase project populace, logbook_writer / logbook_exporter roles, the logbook schema — see logbook.py's own docstring and logbook/README.md). "Ledger" there is the generic build-ledger sense that was renamed to Logbook on 8/8 precisely so it would not collide with Chronicle, the fact store. Renaming them to CHRONICLE_* would re-create that collision in the one place that had already been disambiguated.

Please rename the preferred spellings to LOGBOOK_URL, LOGBOOK_KEY, LOGBOOK_API_KEY, LOGBOOK_EXPORT_KEY (module logbook_env.py, function logbook_env, test file to match), keep the POPULACE_LEDGER_* legacy names honored with the same once-per-process warning, and drop the chronicle#143 framing from the env half (it is a Logbook naming cleanup that rides along). The CHRONICLE_*_BANDS and CHRONICLE_US_SOURCE_COVERAGE_CONTRACT_COMMIT aliases are fine: those really do translate Chronicle ids and pin a Chronicle commit. A follow-up lane is applying this on the same branch.