@git-stunts/git-warp 10.8.0 → 11.3.3

package/index.d.ts

@@ -558,6 +558,25 @@ export interface GitPlumbing {
   executeStream(options: { args: string[] }): Promise<AsyncIterable<Uint8Array> & { collect(opts?: { asString?: boolean }): Promise<Buffer | string> }>;
 }
 
+/**
+ * In-memory persistence adapter for fast unit/integration tests.
+ *
+ * Implements the same GraphPersistencePort contract as GitGraphAdapter
+ * but stores all data in Maps — no real Git I/O required.
+ */
+export class InMemoryGraphAdapter extends GraphPersistencePort {
+  constructor();
+
+  get emptyTree(): string;
+  commitNode(options: CreateNodeOptions): Promise<string>;
+  showNode(sha: string): Promise<string>;
+  getNodeInfo(sha: string): Promise<NodeInfo>;
+  logNodesStream(options: ListNodesOptions & { format: string }): Promise<AsyncIterable<Uint8Array | string>>;
+  logNodes(options: ListNodesOptions & { format: string }): Promise<string>;
+  ping(): Promise<PingResult>;
+  countNodes(ref: string): Promise<number>;
+}
+
 /**
  * Implementation of GraphPersistencePort and IndexStoragePort using GitPlumbing.
  */
@@ -1022,7 +1041,7 @@ export class SyncError extends Error {
  * Base error class for bitmap index operations.
  */
 export class IndexError extends Error {
-  readonly name: 'IndexError';
+  readonly name: string;
   readonly code: string;
   readonly context: Record<string, unknown>;
 
@@ -1283,12 +1302,65 @@ export interface TemporalQuery {
   ): Promise<boolean>;
 }
 
+// ============================================================================
+// PatchV2 & PatchBuilderV2
+// ============================================================================
+
+/**
+ * WARP V5 patch object (schema 2 or 3).
+ */
+export interface PatchV2 {
+  /** Schema version (2 for node/edge ops, 3 if edge properties present) */
+  schema: 2 | 3;
+  /** Writer ID */
+  writer: string;
+  /** Lamport timestamp for ordering */
+  lamport: number;
+  /** Writer's observed frontier (version vector) */
+  context: Record<string, number>;
+  /** Ordered array of operations */
+  ops: unknown[];
+  /** Node/edge IDs read by this patch (provenance tracking) */
+  reads?: string[];
+  /** Node/edge IDs written by this patch (provenance tracking) */
+  writes?: string[];
+}
+
+/**
+ * Fluent builder for creating WARP v5 patches with OR-Set semantics.
+ *
+ * Returned by WarpGraph.createPatch(). Chain mutation methods then call
+ * commit() to persist the patch atomically.
+ */
+export class PatchBuilderV2 {
+  /** Adds a node to the graph. */
+  addNode(nodeId: string): PatchBuilderV2;
+  /** Removes a node from the graph. */
+  removeNode(nodeId: string): PatchBuilderV2;
+  /** Adds an edge between two nodes. */
+  addEdge(from: string, to: string, label: string): PatchBuilderV2;
+  /** Removes an edge between two nodes. */
+  removeEdge(from: string, to: string, label: string): PatchBuilderV2;
+  /** Sets a property on a node. */
+  setProperty(nodeId: string, key: string, value: unknown): PatchBuilderV2;
+  /** Sets a property on an edge. */
+  setEdgeProperty(from: string, to: string, label: string, key: string, value: unknown): PatchBuilderV2;
+  /** Builds the PatchV2 object without committing. */
+  build(): PatchV2;
+  /** Commits the patch to the graph and returns the commit SHA. */
+  commit(): Promise<string>;
+  /** Number of operations in this patch. */
+  readonly opCount: number;
+}
+
 // ============================================================================
 // Writer & PatchSession
 // ============================================================================
 
 /**
  * Fluent patch session for building and committing graph mutations.
+ *
+ * Created by Writer.beginPatch(). Wraps a PatchBuilderV2 with CAS protection.
  */
 export class PatchSession {
   /** Adds a node to the graph. */
@@ -1301,8 +1373,10 @@ export class PatchSession {
   removeEdge(from: string, to: string, label: string): this;
   /** Sets a property on a node. */
   setProperty(nodeId: string, key: string, value: unknown): this;
-  /** Builds the patch object without committing. */
-  build(): unknown;
+  /** Sets a property on an edge. */
+  setEdgeProperty(from: string, to: string, label: string, key: string, value: unknown): this;
+  /** Builds the PatchV2 object without committing. */
+  build(): PatchV2;
   /** Commits the patch with CAS protection. */
   commit(): Promise<string>;
   /** Number of operations in this patch. */
@@ -1321,7 +1395,10 @@ export class Writer {
   head(): Promise<string | null>;
   /** Begins a new patch session. */
   beginPatch(): Promise<PatchSession>;
-  /** Builds and commits a patch in one call. */
+  /**
+   * Builds and commits a patch in one call.
+   * @throws {WriterError} COMMIT_IN_PROGRESS if called while another commitPatch() is in progress (not reentrant)
+   */
   commitPatch(build: (p: PatchSession) => void | Promise<void>): Promise<string>;
 }
 
@@ -1419,6 +1496,7 @@ export interface ApplySyncResult {
 export interface SyncAuthServerOptions {
   keys: Record<string, string>;
   mode?: 'enforce' | 'log-only';
+  allowedWriters?: string[];
 }
 
 /**
@@ -1485,6 +1563,7 @@ export default class WarpGraph {
       compactOnCheckpoint?: boolean;
     };
     checkpointPolicy?: { every: number };
+    /** If true (default), query methods auto-materialize when no cached state exists. */
     autoMaterialize?: boolean;
     onDeleteWithData?: 'reject' | 'cascade' | 'warn';
     clock?: ClockPort;
@@ -1510,9 +1589,21 @@ export default class WarpGraph {
   setSeekCache(cache: SeekCachePort | null): void;
 
   /**
-   * Creates a new patch for adding operations.
+   * Creates a new PatchBuilderV2 for adding operations.
+   */
+  createPatch(): Promise<PatchBuilderV2>;
+
+  /**
+   * Convenience wrapper: creates a patch, runs the callback, and commits.
+   *
+   * The callback receives a PatchBuilderV2 and may be synchronous or
+   * asynchronous. The commit happens only after the callback resolves.
+   * If the callback throws or rejects, no commit is attempted.
+   *
+   * Not reentrant: calling `graph.patch()` inside a callback throws.
+   * Use `createPatch()` directly for nested or concurrent patches.
    */
-  createPatch(): Promise<unknown>;
+  patch(build: (patch: PatchBuilderV2) => void | Promise<void>): Promise<string>;
 
   /**
    * Returns patches from a writer's ref chain.
@@ -1520,7 +1611,7 @@ export default class WarpGraph {
   getWriterPatches(
     writerId: string,
     stopAtSha?: string | null
-  ): Promise<Array<{ patch: unknown; sha: string }>>;
+  ): Promise<Array<{ patch: PatchV2; sha: string }>>;
 
   /**
    * Gets all visible nodes in the materialized state.
@@ -1592,7 +1683,7 @@ export default class WarpGraph {
   /**
    * Materializes graph state from a checkpoint, applying incremental patches.
    */
-  materializeAt(checkpointSha: string): Promise<unknown>;
+  materializeAt(checkpointSha: string): Promise<WarpStateV5>;
 
   /**
    * Logical graph traversal helpers.
@@ -1625,8 +1716,12 @@ export default class WarpGraph {
 
   /**
    * Materializes the current graph state from all patches.
+   *
+   * When `options.receipts` is true, returns `{ state, receipts }`.
+   * Otherwise returns the WarpStateV5 directly.
    */
-  materialize(): Promise<unknown>;
+  materialize(options: { receipts: true; ceiling?: number | null }): Promise<{ state: WarpStateV5; receipts: TickReceipt[] }>;
+  materialize(options?: { receipts?: false; ceiling?: number | null }): Promise<WarpStateV5>;
 
   /**
    * Starts a built-in sync server for this graph.
@@ -1638,10 +1733,13 @@ export default class WarpGraph {
     maxRequestBytes?: number;
     httpPort: HttpServerPort;
     auth?: SyncAuthServerOptions;
+    allowedWriters?: string[];
   }): Promise<{ close(): Promise<void>; url: string }>;
 
   /**
    * Syncs with a remote peer (HTTP URL or another WarpGraph instance).
+   *
+   * When `options.materialize` is true, the returned object also contains a `state` property.
    */
   syncWith(remote: string | WarpGraph, options?: {
     path?: string;
@@ -1658,7 +1756,9 @@ export default class WarpGraph {
       error?: Error;
     }) => void;
     auth?: SyncAuthClientOptions;
-  }): Promise<{ applied: number; attempts: number }>;
+    /** Auto-materialize after sync; when true, result includes `state` */
+    materialize?: boolean;
+  }): Promise<{ applied: number; attempts: number; state?: WarpStateV5 }>;
 
   /**
    * Creates a fork of this graph at a specific point in a writer's history.
@@ -2083,17 +2183,7 @@ export function migrateV4toV5(v4State: {
  */
 export interface PatchEntry {
   /** The decoded patch object */
-  patch: {
-    schema: 2 | 3;
-    writer: string;
-    lamport: number;
-    context: Record<string, number> | Map<string, number>;
-    ops: unknown[];
-    /** Node/edge IDs read by this patch (V2 provenance) */
-    reads?: string[];
-    /** Node/edge IDs written by this patch (V2 provenance) */
-    writes?: string[];
-  };
+  patch: PatchV2;
   /** The Git SHA of the patch commit */
   sha: string;
 }

package/index.js

@@ -33,6 +33,7 @@ import IndexStoragePort from './src/ports/IndexStoragePort.js';
 import LoggerPort from './src/ports/LoggerPort.js';
 import ClockPort from './src/ports/ClockPort.js';
 import SeekCachePort from './src/ports/SeekCachePort.js';
+import InMemoryGraphAdapter from './src/infrastructure/adapters/InMemoryGraphAdapter.js';
 import NoOpLogger from './src/infrastructure/adapters/NoOpLogger.js';
 import ConsoleLogger, { LogLevel } from './src/infrastructure/adapters/ConsoleLogger.js';
 import ClockAdapter from './src/infrastructure/adapters/ClockAdapter.js';
@@ -107,6 +108,7 @@ const TraversalService = CommitDagTraversalService;
 
 export {
   GitGraphAdapter,
+  InMemoryGraphAdapter,
   GraphNode,
   BitmapIndexBuilder,
   BitmapIndexReader,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-warp",
-  "version": "10.8.0",
+  "version": "11.3.3",
   "description": "Deterministic WARP graph over Git: graph-native storage, traversal, and tooling.",
   "type": "module",
   "license": "Apache-2.0",
@@ -43,6 +43,7 @@
   "files": [
     "bin/warp-graph.js",
     "bin/presenters",
+    "bin/cli",
     "bin/git-warp",
     "src",
     "index.js",
@@ -68,16 +69,16 @@
     "benchmark": "sh -c 'if [ \"$GIT_STUNTS_DOCKER\" = \"1\" ]; then vitest bench --run test/benchmark \"$@\"; else docker compose run --build --rm test npm run benchmark:local -- \"$@\"; fi' --",
     "benchmark:local": "vitest bench --run test/benchmark",
     "demo": "cd examples && docker compose up -d && docker compose exec demo bash",
-    "demo:setup": "cd examples && docker compose up -d && docker compose exec demo sh -c 'cd /app && npm install --silent && cd /demo && node /app/examples/setup.js'",
-    "demo:explore": "cd examples && docker compose exec demo node /app/examples/explore.js",
-    "demo:inspect": "cd examples && docker compose exec demo node /app/examples/inspect-index.js",
-    "demo:lagrangian": "cd examples && docker compose exec demo node /app/examples/lagrangian-path.js",
-    "demo:bench-streaming": "cd examples && docker compose up -d && docker compose exec demo node /app/examples/streaming-benchmark.js",
-    "demo:bench-traversal": "cd examples && docker compose up -d && docker compose exec demo node /app/examples/traversal-benchmark.js",
+    "demo:setup": "cd examples && docker compose up -d && docker compose exec demo sh -c 'cd /app && npm install --silent && cd /demo && node /app/examples/scripts/setup.js'",
+    "demo:explore": "cd examples && docker compose exec demo node /app/examples/scripts/explore.js",
+    "demo:inspect": "cd examples && docker compose exec demo node /app/examples/scripts/inspect-index.js",
+    "demo:lagrangian": "cd examples && docker compose exec demo node /app/examples/scripts/lagrangian-path.js",
+    "demo:bench-streaming": "cd examples && docker compose up -d && docker compose exec demo node /app/examples/scripts/streaming-benchmark.js",
+    "demo:bench-traversal": "cd examples && docker compose up -d && docker compose exec demo node /app/examples/scripts/traversal-benchmark.js",
     "demo:down": "cd examples && docker compose down -v",
     "setup:hooks": "node scripts/setup-hooks.js",
     "prepare": "patch-package && node scripts/setup-hooks.js",
-    "prepack": "npm run lint && npm run test:local",
+    "prepack": "npm run lint && npm run test:local && npm run typecheck:consumer",
     "install:git-warp": "bash scripts/install-git-warp.sh",
     "uninstall:git-warp": "bash scripts/uninstall-git-warp.sh",
     "test:node20": "docker compose -f docker-compose.test.yml --profile node20 run --build --rm test-node20",
@@ -88,6 +89,7 @@
     "typecheck": "tsc --noEmit",
     "typecheck:src": "tsc --noEmit -p tsconfig.src.json",
     "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
+    "typecheck:consumer": "tsc --noEmit -p test/type-check/tsconfig.json",
     "typecheck:policy": "node scripts/ts-policy-check.js"
   },
   "dependencies": {