diff --git a/CrypSA_Overview.md b/CrypSA_Overview.md new file mode 100644 index 0000000..5a992fd --- /dev/null +++ b/CrypSA_Overview.md @@ -0,0 +1,257 @@ +# CrypSA β€” Overview + +This document provides a **conceptual explanation** of CrypSA. + +It is intended as the primary reference for understanding: + +* what CrypSA is +* how it works at a high level +* the core ideas behind the architecture + +--- + +## πŸ“œ Authority Level + +This document is **non-authoritative**. + +It explains the system conceptually. + +πŸ‘‰ For authoritative runtime behavior, see: + +* `/spec` + +--- + +## Purpose + +This document exists to: + +* explain CrypSA clearly without implementation detail +* establish the mental model required to understand the system +* provide a single, cohesive explanation of the architecture + +--- + +## What CrypSA Is + +CrypSA is an **architecture model** for systems where: + +πŸ‘‰ **truth is established through validated events** + +Instead of synchronizing state across systems: + +πŸ‘‰ CrypSA synchronizes **validated events that become canonical** + +--- + +## Core Idea + +In traditional systems: + +* state is updated directly +* systems attempt to keep state in sync + +In CrypSA: + +* systems propose **candidate events** +* a validator determines whether those events are accepted +* accepted events become **canonical and are appended to canonical event history** +* all systems derive state from those canonical events + +--- + +## Core Principles + +These principles define how CrypSA establishes and maintains canonical truth. + +--- + +### 1. The Validator Defines Canonical Truth + +The validator is responsible for: + +* accepting or rejecting events +* enforcing validation rules derived from applicable invariants +* determining what becomes canonical + +πŸ‘‰ Truth is not assumedβ€”it is **validated** + +--- + +### 2. Canonical Event History Is the Source of Truth + +Truth is not stored as state. + +It exists only as: + +πŸ‘‰ **an ordered sequence of canonical events** + +This sequence is: + +* append-only +* immutable +* authoritative within the system context + +--- + +### 3. State Is Derived, Not Stored as Truth + +All state in CrypSA is: + +* derived from canonical event history +* reconstructable through replay +* non-authoritative + +State does not define truth under any circumstance. + +Derived canonical state is a projection of canonical event history. It is not the source of truth. + +--- + +### 4. Replay Is Fundamental + +Systems reconstruct state by: + +πŸ‘‰ replaying canonical event history + +This enables: + +* deterministic reconstruction +* debugging and inspection +* consistency across observers + +--- + +### 5. Observers Simulate Locally + +Observers: + +* simulate the system locally +* perform prediction +* provide responsiveness + +But: + +πŸ‘‰ Observers do not define truth + +--- + +### 6. The Invariant Boundary Protects Truth + +All events must pass through: + +πŸ‘‰ the **invariant boundary** + +Where: + +* validation rules derived from applicable invariants are enforced +* invalid events are rejected +* canonical history is protected + +--- + +## High-Level Flow + +At a high level, CrypSA operates like this: + +1. An observer performs a local action +2. The observer creates a candidate event +3. The event is submitted to the validator +4. The validator evaluates the event using validation rules derived from applicable invariants +5. If accepted: + * the event becomes canonical + * it is appended to canonical event history +6. Observers: + * replay the updated history + * reconcile their local state + +--- + +## Key Concepts + +### Validator +Defines canonical truth by validating events. + +--- + +### Observer +Simulates locally and proposes candidate events. + +--- + +### Canonical Event History +The append-only log that defines truth. + +--- + +### Derived Canonical State +The reconstructed system state produced by replay. + +--- + +### Invariants +Rules that define constraints on canonical truth. + +--- + +### Replay +The process of reconstructing state from canonical event history. + +--- + +## What CrypSA Does NOT Define + +CrypSA intentionally does not define: + +* networking model +* client/server structure +* storage strategy +* prediction systems +* reconciliation strategy +* UI or rendering + +πŸ‘‰ These are **implementation decisions** + +--- + +## What CrypSA Defines + +CrypSA defines: + +* how events become canonical +* how truth is established +* how state is derived +* how systems remain consistent through replay and validation + +--- + +## Why CrypSA Exists + +CrypSA is designed to solve problems related to: + +* consistency across distributed systems +* replayability and debugging +* authority and validation +* synchronization complexity + +By shifting from: + +πŸ‘‰ state synchronization +to +πŸ‘‰ **event validation + replay** + +--- + +## Summary + +CrypSA is an architecture where: + +* truth is defined by validated events +* canonical event history is the source of truth +* state is derived through replay +* observers simulate locally +* validation rules derived from applicable invariants protect canonical truth + +And most importantly: + +> Reality is not synchronized β€” it is agreed upon through validated events. diff --git a/CrypSA_Terminology_Primer.md b/CrypSA_Terminology_Primer.md index b15d6ef..ec82fa1 100644 --- a/CrypSA_Terminology_Primer.md +++ b/CrypSA_Terminology_Primer.md @@ -111,7 +111,7 @@ The **validator** is the authority over canonical truth. It: * validates candidate events -* enforces invariants +* enforces validation rules derived from applicable invariants * If accepted, an event becomes canonical and is appended to canonical event history A **server** is a deployment of a validator. @@ -172,7 +172,7 @@ The **validator** determines what becomes canonical. It: * accepts or rejects candidate events -* enforces invariants and rules +* enforces validation rules derived from applicable invariants * maintains canonical event history The validator is a **role**, not a machine. @@ -195,7 +195,7 @@ It separates: * observer-proposed events * canonical truth -Only events that pass validation cross this boundary and become canonical. +Only events that satisfy validation rules derived from applicable invariants cross this boundary and become canonical. --- @@ -288,7 +288,7 @@ Examples: * a player cannot have negative resources * two objects cannot occupy the same exclusive space -Invariants protect canonical truth. +Invariants define constraints on canonical truth. --- @@ -301,13 +301,12 @@ It includes: * schema validation * identity validation * precondition checks -* invariant validation -* rule validation +* validation rules derived from applicable invariants Result: * If accepted, an event becomes canonical and is appended to canonical event history -* If rejected, the event does not become canonical +* If rejected, the event does not become canonical and is not appended to canonical event history --- @@ -417,7 +416,7 @@ It is: ## Replay -**Replay** reconstructs derived canonical state via canonical event replay. +**Replay** reconstructs derived canonical state by applying canonical events from canonical event history in canonical_sequence order. --- diff --git a/README.md b/README.md index 76f40d3..c476235 100644 --- a/README.md +++ b/README.md @@ -1,126 +1,140 @@ -> ⚠️ This repository defines an architecture model. +> ⚠️ 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 establish canonical truth through validated canonical events and deterministic replay. +CrypSA is an architecture for systems where: -In CrypSA: +πŸ‘‰ truth is not synchronized β€” it is agreed upon through validated events -* the validator defines what becomes canonical -* canonical event history is the source of truth -* derived canonical state is reconstructed via replay +Instead of trying to keep state in sync across systems, CrypSA defines a model where: -It is an event-driven architecture for building persistent digital worlds. +* events are proposed +* a validator determines what becomes canonical +* canonical event history becomes the source of truth +* all state is reconstructed through deterministic replay -Rather than synchronizing world state, CrypSA synchronizes validated canonical events governed by invariants. +This enables systems that are: -All canonical changes must cross the invariant boundary, where invariants are enforced before events can become canonical. Observers perform local simulation and predictive behavior. +* consistent without state synchronization +* replayable and debuggable +* resilient to desync and divergence > Reality is not synchronized β€” it is agreed upon through validated events. > Canonical event history is the source of truth. -The validator may run locally or remotely, but its role as the authority of canonical truth does not change. - --- -## πŸ“˜ How to Navigate This Repo +## ⚠️ Why This Exists -If you want to understand how to navigate CrypSA based on your goal and role: +Traditional systems struggle with: -πŸ‘‰ How_To_Read_CrypSA.md +* keeping distributed state in sync +* debugging desynchronization +* defining authoritative truth +* handling conflicting actions -For core terminology: +CrypSA approaches this differently: + +πŸ‘‰ it does not synchronize state +πŸ‘‰ it synchronizes validated events + +This shifts the problem from: -πŸ‘‰ CrypSA_Terminology_Primer.md +state consistency +β†’ event validation + replay + +and removes an entire class of synchronization issues. --- -## πŸš€ Start Here +## 🧠 Overview -If you're new to CrypSA, follow this path in order: +For a full conceptual explanation of CrypSA: -1. 🧭 CrypSA_In_One_Diagram.md β€” see the system at a glance -2. πŸ“˜ CrypSA_In_5_Minutes.md β€” understand the core idea -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 +πŸ‘‰ `./CrypSA_Overview.md` --- -## πŸ— Infrastructure Implications +## πŸš€ Start Here (Required Path) + +If this is your first time reading CrypSA, follow this path: -CrypSA changes how systems distribute: +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 -* computation -* state -* synchronization +--- -Instead of relying on continuous server-side simulation and state synchronization: +πŸ‘‰ **Only after completing the above:** -* observers perform local prediction -* canonical truth is defined by validated events -* state is reconstructed via replay +**These documents assume familiarity with the core model.** -This results in a different distribution of infrastructure responsibilities. +5. πŸ— `architecture/` β€” understand system structure +6. πŸ“œ `/spec` β€” understand authoritative runtime behavior -For a neutral breakdown of these changes, see: +--- -πŸ‘‰ architecture/CrypSA_Infrastructure_Implications.md +⚠️ **Do not start with `/spec` on your first pass.** +CrypSA is concept-driven and requires the mental model first. --- -## βš™οΈ Canonical Event Lifecycle (At a Glance) +## πŸ“˜ Additional Navigation -The canonical event lifecycle is defined by the CrypSA runtime model, which is the authoritative conceptual flow of the system: +For a deeper walkthrough of how to read CrypSA: -πŸ‘‰ architecture/CrypSA_Runtime_Model.md +πŸ‘‰ `How_To_Read_CrypSA.md` -At a high level: +For core terminology: -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 +πŸ‘‰ `CrypSA_Terminology_Primer.md` -This defines the boundary between: +--- -* local simulation (non-authoritative) -* canonical reality (validator-defined) +## 🧭 Reading Modes -Canonical event history is an append-only log. -It is never mutated, only extended through accepted events. +Choose your path based on your goal: -All derived state must be consistent with this history. +--- -Canonical event history is the source of truth. +### First-time reader +Follow the **Start Here (Required Path)** above. --- -## πŸ›  Build CrypSA +### Architecture deep dive +Go to: -Start with the smallest working system: +πŸ‘‰ `architecture/` + +--- -πŸ‘‰ implementation/CrypSA_Minimal_Runtime_Walkthrough.md +### Formal behavior (authoritative) +Go to: -Then explore: +πŸ‘‰ `/spec` -πŸ‘‰ implementation/minimal_validator/CrypSA_Minimal_Validator_v0.1.md -πŸ‘‰ implementation/CrypSA_Local_First_Development_Approach.md +--- + +### Implementation / building +Go to: + +πŸ‘‰ `implementation/` --- ## 🧠 What CrypSA Is (and Is Not) -CrypSA defines how systems establish and maintain canonical truth through validated canonical events. +CrypSA defines how systems establish and maintain canonical truth through validated 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 +* simulation is local, but canonical authority is enforced by the validator using validation rules derived from applicable invariants > Derived canonical state is a projection of canonical event history. It is not the source of truth. @@ -131,17 +145,9 @@ It provides a model where: CrypSA is: * a structured architecture model -* a set of invariants around truth, validation, and canonical event history +* a set of invariants defining constraints on canonical truth * a framework for building replayable and consistent systems -It defines: - -πŸ‘‰ 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. - -Systems built with CrypSA are inherently replayable from canonical event history. - --- ### ❌ CrypSA Is NOT @@ -157,73 +163,58 @@ CrypSA is not: * an ECS framework * a state synchronization model -> CrypSA defines truth agreement, not rendering, transport, or simulation. +> CrypSA defines how systems agree on truth β€” not how they render, transport, or simulate it. --- -### 🧭 What CrypSA Defines vs Leaves Open - -CrypSA defines: - -* how events become canonical -* how truth is established -* how state is derived from canonical event history - -CrypSA intentionally leaves open: - -* how systems are structured at runtime -* how networking is implemented -* how reconciliation and prediction are handled -* how systems are shaped to meet product goals - -πŸ‘‰ CrypSA defines invariants and structure, not a single implementation. +## πŸ›  Build CrypSA -πŸ‘‰ CrypSA provides a structured design space for making these decisions. +Start with the smallest working system: -πŸ‘‰ Implementers are expected to choose these based on product requirements. +πŸ‘‰ `implementation/CrypSA_Minimal_Runtime_Walkthrough.md` -This flexibility is intentional. +Then explore: -CrypSA is designed to support multiple valid implementations that all preserve canonical truth through validation and canonical event history. +πŸ‘‰ `implementation/minimal_validator/CrypSA_Minimal_Validator_v0.1.md` +πŸ‘‰ `implementation/CrypSA_Local_First_Development_Approach.md` --- ## πŸ“˜ Learn More -For a full breakdown of invariants and product-dependent design: +For deeper architectural breakdowns and design space: -πŸ‘‰ architecture/CrypSA_Invariants_and_Design_Space.md +πŸ‘‰ `architecture/CrypSA_Invariants_and_Design_Space.md` +πŸ‘‰ `architecture/CrypSA_Boundary_Definitions.md` -For strict separation of responsibilities: +For system structure: -πŸ‘‰ architecture/CrypSA_Boundary_Definitions.md +πŸ‘‰ `architecture/` --- -## βš™οΈ How CrypSA Works +## βš™οΈ How CrypSA Works (High-Level) ```mermaid flowchart LR -A[Player Action] --> B[Local Prediction] -B --> C[Observer Creates Candidate Event] -C --> D[Submit to Validator] +A[Player Action] --> B[Local Prediction] +B --> C[Observer Creates Candidate Event] +C --> D[Submit to Validator] -D --> E[Validation Pipeline] +D --> E[Validation Pipeline] -E -->|Accepted| F[Canonical Event History] -E -->|Rejected| G[Rejection Result] +E -->|Accepted| F[Canonical Event History] +E -->|Rejected| G[Rejection Result] -F --> H[Replay] -H --> I[Derived Canonical State] -I --> J[Broadcast] +F --> H[Replay] +H --> I[Derived Canonical State] +I --> J[Broadcast] -J --> K[Observer Reconciliation] +J --> K[Observer Reconciliation] G --> K ``` -> If accepted, an event becomes canonical and is appended to canonical event history. - For the full runtime flow, see: -πŸ‘‰ architecture/CrypSA_Runtime_Model.md +πŸ‘‰ `architecture/CrypSA_Runtime_Model.md` diff --git a/architecture/CrypSA_Invariant_Boundary.md b/architecture/CrypSA_Invariant_Boundary.md index c90e6a9..b8a68ba 100644 --- a/architecture/CrypSA_Invariant_Boundary.md +++ b/architecture/CrypSA_Invariant_Boundary.md @@ -4,9 +4,9 @@ This document defines the **invariant boundary** in CrypSA. It formalizes the point at which: -* observer-proposed events -* are evaluated against canonical truth -* and either accepted or rejected +* observer-proposed events +* are evaluated against canonical truth +* and either accepted or rejected This is the **only place where canonical truth may change**. @@ -26,9 +26,9 @@ If there is any conflict, **the spec takes precedence**. The invariant boundary exists to: -* protect canonical truth -* enforce system correctness -* separate observer simulation from authoritative validation +* protect canonical truth +* enforce system correctness +* separate observer simulation from authoritative validation All changes to canonical event history must pass through this boundary. @@ -36,25 +36,26 @@ 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 +- 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 +- 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 +- `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 +- `architecture/CrypSA_Invariant_Types.md` β€” invariant categorization and enforcement model --- @@ -62,9 +63,9 @@ All changes to canonical event history must pass through this boundary. The **invariant boundary** is the control and validation interface between: -* **observers** (which propose candidate events) - and -* the **validator** (which determines canonical truth) +* **observers** (which propose candidate events) + and +* the **validator** (which determines canonical truth) > The invariant boundary is the only entry point through which canonical event history may change. @@ -79,10 +80,10 @@ It defines: ## Boundary Rules -1. Observers may **propose**, but never define truth -2. The validator is the **only authority** over canonical event history -3. No system component may bypass the invariant boundary -4. All canonical events must originate from successful validation +1. Observers may **propose**, but never define truth +2. The validator is the **only authority** over canonical event history +3. No system component may bypass the invariant boundary +4. All canonical events must originate from successful validation --- @@ -91,13 +92,13 @@ It defines: The invariant boundary guarantees: * **No observer authority leakage** - Observers cannot directly affect canonical event history. + Observers cannot directly affect canonical event history * **Deterministic canonicalization** - Given the same candidate event and canonical context, the validator produces the same result. + Given the same candidate event and canonical context, the validator produces the same result * **Atomic validation within conflict scope** - Each candidate event is evaluated as a single unit of validation and either fully accepted or rejected. + Each candidate event is evaluated as a single unit of validation and either fully accepted or rejected --- @@ -111,10 +112,10 @@ A candidate event represents an attempted change to the system. It must include: -* event type -* required data payload -* referenced identities (if applicable) -* any required metadata +* event type +* required data payload +* referenced identities (if applicable) +* any required metadata The exact structure is defined in: @@ -128,11 +129,11 @@ Validation requires access to canonical truth. This may include: -* current derived canonical state -* canonical event history (directly or via derived canonical state) -* identity and ownership information +* current derived canonical state +* canonical event history (directly or via derived canonical state) +* identity and ownership information -This context is used to evaluate invariants and rules. +This context is used to evaluate **validation rules derived from applicable invariants**. --- @@ -140,13 +141,12 @@ This context is used to evaluate invariants and rules. At the invariant boundary, the validator performs: -* schema validation -* identity validation -* precondition checks -* invariant enforcement -* rule evaluation +* schema validation +* identity validation +* precondition checks +* validation rules derived from applicable invariants -These stages may be structured differently depending on the implementation, +These stages may be structured differently depending on the implementation, but must produce consistent results for the same input and context. The validator must produce the same outcome given the same input and canonical context. @@ -163,16 +163,16 @@ The invariant boundary produces exactly one of the following outcomes: If validation succeeds: -* the event becomes **canonical** -* it is appended to canonical event history -* it is assigned a **`canonical_sequence`** -* it becomes immutable +* the event becomes **canonical** +* it is appended to canonical event history +* it is assigned a **`canonical_sequence`** +* it becomes immutable #### Result ```text Accepted(candidate_event) β†’ canonical_event -``` +```` --- @@ -298,7 +298,7 @@ However: The invariant boundary is the point where: * candidate events are evaluated -* invariants are enforced +* validation rules derived from applicable invariants are enforced * canonical truth is determined It ensures that: diff --git a/architecture/CrypSA_Invariant_Types.md b/architecture/CrypSA_Invariant_Types.md new file mode 100644 index 0000000..6f1772f --- /dev/null +++ b/architecture/CrypSA_Invariant_Types.md @@ -0,0 +1,295 @@ +# CrypSA β€” Invariant Types + +This document defines the categories of **invariants** in CrypSA. + +It clarifies: + +* what invariants are +* how they are used +* how different types of invariants relate to each other +* where invariants apply within CrypSA + +--- + +## πŸ“œ Authority Level + +This document is part of `/architecture`. + +It defines the **structure and categorization** of invariants. + +πŸ‘‰ It does not define specific validation rules. + +For authoritative runtime behavior, see: + +* `/spec` + +--- + +## Purpose + +This document exists to: + +* prevent ambiguity around the term β€œinvariant” +* distinguish different types of invariants +* clarify validator responsibility +* support consistent system design + +--- + +## What Is an Invariant + +An invariant is a rule that must hold for an event to become canonical. + +In CrypSA: + +πŸ‘‰ invariants define what is **allowed to become truth** + +They are enforced at the **invariant boundary** during validation. + +--- + +## Core Principle + +> Invariants do not describe the system β€” they constrain what can become canonical. + +Invariants operate exclusively at the invariant boundary. + +--- + +## Invariant Categories + +CrypSA defines two primary categories of invariants: + +1. Architectural Invariants +2. System Invariants + +These invariants are enforced through validation rules. + +--- + +## 1. Architectural Invariants + +Architectural invariants are required for CrypSA to function. + +They define the fundamental structure of the system. + +--- + +### Examples + +* canonical event history is append-only +* the validator defines what becomes canonical +* state is derived from canonical event history +* replay must produce consistent results + +--- + +### Properties + +* required across all CrypSA systems +* non-negotiable +* define the architecture itself + +--- + +### Role + +Architectural invariants ensure: + +* consistency of the model +* correctness of truth definition +* integrity of replay and validation + +--- + +## 2. System Invariants + +System invariants define rules specific to a particular system or product. + +They describe what is valid within that system. + +--- + +### Examples + +* a player cannot move through walls +* inventory cannot exceed capacity +* an entity must exist before it can be modified + +--- + +### Properties + +* defined by the system designer +* vary between implementations +* enforced during validation + +--- + +### Role + +System invariants ensure: + +* correctness of system behavior +* consistency of domain rules +* validity of state transitions + +--- + +## 3. Validation Rules (Enforcement Layer) + +Validation rules are the concrete checks applied to candidate events. + +They are the operational enforcement of invariants. + +--- + +### Examples + +* type validation +* range checks +* existence checks +* rule enforcement based on system invariants + +--- + +### Properties + +* executable +* applied during validation +* derived from architectural and system invariants + +--- + +### Role + +Validation rules: + +* determine whether a candidate event is accepted or rejected +* enforce invariants at runtime + +--- + +## Relationship Between Categories + +The invariant system forms a layered structure: + +```text +Architectural Invariants + ↓ +System Invariants + ↓ +Validation Rules (Enforcement) +```` + +--- + +### Explanation + +* Architectural invariants define the structure of the system +* System invariants define the rules of a specific system +* Validation rules enforce those rules in practice + +--- + +## The Invariant Boundary + +All invariants are enforced at: + +πŸ‘‰ the **invariant boundary** + +This is where: + +* candidate events are evaluated +* validation rules are applied +* events are accepted or rejected + +--- + +### Important + +> Only events that satisfy all applicable invariants may become canonical. + +--- + +## Validator Responsibility + +The validator is responsible for: + +* enforcing validation rules +* ensuring invariants are upheld +* determining whether events become canonical + +The validator does not: + +* define architectural invariants +* define system invariants + +πŸ‘‰ It **enforces**, it does not **design** + +--- + +## What Invariants Do NOT Do + +Invariants do not: + +* define how systems are implemented +* define how state is stored +* define networking behavior +* define user experience + +πŸ‘‰ They constrain truth, not implementation + +--- + +## Common Misinterpretations + +--- + +### ❌ β€œEverything is an invariant” + +Incorrect. + +Not all rules belong at the invariant boundary. + +Only rules that affect whether an event can become canonical are invariants. + +--- + +### ❌ β€œInvariants define system behavior” + +Incorrect. + +Invariants constrain valid events. + +They do not define how systems behave outside validation. + +--- + +### ❌ β€œValidation rules are the same as invariants” + +Incorrect. + +Validation rules are: + +πŸ‘‰ the enforcement of invariants + +--- + +## Summary + +CrypSA defines invariants as constraints on canonical truth: + +* architectural invariants define the system structure +* system invariants define domain rules +* validation rules enforce those constraints + +Together, they ensure that: + +* only valid events become canonical +* canonical event history remains consistent +* systems maintain correctness through validation + +And critically: + +> Invariants do not define the system β€” they define what the system will accept as truth. diff --git a/architecture/CrypSA_Invariants_and_Design_Space.md b/architecture/CrypSA_Invariants_and_Design_Space.md index bd2c2ca..f9c5817 100644 --- a/architecture/CrypSA_Invariants_and_Design_Space.md +++ b/architecture/CrypSA_Invariants_and_Design_Space.md @@ -4,53 +4,54 @@ This document defines: -* the **non-negotiable invariants** of CrypSA +* the **non-negotiable architectural 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 -πŸ‘‰ not a single rigid system design +πŸ‘‰ 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 +* CrypSA's non-negotiable architectural 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 +* 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. +This document defines system structure and responsibilities. +It does not define runtime behavior. -πŸ‘‰ The `/spec` directory is the authoritative source of 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 +* `architecture/CrypSA_Invariant_Types.md` β€” invariant categorization and enforcement model +* `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** -πŸ‘‰ but does not prescribe **how every system must be built** +πŸ‘‰ CrypSA defines **what must be true** +πŸ‘‰ but does not prescribe **how every system must be built** --- @@ -58,10 +59,10 @@ It does not define runtime behavior. 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 --- @@ -69,14 +70,14 @@ 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 --- -# Invariants (Non-Negotiable) +# Architectural Invariants (Non-Negotiable) The following are **fundamental to CrypSA**. @@ -86,29 +87,29 @@ 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 and enforces all system invariants -* 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 validation rules derived from applicable invariants +* If accepted, an event becomes canonical and is appended to canonical event history -πŸ‘‰ Observers do not define truth +πŸ‘‰ Observers do not define truth --- ## 2. Canonical Event History Is the Source of Truth -* Canonical event history is the authoritative record of the system -* It is append-only -* Canonical event history is the source of truth +* 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 canonical state is a projection -* Derived canonical state may be reconstructed at any time via replay of canonical event history +* 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 -πŸ‘‰ Derived canonical state is not authoritative +πŸ‘‰ Derived canonical state is not authoritative --- @@ -116,9 +117,11 @@ If these are not preserved, the system is no longer a CrypSA system. * 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 + * be represented as a candidate event + * pass through the invariant boundary + * be evaluated against validation rules derived from applicable invariants + +* If accepted, an event becomes canonical and is appended to canonical event history --- @@ -126,21 +129,21 @@ 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: -πŸ‘‰ observers do not define canonical truth +πŸ‘‰ observers do not define canonical truth --- ## 6. Replay Is a Required Capability -* 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 +* 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 --- @@ -148,10 +151,10 @@ But: Given the same: -* canonical event history -* interpretation logic +* canonical event history +* interpretation logic -replay must produce equivalent derived canonical state +replay must produce equivalent derived canonical state --- @@ -165,10 +168,10 @@ These are not undefined β€” they are **design axes** that must be decided based ## Key Principle -πŸ‘‰ CrypSA defines that these concerns exist -πŸ‘‰ but does not define a single correct solution +πŸ‘‰ 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 +πŸ‘‰ These are not optional concerns β€” they must be addressed, but the solutions are product-dependent --- @@ -176,11 +179,11 @@ These are not undefined β€” they are **design axes** that must be decided based 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 --- @@ -188,13 +191,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 event history, -but does not enforce how reconciliation is implemented +CrypSA requires consistency with canonical event history, +but does not enforce how reconciliation is implemented --- @@ -202,13 +205,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 --- @@ -216,12 +219,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 --- @@ -229,15 +232,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 --- @@ -245,13 +248,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 --- @@ -259,13 +262,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` +πŸ‘‰ ordering must be enforced via `canonical_sequence` -The transport implementation is product-dependent +The transport implementation is product-dependent --- @@ -273,16 +276,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: -πŸ‘‰ If accepted, an event becomes canonical and is appended to canonical event history +πŸ‘‰ 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 --- @@ -294,43 +297,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 --- @@ -338,9 +341,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 architectural invariants +* balancing performance, responsiveness, and correctness --- @@ -348,22 +351,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 and their enforcement model, 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_Runtime_Model.md b/architecture/CrypSA_Runtime_Model.md index 6383e68..274b562 100644 --- a/architecture/CrypSA_Runtime_Model.md +++ b/architecture/CrypSA_Runtime_Model.md @@ -36,16 +36,16 @@ If there is any conflict, the `/spec` takes precedence. 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 +2. The invariant boundary determines whether the action must be represented as a candidate event - 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 +4. The validator evaluates the candidate event using **validation rules derived from applicable 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 + - 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 @@ -66,7 +66,7 @@ B -->|Creates Candidate Event| C["Candidate Event"] C --> D["Submit to Validator"] -D --> E["Validation and Invariant Evaluation"] +D --> E["Validation (Enforcement of Invariants)"] E -->|Rejected| R["Reject β†’ Observers Reconcile Local State with Canonical Event History"] @@ -79,7 +79,7 @@ G --> H["Apply Canonical Events via Deterministic Replay"] H --> I["Observer Reconciliation"] I --> A -``` +```` --- @@ -146,7 +146,7 @@ No other mechanism can modify canonical truth. The validator is responsible for: 1. Receiving candidate events -2. Evaluating events against invariants +2. Evaluating events using **validation rules derived from applicable invariants** 3. Determining acceptance or rejection 4. Assigning `canonical_sequence` (establishing authoritative ordering) 5. Appending accepted events to canonical event history @@ -216,7 +216,7 @@ 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 +* candidate events are validated using **validation rules derived from invariants** * accepted events are appended to canonical event history * canonical event history is replayed to deterministically produce state diff --git a/implementation/CrypSA_Minimal_Runtime_Walkthrough.md b/implementation/CrypSA_Minimal_Runtime_Walkthrough.md index cca519c..d2b3116 100644 --- a/implementation/CrypSA_Minimal_Runtime_Walkthrough.md +++ b/implementation/CrypSA_Minimal_Runtime_Walkthrough.md @@ -82,7 +82,7 @@ A minimal CrypSA runtime should prove this sequence works end-to-end: 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 +5. the validator evaluates whether the candidate event becomes canonical using validation rules derived from applicable invariants 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 @@ -169,7 +169,7 @@ The validator is the authority that determines what becomes canonical. It is responsible for: * receiving candidate events -* validating them against invariants +* evaluating them using validation rules derived from applicable invariants * determining whether the candidate event becomes canonical * assigning `canonical_sequence` * appending accepted events to canonical event history @@ -266,7 +266,7 @@ Observer A performs: claim tile (2,3) ``` -This crosses the invariant boundary. +This crosses the invariant boundary into validation. So a candidate event is created: @@ -282,7 +282,7 @@ So a candidate event is created: ## Validator Evaluation -The validator evaluates the candidate event against invariants: +The validator evaluates the candidate event using validation rules derived from applicable invariants: * structure is valid * actor exists @@ -349,7 +349,7 @@ All observers converge. 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 +5. Validator evaluates using validation rules derived from applicable invariants 6. Canonical event is appended 7. Canonical event is made available 8. Replay derives canonical state diff --git a/implementation/minimal_validator/CrypSA_Minimal_Validator_v0.1.md b/implementation/minimal_validator/CrypSA_Minimal_Validator_v0.1.md index b0f0b4a..502259e 100644 --- a/implementation/minimal_validator/CrypSA_Minimal_Validator_v0.1.md +++ b/implementation/minimal_validator/CrypSA_Minimal_Validator_v0.1.md @@ -50,14 +50,16 @@ This document assumes a **local-first development approach**. You should: -1. run the validator locally -2. prove validation + replay -3. then move to remote deployment later +1. run the validator locally +2. prove validation + replay +3. then move to remote deployment later πŸ‘‰ See: ``` + CrypSA_Local_First_Development_Approach.md + ``` > First prove CrypSA locally. Then move the validator, not the architecture. @@ -81,14 +83,6 @@ B --> C[canonical event history] C --> A ``` -In this configuration: - -* observer and validator run in the same environment -* canonical event history is maintained locally -* no network is required - -> This is a recommended starting point for implementations - --- ### Remote Deployment (Later Stage) @@ -104,12 +98,6 @@ D -->|canonical event| B B --> A ``` -In this configuration: - -* observers communicate with a remote validator -* canonical event history is shared -* transport and latency must be handled - --- ## Key Insight @@ -120,18 +108,10 @@ In this configuration: ## Quick Start β€” Local Validator (5 Steps) -This is the **core proof loop**. - --- ### Step 1 β€” Start Validator -Create a validator that: - -* initializes empty canonical event history -* initializes derived canonical state -* listens for candidate events - ```text canonical event history = [] derived canonical state = initial @@ -141,18 +121,15 @@ derived canonical state = initial ### Step 2 β€” Connect Observer -Create an observer that: +Observer: * reconstructs derived canonical state -* can submit candidate events -* optionally runs in the same process +* submits candidate events --- ### Step 3 β€” Submit Candidate Event -Example: - ```json { "event_id": "evt_001", @@ -172,31 +149,22 @@ Example: ### Step 4 β€” Validation and Decision -The validator evaluates the candidate event: +The validator evaluates the candidate event using **validation rules derived from applicable invariants**: * schema validation * identity validation * precondition validation -* invariant validation -* rule validation +* validation rules derived from applicable invariants Decision: * 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 +* If rejected, the event does not become canonical and is not appended to canonical event history --- ### Step 5 β€” Broadcast and Reconcile -The validator broadcasts the canonical event. - -Observers: - -* replay canonical events -* update derived canonical state -* reconcile local prediction - ```text canonical event history = [event_1] derived canonical state = updated @@ -213,8 +181,6 @@ If this loop works: * replay works * reconciliation works -> This is a complete CrypSA runtime loop. - --- ## Key Insight @@ -239,19 +205,11 @@ The minimal validator should demonstrate: ## 2. Non-Goals -This validator intentionally excludes: - * scalability * anti-cheat * distributed shards -* complex physics -* combat systems -* branch merging -* cryptographic trust +* complex systems * production persistence -* account systems - -> Keep it small and focused. --- @@ -261,7 +219,7 @@ This validator intentionally excludes: Observer Action β†’ Candidate Event β†’ Invariant Boundary -β†’ Validation +β†’ Validation (enforcement via validation rules derived from applicable invariants) β†’ Decision β†’ If accepted, an event becomes canonical and is appended to canonical event history β†’ Assign canonical_sequence @@ -277,16 +235,14 @@ Observer Action The validator: * validates candidate events -* enforces invariants +* enforces validation rules derived from applicable invariants * maintains canonical event history The validator does **not**: * simulate the world * predict outcomes -* manage UI or experience - -> The validator controls truth, not simulation. Derived canonical state is reconstructed via replay. +* manage UI --- @@ -294,52 +250,21 @@ The validator does **not**: Start extremely small: -* one tile grid +* one grid * one player -* structure placement -* one resource -* one conflict case -* one reconnect path +* one action type +* one conflict --- ## 6. Minimal Components -### Submission and Distribution Layer - -Handles: - -* receiving candidate events -* sending validation results -* broadcasting canonical events - -(Local-first: this can be in-process) - ---- - -### Event Intake - -* parse event -* validate structure -* normalize - ---- - ### Validation Pipeline * schema * identity * preconditions -* invariants -* rules - ---- - -### Conflict Resolver - -* define conflict scope -* enforce atomic validation -* reject losing events +* validation rules derived from applicable invariants --- @@ -351,26 +276,10 @@ Handles: --- -### Derived Canonical State Cache - -* materialized state -* updated via replay -* used for validation + queries - ---- - -### Snapshot System - -* capture state at sequence -* support reconnect - ---- - -### Session Manager +### Derived Canonical State -* track observers -* track sequence -* deliver updates +* reconstructed via replay +* not authoritative --- @@ -390,77 +299,46 @@ Handles: ### Canonical Event -* candidate event fields +* candidate fields * `canonical_event_id` * `canonical_sequence` * `accepted_at` --- -### Canonical Event History +## 8. Idempotency Rule -* append-only ordered sequence of canonical events -* authoritative source of truth - ---- - -### Derived Canonical State - -* reconstructed via replay -* not authoritative -* used for validation and queries - ---- - -### Validation Result - -* accepted or rejected -* optional rejection reason -* canonical metadata if accepted - ---- - -## 8. Idempotency Rule (Critical) - -* each `event_id` must be processed exactly once -* duplicates must not create duplicate canonical events - -If a duplicate `event_id` is received: - -* return the original result (accepted or rejected) -* do not create a new canonical event -* do not modify canonical event history +* each `event_id` processed once +* duplicates return original result +* no duplicate canonical events --- ## 9. Atomicity Requirement -Within a conflict scope: +Within conflict scope: -* validation and decision must be atomic -* conflicting events must not both become canonical +* validation must be atomic +* conflicting events cannot both become canonical --- ## 10. Persistence -Minimal approach: - * append-only event log -* in-memory derived canonical state -* periodic snapshots +* in-memory state +* optional snapshots --- ## 11. Success Criteria -The validator can be considered complete when: +The validator is complete when: * runs independently -* supports multiple observers * validates correctly -* appends canonical events in canonical_sequence order -* updates derived canonical state via replay +* appends canonical events +* supports replay * supports reconnect * enforces idempotency @@ -468,14 +346,13 @@ The validator can be considered complete when: ## 12. Development Order -1. validator process -2. event intake -3. canonical event history -4. derived canonical state +1. validator +2. intake +3. history +4. state 5. validation 6. broadcast 7. reconnect -8. conflict testing --- @@ -484,9 +361,9 @@ The validator can be considered complete when: This validator proves: * observers do not define truth -* events must be validated +* validation determines what becomes canonical * canonical event history defines reality -* observers reconstruct via replay +* state is reconstructed via replay --- diff --git a/spec/CrypSA_Event_Model.md b/spec/CrypSA_Event_Model.md index dd314bf..6b7d702 100644 --- a/spec/CrypSA_Event_Model.md +++ b/spec/CrypSA_Event_Model.md @@ -8,7 +8,7 @@ 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. +> 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. --- @@ -17,9 +17,9 @@ For a conceptual overview of how events flow through the system, see: 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 +* 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 Canonical state is not stored. Only canonical event history is authoritative. @@ -31,18 +31,18 @@ CrypSA defines two primary event types: ### 1. Candidate Events -* created by observers -* represent proposed actions -* not part of shared reality -* subject to validation +* created by observers +* represent proposed actions +* not part of shared reality +* subject to validation --- ### 2. Canonical Events -* If accepted, an event becomes canonical and is appended to canonical event history -* immutable -* assigned validator-defined canonical metadata +* If accepted, an event becomes canonical and is appended to canonical event history +* immutable +* assigned validator-defined canonical metadata --- @@ -52,23 +52,23 @@ An event may exist in one of the following states: ### Candidate -* proposed by an observer -* not yet validated -* not canonical +* proposed by an observer +* not yet validated +* not canonical --- ### Rejected -* evaluated by the validator -* does not become canonical -* does not enter canonical event history +* evaluated by the validator +* does not become canonical +* is not appended to canonical event history --- ### Canonical -* If accepted, an event becomes canonical and is appended to canonical event history +* If accepted, an event becomes canonical and is appended to canonical event history --- @@ -80,25 +80,25 @@ This lifecycle is part of the runtime model described in: Every event follows this lifecycle: -1. **Creation** - An observer creates a candidate event +1. **Creation** + An observer creates a candidate event -2. **Submission** - The candidate event is submitted to the validator +2. **Submission** + The candidate event is submitted to the validator -3. **Validation** - The validator evaluates the candidate event +3. **Validation** + The validator evaluates the candidate event using **validation rules derived from applicable invariants** 4. **Decision** - * 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 + * If accepted, an event becomes canonical and is appended to canonical event history + * If rejected, the event does not become canonical and is not appended to canonical event history -5. **Propagation** - Observers receive the canonical event as part of the runtime model +5. **Propagation** + Observers receive the canonical event as part of the runtime model -6. **Replay** - Observers reconstruct derived canonical state via canonical event replay in canonical_sequence order +6. **Replay** + Observers reconstruct derived canonical state via canonical event replay in `canonical_sequence` order --- @@ -106,8 +106,8 @@ Every event follows this lifecycle: CrypSA events consist of two layers: -* candidate event fields -* canonical metadata (added on acceptance) +* candidate event fields +* canonical metadata (added on acceptance) --- @@ -115,42 +115,42 @@ CrypSA events consist of two layers: #### `event_id` -* unique identifier for the candidate event -* used for idempotency -* must uniquely identify the candidate event +* unique identifier for the candidate event +* used for idempotency +* must uniquely identify the candidate event --- #### `event_type` -* defines the action type +* defines the action type Examples: -* `place_object` -* `destroy_object` -* `transfer_item` +* `place_object` +* `destroy_object` +* `transfer_item` --- #### `actor_id` -* the entity performing the action +* the entity performing the action --- #### `target_ids` -* objects affected by the event -* may be empty or contain multiple targets +* objects affected by the event +* may be empty or contain multiple targets --- #### `payload` -* event-specific data -* must be deterministic -* must contain all data required to produce equivalent derived canonical state via replay +* event-specific data +* must be deterministic +* must contain all data required to produce equivalent derived canonical state via replay Example: @@ -159,7 +159,7 @@ Example: "position": [10, 5], "object_kind": "house" } -```` +``` --- @@ -282,13 +282,12 @@ Candidate events only become canonical through validation. Validation ensures: -* invariants are preserved +* validation rules derived from applicable invariants are satisfied * preconditions are satisfied -* rules are enforced Rejected events: -* do not enter canonical event history +* are not appended to canonical event history * must not affect canonical state --- @@ -302,7 +301,7 @@ The invariant boundary defines: * the transition from local simulation * to canonical validation -Only events that pass validation cross this boundary and become canonical. +Only events that satisfy validation rules derived from applicable invariants become canonical. Actions that do not cross this boundary: diff --git a/spec/CrypSA_Validation_Model.md b/spec/CrypSA_Validation_Model.md index 01e1236..1b9fdf1 100644 --- a/spec/CrypSA_Validation_Model.md +++ b/spec/CrypSA_Validation_Model.md @@ -5,7 +5,7 @@ This document defines how CrypSA validates proposed actions before they become p Validation is the mechanism that: * protects canonical event history -* enforces invariants +* enforces invariants through validation rules * determines what becomes canonical For a conceptual overview of how validation fits into the system runtime, see: @@ -24,7 +24,7 @@ Validation occurs at the **invariant boundary**, where proposed actions transiti --- -> 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. --- @@ -35,7 +35,7 @@ Validation operates on: * the candidate event * canonical event history (or context derived from it) -* invariant rules and validation logic +* validation rules derived from applicable invariants Validation must not depend on: @@ -52,25 +52,25 @@ This flow is part of the runtime model described in: 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** - The validator evaluates the candidate event against invariants and rules +4. **Validation** + The validator evaluates the candidate event using **validation rules derived from applicable invariants** 5. **Decision** - * 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 + * 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. **Observer Reconciliation** - Observers update local state based on canonical events as part of the runtime model +6. **Observer Reconciliation** + Observers update local state based on canonical events as part of the runtime model --- @@ -86,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 --- @@ -98,9 +98,9 @@ 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 --- @@ -110,37 +110,33 @@ 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 --- -### 4. Invariant Validation +### 4. Validation Rules (Enforcement Layer) -Ensures canonical rules are not violated. +Validation rules enforce applicable invariants. -Examples: - -* no duplicate ownership -* valid placement -* valid state transitions - ---- +These rules are derived from: -### 5. Rule Validation - -Ensures event-specific rules are satisfied. +* architectural invariants +* system invariants Examples: -* upgrade paths -* allowed interactions -* resource costs +* no duplicate ownership +* valid placement +* valid state transitions +* upgrade paths +* allowed interactions +* resource costs --- -### 6. Optional Validation Layers +### 5. Optional Validation Layers These are not required for v0.1 runtime behavior. @@ -148,17 +144,17 @@ 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 --- @@ -166,15 +162,14 @@ These are not required for v0.1 runtime behavior. A candidate event is accepted only if: -* it passes all validation layers -* no invariants are violated -* all preconditions hold -* all rules are satisfied +* it passes all validation layers +* all validation rules derived from applicable invariants are satisfied +* all preconditions hold If any validation step fails: -* the event is rejected -* the event does not become canonical +* the event is rejected +* the event does not become canonical --- @@ -182,16 +177,16 @@ If any validation step fails: Validation must be: -* 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 +* candidate event +* canonical event history (or equivalent derived context) +* validation rules the validator must produce the same result. @@ -207,51 +202,55 @@ Each candidate results in: If accepted, an event becomes canonical and is appended to canonical event history. -* assigned `canonical_sequence` +* assigned `canonical_sequence` --- ### Rejected -* the event does not become canonical -* the event does not enter canonical event history +* 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 --- ## Rejection Codes (Recommended) -* `invalid_schema` -* `invalid_identity` -* `precondition_failed` -* `invariant_violation` -* `rule_violation` -* `conflict_lost` +* `invalid_schema` +* `invalid_identity` +* `precondition_failed` +* `invariant_violation` +* `rule_violation` +* `conflict_lost` --- -## Invariant Design +## Invariant and Validation Rule Design Invariants define: -* what must always be true -* what cannot be violated +* what must always be true +* what cannot be violated + +Validation rules: + +* enforce those invariants at runtime 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: +Strong design ensures: -* consistency -* correctness -* security +* consistency +* correctness +* security --- @@ -273,9 +272,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 --- @@ -285,12 +284,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 become canonical and are appended to canonical event history +* invalid actions are rejected +* only accepted events become canonical and are appended to canonical event history --- @@ -298,22 +297,22 @@ 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 +* submission timing +* message ordering +* network conditions Strategies include: -* idempotency checks -* conflict resolution -* ordering rules based on `canonical_sequence` +* idempotency checks +* conflict resolution +* ordering rules based on `canonical_sequence` --- @@ -323,9 +322,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 --- @@ -333,12 +332,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