Add run-summary metrics to the sim and CLI #21

New issue

Closed

opened 2026-07-21 02:57:52 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-07-21 02:57:52 +00:00

Owner

Build the next core simulation step after #20. This is core Rust logic, not Bevy/viewer/deploy work.

Current state on main:

The CLI emits one JSONL snapshot per tick and nothing else. There is no aggregate view of a run.
The original design brief (#11) targets a run-summary output shape: total ticks, ore mined, bars produced, dispatches assigned, and stall visibility.

Goal:

Give the kernel deterministic run-level counters and give the CLI a final summary line, so a long headless run is diffable at a glance without parsing every tick.

Implementation guidance:

Add a metrics module to factory_sim with a RunMetrics struct: per-item mined and crafted totals, dispatches assigned, units collected, units delivered, and idle ticks (ticks that emitted no events).
GameState owns the counters and increments them inside the existing step functions. No parallel bookkeeping in the CLI.
Expose a serializable metrics snapshot from GameState.
After the tick loop, factory_cli emits one final JSON line with a distinguishing key (for example {"summary": ...}) so tick lines and the summary line are mechanically separable.

Acceptance criteria:

cargo test --workspace passes.
At least one test asserts exact summary values for a fixed-tick iron-bars run.
Determinism test extended or preserved: identical runs produce identical metrics.
Tick snapshot lines remain unchanged in shape apart from any addition, and stay deterministic.
docs/factory-sim.md documents the summary line.

Out of scope:

Deadlock detection heuristics beyond the idle-tick counter.
Multiple haulers/sources, recipe breadth.
Bevy, Wasm, viewer, or deploy work.

Build the next core simulation step after #20. This is core Rust logic, not Bevy/viewer/deploy work. Current state on `main`: * The CLI emits one JSONL snapshot per tick and nothing else. There is no aggregate view of a run. * The original design brief (#11) targets a run-summary output shape: total ticks, ore mined, bars produced, dispatches assigned, and stall visibility. Goal: Give the kernel deterministic run-level counters and give the CLI a final summary line, so a long headless run is diffable at a glance without parsing every tick. Implementation guidance: * Add a `metrics` module to `factory_sim` with a `RunMetrics` struct: per-item mined and crafted totals, dispatches assigned, units collected, units delivered, and idle ticks (ticks that emitted no events). * `GameState` owns the counters and increments them inside the existing step functions. No parallel bookkeeping in the CLI. * Expose a serializable metrics snapshot from `GameState`. * After the tick loop, `factory_cli` emits one final JSON line with a distinguishing key (for example `{"summary": ...}`) so tick lines and the summary line are mechanically separable. Acceptance criteria: * `cargo test --workspace` passes. * At least one test asserts exact summary values for a fixed-tick iron-bars run. * Determinism test extended or preserved: identical runs produce identical metrics. * Tick snapshot lines remain unchanged in shape apart from any addition, and stay deterministic. * `docs/factory-sim.md` documents the summary line. Out of scope: * Deadlock detection heuristics beyond the idle-tick counter. * Multiple haulers/sources, recipe breadth. * Bevy, Wasm, viewer, or deploy work.

coilyco-ops referenced this issue from a commit

2026-07-21 03:00:50 +00:00

feat: add run-summary metrics to the sim and cli (closes #21)

coilyco-ops closed this issue

2026-07-21 03:00:50 +00:00

coilyco-ops commented

2026-07-21 03:00:59 +00:00

Author

Owner

Landed on main in fe624a9 (feat: add run-summary metrics to the sim and cli).

What shipped:

New factory_sim::metrics module with RunMetrics / RunMetricsSnapshot: ticks, per-item mined and crafted totals, dispatches assigned, units collected, units delivered, and idle ticks (ticks emitting no events).
GameState owns the counters and increments them inside the existing step functions - mining, dispatch assignment, collect, deliver, and production (whose advance now returns the produced quantity). No parallel bookkeeping in the CLI.
factory_cli emits one final {"summary": ...} JSON line after the tick loop, keeping tick lines and the summary mechanically separable.

Verification:

cargo test --workspace passes - 10 sim tests plus the CLI integration test, including an exact-value summary assertion for a 6-tick iron-bars run and a 12-tick determinism check on metrics.
ward exec test and pre-commit run --all-files both green.
A 12-tick run summarizes as: mined 9 iron ore, crafted 20 iron bars, 3 dispatches assigned, 9 collected, 9 delivered, 0 idle ticks.

WARD-OUTCOME: done

Landed on `main` in `fe624a9` (`feat: add run-summary metrics to the sim and cli`). What shipped: * New `factory_sim::metrics` module with `RunMetrics` / `RunMetricsSnapshot`: ticks, per-item mined and crafted totals, dispatches assigned, units collected, units delivered, and idle ticks (ticks emitting no events). * `GameState` owns the counters and increments them inside the existing step functions - mining, dispatch assignment, collect, deliver, and production (whose `advance` now returns the produced quantity). No parallel bookkeeping in the CLI. * `factory_cli` emits one final `{"summary": ...}` JSON line after the tick loop, keeping tick lines and the summary mechanically separable. Verification: * `cargo test --workspace` passes - 10 sim tests plus the CLI integration test, including an exact-value summary assertion for a 6-tick iron-bars run and a 12-tick determinism check on metrics. * `ward exec test` and `pre-commit run --all-files` both green. * A 12-tick run summarizes as: mined 9 iron ore, crafted 20 iron bars, 3 dispatches assigned, 9 collected, 9 delivered, 0 idle ticks. `WARD-OUTCOME: done`

coilyco-ops referenced this issue

2026-07-21 03:02:52 +00:00

Generalize the world to multiple sources and haulers with dispatch arbitration #22

coilyco-ops referenced this issue

2026-07-21 03:08:22 +00:00

Generalize the world to multiple sources and haulers with dispatch arbitration #22