Skip to content

docs: enhance README with traversal directory, seek guide, and runtime compat #64

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
flyingrobots merged 6 commits into from
Mar 7, 2026
Merged

docs: enhance README with traversal directory, seek guide, and runtime compat #64

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
77bc995
docs: update README documentation and CHANGELOG
flyingrobots Mar 6, 2026
bdf0581
docs: fix CHANGELOG version, restore seek flags, fix broken code fence
flyingrobots Mar 6, 2026
1968dda
docs: fix broken code fence, remove duplicate link, correct crypto claim
flyingrobots Mar 6, 2026
b46658e
docs: update CHANGELOG with review fixes
flyingrobots Mar 6, 2026
a10f89e
docs: complete traversal directory, remove phantom changelog fixes
flyingrobots Mar 6, 2026
f0afc04
docs: drop brittle algorithm count from CHANGELOG entry
flyingrobots Mar 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- **Documentation enhancements in README.md** — Added a high-level Documentation Map, a detailed Graph Traversal Directory, an expanded Time-Travel (Seek) guide, and updated Runtime Compatibility information (Node.js, Bun, Deno).
- **Local-First Applications use-case** — Added git-warp as a backend for LoFi software.

## [13.1.0] - 2026-03-04

### Added
Expand Down
75 changes: 64 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,15 @@ const result = await graph.query()
.run();
```

## Documentation Map

If you are new to git-warp, start with the **[Guide](docs/GUIDE.md)**. For deeper dives:

- **[Architecture](ARCHITECTURE.md)**: Deep dive into the hexagonal "Ports and Adapters" design.
- **[Protocol Specs](docs/specs/)**: Binary formats for Audit Receipts, Content Attachments, and BTRs.
- **[ADR Registry](adr/)**: Architectural Decision Records (e.g., edge-property internal canonicalization).
- **[Cookbook](examples/)**: Functional examples of Event Sourcing, Pathfinding, and Multi-Writer setups.

## How It Works

```mermaid
Expand Down Expand Up @@ -320,6 +329,21 @@ const canReach = await graph.traverse.isReachable('user:alice', 'user:bob', {
// canReach = true | false
```

### Graph Traversal Directory

git-warp includes a high-performance traversal engine with 15 deterministic algorithms:

| Category | Algorithms |
| :--- | :--- |
| **Search** | BFS, DFS, Shortest Path (Unweighted), Reachability |
| **Weighted** | Dijkstra (Weighted Shortest Path), A*, Bidirectional A* |
| **Analytical** | Topological Sort (Kahn's), Connected Components, Levels (DAG) |
| **Ancestry** | Common Ancestors, Root Ancestors |
| **Reduction** | **Transitive Reduction** (v13.1), **Transitive Closure** (v13.1) |
| **Critical Path** | Weighted Longest Path (DAG) |

All algorithms support `maxDepth`, `maxNodes`, and `AbortSignal` cancellation.

Comment on lines +332 to +346
Copy link

@coderabbitai coderabbitai bot Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Count traversal algorithms in GraphTraversal implementation

echo "Searching for GraphTraversal algorithm implementations..."

# Look for method definitions in GraphTraversal class/module
rg -n -A 2 'class GraphTraversal|export.*GraphTraversal' --type=ts --type=js

# Search for public algorithm methods (common patterns)
rg -n -P '^\s*(public\s+)?(async\s+)?\w+(Path|Sort|Search|Component|Ancestor|Reduction|Closure|Level|Reachable)' \
  --glob '**/GraphTraversal*' --glob '**/graph-traversal*' \
  --type=ts --type=js -C 1

Repository: git-stunts/git-warp

Length of output: 4198

🏁 Script executed:

# Check line 670 in README.md
head -n 670 README.md | tail -n 5

Repository: git-stunts/git-warp

Length of output: 367

🏁 Script executed:

# Find all public methods in GraphTraversal.js
rg -n '^\s*async\s+\w+\(' src/domain/services/GraphTraversal.js | head -20

Repository: git-stunts/git-warp

Length of output: 665

🏁 Script executed:

# Search for BFS and DFS specifically
rg -n 'async (bfs|dfs)' src/domain/services/GraphTraversal.js

Repository: git-stunts/git-warp

Length of output: 98

🏁 Script executed:

# Get total line count of GraphTraversal.js to understand file structure
wc -l src/domain/services/GraphTraversal.js

Repository: git-stunts/git-warp

Length of output: 105

Update line 670 in Architecture section: algorithm count is 15, not 11.

The Graph Traversal Directory table (lines 332-346) correctly lists 15 algorithms, and the GraphTraversal.js implementation confirms all 15 exist. However, line 670's Architecture description still states "11 algorithms" and must be updated to match.

Update line 670 from:

`GraphTraversal` -- unified traversal engine (11 algorithms, `nodeWeightFn`)

to:

`GraphTraversal` -- unified traversal engine (15 algorithms, `nodeWeightFn`)
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 332 - 346, Update the Architecture description to
reflect the correct algorithm count: change the `GraphTraversal` summary string
to say "(15 algorithms, `nodeWeightFn`)" instead of "(11 algorithms,
`nodeWeightFn`)" so the `GraphTraversal` entry matches the 15 algorithms listed
and implemented.

## Subscriptions & Reactivity

React to graph changes without polling. Handlers are called after `materialize()` when state has changed.
Expand Down Expand Up @@ -526,25 +550,43 @@ git warp history --writer alice

# Check graph health, status, and GC metrics
git warp check
```

### Time-Travel (Seek)

One of git-warp's most powerful features is the ability to query the graph at any point in its history without modifying your Git HEAD.

```bash
# Jump to absolute Lamport tick 3
git warp seek --tick 3

# Step forward or backward relative to your current cursor
git warp seek --tick=+1
git warp seek --tick=-1

# Time-travel: step through graph history
git warp seek --tick 3 # jump to Lamport tick 3
git warp seek --tick=+1 # step forward one tick
git warp seek --tick=-1 # step backward one tick
git warp seek --save before-refactor # bookmark current position
git warp seek --load before-refactor # restore bookmark
git warp seek --latest # return to present
git warp seek --clear-cache # purge persistent seek cache
git warp seek --no-persistent-cache --tick 5 # skip cache for one invocation
# Bookmark and restore positions
git warp seek --save before-refactor
git warp seek --load before-refactor

# Return to the present and clear the cursor
git warp seek --latest

# Purge the persistent seek cache
git warp seek --clear-cache

# Skip cache for a single invocation
git warp seek --no-persistent-cache --tick 5
```

When a seek cursor is active, `query`, `info`, `materialize`, and `history` automatically show state at the selected tick.

```bash
# Visualize query results (ascii output by default)
git warp query --match 'user:*' --outgoing manages --view
```

All commands accept `--repo <path>` to target a specific Git repository, `--json` for machine-readable output, and `--view [mode]` for visual output (ascii by default, or browser, svg:FILE, html:FILE).

When a seek cursor is active, `query`, `info`, `materialize`, and `history` automatically show state at the selected tick.

<p align="center">
<img src="docs/seek-demo.gif" alt="git warp seek time-travel demo" width="600">
</p>
Expand Down Expand Up @@ -673,6 +715,7 @@ npm run test:matrix # All runtimes in parallel
- **Audit-critical systems.** Tamper-evident records with cryptographic proof (via Audit Receipts).
- **IoT sensor networks.** Sensors logging readings and relationships, syncing when bandwidth allows.
- **Game world state.** Modders independently adding content that composes without a central manager.
- **Local-First Applications.** A backend for LoFi software that needs Git's robust sync and versioning capabilities without the overhead of a standard Git worktree or a heavy database server.

## When NOT to Use It

Expand All @@ -686,6 +729,16 @@ npm run test:matrix # All runtimes in parallel

This package is the reference implementation of WARP (Worldline Algebra for Recursive Provenance) graphs as described in the AIΩN Foundations Series. The papers formalize the graph as a minimal recursive state object ([Paper I](https://doi.org/10.5281/zenodo.17908005)), equip it with deterministic tick-based semantics ([Paper II](https://doi.org/10.5281/zenodo.17934512)), develop computational holography and provenance payloads ([Paper III](https://doi.org/10.5281/zenodo.17963669)), and introduce observer geometry with the translation cost metric ([Paper IV](https://doi.org/10.5281/zenodo.18038297)).

## Runtime Compatibility

Architected with **Hexagonal Ports and Adapters**, git-warp is runtime-agnostic and tested across the following environments:

- **Node.js**: v22.0.0+ (Native Roaring Bitmaps & WebCrypto)
- **Bun**: v1.1+ (WASM Roaring fallback & WebCrypto)
- **Deno**: v2.0+ (WASM Roaring fallback & WebCrypto)

Bitmap indexes are wire-compatible across all runtimes; a graph created in Node.js can be materialized and queried in Deno without modification.

## License

Apache-2.0
Expand Down
Loading