Phase 0: Event log format v0 #55

Merged

erikinkinen merged 4 commits from 0-event-log-format-v0 into main

2026-03-03 10:21:52 +01:00

erikinkinen commented

2026-03-03 10:20:06 +01:00

Owner

Summary

Implements Event log format v0 for authoritative history and replay validation (#14).

This PR adds a strict JSONL event log pipeline with:

a v0 record schema (v, t, event, delta)
deterministic encode/decode helpers
append-only log writer
strict log reader with replay + delta verification

Closes #14.

What Changed

Added new io module and aes_io target.
Added EventLogRecord and public APIs in io/include/aes/io/event_log.hpp.
Added JSONL v0 encoder/decoder in io/src/event_log_jsonl.cpp.
Added append-only writer in io/src/event_log.cpp:

appends one minified JSON object per line
newline-terminated writes
explicit flush after each append
Errc::IoError on open/write/flush failure

Added reader in io/src/event_log.cpp:

reads line-by-line
strict schema parsing (unknown/missing fields rejected)
enforces v == 0
enforces contiguous t (starting at 1)
replays each event with apply_event
rejects replay failures and delta mismatches (ParseError)

Wired new module in top-level CMakeLists.txt.
Updated docs/phase0.md with event log record v0 constraints and invariants.

Format Decisions (v0)

Serialization format: JSONL
Top-level keys: exactly v, t, event, delta
event.type: human-readable strings (create_subject, create_cap, etc.)
Rights encoding: string arrays (Read, Write, Exec, Grant, Delete)
delta always includes all canonical fields, including edges_modified
Parsing is strict and rejects schema drift

Tests Added

aes_event_log_schema_tests
aes_event_log_format_tests
aes_event_log_writer_tests
aes_event_log_reader_tests

These cover:

roundtrip encode/decode for event types and deltas
canonical deterministic line shape
strict schema rejection paths
writer append behavior and I/O failures
reader success path
malformed JSON, unknown/missing fields, invalid rights
non-contiguous t
tampered delta detection
replay failure handling

Validation

cmake -S . -B _build
cmake --build _build
ctest --test-dir _build --output-on-failure

Result: 23/23 tests passed.

## Summary Implements **Event log format v0** for authoritative history and replay validation (`#14`). This PR adds a strict JSONL event log pipeline with: - a v0 record schema (`v`, `t`, `event`, `delta`) - deterministic encode/decode helpers - append-only log writer - strict log reader with replay + delta verification Closes #14. ## What Changed 1. Added new `io` module and `aes_io` target. 2. Added `EventLogRecord` and public APIs in `io/include/aes/io/event_log.hpp`. 3. Added JSONL v0 encoder/decoder in `io/src/event_log_jsonl.cpp`. 4. Added append-only writer in `io/src/event_log.cpp`: - appends one minified JSON object per line - newline-terminated writes - explicit flush after each append - `Errc::IoError` on open/write/flush failure 5. Added reader in `io/src/event_log.cpp`: - reads line-by-line - strict schema parsing (unknown/missing fields rejected) - enforces `v == 0` - enforces contiguous `t` (starting at 1) - replays each event with `apply_event` - rejects replay failures and delta mismatches (`ParseError`) 6. Wired new module in top-level `CMakeLists.txt`. 7. Updated `docs/phase0.md` with event log record v0 constraints and invariants. ## Format Decisions (v0) - Serialization format: JSONL - Top-level keys: exactly `v`, `t`, `event`, `delta` - `event.type`: human-readable strings (`create_subject`, `create_cap`, etc.) - Rights encoding: string arrays (`Read`, `Write`, `Exec`, `Grant`, `Delete`) - `delta` always includes all canonical fields, including `edges_modified` - Parsing is strict and rejects schema drift ## Tests Added 1. `aes_event_log_schema_tests` 2. `aes_event_log_format_tests` 3. `aes_event_log_writer_tests` 4. `aes_event_log_reader_tests` These cover: - roundtrip encode/decode for event types and deltas - canonical deterministic line shape - strict schema rejection paths - writer append behavior and I/O failures - reader success path - malformed JSON, unknown/missing fields, invalid rights - non-contiguous `t` - tampered delta detection - replay failure handling ## Validation - `cmake -S . -B _build` - `cmake --build _build` - `ctest --test-dir _build --output-on-failure` Result: **23/23 tests passed**.