Phase 0: Add delta unit tests #51

Merged

erikinkinen merged 1 commit from 0-graph-delta-format into main

2026-02-17 07:23:48 +01:00

erikinkinen commented

2026-02-17 07:23:12 +01:00

Owner

Closes #9

Summary

This PR validates and extends the GraphDelta structure that tracks explicit changes to the authority graph during event application. It introduces comprehensive unit tests to ensure delta completeness and verifies full compliance with Phase 0 documentation requirements.

The GraphDelta structure already existed in core/include/aes/core/graph_delta.hpp but lacked dedicated validation and testing. This PR confirms that:

All 9 Phase 0 event types correctly populate delta fields
Edge modifications capture both old and new rights
Delta is atomically cleared on error conditions
The implementation follows event application discipline

Scope

Included

Comprehensive delta unit tests (tests/delta_tests.cpp): 15 tests covering all delta operations
Delta completeness validation: Verified all event types (CreateSubject, DestroySubject, CreateObject, DestroyObject, CreateCap, DeleteCap, DelegateCap, ReduceRights, UseCap) correctly track changes
Documentation compliance verification: Confirmed GraphDelta implementation aligns with docs/model.md and docs/phase0.md
CMake integration: Added aes_delta_tests target to build system

Explicitly excluded

No structural changes to GraphDelta: The existing structure is already complete and correct
No new event types: This PR validates existing Phase 0 events only
No temporal/provenance fields: Time-related delta fields remain reserved for Phase 1+
No serialization/logging: Delta persistence is deferred to event logging infrastructure

Design intent

The GraphDelta structure serves as the explicit audit trail for all authority graph mutations. It enables:

Deterministic replay: Complete record of what changed enables exact graph reconstruction
Atomic application: Delta is populated only on success, cleared on any error
Observability: Tests and future tooling can inspect exactly what each event modified
Phase extensibility: Structure ready for Phase 1+ temporal annotations

Design decisions:

Separate vectors for each change type (created/destroyed/modified) provides clarity over a single unified change list
EdgeModification captures before/after state to support modification tracking and potential undo/replay scenarios
empty() method enables fast checks for no-op events (like UseCap in Phase 0)
Cleared on error maintains atomic application discipline—no partial deltas

The implementation maintains strict alignment with event application semantics documented in docs/model.md:

Events are the sole mechanism for graph changes
Preconditions are mandatory runtime checks
Postconditions guarantee resulting graph state

Phase discipline

Phase 0 foundation

This PR is entirely within Phase 0 scope. GraphDelta:

Tracks structural graph changes without temporal semantics
Provides foundation for event logging (planned)
Maintains phase-stable event meanings
Includes no revocation, provenance, or epistemic assumptions

Reserved fields for later phases

Per docs/model.md line 376, GraphDelta is identified as a future attachment point for:

Creation time / generation (Phase 1+)
Provenance depth tracking (Phase 3+)
Derivation metadata (Phase 3+)

These fields are intentionally absent until their respective phases define the appropriate semantics.

Verification

All tests pass: 14/14 tests passing (including 2 delta-related test suites)
Model internally consistent: Delta structure captures all possible Phase 0 graph changes
Documentation compliance verified: Full alignment with docs/model.md event semantics (lines 144-361), atomic application discipline (lines 345-361), and invariant preservation (lines 443-608)
No regressions: Existing aes_apply_event_tests continue to pass with delta validation
Code formatted: All files pass clang-format and pre-commit hooks
Coverage validation:
- All 9 event types tested for delta population
- Error cases verified (delta cleared on precondition violations)
- EdgeModification struct validated with old_rights/new_rights tracking
- Empty delta detection for UseCap events (no-op in Phase 0)
- Sequential operations maintain independent deltas

Notes

What reviewers should focus on:

Test coverage completeness: tests/delta_tests.cpp validates all event types and error conditions. Are there additional edge cases to consider?
Documentation alignment: The compliance verification section confirms alignment with docs/model.md. Does the delta structure support the documented event semantics?
Phase discipline: Are reserved fields appropriately absent? Does the structure avoid premature Phase 1+ coupling?

Known limitations:

Delta tests use sequential event application rather than batch operations (appropriate for Phase 0's atomic event model)
No performance benchmarking of delta population overhead (deferred pending event logging infrastructure)

Follow-up work:

Integration with event logging system (when implemented)
Delta serialization for replay/checkpoint (Part of broader logging design)
Phase 1+ temporal annotations as documented in reserved fields

Closes #9 --- ## Summary This PR validates and extends the **GraphDelta** structure that tracks explicit changes to the authority graph during event application. It introduces comprehensive unit tests to ensure delta completeness and verifies full compliance with Phase 0 documentation requirements. The GraphDelta structure already existed in `core/include/aes/core/graph_delta.hpp` but lacked dedicated validation and testing. This PR confirms that: - All 9 Phase 0 event types correctly populate delta fields - Edge modifications capture both old and new rights - Delta is atomically cleared on error conditions - The implementation follows event application discipline --- ## Scope ### **Included** - **Comprehensive delta unit tests** (`tests/delta_tests.cpp`): 15 tests covering all delta operations - **Delta completeness validation**: Verified all event types (CreateSubject, DestroySubject, CreateObject, DestroyObject, CreateCap, DeleteCap, DelegateCap, ReduceRights, UseCap) correctly track changes - **Documentation compliance verification**: Confirmed GraphDelta implementation aligns with `docs/model.md` and `docs/phase0.md` - **CMake integration**: Added `aes_delta_tests` target to build system ### **Explicitly excluded** - **No structural changes to GraphDelta**: The existing structure is already complete and correct - **No new event types**: This PR validates existing Phase 0 events only - **No temporal/provenance fields**: Time-related delta fields remain reserved for Phase 1+ - **No serialization/logging**: Delta persistence is deferred to event logging infrastructure --- ## Design intent The GraphDelta structure serves as the **explicit audit trail** for all authority graph mutations. It enables: 1. **Deterministic replay**: Complete record of what changed enables exact graph reconstruction 2. **Atomic application**: Delta is populated only on success, cleared on any error 3. **Observability**: Tests and future tooling can inspect exactly what each event modified 4. **Phase extensibility**: Structure ready for Phase 1+ temporal annotations Design decisions: - **Separate vectors for each change type** (created/destroyed/modified) provides clarity over a single unified change list - **EdgeModification captures before/after state** to support modification tracking and potential undo/replay scenarios - **`empty()` method** enables fast checks for no-op events (like UseCap in Phase 0) - **Cleared on error** maintains atomic application discipline—no partial deltas The implementation maintains strict alignment with event application semantics documented in `docs/model.md`: - Events are the sole mechanism for graph changes - Preconditions are mandatory runtime checks - Postconditions guarantee resulting graph state --- ## Phase discipline **Phase 0 foundation** This PR is entirely within Phase 0 scope. GraphDelta: - Tracks structural graph changes without temporal semantics - Provides foundation for event logging (planned) - Maintains phase-stable event meanings - Includes no revocation, provenance, or epistemic assumptions **Reserved fields for later phases** Per `docs/model.md` line 376, GraphDelta is identified as a future attachment point for: - Creation time / generation (Phase 1+) - Provenance depth tracking (Phase 3+) - Derivation metadata (Phase 3+) These fields are intentionally absent until their respective phases define the appropriate semantics. --- ## Verification - [x] **All tests pass**: 14/14 tests passing (including 2 delta-related test suites) - [x] **Model internally consistent**: Delta structure captures all possible Phase 0 graph changes - [x] **Documentation compliance verified**: Full alignment with `docs/model.md` event semantics (lines 144-361), atomic application discipline (lines 345-361), and invariant preservation (lines 443-608) - [x] **No regressions**: Existing `aes_apply_event_tests` continue to pass with delta validation - [x] **Code formatted**: All files pass `clang-format` and pre-commit hooks - [x] **Coverage validation**: - All 9 event types tested for delta population - Error cases verified (delta cleared on precondition violations) - EdgeModification struct validated with old_rights/new_rights tracking - Empty delta detection for UseCap events (no-op in Phase 0) - Sequential operations maintain independent deltas --- ## Notes **What reviewers should focus on:** 1. **Test coverage completeness**: `tests/delta_tests.cpp` validates all event types and error conditions. Are there additional edge cases to consider? 2. **Documentation alignment**: The compliance verification section confirms alignment with `docs/model.md`. Does the delta structure support the documented event semantics? 3. **Phase discipline**: Are reserved fields appropriately absent? Does the structure avoid premature Phase 1+ coupling? **Known limitations:** - Delta tests use sequential event application rather than batch operations (appropriate for Phase 0's atomic event model) - No performance benchmarking of delta population overhead (deferred pending event logging infrastructure) **Follow-up work:** - Integration with event logging system (when implemented) - Delta serialization for replay/checkpoint (Part of broader logging design) - Phase 1+ temporal annotations as documented in reserved fields