diff --git a/spec/CrypSA_Consistency_Model.md b/spec/CrypSA_Consistency_Model.md index f0430fb..d041646 100644 --- a/spec/CrypSA_Consistency_Model.md +++ b/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,7 +147,7 @@ The result must be: | ---------------- | ----------------------- | | Local simulation | Observer-only | | UI interaction | Minimal | -| Canonical events | Strong (validated) | +| Canonical events | Validator-enforced | All canonical events require validation. @@ -148,7 +155,7 @@ All canonical events require validation. ## Partitioning -CrypSA may partition the world into independent scopes: +Implementations may partition the world into independent scopes: * regions * zones @@ -156,7 +163,7 @@ CrypSA may partition the world into independent scopes: Within a partition: -* stronger consistency can be enforced +* stronger coordination may be enforced Across partitions: @@ -170,7 +177,7 @@ 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: @@ -178,6 +185,8 @@ Possible strategies include: * staged validation * compensating events +These are implementation strategies, not core consistency requirements. + --- ## Observer Reconciliation @@ -185,7 +194,7 @@ Possible strategies include: 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. --- diff --git a/spec/CrypSA_Event_Model.md b/spec/CrypSA_Event_Model.md index ad17138..0baabd8 100644 --- a/spec/CrypSA_Event_Model.md +++ b/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 --- diff --git a/spec/CrypSA_Identity_Model.md b/spec/CrypSA_Identity_Model.md index 66caa05..2656e60 100644 --- a/spec/CrypSA_Identity_Model.md +++ b/spec/CrypSA_Identity_Model.md @@ -15,17 +15,22 @@ The identity model ensures that: In CrypSA: -> Identity is permanent. +> Identity is persistent and immutable. > Definition may evolve. > History must remain valid. --- +> 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. + +--- + ## Identity vs Definition CrypSA separates: -* **Identity** → “what this object is” +* **Identity** → “which object this is” * **Definition (Genome)** → “how this object behaves” --- @@ -57,9 +62,9 @@ Objects are created through **canonical mint events**. A mint event creates: -* a new unique identity (`object_id`) +* a new unique identity (`object_id`) within canonical event history * an initial genome reference (`genome_id`) -* initial state +* initial state (defined through canonical event payload) --- @@ -78,7 +83,7 @@ payload = { ### Requirements -* `object_id` must be globally unique within the canonical domain +* `object_id` must be unique within canonical event history * mint events must be accepted as canonical before the object exists * no object exists without a canonical mint event @@ -90,10 +95,10 @@ Objects follow this lifecycle: ```text id="cz2b8k" non-existent -→ minted +→ minted (canonical) → active -→ modified (via events) -→ possibly destroyed or archived +→ modified (via canonical events) +→ destroyed or archived ``` --- @@ -126,10 +131,9 @@ Each object references a **genome**. ### Genome Purpose Defines: - * structure * allowed state transitions -* validation rules +* validation constraints * event compatibility --- @@ -151,7 +155,7 @@ mining_station_v2 Replay must remain deterministic. -Objects must remain compatible with their genome definition. +Objects must remain compatible with the genome version they reference during replay. --- @@ -180,7 +184,7 @@ All canonical events must reference identities explicitly. ### Requirements * all target objects must exist at validation time -* identity must be valid within canonical event history +* identity must exist in canonical event history at validation time * destroyed objects cannot be modified --- @@ -194,7 +198,7 @@ This registry contains: * object_id * genome reference * lifecycle status -* derived state (materialized from canonical event history) +* derived canonical state (a projection of canonical event history) This registry is: @@ -219,13 +223,13 @@ Replay relies on identity stability. ## Identity Scope -Identity must be unique within the canonical system. +Identity must be unique within canonical event history. --- ### v0.1 Assumption -* global uniqueness within a single canonical domain +* global uniqueness within canonical event history --- @@ -241,7 +245,7 @@ Identity must be unique within the canonical system. In v0.1: -* observers may propose `object_id` +* observers may propose `object_id` values in candidate events * the validator must validate uniqueness --- @@ -306,9 +310,9 @@ Identity validation must ensure: CrypSA identity model ensures: -* objects have permanent identities +* objects have persistent and immutable identities * definitions are versioned and controlled -* events safely reference objects +* canonical events safely reference objects * replay remains deterministic --- diff --git a/spec/CrypSA_Replay_Model.md b/spec/CrypSA_Replay_Model.md index 2bad6bb..bb2c125 100644 --- a/spec/CrypSA_Replay_Model.md +++ b/spec/CrypSA_Replay_Model.md @@ -1,6 +1,6 @@ # CrypSA Replay Model Spec v0.1 -This document defines how CrypSA reconstructs world state from canonical event history. +This document defines how CrypSA reconstructs derived canonical state from canonical event history. Replay is the mechanism that turns: @@ -14,9 +14,10 @@ Replay is the mechanism that turns: In CrypSA: -> The world is not stored — it is reconstructed. +> 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. -Canonical state is always derived by replaying canonical event history. +Derived canonical state is reconstructed by replaying canonical event history. --- @@ -24,7 +25,7 @@ Canonical state is always derived by replaying canonical event history. Replay is the process of: -1. starting from a known base state (genesis or snapshot) +1. starting from a known derived canonical state (genesis or snapshot state) 2. applying canonical events in order 3. producing a deterministic derived canonical state @@ -35,10 +36,10 @@ Replay is the process of: Replay requires: * canonical event history -* authoritative ordering (`server_sequence`) +* authoritative ordering defined by `canonical_sequence` * event payloads -* invariant rules -* object definitions (genomes / mint) +* invariant rules defined by the validation model +* object definitions (genomes and canonical mint events) --- @@ -48,14 +49,14 @@ Replay can begin from: ### 1. Genesis -* empty or initial world state +* empty or initial derived canonical state * all events are applied --- ### 2. Snapshot (Recommended) -* precomputed derived canonical state at a known sequence +* precomputed derived canonical state at a known `canonical_sequence` * replay resumes from snapshot forward --- @@ -66,11 +67,12 @@ Replay order is defined by: ### Canonical Ordering -* events must be applied strictly in `server_sequence` order +* events must be applied strictly in `canonical_sequence` order +* no reordering is permitted * this ordering is authoritative * all observers must use the same ordering -> `server_sequence` is assigned by the validator and defines canonical ordering. +> `canonical_sequence` is assigned by the validator and defines canonical ordering. --- @@ -81,7 +83,7 @@ Each canonical event modifies derived canonical state according to: * its `event_type` * its `payload` * the current derived canonical state -* invariant rules +* invariant rules defined by the validation model --- @@ -141,7 +143,7 @@ Replay must be safe under repeated or partial application. ### Requirements -* canonical events must not produce different results if applied multiple times in the same sequence position +* canonical events must produce the same result when applied at the same `canonical_sequence` * event identity must uniquely identify each canonical event * replay systems must prevent duplicate application within the same sequence @@ -153,7 +155,7 @@ Replay is not defined as arbitrary reapplication. Instead: -> replay is deterministic application of a canonical sequence +> replay is the deterministic application of a canonical sequence Idempotency ensures robustness in: @@ -228,8 +230,8 @@ Snapshots improve replay performance. ### Requirements -* snapshot must correspond to a specific `server_sequence` -* snapshot must be reproducible from canonical event history +* snapshot must correspond to a specific `canonical_sequence` +* snapshot must be reproducible from canonical event history via deterministic replay * replay after snapshot must produce identical results to full replay --- @@ -301,12 +303,12 @@ CrypSA replay is: * deterministic * event-driven * reconstructive -* validator-aligned +* validator-defined canonical ordering It ensures that: > given the same canonical event history, -> all observers derive the same world +> all observers derive the same derived canonical state --- diff --git a/spec/CrypSA_Runtime_Spec_v0.1.md b/spec/CrypSA_Runtime_Spec_v0.1.md index c7595e8..26bf431 100644 --- a/spec/CrypSA_Runtime_Spec_v0.1.md +++ b/spec/CrypSA_Runtime_Spec_v0.1.md @@ -57,7 +57,7 @@ This v0.1 spec does **not fully define**: A process that: -* reconstructs canonical objects locally +* reconstructs derived canonical state locally * simulates local experience * proposes candidate events * performs observer reconciliation @@ -111,7 +111,7 @@ Supporting runtime structures may include: * indexes * object identity registries * genome references -* derived canonical state (materialized views) +* derived canonical state (materialized projection of canonical event history) These structures exist to enable: @@ -128,6 +128,9 @@ They do **not define truth**. ## 3. Core Runtime Principle +> 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. + An observer action does **not directly modify canonical event history**. Instead: @@ -137,7 +140,7 @@ Local Action → Candidate Event → Validation → Accept or Reject -→ Canonical Event History Update +→ Canonical Event Appended to Canonical Event History → Observer Reconciliation ``` @@ -161,7 +164,7 @@ If an action does not cross the invariant boundary: --- -## 4. Event Classes +## 4. Action Classes ### 4.1 Local-Only Actions @@ -282,7 +285,6 @@ CrypSA v0.1 uses: * observer order is not authoritative > `canonical_sequence` is the canonical ordering assigned by the validator. -> The name is retained for compatibility with common terminology. --- @@ -299,7 +301,7 @@ Conflicts are resolved within: ### 6.3 Conflict Resolution -* first valid accepted event wins +* the first event accepted by the validator becomes canonical * later conflicting events are rejected --- @@ -353,8 +355,8 @@ All accepted events must produce deterministic results. ### Accepted * event recorded -* derived canonical state updated -* obs notified +* derived canonical state updated via deterministic replay of canonical events +* observer notified --- @@ -362,7 +364,7 @@ All accepted events must produce deterministic results. * no canonical change * rejection returned -* ob reconciles +* observer reconciles --- @@ -477,13 +479,15 @@ System must handle: * retries * duplicates +* ordering must be enforced by `canonical_sequence`, not network delivery + --- ## 14. Idempotency Requirement The system must ensure that duplicate `event_id` submissions do not create duplicate canonical events. -Each event must be processed exactly once. +Repeated submission of the same `event_id` must not result in more than one canonical event. --- diff --git a/spec/CrypSA_Snapshot_Model.md b/spec/CrypSA_Snapshot_Model.md index 74fedfe..1d7d0d6 100644 --- a/spec/CrypSA_Snapshot_Model.md +++ b/spec/CrypSA_Snapshot_Model.md @@ -14,7 +14,8 @@ Snapshots are used to: In CrypSA: -> Canonical event history is 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. > Snapshots are derived performance artifacts. Snapshots do not replace canonical event history. @@ -28,7 +29,7 @@ They are cached representations of derived canonical state at a specific point i A snapshot is: * derived canonical state -* tied to a specific canonical sequence position +* tied to a specific `canonical_sequence` * used as a starting point for replay --- @@ -37,7 +38,7 @@ A snapshot is: Every snapshot must reference: -* `server_sequence` +* `canonical_sequence` It may also include: @@ -47,7 +48,7 @@ This ensures: > replay from snapshot + subsequent canonical events produces the same result as full replay -> `server_sequence` is assigned by the validator and defines canonical ordering. +> `canonical_sequence` is assigned by the validator and defines canonical ordering. --- @@ -56,8 +57,8 @@ This ensures: A snapshot contains: * derived canonical state -* relevant system state required for reconstruction -* snapshot position (`server_sequence`) +* relevant derived canonical state required for reconstruction +* snapshot position (`canonical_sequence`) * version metadata Snapshots must not contain: @@ -157,21 +158,27 @@ Snapshots are used for: Replay using snapshots follows this process: 1. load snapshot state -2. read snapshot `server_sequence` +2. read snapshot `canonical_sequence` 3. fetch canonical events after that sequence -4. apply events in `server_sequence` order +4. apply events in `canonical_sequence` order 5. produce current derived canonical state --- +### Reconstruction Rule + +Snapshot (at canonical_sequence N) + Canonical Event Tail (N+1 → latest) → Derived Canonical State + +--- + ## Snapshot Consistency Snapshots must satisfy all of the following: * derived from valid canonical event history -* tied to a specific `server_sequence` +* tied to a specific position `canonical_sequence` * reproducible via replay -* equivalent to replaying history up to that sequence +* equivalent to replaying canonical event history up to that `canonical_sequence` --- @@ -179,7 +186,7 @@ Snapshots must satisfy all of the following: Snapshots should be verified by: -* comparing replay results against snapshot contents +* comparing replay-derived canonical state against snapshot contents * periodic consistency checks * optional checksum or hash validation @@ -259,7 +266,7 @@ Snapshot performance depends on: Snapshots must: -* contain only canonical-derived data +* contain only data derived from canonical event history * be verifiable against canonical event history * never override canonical event history in the event of mismatch @@ -306,7 +313,7 @@ CrypSA snapshots are: * derived * versioned -* sequence-aware +* canonical-sequence-aware * replay-compatible They make event-driven worlds practical to operate without changing the source of truth. @@ -315,4 +322,4 @@ They make event-driven worlds practical to operate without changing the source o ## One Sentence Summary -CrypSA snapshots are derived, sequence-bound representations of canonical state that accelerate replay while preserving canonical event history as the sole source of truth. +CrypSA snapshots are derived, sequence-bound representations of derived canonical state that accelerate replay while preserving canonical event history as the sole source of truth. diff --git a/spec/CrypSA_Spec_Status.md b/spec/CrypSA_Spec_Status.md index 28082fc..31d9278 100644 --- a/spec/CrypSA_Spec_Status.md +++ b/spec/CrypSA_Spec_Status.md @@ -4,6 +4,11 @@ This document describes the maturity of each specification in the `spec/` folder --- +> 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. + +--- + ## Status Levels ### Draft @@ -12,7 +17,7 @@ Conceptual and may change significantly. * not fully aligned with the overall system * terminology or behavior may still evolve -* not ready for reliable implementation +* not yet suitable for reliable implementation --- @@ -53,20 +58,24 @@ Considered reliable for production use. | Spec | Status | | ----------------- | -------- | -| Runtime Spec | Testable | +| Runtime Spec | Defined | | Event Model | Defined | -| Validation Model | Defined | +| Validation Model | Defined (pending final review) | | Consistency Model | Defined | | Replay Model | Defined | | Snapshot Model | Defined | | Identity Model | Defined | | Transport Model | Draft | +--- +Transport Model is non-authoritative for canonical behavior and describes optional communication mechanisms. +--- + --- ## Interpretation -* **Defined** → structurally complete and aligned +* **Defined** → structurally complete and aligned with other spec documents * **Testable** → ready to implement and validate * **Draft** → still evolving and not yet implementation-ready @@ -86,7 +95,7 @@ Status reflects **maturity**, not authority. CrypSA is currently transitioning from: -> Defined → Testable +> **Defined → Testable** This phase involves: @@ -105,7 +114,7 @@ Specifications are expected to move through: Draft → Defined → Testable → Stable ``` -Progression is achieved by: +Progression is achieved through: * refining definitions * removing ambiguity diff --git a/spec/CrypSA_Spec_Version.md b/spec/CrypSA_Spec_Version.md index f44ec0a..40c31df 100644 --- a/spec/CrypSA_Spec_Version.md +++ b/spec/CrypSA_Spec_Version.md @@ -4,11 +4,16 @@ This document defines how CrypSA specifications are versioned. --- +> 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. + +--- + ## Current Version CrypSA Specification Set: -> v0.1 +> **v0.1** All documents in the `spec/` folder are part of this version unless explicitly stated otherwise. @@ -20,13 +25,13 @@ All documents in the `spec/` folder are part of this version unless explicitly s * concepts are stabilizing * breaking changes are expected -* specifications may evolve rapidly +* specifications may evolve rapidly during development * not production-ready Behavior defined in v0.x: * is authoritative within the version -* is not guaranteed to remain compatible across minor revisions +* is not guaranteed to remain compatible across minor version revisions --- diff --git a/spec/CrypSA_Transport_Model.md b/spec/CrypSA_Transport_Model.md index a183a3b..bd0a647 100644 --- a/spec/CrypSA_Transport_Model.md +++ b/spec/CrypSA_Transport_Model.md @@ -18,7 +18,7 @@ This is a minimal transport model for CrypSA v0.1. CrypSA transport is designed around: -> reliable agreement on canonical events, not perfect real-time synchronization +> reliable agreement on canonical event history, not perfect real-time synchronization The system prioritizes: @@ -30,6 +30,11 @@ over strict real-time guarantees. --- +> 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. + +--- + ## Transport Roles ### Observer → Validator @@ -82,7 +87,7 @@ The validator must treat `event_id` as idempotent. If the same event is submitted multiple times: -* it must be processed once +* it must not result in more than one canonical event * duplicates must be ignored or mapped to the same result --- @@ -102,7 +107,7 @@ The observer must be informed of the outcome. The validator should provide: -* acknowledgment of receipt (optional in v0.1) +* acknowledgment of receipt (optional optimization in v0.1) * final validation outcome (required) Observers must track: @@ -124,7 +129,7 @@ The validator distributes accepted canonical events to observers. Canonical events must be: * eventually delivered to all relevant observers -* complete and consistent with canonical event history ordering (`server_sequence`) +* complete and consistent with canonical ordering defined by `canonical_sequence` --- @@ -134,18 +139,18 @@ Transport does **not** guarantee ordering. Canonical ordering is defined by: -* `server_sequence` assigned by the validator +> `canonical_sequence` is assigned by the validator and defines canonical ordering. Observers must: * reorder events as needed -* apply events strictly in `server_sequence` order +* apply events strictly in `canonical_sequence` order --- -## Event Stream Model +## Canonical Event Stream Model -Observers receive a stream of canonical events. +Observers receive canonical events as a stream derived from canonical event history. This stream may: @@ -155,7 +160,7 @@ This stream may: Observers must: -* reorder events using `server_sequence` +* reorder events using `canonical_sequence` * discard duplicates * apply events deterministically @@ -211,7 +216,7 @@ Observers must support resynchronization. ### Minimum Mechanism -* request canonical events since last known `server_sequence` +* request canonical events since last known `canonical_sequence` * optionally load snapshot * replay event tail @@ -226,7 +231,7 @@ Transport may provide: Reconstruction: -> Snapshot + Event Stream → Current Derived Canonical State +> Snapshot + Canonical Event Tail → Derived Canonical State --- @@ -316,7 +321,7 @@ It does not: * validate events * define canonical event history -* simulate world state +* simulate derived canonical state --- @@ -333,7 +338,7 @@ It ensures: > candidate events reach the validator, > canonical events reach observers, -> and all participants converge on shared history +> and all participants converge on canonical event history --- diff --git a/spec/CrypSA_Validation_Model.md b/spec/CrypSA_Validation_Model.md index f1373a1..6de17ae 100644 --- a/spec/CrypSA_Validation_Model.md +++ b/spec/CrypSA_Validation_Model.md @@ -14,12 +14,17 @@ Validation is the mechanism that: In CrypSA: -> Observers may simulate freely, but only validated events become part of canonical event history. +> Observers may simulate freely, but only validated events become canonical and are appended to canonical event history Validation occurs at the **Invariant Boundary**, where proposed actions transition from local simulation to 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. + +--- + ## Validation Flow The validation pipeline follows this sequence: @@ -31,10 +36,10 @@ The validation pipeline follows this sequence: Action becomes a candidate event 3. **Submission** - Event is sent to the server + Event is sent to the validator 4. **Validation** - Server evaluates the event + Validator evaluates the event 5. **Decision** @@ -42,7 +47,7 @@ The validation pipeline follows this sequence: * rejected → discarded 6. **Canonical Update** - Accepted events are assigned `server_sequence` and appended to canonical event history + Accepted events are assigned `canonical_sequence` and appended to canonical event history 7. **Observer Reconciliation** Observers update local state based on canonical events @@ -81,11 +86,11 @@ Checks include: ### 3. Precondition Validation -Ensures observers assumptions are still true. +Ensures observers assumptions are still valid. Checks include: -* expected state matches canonical state +* expected state matches derived canonical state * required resources exist * required conditions hold @@ -142,7 +147,7 @@ These are not required for v0.1 runtime behavior. Validation must be: * deterministic -* atomic within conflict scope +* atomic within the relevant conflict scope * based on canonical event history and derived canonical state --- @@ -156,7 +161,7 @@ Each candidate results in: ### Accepted * event is valid -* assigned `server_sequence` +* assigned `canonical_sequence` * appended to canonical event history * becomes part of canonical event history @@ -216,13 +221,13 @@ Examples: | ---------------- | --------------- | | Local simulation | Not validated | | UI interaction | Not validated | -| Canonical events | Fully validated | +| Candidate events | Fully validated | --- ## Performance Considerations -CrypSA reduces server load by: +CrypSA reduces validator load by: * avoiding full simulation * validating only boundary-crossing actions @@ -236,7 +241,7 @@ CrypSA does not trust observer simulation. It trusts: -> the validation process that determines canonical event history +> the validation process that determines what becomes canonical Observers may propose any action, but: @@ -258,7 +263,7 @@ Strategies include: * idempotency checks * conflict resolution -* ordering rules +* ordering rules based on `canonical_sequence` --- @@ -286,4 +291,4 @@ CrypSA validation is: It ensures: > observers may act freely, -> but only valid actions become part of canonical event history +> only validated actions become canonical and are appended to canonical event history diff --git a/spec/README.md b/spec/README.md index 3c763ed..6ab6f02 100644 --- a/spec/README.md +++ b/spec/README.md @@ -16,7 +16,7 @@ the `spec/` folder defines: ## 🧭 Purpose of This Folder -The documents in this folder define the **minimum required runtime behavior** of CrypSA, including: +The documents in this folder define the **minimum required runtime behavior** of the CrypSA system, including: * event structure and lifecycle * validation and invariant enforcement @@ -28,11 +28,11 @@ The documents in this folder define the **minimum required runtime behavior** of * identity and object lifecycle * observer ↔ validator communication -These specifications make CrypSA: +These specifications make CrypSA systems: * implementable * testable -* technically reviewable +* technically verifiable They do **not** define full production systems. @@ -40,14 +40,15 @@ They do **not** define full production systems. ## ⚙️ Core Runtime Principle -> Canonical truth is defined by validated canonical events — not by synchronized state. +> 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. At runtime: * observers propose candidate events * the validator evaluates them * accepted events are appended to canonical event history -* derived canonical state is reconstructed via deterministic replay +* derived canonical state is reconstructed by deterministic replay of canonical event history This model applies regardless of validator deployment: @@ -82,10 +83,10 @@ This includes: * event structure * validation behavior -* canonical event handling +* canonical event lifecycle and handling * ordering (`canonical_sequence`) * consistency and reconciliation rules -* replay and derived state behavior +* replay and derived canonical state behavior * snapshot behavior * identity and minting * transport expectations @@ -150,7 +151,7 @@ All documents in this folder must: If ambiguity exists: -> the Runtime Model defines final behavior +> the Runtime Model defines authoritative runtime behavior --- @@ -243,4 +244,4 @@ These specifications are: ## One Sentence Summary -The `spec/` folder defines the authoritative runtime behavior of CrypSA—how events, validation, consistency, replay, identity, snapshots, and transport work together to produce shared canonical reality through validator-controlled canonical event history. +The `spec/` folder defines the authoritative runtime behavior of CrypSA—how events, validation, consistency, replay, identity, snapshots, and transport work together to produce shared canonical reality defined by canonical event history.