babylon.engine.headless_runner.trace_emitter

Stream the trace.csv artifact from the trace-emission view.

Spec: 064-headless-sim-runner (T025).

The emitter is decoupled from Postgres: it accepts an iterable of TraceRow instances (or row-shaped tuples / mappings) and writes them in the canonical 22-column order. Postgres-backed runs feed it the result of SELECT ... FROM view_runtime_trace_emission ORDER BY tick, entity_id; unit tests feed synthetic fixtures.

CSV format follows contracts/trace_csv_schema.yaml:

  • utf-8 encoding

  • RFC 4180 minimal quoting

  • trailing newline

  • "" for None / NULL (FR-008)

  • header row in the order declared below

Module Attributes

TRACE_COLUMNS

Canonical 22-column ordering.

Classes

TraceEmitter(output_path)

Stream trace rows into a CSV file at the configured path.
babylon.engine.headless_runner.trace_emitter.TRACE_COLUMNS: tuple[str, ...] = ('tick', 'simulated_year', 'entity_id', 'entity_kind', 'v', 'c', 's', 'k', 'p_acquiescence', 'p_revolution', 'ideology_r', 'ideology_l', 'ideology_f', 'surveillance_coupling', 'internet_access_pct', 'biocapacity_stock', 'energy_stock', 'raw_material_stock', 'profit_rate', 'exploitation_rate', 'population', 'employment_proxy')

Canonical 22-column ordering. MUST match contracts/trace_csv_schema.yaml and the SQL view.

class babylon.engine.headless_runner.trace_emitter.TraceEmitter(output_path)[source]

Bases: object

Stream trace rows into a CSV file at the configured path.

Parameters:

output_path (Path)

__init__(output_path)[source]

Open the CSV writer on output_path.

Parameters:

output_path (Path) – Filesystem path where trace.csv will be written.

Return type:

None

property row_count: int

Number of data rows emitted (excludes header).

property path: Path

Filesystem path of the written CSV.

write_row(row)[source]

Emit one trace row in canonical column order.

Return type:

None

Parameters:

row (TraceRow | Mapping[str, Any])

write_rows(rows)[source]

Emit many rows; thin wrapper over write_row().

Return type:

None

Parameters:

rows (Iterable[TraceRow | Mapping[str, Any]])

close()[source]

Flush + close the underlying file handle.

Return type:

None