Merge remote-tracking branch 'origin/graph-boaw' into graph-boaw

# Conflicts:
#	README.md

Author: flyingrobots

.ban-nondeterminism-allowlist

@@ -5,3 +5,6 @@ crates/warp-wasm/src/lib.rs
 # This is intentional - WSC is for native tooling, not WASM determinism
 crates/warp-core/src/wsc/mod.rs
 crates/warp-core/src/wsc/view.rs
+# BOAW exec uses std::env for feature-gated stride fallback (ECHO_PARALLEL_STRIDE)
+# This is a build-time debug toggle, not runtime non-determinism
+crates/warp-core/src/boaw/exec.rs

.markdownlint.json

@@ -1,10 +1,12 @@
 {
   "MD013": false,
   "MD033": {
-    "allowed_elements": ["u8", "br", "p", "img"]
+    "allowed_elements": ["u8", "br", "p", "img", "a", "strong", "sub"]
   },
   "MD041": false,
+  "MD045": false,
   "MD046": {
     "style": "fenced"
-  }
+  },
+  "MD060": false
 }

README.md

@@ -3,117 +3,123 @@
 
 <p align="center">
   <img alt="ECHO" src="https://github.com/user-attachments/assets/bef3fab9-cfc7-4601-b246-67ef7416ae75" />
-
 </p>
 
----
-
-Echo is a **deterministic graph‑rewrite engine + tooling** for building simulations you can replay, verify, and synchronize without guessing.
-
-Instead of treating a game/simulation as a pile of mutable objects, Echo treats **state as a typed graph**. Each “tick” proposes a set of rewrites, executes them in a deterministic order, and emits **cryptographic hashes** of the resulting state and provenance so tools/peers can validate and converge.
+<p align="center">
+  <strong>State is a graph. Time is a hash chain. Determinism isn't optional.</strong>
+</p>
 
-## Project Status
+<p align="center">
+  <a href="docs/guide/start-here.md">Get Started</a> •
+  <a href="docs/architecture-outline.md">Architecture</a> •
+  <a href="docs/meta/docs-index.md">Docs</a> •
+  <a href="https://github.com/flyingrobots/aion">AIΩN Framework</a>
+</p>
 
-**Status (2026-01):** Active R&D. The deterministic core (`warp-core`) and session/tooling pipeline are implemented. Higher-level layers (ECS storage, system scheduler, timeline tree) are specced but not yet built. See [`docs/architecture-outline.md`](docs/architecture-outline.md) for per-section implementation status.
+<p align="center">
+    <a href="https://github.com/flyingrobots/echo/actions/workflows/determinism.yml" ><img src="https://github.com/flyingrobots/echo/actions/workflows/determinism.yml/badge.svg" /></a>  
+    <a href="https://github.com/flyingrobots/echo/actions/workflows/ci.yml" ><img src="https://github.com/flyingrobots/echo/actions/workflows/ci.yml/badge.svg" /></a>
+    <img src="https://img.shields.io/badge/platforms-Linux%20%7C%20macOS%20%7C%20Windows-blue" alt="Platforms" />
+</p>
 
-## Buckle Up
+---
 
-Start here:
+## What is Echo?
 
-- Start Here: [`docs/guide/start-here.md`](docs/guide/start-here.md)
-- Non-programmer on-ramp: [`docs/guide/eli5.md`](docs/guide/eli5.md)
-- WARP primer: [`docs/guide/warp-primer.md`](docs/guide/warp-primer.md)
-- Docs map: [`docs/meta/docs-index.md`](docs/meta/docs-index.md)
-- AIΩN bridge doc: [`docs/aion-papers-bridge.md`](docs/aion-papers-bridge.md)
-- Architecture outline: [`docs/architecture-outline.md`](docs/architecture-outline.md)
-- Commit hashing spec: [`docs/spec-merkle-commit.md`](docs/spec-merkle-commit.md)
+Echo is a **deterministic state machine** where every transition is cryptographically verifiable. Run the same inputs on any machine, get the same hashes. Always.
 
-## AIΩN Framework
+```text
+tick 0 ──hash──► tick 1 ──hash──► tick 2 ──hash──► ...
+         │              │              │
+         ▼              ▼              ▼
+      provable       provable       provable
+```
 
-Echo is part of the **AIΩN Framework**:
+No floating-point drift. No unordered iteration surprises. No "it works on my machine." Just math you can trust.
 
-- AIΩN repo: <https://github.com/flyingrobots/aion>
+**Prove it:**
 
-Research lineage (AIΩN Foundations series):
+```text
+$ cargo xtask dind run
+[DIND] Running 50 seeds across 3 platforms...
+[DIND] linux-x64:   7f3a9c...d82e1a ✅
+[DIND] macos-arm64: 7f3a9c...d82e1a ✅
+[DIND] windows-x64: 7f3a9c...d82e1a ✅
 
-- Paper I — *WARP Graphs: A Worldline Algebra for Recursive Provenance* ([doi:10.5281/zenodo.17908005](https://doi.org/10.5281/zenodo.17908005))
-- Paper II — *WARP Graphs: Canonical State Evolution and Deterministic Worldlines* ([doi:10.5281/zenodo.17934512](https://doi.org/10.5281/zenodo.17934512))
-- Paper III — *WARP Graphs: Computational Holography & Provenance Payloads* ([doi:10.5281/zenodo.17963669](https://doi.org/10.5281/zenodo.17963669))
-- Paper IV — *WARP Graphs: Rulial Distance & Observer Geometry* ([doi:10.5281/zenodo.18038297](https://doi.org/10.5281/zenodo.18038297))
-- Paper V — *WARP Graphs: Ethics of Deterministic Replay & Provenance Sovereignty* (not yet published)
-- Paper VI — *The AIΩN Computer: Architecture & Operating System* (not yet published)
+Hashes match. Determinism verified.
+```
 
----
+> **Naming:** Echo is the product. WARP is the underlying graph algebra. The `warp-*` and `echo-*` crates are internal modules—same project, different layers.
 
 ## Why?
 
-- **Determinism first:** same inputs → same ordered rewrites → same hashes.
-- **Provenance you can trust:** snapshots and commits are content‑addressed.
-- **Tooling as a first‑class citizen:** graphs stream over a canonical wire protocol; consumers verify hashes and detect desync early.
-
-If you’re building anything that benefits from “Git‑like” properties for state (replay, branching, inspection, synchronization), Echo is designed for that.
+| Problem                                | Echo's Answer                              |
+| -------------------------------------- | ------------------------------------------ |
+| "Replay diverged after 10,000 ticks"   | Deterministic scheduler + fixed-point math |
+| "Which client has the correct state?"  | Compare 32-byte tick hashes                |
+| "We can't reproduce that bug"          | Every tick is content-addressed and replayable |
+| "Syncing state is expensive"           | Stream diffs, verify hashes, done          |
 
----
+If you've ever built a game, simulation, or distributed system and wished state had Git-like properties—branches, merges, provable history—that's what we're building.
 
-## What It Does Right Now
+## Project Status
 
-### Core engine + math
+> [!WARNING]
+> **Echo is early. Sharp edges.**
+>
+> - ✅ **Stable:** Core determinism, hashing, replay invariants
+> - ⚠️ **Changing:** Schema/IR, APIs, file formats, viewer protocol
+> - ❌ **Not yet:** Nice UX, polished docs, batteries-included examples
+>
+> If you need a plug-and-play game engine today, this isn't that (yet).
+> If you need deterministic, replayable state transitions you can prove, it is.
 
 - `crates/warp-core` — deterministic rewrite engine: canonical scheduling, parallel execution with deterministic results independent of CPU count, snapshot and commit hashing. See [`docs/architecture-outline.md`](docs/architecture-outline.md) for detailed API documentation.
 - `crates/warp-geom` — geometry primitives (currently isolated).
 
-### Session + streaming pipeline
+### Roadmap
 
-- `crates/echo-graph` — canonical renderable graph (`RenderGraph`) + diff ops (`WarpOp`) + deterministic graph hashing.
-- `crates/echo-session-proto` — deterministic JS‑ABI v1.0 framing + canonical CBOR + wire schema.
-- `crates/echo-session-service` — headless Unix‑socket hub:
-  - handshake + monotonic `ts`
-  - subscriptions per `WarpId`
-  - gapless diff enforcement (snapshot resets; diffs must be consecutive epochs)
-- `crates/echo-session-client` — client helpers + tool port abstraction (`tool::SessionPort`).
-- `crates/echo-session-ws-gateway` — WebSocket ↔ Unix‑socket bridge for browser‑based tools.
+Echo is a high-performance graph rewriting engine written in Rust, designed to run everywhere. All upcoming milestones target Echo-in-the-browser so people can try it out with minimal friction.
 
-### Tools + adapters
+1. **WARPSITE**—a website powered by WARP graph rewriting
+2. **Splash Guy**—a demo game designed to introduce Echo concepts
+3. **Tumble Tower**—a demo game designed to demonstrate Echo's physics determinism
 
-- `crates/warp-viewer` — native WGPU viewer:
-  - subscribes to a WARP stream,
-  - applies snapshots/diffs,
-  - verifies `state_hash` per frame (declares desync on mismatch).
-- `crates/echo-app-core` / `crates/echo-config-fs` — “tool hexagon” ports + filesystem config adapter.
-- `crates/warp-ffi` / `crates/warp-wasm` — bindings around `warp-core`.
-- `crates/warp-benches` — Criterion microbenchmarks (scheduler drain, snapshot hash, etc.).
-- `crates/echo-dind-harness` — determinism drill runner (DIND suite; cross‑platform hash verification).
-- `crates/echo-dind-tests` — stable test app used by the DIND harness.
+#### Time Travel Debugger + WARPSITE
 
-### Living specs (teaching slice)
+True, deterministic **Time Travel Debugging** (TTD) is always available by default—not something you have to record or prepare for in advance. Made possible by [WARP graph](https://doi.org/10.5281/zenodo.17908005) [rewriting](https://doi.org/10.5281/zenodo.17963669), each tick's [computational hologram](https://doi.org/10.5281/zenodo.17963669) is captured in an immutable, append-only, tamper-evident ledger. Step backwards to any previous tick, then forward again. Exactly the same every time, bit-for-bit, cryptographically verified. Want to see what *could* have happened? Fork to a different worldline, try something different, then discard it and return to your original timeline.
 
-- `specs/spec-000-rewrite` — Leptos + Trunk scaffold for “Spec‑000: Everything is a Rewrite”.
-- `crates/echo-wasm-abi` — WASM‑friendly DTO schema for specs.
-- `crates/echo-wasm-bindings` — demo kernel + rewrite history (teaching slice; not the production engine).
+- Time Travel Debugging (TTD) Part 1—Tick Inspector + Rewind/Jump to Previous Tick (In Progress)
+- WARPSITE (In Progress)
+- [Wesley](https://github.com/flyingrobots/wesley)—GraphQL-as-schema → Rust/TypeScript Compiler
+- TTD Part 2—Fork Worldlines
 
-For a deeper tour, see [`docs/meta/docs-index.md`](docs/meta/docs-index.md).
+#### Then: Splash Guy Tutorial Demo
 
----
+Navigate a grid-based maze and strategically place timed water balloons to clear obstacles and trap opponents in a chaotic bid to be the last one dry. A simple game demo designed to teach Echo concepts.
 
-## Quickstart
+- Rhai Scripting API
+- Graphics
+- Input
 
-### Requirements
+#### After: Tumble Tower Demo
 
-- Rust toolchain pinned by `rust-toolchain.toml` (currently `1.90.0`).
-- Node.js (for docs site). The docs toolchain uses `vitepress@1.6.4`; supported Node versions are pinned via `package.json` (currently `>=18 <25`). For best results, use an LTS (Node 18/20/22).
+Carefully extract load-bearing blocks from a precarious tower and place them at the summit without triggering a catastrophic collapse. A block-stacking game that demonstrates deterministic physics.
 
-### Common commands
+- Physics Engine
+- Collision Resolution
 
-Install repo hooks:
+## Quick Tour
 
 ```bash
+# Install hooks (formats code, runs clippy, checks docs)
 make hooks
-```
-
-Run the workspace tests:
 
-```bash
+# Run the test suite
 cargo test --workspace
+
+# Run determinism verification
+cargo xtask dind run
 ```
 
 Run `warp-core` with extra delta validation enabled:
@@ -122,80 +128,97 @@ Run `warp-core` with extra delta validation enabled:
 cargo test -p warp-core --features delta_validate
 ```
 
-Run clippy with the repo’s docs gate:
-
 ```bash
-cargo clippy --all-targets -- -D warnings -D missing_docs
-```
-
-Run the docs site (VitePress):
+# Launch the viewer
+cargo run -p warp-viewer
 
-```bash
+# Build the docs site
 make docs
 ```
 
-Directly (useful when debugging):
-
-```bash
-pnpm install
-pnpm docs:dev
+## The Stack
+
+```mermaid
+flowchart TB
+  %% Authoring
+  A["GraphQL Schema<br />(Types + Ops + Docs)"] -->|author + version| B["Wesley<br />(schema compiler)"]
+
+  %% Codegen outputs
+  B --> C["Rust Types + Op IDs<br />(structs/enums, stable IDs)"]
+  B --> D["ABI / Wire Layout<br />(canonical encoding)"]
+  B --> E["Client Stubs<br/>(TS/Rust helpers)"]
+  B --> F["Registry Metadata<br/>(introspection, docs index)"]
+
+  %% App layer
+  C --> G["Game / App Code<br/>(rules + gameplay)"]
+  D --> G
+  F --> G
+
+  %% Runtime
+  G --> H["Echo Core Runtime<br/>(deterministic tick loop)"]
+  H --> I["WARP Graph Engine<br/>(rewrite + commit + hash)"]
+  I --> J["WARP Graph Executable<br/>(content-addressed worldline)"]
+
+  %% Tooling
+  F --> K["Devtools / Viewer<br/>(inspect ops, decode vars)"]
+  I --> K
+  J --> K
 ```
 
-CI-style build (includes link checking):
+**Core** — `crates/warp-core`
 
-```bash
-pnpm docs:build
-```
+- Graph-rewrite engine with transactional commits
+- Deterministic math (fixed-point, PRNG, Vec3/Mat4/Quat)
+- **Materialization bus**—order-independent channel for outputs; emitters don't need to coordinate
+- **WSC** (Write-Streaming Columnar)—zero-copy snapshot format (mmap-friendly) for fast state reload + verification
 
-Run the session hub:
+**Pipeline** — `crates/echo-session-*`
 
-```bash
-cargo run -p echo-session-service
-```
+- Unix socket hub with gapless diff streaming
+- WebSocket gateway for browser tools
+- Canonical CBOR wire format
 
-Run the viewer:
+**Tools** — `crates/warp-viewer`, `crates/echo-dind-*`
 
-```bash
-cargo run -p warp-viewer
-```
+- Native GPU viewer with per-frame hash verification
+- **DIND** (Determinism-in-Determinism)—cross-platform test harness that proves hash convergence
 
-Run Spec‑000 (WASM dev server; requires `trunk` installed):
+## Research Foundation
 
-```bash
-make spec-000-dev
-```
+Echo implements ideas from the **AIΩN Foundations** paper series:
 
-Run DIND (cross-platform determinism verification):
+1. [WARP Graphs: A Worldline Algebra for Recursive Provenance](https://doi.org/10.5281/zenodo.17908005)
+2. [Canonical State Evolution and Deterministic Worldlines](https://doi.org/10.5281/zenodo.17934512)
+3. [Computational Holography & Provenance Payloads](https://doi.org/10.5281/zenodo.17963669)
+4. [Rulial Distance & Observer Geometry](https://doi.org/10.5281/zenodo.18038297)
 
-```bash
-cargo xtask dind run
-```
+Part of the [AIΩN Framework](https://github.com/flyingrobots/aion).
 
----
+## Contributing
 
-## Contributions
+Determinism is sacred. Before you change anything:
 
-- Start with `CONTRIBUTING.md`.
-- Echo is docs-driven: behavior changes should be reflected in specs and ADRs.
-- Determinism is sacred: avoid wall‑clock time, uncontrolled randomness, and unspecified iteration order.
+1. Read [`CONTRIBUTING.md`](CONTRIBUTING.md)
+2. Run `make hooks` to install the guardrails
+3. Write tests. If it's not tested, it's not deterministic.
 
-### Determinism guard scripts
+The codebase enforces:
 
-Echo enforces determinism guardrails via scripts in `scripts/`:
+- No global state (`scripts/ban-globals.sh`)
+- No wall-clock time or uncontrolled randomness (`scripts/ban-nondeterminism.sh`)
+- No unordered iteration (`scripts/ban-unordered-abi.sh`)
 
-- `scripts/ban-globals.sh`
-- `scripts/ban-nondeterminism.sh`
-- `scripts/ban-unordered-abi.sh`
+## Requirements
 
-## Workflows
+- **Rust** — pinned in `rust-toolchain.toml` (currently 1.90.0)
+- **Node.js 18+** — for the docs site (VitePress)
 
-Echo has a few “official workflows” (policy + blessed scripts/entrypoints), documented here:
+## License
 
-- [`docs/workflows.md`](docs/workflows.md) — contributor playbook (PR policy, docs guard, `cargo xtask`, scheduled automations)
-- [`docs/dependency-dags.md`](docs/dependency-dags.md) — issue + milestone dependency DAGs (DOT/SVG) and how to regenerate them
+Dual-licensed under Apache 2.0 and MIND-UCAL 1.0. See [`LEGAL.md`](LEGAL.md) for details.
 
 ---
 
-## License
-
-Echo is dual‑licensed. See `LICENSE`, `LICENSE-APACHE`, `LICENSE-MIND-UCAL`, and `LEGAL.md` for details.
+<p align="center">
+  <sub>Built by <a href="https://github.com/flyingrobots">FLYING•ROBOTS</a></sub>
+</p>

crates/echo-dind-harness/tests/coverage.rs

@@ -42,6 +42,7 @@ fn run_suite(manifest_path: PathBuf) -> Result<()> {
     let manifest: Vec<ManifestEntry> = serde_json::from_reader(BufReader::new(f))?;
 
     let base_dir = manifest_path.parent().unwrap();
+    let update_golden = std::env::var("DIND_UPDATE_GOLDEN").is_ok();
 
     for entry in manifest {
         let scenario_path = base_dir.join(&entry.path);
@@ -54,7 +55,21 @@ fn run_suite(manifest_path: PathBuf) -> Result<()> {
 
         // Check if there is a golden file to verify against
         let golden_path = base_dir.join(entry.path.replace(".eintlog", ".hashes.json"));
-        if golden_path.exists() {
+
+        if update_golden {
+            // Update mode: write new golden file
+            let golden = echo_dind_harness::dind::Golden {
+                elog_version: 1,
+                schema_hash_hex: "0427e9fd236e92dfc8c0765f7bd429fc233bfbfab3cb67c9d03b22a0f31e7f8a"
+                    .to_string(),
+                hash_domain: "DIND_STATE_HASH_V2".to_string(),
+                hash_alg: "BLAKE3".to_string(),
+                hashes_hex: hashes.clone(),
+            };
+            let f_out = std::fs::File::create(&golden_path)?;
+            serde_json::to_writer_pretty(f_out, &golden)?;
+            println!("Updated: {:?}", golden_path);
+        } else if golden_path.exists() {
             let f_golden = File::open(&golden_path)?;
             let expected: echo_dind_harness::dind::Golden =
                 serde_json::from_reader(BufReader::new(f_golden))?;