babylon.engine.headless_runner.storage_probe

Collect the run’s storage footprint for the manifest storage block.

Spec: 087-storage-foundations (FR-009/FR-010).

Two layers, mirroring babylon.engine.headless_runner.run_summary:

  • build_storage_block() — pure builder; callers feed pre-shaped per-table stats, unit tests exercise the math.

  • query_storage_footprint() — Postgres-backed collector run once at artifact-emission time. Best-effort by contract: a completed simulation MUST NOT fail because observability could not be collected (FR-010), so any collection error logs a warning and yields None (the manifest simply omits the block).

Semantics note: total_bytes is the whole relation (indexes included) and may contain other sessions’ rows in a shared database; session_rows is exact for this session. Rows/tick is therefore the deterministic regression signal (tools/storage_budget.py); bytes are informational.

Module Attributes

PER_TICK_TABLES

Per-tick append-only table families written by persist_tick_atomic (spec-062 migrations 0011-0025).

Functions

build_storage_block(*, db_total_bytes, ...)

Shape the manifest storage block from pre-collected stats.

query_storage_footprint(*, pool, session_id, ...)

Collect per-table sizes + session row counts from Postgres.
babylon.engine.headless_runner.storage_probe.PER_TICK_TABLES: tuple[str, ...] = ('dynamic_hex_state', 'boundary_flow_register', 'conservation_audit_log', 'dynamic_consciousness_state', 'dynamic_demographics_state', 'dynamic_employment_state', 'dynamic_external_node_state', 'dynamic_relationship_state', 'contradiction_field', 'tick_commit')

Per-tick append-only table families written by persist_tick_atomic (spec-062 migrations 0011-0025). to_regclass guards absence, so older databases probe cleanly.

babylon.engine.headless_runner.storage_probe.build_storage_block(*, db_total_bytes, ticks_persisted, tables)[source]

Shape the manifest storage block from pre-collected stats.

Parameters:

  • db_total_bytes (int) – pg_database_size of the runtime database.

  • ticks_persisted (int) – Fully-persisted tick count (0 for errored runs; rows/tick then falls back to the raw row count).

  • tables (list[dict[str, Any]]) – One entry per probed table with table, total_bytes, and session_rows keys.

Return type:

dict[str, Any]

Returns:

Dict ready to embed under the manifest’s top-level storage key, tables sorted by total_bytes descending.

babylon.engine.headless_runner.storage_probe.query_storage_footprint(*, pool, session_id, ticks_persisted)[source]

Collect per-table sizes + session row counts from Postgres.

Parameters:

  • pool (Any) – psycopg connection pool (connection() context manager).

  • session_id (Any) – This run’s session UUID (str or UUID).

  • ticks_persisted (int) – Fully-persisted tick count for rows/tick math.

Return type:

dict[str, Any] | None

Returns:

The build_storage_block() dict, or None when collection fails for any reason (FR-010 best-effort contract — the run’s success must never depend on observability, so this is a declared broad-catch exemption; the failure is logged at WARNING).