Phase 0: Event taxonomy v0 #49

Merged

erikinkinen merged 1 commit from 0-event-taxonomy-v0 into main

2026-02-17 06:11:24 +01:00

erikinkinen commented

2026-02-17 06:10:46 +01:00

Owner

Closes #7

Summary

This PR introduces the Phase 0 Event Taxonomy for the AES. It establishes a foundational type system for representing all authority-graph-modifying operations, providing a formal specification for how the authority graph evolves through discrete events.

The taxonomy defines 9 event types across 5 conceptual categories: subject lifecycle, object lifecycle, capability edge lifecycle, capability derivation, and rights attenuation. Each event type has an associated payload structure with explicitly documented preconditions and postconditions, ensuring clear operational semantics for graph transformations.

This work is essential for Phase 0 as it provides the vocabulary needed to describe, validate, and reason about authority graph operations throughout the simulation, metrics collection, and eventual I/O subsystems.

Scope

Included

EventType enum with 9 Phase 0 event categories
Payload structures for all event types:
- CreateSubjectPayload / DestroySubjectPayload (subject lifecycle)
- CreateObjectPayload / DestroyObjectPayload (object lifecycle)
- CreateCapPayload / DeleteCapPayload (capability edge management)
- DelegateCapPayload (capability derivation with optional attenuation)
- ReduceRightsPayload (rights attenuation on existing edges)
- UseCapPayload (capability usage tracking, reserved for future phases)
Comprehensive precondition/postcondition documentation for each event
Thorough test coverage validating payload structure integrity, trivial copyability, and rights subset semantics

Explicitly excluded

Event application logic (graph mutation implementation)
Event sequencing/ordering constraints
Event validation against graph state
Event serialization/deserialization
Event history/provenance tracking mechanisms
std::variant-based unified Event type (reserved for future PR)

Design intent

The event taxonomy serves as the interface contract between different subsystems of AES:

Separation of concerns: Events describe what should happen, not how to make it happen. The actual graph mutation logic remains in separate application/validation layers.
Explicit invariant documentation: Each payload structure documents its preconditions and postconditions directly in code comments, making the operational semantics self-documenting and serving as executable specifications for future validation logic.
Type safety: Using distinct payload structures (rather than a generalized event structure) ensures compile-time correctness and makes impossible states unrepresentable.
Trivial copyability: All payload structures are trivially copyable, enabling efficient serialization, transmission, and storage without complex memory management.
Rights algebra foundation: The taxonomy explicitly encodes subset relationships for delegation and attenuation, establishing the formal basis for rights reasoning that will be validated in future PRs.

Phase discipline

Phase 0 Baseline

This PR belongs entirely to Phase 0 and establishes the foundational event vocabulary. Key phase discipline considerations:

Reserved for future phases: UseCapPayload has no graph effect in Phase 0 but is included to reserve the event type for future provenance/audit functionality. This allows Phase 0 code to generate UseCap events without requiring implementation of the tracking infrastructure.
No backward compatibility burden: As a Phase 0 introduction, this taxonomy can establish conventions without legacy constraints. Future phases may extend the taxonomy with additional event types but should not modify these foundational definitions.
Delegation semantics: DelegateCap is included in Phase 0 even though full delegation semantics may be refined in later phases, because it's essential for basic capability derivation scenarios.
Extensibility: The enum-based design allows future phases to add new EventType values without breaking existing event handling code.

Verification

All tests pass (event_tests.cpp validates payload structure properties)
All payload structures are trivially copyable (verified via static_assert)
Rights subset semantics are correctly encoded and testable
Preconditions and postconditions documented for all event types
Event type discriminators are distinct and well-named
Code follows project formatting conventions
No regressions in existing test suite

Notes

Review focus areas:

Precondition/postcondition accuracy: Verify that the documented invariants correctly capture the intended semantics of each event type.
Rights subset semantics: Confirm that DelegateCapPayload and ReduceRightsPayload correctly encode the subset relationship constraints.
Naming consistency: Ensure event type names and payload field names align with the existing AES terminology (subject, object, capability edge).
Reserved fields: Note that UseCapPayload is intentionally minimal; future phases will extend this with provenance tracking fields.

Known limitations:

This PR defines the event types but does not implement event application logic. That will come in a follow-up PR that adds event validation and graph mutation methods.
There is no unified Event variant type yet. A future PR will add using Event = std::variant<CreateSubjectPayload, ...> to enable polymorphic event handling.

Follow-up work planned:

Event validation functions that check preconditions against graph state
Event application functions that mutate the graph according to postconditions
Event sequence validation (ensuring event ordering preserves graph consistency)
Unified Event variant type with type-safe visitation support

Closes #7 --- ## Summary This PR introduces the **Phase 0 Event Taxonomy** for the AES. It establishes a foundational type system for representing all authority-graph-modifying operations, providing a formal specification for how the authority graph evolves through discrete events. The taxonomy defines 9 event types across 5 conceptual categories: subject lifecycle, object lifecycle, capability edge lifecycle, capability derivation, and rights attenuation. Each event type has an associated payload structure with explicitly documented preconditions and postconditions, ensuring clear operational semantics for graph transformations. This work is essential for Phase 0 as it provides the vocabulary needed to describe, validate, and reason about authority graph operations throughout the simulation, metrics collection, and eventual I/O subsystems. --- ## Scope ### **Included** - `EventType` enum with 9 Phase 0 event categories - Payload structures for all event types: - `CreateSubjectPayload` / `DestroySubjectPayload` (subject lifecycle) - `CreateObjectPayload` / `DestroyObjectPayload` (object lifecycle) - `CreateCapPayload` / `DeleteCapPayload` (capability edge management) - `DelegateCapPayload` (capability derivation with optional attenuation) - `ReduceRightsPayload` (rights attenuation on existing edges) - `UseCapPayload` (capability usage tracking, reserved for future phases) - Comprehensive precondition/postcondition documentation for each event - Thorough test coverage validating payload structure integrity, trivial copyability, and rights subset semantics ### **Explicitly excluded** - Event application logic (graph mutation implementation) - Event sequencing/ordering constraints - Event validation against graph state - Event serialization/deserialization - Event history/provenance tracking mechanisms - `std::variant`-based unified Event type (reserved for future PR) --- ## Design intent The event taxonomy serves as the **interface contract** between different subsystems of AES: 1. **Separation of concerns**: Events describe *what* should happen, not *how* to make it happen. The actual graph mutation logic remains in separate application/validation layers. 2. **Explicit invariant documentation**: Each payload structure documents its preconditions and postconditions directly in code comments, making the operational semantics self-documenting and serving as executable specifications for future validation logic. 3. **Type safety**: Using distinct payload structures (rather than a generalized event structure) ensures compile-time correctness and makes impossible states unrepresentable. 4. **Trivial copyability**: All payload structures are trivially copyable, enabling efficient serialization, transmission, and storage without complex memory management. 5. **Rights algebra foundation**: The taxonomy explicitly encodes subset relationships for delegation and attenuation, establishing the formal basis for rights reasoning that will be validated in future PRs. --- ## Phase discipline **Phase 0 Baseline** This PR belongs entirely to Phase 0 and establishes the foundational event vocabulary. Key phase discipline considerations: - **Reserved for future phases**: `UseCapPayload` has no graph effect in Phase 0 but is included to reserve the event type for future provenance/audit functionality. This allows Phase 0 code to generate `UseCap` events without requiring implementation of the tracking infrastructure. - **No backward compatibility burden**: As a Phase 0 introduction, this taxonomy can establish conventions without legacy constraints. Future phases may extend the taxonomy with additional event types but should not modify these foundational definitions. - **Delegation semantics**: `DelegateCap` is included in Phase 0 even though full delegation semantics may be refined in later phases, because it's essential for basic capability derivation scenarios. - **Extensibility**: The enum-based design allows future phases to add new `EventType` values without breaking existing event handling code. --- ## Verification - [x] All tests pass (event_tests.cpp validates payload structure properties) - [x] All payload structures are trivially copyable (verified via static_assert) - [x] Rights subset semantics are correctly encoded and testable - [x] Preconditions and postconditions documented for all event types - [x] Event type discriminators are distinct and well-named - [x] Code follows project formatting conventions - [x] No regressions in existing test suite --- ## Notes **Review focus areas:** 1. **Precondition/postcondition accuracy**: Verify that the documented invariants correctly capture the intended semantics of each event type. 2. **Rights subset semantics**: Confirm that `DelegateCapPayload` and `ReduceRightsPayload` correctly encode the subset relationship constraints. 3. **Naming consistency**: Ensure event type names and payload field names align with the existing AES terminology (subject, object, capability edge). 4. **Reserved fields**: Note that `UseCapPayload` is intentionally minimal; future phases will extend this with provenance tracking fields. **Known limitations:** - This PR defines the event types but does not implement event application logic. That will come in a follow-up PR that adds event validation and graph mutation methods. - There is no unified `Event` variant type yet. A future PR will add `using Event = std::variant<CreateSubjectPayload, ...>` to enable polymorphic event handling. **Follow-up work planned:** - Event validation functions that check preconditions against graph state - Event application functions that mutate the graph according to postconditions - Event sequence validation (ensuring event ordering preserves graph consistency) - Unified `Event` variant type with type-safe visitation support