git-warp commits truth, folds truth, and reveals truth under law.

It stores causal graph history in Git objects and refs. Writes are admitted through patches. Reads happen through worldlines, strands, and observers. Provenance, replay, and explicit historical coordinates are part of the model, not bolted-on afterthoughts.

Quick start

import { openWarpGraph } from '@git-stunts/git-warp';
import GitPlumbing from '@git-stunts/plumbing';
import { GitGraphAdapter } from '@git-stunts/git-warp';

const plumbing = new GitPlumbing({ cwd: '.' });
const persistence = new GitGraphAdapter({ plumbing });

const graph = await openWarpGraph({
  persistence,
  graphName: 'events',
  writerId: 'agent-1',
});

// Commit: admit a claim into shared causal reality
const patch = await graph.patches.createPatch();
patch.addNode('user:alice').setProperty('user:alice', 'role', 'admin');
await patch.commit();

// Reveal: read the admitted truth through a live worldline
const worldline = graph.query.worldline();
const props = await worldline.getNodeProps('user:alice');

What git-warp is

git-warp is a Git-native implementation of WARP: Worldline Algebra for Recursive Provenance.

• Offline-first — writers work independently, converge later
• Multi-writer — each writer owns its own ref, no coordination
• Append-only — history is never rewritten
• Deterministic — same patches, any order, same materialized state
• Provenance-complete — every value traces to exactly one producing patch
• Speculative — strands are causal lanes for counterfactual work
• Observable — worldlines, observers, and apertures shape what you see

The admission architecture

openWarpGraph() returns a frozen capability bag organized around three architectural moments:

| Moment | Capabilities | What it does | |--------|-------------|--------------| | Commitment | patches, strands, comparison | Admits claims into frontier-relative truth | | Folding | checkpoint | Re-expresses admitted history as operational artifacts | | Revelation | query, subscriptions, provenance | Exposes admitted truth under bounded rights | | Governance | sync | Transports and admits remote suffixes |

Core nouns

| Term | Meaning | |------|---------| | Worldline | Canonical admitted causal lane. The shared truth others may rely on. | | Strand | Speculative causal lane with fork provenance. Private until admitted. | | Braid | Plural composition over a family of lanes. Not itself a lane. | | Observer | Filtered read-only projection through an aperture. | | Aperture | The boundary that shapes what an observer can see. | | Patch | A claim: a set of operations over a bounded causal site. | | Receipt | Provenance-bearing witness of an admission outcome. |

Why Git

Git and WARP fit together because both are:

• append-only in spirit
• content-addressed
• distributed and multi-writer
• history-preserving

Each writer appends patch commits under refs/warp/<graph>/writers/<writerId>. Commits point at Git's empty tree — graph history stays orthogonal to your source tree. Sync happens through normal git push / git fetch.

When to use it

| Use case | Fit | |----------|-----| | Offline-first multi-writer convergence | Strong | | Agent/tool substrate with causal history | Strong | | Graph semantics without inventing merge law | Strong | | Speculative lanes for what-if exploration | Strong | | High-throughput real-time execution | Use Echo instead | | General-purpose OLTP | Use Postgres | | Full-text search / analytics | Use purpose-built engines | | Time-travel debugging UI | Use warp-ttd on top of git-warp |

Documentation

• Getting Started — first open, write, read, sync
• Readings & Optics — public read model and app-facing read patterns
• Guide — patterns for apps, agents, and tools
• API Reference — exhaustive public API
• Architecture — hexagonal layers and admission kernel
• Migration Guide — upgrading from v16
• CLI Guide — terminal workflows
• Vision — repo doctrine
• Specs — normative protocol and format specifications

Substrate stack

git-warp is part of the @git-stunts substrate:

| Package | Role | |---------|------| | @git-stunts/plumbing | Git operations | | @git-stunts/git-cas | Content-addressable storage with dedup | | @git-stunts/alfred | Resilience (retry, timeout, circuit breaker) | | @git-stunts/trailer-codec | Commit message trailers | | @git-stunts/vault | Secrets management via OS keychain |

License

Apache-2.0