git-warp

A recursive witnessed admission architecture over Git.

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

---

_{Built by FLYING ROBOTS}