Skip to content

git-substrate.md

Latest commit

 

History

History
109 lines (80 loc) · 3.43 KB

git-substrate.md

File metadata and controls

109 lines (80 loc) · 3.43 KB
Raw

Git substrate

Use this page when you need to understand what lives in Git and why replay is deterministic.

Package boundary

The graph composition roots described by older releases are runtime internals in v19, not deprecated package exports. Application code starts with openWarp(); storage, formal machinery, and operator inspection use the explicit storage, advanced, and diagnostics subpaths. Keep substrate tooling behind those supported boundaries instead of importing src/domain modules.

WARP refs

WARP data stays under refs/warp/..., outside normal source-tree refs:

refs/warp/<graphName>/
├── writers/
│   ├── alice
│   └── bob
├── checkpoints/
│   └── head
├── coverage/
│   └── head
├── cursor/
│   ├── active
│   └── saved/<name>
├── strand-braids/
│   └── <strand>/<support>
├── audit/
│   └── <writerId>
└── trust/
    └── ...

Normal source code remains under refs such as refs/heads/main.

Patch commits

At the substrate level, a WARP patch is a Git commit on a WARP ref.

flowchart TB
    commit["patch commit"] --> parent["previous writer patch"]
    commit --> tree["patch/content tree"]
    commit --> trailers["graph, writer, Lamport, schema"]
    tree --> patch["patch.cbor"]
    tree --> content["optional content payloads"]
Loading

Patch commits may carry Git trees for payloads and content. Do not document a blanket empty-tree invariant for current graph state.

Replay convergence

Each writer appends an independent patch chain. Visible state is derived by replaying the visible patches and reducing them with deterministic CRDT rules:

  • nodes and edges use OR-Set semantics;
  • properties use last-writer-wins registers;
  • Lamport ticks plus writer identity provide deterministic ordering;
  • version vectors distinguish causal order from concurrency.

That is why multiple writers can work independently and later converge without source-tree merge conflicts for graph data.

Checkpoints

Checkpoints persist folded state plus index, frontier, and schema metadata. They accelerate recovery and bounded-read evidence. They are not the source of truth; patch history remains authoritative.

Use Operations for checkpoint and GC workflows.

Provenance

Provenance APIs explain which patches contributed to an entity or slice. materializeSlice(nodeId) can replay a single entity's backward causal cone for diagnostics. It is not the first-use application read path.

Content storage

Patch trees can carry payloads and content pointers. Larger payloads and encrypted content are handled through CAS-backed adapters. Use Content and CAS for content attachments, git-cas, and encryption posture.

Strands and braids

Strands are durable speculative lanes built on pinned observations and overlay patch logs. Braid refs record pinned support overlays for strand composition.

Use Strands for user-facing strand and braid workflows.

Continuum boundary

git-warp owns local runtime truth over Git-backed history. Continuum owns the shared boundary vocabulary for witnessed history exchange. Use Continuum boundary for that relationship.

See also