Phase 0: Snapshot hashing and equality #57

Merged

erikinkinen merged 4 commits from 0-snapshot-hashing-and-equality into main

2026-03-03 11:09:19 +01:00

erikinkinen commented

2026-03-03 11:04:24 +01:00

Owner

Summary

Implements Snapshot Hashing and Equality v0 in aes::sim so snapshots can be compared exactly and deterministically.

Closes #16.

What’s Included

1) Canonical snapshot serialization (v0)

Added canonical serializer API:

core::Result<std::string> canonical_snapshot_v0(const Engine &engine);

Implemented deterministic ASCII serialization with fixed line grammar/order, terminal newline, and stable ordering of all graph/state components.

Behavior/details:

Serializes time, history, subject/object/edge stores, outgoing/incoming indices, and next ID cursors.
Uses fixed event type tokens and fixed payload key ordering per event type.
Sorts adjacency edge-id lists before output.
Excludes seed and debug labels by design.
Validates graph first; returns Errc::InvariantViolation on invalid graph.

2) Stable snapshot hash computation

Added hash API:

core::Result<std::uint64_t> snapshot_hash_v0(const Engine &engine);

Behavior/details:

Computes hash as fnv1a64(canonical_snapshot_v0(engine)).
Propagates canonicalization errors unchanged.

3) Deep equality with mismatch diagnostics

Added equality API:

core::Error snapshot_equal(const Engine &lhs, const Engine &rhs);

Behavior/details:

Compares full snapshot semantics (excluding seed and debug labels):
- time
- history length + each record (EventId, event type/payload)
- subjects/objects/edges (including rights)
- outgoing/incoming indices
- next ID cursors
Validates both graphs first; reports which side is invalid.
Returns first-mismatch Errc::InvariantViolation message.

4) Tests

Added new test target:

tests/snapshot_tests.cpp
wired in tests/CMakeLists.txt as aes_snapshot_tests

Coverage includes:

canonical determinism
hash determinism
canonical/hash sensitivity to time/history/rights changes
deep equality success
mismatch paths (time, history id, event payload, edge rights, outgoing/incoming index ordering differences, next-id cursor mismatch)
seed exclusion
graph validity guard behavior

Files Changed

sim/include/aes/sim/snapshot.hpp (new)
sim/src/snapshot.cpp (new)
sim/CMakeLists.txt
tests/snapshot_tests.cpp (new)
tests/CMakeLists.txt

Validation

Executed successfully:

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

Result: all tests passing, including new snapshot tests.

## Summary Implements Snapshot Hashing and Equality v0 in `aes::sim` so snapshots can be compared exactly and deterministically. Closes #16. ## What’s Included ### 1) Canonical snapshot serialization (v0) Added canonical serializer API: - `core::Result<std::string> canonical_snapshot_v0(const Engine &engine);` Implemented deterministic ASCII serialization with fixed line grammar/order, terminal newline, and stable ordering of all graph/state components. Behavior/details: - Serializes `time`, `history`, subject/object/edge stores, outgoing/incoming indices, and next ID cursors. - Uses fixed event type tokens and fixed payload key ordering per event type. - Sorts adjacency edge-id lists before output. - Excludes `seed` and debug labels by design. - Validates graph first; returns `Errc::InvariantViolation` on invalid graph. ### 2) Stable snapshot hash computation Added hash API: - `core::Result<std::uint64_t> snapshot_hash_v0(const Engine &engine);` Behavior/details: - Computes hash as `fnv1a64(canonical_snapshot_v0(engine))`. - Propagates canonicalization errors unchanged. ### 3) Deep equality with mismatch diagnostics Added equality API: - `core::Error snapshot_equal(const Engine &lhs, const Engine &rhs);` Behavior/details: - Compares full snapshot semantics (excluding `seed` and debug labels): - `time` - history length + each record (`EventId`, event type/payload) - subjects/objects/edges (including rights) - outgoing/incoming indices - next ID cursors - Validates both graphs first; reports which side is invalid. - Returns first-mismatch `Errc::InvariantViolation` message. ### 4) Tests Added new test target: - `tests/snapshot_tests.cpp` - wired in `tests/CMakeLists.txt` as `aes_snapshot_tests` Coverage includes: - canonical determinism - hash determinism - canonical/hash sensitivity to time/history/rights changes - deep equality success - mismatch paths (time, history id, event payload, edge rights, outgoing/incoming index ordering differences, next-id cursor mismatch) - seed exclusion - graph validity guard behavior ## Files Changed - `sim/include/aes/sim/snapshot.hpp` (new) - `sim/src/snapshot.cpp` (new) - `sim/CMakeLists.txt` - `tests/snapshot_tests.cpp` (new) - `tests/CMakeLists.txt` ## Validation Executed successfully: - `cmake --build _build` - `ctest --test-dir _build --output-on-failure` Result: all tests passing, including new snapshot tests.