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