Phase 0: CLI: simulate and export #61

Merged

erikinkinen merged 4 commits from 0-cli-simulate-and-export into main

2026-03-03 13:20:59 +01:00

erikinkinen commented

2026-03-03 13:18:24 +01:00

Owner

Summary

Implements #20 by adding a unified aes simulate workflow that:

Parses strict CLI arguments
Runs deterministic simulation (linear or branching)
Writes authoritative JSONL event log to disk
Exports final-snapshot metrics as deterministic CSV

Base branch for this PR is 0-metrics-framework (intended to rebase to main later).

Closes #20.

CLI Contract

aes --version
aes simulate --workload <linear|branching> --event-log <path> --metrics-csv <path> [--seed <u64>] [--mode <accumulate|transfer>] [--chain-length <u64> | --depth <u64> --fanout <u64>]

Behavior:

Usage/argument errors: exit 2
Runtime/IO/model errors: exit 1
Success: exit 0

What Changed

Replaced minimal CLI with subcommand parser/dispatcher in cli/src/main.cpp
Added strict flag validation:
- Required flags, workload-specific constraints, duplicate/unknown flag rejection
- Strict unsigned numeric parsing
- Output path non-empty + distinct-path check
Implemented simulation execution path:
- Workload factory for linear and branching
- Deterministic RNG flow (seed + fork("workload"))
- Run exactly workload.total_events()
Implemented event log persistence:
- Collect EventLogRecord (v=0, contiguous t, event, delta)
- Write to <event_log>.tmp then atomic rename
Added metrics CSV export:
- New API: encode_metrics_report_csv_v0(...)
- CLI computes metrics on final engine snapshot and writes CSV atomically

CSV Output Schema

metrics_v,kind,id,count

Rows:

0,total_caps,,<total_caps>
0,caps_per_subject,<id>,<count> (ascending subject id)
0,caps_per_object,<id>,<count> (ascending object id)

Tests

Added/updated coverage for:

CLI parsing and usage behavior
Invalid flag/numeric/combination handling
Deterministic simulation runs
Event log existence + strict replay acceptance
Log determinism smoke test
CSV exact content and determinism
CSV write error path
Metrics CSV encoder behavior in metrics unit tests

All tests pass:

cmake --build _build
ctest --test-dir _build --output-on-failure (33/33 passing)

Commit Structure

Phase 0: Implement CLI argument parsing (#20)
Phase 0: Run simulation from CLI (#20)
Phase 0: Write event log to disk (#20)
Phase 0: Export metrics CSV (#20)

## Summary Implements `#20` by adding a unified `aes simulate` workflow that: - Parses strict CLI arguments - Runs deterministic simulation (`linear` or `branching`) - Writes authoritative JSONL event log to disk - Exports final-snapshot metrics as deterministic CSV Base branch for this PR is `0-metrics-framework` (intended to rebase to `main` later). Closes #20. ## CLI Contract - `aes --version` - `aes simulate --workload <linear|branching> --event-log <path> --metrics-csv <path> [--seed <u64>] [--mode <accumulate|transfer>] [--chain-length <u64> | --depth <u64> --fanout <u64>]` Behavior: - Usage/argument errors: exit `2` - Runtime/IO/model errors: exit `1` - Success: exit `0` ## What Changed - Replaced minimal CLI with subcommand parser/dispatcher in `cli/src/main.cpp` - Added strict flag validation: - Required flags, workload-specific constraints, duplicate/unknown flag rejection - Strict unsigned numeric parsing - Output path non-empty + distinct-path check - Implemented simulation execution path: - Workload factory for `linear` and `branching` - Deterministic RNG flow (`seed` + `fork("workload")`) - Run exactly `workload.total_events()` - Implemented event log persistence: - Collect `EventLogRecord` (`v=0`, contiguous `t`, `event`, `delta`) - Write to `<event_log>.tmp` then atomic rename - Added metrics CSV export: - New API: `encode_metrics_report_csv_v0(...)` - CLI computes metrics on final engine snapshot and writes CSV atomically ## CSV Output Schema `metrics_v,kind,id,count` Rows: - `0,total_caps,,<total_caps>` - `0,caps_per_subject,<id>,<count>` (ascending subject id) - `0,caps_per_object,<id>,<count>` (ascending object id) ## Tests Added/updated coverage for: - CLI parsing and usage behavior - Invalid flag/numeric/combination handling - Deterministic simulation runs - Event log existence + strict replay acceptance - Log determinism smoke test - CSV exact content and determinism - CSV write error path - Metrics CSV encoder behavior in metrics unit tests All tests pass: - `cmake --build _build` - `ctest --test-dir _build --output-on-failure` (`33/33` passing) ## Commit Structure - `Phase 0: Implement CLI argument parsing (#20)` - `Phase 0: Run simulation from CLI (#20)` - `Phase 0: Write event log to disk (#20)` - `Phase 0: Export metrics CSV (#20)`