From 1e90cdc72e9f9537c7aa075c9cdef06e0cc5ebc4 Mon Sep 17 00:00:00 2001
From: godofthunder101 <godofthunder101@hotmail.com>
Date: Thu, 9 Apr 2026 10:37:59 +1000
Subject: [PATCH 1/6] Add CrypSA Invariants and Design Space documentation

This document outlines the invariants and design space for CrypSA, detailing its core principles, what it is and is not, and the responsibilities of implementers.
---
 .../CrypSA_Invariants_and_Design_Space.md     | 328 ++++++++++++++++++
 1 file changed, 328 insertions(+)
 create mode 100644 architecture/CrypSA_Invariants_and_Design_Space.md

diff --git a/architecture/CrypSA_Invariants_and_Design_Space.md b/architecture/CrypSA_Invariants_and_Design_Space.md
new file mode 100644
index 0000000..fe9023d
--- /dev/null
+++ b/architecture/CrypSA_Invariants_and_Design_Space.md
@@ -0,0 +1,328 @@
+# CrypSA — Invariants and Design Space
+
+## Purpose
+
+This document defines:
+
+- 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  
+👉 not a single rigid system design
+
+---
+
+## Core Principle
+
+👉 CrypSA defines **what must be true**,  
+👉 but does not prescribe **how every system must be built**
+
+---
+
+## What 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
+
+---
+
+## What CrypSA Is Not
+
+CrypSA is **not**:
+
+- a fixed client-server architecture
+- a required networking topology
+- a single implementation pattern
+- a one-size-fits-all runtime design
+
+---
+
+# Invariants (Non-Negotiable)
+
+The following are **fundamental to CrypSA**.
+
+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
+- Only the validator determines whether an event becomes canonical
+
+👉 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
+- It defines the shared reality of the system
+
+---
+
+## 3. If Accepted, an Event Becomes Canonical and Is Appended to Canonical Event History
+
+- Events are proposed as candidates
+- If accepted:
+  - they are assigned canonical sequence
+  - they are appended to canonical event history
+
+---
+
+## 4. 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
+
+👉 State is not authoritative
+
+---
+
+## 5. All Shared Reality Changes Cross the Invariant Boundary
+
+- Any change that affects shared reality must:
+  - be represented as a candidate event
+  - pass through validation
+  - be accepted to become canonical
+
+---
+
+## 6. Observers Are Non-Authoritative
+
+Observers:
+
+- may simulate locally
+- may predict outcomes
+- may propose candidate events
+
+But:
+
+👉 observers do not define canonical truth
+
+---
+
+## 7. Replay Is a First-Class Capability
+
+- Systems must be able to reconstruct derived state from canonical event history
+- Replay is not optional
+- Snapshots are optimizations, not truth
+
+---
+
+# Design Space (Product-Dependent)
+
+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.
+
+---
+
+## Key Principle
+
+👉 CrypSA defines that these concerns exist  
+👉 but does not define a single correct solution
+
+---
+
+## 1. Validator Deployment
+
+Options include:
+
+- local validator (single-player / offline / fallback)
+- remote validator (shared systems)
+- hybrid models
+
+CrypSA defines the role of the validator, not its location.
+
+---
+
+## 2. Reconciliation Strategy
+
+Systems may choose:
+
+- full replay-based reconciliation
+- partial rollback
+- state patching
+- hybrid approaches
+
+CrypSA requires consistency with canonical history,  
+but does not enforce how reconciliation is implemented.
+
+---
+
+## 3. Prediction Model
+
+Observers may:
+
+- aggressively predict outcomes
+- minimally predict
+- avoid prediction entirely
+
+Tradeoff:
+
+- responsiveness vs correction frequency
+
+---
+
+## 4. Observer Simulation Depth
+
+Observer-side systems may include:
+
+- full local simulation
+- partial simulation
+- presentation-only layers
+
+CrypSA defines that observer simulation is non-authoritative,  
+but does not define its depth.
+
+---
+
+## 5. Snapshot Strategy
+
+Snapshots may vary in:
+
+- frequency
+- granularity
+- storage model
+
+Snapshots are:
+
+- derived artifacts
+- performance optimizations
+- never authoritative
+
+---
+
+## 6. Partitioning Strategy
+
+Systems may choose:
+
+- no partitioning
+- spatial partitioning
+- logical/domain partitioning
+- hybrid models
+
+CrypSA defines conflict scope,  
+but not how partitions are implemented.
+
+---
+
+## 7. Transport Layer
+
+CrypSA is transport-agnostic, but requires:
+
+- reliable delivery of canonical events
+- correct ordering of canonical events
+- replay-safe communication
+
+The transport implementation is product-dependent.
+
+---
+
+## 8. Security Model
+
+Systems may choose:
+
+- strict validation
+- lightweight validation with monitoring
+- trust-weighted systems
+- hybrid approaches
+
+CrypSA enforces that:
+
+👉 only accepted events become canonical
+
+but does not enforce a single validation strictness model.
+
+---
+
+# Design Axes (Structured Tradeoffs)
+
+These axes help implementers reason about choices.
+
+---
+
+## Validation Strictness
+
+- strict validation ↔ permissive validation
+
+---
+
+## Reconciliation
+
+- heavy replay ↔ lightweight correction
+
+---
+
+## Prediction
+
+- aggressive prediction ↔ minimal prediction
+
+---
+
+## State Reconstruction
+
+- replay-heavy ↔ snapshot-heavy
+
+---
+
+## Deployment
+
+- local-first ↔ remote-authority systems
+
+---
+
+## Partitioning
+
+- fine-grained ↔ coarse-grained
+
+---
+
+## Security
+
+- high-trust ↔ zero-trust systems
+
+---
+
+# Implementation Responsibility
+
+Implementers are responsible for:
+
+- selecting appropriate strategies within this design space
+- ensuring chosen strategies do not violate CrypSA invariants
+- balancing performance, responsiveness, and correctness
+
+---
+
+# Summary
+
+CrypSA provides:
+
+- 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
+
+---
+
+## Final Statement
+
+👉 CrypSA is a framework for structuring systems around canonical validation and replayable truth.
+
+👉 It defines invariants, not implementations.
+
+👉 Systems built with CrypSA are expected to make product-driven decisions within this structure.

From 7dd363b1e24e69163986616b32ca7e3f97cc7868 Mon Sep 17 00:00:00 2001
From: godofthunder101 <godofthunder101@hotmail.com>
Date: Thu, 9 Apr 2026 11:15:17 +1000
Subject: [PATCH 2/6] Revise README for clarity on CrypSA architecture

Updated the README to clarify the definitions and roles within CrypSA, including changes to the structure and terminology. Added sections on what CrypSA is and is not, along with core rules and design space.
---
 README.md | 83 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 61 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 5ca547f..efa2992 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,14 @@
 # CrypSA — Cryptid Server Architecture
 
-CrypSA is an event-driven architecture for building persistent digital worlds.
+CrypSA defines how systems agree on truth through validated canonical events.
+
+It is an event-driven architecture for building persistent digital worlds.
+
+Rather than synchronizing full world state, CrypSA synchronizes validated canonical events under invariant rules.
 
-Rather than synchronizing full world state, CrypSA synchronizes **validated canonical events under invariant rules**.
+All canonical changes pass through the invariant boundary, where system invariants are enforced.
 
-Observers simulate locally. The validator defines what becomes canonical.
+Observers simulate locally. The validator defines what becomes canonical—and therefore what becomes shared reality.
 
 > Reality is not synchronized — it is agreed upon through validated events.  
 > The validator defines what becomes canonical.  
@@ -37,14 +41,18 @@ CrypSA follows a consistent event lifecycle:
 
 This defines the boundary between:
 
-* local simulation  
-* canonical reality  
+* local simulation (non-authoritative)  
+* canonical reality (validator-defined)
+
+Canonical event history is an append-only log that defines the shared reality of the system.
+
+All derived state must be consistent with this history.
 
 ---
 
 ## 🛠 Build CrypSA
 
-Start implementing with the minimal validator:
+Start implementing a CrypSA system with the minimal validator:
 
 👉 implementation/minimal_validator/CrypSA_Minimal_Validator_v0.1.md  
 
@@ -54,9 +62,9 @@ Then follow:
 
 ---
 
-## 🧠 What CrypSA Is
+## 🧠 What CrypSA Is (and Is Not)
 
-CrypSA defines how systems establish canonical truth.
+CrypSA defines how systems establish and maintain canonical truth over time through validated events.
 
 It provides a model where:
 
@@ -66,20 +74,33 @@ It provides a model where:
 
 > Derived canonical state is a projection of canonical event history. It is not the source of truth.
 
-This enables systems that are:
+---
 
-* deterministic  
-* replayable  
-* resistant to desynchronization  
+### ✅ CrypSA Is
 
----
+CrypSA is:
+
+* a structured architecture model  
+* a set of invariants around truth, validation, and canonical event history  
+* a framework for building replayable, consistent systems  
+
+It defines:
 
-## ❌ What CrypSA Is Not
+👉 what must be true for a system to maintain canonical agreement
 
-CrypSA does not replace engines or networking stacks.
+CrypSA is typically integrated alongside existing systems such as game engines, simulation layers, and networking stacks.
 
-It is not:
+Systems built with CrypSA are inherently replayable from canonical event history.
+
+---
 
+### ❌ CrypSA Is NOT
+
+CrypSA is not:
+
+* a fixed networking architecture  
+* a required client-server topology  
+* a one-size-fits-all implementation  
 * a game engine  
 * a networking library  
 * a state replication system  
@@ -89,17 +110,35 @@ It is not:
 
 ---
 
-## 🔒 Core Rules
+### 🧭 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:
 
-The following must always hold:
+* how systems are structured at runtime  
+* how networking is implemented  
+* how reconciliation and prediction are handled  
+* how systems are shaped to meet product goals  
 
-* Only the validator may modify canonical event history  
-* All canonical changes must pass validation  
-* All candidate events must cross the invariant boundary  
-* Observers may simulate freely, but never define truth  
+👉 CrypSA defines invariants and structure, not a single implementation.
+
+👉 CrypSA provides a structured design space for making these decisions.
+
+👉 Implementers are expected to choose these based on product requirements.
 
 ---
 
+### 📘 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
+
 ## ⚙️ How CrypSA Works
 
 ```mermaid

From 41ce1e9f55ef9c6a00aa2acc7e12b95e149cd9a8 Mon Sep 17 00:00:00 2001
From: godofthunder101 <godofthunder101@hotmail.com>
Date: Thu, 9 Apr 2026 11:38:42 +1000
Subject: [PATCH 3/6] Add navigation section to README

Added navigation instructions for the repository.
---
 README.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/README.md b/README.md
index efa2992..37765af 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,14 @@ If you're new to CrypSA, follow this path:
 
 ---
 
+## 📘 How to Navigate This Repo
+
+If you want to understand how to navigate CrypSA based on your goal and role:
+
+👉 docs/How_To_Read_CrypSA.md
+
+---
+
 ## ⚙️ System Model (At a Glance)
 
 CrypSA follows a consistent event lifecycle:

From b189e4c1d3cc1987d90372c7810f07cfb271d0e1 Mon Sep 17 00:00:00 2001
From: godofthunder101 <godofthunder101@hotmail.com>
Date: Thu, 9 Apr 2026 11:57:47 +1000
Subject: [PATCH 4/6] Update CrypSA Observer Model documentation

---
 architecture/CrypSA_Observer_Model.md         | 361 ++++++++++++++++++
 .../CrypSA_Observer_Responsibility_Model.md   | 311 ---------------
 2 files changed, 361 insertions(+), 311 deletions(-)
 create mode 100644 architecture/CrypSA_Observer_Model.md
 delete mode 100644 architecture/CrypSA_Observer_Responsibility_Model.md

diff --git a/architecture/CrypSA_Observer_Model.md b/architecture/CrypSA_Observer_Model.md
new file mode 100644
index 0000000..0d1f8bc
--- /dev/null
+++ b/architecture/CrypSA_Observer_Model.md
@@ -0,0 +1,361 @@
+# CrypSA Observer Model
+
+## Purpose
+
+This document defines the role of the **observer** in a CrypSA system.
+
+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
+
+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**.
+
+---
+
+## Core Principle
+
+In CrypSA, the observer is not a passive renderer.
+
+It is a system that **reconstructs and simulates a view of the universe** defined by canonical event history.
+
+Observers:
+
+* reconstruct derived canonical state locally from canonical event history  
+* simulate world behavior locally (to a degree appropriate for the product)  
+* translate data through adapters  
+* interpret data through lenses  
+* propose candidate events  
+* reconcile with canonical event history  
+
+Observers do not define truth.
+
+---
+
+## Architectural Position
+
+CrypSA separates responsibilities into:
+
+* **Truth** → canonical events and validation  
+* **Translation** → adapters  
+* **Interpretation** → lenses  
+* **Experience** → UI and local simulation  
+
+Observers operate across:
+
+* translation  
+* interpretation  
+* experience  
+
+They do not operate in the truth layer.
+
+---
+
+## Observer-Side Flow
+
+A CrypSA observer operates in the following sequence:
+
+1. reconstruct derived canonical state from canonical event history  
+2. simulate the world locally  
+3. translate data through adapters  
+4. interpret data through lenses  
+5. present the world to the player  
+6. emit candidate events representing intent  
+7. apply local prediction based on those events  
+8. reconcile with canonical event history  
+
+This complements validator-side validation on the truth layer.
+
+---
+
+## Observer Responsibilities
+
+### 1. Canonical State Reconstruction
+
+Observers reconstruct the world from canonical event history.
+
+Examples:
+
+* object existence  
+* ownership  
+* structure placement  
+* inventory contents  
+* progression state  
+
+This produces **derived canonical state** for local use.
+
+---
+
+### 2. Local Simulation
+
+Observers simulate the world locally using derived canonical state as a foundation.
+
+Examples:
+
+* movement  
+* physics  
+* combat  
+* AI behavior  
+* environmental interaction  
+
+This enables responsiveness without requiring validator-side simulation.
+
+---
+
+### 3. Translation (Adapters)
+
+Observers use adapters to shape runtime and canonical data into stable, consumable forms.
+
+Adapters:
+
+* reshape data  
+* preserve meaning  
+* isolate internal structures  
+
+Adapters do not define truth or interpretation.
+
+---
+
+### 4. Interpretation (Lenses)
+
+Observers interpret data through lenses.
+
+Lenses assign meaning to translated data.
+
+Different observers may apply different lenses to the same canonical event history.
+
+---
+
+### 5. Event Proposal
+
+Observers generate candidate events from player intent.
+
+These are sent to the validator for validation.
+
+They are not canonical until accepted.
+
+---
+
+### 6. Prediction and Responsiveness
+
+Observers may predict outcomes to maintain responsiveness.
+
+Prediction:
+
+* occurs locally  
+* is provisional  
+* may be corrected  
+
+Prediction never defines canonical truth and must be reconciled against it.
+
+---
+
+### 7. Reconciliation
+
+Observers reconcile local state with canonical event history.
+
+Reconciliation occurs when:
+
+* events are accepted  
+* events are rejected  
+* new canonical events arrive  
+* corrections occur  
+
+The observer must adjust its state to remain consistent with canonical truth.
+
+---
+
+## Observer State Model
+
+Observers may maintain multiple categories of state.
+
+These categories define how observer-side data relates to canonical truth.
+
+---
+
+### Derived Canonical State
+
+State reconstructed from canonical event history.
+
+* must remain consistent with canonical history  
+* forms the authoritative local baseline  
+
+---
+
+### Predicted State
+
+Provisional state based on local prediction.
+
+* improves responsiveness  
+* may be corrected during reconciliation  
+* never authoritative  
+
+---
+
+### Local-Only Runtime State
+
+Runtime state used for simulation support or control.
+
+Examples:
+
+* input buffers  
+* temporary physics values  
+* AI working state  
+
+* never canonical  
+* never shared directly  
+
+---
+
+### Presentation State
+
+Experience-layer state.
+
+Examples:
+
+* UI  
+* animations  
+* visual effects  
+* audio  
+
+* not authoritative  
+* not part of canonical state  
+
+---
+
+### Important
+
+👉 These categories may exist in different forms depending on the product.
+
+👉 CrypSA defines their relationship to canonical truth, not a single implementation pattern.
+
+---
+
+## Observer and Canonical Truth
+
+Observers maintain a local view of the world.
+
+This view is not authoritative and must always yield to canonical event history.
+
+Canonical event history is defined by:
+
+* validated events  
+* validator-enforced invariants  
+
+---
+
+## Observer Autonomy
+
+Observers operate with high autonomy:
+
+* continue during latency  
+* simulate independently  
+* predict outcomes  
+
+However:
+
+👉 autonomy exists only outside canonical authority  
+
+Reconciliation ensures alignment with canonical truth.
+
+---
+
+## Observer Limitations
+
+Observers cannot:
+
+* create canonical event history directly  
+* bypass invariant validation  
+* alter shared state without validator approval  
+
+👉 All canonical changes pass through the invariant boundary, where system invariants are enforced.
+
+---
+
+## Synchronization
+
+Observers synchronize through canonical updates:
+
+* event streams  
+* polling or broadcast  
+* reconciliation cycles  
+* snapshot updates  
+
+On update:
+
+* canonical event history is extended  
+* derived canonical state is updated  
+* adapters reshape data  
+* lenses reinterpret  
+* presentation updates  
+
+---
+
+## Failure and Recovery
+
+If an observer disconnects:
+
+* canonical event history continues  
+
+On reconnect:
+
+* history is replayed  
+* derived canonical state is reconstructed  
+* adapters and lenses rebuild the view  
+
+---
+
+## Required Capabilities
+
+A CrypSA observer must:
+
+1. reconstruct derived canonical state from canonical event history  
+2. simulate locally  
+3. translate data (adapters)  
+4. interpret data (lenses)  
+5. present the world  
+6. emit candidate events  
+7. reconcile with canonical event history  
+
+---
+
+## Validator vs Observer Responsibilities
+
+| Responsibility           | Observer | Validator    |
+| ------------------------ | -------- | ------------ |
+| Canonical reconstruction | Yes      | Not required |
+| Local simulation         | Yes      | Not required |
+| Translation (adapters)   | Yes      | Not required |
+| Interpretation (lenses)  | Yes      | Not required |
+| Event proposal           | Yes      | No           |
+| Event validation         | No       | Yes          |
+| Invariant enforcement    | No       | Yes          |
+| Canonical recording      | No       | Yes          |
+| Rendering                | Yes      | No           |
+| Truth authority          | No       | Yes          |
+
+---
+
+## Summary
+
+Observers reconstruct canonical reality from canonical event history, simulate the world locally, translate and interpret data, and present the experience.
+
+The validator validates events and maintains canonical event history.
+
+Together, this enables a shared universe defined by event history rather than centralized simulation.
+
+---
+
+## Key Idea
+
+A CrypSA observer is not a renderer.
+
+It is a system that reconstructs, simulates, translates, interprets, and experiences a universe defined by canonical event history.
diff --git a/architecture/CrypSA_Observer_Responsibility_Model.md b/architecture/CrypSA_Observer_Responsibility_Model.md
deleted file mode 100644
index 2c816ad..0000000
--- a/architecture/CrypSA_Observer_Responsibility_Model.md
+++ /dev/null
@@ -1,311 +0,0 @@
-# CrypSA Observer Responsibility Model
-
-## Purpose
-
-This document defines the role of the **observer** in a CrypSA system.
-
-Observers are responsible for reconstructing canonical reality, 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
-
-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**.
-
----
-
-## Core Principle
-
-In CrypSA, the observer is not a passive renderer.
-
-It is an **observer-simulator** of the universe.
-
-Observers:
-
-* reconstruct derived canonical state locally from canonical event history
-* simulate world behavior locally
-* translate data through adapters
-* interpret data through lenses
-* propose candidate events
-* reconcile with canonical event history
-
----
-
-## Architectural Position
-
-CrypSA separates responsibilities into:
-
-* **Truth** → canonical events and validation
-* **Translation** → adapters
-* **Interpretation** → lenses
-* **Experience** → UI and local simulation
-
-Observers operate across:
-
-* translation
-* interpretation
-* experience
-
-They do not control truth.
-
----
-
-## Observer-Side Flow
-
-A CrypSA observer operates in the following sequence:
-
-1. reconstruct derived canonical state from canonical event history
-2. simulate the world locally
-3. translate data through adapters
-4. interpret data through lenses
-5. present the world to the player
-6. emit candidate events representing intent
-7. apply local prediction based on those events
-8. reconcile with canonical event history
-
-This complements validator-side validation on the truth layer.
-
----
-
-## Observer Responsibilities
-
-### 1. Canonical State Reconstruction
-
-Observers reconstruct the world from canonical event history.
-
-Examples:
-
-* object existence
-* ownership
-* structure placement
-* inventory contents
-* progression state
-
-This produces derived canonical state for local use.
-
----
-
-### 2. Local Simulation
-
-Observers simulate the world locally using derived canonical state as a foundation.
-
-Examples:
-
-* movement
-* physics
-* combat
-* AI behavior
-* environmental interaction
-
-This enables responsiveness without validator-side simulation.
-
----
-
-### 3. Translation (Adapters)
-
-Observers use adapters to shape runtime and canonical data into stable, consumable forms.
-
-Adapters:
-
-* reshape data
-* preserve meaning
-* isolate internal structures
-
-Adapters do not define truth or interpretation.
-
----
-
-### 4. Interpretation (Lenses)
-
-Observers interpret data through lenses.
-
-Lenses assign meaning to translated data.
-
-Different observers may apply different lenses to the same canonical event history.
-
----
-
-### 5. Event Proposal
-
-Observers generate candidate events from player intent.
-
-These are sent to the validator for validation.
-
-They are not canonical until accepted.
-
----
-
-### 6. Reconciliation
-
-Observers reconcile local simulation with canonical event history.
-
-Reconciliation occurs when:
-
-* events are accepted
-* events are rejected
-* new canonical events arrive
-* corrections occur
-
-The observer adjusts its simulation to remain consistent.
-
----
-
-### 7. Prediction and Responsiveness
-
-Observers may predict outcomes to maintain responsiveness.
-
-Prediction is always secondary to canonical event history.
-
----
-
-## Observer State vs Canonical Event History
-
-Observers maintain a local interpretation of the world.
-
-This is not authoritative.
-
-Canonical event history is defined by:
-
-* validated events
-* validator-enforced invariants
-
-Observer state must always yield to canonical truth.
-
----
-
-## Observer Data Layers
-
-Observers may maintain multiple layers of data:
-
-### Derived Canonical State
-
-Derived from canonical event history.
-
-### Local Simulation State
-
-Runtime-only simulation data.
-
-### Adapter-Shaped Data
-
-Structured, translation-layer outputs.
-
-### Lens-Interpreted Data
-
-Meaningful, observer-specific views.
-
-### Presentation Data
-
-UI, visuals, audio, and effects.
-
----
-
-## Observer Autonomy
-
-Observers operate with high autonomy:
-
-* continue during latency
-* simulate independently
-* predict outcomes
-
-Reconciliation ensures eventual consistency.
-
----
-
-## Observer Limitations
-
-Observers cannot:
-
-* create canonical event history directly
-* bypass invariant validation
-* alter shared state without validator approval
-
-All canonical changes pass through validation.
-
----
-
-## Synchronization
-
-Observers synchronize through canonical updates:
-
-* event streams
-* polling or broadcast
-* reconciliation cycles
-* snapshot updates
-
-On update:
-
-* canonical event history is extended
-* derived canonical state is updated
-* adapters reshape data
-* lenses reinterpret
-* presentation updates
-
----
-
-## Failure and Recovery
-
-If an observer disconnects:
-
-* canonical event history continues
-
-On reconnect:
-
-* history is replayed
-* derived canonical state is reconstructed
-* adapters and lenses rebuild the view
-
----
-
-## Minimal Responsibilities
-
-A CrypSA observer must:
-
-1. reconstruct derived canonical state from canonical event history
-2. simulate locally
-3. translate data (adapters)
-4. interpret data (lenses)
-5. present the world
-6. emit candidate events
-7. reconcile with canonical event history
-
----
-
-## Validator vs Observer Responsibilities
-
-| Responsibility           | Observer | Validator    |
-| ------------------------ | -------- | ------------ |
-| Canonical reconstruction | Yes      | Not required |
-| Local simulation         | Yes      | Not required |
-| Translation (adapters)   | Yes      | Not required |
-| Interpretation (lenses)  | Yes      | Not required |
-| Event proposal           | Yes      | No           |
-| Event validation         | No       | Yes          |
-| Invariant enforcement    | No       | Yes          |
-| Canonical recording      | No       | Yes          |
-| Rendering                | Yes      | No           |
-| Truth authority          | No       | Yes          |
-
----
-
-## Summary
-
-Observers reconstruct canonical reality from canonical event history, simulate the world locally, translate and interpret data, and present the experience.
-
-The validator validates events and maintains canonical event history.
-
-Together, this enables a shared universe defined by event history rather than centralized simulation.
-
----
-
-## Key Idea
-
-A CrypSA observer is not a renderer.
-
-It is a system that reconstructs, simulates, translates, interprets, and experiences a universe defined by canonical event history.

From 9b83176eeda9ce2a350473df6e4c6ea1db2e7f48 Mon Sep 17 00:00:00 2001
From: godofthunder101 <godofthunder101@hotmail.com>
Date: Thu, 9 Apr 2026 12:09:31 +1000
Subject: [PATCH 5/6] Enhance CrypSA Invariant Boundary documentation

Added guarantees section and clarified input evaluation.
---
 architecture/CrypSA_Invariant_Boundary.md | 25 ++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/architecture/CrypSA_Invariant_Boundary.md b/architecture/CrypSA_Invariant_Boundary.md
index a4f13e1..815113b 100644
--- a/architecture/CrypSA_Invariant_Boundary.md
+++ b/architecture/CrypSA_Invariant_Boundary.md
@@ -47,9 +47,10 @@ The **invariant boundary** is the control and validation interface between:
 
 It defines:
 
-* how inputs are evaluated
-* how validation is performed
-* what outputs are produced
+* how inputs are evaluated  
+* how validation is performed  
+* what outputs are produced  
+* how canonical events are created or rejected  
 
 ---
 
@@ -62,6 +63,21 @@ It defines:
 
 ---
 
+## Guarantees
+
+The invariant boundary guarantees:
+
+* **No observer authority leakage**  
+  Observers cannot directly affect canonical event history.
+
+* **Deterministic canonicalization**  
+  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.
+
+---
+
 ## Input
 
 The invariant boundary receives:
@@ -107,6 +123,9 @@ At the invariant boundary, the validator performs:
 * invariant enforcement
 * rule evaluation
 
+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.
 
 ---

From 8208cd0e50183cbf61cf89ccc8bca16d72a2c50f Mon Sep 17 00:00:00 2001
From: godofthunder101 <godofthunder101@hotmail.com>
Date: Thu, 9 Apr 2026 12:20:15 +1000
Subject: [PATCH 6/6] Revise sections on canonical events and derived state

Reorganize sections and clarify definitions regarding canonical events and derived state.
---
 .../CrypSA_Invariants_and_Design_Space.md     | 24 +++++++------------
 1 file changed, 8 insertions(+), 16 deletions(-)

diff --git a/architecture/CrypSA_Invariants_and_Design_Space.md b/architecture/CrypSA_Invariants_and_Design_Space.md
index fe9023d..1e0d9b2 100644
--- a/architecture/CrypSA_Invariants_and_Design_Space.md
+++ b/architecture/CrypSA_Invariants_and_Design_Space.md
@@ -54,7 +54,8 @@ 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
-- Only the validator determines whether an event becomes canonical
+- The validator defines what becomes canonical.
+- If accepted, an event becomes canonical and is appended to canonical event history.
 
 👉 Observers do not define truth
 
@@ -68,16 +69,7 @@ If these are not preserved, the system is no longer a CrypSA system.
 
 ---
 
-## 3. If Accepted, an Event Becomes Canonical and Is Appended to Canonical Event History
-
-- Events are proposed as candidates
-- If accepted:
-  - they are assigned canonical sequence
-  - they are appended to canonical event history
-
----
-
-## 4. Derived State Is Not Truth
+## 3. Derived State Is Not Truth
 
 - All state is derived from canonical event history
 - Derived state is a projection
@@ -87,16 +79,16 @@ If these are not preserved, the system is no longer a CrypSA system.
 
 ---
 
-## 5. All Shared Reality Changes Cross the Invariant Boundary
+## 4. All Shared Reality Changes Cross the Invariant Boundary
 
 - Any change that affects shared reality must:
   - be represented as a candidate event
-  - pass through validation
-  - be accepted to become canonical
+  - pass through the invariant boundary
+  - If accepted, an event becomes canonical and is appended to canonical event history.
 
 ---
 
-## 6. Observers Are Non-Authoritative
+## 5. Observers Are Non-Authoritative
 
 Observers:
 
@@ -110,7 +102,7 @@ But:
 
 ---
 
-## 7. Replay Is a First-Class Capability
+## 6. Replay Is a First-Class Capability
 
 - Systems must be able to reconstruct derived state from canonical event history
 - Replay is not optional