babylon.engine.headless_runner.reference_data_cache

Per-bridge reference-data cache for the spec-066 bridged headless runner.

Spec: 069-sqlite-cache-optimization.

The spec-066-bridged headless runner’s persist_tick step opens fresh sqlite3.Connection instances per (county, tick) for two reference-data lookups (population, employment-proxy). The returned values are invariant within a calendar year, so under the weekly cadence (year = start_year + tick // 52) the same fetch is re-executed 51 redundant times before the year rolls over.

This module lifts those reads out of the per-tick path into a hydrate-once, year-keyed cache resident on the bridge instance. At WorldStateBridge.hydrate_initial time, the cache issues batched SQL queries against data/sqlite/marxist-data-3NF.sqlite under a single connection (Census-by-(fips, year), QCEW-by-(fips, year)) collectively touching each (county_fips, year) tuple in scope exactly once. Every persist_tick thereafter reads from the in-memory dict; no new SQLite connection is opened on the per-tick path.

See also

specs/069-sqlite-cache-optimization/spec.md — feature spec. specs/069-sqlite-cache-optimization/contracts/reference_data_cache_contract.md

— cache class contract.

specs/069-sqlite-cache-optimization/contracts/instrumentation_contract.md: — bridge read-counter contract.

specs/069-sqlite-cache-optimization/data-model.md — entity inventory. specs/069-sqlite-cache-optimization/research.md — design decisions

(R1-R11).

babylon.persistence.county_aggregation — the legacy fetchers: whose values the cache memoizes; unchanged per spec-069 R10 (II.11 subsystem ownership).

Functions

derive_year_set(start_year, total_ticks)

Enumerate the calendar years touched by a total_ticks-tick run.

Classes

`ReferenceCacheEntry`(**data)	One `(county_fips, year)` tuple's cached reference data.
`ReferenceDataCache`(sqlite_path)	Per-bridge reference-data cache.

class babylon.engine.headless_runner.reference_data_cache.ReferenceCacheEntry(**data)[source]

Bases: BaseModel

One (county_fips, year) tuple’s cached reference data.

population and employment_proxy are independently nullable: Census and QCEW data coverage is asymmetric (see R2 in specs/069-sqlite-cache-optimization/research.md). The four combinations {(present, present), (present, None), (None, present), (None, None)} are all legitimate empirical states.

Frozen: once constructed at hydrate time, never mutated.

Parameters:

population (int | None)
employment_proxy (float | None)

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

population: int | None

employment_proxy: float | None

class babylon.engine.headless_runner.reference_data_cache.ReferenceDataCache(sqlite_path)[source]

Bases: object

Per-bridge reference-data cache.

Contract: /specs/069-sqlite-cache-optimization/contracts/reference_data_cache_contract.

Lifecycle:

Construction: records the SQLite path. No connection opened.
hydrate: opens one connection, issues two batched SQL queries (Census + QCEW), populates the per-tuple entry dict, sets _hydrated = True. One-shot — calling twice raises.
lookup_*: returns cached values. No DB I/O.
mark_*_miss_logged: tracks first-occurrence semantics for missing-data warnings (FR-004 / SC-004).

Parameters:: sqlite_path (Path)

__init__(sqlite_path)[source]

Parameters:: sqlite_path (Path)
Return type:: None

property population_db_reads: int

property employment_db_reads: int

property total_db_reads: int

hydrate(scope_fips, year_set)[source]

Populate the cache by batched SQL against the SQLite reference DB.

Per data-model.md §2 algorithm. Issues two queries under a single sqlite3.Connection (Census-by-(fips, year) and QCEW-by-(fips, year)); the QCEW result feeds both the Census-missing population fallback AND the employment proxy.

Parameters:

scope_fips (frozenset[str]) – 5-digit FIPS codes for the scope counties. Must be non-empty.
year_set (frozenset[int]) – Calendar years in scope. Empty set is allowed (degenerate zero-tick run → no-op hydrate).

Raises:

RuntimeError – If called twice on the same instance.
ValueError – If scope_fips is empty.
FileNotFoundError – If the SQLite file does not exist.
sqlite3.Error – Propagated unchanged on any SQL failure.

Return type:

None

lookup_population(county_fips, year)[source]

Cached population for (county_fips, year).

Returns None for tuples whose underlying data was absent at hydrate time.

Raises:

RuntimeError – If the cache is not yet hydrated.
KeyError – If (county_fips, year) was not in the hydrated scope.

Return type:

int | None

Parameters:

county_fips (str)
year (int)

lookup_employment_proxy(county_fips, year)[source]

Cached employment proxy for (county_fips, year).

Returns None for tuples whose underlying QCEW data was absent.

Raises:

RuntimeError – If the cache is not yet hydrated.
KeyError – If (county_fips, year) was not in the hydrated scope.

Return type:

float | None

Parameters:

county_fips (str)
year (int)

mark_population_miss_logged(county_fips, year)[source]

Once-per-tuple miss-log marker for the population field.

Returns True on the first call for (county_fips, year) and False thereafter. Drives SC-004 (warning at most once per tuple, never once per tuple-tick).

Raises:

RuntimeError – If the cache is not yet hydrated.
KeyError – If (county_fips, year) was not in the hydrated scope.

Return type:

bool

Parameters:

county_fips (str)
year (int)

mark_employment_miss_logged(county_fips, year)[source]

Once-per-tuple miss-log marker for the employment-proxy field.

Returns True on the first call for (county_fips, year) and False thereafter.

Raises:

RuntimeError – If the cache is not yet hydrated.
KeyError – If (county_fips, year) was not in the hydrated scope.

Return type:

bool

Parameters:

county_fips (str)
year (int)

babylon.engine.headless_runner.reference_data_cache.derive_year_set(start_year, total_ticks)[source]

Enumerate the calendar years touched by a total_ticks-tick run.

Under the weekly cadence (year = start_year + tick // 52) the in-scope year set is mechanical:

derive_year_set(start_year, total_ticks) =
{start_year + i // 52 : i in [0, total_ticks - 1]} = {start_year, …, start_year + (total_ticks - 1) // 52}

Parameters:

start_year (int) – Calendar year for tick 0.
total_ticks (int) – Number of ticks in the run.

Return type:

frozenset[int]

Returns:

Frozen set of distinct calendar years touched. Empty for total_ticks <= 0 (degenerate zero-tick run; spec-069 Edge Cases).

Example

>>> sorted(derive_year_set(2010, 520))
[2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019]
>>> derive_year_set(2010, 0)
frozenset()
>>> sorted(derive_year_set(2010, 53))
[2010, 2011]