diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 64275d9..7ba3363 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,7 @@ CrypSA is **architecture-first**. This means: * the **spec defines runtime behavior** -* the **architecture defines structure and boundaries** +* the **architecture defines system structure and conceptual models** * implementation follows these definitions > Contributions must preserve clarity and consistency of the model. @@ -27,13 +27,13 @@ This means: The repository is structured by document authority: -| Layer | Purpose | Authority | -| ----------------- | ------------------------------ | ----------------- | -| `spec/` | Runtime behavior | **Highest** | -| `architecture/` | Structure and responsibilities | High | -| `implementation/` | How to build | Support | -| `diagrams/` | Visualization | Non-authoritative | -| `exploratory/` | Ideas | Non-authoritative | +| Layer | Purpose | Authority | +| ----------------- | ----------------------------------------- | ----------------- | +| `spec/` | Authoritative runtime behavior | **Highest** | +| `architecture/` | System structure and responsibilities | High | +| `implementation/` | How to build | Support | +| `diagrams/` | Visualization | Non-authoritative | +| `exploratory/` | Ideas | Non-authoritative | ### Rules @@ -75,13 +75,13 @@ All contributors must follow the terminology defined in: ✔ Correct: -``` id="tr8wq5" +``` validator validates events -```` +``` ❌ Incorrect: -```id="83nmq2" +``` server validates events ``` @@ -125,9 +125,11 @@ The following phrases are **canonical** and must be used exactly as written. Do not rephrase, simplify, substitute, or partially restate these phrases. -If a sentence expresses one of these concepts, it must use the canonical phrasing exactly. +If a sentence expresses one of these concepts, it must use the canonical phrasing exactly. Near matches are not acceptable. +These phrases are enforced by documentation linting and must not be altered. + --- ### Validator Authority @@ -169,11 +171,11 @@ CrypSA enforces strict separation: | Truth | Validation + canonical event history | | Translation | Adapters | | Interpretation | Lenses | -| Experience | UI / simulation | +| Experience | UI and local simulation | ### Rules -* Adapters **change structure, not meaning** +* Adapters **change structure without interpreting meaning** * Lenses **define meaning, not structure** * UI **does not define truth** * Observers **never define canonical truth** @@ -200,7 +202,7 @@ Do not blur these boundaries in contributions. 2. Reference it elsewhere: -```id="f6o525" +``` See: Terminology Primer → [Term] ``` @@ -234,9 +236,9 @@ When contributing documentation: Examples: -❌ Spec logic inside architecture docs -❌ Implementation details inside spec -❌ New concepts defined inside diagrams +❌ Spec logic inside architecture docs +❌ Implementation details inside spec +❌ New concepts defined inside diagrams --- diff --git a/CrypSA_Architecture_Overview.md b/CrypSA_Architecture_Overview.md index 1b5b6fd..c47c2f4 100644 --- a/CrypSA_Architecture_Overview.md +++ b/CrypSA_Architecture_Overview.md @@ -10,14 +10,22 @@ For a worked example, see: --- -## 📜 Specification Authority +## 📜 Authority Level -The `/spec` directory is the **authoritative definition of runtime behavior**. +CrypSA documentation is structured across layers: -Architecture documents explain the system. -The spec defines how it must behave. +* `/spec` — authoritative definition of runtime behavior +* `/architecture` — system structure and conceptual models -If there is any conflict, **the spec takes precedence**. +This document provides a high-level structural overview. + +For strict separation of responsibilities, see: + +→ `CrypSA_Boundary_Definitions.md` + +If there is any conflict: + +* spec takes precedence over architecture --- @@ -57,6 +65,10 @@ They are responsible for local simulation and experience. Observers do **not define truth**. +For the boundary between observers and the validator, see: + +→ `CrypSA_Boundary_Definitions.md` + --- ### Validator @@ -68,12 +80,14 @@ The validator: * accepts or rejects them * assigns canonical ordering (`canonical_sequence`) -Accepted events become canonical and are appended to canonical event history, which defines what is true. +If accepted, an event becomes canonical and is appended to canonical event history. > Canonical event history is the source of truth. The validator is a **logical role**, not a specific machine. +It is the only component that defines what becomes canonical. + It may run: * locally (within an observer environment) @@ -97,13 +111,16 @@ Not all validators are servers, but all servers host a validator. Adapters: -* reshape canonical and observer data +* reshape canonical data and observer-local data * prepare structured outputs for interpretation and UI Adapters are the **translation layer**. -They change structure, not meaning. -They do not define truth. +They reshape data for downstream systems. + +For strict responsibility boundaries between adapters and lenses, see: + +→ `CrypSA_Boundary_Definitions.md` --- @@ -117,7 +134,11 @@ Lenses: Lenses are the **interpretation layer**. -They do not define truth or mutate canonical data. +They interpret data for observer experience. + +For strict responsibility boundaries between lenses and adapters, see: + +→ `CrypSA_Boundary_Definitions.md` --- @@ -152,6 +173,22 @@ This separation prevents: --- +## Responsibility Boundaries + +CrypSA enforces strict boundaries between system responsibilities. + +These boundaries prevent: + +* responsibility overlap +* architectural drift +* ambiguity in system design + +For formal definitions of these boundaries, see: + +→ `CrypSA_Boundary_Definitions.md` + +--- + ## Why This Structure Exists Traditional architectures often combine: @@ -169,30 +206,36 @@ CrypSA separates them to: * support multiple observer perspectives * allow independent evolution of layers +For how this architecture affects infrastructure design, see: + +→ `CrypSA_Infrastructure_Implications.md` + --- ## Data Flow (Simplified) -```mermaid id="e9z2gk" +```mermaid flowchart LR -A[Canonical Event History] --> B[Derived Canonical State] -B --> C[Adapters] -C --> D[Lenses] -D --> E[UI / Experience] +A["Canonical Event History"] --> B["Derived Canonical State"] +B --> C["Adapters"] +C --> D["Lenses"] +D --> E["UI / Experience"] ``` --- ## Intent Flow (Simplified) -```mermaid id="n3b6rq" +```mermaid flowchart LR -A[User Action] --> B[Candidate Event] -B --> C[Validator] -C -->|Accepted| D[Canonical Event History] -C -->|Rejected| E[Rejection] +A["User Action"] --> B["Invariant Boundary"] +B -->|Remains Local| C["Local Result"] +B -->|Crosses Boundary| D["Candidate Event"] +D --> E["Validator"] +E -->|Accepted| F["Canonical Event History"] +E -->|Rejected| G["Reconciliation"] ``` --- @@ -209,7 +252,9 @@ Truth is established through validation and recorded in canonical event history. Derived canonical state is reconstructed via replay. -> Derived canonical state is a projection of canonical event history. It is not the source of truth. +Derived canonical state is not a source of truth. + +> Derived canonical state is a projection of canonical event history. Everything else builds on that. diff --git a/CrypSA_In_5_Minutes.md b/CrypSA_In_5_Minutes.md index c30643e..0b696dd 100644 --- a/CrypSA_In_5_Minutes.md +++ b/CrypSA_In_5_Minutes.md @@ -11,6 +11,14 @@ Before reading this, you should have seen: This document explains the same system in words. +For a complete end-to-end explanation of how CrypSA operates at runtime, see: + +→ architecture/CrypSA_Runtime_Model.md + +For how CrypSA affects infrastructure and scaling, see: + +→ CrypSA_Infrastructure_Implications.md + --- ## The Core Idea @@ -26,28 +34,29 @@ In CrypSA: * **observers** simulate locally * actions are proposed as **candidate events** * a **validator** evaluates those events -* accepted events become **canonical events** -* canonical events are appended to **canonical event history** +* If accepted, an event becomes canonical and is appended to canonical event history -> The shared world is defined by accepted events, not continuously synchronized state. > Canonical event history is the source of truth. --- -## The Event Flow +## The Event Flow (Conceptual) + +Everything in CrypSA follows a consistent event-driven process: -Everything in CrypSA follows this flow: +* observers simulate locally +* candidate events are proposed +* the validator evaluates events against invariants +* if accepted, events become canonical and are appended to canonical event history +* observers derive state through replay and reconcile with canonical event history -1. An observer simulates locally -2. The observer proposes a **candidate event** -3. The **validator** checks invariants -4. If accepted → the event becomes **canonical and is appended to canonical event history** -5. Observers reconcile to canonical truth +👉 For the exact runtime flow, see: +→ architecture/CrypSA_Runtime_Model.md -This is the boundary between: +This defines the boundary between: -* local possibility -* canonical reality +* local possibility +* canonical reality --- @@ -57,6 +66,7 @@ The validator is responsible for: * accepting or rejecting candidate events * enforcing invariants +* If accepted, an event becomes canonical and is appended to canonical event history * maintaining canonical event history > The validator defines what becomes canonical. @@ -96,7 +106,7 @@ end subgraph Experience E[UI and Observer Experience] -F[Local Simulation] +F[Local Prediction] end A --> B @@ -113,7 +123,7 @@ Think of CrypSA like this: * the validator determines what becomes canonical * observers simulate what they think is happening -* only validated events become part of canonical history +* only validated events become part of canonical event history * everything else is local prediction The system is easiest to understand as **four separate responsibilities**. @@ -206,6 +216,18 @@ But: ## Derived State > Derived canonical state is a projection of canonical event history. It is not the source of truth. +> Derived canonical state is reconstructed via replay. + +--- + +## Determinism + +Given the same: + +* canonical event history +* interpretation logic + +all observers derive equivalent derived canonical state via replay. --- @@ -284,7 +306,7 @@ It is a way of structuring: * authority * validation * interpretation -* shared reality +* shared system behavior --- @@ -317,8 +339,8 @@ CrypSA is not ideal for: ## If You Understand This, You Understand CrypSA -* events become truth only after validation -* truth is an append-only history -* state is derived, not stored +* events become canonical only after validation +* canonical event history is the source of truth +* derived canonical state is reconstructed via replay * observers simulate locally and reconcile -* the validator defines canonical reality +* the validator defines what becomes canonical diff --git a/CrypSA_In_One_Diagram.md b/CrypSA_In_One_Diagram.md index d317109..6945c3b 100644 --- a/CrypSA_In_One_Diagram.md +++ b/CrypSA_In_One_Diagram.md @@ -8,8 +8,8 @@ It shows how: * observers simulate locally * candidate events cross the invariant boundary -* the validator determines canonical truth -* canonical event history drives reconstruction +* the validator determines what becomes canonical +* canonical event history drives reconstruction via replay This is the **core mental model of CrypSA in a single view**. @@ -33,7 +33,7 @@ end subgraph "Truth Layer" V[Validator] - F[Validation and Invariant Enforcement] + F[Validation Pipeline] G[Canonical Event History] H[Derived Canonical State] end @@ -50,7 +50,7 @@ V --> F F -->|Accepted| G F -->|Rejected| B -G --> H +G -->|Replay| H H --> C ``` @@ -93,6 +93,10 @@ If yes: * it must cross the invariant boundary * it must be validated before becoming canonical +If accepted: + +* If accepted, an event becomes canonical and is appended to canonical event history + --- ### Validator (Truth Authority) @@ -101,7 +105,7 @@ The validator: * evaluates candidate events * enforces invariants -* accepts or rejects proposed canonical changes +* If accepted, an event becomes canonical and is appended to canonical event history. It may run: @@ -120,14 +124,14 @@ CrypSA defines the validator as an architectural role, not a fixed machine locat If accepted: -* the event is assigned canonical ordering (`canonical_sequence`) -* the event is appended to canonical event history +* If accepted, an event becomes canonical and is appended to canonical event history +* `canonical_sequence` is assigned by the validator Canonical event history is: > the only source of truth -Derived canonical state is useful, but it is reconstructed from canonical event history and is not independently authoritative. +Derived canonical state is useful, but it is reconstructed from canonical event history via replay and is not independently authoritative. --- @@ -135,13 +139,13 @@ Derived canonical state is useful, but it is reconstructed from canonical event From canonical event history: -* derived canonical state is reconstructed +* derived canonical state is reconstructed via replay * observers receive canonical updates * local state is corrected or confirmed This ensures: -> all observers converge toward the same shared reality +> all observers converge toward equivalent derived canonical state --- @@ -152,13 +156,13 @@ This ensures: And: -> validation determines what becomes real +> validation determines what becomes canonical --- ## The Entire System in One Sentence -Observers simulate locally, propose candidate events across the invariant boundary, the validator determines which events become canonical, and canonical event history drives reconstruction of shared reality. +Observers simulate locally, propose candidate events across the invariant boundary, the validator determines which events become canonical, and canonical event history drives reconstruction of derived canonical state via replay. --- @@ -171,7 +175,7 @@ This model enables: * clear authority boundaries * replayable systems * flexible deployment (local or remote validator) -* persistent worlds defined by canonical history +* persistent worlds defined by canonical event history --- @@ -186,7 +190,7 @@ Clients → Central Authority → State Synchronization CrypSA: ```text -Observer → Validation → Canonical Event History → Reconstruction +Observer → Validation → Canonical Event History → Replay → Reconstruction ``` --- @@ -209,4 +213,4 @@ CrypSA separates: * **Interpretation** → lenses * **Truth** → validation and canonical event history -The invariant boundary and validator ensure that only valid events become part of shared reality. +The invariant boundary and validator ensure that only valid events become part of canonical event history. diff --git a/CrypSA_Terminology_Primer.md b/CrypSA_Terminology_Primer.md index 5e64147..b15d6ef 100644 --- a/CrypSA_Terminology_Primer.md +++ b/CrypSA_Terminology_Primer.md @@ -8,22 +8,39 @@ If something feels unclear, check here first. This document defines terms used in: -→ CrypSA_In_One_Diagram.md -→ CrypSA_In_5_Minutes.md +→ CrypSA_In_One_Diagram.md +→ CrypSA_In_5_Minutes.md If something here feels abstract, refer back to those documents. --- -## 🔒 Terminology Authority +## 📜 Terminology Authority -This document is the **authoritative source of all core term definitions in CrypSA**. +This document defines the authoritative terminology used across CrypSA. +It does not define runtime behavior. + +CrypSA documentation is structured across layers: + +* `/spec` — authoritative definition of runtime behavior +* `/architecture` — system structure and conceptual models +* `/architecture/CrypSA_Terminology_Primer.md` — authoritative terminology definitions + +If there is any conflict: + +* spec takes precedence over terminology usage All other documents must: -* use these terms consistently -* avoid redefining terms -* reference this document when introducing terminology +* use these terms consistently +* avoid redefining terms +* reference this document when introducing terminology + +--- + +## ⚖️ Core Rule + +If accepted, an event becomes canonical and is appended to canonical event history. --- @@ -41,9 +58,9 @@ If a definition is needed outside this document, it must use: This ensures: -* consistency across the repository -* no drift in meaning -* a single source of truth for terminology +* consistency across the repository +* no drift in meaning +* a single source of truth for terminology --- @@ -51,32 +68,59 @@ This ensures: CrypSA can be understood as four responsibilities: -* **Truth** → canonical event history and validation -* **Translation** → adapters shaping data -* **Interpretation** → lenses defining meaning -* **Experience** → UI and local interaction +* **Truth** → canonical event history and validation +* **Translation** → adapters shaping data +* **Interpretation** → lenses defining meaning +* **Experience** → UI and local interaction + +These responsibilities do not overlap. + +> Canonical event history is the source of truth. All terms below map into one of these responsibilities. --- +## 📌 Canonical Scope Rule + +The term “canonical” applies only to: + +* canonical events +* canonical event history + +It does not apply to stored state. + +Derived canonical state is a projection of canonical event history. It is not the source of truth. + +--- + +## 🔁 Replay Terminology + +Replay refers to reconstruction via canonical event replay. + +It means applying canonical events from canonical event history in canonical_sequence order to reconstruct derived canonical state. + +Replay is deterministic. + +--- + # 🔐 Validator vs Server (Critical Distinction) The **validator** is the authority over canonical truth. It: -* validates candidate events -* enforces invariants -* appends accepted events to canonical event history +* validates candidate events +* enforces invariants +* If accepted, an event becomes canonical and is appended to canonical event history A **server** is a deployment of a validator. The validator: -* may run locally (same process as an observer) -* may run remotely (shared system) -* may run in a host-based configuration +* may run locally (same process as an observer) +* may run remotely (shared system) +* may run in a host-based configuration > The validator’s responsibilities do not change based on deployment. @@ -86,16 +130,16 @@ The validator: Use **validator** when referring to: -* validation -* canonical truth -* event acceptance/rejection -* canonical sequencing +* validation +* canonical truth +* event acceptance/rejection +* canonical sequencing Use **server** only when referring to: -* network topology -* deployment -* infrastructure +* network topology +* deployment +* infrastructure --- @@ -112,7 +156,7 @@ Use **server** only when referring to: ## ⚠️ Important -If a sentence is still correct when the validator is running locally, +If a sentence is still correct when the validator is running locally, then **“validator” is the correct term**, not “server”. --- @@ -127,18 +171,31 @@ The **validator** determines what becomes canonical. It: -* accepts or rejects candidate events -* enforces invariants and rules -* maintains canonical event history +* accepts or rejects candidate events +* enforces invariants and rules +* maintains canonical event history The validator is a **role**, not a machine. It may run: -* locally (alongside an observer) -* remotely (shared across observers) +* locally (alongside an observer) +* remotely (shared across observers) -> In CrypSA, truth is defined by validation — not by location. +> The validator defines what becomes canonical. + +--- + +## Invariant Boundary + +The invariant boundary is where candidate events are evaluated by the validator. + +It separates: + +* observer-proposed events +* canonical truth + +Only events that pass validation cross this boundary and become canonical. --- @@ -148,24 +205,24 @@ A **local validator** runs within the observer’s environment. Examples: -* same process -* same application -* same device +* same process +* same application +* same device Use cases: -* single-player or offline operation -* development and testing -* local-first systems -* resilience during network interruption +* single-player or offline operation +* development and testing +* local-first systems +* resilience during network interruption Even when local, the validator remains a **separate logical role**. The invariant boundary still exists: -* observer proposes candidate events -* validator evaluates them -* canonical event history is updated +* observer proposes candidate events +* validator evaluates them +* canonical event history is updated --- @@ -177,9 +234,9 @@ Observers communicate with it over a network. Use cases: -* shared canonical truth -* persistent multiplayer systems -* distributed environments +* shared canonical truth +* persistent multiplayer systems +* distributed environments > Deployment changes location, not responsibility. @@ -191,21 +248,22 @@ A **server** is a remote deployment of a validator. It is an infrastructure term, not an authority role. -Not all validators are servers. +Not all validators are servers. All servers host a validator. --- ## Canonical Event -A **canonical event** is an event that has been: +A **canonical event** is an event that has become canonical through validation. + +If accepted, an event becomes canonical and is appended to canonical event history. -* validated -* accepted -* assigned a `canonical_sequence` -* made immutable +Canonical events: -Canonical events define **truth**. +* are immutable +* have a `canonical_sequence` +* define truth --- @@ -213,45 +271,43 @@ Canonical events define **truth**. A **candidate event** is: -* proposed by an observer -* not yet validated -* subject to rejection +* proposed by an observer +* not yet validated +* subject to rejection -It represents **intent**, not truth. +It represents **intent**, not truth, and does not affect canonical event history unless accepted. --- ## Invariant -An **invariant** is a rule that must always hold. +An **invariant** is a rule that must always hold for canonical truth. Examples: -* a player cannot have negative resources -* two objects cannot occupy the same exclusive space +* a player cannot have negative resources +* two objects cannot occupy the same exclusive space -Invariants protect **canonical truth**. +Invariants protect canonical truth. --- ## Validation -**Validation** is the process of evaluating a candidate event. +**Validation** is the process performed by the validator to evaluate a candidate event. It includes: -* schema validation -* identity validation -* precondition checks -* invariant validation -* rule validation +* schema validation +* identity validation +* precondition checks +* invariant validation +* rule validation Result: -* valid → becomes canonical and is appended to canonical event history -* invalid → rejected - -Validation determines what becomes **truth**. +* If accepted, an event becomes canonical and is appended to canonical event history +* If rejected, the event does not become canonical --- @@ -259,8 +315,8 @@ Validation determines what becomes **truth**. The **canonical event history** is: -* the ordered sequence of canonical events -* the authoritative record of what has happened +* the ordered sequence of canonical events +* the authoritative record of what has happened > Canonical event history is the source of truth. @@ -268,27 +324,18 @@ Everything else is derived from this. --- -## Replay - -**Replay** is the process of: - -* applying canonical events in order -* reconstructing derived canonical state deterministically - ---- - ## Derived Canonical State The **derived canonical state** is: -* the current world state -* produced via replay +* the current world state +* produced via replay It is: -* not authoritative -* not stored as truth -* always reconstructable +* not authoritative +* not stored as truth +* always reconstructable > Derived canonical state is a projection of canonical event history. It is not the source of truth. @@ -298,20 +345,26 @@ It is: An **observer**: -* simulates the world locally -* proposes candidate events -* reconciles with canonical truth +* simulates the world locally +* proposes candidate events +* reconciles with canonical truth Observers operate in the **experience layer**. +Observers do not define truth. + --- ## Observer Reconciliation **Observer reconciliation** is when: -* local simulation is updated -* to match canonical outcomes +* local simulation is updated +* to match canonical outcomes + +This occurs via canonical event replay, aligning local derived state with canonical outcomes. + +Observers do not modify canonical event history directly. --- @@ -321,12 +374,12 @@ An **adapter** reshapes data. It: -* transforms canonical and observer data -* produces structured outputs +* transforms canonical and observer data +* produces structured outputs Adapters belong to the **translation layer**. -They change structure, not meaning. +Adapters reshape data without affecting truth or interpreting meaning. --- @@ -336,13 +389,13 @@ A **lens** interprets data. It determines: -* meaning -* relevance -* context for an observer +* meaning +* relevance +* context for an observer Lenses belong to the **interpretation layer**. -They do not define truth or modify canonical data. +Lenses interpret data but do not modify canonical data or define truth. --- @@ -350,15 +403,21 @@ They do not define truth or modify canonical data. The **experience layer** includes: -* rendering -* input -* local feedback +* rendering +* input +* local feedback It is: -* responsive -* immediate -* non-authoritative +* responsive +* immediate +* non-authoritative + +--- + +## Replay + +**Replay** reconstructs derived canonical state via canonical event replay. --- @@ -366,11 +425,11 @@ It is: CrypSA separates the system into four responsibilities: -* **truth** → canonical event history and validation -* **translation** → adapters shape data -* **interpretation** → lenses define meaning -* **experience** → local interaction +* **truth** → canonical event history and validation +* **translation** → adapters shape data +* **interpretation** → lenses define meaning +* **experience** → local interaction And critically: -> the validator defines what becomes canonical, regardless of deployment +> The validator defines what becomes canonical, regardless of deployment. diff --git a/CrypSA_Worked_Example.md b/CrypSA_Worked_Example.md index 25a92b5..c35455c 100644 --- a/CrypSA_Worked_Example.md +++ b/CrypSA_Worked_Example.md @@ -1,14 +1,30 @@ # CrypSA Worked Example -> Illustrative note: This document is illustrative. +> Illustrative note: This document is illustrative. > For authoritative behavior, see `spec/`. --- -This example uses concepts from: +This example demonstrates the runtime model described in: -→ CrypSA_In_5_Minutes.md -→ CrypSA_Terminology_Primer.md +→ ../architecture/CrypSA_Runtime_Model.md + +This example also uses concepts from: + +→ ../architecture/CrypSA_In_5_Minutes.md +→ ../architecture/CrypSA_Terminology_Primer.md + +For formal responsibility boundaries, see: + +→ ../architecture/CrypSA_Boundary_Definitions.md + +For a minimal executable version of this example, see: + +→ ../implementation/CrypSA_Minimal_Runtime_Walkthrough.md + +For how this example translates to infrastructure design, see: + +→ ../architecture/CrypSA_Infrastructure_Implications.md You should be familiar with: @@ -18,11 +34,11 @@ You should be familiar with: --- -## 📜 Specification Authority +## 📜 Authority Level The `/spec` directory is the **authoritative definition of runtime behavior**. -This document shows how the system behaves. +This document demonstrates how the system behaves using the runtime model. The spec defines how it must behave. If there is any conflict, **the spec takes precedence**. @@ -31,39 +47,46 @@ If there is any conflict, **the spec takes precedence**. ## What This Example Shows -This walkthrough follows a complete event lifecycle: +This walkthrough demonstrates the runtime model in action: + +* a local action +* becomes a candidate event +* crosses the invariant boundary +* if accepted, becomes canonical and is appended to canonical event history +* is applied through replay to derive state +* and is reconciled by observers -* a local action -* becomes a candidate event -* crosses the invariant boundary -* becomes canonical (or is rejected) -* updates canonical event history -* and is reconciled by observers +👉 For the full runtime flow, see: +→ ../architecture/CrypSA_Runtime_Model.md --- ## 📊 Runtime Flow Overview -```mermaid id="c3w1n8" +```mermaid flowchart LR -A[Player Action] --> B[Local Simulation] -B --> C[Create Candidate Event] +A[Observer Action] --> B[Local Prediction] +B --> C[Observer Creates Candidate Event] C --> D[Submit to Validator] -D --> E[Validation Pipeline] +D --> E[Validation] E -->|Accepted| F[Canonical Event History] E -->|Rejected| G[Rejection Result] F --> H[Replay] H --> I[Derived Canonical State] -I --> J[Broadcast] +I --> J[Distribution] J --> K[Observer Reconciliation] G --> K ``` +> This diagram illustrates the runtime model. +> For the authoritative conceptual flow, see: +> → ../architecture/CrypSA_Runtime_Model.md + --- ## Scenario @@ -104,9 +127,9 @@ At this point: # Phase 2 — Candidate Event Creation -The observer creates a **candidate event**: +The observer creates a **candidate event** (not yet canonical): -```id="v4dq6z" +```text event_type = place_structure actor_id = player_A target_ids = [tile_42] @@ -130,7 +153,7 @@ This event represents **intent**, not reality. # Phase 3 — Submission -The observer submits the event to the validator. +The observer submits the candidate event to the validator. State at this moment: @@ -141,55 +164,38 @@ State at this moment: --- -# Phase 4 — Validation Pipeline (Validator) +# Phase 4 — Validation (Validator) The event crosses the **invariant boundary**. -The validator evaluates: - -### Schema Validation +The validator evaluates the candidate event through validation. -✅ pass - -### Identity Validation - -✅ pass - -### Precondition Validation - -✅ pass - -### Invariant Validation - -✅ pass - -### Rule Validation - -✅ pass +👉 For how validation fits into the full runtime model, see: +→ ../architecture/CrypSA_Runtime_Model.md --- -# Phase 5 — Acceptance +# Phase 5 — Validation Outcome (Accepted) The validator accepts the event. +If accepted, an event becomes canonical and is appended to canonical event history. + Canonical metadata is assigned: -```id="f0w3px" +```text canonical_event_id = canon_1203 canonical_sequence = 1203 accepted_at = timestamp ``` -The event becomes canonical and is appended to **canonical event history**. - -> This is the moment the action becomes canonical. +This event is now **canonical**. --- # Phase 6 — Replay and Derived State -Replay applies canonical events in `canonical_sequence` order. +Replay applies canonical events from canonical event history in `canonical_sequence` order. Derived canonical state updates: @@ -200,9 +206,9 @@ Derived canonical state updates: --- -# Phase 7 — Broadcast +# Phase 7 — Distribution -The canonical event is propagated to observers. +The canonical event is distributed to observers. --- @@ -211,7 +217,7 @@ The canonical event is propagated to observers. Each observer compares: * local predicted state -* canonical update +* canonical event --- @@ -238,8 +244,8 @@ After reconciliation: * lenses interpret meaning * UI renders the result -```text id="9tb7mq" -Canonical Update → Adapter → Lens → UI +```text +Canonical Event → Adapter → Lens → UI ``` --- @@ -254,13 +260,13 @@ Two players attempt to place on tile_42. * evaluates both candidate events * accepts the first valid event -* rejects the second +* the second event does not become canonical and does not enter canonical event history --- ## Rejection Result -```id="sx9k2u" +```text result = rejected reason = precondition_failed ``` @@ -272,7 +278,7 @@ reason = precondition_failed Rejected observer: * removes predicted structure -* updates to canonical state +* updates to canonical state via replay --- @@ -300,4 +306,4 @@ This example corresponds to: # One Sentence Summary -A local action becomes a candidate event, the validator evaluates it, accepted events become canonical and are appended to canonical event history, and observers reconcile their local simulation to that shared history. +A local action becomes a candidate event, the validator evaluates it, if accepted, an event becomes canonical and is appended to canonical event history, and observers reconcile their local prediction to that shared history diff --git a/DOCS_STRUCTURE.md b/DOCS_STRUCTURE.md index 23969d9..2c1f180 100644 --- a/DOCS_STRUCTURE.md +++ b/DOCS_STRUCTURE.md @@ -33,7 +33,7 @@ These documents provide: These define the system’s behavior and structure: -* `spec/` — runtime behavior (**highest authority**) +* `spec/` — runtime behavior and validation rules (**highest authority for behavior**) * `architecture/` — system structure and responsibilities These documents define: @@ -43,6 +43,12 @@ These documents define: * system responsibilities * invariant enforcement +Core truths: + +* canonical event history is the source of truth +* the validator defines what becomes canonical +* derived canonical state is reconstructed via replay of canonical event history + --- ## Implementation Direction @@ -55,7 +61,7 @@ These documents: * guide system construction * describe practical approaches -* do not redefine system behavior +* must not redefine system behavior defined in the spec --- @@ -88,7 +94,7 @@ These documents: * support understanding * must align with authoritative sources -* must not introduce new behavior +* must not introduce or reinterpret system behavior --- @@ -110,13 +116,13 @@ These documents: If multiple documents appear to describe the same concept, the following precedence applies: -1. `spec/` — runtime behavior (highest authority) +1. `spec/` — runtime behavior 2. `architecture/` — system structure 3. `implementation/` — build direction 4. `teaching/` — examples and explanation 5. supporting and exploratory content -> In case of conflict, higher-authority documents override lower-authority ones. +> In case of conflict, higher-authority documents override lower-authority ones and define the correct interpretation. Supporting and exploratory documents must not be treated as authoritative definitions of CrypSA behavior. @@ -149,4 +155,4 @@ This prevents: ## One Sentence Summary -CrypSA documentation is structured so that authoritative definitions live in `spec/` and `architecture/`, while all other documents support understanding without redefining behavior. +CrypSA documentation is structured so that authoritative definitions live in `spec/` and `architecture/`, canonical event history is the source of truth, and all other documents support understanding without redefining behavior. diff --git a/FAQ.md b/FAQ.md index ee1b4f5..227e2dc 100644 --- a/FAQ.md +++ b/FAQ.md @@ -22,7 +22,9 @@ CrypSA is an event-driven architecture where: * observers simulate locally * actions are proposed as candidate events * a validator evaluates those events -* accepted events define shared reality through canonical event history +* If accepted, an event becomes canonical and is appended to canonical event history + +👉 Canonical event history is the source of truth. --- @@ -70,13 +72,14 @@ It depends on how the system is deployed. * the observer continues local simulation * no new canonical events can be accepted * canonical updates stop arriving -* local state may temporarily diverge +* local derived state may temporarily diverge When the connection is restored: * canonical updates are fetched -* reconciliation occurs -* the observer converges to canonical state +* canonical event history is synchronized +* reconstruction via replay of canonical event history occurs +* the observer converges to derived canonical state --- @@ -94,7 +97,11 @@ Yes — but differently than traditional systems. The validator does not simulate everything. -Instead, it is authoritative over: +Instead: + +> The validator defines what becomes canonical. + +It is authoritative over: * which events are accepted * what becomes canonical event history @@ -110,7 +117,11 @@ Observers can propose events, but: * all canonical changes must be validated * invalid or conflicting events are rejected -Observers have freedom to simulate, not authority to define truth. +Observers simulate freely, but: + +> If accepted, an event becomes canonical and is appended to canonical event history. + +Observers do not define truth. --- @@ -127,7 +138,7 @@ This allows: * flexibility * reduced synchronization overhead -The validator still determines what becomes canonical. +The validator still defines what becomes canonical. --- @@ -135,11 +146,16 @@ The validator still determines what becomes canonical. It is similar, but not identical. +Event sourcing: + +* stores a history of events + CrypSA: -* is designed for interactive simulations -* includes invariant validation as a core system -* explicitly models observers and reconstruction +* uses validated events to define canonical event history +* includes invariant enforcement as a core responsibility +* explicitly models observers and reconstruction via canonical event replay +* reconstructs derived canonical state via replay --- @@ -155,7 +171,7 @@ It can be deployed as: * host-based * dedicated validator -The architecture defines **how truth is determined**, not how networking must be structured. +The architecture defines how truth is determined, not how networking must be structured. --- @@ -166,8 +182,9 @@ The validator: * receives candidate events * validates them * enforces invariants +* determines whether an event becomes canonical * assigns canonical ordering (`canonical_sequence`) -* records accepted events +* If accepted, an event becomes canonical and is appended to canonical event history It does not need to simulate the entire world continuously. @@ -183,7 +200,9 @@ The validator: * accepts one valid event * rejects the other -The rejected observer reconciles to canonical state. +If accepted, an event becomes canonical and is appended to canonical event history. + +The rejected observer reconciles via canonical event replay. --- @@ -192,7 +211,7 @@ The rejected observer reconciles to canonical state. If an observer predicts incorrectly: * the validator rejects the event -* the observer corrects its local state +* the observer corrects its local state via replay of canonical event history This is expected and correct behavior. @@ -200,32 +219,30 @@ This is expected and correct behavior. ## How does CrypSA prevent observer-side logic from breaking the system? -CrypSA relies on strict separation of responsibilities: +CrypSA enforces strict separation of responsibilities: -* the validator defines truth -* adapters shape data -* lenses interpret meaning -* UI presents the result +* the validator defines what becomes canonical +* canonical event history is the source of truth +* derived state is reconstructed via replay In addition: -* observers emit requests representing intent -* canonical changes occur only through validated events -* adapters prevent UI and lenses from accessing raw runtime structures +* observers emit candidate events representing intent +* canonical changes occur only through validation +* adapters and lenses prevent direct access to runtime internals --- ## Is CrypSA deterministic? -Yes, at the canonical level via deterministic replay. +Yes — at the canonical level. Given the same: * canonical event history -* rules -* definitions +* interpretation logic -All observers must derive the same state. +all observers must derive equivalent derived canonical state via replay of canonical event history. --- @@ -234,14 +251,14 @@ All observers must derive the same state. Not as truth. * canonical truth = canonical event history -* derived state = reconstructed via replay +* derived canonical state = reconstructed via replay * snapshots = reconstruction checkpoints --- ## What are snapshots? -Snapshots are stored derived state used to: +Snapshots are stored derived canonical state used to: * speed up loading * reduce replay cost @@ -257,7 +274,7 @@ Yes — this is a core design goal. CrypSA supports a **local-first development model**: -```text +```text id="v42c9u" Local Validator → Host-Based → Dedicated Validator ``` @@ -306,7 +323,7 @@ CrypSA is: * supported by specifications * backed by a teaching prototype -It is not yet a production system. +It does not yet include a full reference implementation or minimal validator. --- @@ -321,4 +338,4 @@ It is not yet a production system. ## One Sentence Summary -CrypSA is a system where observers simulate locally, a validator evaluates events, and shared reality is defined by canonical event history. +CrypSA is a system where observers simulate locally, a validator evaluates candidate events, and canonical event history is the source of truth. diff --git a/How_To_Read_CrypSA.md b/How_To_Read_CrypSA.md index 80b47ab..bc1eae6 100644 --- a/How_To_Read_CrypSA.md +++ b/How_To_Read_CrypSA.md @@ -6,20 +6,48 @@ This document helps readers navigate the CrypSA repository effectively. CrypSA is structured as a layered architecture with: -- conceptual explanations -- architectural models -- authoritative specifications -- implementation guidance +* conceptual explanations +* architectural models +* authoritative specifications +* implementation guidance Different readers should approach the repo differently. --- -## Core Principle +## 📜 Authority Level + +This document provides guidance for navigating the repository. +It does not define system behavior or architecture. + +--- + +## Recommended Starting Point + +If you are unsure where to start: + +1. CrypSA_In_One_Diagram.md +2. CrypSA_In_5_Minutes.md +3. CrypSA_Terminology_Primer.md + +This is the fastest correct path into CrypSA. + +--- + +## Related Documents + +* `README.md` — project overview +* `architecture/` — system structure and responsibilities +* `spec/` — authoritative runtime behavior +* `CrypSA_Terminology_Primer.md` — CrypSA language and terms + +--- -👉 CrypSA is not meant to be read linearly. +## Core Principle -👉 It is meant to be read based on your goal. +👉 Start with the Quick Start Paths below. +👉 Do not read the repository randomly. +👉 Follow a path based on your goal. --- @@ -29,15 +57,15 @@ Different readers should approach the repo differently. If you want to understand what CrypSA is: -1. CrypSA_In_One_Diagram.md -2. CrypSA_In_5_Minutes.md -3. CrypSA_Terminology_Primer.md +1. CrypSA_In_One_Diagram.md +2. CrypSA_In_5_Minutes.md +3. CrypSA_Terminology_Primer.md This gives you: -- the core idea -- the key concepts -- the language of the system +* the core idea +* the key concepts +* the language of the system --- @@ -45,15 +73,15 @@ This gives you: If you want to understand how CrypSA works: -1. CrypSA_In_5_Minutes.md -2. CrypSA_Worked_Example.md -3. architecture/ +1. CrypSA_In_5_Minutes.md +2. CrypSA_Worked_Example.md +3. architecture/ This gives you: -- the mental model -- the system structure -- how concepts connect +* the mental model +* the system structure +* how concepts connect --- @@ -61,17 +89,17 @@ This gives you: If you want to build a system using CrypSA: -1. spec/ -2. implementation/minimal_validator/ -3. implementation/CrypSA_Local_First_Development_Approach.md +1. implementation/CrypSA_Local_First_Development_Approach.md +2. implementation/minimal_validator/ +3. spec/ This gives you: -- authoritative behavior -- a starting implementation -- a practical build path +* how to build +* what to build +* the rules your implementation must follow -> The spec defines runtime behavior. +> The spec defines runtime behavior. > Your implementation must follow it. 👉 Start with the minimal validator, then expand outward. @@ -82,16 +110,16 @@ This gives you: If you want full architectural clarity: -1. architecture/ -2. spec/ -3. diagrams/ +1. architecture/ +2. spec/ +3. diagrams/ This gives you: -- system boundaries -- validation model -- event model -- consistency model +* system boundaries +* validation model +* event model +* consistency model --- @@ -99,13 +127,13 @@ This gives you: If you want to understand what CrypSA leaves open: -👉 architecture/CrypSA_Invariants_and_Design_Space.md +👉 architecture/CrypSA_Invariants_and_Design_Space.md This explains: -- what is fixed -- what is product-dependent -- how to make design decisions +* what is fixed +* what is product-dependent +* how to make design decisions --- @@ -119,15 +147,20 @@ CrypSA is divided into layers: Defines: -- canonical event history -- validator authority -- invariant boundary +* canonical event history +* validator authority +* invariant boundary +* the canonical event lifecycle (see spec for exact behavior) Important: -👉 This is the foundation of all CrypSA systems and defines canonical truth. +👉 The runtime model defines the authoritative conceptual flow of the system. + +👉 This model connects observers, the invariant boundary, validation, and canonical event history. + +👉 This is the foundation of all CrypSA systems and defines canonical event history as the source of truth. -👉 All other layers depend on this model +👉 All other layers depend on this model --- @@ -135,14 +168,14 @@ Important: Explain: -- what CrypSA is -- why it exists -- how to think about it +* what CrypSA is +* why it exists +* how to think about it Examples: -- CrypSA_In_5_Minutes.md -- CrypSA_Worked_Example.md +* CrypSA_In_5_Minutes.md +* CrypSA_Worked_Example.md --- @@ -150,17 +183,20 @@ Examples: Defines: -- system structure -- responsibilities -- boundaries between components +* system structure +* responsibilities +* boundaries between components Important: -👉 Architecture explains how the system is organized. +👉 Architecture defines structure and responsibility boundaries. -👉 It defines structure, not runtime behavior. +👉 It does not define runtime behavior. -👉 The spec defines behavior within that structure. +👉 The spec defines exact runtime behavior within that structure. + +👉 For strict separation of responsibilities, see: +`architecture/CrypSA_Boundary_Definitions.md` --- @@ -168,14 +204,14 @@ Important: Defines: -- runtime behavior -- validation rules -- event lifecycle -- consistency guarantees +* runtime behavior +* validation rules +* event lifecycle +* consistency guarantees Important: -👉 The spec is the source of truth for system behavior +👉 The spec is the source of truth for system behavior --- @@ -183,15 +219,15 @@ Important: Provides: -- build strategies -- reference implementations -- practical guidance +* build strategies +* reference implementations +* practical guidance Important: 👉 Implementation docs are not authoritative -👉 They must not redefine system behavior +👉 They must not redefine system behavior --- @@ -199,14 +235,14 @@ Important: Provide: -- visual explanations -- conceptual overviews +* visual explanations +* conceptual overviews Important: 👉 Diagrams are illustrative -👉 They must align with architecture and spec +👉 They must align with architecture and spec --- @@ -214,8 +250,7 @@ Important: ## 1. Do not treat architecture docs as spec -Architecture explains structure. - +Architecture defines structure. Spec defines behavior. --- @@ -223,7 +258,6 @@ Spec defines behavior. ## 2. Do not treat implementation docs as rules Implementation docs show possible approaches. - They are not required patterns. --- @@ -238,31 +272,39 @@ If there is any ambiguity: ## 4. Use the design space intentionally -CrypSA is not all-or-nothing. +CrypSA is not an all-or-nothing architecture. You are expected to: -- choose reconciliation strategies -- choose prediction models -- choose deployment models +* choose reconciliation strategies +* choose prediction models +* choose deployment models -👉 within the constraints of CrypSA invariants +👉 within the constraints of CrypSA invariants 👉 CrypSA provides structure for these decisions, not answers for all of them. --- -# Suggested Reading Order (Complete Path) +## 5. Do not treat derived state as truth + +Derived canonical state is a projection of canonical event history. + +It must always be reconstructable via replay. + +--- + +# Suggested Reading Order (Full Understanding) For a full understanding: -1. CrypSA_In_One_Diagram.md -2. CrypSA_In_5_Minutes.md -3. CrypSA_Terminology_Primer.md -4. CrypSA_Worked_Example.md -5. architecture/ -6. spec/ -7. implementation/ +1. CrypSA_In_One_Diagram.md +2. CrypSA_In_5_Minutes.md +3. CrypSA_Terminology_Primer.md +4. CrypSA_Worked_Example.md +5. architecture/ +6. spec/ +7. implementation/ --- @@ -270,15 +312,17 @@ For a full understanding: CrypSA is a structured architecture model with: -- strict invariants -- flexible implementation space -- layered documentation +* strict invariants +* flexible implementation space +* layered documentation -👉 Read based on your goal, not in strict sequence. +👉 Read based on your goal, not randomly. 👉 Always distinguish between: -- concept (what it means) -- architecture (how it is structured) -- specification (how it behaves) -- implementation (how it is built) +* concept (what it means) +* architecture (how it is structured) +* specification (how it behaves) +* implementation (how it is built) + +👉 Canonical event history is the source of truth. diff --git a/README.md b/README.md index 37765af..76f40d3 100644 --- a/README.md +++ b/README.md @@ -1,82 +1,124 @@ +> ⚠️ This repository defines an architecture model. +> If you are reviewing it, please read REVIEWER_GUIDE.md first. + # CrypSA — Cryptid Server Architecture -CrypSA defines how systems agree on truth through validated canonical events. +CrypSA defines how systems establish canonical truth through validated canonical events and deterministic replay. -It is an event-driven architecture for building persistent digital worlds. +In CrypSA: -Rather than synchronizing full world state, CrypSA synchronizes validated canonical events under invariant rules. +* the validator defines what becomes canonical +* canonical event history is the source of truth +* derived canonical state is reconstructed via replay + +It is an event-driven architecture for building persistent digital worlds. -All canonical changes pass through the invariant boundary, where system invariants are enforced. +Rather than synchronizing world state, CrypSA synchronizes validated canonical events governed by invariants. -Observers simulate locally. The validator defines what becomes canonical—and therefore what becomes shared reality. +All canonical changes must cross the invariant boundary, where invariants are enforced before events can become canonical. Observers perform local simulation and predictive behavior. > Reality is not synchronized — it is agreed upon through validated events. -> The validator defines what becomes canonical. > Canonical event history is the source of truth. -The validator may run locally or remotely, but its role does not change. +The validator may run locally or remotely, but its role as the authority of canonical truth does not change. + +--- + +## 📘 How to Navigate This Repo + +If you want to understand how to navigate CrypSA based on your goal and role: + +👉 How_To_Read_CrypSA.md + +For core terminology: + +👉 CrypSA_Terminology_Primer.md --- ## 🚀 Start Here -If you're new to CrypSA, follow this path: +If you're new to CrypSA, follow this path in order: 1. 🧭 CrypSA_In_One_Diagram.md — see the system at a glance 2. 📘 CrypSA_In_5_Minutes.md — understand the core idea -3. 📖 CrypSA_Terminology_Primer.md — learn the language -4. 📖 CrypSA_Worked_Example.md — see it in action +3. ⚙️ architecture/CrypSA_Runtime_Model.md — understand how the system operates end-to-end +4. 📖 CrypSA_Terminology_Primer.md — learn the language +5. 📖 CrypSA_Worked_Example.md — see it in action +6. 🛠 implementation/CrypSA_Minimal_Runtime_Walkthrough.md — see the smallest working system --- -## 📘 How to Navigate This Repo +## 🏗 Infrastructure Implications -If you want to understand how to navigate CrypSA based on your goal and role: +CrypSA changes how systems distribute: + +* computation +* state +* synchronization + +Instead of relying on continuous server-side simulation and state synchronization: + +* observers perform local prediction +* canonical truth is defined by validated events +* state is reconstructed via replay -👉 docs/How_To_Read_CrypSA.md +This results in a different distribution of infrastructure responsibilities. + +For a neutral breakdown of these changes, see: + +👉 architecture/CrypSA_Infrastructure_Implications.md --- -## ⚙️ System Model (At a Glance) +## ⚙️ Canonical Event Lifecycle (At a Glance) + +The canonical event lifecycle is defined by the CrypSA runtime model, which is the authoritative conceptual flow of the system: -CrypSA follows a consistent event lifecycle: +👉 architecture/CrypSA_Runtime_Model.md -1. Observer simulates locally -2. Observer proposes a **candidate event** -3. Validator evaluates the event -4. If accepted, an event becomes canonical and is appended to canonical event history -5. Observers reconcile to canonical truth +At a high level: + +1. Observers create candidate events +2. Events are validated by the validator +3. If accepted, an event becomes canonical and is appended to canonical event history +4. Observers derive state through replay and reconciliation This defines the boundary between: * local simulation (non-authoritative) -* canonical reality (validator-defined) +* canonical reality (validator-defined) -Canonical event history is an append-only log that defines the shared reality of the system. +Canonical event history is an append-only log. +It is never mutated, only extended through accepted events. All derived state must be consistent with this history. +Canonical event history is the source of truth. + --- ## 🛠 Build CrypSA -Start implementing a CrypSA system with the minimal validator: +Start with the smallest working system: -👉 implementation/minimal_validator/CrypSA_Minimal_Validator_v0.1.md +👉 implementation/CrypSA_Minimal_Runtime_Walkthrough.md -Then follow: +Then explore: -👉 implementation/CrypSA_Local_First_Development_Approach.md +👉 implementation/minimal_validator/CrypSA_Minimal_Validator_v0.1.md +👉 implementation/CrypSA_Local_First_Development_Approach.md --- ## 🧠 What CrypSA Is (and Is Not) -CrypSA defines how systems establish and maintain canonical truth over time through validated events. +CrypSA defines how systems establish and maintain canonical truth through validated canonical events. It provides a model where: * truth is validated, not assumed +* the validator defines what becomes canonical * state is derived, not synchronized * simulation is local, but canonical authority is enforced by the validator @@ -90,11 +132,11 @@ CrypSA is: * a structured architecture model * a set of invariants around truth, validation, and canonical event history -* a framework for building replayable, consistent systems +* a framework for building replayable and consistent systems It defines: -👉 what must be true for a system to maintain canonical agreement +👉 what must be true for a system to maintain canonical agreement CrypSA is typically integrated alongside existing systems such as game engines, simulation layers, and networking stacks. @@ -113,6 +155,7 @@ CrypSA is not: * a networking library * a state replication system * an ECS framework +* a state synchronization model > CrypSA defines truth agreement, not rendering, transport, or simulation. @@ -133,27 +176,37 @@ CrypSA intentionally leaves open: * how reconciliation and prediction are handled * how systems are shaped to meet product goals -👉 CrypSA defines invariants and structure, not a single implementation. +👉 CrypSA defines invariants and structure, not a single implementation. -👉 CrypSA provides a structured design space for making these decisions. +👉 CrypSA provides a structured design space for making these decisions. -👉 Implementers are expected to choose these based on product requirements. +👉 Implementers are expected to choose these based on product requirements. + +This flexibility is intentional. + +CrypSA is designed to support multiple valid implementations that all preserve canonical truth through validation and canonical event history. --- -### 📘 Learn More +## 📘 Learn More For a full breakdown of invariants and product-dependent design: -👉 architecture/CrypSA_Invariants_and_Design_Space.md — defines invariants and guides product-level design decisions +👉 architecture/CrypSA_Invariants_and_Design_Space.md + +For strict separation of responsibilities: + +👉 architecture/CrypSA_Boundary_Definitions.md + +--- ## ⚙️ How CrypSA Works ```mermaid flowchart LR -A[Player Action] --> B[Local Simulation] -B --> C[Create Candidate Event] +A[Player Action] --> B[Local Prediction] +B --> C[Observer Creates Candidate Event] C --> D[Submit to Validator] D --> E[Validation Pipeline] @@ -171,175 +224,6 @@ G --> K > If accepted, an event becomes canonical and is appended to canonical event history. ---- - -## 📚 Documentation Guide - -CrypSA documentation is structured by role: - -| Type | Purpose | -| ------------ | --------------------------------------- | -| Conceptual | Mental models and explanations | -| Architecture | System structure and boundaries | -| Spec | Authoritative runtime behavior | -| Example | Concrete walkthroughs | -| Diagram | Visual explanations (non-authoritative) | -| Exploratory | Non-final ideas | - -👉 Full structure: DOCS_STRUCTURE.md - ---- - -## 🧭 Full Reading Path - -### Foundation - -* CrypSA_In_One_Diagram.md -* CrypSA_In_5_Minutes.md -* CrypSA_Terminology_Primer.md - -### Motivation - -* CrypSA_Why_It_Exists.md - -### Example - -* CrypSA_Worked_Example.md - -### Architecture - -* architecture/ - -### Runtime (Required for Implementation) - -* spec/ - -### Implementation - -* implementation/ - ---- - -## 👥 Who This Is For - -### 🧠 Learners - -Start with: - -* CrypSA_In_5_Minutes.md -* CrypSA_Worked_Example.md - ---- - -### ⚙️ Implementers - -Focus on: - -* spec/ -* minimal validator docs - -> The spec defines behavior — your implementation must follow it. - ---- - -### 🧱 Contributors - -Read: - -* terminology primer -* architecture -* spec -* CONTRIBUTING.md - -Before submitting: - -→ run: `docs/DOCS_LINT_CHECKLIST.md` -→ ensure the docs gate will pass - -Follow: - -* do not redefine terminology -* do not duplicate definitions -* do not introduce behavior outside the spec - ---- - -## 🚧 Project Status — v1.0 - -CrypSA v1.0 defines the core architecture and runtime model. - -It is: - -* stable in its core concepts -* consistent in terminology and structure -* ready for implementation - -Ongoing work includes: - -* reference implementations -* documentation refinement - -> v1.0 is a stable architectural baseline, not a finished product. - ---- - -## 🔢 Versioning Philosophy - -* v1.x → stable architecture, evolving implementations -* v2.0 → breaking architectural changes - ---- - -## 🧠 Why CrypSA Exists - -Traditional systems: - -Client → Server → State Sync - -CrypSA: - -Observer → Validator → Canonical Event History → Reconstruction - -Instead of synchronizing state, it: - -* validates events -* records canonical history -* reconstructs reality deterministically - ---- - -## 🧩 Key Concepts - -* Validator -* Canonical Events -* Invariants -* Observers -* Lenses - -See: - -CrypSA_Terminology_Primer.md - ---- - -## 📁 Repository Structure - -* architecture/ -* spec/ -* implementation/ -* diagrams/ -* exploratory/ -* teaching/ -* atlas/ - ---- - -## 👤 Author - -Beau Wells - ---- - -## One Sentence Summary +For the full runtime flow, see: -CrypSA defines how systems agree on truth through validated canonical events. +👉 architecture/CrypSA_Runtime_Model.md diff --git a/REVIEWER_GUIDE.md b/REVIEWER_GUIDE.md new file mode 100644 index 0000000..7a41907 --- /dev/null +++ b/REVIEWER_GUIDE.md @@ -0,0 +1,174 @@ +# 🧠 CrypSA Reviewer Guide + +This document provides important context for reviewing the CrypSA repository. + +Reading this ensures the project is evaluated using the correct expectations. + +--- + +## What CrypSA Is + +CrypSA is an **architecture model**, not a framework, library, or complete product. + +It defines: + +* how truth is established +* how events become canonical +* how state is derived +* how systems remain replayable and consistent + +It does **not** provide: + +* a full implementation +* a fixed runtime design +* a required networking model + +--- + +## What to Evaluate + +This repository should be evaluated on: + +* clarity of the architecture +* internal consistency of terminology +* correctness of the runtime model +* alignment between spec, architecture, and implementation guidance +* ability to support real system implementation + +--- + +## What Not to Evaluate + +This repository is **not intended to be judged** on: + +* amount of production code +* completeness of a runnable system +* presence of a full framework or SDK +* performance optimizations + +The goal of this repo is **architectural correctness**, not implementation completeness. + +--- + +## Source of Truth + +👉 The `/spec` directory defines authoritative runtime behavior. + +* If any document appears inconsistent: + → the spec is correct +* Architecture documents define structure +* Implementation documents provide guidance + +--- + +## How to Read the Repository + +CrypSA is **layered**, not linear. + +Recommended entry path: + +1. `CrypSA_In_One_Diagram.md` +2. `CrypSA_In_5_Minutes.md` +3. `CrypSA_Terminology_Primer.md` +4. `CrypSA_Worked_Example.md` + +Then: + +* `architecture/` → system structure +* `spec/` → authoritative behavior +* `implementation/` → how to build + +--- + +## Core Concepts to Understand + +### Validator + +The validator is a **role**, not a location. + +* it may run locally or remotely +* it defines what becomes canonical + +👉 The validator defines what becomes canonical and therefore controls canonical truth. + +--- + +### Canonical Event History + +> Canonical event history is the source of truth + +* it is append-only +* all state is derived from it + +--- + +### Canonical Lifecycle + +> If accepted, an event becomes canonical and is appended to canonical event history + +This is the core rule of the system. + +--- + +### Replay + +Replay is a required mechanism. + +* derived canonical state is reconstructed via replay +* replay must be deterministic + +--- + +### Observers + +Observers: + +* simulate locally +* propose candidate events +* reconcile to canonical state + +They do **not define truth**. + +--- + +## Design Philosophy + +CrypSA separates: + +* **what must be true** (invariants) +* **how systems are built** (design space) + +This means: + +* invariants are strict +* implementation choices are flexible + +Flexibility is **intentional**, not a lack of definition. + +--- + +## Current Project State + +This repository is: + +* **architecturally complete** +* **spec-complete** +* **implementation-ready (with minimal validator as the first execution step)** + +The next step is: + +👉 building the minimal validator + +--- + +## Key Insight + +CrypSA does not synchronize state. + +> It synchronizes validated events. + +--- + +## One Sentence Summary + +CrypSA is an architecture model where a validator determines what becomes canonical, canonical event history is the source of truth, and derived canonical state is reconstructed via deterministic replay. diff --git a/architecture/CrypSA_Adapter_Model.md b/architecture/CrypSA_Adapter_Model.md index adeebbc..c47c611 100644 --- a/architecture/CrypSA_Adapter_Model.md +++ b/architecture/CrypSA_Adapter_Model.md @@ -6,24 +6,29 @@ This document defines the role of **adapters** in CrypSA. Adapters are responsible for **translation**. -They convert runtime data into forms usable by other layers without altering meaning, truth, or intent. +They reshape data into forms usable by other layers without affecting truth, meaning, or intent. --- -## 📜 Specification Authority +## 📜 Authority Level -The `/spec` directory is the **authoritative definition of runtime behavior**. +This document defines system structure and responsibilities. +It does not define runtime behavior. -Architecture documents explain the system. -The spec defines how it must behave. +CrypSA documentation is structured across layers: -If there is any conflict, **the spec takes precedence**. +* `/spec` — authoritative definition of runtime behavior +* `/architecture` — system structure and conceptual models + +If there is any conflict: + +* spec takes precedence over architecture --- ## Core Principle -Adapters **translate data without changing its meaning**. +Adapters translate data without affecting meaning. They do not: @@ -38,6 +43,10 @@ They exist to ensure: * data remains consistent * boundaries remain explicit +For formal responsibility boundaries, see: + +→ `CrypSA_Boundary_Definitions.md` + --- ## Adapters in the CrypSA Architecture @@ -57,10 +66,16 @@ They: * reshape it for other systems * do not influence truth or interpretation +For strict separation of these responsibilities, see: + +→ `CrypSA_Boundary_Definitions.md` + --- ## What Adapters Do +This is a conceptual model, not a strict execution definition. + Adapters perform **pure data transformation**. Typical responsibilities include: @@ -94,7 +109,7 @@ Adapters must never: * execute gameplay or domain logic * act as controllers or coordinators * interpret meaning (this is the role of lenses) -* assign canonical ordering or authority (e.g. canonical_sequence) +* assign canonical ordering or authority (e.g. `canonical_sequence`) If an adapter begins making decisions about meaning or rules, it is no longer an adapter. @@ -115,9 +130,8 @@ Adapters and lenses are distinct and must not overlap in responsibility. Adapters: -* reshape data -* preserve meaning -* do not interpret +* reshape data structure +* do not define or interpret meaning Lenses: @@ -132,6 +146,10 @@ Lenses: * Adapters do not decide meaning * Lenses do not modify canonical data +For formal boundary definitions between translation and interpretation, see: + +→ `CrypSA_Boundary_Definitions.md` + --- ### Example @@ -234,7 +252,6 @@ Adapters are the **translation layer** of CrypSA. They: * reshape data -* preserve meaning * enforce separation between systems They do not: @@ -247,4 +264,4 @@ They do not: ## One Sentence Summary -Adapters convert data between systems without changing its meaning, ensuring that truth, interpretation, and experience remain cleanly separated. +Adapters reshape data between systems without affecting truth or meaning, ensuring that truth, interpretation, and experience remain cleanly separated. diff --git a/architecture/CrypSA_Boundary_Definitions.md b/architecture/CrypSA_Boundary_Definitions.md new file mode 100644 index 0000000..2f10fb3 --- /dev/null +++ b/architecture/CrypSA_Boundary_Definitions.md @@ -0,0 +1,259 @@ +# CrypSA Boundary Definitions + +## Purpose + +This document defines the critical conceptual boundaries in CrypSA. + +These boundaries prevent: + +* responsibility overlap +* architectural drift +* ambiguity in system design + +They reinforce how different parts of the system relate to each other. + +For the authoritative conceptual flow of the system, see: + +→ CrypSA_Runtime_Model.md + +--- + +## 📜 Authority Level + +This document defines conceptual boundaries between system responsibilities. + +It does not define runtime behavior or validation rules. + +The CrypSA documentation is structured as: + +* `/spec` — authoritative definition of runtime behavior +* `/architecture` — system structure and conceptual models + +If there is any conflict: + +* spec takes precedence over architecture +* architecture takes precedence over this document + +--- + +# Core Boundaries + +--- + +## Adapter vs Lens + +### Adapter + +An **adapter**: + +* reshapes data +* bridges systems +* combines canonical and observer data +* prepares structured outputs + +An adapter does: + +* transform structure +* organize data for consumption + +An adapter does not: + +* define meaning +* interpret data +* modify canonical truth + +--- + +### Lens + +A **lens**: + +* interprets data +* defines meaning +* determines visibility and interaction relevance +* produces observer-specific views + +A lens does: + +* assign meaning to structured data +* shape observer experience + +A lens does not: + +* alter canonical structure +* define canonical truth +* perform validation + +--- + +### Boundary Summary + +> Adapters shape data. +> Lenses define meaning. + +--- + +## Observer vs Validator + +### Observer + +An **observer**: + +* performs local simulation +* produces prediction +* handles UI and experience +* proposes candidate events + +An observer: + +* is responsive and immediate +* may diverge temporarily from canonical truth + +An observer does not: + +* define truth +* modify canonical event history directly + +--- + +### Validator + +The **validator**: + +* evaluates candidate events +* enforces invariants +* determines acceptance or rejection +* appends accepted events to canonical event history +* assigns `canonical_sequence` + +The validator: + +* defines what becomes canonical +* operates as the authority of truth + +The validator does not: + +* simulate the world +* provide observer experience + +--- + +### Boundary Summary + +> Observers simulate. +> The validator defines what becomes canonical. + +--- + +## Canonical vs Local State + +### Canonical + +Canonical state is: + +* derived from canonical event history +* authoritative +* consistent across observers +* reconstructable via replay + +Canonical state: + +* is derived from canonical event history +* is not a source of truth +* exists as a computed result of canonical events + +--- + +### Local + +Local state is: + +* observer-specific +* predicted +* responsive +* potentially divergent + +Local state: + +* may temporarily differ from canonical outcomes +* must reconcile when canonical events are received + +--- + +### Boundary Summary + +> Canonical state is authoritative. +> Local state is predictive. + +--- + +## Invariant Boundary + +The **invariant boundary** separates: + +* local simulation +* canonical truth + +At this boundary: + +* candidate events are evaluated +* invariants are enforced +* acceptance determines canonical impact + +--- + +### Boundary Summary + +> The invariant boundary determines whether an action remains local or must be validated. + +--- + +## Validation vs Simulation + +### Simulation + +Simulation: + +* occurs locally in observers +* produces immediate results +* is not authoritative + +--- + +### Validation + +Validation: + +* occurs in the validator +* determines canonical truth +* enforces invariants and rules + +--- + +### Boundary Summary + +> Simulation proposes. +> Validation decides. + +--- + +# Why These Boundaries Matter + +These boundaries ensure: + +* clear separation of responsibilities +* predictable system behavior +* easier debugging and reasoning +* prevention of architectural drift + +They allow CrypSA to maintain: + +* local responsiveness +* shared canonical truth +* deterministic reconstruction + +--- + +# One Sentence Summary + +CrypSA enforces strict boundaries between data shaping, interpretation, simulation, and validation so that only validated events become canonical, while observers remain responsive and locally predictive. diff --git a/architecture/CrypSA_Infrastructure_Implications.md b/architecture/CrypSA_Infrastructure_Implications.md new file mode 100644 index 0000000..3b4a1e4 --- /dev/null +++ b/architecture/CrypSA_Infrastructure_Implications.md @@ -0,0 +1,258 @@ +# CrypSA Infrastructure Implications + +## Purpose + +This document describes how the CrypSA architecture changes the distribution of computation, state, and synchronization in a system. + +It focuses on **what changes compared to traditional architectures**, not on measured performance or cost outcomes. + +The goal is to provide a clear, neutral understanding of: + +* how responsibilities shift within the system +* what infrastructure patterns are no longer required +* what new considerations are introduced + +This document does not claim performance improvements. + +It outlines implications that may affect scalability, complexity, and infrastructure design. + +For the underlying runtime model, see: + +→ ../architecture/CrypSA_Runtime_Model.md + +For terminology definitions, see: + +→ ../architecture/CrypSA_Terminology_Primer.md + +--- + +## 📜 Authority Level + +This document describes architectural implications. + +It does not define runtime behavior. + +It does not define implementation details. + +If there is any conflict: + +* `/spec` defines behavior +* `/architecture` defines system structure +* this document describes consequences of that structure + +--- + +## Traditional System Model + +In a typical server-authoritative system: + +> In this document, “server” refers to a traditional authoritative runtime, not the CrypSA validator role. + +* the server runs a continuous authoritative simulation loop +* the server maintains mutable state +* clients send actions to the server +* the server resolves interactions +* the server synchronizes state to clients + +This requires: + +* continuous server-side computation +* state storage and mutation on the server +* frequent state synchronization across the network +* reconciliation logic on clients + +--- + +## CrypSA System Model + +In CrypSA: + +* observers perform local prediction +* actions become candidate events when crossing the invariant boundary +* the validator determines what becomes canonical +* accepted events are appended to canonical event history +* observers reconstruct state via replay + +This removes the requirement for: + +* continuous authoritative simulation loop +* server-owned mutable world state +* direct state synchronization between clients + +--- + +## Responsibility Shift + +CrypSA changes where key responsibilities live. + +### Simulation + +* Traditional → server (authoritative runtime) +* CrypSA → observer + +Observers perform local prediction for responsiveness. + +--- + +### State Representation + +* Traditional → server-managed mutable state +* CrypSA → derived from canonical event history + +State is reconstructed through deterministic replay. + +--- + +### Authority + +* Traditional → server runtime +* CrypSA → validator role + +The validator defines what becomes canonical. + +--- + +### Synchronization + +* Traditional → state replication +* CrypSA → canonical event distribution + +Observers receive events and derive state independently. + +--- + +## Infrastructure Implications + +These architectural changes lead to different infrastructure characteristics. + +### Reduced Continuous Server Computation + +Because local prediction occurs on observers: + +* the system does not require a continuously running authoritative simulation loop + +--- + +### Reduced State Synchronization Requirements + +Because state is derived from events: + +* large state payloads do not need to be transmitted +* synchronization is based on events rather than full state updates + +--- + +### Event-Based Network Traffic + +Network communication shifts from: + +* state updates → event distribution + +This may result in: + +* smaller payload sizes +* different bandwidth patterns +* reliance on ordered event delivery (`canonical_sequence`) + +--- + +### Simplified Backend State Model + +Because canonical truth is stored as event history: + +* backend systems can use append-only storage +* mutation-heavy state management is reduced + +--- + +### Replay-Dependent State + +Because state is derived: + +* replay becomes a core system requirement +* performance depends on replay efficiency and optimization strategies + +--- + +## New Considerations + +CrypSA introduces new areas that must be handled carefully. + +### Validator Scalability + +The validator must: + +* process candidate events +* enforce invariants +* maintain ordering + +Its performance characteristics become critical. + +--- + +### Event Throughput + +The system must handle: + +* event ingestion +* event ordering +* event distribution + +Throughput requirements depend on application design. + +--- + +### Replay Performance + +Replay must remain: + +* deterministic +* efficient +* scalable with event history size + +Optimization strategies may be required. + +--- + +### Event Storage and Persistence + +Canonical event history must be: + +* durable +* ordered +* queryable for replay + +Storage design becomes an important consideration. + +--- + +## What Must Be Proven + +The following areas require practical validation: + +* validator performance under load +* replay performance at scale +* event throughput limits +* comparison of event-based vs state-based bandwidth usage + +These are implementation concerns that determine real-world outcomes. + +--- + +## Summary + +CrypSA does not eliminate infrastructure requirements. + +It changes: + +* where computation occurs +* how state is represented +* how systems synchronize + +These changes may lead to different scaling characteristics and system designs. + +--- + +## One Sentence Summary + +CrypSA shifts local prediction to observers, replaces synchronized state with canonical event history, and uses validation to define truth, resulting in a fundamentally different distribution of infrastructure responsibilities. diff --git a/architecture/CrypSA_Invariant_Boundary.md b/architecture/CrypSA_Invariant_Boundary.md index 815113b..c90e6a9 100644 --- a/architecture/CrypSA_Invariant_Boundary.md +++ b/architecture/CrypSA_Invariant_Boundary.md @@ -12,13 +12,12 @@ This is the **only place where canonical truth may change**. --- -## 📜 Specification Authority +## 📜 Authority Level +This document defines system structure and responsibilities. +It does not define runtime behavior. The `/spec` directory is the **authoritative definition of runtime behavior**. -Architecture documents explain the system. -The spec defines how it must behave. - If there is any conflict, **the spec takes precedence**. --- @@ -35,6 +34,30 @@ All changes to canonical event history must pass through this boundary. --- +## Defines + +- The **invariant boundary** as the structural interface between observer-proposed events and validator authority +- The rules, inputs, outputs, and guarantees of boundary validation +- The authority constraint that only the validator may change canonical event history + +--- + +## Does Not Define + +- Authoritative runtime behavior (defined in `/spec`) +- Implementation strategies for the validator or boundary +- Observer-side simulation behavior beyond event proposal + +--- + +## Related Documents + +- `spec/CrypSA_Validation_Model.md` — authoritative runtime validation behavior +- `architecture/CrypSA_Observer_Model.md` — observer responsibilities and state model +- `architecture/CrypSA_Invariants_and_Design_Space.md` — CrypSA invariants and design space + +--- + ## Core Definition The **invariant boundary** is the control and validation interface between: diff --git a/architecture/CrypSA_Invariants_and_Design_Space.md b/architecture/CrypSA_Invariants_and_Design_Space.md index 1e0d9b2..bd2c2ca 100644 --- a/architecture/CrypSA_Invariants_and_Design_Space.md +++ b/architecture/CrypSA_Invariants_and_Design_Space.md @@ -4,19 +4,52 @@ This document defines: -- the **non-negotiable invariants** of CrypSA -- the **product-dependent design space** intentionally left open to implementers +* the **non-negotiable invariants** of CrypSA +* the **product-dependent design space** intentionally left open to implementers Its goal is to clarify that CrypSA is: -👉 a structured architecture model with fixed core truths +👉 a structured architecture model with fixed core truths 👉 not a single rigid system design --- +## Defines + +* CrypSA's non-negotiable invariants and the product-dependent design space +* Structured design axes for reasoning about implementation choices + +--- + +## Does Not Define + +* A single required implementation strategy +* Authoritative runtime behavior (defined in `/spec`) +* Observer-side or validator-side implementation details + +--- + +## 📜 Authority Level + +This document defines system structure and responsibilities. +It does not define runtime behavior. + +👉 The `/spec` directory is the authoritative source of behavior. + +--- + +## Related Documents + +* `spec/CrypSA_Validation_Model.md` — authoritative runtime validation behavior +* `architecture/CrypSA_Invariant_Boundary.md` — the invariant boundary +* `architecture/CrypSA_Observer_Model.md` — observer responsibilities +* `architecture/CrypSA_Validator_Responsibility_Model.md` — validator responsibilities + +--- + ## Core Principle -👉 CrypSA defines **what must be true**, +👉 CrypSA defines **what must be true** 👉 but does not prescribe **how every system must be built** --- @@ -25,10 +58,10 @@ Its goal is to clarify that CrypSA is: CrypSA is an architecture model that defines: -- how truth is established -- how events become canonical -- how state is derived -- how systems remain replayable and consistent +* how truth is established +* how events become canonical +* how state is derived +* how systems remain replayable and consistent --- @@ -36,10 +69,10 @@ CrypSA is an architecture model that defines: CrypSA is **not**: -- a fixed client-server architecture -- a required networking topology -- a single implementation pattern -- a one-size-fits-all runtime design +* a fixed client-server architecture +* a required networking topology +* a single implementation pattern +* a one-size-fits-all runtime design --- @@ -53,9 +86,9 @@ If these are not preserved, the system is no longer a CrypSA system. ## 1. The Validator Defines What Becomes Canonical -- All candidate events must be evaluated by a validator -- The validator defines what becomes canonical. -- If accepted, an event becomes canonical and is appended to canonical event history. +* All candidate events must be evaluated by a validator +* The validator defines what becomes canonical and enforces all system invariants +* If accepted, an event becomes canonical and is appended to canonical event history 👉 Observers do not define truth @@ -63,28 +96,29 @@ If these are not preserved, the system is no longer a CrypSA system. ## 2. Canonical Event History Is the Source of Truth -- Canonical event history is the authoritative record of the system -- It is append-only -- It defines the shared reality of the system +* Canonical event history is the authoritative record of the system +* It is append-only +* Canonical event history is the source of truth --- ## 3. Derived State Is Not Truth -- All state is derived from canonical event history -- Derived state is a projection -- Derived state may be reconstructed at any time +* All state is derived from canonical event history +* Derived canonical state is a projection +* Derived canonical state may be reconstructed at any time via replay of canonical event history -👉 State is not authoritative +👉 Derived canonical state is not authoritative --- -## 4. All Shared Reality Changes Cross the Invariant Boundary +## 4. All Changes That Affect Canonical Event History Cross the Invariant Boundary -- Any change that affects shared reality must: - - be represented as a candidate event - - pass through the invariant boundary - - If accepted, an event becomes canonical and is appended to canonical event history. +* Any change that affects canonical event history must: + + * be represented as a candidate event + * pass through the invariant boundary + * If accepted, an event becomes canonical and is appended to canonical event history --- @@ -92,9 +126,9 @@ If these are not preserved, the system is no longer a CrypSA system. Observers: -- may simulate locally -- may predict outcomes -- may propose candidate events +* may simulate locally +* may predict outcomes +* may propose candidate events But: @@ -102,11 +136,22 @@ But: --- -## 6. Replay Is a First-Class Capability +## 6. Replay Is a Required Capability -- Systems must be able to reconstruct derived state from canonical event history -- Replay is not optional -- Snapshots are optimizations, not truth +* Systems must be able to reconstruct derived canonical state from canonical event history via replay +* Replay is a required capability +* Snapshots are optimizations, not truth + +--- + +## 7. Replay Must Be Deterministic + +Given the same: + +* canonical event history +* interpretation logic + +replay must produce equivalent derived canonical state --- @@ -114,26 +159,28 @@ But: CrypSA intentionally leaves several areas **open to implementation choice**. -These are not undefined—they are **design axes** that must be decided based on product goals. +These are not undefined — they are **design axes** that must be decided based on product goals. --- ## Key Principle -👉 CrypSA defines that these concerns exist +👉 CrypSA defines that these concerns exist 👉 but does not define a single correct solution +👉 These are not optional concerns — they must be addressed, but the solutions are product-dependent + --- ## 1. Validator Deployment Options include: -- local validator (single-player / offline / fallback) -- remote validator (shared systems) -- hybrid models +* local validator (single-player / offline / fallback) +* remote validator (shared systems) +* hybrid models -CrypSA defines the role of the validator, not its location. +CrypSA defines the role of the validator, not its location --- @@ -141,13 +188,13 @@ CrypSA defines the role of the validator, not its location. Systems may choose: -- full replay-based reconciliation -- partial rollback -- state patching -- hybrid approaches +* full replay-based reconciliation +* partial rollback +* state patching +* hybrid approaches -CrypSA requires consistency with canonical history, -but does not enforce how reconciliation is implemented. +CrypSA requires consistency with canonical event history, +but does not enforce how reconciliation is implemented --- @@ -155,13 +202,13 @@ but does not enforce how reconciliation is implemented. Observers may: -- aggressively predict outcomes -- minimally predict -- avoid prediction entirely +* aggressively predict outcomes +* minimally predict +* avoid prediction entirely Tradeoff: -- responsiveness vs correction frequency +* responsiveness vs correction frequency --- @@ -169,12 +216,12 @@ Tradeoff: Observer-side systems may include: -- full local simulation -- partial simulation -- presentation-only layers +* full local simulation +* partial simulation +* presentation-only layers -CrypSA defines that observer simulation is non-authoritative, -but does not define its depth. +CrypSA defines that observer simulation is non-authoritative, +but does not define its depth --- @@ -182,15 +229,15 @@ but does not define its depth. Snapshots may vary in: -- frequency -- granularity -- storage model +* frequency +* granularity +* storage model Snapshots are: -- derived artifacts -- performance optimizations -- never authoritative +* derived artifacts +* performance optimizations +* never authoritative --- @@ -198,13 +245,13 @@ Snapshots are: Systems may choose: -- no partitioning -- spatial partitioning -- logical/domain partitioning -- hybrid models +* no partitioning +* spatial partitioning +* logical/domain partitioning +* hybrid models -CrypSA defines conflict scope, -but not how partitions are implemented. +CrypSA defines conflict scope, +but not how partitions are implemented --- @@ -212,11 +259,13 @@ but not how partitions are implemented. CrypSA is transport-agnostic, but requires: -- reliable delivery of canonical events -- correct ordering of canonical events -- replay-safe communication +* reliable delivery of canonical events +* correct ordering of canonical events +* replay-safe communication + +👉 ordering must be enforced via `canonical_sequence` -The transport implementation is product-dependent. +The transport implementation is product-dependent --- @@ -224,16 +273,16 @@ The transport implementation is product-dependent. Systems may choose: -- strict validation -- lightweight validation with monitoring -- trust-weighted systems -- hybrid approaches +* strict validation +* lightweight validation with monitoring +* trust-weighted systems +* hybrid approaches CrypSA enforces that: -👉 only accepted events become canonical +👉 If accepted, an event becomes canonical and is appended to canonical event history -but does not enforce a single validation strictness model. +but does not enforce a single validation strictness model --- @@ -245,43 +294,43 @@ These axes help implementers reason about choices. ## Validation Strictness -- strict validation ↔ permissive validation +* strict validation ↔ permissive validation --- ## Reconciliation -- heavy replay ↔ lightweight correction +* heavy replay ↔ lightweight correction --- ## Prediction -- aggressive prediction ↔ minimal prediction +* aggressive prediction ↔ minimal prediction --- ## State Reconstruction -- replay-heavy ↔ snapshot-heavy +* replay-heavy ↔ snapshot-heavy --- ## Deployment -- local-first ↔ remote-authority systems +* local-first ↔ remote-authority systems --- ## Partitioning -- fine-grained ↔ coarse-grained +* fine-grained ↔ coarse-grained --- ## Security -- high-trust ↔ zero-trust systems +* high-trust ↔ zero-trust systems --- @@ -289,9 +338,9 @@ These axes help implementers reason about choices. Implementers are responsible for: -- selecting appropriate strategies within this design space -- ensuring chosen strategies do not violate CrypSA invariants -- balancing performance, responsiveness, and correctness +* selecting appropriate strategies within this design space +* ensuring chosen strategies do not violate CrypSA invariants +* balancing performance, responsiveness, and correctness --- @@ -299,22 +348,22 @@ Implementers are responsible for: CrypSA provides: -- a **fixed model of truth** -- a **structured event-driven architecture** -- a **clear authority boundary** +* a **fixed model of truth** +* a **structured event-driven architecture** +* a **clear authority boundary** CrypSA does not provide: -- a single runtime design -- a fixed deployment model -- a universal implementation strategy +* a single runtime design +* a fixed deployment model +* a universal implementation strategy --- ## Final Statement -👉 CrypSA is a framework for structuring systems around canonical validation and replayable truth. +👉 CrypSA is a framework for structuring systems around canonical validation and replayable truth -👉 It defines invariants, not implementations. +👉 It defines invariants, not implementations -👉 Systems built with CrypSA are expected to make product-driven decisions within this structure. +👉 Systems built with CrypSA are expected to make product-driven decisions within this structure diff --git a/architecture/CrypSA_Lens_Model.md b/architecture/CrypSA_Lens_Model.md index 6a34aea..2da5f1e 100644 --- a/architecture/CrypSA_Lens_Model.md +++ b/architecture/CrypSA_Lens_Model.md @@ -6,18 +6,23 @@ This document defines the role of **lenses** in CrypSA. Lenses are responsible for **interpretation**. -They transform data derived from canonical event history into observer-specific experience without altering truth. +They transform data derived from canonical event history into observer-specific interpretation without altering truth. --- -## 📜 Specification Authority +## 📜 Authority Level -The `/spec` directory is the **authoritative definition of runtime behavior**. +This document defines system structure and responsibilities. +It does not define runtime behavior. -Architecture documents explain the system. -The spec defines how it must behave. +CrypSA documentation is structured across layers: -If there is any conflict, **the spec takes precedence**. +* `/spec` — authoritative definition of runtime behavior +* `/architecture` — system structure and conceptual models + +If there is any conflict: + +* spec takes precedence over architecture --- @@ -25,12 +30,16 @@ If there is any conflict, **the spec takes precedence**. In CrypSA: -> Canonical event history defines what is real -> Lenses define how that reality is interpreted +> Canonical event history defines what is real +> Lenses define how that reality is interpreted -Lenses do not create or modify canonical event history. +Lenses do not create or modify canonical event history. They interpret it. +For formal responsibility boundaries, see: + +→ `CrypSA_Boundary_Definitions.md` + --- ## Lenses in the CrypSA Architecture @@ -50,6 +59,10 @@ They: * produce observer-specific meaning and context * do not influence truth or validation +For strict separation of these responsibilities, see: + +→ `CrypSA_Boundary_Definitions.md` + --- ## Why Lenses Exist @@ -57,7 +70,7 @@ They: CrypSA separates: * **what happened** -* **how it is experienced** +* **how it is interpreted and experienced** This allows: @@ -72,6 +85,8 @@ Lenses make this separation explicit. ## What a Lens Is +This is a conceptual model, not a strict execution definition. + A lens is an interpretation layer that transforms input data into observer-usable meaning. It may: @@ -112,9 +127,8 @@ Lenses and adapters are distinct and must not overlap in responsibility. Adapters: -* reshape data -* preserve meaning -* do not interpret +* reshape data structure +* do not define or interpret meaning Lenses: @@ -126,8 +140,12 @@ Lenses: ### ⚠️ Hard Constraints -* Adapters do not decide meaning -* Lenses do not modify canonical data +* Adapters do not decide meaning +* Lenses do not modify canonical data + +For formal boundary definitions between translation and interpretation, see: + +→ `CrypSA_Boundary_Definitions.md` --- @@ -135,7 +153,7 @@ Lenses: Given canonical-derived data: -```json id="0n7b31" +```json { "health": 25 } ``` @@ -265,7 +283,7 @@ These categories may overlap. ## Minimal Lens Model (v0.1) -```text id="9m17ls" +``` Derived State + Observer Context → Interpreted View ``` diff --git a/architecture/CrypSA_Observer_Model.md b/architecture/CrypSA_Observer_Model.md index 0d1f8bc..40b0b1f 100644 --- a/architecture/CrypSA_Observer_Model.md +++ b/architecture/CrypSA_Observer_Model.md @@ -4,20 +4,52 @@ This document defines the role of the **observer** in a CrypSA system. +Observer behavior within the system is defined in the runtime model: + +→ CrypSA_Runtime_Model.md + Observers are responsible for reconstructing canonical reality from canonical event history, simulating the world locally, translating runtime data through adapters, interpreting that data through lenses, and presenting the result to the player. The validator validates events and maintains canonical event history. --- -## 📜 Specification Authority +## Defines + +- The observer's architectural role within a CrypSA system +- Observer responsibilities and capabilities +- The observer-side state model and its relationship to canonical truth + +--- + +## Does Not Define + +- Canonical truth or validation authority (owned by the validator) +- Authoritative runtime behavior (defined in `/spec`) +- A single required implementation pattern for observers + +--- + +## 📜 Authority Level + +This document defines system structure and responsibilities. +It does not define runtime behavior. The `/spec` directory is the **authoritative definition of runtime behavior**. -Architecture documents explain the system. -The spec defines how it must behave. +If there is any conflict: + +* spec takes precedence over architecture + +--- + +## Related Documents -If there is any conflict, **the spec takes precedence**. +- `spec/CrypSA_Validation_Model.md` — authoritative runtime validation behavior +- `architecture/CrypSA_Boundary_Definitions.md` — system responsibility boundaries +- `architecture/CrypSA_Invariants_and_Design_Space.md` — CrypSA invariants and design space +- `architecture/CrypSA_Adapter_Model.md` — adapter responsibilities +- `architecture/CrypSA_Lens_Model.md` — lens responsibilities --- @@ -38,6 +70,10 @@ Observers: Observers do not define truth. +For formal responsibility boundaries, see: + +→ `CrypSA_Boundary_Definitions.md` + --- ## Architectural Position @@ -57,10 +93,20 @@ Observers operate across: They do not operate in the truth layer. +For strict separation of these responsibilities, see: + +→ `CrypSA_Boundary_Definitions.md` + --- ## Observer-Side Flow +This flow operates within the runtime model described in: + +→ CrypSA_Runtime_Model.md + +This is a conceptual flow, not a strict execution order. + A CrypSA observer operates in the following sequence: 1. reconstruct derived canonical state from canonical event history @@ -116,11 +162,14 @@ Observers use adapters to shape runtime and canonical data into stable, consumab Adapters: -* reshape data -* preserve meaning +* reshape data structure * isolate internal structures -Adapters do not define truth or interpretation. +Adapters do not define meaning, truth, or interpretation. + +For strict responsibility boundaries between adapters and lenses, see: + +→ `CrypSA_Boundary_Definitions.md` --- @@ -132,6 +181,10 @@ Lenses assign meaning to translated data. Different observers may apply different lenses to the same canonical event history. +For strict responsibility boundaries between lenses and adapters, see: + +→ `CrypSA_Boundary_Definitions.md` + --- ### 5. Event Proposal @@ -142,6 +195,8 @@ These are sent to the validator for validation. They are not canonical until accepted. +If accepted, an event becomes canonical and is appended to canonical event history. + --- ### 6. Prediction and Responsiveness @@ -188,6 +243,8 @@ State reconstructed from canonical event history. * must remain consistent with canonical history * forms the authoritative local baseline +Derived canonical state is not a source of truth. + --- ### Predicted State diff --git a/architecture/CrypSA_Observer_Simulation_And_Security.md b/architecture/CrypSA_Observer_Simulation_And_Security.md index 4d1b307..2e15352 100644 --- a/architecture/CrypSA_Observer_Simulation_And_Security.md +++ b/architecture/CrypSA_Observer_Simulation_And_Security.md @@ -6,6 +6,10 @@ CrypSA allows observers significantly more simulation freedom than traditional m This is intentional. +Observer behavior and event flow within the system are defined in the runtime model: + +→ CrypSA_Runtime_Model.md + This document explains: * why CrypSA allows this @@ -15,7 +19,7 @@ This document explains: --- -## 📜 Specification Authority +## 📜 Authority Level The `/spec` directory is the **authoritative definition of runtime behavior**. @@ -71,6 +75,10 @@ Only validated events affect the shared world. ## The Invariant Boundary +The invariant boundary operates within the runtime model described in: + +→ CrypSA_Runtime_Model.md + The control point in CrypSA is the **invariant boundary**. > The invariant boundary is also the primary security boundary of the system. diff --git a/architecture/CrypSA_Runtime_Model.md b/architecture/CrypSA_Runtime_Model.md new file mode 100644 index 0000000..6383e68 --- /dev/null +++ b/architecture/CrypSA_Runtime_Model.md @@ -0,0 +1,230 @@ +# CrypSA Runtime Model + +## Purpose + +This document defines the end-to-end runtime behavior of CrypSA at a conceptual level. + +It explains how events move through the system and how canonical truth is established and observed. + +For authoritative behavior, refer to the `/spec` directory. + +For implications of this runtime model on infrastructure design, see: + +→ `CrypSA_Infrastructure_Implications.md` + +--- + +## Authority Level + +This document describes system structure and runtime flow. + +It does not define validation rules or exact behavior. + +If there is any conflict, the `/spec` takes precedence. + +--- + +## Core Principle + +👉 The validator defines what becomes canonical. +👉 Canonical event history is the source of truth. + +--- + +## Core Runtime Loop + +CrypSA operates through a continuous event-driven loop: + +1. An observer performs an action +2. The invariant boundary determines whether the action must cross into canonical event history + - If no, the result remains local + - If yes, a candidate event is created +3. The candidate event is submitted to the validator +4. The validator evaluates the candidate event against invariants to determine whether it becomes canonical + - If rejected, canonical event history does not change. Observers reconcile their local state with canonical event history +5. If accepted, an event becomes canonical and is appended to canonical event history +6. The canonical event is made available to observers + - events may be delayed or arrive out of order + - ordering is resolved using `canonical_sequence`, which defines authoritative event order +7. Observers apply canonical events via deterministic replay +8. Observers reconcile their local state with canonical event history, yielding to canonical outcomes where differences exist + +This loop repeats continuously as observers interact with the system. + +--- + +## Visual Representation + +```mermaid +flowchart LR + +A["Observer Action"] --> B["Invariant Boundary Check"] + +B -->|Remains Local| L["Local Result (No Canonical Change)"] + +B -->|Creates Candidate Event| C["Candidate Event"] + +C --> D["Submit to Validator"] + +D --> E["Validation and Invariant Evaluation"] + +E -->|Rejected| R["Reject → Observers Reconcile Local State with Canonical Event History"] + +E -->|Accepted| F["If accepted, an event becomes canonical and is appended to canonical event history"] + +F --> G["Make Canonical Event Available to Observers"] + +G --> H["Apply Canonical Events via Deterministic Replay"] + +H --> I["Observer Reconciliation"] + +I --> A +``` + +--- + +## Key Properties + +### Observers Do Not Define Truth + +Observers may perform local prediction, but they do not determine canonical outcomes. + +--- + +### Canonical Event History Is the Source of Truth + +All authoritative state is derived from canonical event history. + +There is no separate source of truth. + +--- + +### No Direct State Authority + +No system component maintains authoritative state outside of canonical event history. + +--- + +### State Is Derived, Not Stored as Truth + +System state is reconstructed from canonical event history through replay. + +Any stored state is a derived representation. + +--- + +### Replay Is Fundamental + +Replay is not a recovery feature. + +Replay is the mechanism by which canonical event history becomes observable system state. + +--- + +### Local Prediction May Diverge + +Observers may temporarily diverge from canonical truth due to local prediction, but must reconcile upon receiving canonical events. + +--- + +### Convergence Occurs Through Canonical Events + +Observers converge toward canonical truth as canonical events are received and applied. + +--- + +## Canonical Authority Constraint + +Canonical event history can only be extended through events accepted by the validator. + +No other mechanism can modify canonical truth. + +--- + +## Validator Role in the Runtime + +The validator is responsible for: + +1. Receiving candidate events +2. Evaluating events against invariants +3. Determining acceptance or rejection +4. Assigning `canonical_sequence` (establishing authoritative ordering) +5. Appending accepted events to canonical event history +6. Making canonical events available to observers + +The validator defines what becomes canonical. + +--- + +## Observer Role in the Runtime + +Observers are responsible for: + +* Local prediction and experience +* Generating candidate events (when crossing the invariant boundary) +* Maintaining predicted state +* Receiving canonical events +* Reconciling local state with canonical event history + +Observers do not define truth. + +--- + +## Relationship to Replay + +Replay is the process of applying canonical event history to derive state. + +This means: + +* state is not authoritative +* canonical event history is authoritative +* replay ensures deterministic reconstruction of state + +Snapshots and optimizations may be used, but they do not replace canonical history. + +--- + +## Relationship to Consistency + +CrypSA does not rely on direct state synchronization. + +Consistency emerges through: + +* shared canonical event history +* deterministic replay +* observer reconciliation + +--- + +## Relationship to Deployment + +The runtime model is independent of deployment. + +The validator may run: + +* locally +* remotely +* in a hybrid configuration + +This does not change the runtime model. + +--- + +## Summary + +CrypSA is a system where: + +* observers perform local prediction +* the invariant boundary determines what becomes a candidate event +* candidate events are validated by a validator +* accepted events are appended to canonical event history +* canonical event history is replayed to deterministically produce state + +👉 Truth is not synchronized. +👉 Truth is established through validated events and observed through deterministic replay. + +--- + +## Additional Clarification + +Canonical events define the only authoritative sequence of system changes. diff --git a/architecture/CrypSA_State_Model.md b/architecture/CrypSA_State_Model.md index 03b1e00..4af672e 100644 --- a/architecture/CrypSA_State_Model.md +++ b/architecture/CrypSA_State_Model.md @@ -13,7 +13,7 @@ Understanding these distinctions is critical to implementing CrypSA correctly. --- -## 📜 Specification Authority +## 📜 Authority Level The `/spec` directory is the **authoritative definition of runtime behavior**. diff --git a/architecture/CrypSA_Validator_Deployment_Model.md b/architecture/CrypSA_Validator_Deployment_Model.md index 351fc56..1d8abfb 100644 --- a/architecture/CrypSA_Validator_Deployment_Model.md +++ b/architecture/CrypSA_Validator_Deployment_Model.md @@ -4,13 +4,17 @@ This document defines how the **validator role** in CrypSA can be deployed. +Validator behavior within the system is defined in the runtime model: + +→ CrypSA_Runtime_Model.md + CrypSA treats validation as an **architectural responsibility**, not a fixed machine location. This allows the same system model to operate across different deployment styles without changing how canonical truth is defined. --- -## 📜 Specification Authority +## 📜 Authority Level The `/spec` directory is the **authoritative definition of runtime behavior**. diff --git a/architecture/CrypSA_Validator_Responsibility_Model.md b/architecture/CrypSA_Validator_Responsibility_Model.md index e3cfb73..4c46e9e 100644 --- a/architecture/CrypSA_Validator_Responsibility_Model.md +++ b/architecture/CrypSA_Validator_Responsibility_Model.md @@ -4,18 +4,27 @@ This document defines the role of the **validator** in a CrypSA system. +Validator behavior within the system is defined in the runtime model: + +→ CrypSA_Runtime_Model.md + The validator is responsible for protecting the integrity of **canonical event history** by validating events, enforcing invariants, and maintaining that history. --- -## 📜 Specification Authority +## 📜 Authority Level + +This document defines system structure and responsibilities. +It does not define runtime behavior. + +CrypSA documentation is structured across layers: -The `/spec` directory is the **authoritative definition of runtime behavior**. +* `/spec` — authoritative definition of runtime behavior +* `/architecture` — system structure and conceptual models -Architecture documents explain the system. -The spec defines how it must behave. +If there is any conflict: -If there is any conflict, **the spec takes precedence**. +* spec takes precedence over architecture --- @@ -23,21 +32,25 @@ If there is any conflict, **the spec takes precedence**. In CrypSA: -> The validator does not simulate the world. +> The validator does not simulate the world. > The validator defines what becomes canonical. Canonical event history is the source of truth. The validator acts as: -* an event validator -* an invariant enforcer -* a canonical event recorder -* an assigner of canonical ordering (`canonical_sequence`), where accepted events become canonical and are appended to canonical event history +* an event validator +* an invariant enforcer +* a canonical event recorder +* an assigner of canonical ordering (`canonical_sequence`), where if accepted, an event becomes canonical and is appended to canonical event history -Observers simulate the world locally. +Observers simulate the world locally. The validator ensures all accepted events are valid. +For formal responsibility boundaries, see: + +→ `CrypSA_Boundary_Definitions.md` + --- ## Validator as a Role @@ -46,8 +59,8 @@ In CrypSA, the validator is a **logical role**, not a specific machine. It may run: -* **locally**, alongside an observer -* **remotely**, as a separate system +* **locally**, alongside an observer +* **remotely**, as a separate system The responsibilities of the validator do not change based on where it runs. @@ -67,36 +80,46 @@ Not all validators are servers, but all servers host a validator. CrypSA separates responsibilities into: -* **Truth** → canonical events and validation -* **Translation** → adapters -* **Interpretation** → lenses -* **Experience** → UI and local simulation +* **Truth** → canonical events and validation +* **Translation** → adapters +* **Interpretation** → lenses +* **Experience** → UI and local simulation The validator operates strictly in the **truth layer**. It does not: -* simulate gameplay -* interpret meaning -* manage presentation +* simulate gameplay +* interpret meaning +* manage presentation + +For strict separation of these responsibilities, see: + +→ `CrypSA_Boundary_Definitions.md` --- ## The Validator Model +This is a conceptual model, not a strict execution definition. + CrypSA replaces centralized simulation with **canonical event validation**. Instead of computing the entire world, the validator: -1. receives candidate events -2. validates them -3. accepts or rejects them -4. accepted events become canonical and are appended to canonical event history +1. receives candidate events +2. validates them +3. accepts or rejects them +4. if accepted, an event becomes canonical and is appended to canonical event history This defines the minimal validator loop. All candidate events cross the invariant boundary, where they become canonical or are rejected. +The invariant boundary is defined in: + +→ `CrypSA_Boundary_Definitions.md` + > The invariant boundary is the only point at which canonical event history may change. --- @@ -109,10 +132,10 @@ The validator receives **candidate events** from observers. Examples: -* crafting -* upgrading -* transferring -* building +* crafting +* upgrading +* transferring +* building Each event represents **intent**, not truth. @@ -122,36 +145,36 @@ Each event represents **intent**, not truth. The validator validates events against: -* object existence -* ownership rules -* invariant constraints -* rule compliance -* resource requirements +* object existence +* ownership rules +* invariant constraints +* rule compliance +* resource requirements Invariants define what must always be true. If an event violates invariants: -→ it is rejected -→ it never becomes canonical +→ it is rejected +→ it never becomes canonical --- ### 3. Canonical Event Recording -Accepted events become canonical and are appended to canonical event history. +If accepted, an event becomes canonical and is appended to canonical event history. This includes: -* assignment of canonical ordering (`canonical_sequence`) -* recording of the canonical event +* assignment of canonical ordering (`canonical_sequence`) +* recording of the canonical event This history defines: -* object creation -* state changes -* ownership changes -* world evolution +* object creation +* state changes +* ownership changes +* world evolution Canonical event history is the source of truth. @@ -161,11 +184,11 @@ Canonical event history is the source of truth. The validator’s persistent data consists of: -* object identities -* genome definitions -* canonical event history -* invariant-relevant state -* optional snapshots +* object identities +* genome definitions +* canonical event history +* invariant-relevant state +* optional snapshots The system is **event-first**, not state-first. @@ -177,14 +200,18 @@ Derived canonical state is reconstructed via replay. ## Minimal Runtime Flow (v0.1) +This flow operates within the runtime model described in: + +→ CrypSA_Runtime_Model.md + The minimal validator loop is: -1. receive candidate event -2. parse into a candidate event structure -3. validate against canonical context -4. accept or reject -5. append event if accepted -6. make canonical events available to observers +1. receive candidate event +2. parse into a candidate event structure +3. validate against canonical context +4. accept or reject +5. append event if accepted +6. make canonical events available to observers This is sufficient to maintain shared reality. @@ -194,13 +221,17 @@ This is sufficient to maintain shared reality. The validator does not need to: -* simulate the full world -* run physics or AI continuously -* maintain large mutable world-state models -* render or predict gameplay +* simulate the full world +* run physics or AI continuously +* maintain large mutable world-state models +* render or predict gameplay Observers handle simulation and experience. +For boundaries between simulation, validation, and interpretation, see: + +→ `CrypSA_Boundary_Definitions.md` + --- ## Optional Supporting Systems @@ -209,24 +240,24 @@ Production systems may include: ### Auditing -* anomaly detection -* suspicious behavior tracking +* anomaly detection +* suspicious behavior tracking ### Security -* exploit detection -* rate limiting +* exploit detection +* rate limiting ### Performance -* snapshots -* caching -* indexing +* snapshots +* caching +* indexing ### Analytics -* telemetry -* behavior analysis +* telemetry +* behavior analysis These are optional and do not define the core model. @@ -236,12 +267,12 @@ These are optional and do not define the core model. At minimum, a CrypSA validator must: -1. receive candidate events -2. validate them -3. enforce invariants -4. accept or reject -5. record canonical event history -6. make canonical events available to observers +1. receive candidate events +2. validate them +3. enforce invariants +4. accept or reject +5. record canonical event history +6. make canonical events available to observers --- @@ -268,20 +299,20 @@ The validator’s behavior is independent of deployment. Whether the validator runs: -* locally (within an observer environment) -* remotely (as a dedicated server) +* locally (within an observer environment) +* remotely (as a dedicated server) The following remain unchanged: -* validation rules -* invariant enforcement -* canonical event structure and meaning -* definition of truth +* validation rules +* invariant enforcement +* canonical event structure and meaning +* definition of truth What changes is: -* where validation executes -* how observers communicate with the validator +* where validation executes +* how observers communicate with the validator --- @@ -291,9 +322,9 @@ The CrypSA validator is the **guardian of canonical event history**. It: -* validates events -* enforces invariants -* records canonical events +* validates events +* enforces invariants +* records canonical events Observers simulate and interpret the world locally. diff --git a/architecture/README.md b/architecture/README.md index 345becb..9d601cd 100644 --- a/architecture/README.md +++ b/architecture/README.md @@ -10,16 +10,25 @@ This folder is part of the **authoritative architecture layer**. Other documents must not redefine the concepts described here. +For the authoritative conceptual flow of the system, see: + +→ CrypSA_Runtime_Model.md + --- -## 📜 Specification Authority +## 📜 Authority Level + +The CrypSA documentation is structured as: -The `/spec` directory is the **authoritative definition of runtime behavior**. +* `/spec` — authoritative definition of runtime behavior +* `/architecture` — system structure and conceptual models -Architecture documents explain the system. -The spec defines how it must behave. +The runtime model (`CrypSA_Runtime_Model.md`) defines the authoritative conceptual flow of the system. -If there is any conflict, **the spec takes precedence**. +If there is any conflict: + +* spec takes precedence over architecture +* architecture takes precedence over all other documents in this repository --- @@ -43,7 +52,7 @@ At a system level, everything follows this flow: 1. Observer simulates locally 2. Observer proposes a **candidate event** 3. Validator evaluates the event -4. Accepted events become canonical and are appended to canonical event history +4. If accepted, an event becomes canonical and is appended to canonical event history 5. Observers reconcile to canonical truth This defines the boundary between: @@ -64,6 +73,10 @@ CrypSA is organized into four responsibilities: These responsibilities define the architecture. +For strict separation of these responsibilities, see: + +→ CrypSA_Boundary_Definitions.md + --- ## Key Architectural Ideas @@ -172,14 +185,14 @@ It is: ## Layer Relationship (Simplified) -```mermaid id="z8y4tq" +```mermaid flowchart LR -A[Canonical Event History] --> B[Derived Canonical State] -B --> C[Adapters] -C --> D[Lenses] -D --> E[UI / Experience] -``` +A["Canonical Event History"] --> B["Derived Canonical State"] +B --> C["Adapters"] +C --> D["Lenses"] +D --> E["UI / Experience"] +```` --- @@ -202,6 +215,8 @@ This document defines **structure and relationships**. For other aspects: * Runtime behavior → `/spec/` +* Conceptual flow → `CrypSA_Runtime_Model.md` +* Responsibility boundaries → `CrypSA_Boundary_Definitions.md` * Concepts and definitions → Terminology Primer * End-to-end flow → Worked Example @@ -209,7 +224,9 @@ For other aspects: ## Where to Go Next +* `CrypSA_Runtime_Model.md` — authoritative conceptual flow * `CrypSA_Architecture_Overview.md` — system overview +* `CrypSA_Boundary_Definitions.md` — responsibility boundaries * `../spec/CrypSA_Event_Model.md` — event structure * `../spec/CrypSA_Validation_Model.md` — invariant enforcement * `../spec/CrypSA_Replay_Model.md` — state reconstruction diff --git a/diagrams/CrypSA_Adapter_Lens_Runtime_Relationship.md b/diagrams/CrypSA_Adapter_Lens_Runtime_Relationship.md index 9214793..1915328 100644 --- a/diagrams/CrypSA_Adapter_Lens_Runtime_Relationship.md +++ b/diagrams/CrypSA_Adapter_Lens_Runtime_Relationship.md @@ -11,10 +11,19 @@ This diagram shows how CrypSA separates: It also clarifies how canonical truth is established before it flows into the rest of the system. +For the authoritative conceptual flow of the system, see: + +→ ../architecture/CrypSA_Runtime_Model.md + --- ## System Relationship Diagram +> This diagram illustrates the relationship between system layers within the runtime model. +> It does not define runtime behavior or event flow. +> For the authoritative conceptual flow, see: +> → ../architecture/CrypSA_Runtime_Model.md + ```mermaid flowchart LR @@ -46,7 +55,7 @@ B --> D C --> D D --> E E --> F -``` +```` --- diff --git a/diagrams/CrypSA_Conflict_Resolution.md b/diagrams/CrypSA_Conflict_Resolution.md index 8dc139e..c10f23a 100644 --- a/diagrams/CrypSA_Conflict_Resolution.md +++ b/diagrams/CrypSA_Conflict_Resolution.md @@ -15,10 +15,19 @@ In CrypSA v0.1: > the first valid event within the conflict scope is accepted +For the authoritative conceptual flow of the system, see: + +→ ../architecture/CrypSA_Runtime_Model.md + --- ## Diagram +> This diagram illustrates conflict resolution within the CrypSA runtime model. +> It does not define runtime behavior or event flow. +> For the authoritative conceptual flow, see: +> → ../architecture/CrypSA_Runtime_Model.md + ```mermaid flowchart TD @@ -40,7 +49,7 @@ J --> K[Observers reconcile] R1 --> L[Return rejection result] L --> K -``` +```` --- diff --git a/diagrams/CrypSA_Control_Flow_Diagram.md b/diagrams/CrypSA_Control_Flow_Diagram.md index 26d4b3d..e178225 100644 --- a/diagrams/CrypSA_Control_Flow_Diagram.md +++ b/diagrams/CrypSA_Control_Flow_Diagram.md @@ -11,8 +11,17 @@ The system continuously decides: * should the validator evaluate it? * should observers reconstruct? +For the authoritative conceptual flow of the system, see: + +→ ../architecture/CrypSA_Runtime_Model.md + --- +> This document illustrates control flow within the CrypSA runtime model. +> It does not define runtime behavior. +> For the authoritative conceptual flow, see: +> → ../architecture/CrypSA_Runtime_Model.md + ## High-Level Control Flow ```text @@ -37,7 +46,7 @@ Invariant Boundary Check Append to Canonical Event History ↓ Observers reconstruct derived canonical state -``` +```` --- diff --git a/diagrams/CrypSA_Event_Flow.md b/diagrams/CrypSA_Event_Flow.md index 5d60cbe..71faf58 100644 --- a/diagrams/CrypSA_Event_Flow.md +++ b/diagrams/CrypSA_Event_Flow.md @@ -8,11 +8,20 @@ It represents the runtime loop: > local simulation → validation → canonical event history → observer reconciliation +For the authoritative conceptual flow of the system, see: + +→ ../architecture/CrypSA_Runtime_Model.md + --- ## Diagram -```mermaid id="r7p2m1" +> This diagram illustrates event flow within the CrypSA runtime model. +> It does not define runtime behavior. +> For the authoritative conceptual flow, see: +> → ../architecture/CrypSA_Runtime_Model.md + +```mermaid flowchart LR A[Observer Action] --> B[Local Simulation] @@ -28,7 +37,7 @@ F --> H[Observers receive canonical events] H --> J[Observer Reconciliation] G --> J J --> K[Derived Canonical State Updated] -``` +```` --- diff --git a/diagrams/CrypSA_In_One_Diagram.md b/diagrams/CrypSA_In_One_Diagram.md index e299c86..da2a066 100644 --- a/diagrams/CrypSA_In_One_Diagram.md +++ b/diagrams/CrypSA_In_One_Diagram.md @@ -17,11 +17,20 @@ into a single lifecycle model. This is an **illustrative system view**, not an authoritative specification. +For the authoritative conceptual flow of the system, see: + +→ ../architecture/CrypSA_Runtime_Model.md + --- ## Diagram -```mermaid id="7k1mzp" +> This diagram illustrates the CrypSA runtime model. +> It does not define runtime behavior. +> For the authoritative conceptual flow, see: +> → ../architecture/CrypSA_Runtime_Model.md + +```mermaid flowchart LR subgraph Observer @@ -67,7 +76,7 @@ H --> I I --> J J --> K K --> A -``` +```` --- @@ -212,7 +221,7 @@ They: ## Full Lifecycle Summary -```text id="lifecycle_summary" +```text Reconstruct → Simulate → Act → Check Boundary → Validate → Append to Canonical Event History → Distribute → Replay → Reconcile → Repeat ``` diff --git a/diagrams/CrypSA_Local_vs_Remote_Validator.md b/diagrams/CrypSA_Local_vs_Remote_Validator.md index bcdce8a..e7dd696 100644 --- a/diagrams/CrypSA_Local_vs_Remote_Validator.md +++ b/diagrams/CrypSA_Local_vs_Remote_Validator.md @@ -15,6 +15,10 @@ CrypSA can operate with validation running: This is a deployment distinction, not a change to the truth model. +For the authoritative conceptual flow of the system, see: + +→ ../architecture/CrypSA_Runtime_Model.md + --- ## Core Principle @@ -38,6 +42,11 @@ What does **not** change is: ## Diagram +> This diagram illustrates deployment configurations within the CrypSA runtime model. +> It does not define runtime behavior or event flow. +> For the authoritative conceptual flow, see: +> → ../architecture/CrypSA_Runtime_Model.md + ```mermaid flowchart TB @@ -58,7 +67,7 @@ subgraph Case_B["Case B - Remote Validator"] B2 --> B3 B3 --> B4 end -``` +```` --- diff --git a/diagrams/CrypSA_Observer_vs_Canonical.md b/diagrams/CrypSA_Observer_vs_Canonical.md index 51405ed..c396c1b 100644 --- a/diagrams/CrypSA_Observer_vs_Canonical.md +++ b/diagrams/CrypSA_Observer_vs_Canonical.md @@ -13,10 +13,19 @@ It explains how CrypSA separates: > from > what is real +For the authoritative conceptual flow of the system, see: + +→ ../architecture/CrypSA_Runtime_Model.md + --- ## Diagram +> This diagram illustrates the relationship between observer state and canonical state within the CrypSA runtime model. +> It does not define runtime behavior or event flow. +> For the authoritative conceptual flow, see: +> → ../architecture/CrypSA_Runtime_Model.md + ```mermaid flowchart LR @@ -41,7 +50,7 @@ D -->|Rejected| A E --> F F --> A -``` +```` --- diff --git a/diagrams/CrypSA_Snapshot_And_Replay.md b/diagrams/CrypSA_Snapshot_And_Replay.md index a68e152..ff75b6e 100644 --- a/diagrams/CrypSA_Snapshot_And_Replay.md +++ b/diagrams/CrypSA_Snapshot_And_Replay.md @@ -9,11 +9,20 @@ This diagram shows how CrypSA reconstructs current derived canonical state using It illustrates how CrypSA avoids replaying from genesis while keeping canonical event history as the source of truth. +For the authoritative conceptual flow of the system, see: + +→ ../architecture/CrypSA_Runtime_Model.md + --- ## Diagram -```mermaid id="snapshot_replay" +> This diagram illustrates snapshot and replay within the CrypSA runtime model. +> It does not define runtime behavior or event flow. +> For the authoritative conceptual flow, see: +> → ../architecture/CrypSA_Runtime_Model.md + +```mermaid flowchart LR A[Canonical Event History] --> B[Create Snapshot at canonical_sequence N] @@ -30,7 +39,7 @@ F -->|Base State| H[Reconstructed Derived Canonical State] G -->|Apply Events| H H --> I[Observer Continues Local Simulation] -``` +```` --- diff --git a/diagrams/CrypSA_State_Transition_Diagram.md b/diagrams/CrypSA_State_Transition_Diagram.md index 7b79692..abaa746 100644 --- a/diagrams/CrypSA_State_Transition_Diagram.md +++ b/diagrams/CrypSA_State_Transition_Diagram.md @@ -8,10 +8,19 @@ The universe does not evolve through continuous simulation, but through: > validated canonical events that transition the universe between stable states +For the authoritative conceptual flow of the system, see: + +→ ../architecture/CrypSA_Runtime_Model.md + --- ## Diagram +> This diagram illustrates state transitions within the CrypSA runtime model. +> It does not define runtime behavior or event flow. +> For the authoritative conceptual flow, see: +> → ../architecture/CrypSA_Runtime_Model.md + ```mermaid flowchart TD @@ -41,7 +50,7 @@ E --> O O --> S1 S1 --> A -``` +```` --- diff --git a/diagrams/CrypSA_System_Stack_Diagram.md b/diagrams/CrypSA_System_Stack_Diagram.md index f6506a3..315e8ed 100644 --- a/diagrams/CrypSA_System_Stack_Diagram.md +++ b/diagrams/CrypSA_System_Stack_Diagram.md @@ -13,11 +13,20 @@ It shows how CrypSA separates: This separation allows observers to simulate locally while canonical event history remains consistent. +For the authoritative conceptual flow of the system, see: + +→ ../architecture/CrypSA_Runtime_Model.md + --- ## Diagram -```mermaid id="system_stack" +> This diagram illustrates the layered structure within the CrypSA runtime model. +> It does not define runtime behavior or event flow. +> For the authoritative conceptual flow, see: +> → ../architecture/CrypSA_Runtime_Model.md + +```mermaid flowchart TB subgraph "Experience Layer" @@ -53,7 +62,7 @@ V --> F F --> G G --> H H --> D -``` +```` --- diff --git a/diagrams/CrypSA_Ten_Diagrams.md b/diagrams/CrypSA_Ten_Diagrams.md index 93edcc0..97bda0e 100644 --- a/diagrams/CrypSA_Ten_Diagrams.md +++ b/diagrams/CrypSA_Ten_Diagrams.md @@ -8,8 +8,16 @@ Each diagram highlights a key idea. Together, they provide a high-level understanding of how CrypSA works as a system for persistent digital universes. +For the authoritative conceptual flow and system behavior, see: + +→ ../architecture/CrypSA_Runtime_Model.md + +This document is a simplified conceptual walkthrough built on top of that model. + This document is **illustrative**, not authoritative. +It simplifies and visualizes concepts defined in the runtime model and specification. + --- ## Diagram 1 — Traditional Multiplayer @@ -18,7 +26,7 @@ Most online games use a server-authoritative model: ```text Clients → Server → Database -``` +```` The server: diff --git a/diagrams/CrypSA_Validation_Pipeline.md b/diagrams/CrypSA_Validation_Pipeline.md index 0c67666..55d4819 100644 --- a/diagrams/CrypSA_Validation_Pipeline.md +++ b/diagrams/CrypSA_Validation_Pipeline.md @@ -9,10 +9,19 @@ It represents the layered validation model used to determine whether an event is * accepted * rejected +For the authoritative conceptual flow of how validation fits into the system, see: + +→ ../architecture/CrypSA_Runtime_Model.md + --- ## Diagram +> This diagram illustrates the validation pipeline within the CrypSA runtime model. +> It does not define validation rules beyond those specified in the specification. +> For authoritative validation behavior, refer to: +> → spec/CrypSA_Validation_Model.md + ```mermaid flowchart TD @@ -35,7 +44,7 @@ F -->|Pass| G["Accept and Assign canonical_sequence"] G --> H["Append to Canonical Event History"] H --> I["Canonical Events Available to Observers"] -``` +```` --- diff --git a/diagrams/README.md b/diagrams/README.md index dc92ddf..3e2b76c 100644 --- a/diagrams/README.md +++ b/diagrams/README.md @@ -12,14 +12,23 @@ Diagrams are used to: --- -## 📜 Specification Authority +## 📜 Authority Level -The `/spec` directory is the **authoritative definition of runtime behavior**. +This folder contains visual representations only. +It does not define runtime behavior or system structure. -Architecture documents explain the system. -The spec defines how it must behave. +CrypSA documentation is structured across three layers: -If there is any conflict, **the spec takes precedence**. +* `/spec` — **authoritative definition of runtime behavior** +* `/architecture` — **system structure and conceptual models** +* `/diagrams` — **visual representations of those models** + +The runtime model (`architecture/CrypSA_Runtime_Model.md`) describes the conceptual flow of the system. + +If there is any conflict: + +* spec takes precedence over architecture +* architecture takes precedence over diagrams --- @@ -32,6 +41,7 @@ They: * do not define authoritative behavior * do not introduce new rules * do not override architecture or specification +* must align with architecture and the runtime model For authoritative definitions, refer to: @@ -42,7 +52,11 @@ For authoritative definitions, refer to: ## 📍 Diagram Context -Diagrams are visual aids and must support specific documents. +Diagrams are visual aids and must support specific documents without redefining them. + +For formal responsibility boundaries, see: + +→ `../architecture/CrypSA_Boundary_Definitions.md` --- @@ -50,8 +64,9 @@ Diagrams are visual aids and must support specific documents. Most diagrams support: -* `../CrypSA_Worked_Example.md` — step-by-step system flow -* `../CrypSA_Architecture_Overview.md` — system structure +* `../architecture/CrypSA_Runtime_Model.md` — conceptual flow +* `../architecture/CrypSA_Worked_Example.md` — step-by-step system walkthrough +* `../architecture/CrypSA_Architecture_Overview.md` — system structure --- @@ -77,11 +92,12 @@ All diagrams must align with the core CrypSA architecture: And must reflect these core principles: -* **validation determines canonical truth** -* **canonical event history is the source of truth** -* **the validator is the authority over canonical events** -* **the invariant boundary defines where candidate events are evaluated before becoming canonical** -* **derived canonical state is not a source of truth and must be shown as reconstructed from canonical event history** +* the validator defines what becomes canonical +* canonical event history is the source of truth +* If accepted, an event becomes canonical and is appended to canonical event history +* the invariant boundary defines where candidate events are evaluated before becoming canonical +* derived canonical state is reconstructed via replay of canonical event history +* derived canonical state is not a source of truth Diagrams must not introduce alternative models or terminology. @@ -93,7 +109,7 @@ Diagrams must use consistent CrypSA terminology: * use **validator**, not “server”, unless explicitly describing deployment * “server” must never be used as a synonym for authority -* use **candidate event**, not generic “action” when crossing the invariant boundary +* use **candidate event** for events crossing the invariant boundary, not generic “action” * use **canonical event history**, not “state” as a source of truth * use **canonical_sequence** for ordering, not server_sequence or other alternatives @@ -103,6 +119,18 @@ If “server” is used, it must be clear that: --- +## Terminology Source + +All terminology used in diagrams must align with: + +→ `../architecture/CrypSA_Terminology_Primer.md` + +Terms must not be redefined within diagrams. + +If clarification is needed, refer to the Terminology Primer rather than introducing new definitions. + +--- + ## Scope Diagrams may: @@ -151,4 +179,4 @@ Diagrams should reflect the architecture and spec, not reinterpret them. ## One Sentence Summary -Diagrams visualize CrypSA concepts to aid understanding, but authoritative definitions and behavior are defined only in the architecture and spec layers, where validation defines what becomes canonical truth and canonical event history is the sole source of that truth. +Diagrams visualize CrypSA concepts to aid understanding, but authoritative definitions and behavior are defined in the architecture and spec, where the validator defines what becomes canonical and canonical event history is the source of truth. diff --git a/exploratory/CrypSA_Offline_Mode_Simple.md b/exploratory/CrypSA_Offline_Mode_Simple.md index 6d2934e..eef823a 100644 --- a/exploratory/CrypSA_Offline_Mode_Simple.md +++ b/exploratory/CrypSA_Offline_Mode_Simple.md @@ -1,5 +1,12 @@ # CrypSA Offline Mode — Simple +--- + +“Terminology in this document may not match current CrypSA definitions. +Refer to the Terminology Primer for authoritative meaning.” + +--- + ## Purpose This document describes a simple offline mode model for CrypSA systems. diff --git a/exploratory/README.md b/exploratory/README.md index 09ef3a6..574bada 100644 --- a/exploratory/README.md +++ b/exploratory/README.md @@ -1,5 +1,12 @@ # CrypSA Exploratory +--- + +“Terminology in this document may not match current CrypSA definitions. +Refer to the Terminology Primer for authoritative meaning.” + +--- + ## Purpose This section contains experimental and forward-looking ideas related to CrypSA. diff --git a/exploratory/core_concepts/CrypSA_Concept_Map.md b/exploratory/core_concepts/CrypSA_Concept_Map.md index bd520c8..2a2e2b1 100644 --- a/exploratory/core_concepts/CrypSA_Concept_Map.md +++ b/exploratory/core_concepts/CrypSA_Concept_Map.md @@ -1,5 +1,12 @@ # CrypSA Concept Map +--- + +“Terminology in this document may not match current CrypSA definitions. +Refer to the Terminology Primer for authoritative meaning.” + +--- + > Exploratory note: This document reflects conceptual exploration and early modeling. > > For the current CrypSA model, refer to: diff --git a/exploratory/core_concepts/CrypSA_Event_Flow_Diagram_Explanation.md b/exploratory/core_concepts/CrypSA_Event_Flow_Diagram_Explanation.md index ecdfda1..3cfd541 100644 --- a/exploratory/core_concepts/CrypSA_Event_Flow_Diagram_Explanation.md +++ b/exploratory/core_concepts/CrypSA_Event_Flow_Diagram_Explanation.md @@ -1,5 +1,12 @@ # CrypSA Event Flow Model +--- + +“Terminology in this document may not match current CrypSA definitions. +Refer to the Terminology Primer for authoritative meaning.” + +--- + > Exploratory note: This document reflects conceptual exploration and early modeling. > > For the current CrypSA model, refer to: diff --git a/exploratory/core_concepts/CrypSA_Event_Flow_Simple.md b/exploratory/core_concepts/CrypSA_Event_Flow_Simple.md index 5e939cf..c89f9ce 100644 --- a/exploratory/core_concepts/CrypSA_Event_Flow_Simple.md +++ b/exploratory/core_concepts/CrypSA_Event_Flow_Simple.md @@ -1,5 +1,12 @@ # CrypSA Event Flow (Simplified) +--- + +“Terminology in this document may not match current CrypSA definitions. +Refer to the Terminology Primer for authoritative meaning.” + +--- + > Exploratory note: This document reflects conceptual exploration and early modeling. > > For the current CrypSA model, refer to: diff --git a/exploratory/core_concepts/CrypSA_Event_Lifecycle.md b/exploratory/core_concepts/CrypSA_Event_Lifecycle.md index e8eb738..6326ce7 100644 --- a/exploratory/core_concepts/CrypSA_Event_Lifecycle.md +++ b/exploratory/core_concepts/CrypSA_Event_Lifecycle.md @@ -1,5 +1,12 @@ # CrypSA Event Lifecycle +--- + +“Terminology in this document may not match current CrypSA definitions. +Refer to the Terminology Primer for authoritative meaning.” + +--- + > Exploratory note: This document reflects conceptual exploration and early modeling. > > For the current CrypSA model, refer to: diff --git a/exploratory/core_concepts/CrypSA_Invariant_Model.md b/exploratory/core_concepts/CrypSA_Invariant_Model.md index 53fba7e..74943d7 100644 --- a/exploratory/core_concepts/CrypSA_Invariant_Model.md +++ b/exploratory/core_concepts/CrypSA_Invariant_Model.md @@ -1,5 +1,12 @@ # CrypSA Invariant Model +--- + +“Terminology in this document may not match current CrypSA definitions. +Refer to the Terminology Primer for authoritative meaning.” + +--- + > Exploratory note: This document reflects conceptual exploration and early modeling. > > For the current CrypSA model, refer to: diff --git a/exploratory/core_concepts/CrypSA_Mental_Model_One_Page.md b/exploratory/core_concepts/CrypSA_Mental_Model_One_Page.md index 358a43c..74db805 100644 --- a/exploratory/core_concepts/CrypSA_Mental_Model_One_Page.md +++ b/exploratory/core_concepts/CrypSA_Mental_Model_One_Page.md @@ -1,5 +1,12 @@ # CrypSA Mental Model (One Page) +--- + +“Terminology in this document may not match current CrypSA definitions. +Refer to the Terminology Primer for authoritative meaning.” + +--- + > Exploratory note: This document reflects conceptual exploration and early modeling. > > For the current CrypSA model, refer to: diff --git a/exploratory/core_concepts/CrypSA_Object_Model.md b/exploratory/core_concepts/CrypSA_Object_Model.md index 033aa37..89c9370 100644 --- a/exploratory/core_concepts/CrypSA_Object_Model.md +++ b/exploratory/core_concepts/CrypSA_Object_Model.md @@ -1,5 +1,13 @@ # CrypSA Object Model +--- + +“Terminology in this document may not match current CrypSA definitions. +Refer to the Terminology Primer for authoritative meaning.” + +--- + + > Exploratory note: This document reflects conceptual exploration and early modeling. > > For the current CrypSA model, refer to: diff --git a/exploratory/core_concepts/README.md b/exploratory/core_concepts/README.md index 0cbd2f9..20846fc 100644 --- a/exploratory/core_concepts/README.md +++ b/exploratory/core_concepts/README.md @@ -1,5 +1,12 @@ # Core Concepts +--- + +“Terminology in this document may not match current CrypSA definitions. +Refer to the Terminology Primer for authoritative meaning.” + +--- + ## Purpose This folder contains exploratory concept documents and early explanatory models of CrypSA. diff --git a/exploratory/foundation/CrypSA_Foundational_Paper_v1.md b/exploratory/foundation/CrypSA_Foundational_Paper_v1.md index d21c0ee..2f239f6 100644 --- a/exploratory/foundation/CrypSA_Foundational_Paper_v1.md +++ b/exploratory/foundation/CrypSA_Foundational_Paper_v1.md @@ -1,5 +1,13 @@ # CrypSA: A Distributed Architecture for Persistent Digital Universes +--- + +“Terminology in this document may not match current CrypSA definitions. +Refer to the Terminology Primer for authoritative meaning.” + +--- + + > Exploratory note: This document represents early conceptual framing. > > It reflects the evolution of CrypSA and may contain terminology or structure that differs from the current model. diff --git a/exploratory/foundation/CrypSA_Origin_Statement.md b/exploratory/foundation/CrypSA_Origin_Statement.md index 16b4111..5826caa 100644 --- a/exploratory/foundation/CrypSA_Origin_Statement.md +++ b/exploratory/foundation/CrypSA_Origin_Statement.md @@ -1,5 +1,12 @@ # CrypSA Origin Statement +--- + +“Terminology in this document may not match current CrypSA definitions. +Refer to the Terminology Primer for authoritative meaning.” + +--- + > Exploratory note: This document represents early conceptual framing. > > For the current CrypSA model, refer to: diff --git a/exploratory/foundation/CrypSA_Universe_Model.md b/exploratory/foundation/CrypSA_Universe_Model.md index aab9588..5e29d33 100644 --- a/exploratory/foundation/CrypSA_Universe_Model.md +++ b/exploratory/foundation/CrypSA_Universe_Model.md @@ -1,5 +1,12 @@ # CrypSA Universe Model +--- + +“Terminology in this document may not match current CrypSA definitions. +Refer to the Terminology Primer for authoritative meaning.” + +--- + > Exploratory note: This document represents early conceptual framing. > > For the current CrypSA model, refer to: diff --git a/exploratory/foundation/CrypSA_vs_Traditional_Multiplayer.md b/exploratory/foundation/CrypSA_vs_Traditional_Multiplayer.md index 99a668f..4abbb31 100644 --- a/exploratory/foundation/CrypSA_vs_Traditional_Multiplayer.md +++ b/exploratory/foundation/CrypSA_vs_Traditional_Multiplayer.md @@ -1,5 +1,12 @@ # Traditional Multiplayer vs CrypSA Architecture +--- + +“Terminology in this document may not match current CrypSA definitions. +Refer to the Terminology Primer for authoritative meaning.” + +--- + > Exploratory note: This document represents early conceptual framing. > > For the current CrypSA model, refer to: diff --git a/exploratory/foundation/README.md b/exploratory/foundation/README.md index d1c979b..50c66dd 100644 --- a/exploratory/foundation/README.md +++ b/exploratory/foundation/README.md @@ -1,5 +1,12 @@ # Foundation +--- + +“Terminology in this document may not match current CrypSA definitions. +Refer to the Terminology Primer for authoritative meaning.” + +--- + ## Purpose This folder contains the early conceptual framing, motivation, and philosophical background of CrypSA. diff --git a/implementation/CrypSA_Adapter_Rules.md b/implementation/CrypSA_Adapter_Rules.md index decf43e..ed26250 100644 --- a/implementation/CrypSA_Adapter_Rules.md +++ b/implementation/CrypSA_Adapter_Rules.md @@ -1,14 +1,24 @@ # CrypSA Adapter Rules -> Scope note: This document provides implementation guidance for adapters. -> -> For authoritative system behavior, refer to `../spec/` and `../architecture/`. +--- + +## ⚠️ Implementation Guidance (Non-Authoritative) + +This document provides example implementation approaches for CrypSA. + +👉 These patterns are not required, but are recommended to maintain clear architectural boundaries. + +👉 CrypSA defines invariants and behavior through the `/spec` directory. + +👉 Implementation details may vary based on product requirements. + +This document illustrates one possible way to structure a system that conforms to CrypSA. --- ## Purpose -This document defines practical engineering rules for adapters in CrypSA. +This document provides practical engineering guidance and example rules for implementing adapters in CrypSA. Adapters are part of the **translation layer** and exist to shape runtime and canonical data for consumption by: @@ -17,7 +27,7 @@ Adapters are part of the **translation layer** and exist to shape runtime and ca * tools * debugging systems -These rules exist to prevent adapters from becoming: +These guidelines exist to prevent adapters from becoming: * hidden controllers * validation layers diff --git a/implementation/CrypSA_Local_First_Design_Pattern.md b/implementation/CrypSA_Local_First_Design_Pattern.md index 4b7be27..276560d 100644 --- a/implementation/CrypSA_Local_First_Design_Pattern.md +++ b/implementation/CrypSA_Local_First_Design_Pattern.md @@ -1,5 +1,21 @@ # Local-First CrypSA Design Pattern +--- + +## ⚠️ Implementation Guidance (Non-Authoritative) + +This document provides example implementation approaches for CrypSA. + +👉 These patterns are not required, but are recommended to maintain clear architectural boundaries. + +👉 CrypSA defines invariants and behavior through the `/spec` directory. + +👉 Implementation details may vary based on product requirements. + +This document illustrates one possible way to structure a system that conforms to CrypSA. + +--- + ## Purpose This document describes a practical design pattern for building CrypSA systems **local-first**. @@ -87,7 +103,7 @@ In the first implementation: * candidate events still flow through validation * canonical event history is still distinct from local simulation -This is not a shortcut or fake mode. +This is not a shortcut or reduced mode. It is a valid CrypSA deployment. @@ -176,10 +192,14 @@ These are deployment concerns, not architectural changes. ### 1. Never bypass validation just because everything is local +Even in local mode, all candidate events must pass through the invariant boundary. + --- ### 2. Keep candidate events explicit +All changes to shared or canonical state must be represented as candidate events, not implicit mutations. + --- ### 3. Reconstruct from canonical event history even in local mode @@ -196,20 +216,54 @@ The candidate event contract and validation behavior must remain identical acros ### 5. Treat local validator as a first-class deployment +Local validation is not a temporary shortcut. It is a valid CrypSA deployment that should follow the same architectural rules as remote systems. + --- ## Common Failure Modes ### Hidden Direct State Mutation +Problem: + +* local systems mutate runtime or canonical state directly +* changes bypass candidate events and validation + +Result: + +* breaks invariant boundary +* introduces hidden state changes +* prevents reliable replay + --- ### Local and Remote Modes Behave Differently +Problem: + +* local mode bypasses validation or uses different logic +* remote mode enforces full validation + +Result: + +* inconsistent behavior between environments +* bugs that only appear after deployment +* loss of architectural continuity + --- ### Replay Is Skipped in Local Mode +Problem: + +* local systems rely on live state instead of reconstructing from canonical event history + +Result: + +* replay becomes unreliable or impossible +* derived canonical state diverges +* debugging becomes difficult + --- ### Canonical Ordering Drift @@ -229,6 +283,29 @@ Result: ## Relationship to Validator Deployment Model +The local-first design pattern aligns directly with the CrypSA validator deployment model. + +The validator is a role, not a location. + +In a local-first system: + +* the validator may run in the same process as the observer +* the invariant boundary remains explicit +* canonical event history is still produced through validation + +As the system evolves: + +* the validator may move to a host process +* or to a dedicated remote system + +This transition does not change: + +* the validation model +* the event lifecycle +* the role of the invariant boundary + +Only the deployment changes. The architecture remains the same. + --- ## Key Insight @@ -240,6 +317,17 @@ Result: ## Summary +The local-first CrypSA pattern allows systems to be built and tested without introducing architectural shortcuts. + +By preserving: + +* the invariant boundary +* canonical event history +* deterministic replay +* validator authority + +from the beginning, the system can scale from local execution to distributed deployment without requiring structural changes. + --- ## One Sentence Summary diff --git a/implementation/CrypSA_Local_First_Development_Approach.md b/implementation/CrypSA_Local_First_Development_Approach.md index 4223057..3830135 100644 --- a/implementation/CrypSA_Local_First_Development_Approach.md +++ b/implementation/CrypSA_Local_First_Development_Approach.md @@ -1,8 +1,22 @@ # CrypSA Local-First Development Approach +--- + +## ⚠️ Implementation Guidance (Non-Authoritative) + +This document provides example implementation approaches for CrypSA. + +👉 These patterns are not required, but are recommended to maintain clear architectural boundaries. + +👉 CrypSA defines invariants and behavior through the `/spec` directory. + +👉 Implementation details may vary based on product requirements. + +--- + ## Purpose -This document defines the recommended development approach for building CrypSA systems. +This document provides a recommended development approach for building CrypSA systems. The core idea is: @@ -14,6 +28,16 @@ It is an implementation strategy, not a runtime specification. --- +## Relationship to Minimal Validator + +This document assumes you are building: + +→ `implementation/CrypSA_Minimal_Validator_v0.1.md` + +Follow this document alongside the minimal validator implementation. + +--- + ## Core Principle CrypSA defines the validator as a **role**, not a location. @@ -22,7 +46,7 @@ Because of this, a system can begin with: * an observer * a validator -* canonical event history (ordered via canonical_sequence) +* canonical event history (ordered via `canonical_sequence`) all running locally, while still following the real architecture. @@ -49,7 +73,7 @@ It lets builders first prove: * candidate events are correctly formed * validation behaves correctly -* canonical event history is correct, append-only, and ordered via canonical_sequence +* canonical event history is correct, append-only, and ordered via `canonical_sequence` * replay produces deterministic results based on canonical ordering * observers reconcile properly @@ -57,25 +81,44 @@ It lets builders first prove: ## The Recommended Sequence +Local Phase: + +Observer → Validator → Canonical Event History → Replay → Observer + +Remote Phase: + +Observer → Network → Validator → Canonical Event History → Network → Observer + +--- + ### Step 1 — Start with a Local Validator Begin with a minimal local deployment: * observer and validator in the same process or machine * canonical event history stored locally -* replay and derived state functioning normally +* replay and derived canonical state functioning normally * validation fully active * invariant boundary explicitly enforced -At this stage, the goal is to prove the **actual runtime loop**, not simulate one. +#### You should implement: + +* an in-process validator +* an append-only canonical event history +* a validation pipeline: + + * schema → identity → preconditions → invariants → rules +* deterministic replay that produces derived canonical state +* a simple observer that can submit candidate events + +#### Result -You should already have: +At the end of this step, you should have: -* explicit candidate events -* explicit validation -* append-only canonical event history ordered via canonical_sequence -* deterministic replay -* observer reconciliation +* a working validator running locally +* a canonical event history that can append events +* replay producing derived canonical state +* an observer capable of submitting candidate events --- @@ -83,15 +126,14 @@ You should already have: Before introducing networking, confirm that the CrypSA model works locally. -This means proving: +#### You should verify: -* local simulation does not define truth -* candidate events cross the invariant boundary -* the validator determines accept/reject -* accepted events become canonical and are assigned canonical_sequence -* replay produces consistent derived canonical state -* rejected events correctly roll back or adjust local state -* snapshot and reconnect logic can be reasoned about +* submitting a candidate event triggers validation +* If accepted, an event becomes canonical and is appended to canonical event history +* `canonical_sequence` is assigned correctly +* replay produces the same derived canonical state every time +* rejected events do not affect canonical event history +* observer reconciliation corrects local prediction --- @@ -104,22 +146,12 @@ This may involve: * host-based deployment * or a dedicated remote validator -At this stage, the architecture must remain unchanged. +#### You should implement: -What changes: - -* process separation -* transport mechanism -* observer ↔ validator communication - -What must not change: - -* event structure -* validation semantics -* canonical event history behavior -* canonical ordering via canonical_sequence -* replay behavior -* observer reconciliation model +* a transport layer between observer and validator +* message-based submission of candidate events +* broadcast of canonical events +* replay-based synchronization on reconnect --- @@ -129,9 +161,10 @@ A correct CrypSA implementation preserves the following across deployment change * observers submit candidate events * validator determines truth +* If accepted, an event becomes canonical and is appended to canonical event history * canonical event history remains append-only -* canonical event history remains ordered via canonical_sequence -* replay remains deterministic and ordered via canonical_sequence +* canonical event history remains ordered via `canonical_sequence` +* replay remains deterministic and ordered via `canonical_sequence` * derived canonical state remains reconstructable * invariant boundary remains explicit @@ -141,6 +174,18 @@ If these change when moving to a remote validator: --- +## Definition of Done (Local Phase) + +You have successfully completed local-first development when: + +* a candidate event can be submitted +* If accepted, an event becomes canonical and is appended to canonical event history +* `canonical_sequence` is assigned correctly +* replay produces deterministic derived canonical state +* observers reconcile correctly + +--- + ## What Can Be Added Later After the core system works locally, additional concerns can be layered in: @@ -190,15 +235,15 @@ Examples of incorrect approaches: * bypassing validation because everything is local * mutating canonical state directly * skipping replay -* ignoring canonical_sequence or relying on local ordering +* ignoring `canonical_sequence` or relying on local ordering * letting observer/UI logic define truth -This is not CrypSA. +This does not align with CrypSA. A local validator must behave exactly like a real validator, including: * enforcing invariants -* assigning canonical_sequence +* assigning `canonical_sequence` * maintaining canonical event history --- diff --git a/implementation/CrypSA_Local_To_Remote_Migration_Guide.md b/implementation/CrypSA_Local_To_Remote_Migration_Guide.md index 9e2a867..6af8a36 100644 --- a/implementation/CrypSA_Local_To_Remote_Migration_Guide.md +++ b/implementation/CrypSA_Local_To_Remote_Migration_Guide.md @@ -1,5 +1,21 @@ # CrypSA Local → Remote Migration Guide +--- + +## ⚠️ Implementation Guidance (Non-Authoritative) + +This document provides example implementation approaches for CrypSA. + +👉 These patterns are not required, but are recommended to maintain clear architectural boundaries. + +👉 CrypSA defines invariants and behavior through the `/spec` directory. + +👉 Implementation details may vary based on product requirements. + +This document illustrates one possible way to structure a system that conforms to CrypSA. + +--- + ## Purpose This document explains how to transition a CrypSA system from: @@ -267,7 +283,7 @@ You must now handle: If validation changes between local and remote: -> you have broken CrypSA +> the implementation no longer conforms to CrypSA --- diff --git a/implementation/CrypSA_Minimal_Runtime_Walkthrough.md b/implementation/CrypSA_Minimal_Runtime_Walkthrough.md new file mode 100644 index 0000000..cca519c --- /dev/null +++ b/implementation/CrypSA_Minimal_Runtime_Walkthrough.md @@ -0,0 +1,468 @@ +# CrypSA Minimal Runtime Walkthrough + +## Purpose + +This document shows the smallest practical end-to-end runtime flow of a CrypSA system. + +It exists to make the architecture concrete. + +This is not a full implementation guide. + +It is a walkthrough of the minimum moving parts required to demonstrate the CrypSA runtime model in practice. + +The goal is to show: + +* what components exist +* what each component does +* how a simple interaction flows through the system +* what a minimal implementation must prove + +For authoritative runtime behavior, refer to: + +* `../spec/` + +For the authoritative conceptual flow of the system, refer to: + +* `../architecture/CrypSA_Runtime_Model.md` + +For how this runtime design affects infrastructure, see: + +→ `../architecture/CrypSA_Infrastructure_Implications.md` + +--- + +## 📜 Authority Level + +This document is implementation guidance. + +It does not define runtime behavior. + +It does not override the architecture or specification. + +If there is any conflict: + +* `/spec` defines behavior +* `/architecture` defines structure and conceptual flow +* this document illustrates one minimal practical implementation path + +--- + +## What This Walkthrough Is + +This walkthrough describes the smallest useful CrypSA runtime that proves: + +* observers can perform actions locally +* actions that affect canonical truth become candidate events +* a validator determines whether those candidate events become canonical +* accepted events are appended to canonical event history +* observers replay canonical event history +* observers reconcile local state against canonical truth + +--- + +## What This Walkthrough Is Not + +This walkthrough is not: + +* a production deployment guide +* a required transport design +* a required programming model +* a complete multiplayer framework +* a performance guide + +It is a minimal proof path. + +--- + +## Minimal Runtime Goal + +A minimal CrypSA runtime should prove this sequence works end-to-end: + +1. an observer performs an action +2. the invariant boundary determines the action affects canonical truth +3. a candidate event is created +4. the candidate event is submitted to the validator +5. the validator determines whether the candidate event becomes canonical +6. if accepted, an event becomes canonical and is appended to canonical event history +7. canonical events are made available to observers +8. observers replay canonical event history +9. observers reconcile local state with canonical event history + +If this works, the CrypSA runtime model is proven in executable form. + +--- + +## Minimal Runtime Loop (Visual) + +```mermaid +flowchart LR + +A["Observer Action"] --> B["Invariant Boundary"] +B -->|Affects Canonical Truth| C["Candidate Event"] +C --> D["Validator"] +D -->|Accepted| E["Canonical Event History"] +D -->|Rejected| G["Reconciliation"] +E --> F["Replay"] +F --> G["Reconciliation"] +G --> A +``` + +This loop repeats continuously. + +> This loop replaces the need for a continuously running authoritative simulation. + +--- + +## What This Replaces + +A minimal CrypSA runtime does not require: + +* a continuously running authoritative server simulation loop +* direct state synchronization between clients +* server-maintained mutable world state as the source of truth + +Instead: + +* validation defines canonical truth +* canonical event history replaces synchronized state +* observers perform local prediction + +--- + +## Minimal Transport Assumption + +A minimal runtime only requires two flows: + +* observer → validator: submit candidate event +* validator → observers: make canonical events available + +No direct state synchronization is required. + +--- + +# Minimal Components + +--- + +## 1. Observer + +The observer is the local runtime instance responsible for: + +* receiving input +* performing local prediction +* creating candidate events when the invariant boundary is crossed +* maintaining predicted state +* replaying canonical events +* reconciling local state with canonical truth + +In a minimal implementation: + +* one observer proves the loop +* two observers prove shared canonical truth (convergence to the same canonical state) + +--- + +## 2. Validator + +The validator is the authority that determines what becomes canonical. + +It is responsible for: + +* receiving candidate events +* validating them against invariants +* determining whether the candidate event becomes canonical +* assigning `canonical_sequence` +* appending accepted events to canonical event history +* making canonical events available to observers + +The validator may run: + +* locally +* remotely + +The deployment does not matter. +The role does. + +--- + +## 3. Canonical Event History + +Canonical event history is the source of truth. + +A minimal implementation only needs: + +* append-only storage +* `canonical_sequence` +* ordered retrieval of accepted canonical events + +This can be implemented as: + +* an in-memory list +* a local file +* a simple database table + +--- + +## 4. Replay Function + +Replay derives canonical state from canonical event history. + +A minimal implementation must prove: + +* replay is deterministic +* replay produces identical results from identical history +* state can be rebuilt from canonical event history alone + +--- + +## 5. Reconciliation Logic + +The observer compares: + +* predicted local state +* replayed canonical state + +If they differ: + +* local state yields to canonical truth + +Minimal reconciliation: + +* replace local values +* correct divergence +* continue simulation + +--- + +# Minimal Example Scenario + +## Example: Claim a Tile + +A user attempts to claim a tile in a shared grid. + +This works well because: + +* clear conflict scope +* simple validation +* visible results +* proves authority and convergence + +--- + +## Initial State + +* tile `(2,3)` is unclaimed +* observer A sees it as open +* observer B sees it as open +* canonical event history contains no claim + +--- + +## Action + +Observer A performs: + +```text +claim tile (2,3) +``` + +This crosses the invariant boundary. + +So a candidate event is created: + +```json +{ + "event_type": "tile.claim_requested", + "actor_id": "observer_a", + "target_tile": [2, 3] +} +``` + +--- + +## Validator Evaluation + +The validator evaluates the candidate event against invariants: + +* structure is valid +* actor exists +* tile exists +* tile is not already claimed + +### If accepted + +```json +{ + "canonical_sequence": 17, + "event_type": "tile.claimed", + "actor_id": "observer_a", + "target_tile": [2, 3] +} +``` + +Event becomes canonical and is appended. + +### If rejected + +* canonical event history does not change +* the rejection reason may be returned to the observer + +--- + +## Availability + +Canonical events are made available to observers. + +Observers must: + +* consume events +* order them by `canonical_sequence` + +--- + +## Replay + +Replay applies canonical events: + +* tile `(2,3)` becomes claimed + +--- + +## Reconciliation + +Observers compare: + +* predicted state +* canonical replayed state + +If different: + +* local state is corrected + +All observers converge. + +--- + +# Minimal Runtime Sequence + +1. Observer performs action +2. Invariant boundary determines canonical impact +3. Candidate event is created +4. Event is submitted to validator +5. Validator determines whether the candidate event becomes canonical +6. Canonical event is appended +7. Canonical event is made available +8. Replay derives canonical state +9. Observer reconciles + +--- + +# Minimal Proof Checklist + +## Core Truth Model + +* candidate events ≠ canonical events +* validator defines canonical +* canonical event history is append-only +* canonical event history is the only source of truth + +## Replay Model + +* state derives from canonical event history +* replay is deterministic +* results are consistent + +## Reconciliation Model + +* local prediction allowed +* divergence corrected +* rejected events do not affect history + +## Ordering Model + +* events use `canonical_sequence` +* ordering is independent of delivery timing + +--- + +# Suggested Minimal Runtime Architecture + +```text +Observer + ├── Input Handling + ├── Local Prediction + ├── Invariant Boundary Check + ├── Candidate Event Creation + ├── Replay Engine + └── Reconciliation + +Validator + ├── Candidate Event Intake + ├── Validation + ├── canonical_sequence Assignment + ├── Canonical Event History Append + └── Canonical Event Availability + +Shared + └── Canonical Event History Storage +``` + +--- + +# Recommended First Implementation Scope + +Keep it extremely small: + +* one event type +* one invariant +* two observers +* no smoothing +* no production networking + +Target: + +```text +Two observers claim tiles on a shared grid +``` + +--- + +# What Must Be Visible + +A demo must show: + +* immediate local action +* candidate event creation +* validator decision +* canonical history changes only on acceptance +* replay updates state +* observers converge + +--- + +# Why This Matters + +This document proves: + +> CrypSA is not just an idea — it is a minimal executable system. + +It provides the bridge from: + +* architecture → proof → implementation + +--- + +# Relationship to Other Documents + +* `../architecture/CrypSA_Runtime_Model.md` +* `../architecture/CrypSA_Boundary_Definitions.md` +* `../spec/` +* `minimal_validator/` +* `CrypSA_Local_First_Development_Approach.md` + +--- + +# One Sentence Summary + +A minimal CrypSA runtime proves that observers can act locally, candidate events can be validated into canonical event history, and canonical truth can be replayed and reconciled across observers using a small, well-defined set of components. +👉 This demonstrates that canonical truth can exist without a continuously running authoritative simulation. diff --git a/implementation/CrypSA_Project_Status.md b/implementation/CrypSA_Project_Status.md index 949186d..01f8070 100644 --- a/implementation/CrypSA_Project_Status.md +++ b/implementation/CrypSA_Project_Status.md @@ -1,8 +1,18 @@ # CrypSA Project Status -> Scope note: This document describes project status and implementation direction. -> -> For authoritative runtime behavior, refer to `../spec/`. +--- + +## ⚠️ Implementation Guidance (Non-Authoritative) + +This document provides example implementation approaches for CrypSA. + +👉 These patterns are not required, but are recommended to maintain clear architectural boundaries. + +👉 CrypSA defines invariants and behavior through the `/spec` directory. + +👉 Implementation details may vary based on product requirements. + +This document illustrates one possible way to structure a system that conforms to CrypSA. --- @@ -52,9 +62,14 @@ CrypSA separates responsibilities into four layers: The validator controls truth. +👉 The validator defines what becomes canonical and therefore controls canonical truth. + Observers simulate locally. * canonical event history is ordered via canonical_sequence +* canonical event history is the source of truth + +If accepted, an event becomes canonical and is appended to canonical event history. --- @@ -86,13 +101,13 @@ The repository currently defines CrypSA through: * `../architecture/` — system structure and architectural boundaries * `../spec/` — runtime behavior and implementation-facing system contracts -Together, these define: +Together, these describe: * the observer model * the validator role in validation and canonical event handling * validated canonical event-driven world evolution * invariant-based validation -* reconstruction from canonical event history ordered via canonical_sequence +* reconstruction via replay of canonical event history ordered via canonical_sequence --- @@ -123,7 +138,7 @@ Current coverage includes: * snapshot model * identity model * transport model -* canonical ordering model (canonical_sequence) +* canonical ordering model (`canonical_sequence`) These documents define how CrypSA is expected to function as a system. @@ -145,7 +160,7 @@ It demonstrates: * validation and invariant boundaries * explicit invariant boundary enforcement * canonical vs observer-local state -* replay-derived state +* replay-derived canonical state * adapter and lens separation Status: @@ -161,9 +176,9 @@ Important: --- -### 5. Minimal Server Design +### 5. Minimal Validator Design -A minimal server design has been defined in: +A minimal validator design has been defined in: * `CrypSA_Minimal_Server_v0.1.md` @@ -172,7 +187,7 @@ This document describes: * the smallest viable independent validator * validation pipeline structure * invariant boundary enforcement -* canonical event handling and ordering (canonical_sequence) +* canonical event handling and ordering (`canonical_sequence`) * observer interaction --- @@ -181,8 +196,8 @@ This document describes: The following are **not yet implemented**: -* a fully functional independent CrypSA server -* real networked multi-client runtime +* a fully functional independent CrypSA validator runtime +* real networked multi-observer runtime * production-grade persistence layer * large-scale performance testing * shard or partition coordination @@ -215,21 +230,30 @@ CrypSA is currently focused on proving: 1. that canonical event-driven truth with deterministic ordering is viable 2. that invariant-based validation can replace full server simulation -3. that observers can reconstruct shared state from canonical event history +3. that observers can reconstruct derived canonical state from canonical event history 4. that observer reconciliation is manageable -5. that deterministic reconstruction from canonical event history ordered via canonical_sequence is reliable +5. that deterministic reconstruction via replay of canonical event history ordered via canonical_sequence is reliable + +--- + +## Determinism Guarantee + +Given the same: + +* canonical event history +* interpretation logic -The goal is to validate the architecture, not optimize it. +reconstruction must produce equivalent derived canonical state --- ## Next Major Step -## CrypSA Minimal Server v0.1 +### CrypSA Minimal Validator v0.1 The teaching prototype demonstrates the model. -The minimal server will test CrypSA as a runtime system. +The minimal validator will test CrypSA as a runtime system. This introduces: @@ -237,7 +261,7 @@ This introduces: * real event submission over a network * validation pipeline execution * canonical event history (ordered via canonical_sequence) -* derived state updates +* derived canonical state reconstruction via replay * multi-observer interaction --- @@ -245,7 +269,7 @@ This introduces: ### Key Distinction * The **teaching prototype** exists to make the model understandable -* The **minimal server** exists to test the model under real runtime conditions +* The **minimal validator** exists to test the model under real runtime conditions --- @@ -253,7 +277,7 @@ This introduces: Immediate priorities: -1. build the minimal server runtime +1. build the minimal validator runtime 2. connect multiple observers 3. test validation and conflict resolution 4. validate replay and reconstruction @@ -314,4 +338,4 @@ Use these for background only, not as the current source of truth. ## One Sentence Summary -CrypSA is a defined architecture with formal specifications and a completed teaching prototype, now moving toward its first real runtime implementation through a minimal independent validator while preserving canonical truth, ordering, and deterministic reconstruction. +CrypSA is a defined architecture with formal specifications and a completed teaching prototype, now moving toward its first real runtime implementation through a minimal validator while preserving canonical event history as the source of truth, canonical ordering via canonical_sequence, and deterministic reconstruction via replay. diff --git a/implementation/CrypSA_Quick_Start_For_Engineers.md b/implementation/CrypSA_Quick_Start_For_Engineers.md index 42d871a..1812bf6 100644 --- a/implementation/CrypSA_Quick_Start_For_Engineers.md +++ b/implementation/CrypSA_Quick_Start_For_Engineers.md @@ -1,13 +1,23 @@ # CrypSA Quick Start for Engineers -> Scope note: This document is an implementation-oriented starting point. -> -> For authoritative runtime behavior, refer to `../spec/`. -> > Intended audience: engineers who understand the core CrypSA idea and want to build a minimal working system. --- +## ⚠️ Implementation Guidance (Non-Authoritative) + +This document provides example implementation approaches for CrypSA. + +👉 These patterns are not required, but are recommended to maintain clear architectural boundaries. + +👉 CrypSA defines invariants and behavior through the `/spec` directory. + +👉 Implementation details may vary based on product requirements. + +This document illustrates one possible way to structure a system that conforms to CrypSA. + +--- + ## Purpose This document provides a concise guide for building a minimal CrypSA-based system. @@ -17,14 +27,14 @@ It is not a full introduction to CrypSA. It focuses on: * the smallest viable runtime loop -* the minimum required components +* the core components of a minimal CrypSA system * how to go from concept → working system --- ## Minimal CrypSA System -A minimal CrypSA implementation requires only: +A minimal CrypSA implementation can be built with: * identity and object definitions * canonical event history @@ -36,7 +46,7 @@ Each part exists to protect canonical event history while allowing local simulat --- -## Step 1 — Define Identity and Object Structure +## Step 1 — Define Identity and Object Structure (Example Approach) Every canonical object must have: @@ -47,8 +57,8 @@ Every canonical object must have: Example: ```text -Object Identity: sword_1001 -Genome: sword_type_A +Object Identity: sword_1001 +Genome: sword_type_A ``` The Mint (or equivalent system) defines: @@ -115,7 +125,7 @@ Avoid: --- -## Step 4 — Maintain Derived Canonical State +## Step 4 — Maintain Derived Canonical State (via Replay) The validator maintains a derived canonical state (typically cached) for: @@ -134,7 +144,7 @@ Important: > derived canonical state is a computed view, not the source of truth -It is updated by applying accepted events in canonical_sequence order. +It is reconstructed via replay of canonical event history, typically applied incrementally in canonical_sequence order. --- @@ -154,6 +164,8 @@ Observers: * gather user input * track pending candidate events +👉 Observers do not define canonical truth + --- ## Step 6 — Implement the Invariant Boundary @@ -162,7 +174,7 @@ Every interaction must answer: > Does this affect canonical event history? -All canonical changes must pass through the invariant boundary. +All changes that affect canonical event history must pass through the invariant boundary. Example: @@ -248,9 +260,10 @@ def validate_event(event): If validation succeeds: +* If accepted, an event becomes canonical and is appended to canonical event history * assign canonical metadata (including `canonical_sequence`) * append to canonical event history -* update derived canonical state +* update derived canonical state via replay * notify observers Example: @@ -278,14 +291,25 @@ This may involve: Because reconstruction is deterministic: -> all observers converge on the same derived canonical state reconstructed from canonical event history +> all observers converge on equivalent derived canonical state reconstructed from canonical event history + +--- + +## Determinism Guarantee + +Given the same: + +* canonical event history +* interpretation logic + +replay must produce equivalent derived canonical state --- ## Minimal CrypSA Loop ```text -Reconstruct world +Reconstruct world via replay → Simulate locally → Interaction occurs → Invariant boundary check @@ -293,7 +317,7 @@ Reconstruct world → Validator validation → Assign canonical_sequence → Canonical event history updated -→ Derived canonical state updated +→ Derived canonical state reconstructed via replay → Observer reconciliation ``` @@ -358,7 +382,7 @@ Why: ## Summary -A minimal CrypSA system requires: +A minimal CrypSA system typically includes: * identity and structural definitions * canonical event history @@ -367,10 +391,10 @@ A minimal CrypSA system requires: * invariant boundary checks * validator-side validation -With these, a persistent event-driven universe can be built. +With these, a persistent event-driven system can be built. --- ## One Sentence Summary -A minimal CrypSA system allows observers to simulate locally while a validator validates candidate events, records accepted events as canonical event history ordered via canonical_sequence, and distributes that shared history back to all observers. +A minimal CrypSA system allows observers to simulate locally while a validator validates candidate events; if accepted, an event becomes canonical and is appended to canonical event history, which is then used to reconstruct derived canonical state via deterministic replay across all observers. diff --git a/implementation/CrypSA_Teaching_Prototype_Lessons.md b/implementation/CrypSA_Teaching_Prototype_Lessons.md index 3a8c0b8..400c991 100644 --- a/implementation/CrypSA_Teaching_Prototype_Lessons.md +++ b/implementation/CrypSA_Teaching_Prototype_Lessons.md @@ -90,7 +90,7 @@ Together, they prevented: * interpretation logic from spreading across layers * control logic from leaking into presentation -This confirmed that: +This demonstrated that: > data shaping and intent handling must be explicit and separated @@ -153,7 +153,7 @@ helped: * protect boundaries * verify assumptions -This reinforced that: +This showed that: > tests should protect architecture, not just behavior diff --git a/implementation/README.md b/implementation/README.md index 50fca58..ca656bb 100644 --- a/implementation/README.md +++ b/implementation/README.md @@ -1,16 +1,66 @@ # Implementation +--- + +## ⚠️ Implementation Guidance (Non-Authoritative) + +This folder provides example implementation approaches for CrypSA. + +👉 These patterns are not required, but are recommended to maintain clear architectural boundaries. + +👉 CrypSA defines invariants and behavior through the `/spec` directory. + +👉 Implementation details will vary based on product requirements. + +Documents in this folder illustrate possible implementation approaches to structure systems that conform to CrypSA. + +--- + ## Purpose -This folder contains implementation strategy, build direction, project status, and practical engineering guidance for CrypSA. +This folder contains implementation strategy, build direction, and practical engineering guidance for CrypSA. These documents describe: * how the system may be implemented in code * how components may be organized in practice -* how architectural ideas translate into implementation +* how architectural ideas are proven through implementation -Implementation must treat the validator as the authority over canonical event history. +👉 Implementation exists to **prove the CrypSA runtime model through executable systems**. + +Implementation must treat the validator as the component that defines what becomes canonical. + +--- + +## Where to Start + +The recommended starting point is: + +👉 `CrypSA_Minimal_Runtime_Walkthrough.md` + +This document defines: + +* the smallest possible working CrypSA system +* the minimal runtime loop +* the components required to prove the architecture + +👉 Implementation should begin by proving this minimal runtime, not by building a full system. + +--- + +## Implementation Approach + +CrypSA development follows a **proof-first approach**: + +1. implement the minimal runtime loop +2. verify canonical event flow +3. prove deterministic replay +4. validate reconciliation behavior +5. expand system scope incrementally + +👉 A full system should only be built after the minimal runtime has been proven. + +👉 The goal is to validate the architecture through working systems, not speculative design. --- @@ -30,10 +80,13 @@ They must not be treated as: * architecture definitions Implementation must not treat derived state or local simulation as authoritative. + Canonical event history remains the sole source of truth. Examples and code patterns are illustrative and must not be treated as normative or complete implementations. +Implementation choices must not redefine or reinterpret CrypSA behavior. + --- ## Source of Truth @@ -54,10 +107,12 @@ CrypSA separates documentation responsibilities across three layers: * **Architecture** → what the system is * **Spec** → how the system behaves -* **Implementation** → how the system is built +* **Implementation** → how the system is built and proven This folder exists only in the **implementation layer**. +👉 Implementation must prove architecture and strictly conform to the spec. + Implementation must never override, reinterpret, or bypass behavior defined in the spec. --- @@ -90,10 +145,10 @@ If implementation patterns become stable and necessary: No behavioral rule should remain only in implementation documentation. -Implementation documents should not become authoritative definitions. +Implementation documents must not become authoritative definitions. --- ## One Sentence Summary -This folder provides practical guidance for building CrypSA systems, while authoritative behavior and structure are defined in the specification and architecture layers. +This folder provides practical guidance for proving and building CrypSA systems, while authoritative behavior and structure are defined in the specification and architecture layers. diff --git a/implementation/minimal_validator/CrypSA_Minimal_Validator_Folder_structure.md b/implementation/minimal_validator/CrypSA_Minimal_Validator_Folder_structure.md index 8fd2009..173482a 100644 --- a/implementation/minimal_validator/CrypSA_Minimal_Validator_Folder_structure.md +++ b/implementation/minimal_validator/CrypSA_Minimal_Validator_Folder_structure.md @@ -1,8 +1,22 @@ # CrypSA Minimal Validator Folder Structure +--- + +## ⚠️ Implementation Guidance (Non-Authoritative) + +This document provides one possible file and module structure for a CrypSA minimal validator. + +👉 This structure is not required, but is designed to maintain clear architectural boundaries. + +👉 CrypSA defines invariants and behavior through the `/spec` directory. + +👉 Alternative structures may be used, as long as CrypSA invariants are preserved. + +--- + ## Purpose -This document defines a clean file and module structure for building **CrypSA Minimal Validator v0.1**. +This document provides a clean file and module structure for building **CrypSA Minimal Validator v0.1**. Its goal is to make the minimal validator: @@ -29,11 +43,11 @@ The minimal validator should reflect the same core runtime boundaries that exist * observer/session coordination * replay and snapshots -The file structure should reinforce those boundaries. +The file structure is intended to reinforce those boundaries. --- -## Recommended Top-Level Structure +## Recommended Top-Level Structure (Example) ```text minimal-validator/ @@ -140,7 +154,7 @@ These files handle communication with observers. ### `src/transport/websocket-server.ts` -Responsible for: +May handle: * accepting observer connections * receiving inbound messages @@ -166,7 +180,7 @@ This keeps message contracts explicit. ### `src/transport/session-manager.ts` -Responsible for: +Typically responsible for: * tracking connected observers * storing last known `server_sequence` @@ -212,7 +226,7 @@ Examples: ### `src/events/event-intake.ts` -Responsible for: +May Handle: * parsing incoming event messages * checking required fields exist @@ -224,7 +238,7 @@ This is intake preparation, not full validation. ### `src/events/event-idempotency.ts` -Responsible for: +May Handle: * tracking processed `event_id`s * preventing duplicate canonicalization @@ -318,7 +332,7 @@ Examples: ### `src/validation/conflict-scope-resolver.ts` -Responsible for: +Typically responsible for: * identifying affected conflict scope * locking or isolating validation context @@ -336,7 +350,7 @@ These files maintain canonical truth. ### `src/history/canonical-event-history.ts` -Responsible for: +May handle: * appending canonical events * reading ordered history @@ -359,7 +373,7 @@ Keep sequence assignment explicit and isolated. ### `src/history/event-store.ts` -Responsible for: +Typically responsible for: * writing canonical events to storage * reading persisted canonical events from disk @@ -404,7 +418,7 @@ Keep read logic separate from mutation logic. ### `src/state/state-apply-event.ts` -Responsible for: +May handle: * applying one canonical event to derived canonical state * ensuring deterministic state transitions @@ -433,7 +447,7 @@ These files reconstruct derived state from canonical history. ### `src/replay/replay-engine.ts` -Responsible for: +Typically responsible for: * reconstructing derived state from history * replaying events in `server_sequence` order @@ -472,7 +486,7 @@ Examples: ### `src/snapshots/snapshot-store.ts` -Responsible for: +Typically responsible for: * reading and writing snapshots * managing snapshot file storage @@ -481,7 +495,7 @@ Responsible for: ### `src/snapshots/snapshot-generator.ts` -Responsible for: +May handle: * creating snapshots from current derived canonical state * tagging them with `server_sequence` @@ -648,9 +662,9 @@ Prove: --- -## Minimal Build Order +## Example Build Order -If you want to implement this incrementally: +If you want to implement this incrementally, one possible sequence is: 1. `candidate-event-types.ts` 2. `canonical-event-types.ts` diff --git a/implementation/minimal_validator/CrypSA_Minimal_Validator_v0.1.md b/implementation/minimal_validator/CrypSA_Minimal_Validator_v0.1.md index 7bcfc46..b0f0b4a 100644 --- a/implementation/minimal_validator/CrypSA_Minimal_Validator_v0.1.md +++ b/implementation/minimal_validator/CrypSA_Minimal_Validator_v0.1.md @@ -1,13 +1,13 @@ # CrypSA Minimal Validator v0.1 -> Scope note: This document describes implementation strategy for a minimal validator proof step. +> This document outlines the smallest practical standalone validator for proving the CrypSA runtime model. > For authoritative runtime behavior, refer to `../spec/`. --- ## Purpose -This document defines the smallest practical standalone validator that can prove CrypSA’s core runtime model. +This document describes the smallest practical standalone validator that can prove CrypSA’s core runtime model. The goal is not production readiness. @@ -17,7 +17,7 @@ The goal is to prove that CrypSA functions as a real runtime system with: * candidate event submission * validation * canonical event history -* canonical update distribution +* canonical event distribution * observer reconciliation support This validator is a **technical proof step** between the teaching prototype and a full runtime system. @@ -76,7 +76,7 @@ The minimal validator supports multiple deployment configurations **without chan flowchart LR A[Observer] --> B[Local Validator] -B --> C[Canonical Event History] +B --> C[canonical event history] C --> A ``` @@ -87,7 +87,7 @@ In this configuration: * canonical event history is maintained locally * no network is required -> This is the **recommended starting point for all implementations**. +> This is a recommended starting point for implementations --- @@ -99,8 +99,8 @@ flowchart LR A[Observer] -->|Candidate Event| B[Network] B --> C[Validator] -C --> D[Canonical Event History] -D -->|Canonical Update| B +C --> D[canonical event history] +D -->|canonical event| B B --> A ``` @@ -133,8 +133,8 @@ Create a validator that: * listens for candidate events ```text -Canonical Event History = [] -Derived State = initial +canonical event history = [] +derived canonical state = initial ``` --- @@ -143,7 +143,7 @@ Derived State = initial Create an observer that: -* reconstructs state +* reconstructs derived canonical state * can submit candidate events * optionally runs in the same process @@ -170,35 +170,36 @@ Example: --- -### Step 4 — Validate and Accept +### Step 4 — Validation and Decision -Validator: +The validator evaluates the candidate event: -* checks schema -* verifies identity -* checks preconditions -* enforces invariants +* schema validation +* identity validation +* precondition validation +* invariant validation +* rule validation -If valid: +Decision: -* assigns `canonical_sequence = 1` -* appends to canonical event history +* If accepted, an event becomes canonical and is appended to canonical event history +* If rejected, the event does not become canonical and does not enter canonical event history --- ### Step 5 — Broadcast and Reconcile -Validator sends canonical event. +The validator broadcasts the canonical event. -Observer: +Observers: -* replays event -* updates derived state -* clears prediction +* replay canonical events +* update derived canonical state +* reconcile local prediction ```text -Canonical Event History = [event_1] -Derived State = updated +canonical event history = [event_1] +derived canonical state = updated ``` --- @@ -224,13 +225,13 @@ If this loop works: ## 1. Goals -The minimal validator must prove: +The minimal validator should demonstrate: 1. observers submit candidate events 2. validator validates events 3. events are accepted or rejected -4. accepted events become canonical -5. derived state updates via replay +4. If accepted, an event becomes canonical and is appended to canonical event history +5. derived canonical state updates via replay 6. observers reconcile correctly 7. reconnect works via snapshot + event tail @@ -261,12 +262,12 @@ Observer Action → Candidate Event → Invariant Boundary → Validation -→ Accept or Reject +→ Decision +→ If accepted, an event becomes canonical and is appended to canonical event history → Assign canonical_sequence -→ Append to Canonical Event History +→ Broadcast canonical event → Replay -→ Notify Observers -→ Reconciliation +→ Observer Reconciliation ``` --- @@ -285,7 +286,7 @@ The validator does **not**: * predict outcomes * manage UI or experience -> The validator controls truth, not simulation. +> The validator controls truth, not simulation. Derived canonical state is reconstructed via replay. --- @@ -304,12 +305,12 @@ Start extremely small: ## 6. Minimal Components -### Transport Layer +### Submission and Distribution Layer Handles: * receiving candidate events -* sending results +* sending validation results * broadcasting canonical events (Local-first: this can be in-process) @@ -350,7 +351,7 @@ Handles: --- -### Derived State Cache +### Derived Canonical State Cache * materialized state * updated via replay @@ -373,51 +374,49 @@ Handles: --- -## 7. Data Flow Examples +## 7. Minimal Data Structures -### Submission +### Candidate Event -```json -{ - "type": "candidate_event", - "event": { ... } -} -``` +* `event_id` +* `event_type` +* `actor_id` +* `target_ids` +* `payload` +* `precondition_refs` +* optional `observer_time` --- -### Acceptance +### Canonical Event -```json -{ - "type": "event_result", - "result": "accepted", - "canonical_sequence": 14 -} -``` +* candidate event fields +* `canonical_event_id` +* `canonical_sequence` +* `accepted_at` --- -### Rejection +### Canonical Event History -```json -{ - "type": "event_result", - "result": "rejected", - "reason": "conflict_lost" -} -``` +* append-only ordered sequence of canonical events +* authoritative source of truth --- -### Canonical Update +### Derived Canonical State -```json -{ - "type": "canonical_event", - "event": { ... } -} -``` +* reconstructed via replay +* not authoritative +* used for validation and queries + +--- + +### Validation Result + +* accepted or rejected +* optional rejection reason +* canonical metadata if accepted --- @@ -428,9 +427,9 @@ Handles: If a duplicate `event_id` is received: -* the validator must return the original result (accepted or rejected) -* no new canonical event must be created -* canonical_sequence must not change +* return the original result (accepted or rejected) +* do not create a new canonical event +* do not modify canonical event history --- @@ -438,8 +437,8 @@ If a duplicate `event_id` is received: Within a conflict scope: -* validate + accept atomically -* reject conflicting events +* validation and decision must be atomic +* conflicting events must not both become canonical --- @@ -448,20 +447,20 @@ Within a conflict scope: Minimal approach: * append-only event log -* in-memory derived state +* in-memory derived canonical state * periodic snapshots --- ## 11. Success Criteria -The validator is complete when: +The validator can be considered complete when: * runs independently * supports multiple observers * validates correctly -* maintains canonical history -* updates derived state +* appends canonical events in canonical_sequence order +* updates derived canonical state via replay * supports reconnect * enforces idempotency @@ -472,7 +471,7 @@ The validator is complete when: 1. validator process 2. event intake 3. canonical event history -4. derived state +4. derived canonical state 5. validation 6. broadcast 7. reconnect @@ -493,4 +492,4 @@ This validator proves: ## One Sentence Summary -CrypSA Minimal Validator v0.1 is the smallest complete implementation of the validator role, proving that validated events—ordered by canonical_sequence—form canonical event history and drive shared reality through deterministic replay. +CrypSA Minimal Validator v0.1 is the smallest complete implementation of the validator role, proving that if accepted, an event becomes canonical and is appended to canonical event history, and shared reality is reconstructed via deterministic replay. diff --git a/implementation/minimal_validator/CrypSA_Validator_Runtime_Flow.md b/implementation/minimal_validator/CrypSA_Validator_Runtime_Flow.md index 94fd191..b340d6e 100644 --- a/implementation/minimal_validator/CrypSA_Validator_Runtime_Flow.md +++ b/implementation/minimal_validator/CrypSA_Validator_Runtime_Flow.md @@ -2,7 +2,7 @@ ## Purpose -This document defines the **runtime execution flow** of a CrypSA validator. +This document describes the runtime execution flow. It shows how a candidate event moves through the system: @@ -23,7 +23,7 @@ This is an implementation-oriented document that connects: > The validator is the only authority that may modify canonical event history. -All canonical changes must: +In CrypSA, canonical changes follow this pattern: * originate from a candidate event * cross the invariant boundary @@ -45,7 +45,7 @@ Candidate Event Submitted ├── No → Rejection Result → Observer Correction └── Yes → Assign canonical_sequence - → Append to Canonical Event History + → Append to canonical event history → Apply to Derived Canonical State → Broadcast Canonical Event → Observers Reconcile @@ -144,7 +144,7 @@ Schema → Identity → Preconditions → Invariants → Rules ### Validation Requirements -Validation must be: +Validation should be: * deterministic * based on canonical context @@ -206,7 +206,7 @@ Steps: The canonical event is appended to the canonical event history. -Requirements: +Expected characteristics: * append-only * strictly ordered by canonical_sequence @@ -277,7 +277,7 @@ Observers must: ## Idempotency Guarantee -The validator must ensure: +The validator is expected to ensure: > the same event_id never produces multiple canonical events @@ -291,7 +291,7 @@ This prevents: ## Determinism Guarantee -The system must ensure: +The system is expected to ensure: ```text same canonical event history → same derived canonical state diff --git a/implementation/minimal_validator/CrypSA_Validator_Runtime_Invariants.md b/implementation/minimal_validator/CrypSA_Validator_Runtime_Invariants.md index cd6bc1b..f006b9e 100644 --- a/implementation/minimal_validator/CrypSA_Validator_Runtime_Invariants.md +++ b/implementation/minimal_validator/CrypSA_Validator_Runtime_Invariants.md @@ -1,8 +1,20 @@ # Validator Runtime Invariants +--- + +## ⚠️ Implementation Guidance (Non-Authoritative) + +This document outlines runtime invariants that a CrypSA validator implementation is expected to preserve. + +👉 These invariants reflect architectural requirements but are not authoritative definitions of system behavior. + +👉 For authoritative definitions, refer to the `/spec` directory. + +--- + ## Purpose -This document defines the runtime invariants that must always hold inside **CrypSA Minimal Validator v0.1**. +This document outlines the runtime invariants that are expected to hold inside **CrypSA Minimal Validator v0.1**. These are not gameplay invariants. diff --git a/implementation/minimal_validator/CrypSA_Validator_Runtime_Test_Plan.md b/implementation/minimal_validator/CrypSA_Validator_Runtime_Test_Plan.md index e374af2..a7160c2 100644 --- a/implementation/minimal_validator/CrypSA_Validator_Runtime_Test_Plan.md +++ b/implementation/minimal_validator/CrypSA_Validator_Runtime_Test_Plan.md @@ -1,8 +1,22 @@ # Validator Runtime Test Plan +--- + +## ⚠️ Implementation Guidance (Non-Authoritative) + +This document outlines a testing strategy for a CrypSA validator implementation. + +👉 These tests are not authoritative definitions of system behavior, and must not be treated as such. + +👉 They are derived from runtime invariants and are intended to help validate correctness. + +👉 For authoritative definitions of behavior, refer to the `/spec` directory. + +--- + ## Purpose -This document defines the test strategy for **CrypSA Minimal Validator v0.1**. +This document outlines the test strategy for **CrypSA Minimal Validator v0.1**. It ensures the validator implementation: @@ -22,7 +36,7 @@ It is a **runtime correctness test plan**, directly derived from: ## Core Principle -> Tests must protect the architecture, not just the behavior. +> Tests protect the architecture, not just the behavior. A validator that "works" but violates invariants is incorrect. @@ -30,7 +44,7 @@ A validator that "works" but violates invariants is incorrect. ## Test Categories -The validator must be tested across the following categories: +The validator should be tested across the following categories: 1. Validation correctness 2. Canonical event history correctness diff --git a/spec/CrypSA_Consistency_Model.md b/spec/CrypSA_Consistency_Model.md index d041646..a561ae2 100644 --- a/spec/CrypSA_Consistency_Model.md +++ b/spec/CrypSA_Consistency_Model.md @@ -8,6 +8,10 @@ Consistency determines: * how conflicts are resolved * how observers converge on shared truth +For a conceptual overview of how consistency emerges within the system runtime, see: + +→ ../architecture/CrypSA_Runtime_Model.md + --- ## Core Principle @@ -16,14 +20,14 @@ 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. +Observers may temporarily diverge, but must eventually converge on the same canonical event history. --- -> 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. --- @@ -32,13 +36,13 @@ Observers may temporarily diverge, but must eventually converge on the same cano CrypSA provides: -* **Canonical Consistency** - All observers agree on accepted canonical events +* **Canonical Consistency** + All observers agree on canonical events -* **Replay Consistency** - Given the same canonical event history, all observers derive the same state +* **Replay Consistency** + Given the same canonical event history and the same interpretation logic, observers derive equivalent derived canonical state -* **Eventual Convergence** +* **Eventual Convergence** Temporary divergence is allowed, but must resolve CrypSA does **not guarantee**: @@ -51,13 +55,19 @@ CrypSA does **not guarantee**: ## Consistency Model -CrypSA uses a hybrid consistency model: +This model operates within the runtime described in: + +→ ../architecture/CrypSA_Runtime_Model.md + +CrypSA uses validator-defined canonical consistency with observer-local flexibility. + +--- ### 1. Event-Level Authority * The validator is authoritative over event acceptance * All candidate events must cross the invariant boundary before becoming canonical -* Only accepted events become canonical and are appended to canonical event history +* If accepted, an event becomes canonical and is appended to canonical event history * Canonical event history is the source of truth --- @@ -66,13 +76,13 @@ CrypSA uses a hybrid consistency model: * Observers simulate locally * Observers may temporarily diverge -* Observers reconcile when canonical updates are received +* Observers reconcile when canonical events are received --- ### 3. Eventual Convergence -* All observers converge once canonical history is aligned +* All observers converge once canonical event history is aligned * Divergence is temporary and expected --- @@ -91,7 +101,7 @@ This ordering is: * defined by the validator * used for replay and reconstruction -> `canonical_sequence` is assigned by the validator and defines canonical ordering. +> `canonical_sequence` defines a total canonical order across canonical events. --- @@ -104,7 +114,17 @@ Implementations may reason about events within scopes such as: However: -> canonical ordering remains defined by validator-assigned `canonical_sequence` +> canonical ordering remains defined by validator-assigned `canonical_sequence`. + +--- + +## Replay Relationship + +Consistency is maintained by: + +* aligning canonical event history +* replaying canonical events in `canonical_sequence` order +* reconstructing equivalent derived canonical state --- @@ -123,7 +143,8 @@ The validator resolves conflicts during validation: * events are evaluated atomically within the relevant conflict scope * only valid outcomes can become canonical -* rejected events do not enter canonical event history +* If accepted, an event becomes canonical and is appended to canonical event history +* rejected events do not become canonical and do not enter canonical event history --- @@ -135,7 +156,7 @@ Given: * the same candidate event * the same validation rules -The result must be: +the result must be: > identical (accept or reject) given identical inputs @@ -191,12 +212,12 @@ These are implementation strategies, not core consistency requirements. ## Observer Reconciliation -Observers reconcile when: +Observers reconcile as part of the runtime model by: -* canonical events differ from local prediction -* rejected events invalidate local assumptions +* applying canonical events from canonical event history in `canonical_sequence` order +* updating derived canonical state via replay -Reconciliation may involve: +Reconciliation may also involve: * correcting local state * re-running simulation @@ -206,7 +227,7 @@ Reconciliation may involve: ## Snapshot Consistency -Snapshots represent derived state at a specific `canonical_sequence`. +Snapshots represent derived canonical state at a specific `canonical_sequence`. To remain consistent: @@ -235,6 +256,11 @@ The system must handle: * conflicting submissions * incomplete observer history (missing canonical events) +Observers must recover consistency by: + +* obtaining missing canonical events +* replaying canonical event history + Consistency must still converge under these conditions. --- @@ -270,11 +296,11 @@ CrypSA consistency is: * canonically ordered * eventually convergent -> Observers may disagree temporarily, +> Observers may disagree temporarily, > but canonical event history ensures they eventually agree. --- ## One Sentence Summary -CrypSA ensures consistency through validator-controlled event acceptance, canonical ordering, and deterministic replay, allowing temporary divergence while guaranteeing eventual convergence. +CrypSA ensures consistency through validator-controlled event acceptance, canonical ordering, and deterministic replay, allowing temporary divergence while guaranteeing eventual convergence on equivalent derived canonical state. diff --git a/spec/CrypSA_Event_Model.md b/spec/CrypSA_Event_Model.md index 0baabd8..dd314bf 100644 --- a/spec/CrypSA_Event_Model.md +++ b/spec/CrypSA_Event_Model.md @@ -4,7 +4,11 @@ This document defines the structure, behavior, and lifecycle of events in CrypSA Events are the foundation of the system. -> Canonical event history is the source of truth. +For a conceptual overview of how events flow through the system, see: + +→ ../architecture/CrypSA_Runtime_Model.md + +> 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,12 +19,9 @@ CrypSA is event-driven. * the world 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. +* 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. +Canonical state is not stored. Only canonical event history is authoritative. --- @@ -39,41 +40,65 @@ CrypSA defines two primary event types: ### 2. Canonical Events -* accepted by the validator +* If accepted, an event becomes canonical and is appended to canonical event history * immutable -* part of canonical event history -* used for replay and reconstruction +* assigned validator-defined canonical metadata + +--- + +## Event State Model + +An event may exist in one of the following states: + +### Candidate + +* proposed by an observer +* not yet validated +* not canonical + +--- + +### Rejected + +* evaluated by the validator +* does not become canonical +* does not enter canonical event history + +--- + +### Canonical + +* If accepted, an event becomes canonical and is appended to canonical event history --- ## Event Lifecycle +This lifecycle is part of the runtime model described in: + +→ ../architecture/CrypSA_Runtime_Model.md + Every event follows this lifecycle: 1. **Creation** - Observer creates a candidate event + An observer creates a candidate event 2. **Submission** - Event is submitted to the validator + The candidate event is submitted to the validator 3. **Validation** - The validator evaluates the event + The validator evaluates the candidate event 4. **Decision** - * accepted → proceeds to canonicalization - * rejected → does not become canonical and does not enter canonical event history - -5. **Canonicalization** - - * canonical metadata assigned * If accepted, an event becomes canonical and is appended to canonical event history + * If rejected, the event does not become canonical and does not enter canonical event history -6. **Propagation** - Observers receive the canonical event +5. **Propagation** + Observers receive the canonical event as part of the runtime model -7. **Replay** - Observers update state via replay +6. **Replay** + Observers reconstruct derived canonical state via canonical event replay in canonical_sequence order --- @@ -125,7 +150,7 @@ Examples: * event-specific data * must be deterministic -* must contain all data required for deterministic replay +* must contain all data required to produce equivalent derived canonical state via replay Example: @@ -134,7 +159,7 @@ Example: "position": [10, 5], "object_kind": "house" } -``` +```` --- @@ -170,15 +195,17 @@ When an event is accepted, the validator assigns: #### `canonical_event_id` * unique identifier for the canonical event +* identifies the canonical event record after acceptance --- #### `canonical_sequence` * authoritative ordering index +* assigned by the validator * defines replay order -> `canonical_sequence` is assigned by the validator and defines canonical ordering. +> `canonical_sequence` defines a total canonical order across canonical events. --- @@ -190,12 +217,9 @@ When an event is accepted, the validator assigns: ## Canonical Event Definition -A canonical event is an accepted candidate event that: +A **canonical event** is an event that has become canonical through validation. -* has passed validation -* has been assigned `canonical_sequence` -* has been appended to canonical event history by the validator -* is immutable +If accepted, an event becomes canonical and is appended to canonical event history. --- @@ -210,7 +234,7 @@ Canonical events must satisfy: canonical event history is never rewritten * **deterministic replay** - same history → same state + given the same canonical event history and interpretation logic, replay produces equivalent derived canonical state --- @@ -254,6 +278,8 @@ This ensures: Candidate events only become canonical through validation. +> If accepted, an event becomes canonical and is appended to canonical event history. + Validation ensures: * invariants are preserved @@ -276,6 +302,8 @@ The invariant boundary defines: * the transition from local simulation * to canonical validation +Only events that pass validation cross this boundary and become canonical. + Actions that do not cross this boundary: * remain local @@ -289,7 +317,7 @@ CrypSA events: * represent all canonical changes * are validated before acceptance -* are appended to canonical event history +* If accepted, an event becomes canonical and is appended to canonical event history * canonical event history is the source of truth * are replayed to reconstruct state diff --git a/spec/CrypSA_Replay_Model.md b/spec/CrypSA_Replay_Model.md index bb2c125..49f4c88 100644 --- a/spec/CrypSA_Replay_Model.md +++ b/spec/CrypSA_Replay_Model.md @@ -14,13 +14,23 @@ Replay is the mechanism that turns: 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. Derived canonical state is reconstructed by replaying canonical event history. --- +## Replay Authority + +Replay is authoritative for derived canonical state. + +All derived canonical state must be produced via replay from canonical event history. + +Any optimization must produce results equivalent to replay. + +--- + ## Replay Overview Replay is the process of: @@ -38,8 +48,7 @@ Replay requires: * canonical event history * authoritative ordering defined by `canonical_sequence` * event payloads -* invariant rules defined by the validation model -* object definitions (genomes and canonical mint events) +* interpretation logic used to derive canonical state --- @@ -47,6 +56,8 @@ Replay requires: Replay can begin from: +--- + ### 1. Genesis * empty or initial derived canonical state @@ -65,6 +76,8 @@ Replay can begin from: Replay order is defined by: +--- + ### Canonical Ordering * events must be applied strictly in `canonical_sequence` order @@ -72,7 +85,7 @@ Replay order is defined by: * this ordering is authoritative * all observers must use the same ordering -> `canonical_sequence` is assigned by the validator and defines canonical ordering. +> `canonical_sequence` defines a total canonical order across canonical events. --- @@ -83,7 +96,7 @@ Each canonical event modifies derived canonical state according to: * its `event_type` * its `payload` * the current derived canonical state -* invariant rules defined by the validation model +* interpretation logic --- @@ -103,9 +116,10 @@ Event application must only affect: ## Determinism Requirements -Replay must produce identical results given the same inputs. +Replay must produce equivalent derived canonical state given the same: -This requires: +* canonical event history +* interpretation logic --- @@ -130,7 +144,7 @@ Avoid: ### 3. Stable Definitions -* genomes must be versioned or frozen +* object definitions must be versioned or frozen * historical events must resolve against correct definitions --- @@ -165,18 +179,6 @@ Idempotency ensures robustness in: --- -## Partial Replay - -Replay does not always require full history. - -Possible strategies: - -* replay from last snapshot -* replay a subset of events -* replay per partition or object - ---- - ## Replay Scope Replay can occur at different levels: @@ -185,26 +187,36 @@ Replay can occur at different levels: * region replay * object-specific replay -This depends on system design. +Replay scope does not change correctness requirements. + +All scoped replay must produce results equivalent to full replay for the same canonical event history subset. --- -## Observer Reconciliation +## Partial Replay -Observers use replay to reconcile: +Replay does not always require full history. -* local predictions vs canonical state -* rejected candidate events -* late-arriving canonical events +Possible strategies: + +* replay from last snapshot +* replay a subset of events +* replay per partition or object --- -### Reconciliation Process +## Observer Reconciliation -1. receive canonical event -2. compare with local state -3. correct divergence -4. continue simulation +Observers reconcile by: + +* applying canonical events from canonical event history in `canonical_sequence` order +* updating derived canonical state via replay + +Reconciliation may also involve: + +* correcting local state +* re-running simulation +* discarding invalid predictions --- @@ -214,7 +226,7 @@ Divergence occurs when: * local simulation differs from canonical outcome * events are rejected -* canonical updates arrive after local prediction +* canonical events arrive after local prediction Replay ensures: @@ -241,7 +253,7 @@ Snapshots improve replay performance. Replay must handle: * evolving event schemas -* changing object definitions (genomes) +* changing object definitions --- @@ -262,6 +274,11 @@ Replay systems must handle: * inconsistent ordering * partial snapshots +Recovery from failure requires: + +* restoring canonical event history +* replaying canonical events to reconstruct derived canonical state + --- ## Performance Considerations @@ -282,6 +299,14 @@ Replay cost depends on: --- +### Correctness Requirement + +All replay optimizations must preserve correctness. + +Optimized replay must produce results equivalent to full replay from canonical event history. + +--- + ## Security Considerations Replay assumes: @@ -307,8 +332,8 @@ CrypSA replay is: It ensures that: -> given the same canonical event history, -> all observers derive the same derived canonical state +> given the same canonical event history and the same interpretation logic, +> all observers derive equivalent derived canonical state --- diff --git a/spec/CrypSA_Runtime_Spec_v0.1.md b/spec/CrypSA_Runtime_Spec_v0.1.md index 26bf431..a35f5ac 100644 --- a/spec/CrypSA_Runtime_Spec_v0.1.md +++ b/spec/CrypSA_Runtime_Spec_v0.1.md @@ -36,7 +36,7 @@ This v0.1 runtime spec covers: * validation of candidate events * event acceptance and rejection * canonical event recording -* canonical update distribution +* canonical event distribution * observer reconciliation * snapshot-assisted reconstruction @@ -71,8 +71,8 @@ A process that: * receives candidate events * validates them * enforces invariants -* records accepted canonical events -* distributes canonical updates +* records canonical events +* distributes canonical events The validator does **not**: @@ -128,7 +128,7 @@ They do **not define truth**. ## 3. Core Runtime Principle -> 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. An observer action does **not directly modify canonical event history**. @@ -139,13 +139,12 @@ Instead: Local Action → Candidate Event → Validation -→ Accept or Reject -→ Canonical Event Appended to Canonical Event History +→ Decision +→ If accepted, an event becomes canonical and is appended to canonical event history +→ Replay → Observer Reconciliation ``` -Only accepted events become canonical. - --- ### 3.1 Invariant Boundary @@ -281,11 +280,9 @@ CrypSA v0.1 uses: ### 6.1 Canonical Order * validator assigns `canonical_sequence` -* `canonical_sequence` defines authoritative ordering +* `canonical_sequence` defines a total canonical order across canonical events * observer order is not authoritative -> `canonical_sequence` is the canonical ordering assigned by the validator. - --- ### 6.2 Conflict Scope @@ -337,16 +334,22 @@ E -->|Fail| R4[Reject: invariant_violation] E -->|Pass| F[Rule Validation] F -->|Fail| R5[Reject: rule_violation] -F -->|Pass| G[Accept Event] +F -->|Pass| G[Decision] -G --> H[Canonical Event History Update] +G -->|Accepted| H[Canonical Event History Append] +G -->|Rejected| R6[Rejection Result] ``` --- ### 7.1 Determinism Requirement -All accepted events must produce deterministic results. +Given the same: + +* canonical event history +* interpretation logic + +replay must produce equivalent derived canonical state. --- @@ -354,15 +357,17 @@ All accepted events must produce deterministic results. ### Accepted -* event recorded -* derived canonical state updated via deterministic replay of canonical events -* observer notified +* If accepted, an event becomes canonical and is appended to canonical event history +* `canonical_sequence` is assigned +* canonical events are replayed to update derived canonical state +* observers are notified --- ### Rejected -* no canonical change +* the event does not become canonical +* the event does not enter canonical event history * rejection returned * observer reconciles @@ -400,12 +405,15 @@ Each event includes: ### 9.1 Canonical Event Definition -A canonical event is an accepted candidate event that: +A canonical event is an event that has become canonical through validation. + +> If accepted, an event becomes canonical and is appended to canonical event history. + +Canonical events: -* has passed validation -* has been assigned `canonical_sequence` -* has been appended to canonical event history -* is immutable +* have assigned `canonical_sequence` +* are immutable +* define truth --- @@ -413,9 +421,8 @@ A canonical event is an accepted candidate event that: After a canonical event is appended: -* the event must be applied to derived canonical state -* the application must follow deterministic rules defined by the event type -* the result must match replay behavior +* the event must be applied to derived canonical state via replay +* the result must match deterministic replay behavior This ensures consistency between: @@ -440,8 +447,8 @@ Derived canonical state must be a deterministic function of canonical event hist At any time, it must be possible to: -* discard derived state -* reconstruct it solely from canonical event history +* discard derived canonical state +* reconstruct it solely from canonical event history via replay --- @@ -462,11 +469,16 @@ At any time, it must be possible to: ## 12. Observer Reconciliation -Observers must: +Observers reconcile by: + +* applying canonical events from canonical event history in `canonical_sequence` order +* updating derived canonical state via replay + +They may also: -* detect accepted/rejected events * correct local state -* rebuild derived canonical state from canonical event history +* re-run simulation +* discard invalid predictions --- @@ -475,8 +487,11 @@ Observers must: System must handle: * delays + * out-of-order delivery + * retries + * duplicates * ordering must be enforced by `canonical_sequence`, not network delivery @@ -535,10 +550,11 @@ CrypSA runtime: * observers simulate locally * validator validates events * canonical event history defines truth +* replay reconstructs state * observers reconcile --- ## One Sentence Summary -CrypSA Runtime v0.1 defines how observer actions become validated canonical events and how derived canonical state emerges from canonical event history. +CrypSA Runtime v0.1 defines how observer actions become validated canonical events and how derived canonical state is reconstructed via deterministic replay from canonical event history. diff --git a/spec/CrypSA_Validation_Model.md b/spec/CrypSA_Validation_Model.md index 6de17ae..01e1236 100644 --- a/spec/CrypSA_Validation_Model.md +++ b/spec/CrypSA_Validation_Model.md @@ -8,49 +8,69 @@ Validation is the mechanism that: * enforces invariants * determines what becomes canonical +For a conceptual overview of how validation fits into the system runtime, see: + +→ ../architecture/CrypSA_Runtime_Model.md + --- ## Core Principle In CrypSA: -> Observers may simulate freely, but only validated events become canonical and are appended to canonical event history +> Observers may simulate freely, but only accepted 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. +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. +> 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. --- +## Validator Inputs + +Validation operates on: + +* the candidate event +* canonical event history (or context derived from it) +* invariant rules and validation logic + +Validation must not depend on: + +* observer-local state +* non-canonical external state + +--- + ## Validation Flow +This flow is part of the runtime model described in: + +→ ../architecture/CrypSA_Runtime_Model.md + The validation pipeline follows this sequence: -1. **Observer Action** - Local simulation only +1. **Observer Action** + Local simulation only -2. **Candidate Creation** - Action becomes a candidate event +2. **Candidate Creation** + Action becomes a candidate event -3. **Submission** - Event is sent to the validator +3. **Submission** + Event is sent to the validator -4. **Validation** - Validator evaluates the event +4. **Validation** + The validator evaluates the candidate event against invariants and rules 5. **Decision** - * accepted → becomes a canonical event - * rejected → discarded - -6. **Canonical Update** - Accepted events are assigned `canonical_sequence` and appended to canonical event history + * If accepted, an event becomes canonical and is appended to canonical event history + * If rejected, the event does not become canonical and does not enter canonical event history -7. **Observer Reconciliation** - Observers update local state based on canonical events +6. **Observer Reconciliation** + Observers update local state based on canonical events as part of the runtime model --- @@ -66,9 +86,9 @@ Ensures the event is well-formed. Checks include: -* required fields present -* valid structure -* correct data types +* required fields present +* valid structure +* correct data types --- @@ -78,21 +98,21 @@ Ensures referenced identities are valid. Checks include: -* actor exists -* target objects exist -* identities are valid at event time +* actor exists +* target objects exist +* identities are valid at event time --- ### 3. Precondition Validation -Ensures observers assumptions are still valid. +Ensures observer assumptions are still valid. Checks include: -* expected state matches derived canonical state -* required resources exist -* required conditions hold +* expected state matches derived canonical state +* required resources exist +* required conditions hold --- @@ -102,9 +122,9 @@ Ensures canonical rules are not violated. Examples: -* no duplicate ownership -* valid placement -* valid state transitions +* no duplicate ownership +* valid placement +* valid state transitions --- @@ -114,9 +134,9 @@ Ensures event-specific rules are satisfied. Examples: -* upgrade paths -* allowed interactions -* resource costs +* upgrade paths +* allowed interactions +* resource costs --- @@ -128,17 +148,33 @@ These are not required for v0.1 runtime behavior. #### Simulation Validation (Optional) -* verifies plausibility of proposed outcome -* does not define canonical outcome -* may re-simulate critical actions +* verifies plausibility of proposed outcome +* does not define canonical outcome +* may re-simulate critical actions --- #### Pattern / Anomaly Validation (Optional) -* evaluates behavior over time -* detects suspicious or invalid patterns -* does not directly determine canonical acceptance +* evaluates behavior over time +* detects suspicious or invalid patterns +* does not directly determine canonical acceptance + +--- + +## Acceptance Criteria + +A candidate event is accepted only if: + +* it passes all validation layers +* no invariants are violated +* all preconditions hold +* all rules are satisfied + +If any validation step fails: + +* the event is rejected +* the event does not become canonical --- @@ -146,9 +182,18 @@ These are not required for v0.1 runtime behavior. Validation must be: -* deterministic -* atomic within the relevant conflict scope -* based on canonical event history and derived canonical state +* atomic within the relevant conflict scope +* based on canonical event history and derived canonical state + +Validation must be deterministic. + +Given the same: + +* candidate event +* canonical event history (or equivalent derived context) +* validation rules + +the validator must produce the same result. --- @@ -160,22 +205,21 @@ Each candidate results in: ### Accepted -* event is valid -* assigned `canonical_sequence` -* appended to canonical event history -* becomes part of canonical event history +If accepted, an event becomes canonical and is appended to canonical event history. + +* assigned `canonical_sequence` --- ### Rejected -* event violates rules -* no canonical change +* the event does not become canonical +* the event does not enter canonical event history Optional: -* rejection reason returned -* rejection logged +* rejection reason returned +* rejection logged --- @@ -194,20 +238,20 @@ Optional: Invariants define: -* what must always be true -* what cannot be violated +* what must always be true +* what cannot be violated Examples: -* an object has one location -* ownership is unique -* transitions follow valid paths +* an object has one location +* ownership is unique +* transitions follow valid paths Strong invariant design ensures: -* consistency -* correctness -* security +* consistency +* correctness +* security --- @@ -229,9 +273,9 @@ Examples: CrypSA reduces validator load by: -* avoiding full simulation -* validating only boundary-crossing actions -* applying deeper validation selectively +* avoiding full simulation +* validating only boundary-crossing actions +* applying deeper validation selectively --- @@ -241,12 +285,12 @@ CrypSA does not trust observer simulation. It trusts: -> the validation process that determines what becomes canonical +> the validation process that determines what becomes canonical Observers may propose any action, but: -* invalid actions are rejected -* only accepted events affect canonical event history +* invalid actions are rejected +* only accepted events become canonical and are appended to canonical event history --- @@ -254,15 +298,21 @@ Observers may propose any action, but: Validation must handle: -* duplicate submissions -* delayed submissions -* conflicting actions -* incomplete context +* duplicate submissions +* delayed submissions +* conflicting actions +* incomplete context + +Validation outcomes must remain consistent regardless of: + +* submission timing +* message ordering +* network conditions Strategies include: -* idempotency checks -* conflict resolution +* idempotency checks +* conflict resolution * ordering rules based on `canonical_sequence` --- @@ -273,9 +323,9 @@ Validation determines what enters canonical event history. Once accepted: -* events are immutable -* history is append-only -* state is derived via replay +* events are immutable +* history is append-only +* state is derived via replay --- @@ -283,12 +333,12 @@ Once accepted: CrypSA validation is: -* layered -* deterministic -* rule-driven -* authoritative at the invariant boundary +* layered +* deterministic +* rule-driven +* authoritative at the invariant boundary It ensures: -> observers may act freely, +> observers may act freely, > only validated actions become canonical and are appended to canonical event history