From 77bc99510a03944c9ba2ef003d7bd14f7d44ae1d Mon Sep 17 00:00:00 2001 From: James Ross Date: Fri, 6 Mar 2026 08:13:44 -0800 Subject: [PATCH 1/6] docs: update README documentation and CHANGELOG --- CHANGELOG.md | 7 ++++++ README.md | 65 ++++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 63 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fbd8fa23..0985565c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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). +## [13.1.1] - 2026-03-06 + +### Added + +- **Documentation enhancements in README.md** — Added a high-level Documentation Map, a detailed Graph Traversal Directory (listing 11+ algorithms), 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 diff --git a/README.md b/README.md index 03051e20..cb4ac55c 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,16 @@ 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: + +* **[User Manual](docs/GUIDE.md)**: Comprehensive guide to queries, traversals, and multi-writer sync. +* **[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 @@ -320,6 +330,20 @@ 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 11+ 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) | +| **Reduction** | **Transitive Reduction** (v13.1), **Transitive Closure** (v13.1) | +| **Critical Path** | Weighted Longest Path (DAG) | + +All algorithms support `maxDepth`, `maxNodes`, and `AbortSignal` cancellation. + ## Subscriptions & Reactivity React to graph changes without polling. Handlers are called after `materialize()` when state has changed. @@ -527,15 +551,27 @@ git warp history --writer alice # Check graph health, status, and GC metrics git warp check -# 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 +### 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 + +# 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 +``` + +When a seek cursor is active, `query`, `info`, `materialize`, and `history` automatically show state at the selected tick. # Visualize query results (ascii output by default) git warp query --match 'user:*' --outgoing manages --view @@ -673,6 +709,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 @@ -686,6 +723,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 & NodeCrypto) +* **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 From bdf05810eaf00e54018a085246b7529a42da8cb6 Mon Sep 17 00:00:00 2001 From: James Ross Date: Fri, 6 Mar 2026 10:14:44 -0800 Subject: [PATCH 2/6] docs: fix CHANGELOG version, restore seek flags, fix broken code fence - Change premature [13.1.1] CHANGELOG entry to [Unreleased] - Restore --clear-cache and --no-persistent-cache to seek docs - Fix orphaned code block for visualize example (missing opening fence) - Remove duplicate "seek cursor is active" sentence --- CHANGELOG.md | 2 +- README.md | 7 +++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0985565c..49e79205 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,7 @@ 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). -## [13.1.1] - 2026-03-06 +## [Unreleased] ### Added diff --git a/README.md b/README.md index cb4ac55c..70bfaf1b 100644 --- a/README.md +++ b/README.md @@ -569,18 +569,21 @@ git warp seek --load before-refactor # Return to the present and clear the cursor git warp seek --latest + +# Cache management +git warp seek --clear-cache # purge persistent seek cache +git warp seek --no-persistent-cache --tick 5 # skip cache for one invocation ``` 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 ` 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. -

git warp seek time-travel demo

From 1968dda29626a974b7dcfd4f685114b2b8e5d508 Mon Sep 17 00:00:00 2001 From: James Ross Date: Fri, 6 Mar 2026 12:02:19 -0800 Subject: [PATCH 3/6] docs: fix broken code fence, remove duplicate link, correct crypto claim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Close unclosed ```bash fence before ### Time-Travel heading (critical: entire seek section was rendering as literal code) - Remove duplicate "User Manual" link that pointed to same docs/GUIDE.md already linked as "Guide" in the same paragraph - Correct "NodeCrypto" to "WebCrypto" for Node.js runtime — CLI and WarpGraph use WebCryptoAdapter across all runtimes - Normalize list markers from `* ` to `- ` for consistency (8 items) - Replace bare "Cache management" comment with descriptive per-command comments matching the style of adjacent seek examples --- README.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 70bfaf1b..85568144 100644 --- a/README.md +++ b/README.md @@ -68,11 +68,10 @@ const result = await graph.query() If you are new to git-warp, start with the **[Guide](docs/GUIDE.md)**. For deeper dives: -* **[User Manual](docs/GUIDE.md)**: Comprehensive guide to queries, traversals, and multi-writer sync. -* **[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. +- **[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 @@ -550,6 +549,7 @@ git warp history --writer alice # Check graph health, status, and GC metrics git warp check +``` ### Time-Travel (Seek) @@ -570,9 +570,11 @@ git warp seek --load before-refactor # Return to the present and clear the cursor git warp seek --latest -# Cache management -git warp seek --clear-cache # purge persistent seek cache -git warp seek --no-persistent-cache --tick 5 # skip cache for one invocation +# 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. @@ -730,9 +732,9 @@ This package is the reference implementation of WARP (Worldline Algebra for Recu 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 & NodeCrypto) -* **Bun**: v1.1+ (WASM Roaring fallback & WebCrypto) -* **Deno**: v2.0+ (WASM Roaring fallback & WebCrypto) +- **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. From b46658ed2ac0aded97c4b53ea5419495335743e2 Mon Sep 17 00:00:00 2001 From: James Ross Date: Fri, 6 Mar 2026 12:04:43 -0800 Subject: [PATCH 4/6] docs: update CHANGELOG with review fixes --- CHANGELOG.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 49e79205..12c09481 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Documentation enhancements in README.md** — Added a high-level Documentation Map, a detailed Graph Traversal Directory (listing 11+ algorithms), 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. +### Fixed + +- **Broken code fence in CLI section** — The `bash` fence before the Time-Travel (Seek) heading was never closed, causing the entire Seek section and visualize example to render as literal monospace text. +- **Incorrect crypto adapter claim** — Runtime Compatibility section incorrectly stated Node.js uses "NodeCrypto"; all runtimes use WebCrypto (`globalThis.crypto.subtle`). +- **Duplicate documentation link** — "User Manual" and "Guide" in the Documentation Map both pointed to `docs/GUIDE.md`; removed the redundant entry. +- **Inconsistent list markers** — Normalized `* ` markers to `- ` to match the rest of the README. + ## [13.1.0] - 2026-03-04 ### Added From a10f89e3a252dfbd77627b40ddf936cf819381fb Mon Sep 17 00:00:00 2001 From: James Ross Date: Fri, 6 Mar 2026 12:09:04 -0800 Subject: [PATCH 5/6] docs: complete traversal directory, remove phantom changelog fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add Common Ancestors and Root Ancestors to Graph Traversal Directory - Update algorithm count from "11+" to 15 (matches actual public API) - Remove "Fixed" CHANGELOG section that described bugs introduced and corrected within this branch — never existed in a released version --- CHANGELOG.md | 9 +-------- README.md | 3 ++- 2 files changed, 3 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 12c09481..02066f3e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,16 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- **Documentation enhancements in README.md** — Added a high-level Documentation Map, a detailed Graph Traversal Directory (listing 11+ algorithms), an expanded Time-Travel (Seek) guide, and updated Runtime Compatibility information (Node.js, Bun, Deno). +- **Documentation enhancements in README.md** — Added a high-level Documentation Map, a detailed Graph Traversal Directory (listing all 15 algorithms), 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. -### Fixed - -- **Broken code fence in CLI section** — The `bash` fence before the Time-Travel (Seek) heading was never closed, causing the entire Seek section and visualize example to render as literal monospace text. -- **Incorrect crypto adapter claim** — Runtime Compatibility section incorrectly stated Node.js uses "NodeCrypto"; all runtimes use WebCrypto (`globalThis.crypto.subtle`). -- **Duplicate documentation link** — "User Manual" and "Guide" in the Documentation Map both pointed to `docs/GUIDE.md`; removed the redundant entry. -- **Inconsistent list markers** — Normalized `* ` markers to `- ` to match the rest of the README. - ## [13.1.0] - 2026-03-04 ### Added diff --git a/README.md b/README.md index 85568144..e0e53378 100644 --- a/README.md +++ b/README.md @@ -331,13 +331,14 @@ const canReach = await graph.traverse.isReachable('user:alice', 'user:bob', { ### Graph Traversal Directory -git-warp includes a high-performance traversal engine with 11+ deterministic algorithms: +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) | From f0afc04bf3f13a81c5de2a796ea98e201e4251f9 Mon Sep 17 00:00:00 2001 From: James Ross Date: Fri, 6 Mar 2026 12:10:40 -0800 Subject: [PATCH 6/6] docs: drop brittle algorithm count from CHANGELOG entry --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 02066f3e..b6cd7120 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- **Documentation enhancements in README.md** — Added a high-level Documentation Map, a detailed Graph Traversal Directory (listing all 15 algorithms), an expanded Time-Travel (Seek) guide, and updated Runtime Compatibility information (Node.js, Bun, Deno). +- **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