{"id":34599130,"url":"https://github.com/flyingrobots/echo","last_synced_at":"2025-12-24T12:07:38.120Z","repository":{"id":320428311,"uuid":"1082070703","full_name":"flyingrobots/echo","owner":"flyingrobots","description":"Recursive meta-graph game engine. Fork reality, merge timelines,  get perfect determinism. Built on category theory, powered by graph rewriting.","archived":false,"fork":false,"pushed_at":"2025-12-17T23:48:41.000Z","size":7030,"stargazers_count":6,"open_issues_count":55,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-21T10:37:11.834Z","etag":null,"topics":["confluence","deterministic-simulation","dpo-rewriting","experimental","formal-methods","game-engine","gamedev","graph-rewriting","lua","networked-multiplayer","rust","time-travel-debugging"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flyingrobots.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audit.toml","citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-23T17:32:41.000Z","updated_at":"2025-12-17T23:48:45.000Z","dependencies_parsed_at":"2025-12-02T13:05:16.994Z","dependency_job_id":null,"html_url":"https://github.com/flyingrobots/echo","commit_stats":null,"previous_names":["flyingrobots/echoengine","flyingrobots/echo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/flyingrobots/echo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fecho","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fecho/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fecho/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fecho/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flyingrobots","download_url":"https://codeload.github.com/flyingrobots/echo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fecho/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28002250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["confluence","deterministic-simulation","dpo-rewriting","experimental","formal-methods","game-engine","gamedev","graph-rewriting","lua","networked-multiplayer","rust","time-travel-debugging"],"created_at":"2025-12-24T12:07:29.065Z","updated_at":"2025-12-24T12:07:38.110Z","avatar_url":"https://github.com/flyingrobots.png","language":"Rust","readme":"\u003c!-- SPDX-License-Identifier: Apache-2.0 OR MIND-UCAL-1.0 --\u003e\n\u003c!-- © James Ross Ω FLYING•ROBOTS \u003chttps://github.com/flyingrobots\u003e --\u003e\n# Echo\n\n```rust\n//! ░▒▓████████▓▒░▒▓██████▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓██████▓▒░\n//! ░▒▓█▓▒░     ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░\n//! ░▒▓█▓▒░     ░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░\n//! ░▒▓██████▓▒░░▒▓█▓▒░      ░▒▓████████▓▒░▒▓█▓▒░░▒▓█▓▒░\n//! ░▒▓█▓▒░     ░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░\n//! ░▒▓█▓▒░     ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░\n//! ░▒▓████████▓▒░▒▓██████▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓██████▓▒░\n//!\n//! “What we do in life ECHOES through eternity”\n//! (Recursively, in the Metaverse)\n```\n\n## **tl;dr:**\n\n\u003e Echo is a WARP Graph (Worldline Algebra for Recursive Provenance) simulation engine that treats _everything_–code, data, and time itself—as one big living graph.\n\u003e It’s built so every change can branch, merge, and replay perfectly.\n\n\u003cimg src=\"https://github.com/user-attachments/assets/d31abba2-276e-4740-b370-b4a9c80b30de\" height=\"400\" align=\"right\" /\u003e\n\n### Say what??\n\n**Echo is an ambitious, mind-bending, radically different computational model for game engines and other interactive simulations.** The WARP graph is a powerful mathematical tool that brings the full weight of textbook category theory to interactive computational experiences. \n\nMost game engines are object-oriented state machines. Unity, Unreal, Godot all maintain mutable object hierarchies that update every frame. Echo says: \"No, everything is a graph, and the engine rewrites that graph deterministically using typed transformation rules.\" \n\nEcho is fundamentally **built different**.\n\nWARP provides atomic, in-place edits of WARP graphs with deterministic local scheduling and snapshot isolation. Yep, Echo is powered by a WARP core engine: runtime, assets, networking, and tools all operate on the same living graph of graphs.\n\nEcho is a mathematically rigorous game engine that replaces traditional OOP with deterministic graph rewriting, enabling time-travel debugging, perfect replay, and Git-like branching for game states.\n\n## Developer: Running Benchmarks\n\n- Command (live dashboard): `make bench-report`\n  - Runs `cargo bench -p rmg-benches`, starts a local server, and opens the dashboard at `http://localhost:8000/docs/benchmarks/`.\n- Command (offline static file): `make bench-bake`\n  - Runs benches and bakes `docs/benchmarks/report-inline.html` with results injected so it works over `file://` (no server required).\n- Docs: see `crates/rmg-benches/benches/README.md` for details, tips, and report paths.\n\n### Core Principles\n\n| Principle                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Everything is a graph    | Nodes, edges, even rewrite rules are all graphs.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| Recursive                | Graphs contain subgraphs without limit.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| Typed                    | Every node and edge carries a type hash and schema metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| DPO-i Graph Rewriting    | Based on Double Pushout approach with deterministic local scheduler (DPOi = deterministic parallel-order incremental).                                                                                                                                                                                                                                                                                                                                                                                     |\n| Atomic in-place edits    | Mutations apply directly to the graph with snapshot isolation.                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| Confluence               | Independent rewrite sequences that overlap converge to the same canonical graph.                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| Snapshots, not logs      | Snapshots are emitted from the live graph; append-only history is optional.                                                                                                                                                                                                                                                                                                                                                                                                                                |\n| Deterministic scheduling | The same set of rewrite rules applied to the same graph always yields identical results.                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| QCA-Ready                | Rules can express reversible and superposed transformations for future quantum/parallel semantics. Quantum? Yep. But in this context it means the rewrite engine can be extended to tag rules as **reversible**: every transformation can be walked backward without loss. Built-in, lossless rollback and causal replay, the ability to run parallel speculative branches deterministically, and, yes, quantum, meaning that a research path toward quantum / probabilistic simulation modes is possible. |\n\n---\n\n### What's Echo?\n\nEcho runs on something called a **WARP Graph (Worldline Algebra for Recursive Provenance)**. Think of it as a graph-based operating system. Everything in the engine (worlds, entities, physics, shaders, even the tools) lives inside that graph.\n\nEcho doesn’t “update objects.” It _rewrites_ parts of the graph using a set of deterministic rules. That’s what “graph rewriting” means.\n\n### Why Echo's Cool\n\n- **Deterministic:** same inputs = same world every time.\n- **Branching:** you can fork reality, change it, and merge it back without chaos.\n- **Confluent:** independent edits always end up in the same final state.\n- **Snapshot-based:** you can freeze the whole graph at any moment for replay or rollback.\n- **Recursive:** a node can contain its own sub-graph—systems inside systems.\n\n### In Plain English\n\nEcho feels like if Minecraft, Git, and a physics engine had a baby that understood time travel.\nYou can pause time, fork a copy of reality, try out a new idea, and merge the timelines back together, without breaking determinism.\n\n---\n\n## Advantages\n\n\u003e _\"Things are only impossible until they're not.\" — Jean-Luc Picard_\n\nCan your game engine do...\n\n### Perfect Determinism \n\nSame input graph + same rules = same output, always. This is huge for:\n\n- Networked multiplayer (no desync, ever)\n- Replays (just store the initial state + inputs)\n- Testing (reproducible bugs)\n- Time travel debugging\n\n### Branching Timelines \n\n\u003e _“All we have to decide is what to do with the time that is given to us.” — Gandalf, The Lord of the Rings_\n\nThe Git metaphor is accurate. Fork reality, try something, merge back. This enables:\n\n- Speculative execution\n- \"What if?\" simulation\n- Save/load that's mathematically guaranteed to work\n\n### Confluence\n\nIndependent changes converge to the same result. This is operational transformation meets game engine, and it's bonkers powerful for:\n\n- Collaborative editing\n- Distributed simulation\n- Conflict-free merges\n\n### Everything-is-a-graph \n\nRules are graphs. Systems are graphs. The whole runtime is a graph. This gives you:\n\n- Introspection at every level\n- Hot-reloading without special cases\n- Tools that operate on the same substrate as the engine\n- Zero-copy loading\n\n---\n\n| Principle | Vision | Implementation |\n| :--- | :--- | :--- |\n| **Determinism (The \"Replay\")** | Same input graph + same rules = same output graph. Always. This is huge for networked multiplayer (no desync), perfect replays, and reproducible bug testing. | Achieved via an $O(n)$ deterministic scheduler. Pending graph rewrites are sorted using a stable radix sort (not a comparison-based sort) based on their scope, rule ID, and nonce. Combined with a deterministic math module (Vec3, Quat, PRNG), this ensures identical inputs always produce identical execution order and final state. |\n| **Branching \u0026 Confluence (The \"Time Travel\")** | Fork reality, try something, and merge it back like a Git branch. Independent, non-conflicting changes converge to the same canonical state, guaranteed. | The engine's Timeline Tree (modeling Chronos, Kairos, and Aion) allows for branching realities. The engine's core transaction model (begin, apply, commit) and footprint-based independence checks (MWMR) allow for safe, parallel execution and deterministic, conflict-free merges. |\n| **Snapshot Isolation (The \"Commit\")** | Snapshots are emitted from the live graph; append-only history is optional. This enables save/load, time-travel debugging, and collaborative editing. | Each commit produces two Merkle hashes derived from 256-bit BLAKE3: \u003cul\u003e\u003cli\u003e\u003ccode\u003estate_root\u003c/code\u003e: deterministic hash of the reachable graph state under the current root.\u003c/li\u003e\u003cli\u003e\u003ccode\u003ecommit hash\u003c/code\u003e (commit_id): hash of a canonical header including \u003ccode\u003estate_root\u003c/code\u003e, parents, and deterministic digests for plan/decisions/rewrites.\u003c/li\u003e\u003c/ul\u003e See \u003ccode\u003edocs/spec-merkle-commit.md\u003c/code\u003e for the precise encoding and invariants. |\n| **Everything-is-a-Graph (The \"Substrate\")** | Nodes, edges, systems, assets, and even rewrite rules are all graphs. Graphs can contain subgraphs recursively. | The engine operates on typed, directed graphs. All identifiers (NodeId, TypeId, EdgeId) are domain-separated BLAKE3 hashes. Rewrite Rules are defined with a matcher, executor, and compute_footprint function, allowing the engine to deterministically transform the graph. |\n| **Hexagonal Architecture (The \"Ports\")** | A core engine that is pure logic, completely decoupled from the outside world (rendering, input, networking). | Echo uses a Ports \u0026 Adapters design. The core engine (rmg-core) knows nothing of pixels, sockets, or key presses. It exposes narrow interfaces (\"Ports\") that external crates (\"Adapters\") implement. This allows swapping renderers (e.g., WebGPU, SDL) or physics engines without changing the core simulation logic. |\n\n---\n\n## Architecture\n\n\u003e _“Roads? Where we’re going, we don’t need roads.” — Doc Brown, Back to the Future_\n\nEcho is a Rust workspace organized into a multi-crate setup. The core engine is pure, dependency-free Rust (#![no_std] capable) with I/O isolated to adapter crates.\n\n```bash\necho/\n├── crates/\n│   ├── rmg-core/        (Core engine: WARP, scheduler, transaction model, snapshotting)\n│   ├── rmg-geom/        (Geometry primitives: AABB, transforms, broad-phase)\n│   ├── rmg-benches/     (Criterion microbenchmarks: snapshot_hash, scheduler_drain)\n│   ├── rmg-wasm/        (WebAssembly bindings for tools and web)\n│   ├── rmg-ffi/         (C ABI for Lua/host integration)\n│   └── rmg-cli/         (Command-line interface, demos launcher)\n├── docs/                (Comprehensive specifications and diagrams)\n└── scripts/             (Build automation, benchmarking)\n```\n\n### Core Architectural Layers\n\n1. ECS (Entity-Component-System): Type-safe components with archetype-based storage\n2. Scheduler: Deterministic DAG ordering via O(n) radix sort\n3. Event Bus: Command buffering for deterministic event handling\n4. Timeline Tree: Branching/merging with temporal mechanics (Chronos, Kairos, Aion)\n5. Ports \u0026 Adapters: Renderer, Input, Physics, Networking, Audio, Persistence\n6. Deterministic Math: Vec3, Mat4, Quat, PRNG with reproducible operations\n\n### Key Technical Concepts\n\n#### Recursive Meta Graph Core\n\nThe engine operates on typed, directed graphs:\n\n- Nodes = typed entities with component data\n- Edges = typed relationships between nodes\n- Rules = deterministic transformations that match patterns and rewrite subgraphs\n\nAll identifiers are 256-bit BLAKE3 hashes with domain separation:\n\n```rust\npub type Hash = [u8; 32];\npub struct NodeId(pub Hash);   // Entities\npub struct TypeId(pub Hash);   // Type descriptors\npub struct EdgeId(pub Hash);   // Relationships\n```\n\n#### Deterministic Rewriting\n\nEach tick follows a transaction model:\n\n1. begin()         → Create new transaction\n2. apply(tx, rule) → Enqueue pending rewrites\n3. commit(tx)      → Execute in deterministic order, emit snapshot\n\n#### $O(n)$ Deterministic Scheduler\n\nRewrites are ordered using stable radix sort (not comparison-based):  \n\n- Order: (`scope_hash`, `rule_id`, `nonce`) lexicographically\n- Time: $O(n)$ with 20 passes of 16-bit radix digits\n\nThis ensures identical initial state + rules = identical execution order and final snapshot.\n\n#### Snapshot Hashing (Merkle Commits)\n\nTwo hashes per commit:\n\n- `state_root`: BLAKE3 of canonical graph encoding (sorted nodes/edges)\n- `commit_id`: BLAKE3 of commit header (`state_root` + parent + plan + decisions + rewrites)\n\n### Footprints \u0026 Independence (MWMR)\n\nFor parallel rewriting:\n\n```rust\nstruct Footprint {\n  n_read, n_write: IdSet,     // Node reads/writes\n  e_read, e_write: IdSet,     // Edge reads/writes\n  b_in, b_out: PortSet,       // Boundary ports\n  factor_mask: u64,           // Spatial partitioning hint\n}\n```\n\nDisjoint footprints = independent rewrites = safe parallel execution.\n\n### Component Interaction\n\n#### `rmg-core` (`crates/rmg-core/src/`)\n\n- `engine_impl.rs`: Transaction lifecycle, rewrite application\n- `scheduler.rs`: $O(n)$ radix drain, conflict detection\n- `graph.rs`: BTreeMap-based node/edge storage\n- `snapshot.rs`: State root and commit ID computation\n- `rule.rs`: Rewrite rule definitions with pattern matching\n- `footprint.rs`: Independence checks for concurrent execution\n- `math/`: Deterministic Vec3, Mat4, Quat, PRNG\n\n## Execution Flow\n\n```c\nloop {\n  let tx = engine.begin();\n\n  // Application phase\n  for rule in rules_to_apply {\n      engine.apply(tx, rule, \u0026scope)?;\n  }\n\n  // Deterministic execution\n  let snapshot = engine.commit(tx)?;\n\n  // Emit to networking, tools, etc.\n  publish_snapshot(snapshot);\n}\n```\n\n## Design Principles\n\n1. Determinism as Foundation: Every operation must produce identical results given identical input\n2. Snapshot Isolation: State captured as immutable graph hashes (not event logs)\n3. Hexagonal Architecture: Core never touches I/O directly; all flows through ports\n4. Dependency Injection: Services wired at bootstrap for hot-reload support\n5. Property-Based Testing: Extensive use of proptest for mathematical invariants\n\n## Current Status\n\nPhase 1 MVP (active development on echo/pr-12-snapshot-bench):\n\n✅ Completed:\n- Formal confluence proofs (tick-level determinism proven)\n- Rust core runtime with transaction model\n- 200+ property tests validating commutativity\n- Benchmark infrastructure with D3 dashboard\n\n🚧 In Progress:\n- Performance optimization (subgraph matching, spatial indexing)\n- Temporal mechanics integration\n\n## Key Files to Explore\n\n### Documentation\n\n- `README.md` — Project vision\n- `docs/architecture-outline.md` — Full system design\n- `docs/spec-rmg-core.md` — WARP Core spec v2\n- `docs/spec-merkle-commit.md` — Snapshot hashing spec\n- `docs/spec-scheduler.md` — Deterministic scheduler design\n\n### Core Implementation\n\n- `crates/rmg-core/src/engine_impl.rs` — Engine core\n- `crates/rmg-core/src/scheduler.rs` — O(n) scheduler\n- `crates/rmg-core/src/snapshot.rs` — Merkle hashing\n- `crates/rmg-core/src/demo/motion.rs` — Example rewrite rule\n\n### Tests \u0026 Benchmarks:\n\n- `crates/rmg-core/tests/permutation_commute_tests.rs` — Determinism proofs\n- `crates/rmg-benches/benches/snapshot_hash.rs` — Hashing throughput\n\n---\n\n## Contributing\n\n\u003e ***WANTED:** Somebody to go back in time with me. This is not a joke.*\n\u003e *P.O. Box 91, Ocean View, WA 99393.*\n\u003e *You’ll get paid after we get back. Must bring your own weapons.*\n\u003e *I have only done this once before. **Safety not guaranteed.***\n\n- Start each task by verifying a clean git state and branching (`echo/\u003cfeature\u003e` recommended).\n- Tests go in `packages/echo-core/test/` (fixtures in `test/fixtures/`). End-to-end scenarios will eventually live under `apps/playground`.\n- Use expressive commits (`subject` / `body` / optional `trailer`). Tell future us the *why*, not just the *what*.\n- Treat determinism as sacred: use Echo’s PRNG, avoid non-deterministic APIs without wrapping them.\n  \n### Git Hooks\n\nInstall the repo’s hooks so formatting and quick checks run before commits:\n\n```\nmake hooks\n```\n\n### Development Principles\n\n1. **Tests First** – Write failing unit/integration/branch tests before new engine work.\n2. **Branch Discipline** – Feature branches target `main`; keep `main` pristine.\n3. **Document Ruthlessly** – Update specs/diagrams and log decisions.\n4. **Temporal Mindset** – Think *Chronos* (sequence), *Kairos* (possibility), *Aion* (significance) whenever touching runtime code.\n\n### Roadmap Highlights\n\n✅ **Phase 0** – Finalize specs and design.  \n⏳ **Phase 1** – Ship Echo Core MVP with tests and headless harness.  \n☑️ **Phase 2** – Deliver reference render/input adapters and **the playground**.  \n☑️ **Phase 3+** – Physics, WebGPU, audio, inspector, and full temporal tooling.  \n\n**Chrononauts welcome.** Strap in, branch responsibly, and leave the timeline cleaner than you found it.\n\n---\n\n## License\n\n**Licensing split:**\n\n- Code (all source/build/tooling): [Apache 2.0](./LICENSE-APACHE)\n- Theory / math / docs corpus: [Apache 2.0](./LICENSE-APACHE) OR [MIND-UCAL v1.0](./LICENSE-MIND-UCAL)\n\nIf you do not wish to use MIND-UCAL, you may freely use all theory, math, and\ndocumentation under Apache 2.0 alone. No part of this repository requires\nadopting MIND-UCAL.\n\nSee [`LICENSE`](./LICENSE) for the summary and [`NOTICE`](./NOTICE) for attribution.\n\n© 2025 James Ross   \nΩ [FLYING•ROBOTS](https://github.com/flyingrobots)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflyingrobots%2Fecho","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflyingrobots%2Fecho","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflyingrobots%2Fecho/lists"}