Merge pull request #10 from godofthunder101/godofthunder101-patch-1

Godofthunder101 patch 1

Author: godofthunder101

spec/CrypSA_Consistency_Model.md

@@ -16,23 +16,29 @@ CrypSA does not rely on global state synchronization.
 
 Instead:
 
-> Consistency is achieved through agreement on canonical event history and deterministic replay.
+> Consistency is achieved through agreement on canonical event history and deterministic replay.  
+> Canonical event history is the source of truth.
 
 Observers may temporarily diverge, but must eventually converge on the same canonical history.
 
 ---
 
+> Canonical event history is the source of truth.  
+> Derived canonical state is a projection of canonical event history. It is not the source of truth.
+
+---
+
 ## Consistency Goals
 
 CrypSA provides:
 
-* **Canonical Consistency**
+* **Canonical Consistency**  
   All observers agree on accepted canonical events
 
-* **Replay Consistency**
+* **Replay Consistency**  
   Given the same canonical event history, all observers derive the same state
 
-* **Eventual Convergence**
+* **Eventual Convergence**  
   Temporary divergence is allowed, but must resolve
 
 CrypSA does **not guarantee**:
@@ -50,8 +56,9 @@ CrypSA uses a hybrid consistency model:
 ### 1. Event-Level Authority
 
 * The validator is authoritative over event acceptance
-* Only accepted events enter canonical event history
-* Canonical event history defines shared truth
+* All candidate events must cross the invariant boundary before becoming canonical
+* Only accepted events become canonical and are appended to canonical event history
+* Canonical event history is the source of truth
 
 ---
 
@@ -81,7 +88,7 @@ Canonical event history is strictly ordered by:
 This ordering is:
 
 * authoritative
-* global within a validator instance
+* defined by the validator
 * used for replay and reconstruction
 
 > `canonical_sequence` is assigned by the validator and defines canonical ordering.
@@ -97,7 +104,7 @@ Implementations may reason about events within scopes such as:
 
 However:
 
-> canonical ordering remains defined by validator-assigned sequence
+> canonical ordering remains defined by validator-assigned `canonical_sequence`
 
 ---
 
@@ -114,8 +121,8 @@ Conflicts occur when:
 
 The validator resolves conflicts during validation:
 
-* events are evaluated atomically within the conflict scope
-* only one valid outcome is accepted
+* events are evaluated atomically within the relevant conflict scope
+* only valid outcomes can become canonical
 * rejected events do not enter canonical event history
 
 ---
@@ -130,7 +137,7 @@ Given:
 
 The result must be:
 
-> identical (accept or reject)
+> identical (accept or reject) given identical inputs
 
 ---
 
@@ -140,23 +147,23 @@ The result must be:
 | ---------------- | ----------------------- |
 | Local simulation | Observer-only           |
 | UI interaction   | Minimal                 |
-| Canonical events | Strong (validated)      |
+| Canonical events | Validator-enforced      |
 
 All canonical events require validation.
 
 ---
 
 ## Partitioning
 
-CrypSA may partition the world into independent scopes:
+Implementations may partition the world into independent scopes:
 
 * regions
 * zones
 * object groups
 
 Within a partition:
 
-* stronger consistency can be enforced
+* stronger coordination may be enforced
 
 Across partitions:
 
@@ -170,22 +177,24 @@ When events span partitions:
 
 * coordination may be required
 * validation may involve multiple scopes
-* temporary inconsistency may occur
+* temporary inconsistency is expected during reconciliation
 
 Possible strategies include:
 
 * coordination protocols
 * staged validation
 * compensating events
 
+These are implementation strategies, not core consistency requirements.
+
 ---
 
 ## Observer Reconciliation
 
 Observers reconcile when:
 
 * canonical events differ from local prediction
-* rejected events invalidate assumptions
+* rejected events invalidate local assumptions
 
 Reconciliation may involve:
 
@@ -197,12 +206,12 @@ Reconciliation may involve:
 
 ## Snapshot Consistency
 
-Snapshots represent derived state at a specific canonical sequence.
+Snapshots represent derived state at a specific `canonical_sequence`.
 
 To remain consistent:
 
-* snapshots must correspond to a specific `canonical_sequence`
-* replaying events after the snapshot must produce the same result as full replay
+* a snapshot must correspond to a specific `canonical_sequence`
+* replaying events after that snapshot must produce the same result as full replay
 
 ---
 
@@ -212,7 +221,7 @@ The system must ensure:
 
 * duplicate candidate events do not produce duplicate canonical events
 
-Each `event_id` must be processed exactly once.
+Repeated submission of the same `event_id` must not result in more than one canonical event.
 
 ---
 
@@ -224,7 +233,7 @@ The system must handle:
 * out-of-order delivery
 * missing events
 * conflicting submissions
-* partial history
+* incomplete observer history (missing canonical events)
 
 Consistency must still converge under these conditions.
 
@@ -257,11 +266,11 @@ CrypSA prioritizes:
 CrypSA consistency is:
 
 * event-driven
-* validator-controlled
-* globally ordered (by canonical sequence)
+* validator-defined canonical authority
+* canonically ordered
 * eventually convergent
 
-> Observers may disagree temporarily,
+> Observers may disagree temporarily,  
 > but canonical event history ensures they eventually agree.
 
 ---

spec/CrypSA_Event_Model.md

@@ -4,8 +4,8 @@ This document defines the structure, behavior, and lifecycle of events in CrypSA
 
 Events are the foundation of the system.
 
-> Canonical events define shared reality.
-> State is derived by replaying canonical event history.
+> Canonical event history is the source of truth.  
+> Derived canonical state is a projection of canonical event history. It is not the source of truth.
 
 ---
 
@@ -15,7 +15,12 @@ CrypSA is event-driven.
 
 * the world is not the source of truth
 * **canonical event history is the source of truth**
-* world state is derived from that history
+* derived canonical state is a projection of canonical event history. It is not the source of truth.
+
+---
+
+> Canonical event history is the source of truth.  
+> Derived canonical state is a projection of canonical event history. It is not the source of truth.
 
 ---
 
@@ -52,17 +57,17 @@ Every event follows this lifecycle:
    Event is submitted to the validator
 
 3. **Validation**
-   Validator evaluates the event
+   The validator evaluates the event
 
 4. **Decision**
 
-   * accepted → becomes canonical
-   * rejected → discarded
+   * accepted → proceeds to canonicalization
+   * rejected → does not become canonical and does not enter canonical event history
 
 5. **Canonicalization**
 
    * canonical metadata assigned
-   * appended to canonical event history
+   * If accepted, an event becomes canonical and is appended to canonical event history
 
 6. **Propagation**
    Observers receive the canonical event
@@ -87,7 +92,7 @@ CrypSA events consist of two layers:
 
 * unique identifier for the candidate event
 * used for idempotency
-* must be unique per submission
+* must uniquely identify the candidate event
 
 ---
 
@@ -120,7 +125,7 @@ Examples:
 
 * event-specific data
 * must be deterministic
-* must contain all data required for replay
+* must contain all data required for deterministic replay
 
 Example:
 
@@ -189,7 +194,7 @@ A canonical event is an accepted candidate event that:
 
 * has passed validation
 * has been assigned `canonical_sequence`
-* has been appended to canonical event history
+* has been appended to canonical event history by the validator
 * is immutable
 
 ---
@@ -213,7 +218,7 @@ Canonical events must satisfy:
 
 The system must ensure that duplicate `event_id` submissions do not create duplicate canonical events.
 
-Each candidate event must be processed exactly once.
+Repeated submission of the same `event_id` must not result in more than one canonical event.
 
 ---
 
@@ -264,7 +269,7 @@ Rejected events:
 
 ## Invariant Boundary Relationship
 
-Candidate events originate from actions that cross the invariant boundary.
+Candidate events originate from actions that cross the invariant boundary into validation.
 
 The invariant boundary defines:
 
@@ -284,8 +289,8 @@ CrypSA events:
 
 * represent all canonical changes
 * are validated before acceptance
-* are stored in canonical event history
-* define shared reality
+* are appended to canonical event history
+* canonical event history is the source of truth
 * are replayed to reconstruct state
 
 ---