{"id":44315232,"url":"https://github.com/git-stunts/git-warp","last_synced_at":"2026-04-01T16:34:41.387Z","repository":{"id":333384059,"uuid":"1137101386","full_name":"git-stunts/git-warp","owner":"git-stunts","description":"CRDT-friendly WARP graph engine on Git commits, with deterministic replayable history.","archived":false,"fork":false,"pushed_at":"2026-03-25T15:23:15.000Z","size":24207,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T17:44:42.148Z","etag":null,"topics":["aion","content-addressable-storage","dag","distributed-database","distributed-systems","git","git-internals","git-native","git-plumbing","git-stunts","graph","graph-algorithms","graph-database","hexagonal-architecture","offline-first","offline-first-app","roaring-bitmaps","warp-graphs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/git-stunts.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-18T22:55:21.000Z","updated_at":"2026-03-18T03:04:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/git-stunts/git-warp","commit_stats":null,"previous_names":["git-stunts/empty-graph","git-stunts/git-warp"],"tags_count":44,"template":false,"template_full_name":null,"purl":"pkg:github/git-stunts/git-warp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-stunts%2Fgit-warp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-stunts%2Fgit-warp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-stunts%2Fgit-warp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-stunts%2Fgit-warp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/git-stunts","download_url":"https://codeload.github.com/git-stunts/git-warp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-stunts%2Fgit-warp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["aion","content-addressable-storage","dag","distributed-database","distributed-systems","git","git-internals","git-native","git-plumbing","git-stunts","graph","graph-algorithms","graph-database","hexagonal-architecture","offline-first","offline-first-app","roaring-bitmaps","warp-graphs"],"created_at":"2026-02-11T05:07:21.062Z","updated_at":"2026-04-01T16:34:41.378Z","avatar_url":"https://github.com/git-stunts.png","language":"JavaScript","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/git-stunts/git-warp/main/docs/images/git-warp-alt.svg\" alt=\"git-warp logo\" /\u003e\n  \u003ch1\u003e\u003ccode\u003egit-warp\u003c/code\u003e: a causal, multi-writer graph database for the Git substrate\u003c/h1\u003e\n  \u003cp\u003eDistributed, conflict-free graph storage that lives orthogonally to your source tree.\u003c/p\u003e\n\u003c/div\u003e\n\n[![CI](https://github.com/git-stunts/git-warp/actions/workflows/ci.yml/badge.svg)](https://github.com/git-stunts/git-warp/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![npm version](https://badge.fury.io/js/%40git-stunts%2Fgit-warp.svg)](https://www.npmjs.com/package/@git-stunts/git-warp)\n\n## Choose the right tool\n\n| Use case | git-warp | Echo | Other | Remarks |\n| --- | --- | --- | --- | --- |\n| Offline-first collaborative app | ✅ | ❌ | **CouchDB / PouchDB** | `git-warp` is a strong fit when your data is graph-shaped, writers work independently, and eventual consistency is acceptable. |\n| Multi-writer edge or IoT fleet with intermittent network access | ✅ | ❌ | **Event log + custom sync** | `git-warp` works well when devices need local writes, later sync, and deterministic convergence without central coordination. |\n| Decentralized tool that already trusts Git remotes | ✅ | ❌ | **Plain Git + custom files** | `git-warp` is a better fit when the replicated data is a graph and you do not want to invent your own merge semantics. |\n| High-performance realtime simulation or game loop | ❌ | ✅ | **Traditional ECS / game engine** | Echo is designed for deterministic, replayable, high-throughput rewrite execution where runtime throughput matters more than Git-native storage. |\n| Replayable deterministic simulation tooling | ❌ | ✅ | **Custom lockstep engine** | Echo is the better fit when ticks, stepping, and runtime throughput are the core problem. |\n| Centralized OLTP web app | ❌ | ❌ | **Postgres** | If you need low-latency transactions around one primary database, use a conventional database. |\n| Analytics warehouse or OLAP workload | ❌ | ❌ | **DuckDB / ClickHouse** | Neither `git-warp` nor Echo is a warehouse or columnar analytics engine. |\n\n## What git-warp is\n\n`git-warp` is a JavaScript library that stores a WARP graph inside Git objects and refs.\n\nA WARP graph is causal: history and provenance are part of the model instead of discarded implementation detail. Each write becomes a patch commit, readers can pin history through worldlines, and multiple writers can converge deterministically after sync.\n\nWARP stands for **Worldline Algebra for Recursive Provenance**. WARP itself is not tied to Git; `git-warp` is the Git-native implementation. If you want the underlying theory, see [AIΩN](https://github.com/flyingrobots/aion). If you want a sibling runtime optimized for high-throughput realtime rewrite execution rather than Git-native durability, see [Echo](https://github.com/flyingrobots/echo).\n\nChoose `git-warp` for durable asynchronous collaboration. Choose Echo for deterministic realtime execution.\n\n## Why Git\n\nGit and WARP fit together unusually well:\n\n- both are append-only in spirit\n- both rely on content-addressed artifacts\n- both work well in distributed, multi-writer environments\n\n`git-warp` uses Git because Git already provides battle-tested object storage, cryptographic integrity, and distributed replication. `git-warp` adds graph structure, CRDT merge semantics, and pinned historical reads on top.\n\nEach writer appends patch commits under `refs/warp/\u003cgraph\u003e/writers/\u003cwriterId\u003e`. Those commits point at Git's well-known empty tree, so graph history stays orthogonal to normal source-tree history on your checked-out branches.\n\n## Architecture at a glance\n\n```mermaid\nflowchart TB\n    subgraph app[\"Application surface\"]\n        wa[\"WarpApp\u003cbr /\u003ewrites, sync, worldlines, observers, strands\"]\n    end\n\n    subgraph domain[\"Domain engine\"]\n        wc[\"WarpCore\u003cbr /\u003ereplay, provenance, materialization, inspection\"]\n        crdt[\"CRDT reducer\u003cbr /\u003eOR-Set + LWW + Lamport ordering\"]\n    end\n\n    subgraph infra[\"Infrastructure adapters\"]\n        git[\"Git object store + refs\"]\n        ports[\"Ports / adapters\"]\n    end\n\n    wa --\u003e wc\n    wc --\u003e crdt\n    wc --\u003e ports\n    ports --\u003e git\n```\n\nThe normal builder path is `WarpApp`. `WarpCore` is the plumbing surface for replay, provenance, inspection, debugger tooling, and other substrate-level work.\n\n## When to use it\n\n- You need local graph writes now and sync later.\n- You expect multiple writers to work independently and converge deterministically.\n- You want history, time-travel reads, and provenance to be part of the data model.\n- You already trust Git as a storage and replication substrate.\n\n## When not to use it\n\n- You need a centralized OLTP database with immediate consistency and low-latency transactions.\n- You need a warehouse, search engine, or analytics store.\n- You need ultra-high-throughput realtime simulation rather than Git-native durability.\n- You do not actually need graph relationships, traversal, or history-aware reads.\n\n## Documentation pipeline\n\nUse these docs in order, based on the job you are trying to do:\n\n- **[Getting Started](https://github.com/git-stunts/git-warp/blob/main/docs/GETTING_STARTED.md)**: see `git-warp` work in a few minutes.\n- **[Guide](https://github.com/git-stunts/git-warp/blob/main/docs/GUIDE.md)**: build an app with `WarpApp`, worldlines, observers, and strands.\n- **[API Reference](https://github.com/git-stunts/git-warp/blob/main/docs/API_REFERENCE.md)**: exhaustive API, flags, and examples without the narrative.\n- **[Advanced Guide](https://github.com/git-stunts/git-warp/blob/main/docs/ADVANCED_GUIDE.md)**: substrate internals, replay, trust, performance, and engine-room details.\n- **[CLI Guide](https://github.com/git-stunts/git-warp/blob/main/docs/CLI_GUIDE.md)**: operate, inspect, and debug a live repo from the terminal.\n- **[Documentation index](https://github.com/git-stunts/git-warp/blob/main/docs/README.md)**: canonical map of the full docs corpus.\n\nFocused docs:\n\n- **[Conceptual overview](https://github.com/git-stunts/git-warp/blob/main/docs/CONCEPTUAL_OVERVIEW.md)**: a deeper conceptual explanation of the WARP model and the Git substrate.\n- **[Architecture](https://github.com/git-stunts/git-warp/blob/main/docs/ARCHITECTURE.md)**: system structure and internal layering.\n- **[Protocol specs](https://github.com/git-stunts/git-warp/tree/main/docs/specs)**: normative formats such as content attachments, receipts, and BTRs.\n\n## Core nouns\n\n| Term | Meaning |\n| --- | --- |\n| **WarpApp** | The product-facing root for writing, syncing, worldlines, observers, and strands. |\n| **WarpCore** | The plumbing-facing root for replay, provenance, inspection, and tooling. |\n| **Patch** | A WARP patch is a Git commit under `refs/warp/...` containing a CBOR-encoded operation log plus metadata. |\n| **Tick** | One logical replay step: the application of one patch into visible state. |\n| **Worldline** | A pinned read-history handle over live truth, an explicit coordinate, or a strand. |\n| **Aperture** | The aperture definition that shapes what an observer can see. |\n| **Observer** | A filtered, read-only projection over a worldline through an aperture. |\n| **Strand** | A speculative write lane branched from a base observation. |\n| **Braid** | A read-only composition that lets one strand see one or more support strands without collapsing them together. |\n\n## License\n\nApache-2.0\n\n---\n\n\u003cp align=\"center\"\u003e\n\u003csub\u003eBuilt by \u003ca href=\"https://github.com/flyingrobots\"\u003eFLYING ROBOTS\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-stunts%2Fgit-warp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgit-stunts%2Fgit-warp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-stunts%2Fgit-warp/lists"}