Phase 0: Metrics framework #60

Merged

erikinkinen merged 3 commits from 0-metrics-framework into main

2026-03-03 13:12:51 +01:00

erikinkinen commented

2026-03-03 12:42:15 +01:00

Owner

Summary

Implements Metrics Framework v0 for #19 by adding a dedicated metrics module with snapshot-pure metric computation and a CLI runner that computes metrics from authoritative event history via replay.

Closes #19.

What’s Included

Added new metrics/ module and aes_metrics library target.
Wired module into root build with add_subdirectory(metrics).
Added MetricsReportV0 API with:
- metrics_v (fixed 0)
- total_caps
- caps_per_subject (sparse, deterministic map)
- caps_per_object (sparse, deterministic map)
Added compute_metrics_v0(const sim::Engine&):
- Validates graph invariants first.
- Returns Errc::InvariantViolation on invalid snapshots.
- Counts all stored capability edges (including empty-right edges in v0).
Added deterministic JSON encoder encode_metrics_report_json_v0(...):
- Minified output.
- Stable ordering via map iteration.
Added runner API run_metrics_from_event_log_jsonl_v0(path):
- Replays JSONL log to final snapshot using io::replay_event_log_jsonl.
- Computes v0 metrics and returns encoded JSON.
Added CLI executable aes_metrics:
- Usage: aes_metrics <event_log_path>
- Exit code 2 on bad args.
- Exit code 1 on processing failure (code + message to stderr).
- Exit code 0 on success (JSON + trailing newline to stdout).

Output Schema

Runner emits one minified JSON object:

metrics_v
total_caps
caps_per_subject as [{ "id": <u64>, "count": <u64> }]
caps_per_object as [{ "id": <u64>, "count": <u64> }]

Tests Added

metrics_api_tests (API/interface smoke)
metrics_tests (correctness, sparse behavior, invariant guard, determinism, empty-right edge counting)
metrics_runner_tests (runner success/error paths, CLI usage/error codes, deterministic output shape)

Validation

cmake --build _build
ctest --test-dir _build --output-on-failure

All tests pass (29/29).

## Summary Implements **Metrics Framework v0** for `#19` by adding a dedicated `metrics` module with snapshot-pure metric computation and a CLI runner that computes metrics from authoritative event history via replay. Closes #19. ## What’s Included - Added new `metrics/` module and `aes_metrics` library target. - Wired module into root build with `add_subdirectory(metrics)`. - Added `MetricsReportV0` API with: - `metrics_v` (fixed `0`) - `total_caps` - `caps_per_subject` (sparse, deterministic map) - `caps_per_object` (sparse, deterministic map) - Added `compute_metrics_v0(const sim::Engine&)`: - Validates graph invariants first. - Returns `Errc::InvariantViolation` on invalid snapshots. - Counts all stored capability edges (including empty-right edges in v0). - Added deterministic JSON encoder `encode_metrics_report_json_v0(...)`: - Minified output. - Stable ordering via map iteration. - Added runner API `run_metrics_from_event_log_jsonl_v0(path)`: - Replays JSONL log to final snapshot using `io::replay_event_log_jsonl`. - Computes v0 metrics and returns encoded JSON. - Added CLI executable `aes_metrics`: - Usage: `aes_metrics <event_log_path>` - Exit code `2` on bad args. - Exit code `1` on processing failure (`code + message` to stderr). - Exit code `0` on success (JSON + trailing newline to stdout). ## Output Schema Runner emits one minified JSON object: - `metrics_v` - `total_caps` - `caps_per_subject` as `[{ "id": <u64>, "count": <u64> }]` - `caps_per_object` as `[{ "id": <u64>, "count": <u64> }]` ## Tests Added - `metrics_api_tests` (API/interface smoke) - `metrics_tests` (correctness, sparse behavior, invariant guard, determinism, empty-right edge counting) - `metrics_runner_tests` (runner success/error paths, CLI usage/error codes, deterministic output shape) ## Validation - `cmake --build _build` - `ctest --test-dir _build --output-on-failure` All tests pass (`29/29`).