test(sync): add no-coordination regression suite

[flyingrobots]

Summary

• add no-coordination regression suite covering merge-commit avoidance and head-peek guard
• fuzz random sync/write interleavings with deterministic see
• enforce lint + CLI bats on pre-push and auto-configure hooks on install
• document invariant in CONTRIBUTING and mark M4.3 complete

Testing

• npm run test:local -- test/unit/domain/WarpGraph.noCoordination.test.js

Summary by CodeRabbit

• New Features

  • New CLIs: warp-graph and git-warp for info, query, path, history and health checks
  • Multi-writer WARP API: patch-based edits, materialization, checkpoints, writer discovery and sync
  • Fluent query builder and expanded traversal/pathfinding APIs (BFS/DFS/Dijkstra/A*/shortest/etc.)

• Documentation

  • Large set of guides, examples, specs, runnable HTML demos, and migration/architecture docs

• Chores

  • CI updated to run Docker-based CLI bats tests; package and install scripts updated (v7.0.0)

[coderabbitai]

Actionable comments posted: 7

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

package.json (1)

33-69: ⚠️ Potential issue | 🟠 Major

Move patch-package to dependencies—it's required for postinstall.

When installed as a dependency, npm doesn't install devDependencies, so the postinstall script will fail with patch-package: command not found. Since patches must be applied during installation (e.g., @mapbox+node-pre-gyp+2.0.3.patch), move patch-package to dependencies to ensure it's available for consumers.

🔧 Suggested fix

   "dependencies": {
     "@git-stunts/alfred": "^0.4.0",
     "@git-stunts/plumbing": "^2.8.0",
     "@git-stunts/trailer-codec": "^2.1.1",
     "cbor-x": "^1.6.0",
+    "patch-package": "^8.0.0",
     "roaring": "^2.7.0",
     "zod": "^3.24.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
     "@git-stunts/docker-guard": "^0.1.0",
     "eslint": "^9.17.0",
     "fast-check": "^4.5.3",
-    "patch-package": "^8.0.0",
     "prettier": "^3.4.2",
     "vitest": "^2.1.8"
   },

🤖 Fix all issues with AI agents

In `@ARCHITECTURE.md`:
- Around line 52-90: The markdown diagram in ARCHITECTURE.md uses opening code
fences like ```text but incorrectly closes them with ```text (e.g., the
WarpGraph diagram block containing "WarpGraph (WarpGraph.js)" and the
surrounding Ports/Adapters sections); update each mismatched fence to close with
a plain triple backtick (```) so the block opens with ```text and closes with
```, and fix the same pattern at the other reported locations (lines noted in
the review) to ensure standard Markdown fencing for all code blocks.

In `@bin/warp-graph.js`:
- Around line 914-916: The check that throws usageError when writerId is falsy
is unreachable because options.writer has a default of 'cli'; either remove the
conditional that checks writerId (and the usageError call) so the default 'cli'
is used, or change the default for options.writer to null/undefined where
options are defined so the existing guard (the writerId check in the code that
throws usageError) can meaningfully enforce an explicit --writer; update the
option definition (the symbol options.writer) or the guard around
writerId/usageError accordingly to choose one of these two behaviors.

In `@CHANGELOG.md`:
- Around line 41-47: The two list items under the "### Documentation" section
("Hook docs updated in README/CONTRIBUTING" and "Example imports clarified for
external consumers") have an extra leading space breaking list indentation and
triggering MD005; edit CHANGELOG.md to remove the extra space so all bullet
lines under "### Documentation" align with the other list entries (same indent
as "- **`docs/V7_TEST_MAPPING.md`** ..."), verify the bullets use consistent "-"
prefix and spacing, and re-run markdown linting to confirm MD005 is resolved.

In `@index.d.ts`:
- Around line 894-896: The type declaration for createPatch is wrong because the
implementation in src/domain/WarpGraph.js is async; update the signature of
createPatch in the declaration file to return a Promise (e.g., change
createPatch(): unknown to createPatch(): Promise<unknown> or a more specific
Promise<T> if you can infer the real return type), keeping the function name
createPatch to match the implementation.
- Around line 885-891: The .d.ts for WarpGraph.open is inconsistent with
runtime: change the open() options so writerId is required (remove the ? from
writerId) and add gcPolicy as an optional property (e.g. gcPolicy?: GcPolicy) to
match the implementation that calls validateWriterId(writerId) and accepts a
gcPolicy default; ensure the added GcPolicy type name matches the actual
exported type used elsewhere in the codebase (or import it) and keep other
option names (graphName, persistence, logger, adjacencyCacheSize) unchanged.

In `@package.json`:
- Around line 71-81: The package.json "files" array omits the CLI executable
bin/git-warp so it won't be included in published packages; update the "files"
array entry list (the array containing "bin/warp-graph.js", "src", "index.js",
etc.) to include "bin/git-warp" so the CLI file is bundled when publishing, and
verify package.json's "bin" mapping (if present) still points to the correct
path.

In `@README.md`:
- Around line 1189-1202: Update the Quick Start import to use the correct
package scope: change the module specifier from 'empty-graph' to
'@git-stunts/empty-graph' where EmptyGraph and GitGraphAdapter are imported so
the import line reads import { EmptyGraph, GitGraphAdapter } from
'@git-stunts/empty-graph'; (leave the rest of the example, including Plumbing
from '@git-stunts/plumbing', unchanged).

🧹 Nitpick comments (4)

eslint.config.js (1)

106-118: Optional: prevent Node globals in browser assets.
Because the base config declares Node globals, browser asset scripts can still use process/Buffer/global without lint errors. Consider disabling them here to catch accidental Node-only usage.

♻️ Suggested tweak

   {
     files: ["examples/html/assets/**/*.js"],
     languageOptions: {
       globals: {
         window: "readonly",
         document: "readonly",
         localStorage: "readonly",
         CustomEvent: "readonly",
-        Viz: "readonly"
+        Viz: "readonly",
+        process: "off",
+        Buffer: "off",
+        global: "off"
       }
     }
   },

examples/html/assets/ui.js (1)

270-283: Minor edge case in path matching.

When window.location.pathname is / or ends with /, split('/').pop() returns an empty string. This won't cause errors (just no match), but if root-level highlighting is needed, consider handling this explicitly.

const current = window.location.pathname.split('/').pop() || 'index.html';

examples/html/streaming-benchmark.html (2)

7-8: Consider adding Subresource Integrity (SRI) hashes for CDN resources.

External scripts and stylesheets from CDNs are loaded without integrity attributes. If these CDNs are compromised, malicious code could be injected. For production use, consider adding integrity and crossorigin attributes.

Example:

<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js" 
        integrity="sha384-..." 
        crossorigin="anonymous"></script>

Also applies to: 16-18

---

22-27: Large SVG logo duplicated in masthead and footer.

The same SVG (~15KB) appears twice. Consider extracting it to a separate file or using a <use> reference to reduce HTML size and improve maintainability.

Also applies to: 128-134

[coderabbitai]

Actionable comments posted: 4

🤖 Fix all issues with AI agents

In `@ARCHITECTURE.md`:
- Around line 5-6: Update the overview sentence for WarpGraph to accurately
describe the storage model: either replace "commits as nodes with commit
messages as payloads" with wording that explains WARP's patch-based model (e.g.,
commits represent patch objects/deltas and payloads are patch content with
parent relationships linking patch history) or explicitly mark the current
sentence as the legacy "EmptyGraph" model by naming it (EmptyGraph) and adding a
short note pointing readers to the WARP patch-based model description; ensure
the terms "WarpGraph", "WARP", and "EmptyGraph" appear so readers can find the
detailed sections elsewhere in the doc.
- Around line 361-382: Replace all occurrences of the product name "EmptyGraph"
in the "Core Durability Contract" and "Modes" sections with the correct product
name "WarpGraph" (or explicitly mark any mention as legacy behavior if you
intend to reference historical behavior); update headings and the sentences that
say "EmptyGraph provides mechanisms..." and "In managed/manual mode,
EmptyGraph..." to "WarpGraph provides..." or similar; ensure consistency in the
"Managed Mode (Default)" and "Manual Mode" bullets and any examples so every
durability-related sentence and label refers to WarpGraph (or clearly annotates
legacy references) to avoid ambiguity.

In `@docs/GUIDE.md`:
- Around line 145-147: The import statement for the library is using the wrong
package name; update the import that brings in WarpGraph and GitGraphAdapter to
reference the published scoped package name (replace the unscoped "empty-graph"
import with "@git-stunts/empty-graph") so examples importing WarpGraph and
GitGraphAdapter (and any related examples) use the correct package identifier.
- Around line 128-139: Add the missing public TypeScript declarations for the
checkpoint APIs: update index.d.ts to include method signatures for
createCheckpoint() and materializeAt(checkpointSha: string) (or appropriate
types) on the WarpGraph interface/class so the public type defs match the
implemented methods in src/domain/WarpGraph.js and the documented usage in
GUIDE.md/README.md; ensure the return types align with existing code/tests
(e.g., Promise<string> for createCheckpoint and Promise<StateType> or equivalent
for materializeAt) and export them so consumers see the APIs.

🧹 Nitpick comments (4)

examples/html/assets/style.css (1)

223-226: Make the theme popover keyboard-reachable (:focus-within).

Right now it only appears on hover, so keyboard users won’t see it. Adding :focus-within keeps it accessible without changing behavior for mouse users.

♿ Suggested tweak

-.theme-toggle-wrap:hover .theme-popover {
+.theme-toggle-wrap:hover .theme-popover,
+.theme-toggle-wrap:focus-within .theme-popover {
   opacity: 1;
   transform: translateY(0);
 }

examples/inspect-index.js (1)

44-48: Consider closing the WarpGraph instance after use.

The graph instance opened on line 45 is not explicitly closed after checkpoint creation. For a short-lived CLI script this is acceptable since the process exits, but if WarpGraph has a close() method, calling it would be cleaner for resource hygiene.

examples/streaming-benchmark.js (1)

107-129: Avoid creating an unused patch after the final commit.

When NODE_COUNT is an exact multiple of NODES_PER_PATCH, a new patch is created but never used. This is minor, but easy to avoid.

Optional refactor

     if (nodesInPatch >= NODES_PER_PATCH) {
       await patch.commit();
-      patch = await graph.createPatch();
       nodesInPatch = 0;
+      if (i < NODE_COUNT - 1) {
+        patch = await graph.createPatch();
+      }
     }

docs/ideas/IDEA-001-QUERY-LANGUAGE-AND-TRAVERSAL-ARCHITECTURE.md (1)

171-182: Add language specifier to code blocks for syntax highlighting.

The code block on line 173 (and similarly on lines 207 and 279) lacks a language specifier. Adding javascript enables syntax highlighting and improves readability.

🔧 Proposed fix for line 173

-```
+```javascript
 const query = graph.query()

🔧 Proposed fix for line 207

-```
+```javascript
 for await (const order of graph.query().where({ type: 'order' })) {

🔧 Proposed fix for line 279

-```
+```javascript
 // Example of the "Gut Choice" in action

[coderabbitai]

Actionable comments posted: 3

🤖 Fix all issues with AI agents

In `@examples/html/assets/style.css`:
- Around line 223-227: The visible popover isn't interactive because the base
.theme-popover sets pointer-events: none but the visible state in the
.theme-toggle-wrap:hover .theme-popover and .theme-toggle-wrap:focus-within
.theme-popover rules never restores it; update those selector rules to set
pointer-events: auto (in addition to opacity and transform) so interactive
elements inside .theme-popover (e.g., swatches) become clickable and focusable.
- Around line 272-284: Add a visible keyboard focus style for the interactive
element by extending the .menu-button rule with a .menu-button:focus-visible
selector (or separate block) that sets a clear, accessible outline or box-shadow
and ensures outline-offset and border color contrast (e.g., stronger border or
highlight color and slight outline-offset) while preserving existing
border-radius; update the styles so keyboard focus is not solely reliant on
mouse hover and test that .menu-button:focus-visible appears when tabbing to the
button and does not interfere with existing .menu-button hover/active visuals.
- Around line 140-157: The .theme-toggle lacks a keyboard focus indicator; add a
.theme-toggle:focus-visible rule to provide a clear, high-contrast visible focus
state (e.g., outline or ring using CSS variables like --focus-ring or a fallback
color, or a prominent box-shadow), ensure the transition/positioning works with
the existing .theme-toggle and .theme-toggle:hover rules, and keep the focus
styling accessible without relying on hover (use :focus-visible on the
.theme-toggle element).

🧹 Nitpick comments (3)

examples/streaming-benchmark.js (1)

17-17: Environment variable name inconsistent with WarpGraph refactor.

The environment variable EMPTYGRAPH_MODULE references the old EmptyGraph naming, but the file now uses WarpGraph throughout. Consider renaming to WARPGRAPH_MODULE for consistency.

♻️ Suggested rename

-const modulePath = process.env.EMPTYGRAPH_MODULE || path.resolve(__dirname, '..', 'index.js');
+const modulePath = process.env.WARPGRAPH_MODULE || path.resolve(__dirname, '..', 'index.js');

examples/html/assets/style.css (1)

99-119: Consider combining duplicate .masthead-logo selectors.

The .masthead-logo class is defined twice - consolidating into a single rule block improves maintainability.

♻️ Proposed consolidation

 .masthead-logo {
   display: flex;
   align-items: center;
   flex: 1;
   min-width: 0;
+  width: clamp(320px, 70vw, 920px);
 }

 .masthead-logo svg,
 .footer-logo svg {
   width: 100%;
   height: auto;
   display: block;
 }

 .masthead-logo svg {
   filter: drop-shadow(0 16px 24px rgba(0, 0, 0, 0.25));
 }

-.masthead-logo {
-  width: clamp(320px, 70vw, 920px);
-}

index.d.ts (1)

178-184: Narrow QueryBuilder.select() field types to match runtime validation.

Runtime throws on unknown fields, but the type currently allows any string. This loses TS safety. Consider restricting to 'id' | 'props'.

♻️ Suggested typing refinement

-  select(fields?: string[]): QueryBuilder;
+  select(fields?: Array<'id' | 'props'>): QueryBuilder;