git-warp

A recursive witnessed admission architecture over Git.

git-warp commits truth and reveals truth through bounded worldlines.

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.

Quick start

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

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

const events = await openWarpWorldline({
  persistence,
  worldlineName: 'events',
  writerId: 'agent-1',
});

// Commit: admit a claim into shared causal reality
await events.commit((patch) => {
  patch.addNode('user:alice').setProperty('user:alice', 'role', 'admin');
});

// Reveal: read the admitted truth through a live worldline
const props = await events.live().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 visible 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

The product-facing surface starts with openWarpWorldline(). A worldline is a named admitted causal lane with one writer identity and a small public handle:

Handle method	Moment	What it does
commit()	Commitment	Admits a patch into the named worldline
live()	Revelation	Reads the latest visible state
seek()	Historical revelation	Reads a bounded historical coordinate
observer()	Bounded revelation	Creates an observer through an aperture
optic()	Bounded optic work	Starts optic-shaped reads over the worldline

Advanced tooling can still open the lower-level capability bag with openWarpGraph(). That surface is supported for compatibility, diagnostics, substrate operations, and migration evidence. New application code should prefer Worldlines and Optics unless it is deliberately working on those lower layers.

openWarpGraph() is organized around four 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 — Worldline-first v18 API migration
• 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}