@git-stunts/git-warp 11.5.1 → 12.0.0

package/README.md

@@ -8,6 +8,18 @@
   <img src="docs/images/hero.gif" alt="git-warp CLI demo" width="600">
 </p>
 
+## What's New in v12.0.0
+
+- **MaterializedViewService** — unified service orchestrating build, persist, and load of bitmap indexes and property readers as a single coherent materialized view. Checkpoints now embed the index (schema:4) for instant hydration on open.
+- **GraphTraversal engine (11 algorithms)** — BFS, DFS, shortest path, Dijkstra, A\*, bidirectional A\*, topological sort, longest path, connected component, reachability, and common ancestors. All accessible via `graph.traverse.*`.
+- **NeighborProviderPort abstraction** — decouples traversal algorithms from storage. Two implementations: `AdjacencyNeighborProvider` (in-memory) and `BitmapNeighborProvider` (O(1) bitmap lookups).
+- **Logical bitmap index** — CBOR-sharded Roaring bitmap index with labeled edges, stable numeric IDs, and property indexes. `IncrementalIndexUpdater` enables O(diff) updates.
+- **`nodeWeightFn`** — node-weighted graph algorithms (Dijkstra, A\*, longest path) as an alternative to edge-weight functions.
+- **CLI: `verify-index` and `reindex`** — new commands for index integrity checks and forced rebuilds.
+- **Cross-runtime hardening** — eliminated bare `Buffer` usage across the index subsystem; bitmap indexes now work on Node, Bun, and Deno.
+
+See the [full changelog](CHANGELOG.md) for details.
+
 ## The Core Idea
 
 **git-warp** is a graph database that doesn't need a database server. It stores all its data inside a Git repository by abusing a clever trick: every piece of data is a Git commit that points to the **empty tree** — a special object that exists in every Git repo. Because the commits don't reference any actual files, they're completely invisible to normal Git operations like `git log`, `git diff`, or `git status`. Your codebase stays untouched, but there's a full graph database living alongside it.
@@ -55,9 +67,32 @@ const result = await graph.query()
 
 ## How It Works
 
-<p align="center">
-  <img src="docs/diagrams/fig-data-storage.svg" alt="WARP data storage — invisible to normal Git workflows" width="700">
-</p>
+```mermaid
+flowchart TB
+    subgraph normal["Normal Git Objects"]
+        h["HEAD"] -.-> m["refs/heads/main"]
+        m -.-> c3["C3 · a1b2c3d"]
+        c3 -->|parent| c2["C2 · e4f5a6b"]
+        c2 -->|parent| c1["C1 · 7c8d9e0"]
+        c3 -->|tree| t3["tree"]
+        t3 --> src["src/index.js"]
+        t3 --> pkg["package.json"]
+    end
+
+    subgraph warp["WARP Patch Objects"]
+        wr["refs/warp/myGraph/<br/>writers/alice"] -.-> p3["P3 lamport=3<br/>f1a2b3c"]
+        p3 -->|parent| p2["P2 lamport=2<br/>d4e5f6a"]
+        p2 -->|parent| p1["P1 lamport=1<br/>b7c8d9e"]
+        p3 -->|tree| wt["empty tree"]
+        wt --> pc["patch.cbor"]
+        wt --> cc["_content_*"]
+    end
+
+    vis1["✔ visible to git log"]
+    vis2["✘ invisible to git log<br/>(lives under refs/warp/)"]
+    vis1 ~~~ normal
+    vis2 ~~~ warp
+```
 
 ### The Multi-Writer Problem (and How It's Solved)
 
@@ -77,9 +112,20 @@ Every operation gets a unique **EventId** — `(lamport, writerId, patchSha, opI
 
 ## Multi-Writer Collaboration
 
-<p align="center">
-  <img src="docs/diagrams/fig-multi-writer.svg" alt="Multi-writer convergence — independent chains, deterministic merge" width="700">
-</p>
+```mermaid
+flowchart TB
+    subgraph alice["Alice"]
+        pa1["Pa1 · L=1"] --> pa2["Pa2 · L=2"] --> pa3["Pa3 · L=4"]
+    end
+
+    subgraph bob["Bob"]
+        pb1["Pb1 · L=1"] --> pb2["Pb2 · L=3"]
+    end
+
+    pa3 & pb2 --> sort["Sort by Lamport"]
+    sort --> reducer["JoinReducer<br/>OR-Set merge · LWW merge"]
+    reducer --> state["WarpStateV5<br/>nodeAlive · edgeAlive · prop · frontier"]
+```
 
 Writers operate independently on the same Git repository. Sync happens through standard Git transport (push/pull) or the built-in HTTP sync protocol.
 
@@ -236,6 +282,45 @@ if (result.found) {
 }
 ```
 
+```javascript
+// Weighted shortest path (Dijkstra) with edge weight function
+const weighted = await graph.traverse.weightedShortestPath('city:a', 'city:z', {
+  dir: 'outgoing',
+  weightFn: (from, to, label) => edgeWeights.get(`${from}-${to}`) ?? 1,
+});
+
+// Weighted shortest path with per-node weight function
+const nodeWeighted = await graph.traverse.weightedShortestPath('city:a', 'city:z', {
+  dir: 'outgoing',
+  nodeWeightFn: (nodeId) => nodeDelays.get(nodeId) ?? 0,
+});
+
+// A* search with heuristic
+const astar = await graph.traverse.aStarSearch('city:a', 'city:z', {
+  dir: 'outgoing',
+  heuristic: (nodeId) => euclideanDistance(coords[nodeId], coords['city:z']),
+});
+
+// Topological sort (Kahn's algorithm with cycle detection)
+const sorted = await graph.traverse.topologicalSort('task:root', {
+  dir: 'outgoing',
+  labelFilter: 'depends-on',
+});
+// sorted = ['task:root', 'task:auth', 'task:caching', ...]
+
+// Longest path on DAGs (critical path)
+const critical = await graph.traverse.weightedLongestPath('task:start', 'task:end', {
+  dir: 'outgoing',
+  weightFn: (from, to, label) => taskDurations.get(to) ?? 1,
+});
+
+// Reachability check (fast, no path reconstruction)
+const canReach = await graph.traverse.isReachable('user:alice', 'user:bob', {
+  dir: 'outgoing',
+});
+// canReach = true | false
+```
+
 ## Subscriptions & Reactivity
 
 React to graph changes without polling. Handlers are called after `materialize()` when state has changed.
@@ -465,9 +550,50 @@ When a seek cursor is active, `query`, `info`, `materialize`, and `history` auto
 
 ## Architecture
 
-<p align="center">
-  <img src="docs/diagrams/fig-architecture.svg" alt="Hexagonal architecture — dependency rule: arrows point inward only" width="700">
-</p>
+```mermaid
+flowchart TB
+    subgraph adapters["Adapters — infrastructure implementations"]
+        git["GitGraphAdapter"]
+        cbor["CborCodec"]
+        webcrypto["WebCryptoAdapter"]
+        clocka["ClockAdapter"]
+        consolel["ConsoleLogger"]
+        cascache["CasSeekCacheAdapter"]
+
+        subgraph ports["Ports — abstract interfaces"]
+            pp["GraphPersistencePort"]
+            cp["CodecPort"]
+            crp["CryptoPort"]
+            clp["ClockPort"]
+            lp["LoggerPort"]
+            ip["IndexStoragePort"]
+            sp["SeekCachePort"]
+            np["NeighborProviderPort"]
+
+            subgraph domain["Domain Core"]
+                wg["WarpGraph — main API facade"]
+                jr["JoinReducer"]
+                pb["PatchBuilderV2"]
+                cs["CheckpointService"]
+                qb["QueryBuilder"]
+                lt["LogicalTraversal"]
+                gt["GraphTraversal"]
+                mvs["MaterializedViewService"]
+                crdts["CRDTs: VersionVector · ORSet · LWW"]
+            end
+        end
+    end
+
+    pp -.->|implements| git
+    cp -.->|implements| cbor
+    crp -.->|implements| webcrypto
+    clp -.->|implements| clocka
+    lp -.->|implements| consolel
+    sp -.->|implements| cascache
+    ip -.->|via| git
+
+    wg --> pp & cp & crp & clp & lp & ip & sp
+```
 
 The codebase follows hexagonal architecture with ports and adapters:
 
@@ -480,6 +606,7 @@ The codebase follows hexagonal architecture with ports and adapters:
 - `LoggerPort` -- structured logging
 - `ClockPort` -- time measurement
 - `SeekCachePort` -- persistent seek materialization cache
+- `NeighborProviderPort` -- abstract neighbor lookup interface
 
 **Adapters** implement the ports:
 - `GitGraphAdapter` -- wraps `@git-stunts/plumbing` for Git operations
@@ -496,7 +623,12 @@ The codebase follows hexagonal architecture with ports and adapters:
 - `Writer` / `PatchSession` -- patch creation and commit
 - `JoinReducer` -- CRDT-based state materialization
 - `QueryBuilder` -- fluent query construction
-- `LogicalTraversal` -- graph traversal over materialized state
+- `LogicalTraversal` -- deprecated facade, delegates to GraphTraversal
+- `GraphTraversal` -- unified traversal engine (11 algorithms, `nodeWeightFn`)
+- `MaterializedViewService` -- orchestrate build/persist/load of materialized views
+- `IncrementalIndexUpdater` -- O(diff) bitmap index updates
+- `LogicalIndexBuildService` / `LogicalIndexReader` -- logical bitmap indexes
+- `AdjacencyNeighborProvider` / `BitmapNeighborProvider` -- neighbor provider implementations
 - `SyncProtocol` -- multi-writer synchronization
 - `CheckpointService` -- state snapshot creation and loading
 - `ObserverView` -- read-only filtered graph projections

package/bin/cli/commands/registry.js

@@ -7,6 +7,8 @@ import handleDoctor from './doctor/index.js';
 import handleMaterialize from './materialize.js';
 import handleSeek from './seek.js';
 import handleVerifyAudit from './verify-audit.js';
+import handleVerifyIndex from './verify-index.js';
+import handleReindex from './reindex.js';
 import handleView from './view.js';
 import handleInstallHooks from './install-hooks.js';
 import handleTrust from './trust.js';
@@ -24,6 +26,8 @@ export const COMMANDS = new Map(/** @type {[string, Function][]} */ ([
   ['materialize', handleMaterialize],
   ['seek', handleSeek],
   ['verify-audit', handleVerifyAudit],
+  ['verify-index', handleVerifyIndex],
+  ['reindex', handleReindex],
   ['trust', handleTrust],
   ['patch', handlePatch],
   ['tree', handleTree],

package/bin/cli/commands/reindex.js

@@ -0,0 +1,41 @@
+import { EXIT_CODES, parseCommandArgs } from '../infrastructure.js';
+import { reindexSchema } from '../schemas.js';
+import { openGraph, applyCursorCeiling, emitCursorWarning } from '../shared.js';
+
+/** @typedef {import('../types.js').CliOptions} CliOptions */
+
+/**
+ * Handles the `reindex` command: forces a full bitmap index rebuild
+ * by clearing cached index state and re-materializing.
+ *
+ * @param {{options: CliOptions, args: string[]}} params
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
+ */
+export default async function handleReindex({ options, args }) {
+  parseCommandArgs(args, {}, reindexSchema);
+
+  const { graph, graphName, persistence } = await openGraph(options);
+  const cursorInfo = await applyCursorCeiling(graph, persistence, graphName);
+  emitCursorWarning(cursorInfo, null);
+
+  // Clear cached index to force full rebuild
+  graph.invalidateIndex();
+
+  try {
+    await graph.materialize();
+  } catch (err) {
+    return {
+      payload: { error: /** @type {Error} */ (err).message },
+      exitCode: EXIT_CODES.INTERNAL,
+    };
+  }
+
+  return {
+    payload: {
+      graph: graphName,
+      status: 'ok',
+      message: 'Index rebuilt successfully',
+    },
+    exitCode: EXIT_CODES.OK,
+  };
+}

package/bin/cli/commands/verify-index.js

@@ -0,0 +1,59 @@
+import { EXIT_CODES, parseCommandArgs } from '../infrastructure.js';
+import { verifyIndexSchema } from '../schemas.js';
+import { openGraph, applyCursorCeiling, emitCursorWarning } from '../shared.js';
+
+/** @typedef {import('../types.js').CliOptions} CliOptions */
+
+const VERIFY_INDEX_OPTIONS = {
+  seed: { type: 'string' },
+  'sample-rate': { type: 'string' },
+};
+
+/**
+ * Handles the `verify-index` command: samples alive nodes and cross-checks
+ * bitmap index neighbors against adjacency ground truth.
+ *
+ * @param {{options: CliOptions, args: string[]}} params
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
+ */
+export default async function handleVerifyIndex({ options, args }) {
+  const { values } = parseCommandArgs(
+    args,
+    VERIFY_INDEX_OPTIONS,
+    verifyIndexSchema,
+  );
+  const { graph, graphName, persistence } = await openGraph(options);
+  const cursorInfo = await applyCursorCeiling(graph, persistence, graphName);
+  emitCursorWarning(cursorInfo, null);
+
+  try {
+    await graph.materialize();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      payload: { error: message },
+      exitCode: EXIT_CODES.INTERNAL,
+    };
+  }
+
+  let result;
+  try {
+    result = await graph.verifyIndex({ seed: values.seed, sampleRate: values.sampleRate });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const noIndex = /no bitmap index|cannot verify index|index not built/i.test(message);
+    return {
+      payload: { error: noIndex ? 'No bitmap index available after materialization' : message },
+      exitCode: EXIT_CODES.INTERNAL,
+    };
+  }
+
+  return {
+    payload: {
+      graph: graphName,
+      ...result,
+      totalChecks: result.passed + result.failed,
+    },
+    exitCode: result.failed > 0 ? EXIT_CODES.INTERNAL : EXIT_CODES.OK,
+  };
+}

package/bin/cli/infrastructure.js

@@ -42,6 +42,8 @@ Commands:
   check            Report graph health/GC status
   doctor           Diagnose structural issues and suggest fixes
   verify-audit     Verify audit receipt chain integrity
+  verify-index     Verify bitmap index integrity by sampling
+  reindex          Force full index rebuild
   trust            Evaluate writer trust from signed evidence
   materialize      Materialize and checkpoint all graphs
   seek             Time-travel: step through graph history by Lamport tick
@@ -88,6 +90,10 @@ Verify-audit options:
   --trust-mode <mode>   Trust evaluation mode (warn, enforce)
   --trust-pin <sha>     Pin trust evaluation to a specific record chain commit
 
+Verify-index options:
+  --seed <n>              PRNG seed for reproducible sampling
+  --sample-rate <rate>    Fraction of nodes to verify (>0 and <=1, default 0.1)
+
 Trust options:
   --mode <warn|enforce> Override trust evaluation mode
   --trust-pin <sha>     Pin trust evaluation to a specific record chain commit
@@ -144,7 +150,7 @@ export function notFoundError(message) {
   return new CliError(message, { code: 'E_NOT_FOUND', exitCode: EXIT_CODES.NOT_FOUND });
 }
 
-export const KNOWN_COMMANDS = ['info', 'query', 'path', 'history', 'check', 'doctor', 'materialize', 'seek', 'verify-audit', 'trust', 'patch', 'tree', 'install-hooks', 'view'];
+export const KNOWN_COMMANDS = ['info', 'query', 'path', 'history', 'check', 'doctor', 'materialize', 'seek', 'verify-audit', 'verify-index', 'reindex', 'trust', 'patch', 'tree', 'install-hooks', 'view'];
 
 const BASE_OPTIONS = {
   repo:   { type: 'string', short: 'r' },
@@ -347,4 +353,3 @@ export function parseCommandArgs(args, config, schema, { allowPositionals = fals
 
   return { values: result.data, positionals: parsed.positionals || [] };
 }
-

package/bin/cli/schemas.js

@@ -175,3 +175,22 @@ export const seekSchema = z.object({
     diffLimit: val['diff-limit'],
   };
 });
+
+// ============================================================================
+// Verify-index
+// ============================================================================
+
+export const verifyIndexSchema = z.object({
+  seed: z.coerce.number().int().min(-2147483648).max(2147483647).optional(),
+  'sample-rate': z.coerce.number().gt(0, '--sample-rate must be greater than 0').max(1).optional().default(0.1),
+}).strict().transform((val) => ({
+  seed: val.seed,
+  sampleRate: val['sample-rate'],
+}));
+
+// ============================================================================
+// Reindex
+// ============================================================================
+
+// No command-level options; schema exists for forward compatibility
+export const reindexSchema = z.object({}).strict();

package/bin/cli/types.js

@@ -34,6 +34,8 @@
  * @property {{clear: () => Promise<void>} | null} seekCache
  * @property {number} [_seekCeiling]
  * @property {boolean} [_provenanceDegraded]
+ * @property {(options?: {seed?: number, sampleRate?: number}) => Promise<{passed: number, failed: number, errors: Array<{nodeId: string, direction: string, error: string}>}>} verifyIndex
+ * @property {() => void} invalidateIndex
  */
 
 /**

package/index.d.ts

@@ -238,26 +238,63 @@ export class QueryBuilder {
 /**
  * Logical graph traversal module.
  */
+export interface TraverseFacadeOptions {
+  maxDepth?: number;
+  dir?: 'out' | 'in' | 'both';
+  labelFilter?: string | string[];
+}
+
+export type EdgeWeightFn = (from: string, to: string, label: string) => number | Promise<number>;
+export type NodeWeightFn = (nodeId: string) => number | Promise<number>;
+export type WeightedCostSelector =
+  | { weightFn?: EdgeWeightFn; nodeWeightFn?: never }
+  | { nodeWeightFn?: NodeWeightFn; weightFn?: never };
+
 export interface LogicalTraversal {
-  bfs(start: string, options?: {
+  bfs(start: string, options?: TraverseFacadeOptions): Promise<string[]>;
+  dfs(start: string, options?: TraverseFacadeOptions): Promise<string[]>;
+  shortestPath(from: string, to: string, options?: TraverseFacadeOptions): Promise<{ found: boolean; path: string[]; length: number }>;
+  connectedComponent(start: string, options?: {
     maxDepth?: number;
-    dir?: 'out' | 'in' | 'both';
     labelFilter?: string | string[];
   }): Promise<string[]>;
-  dfs(start: string, options?: {
-    maxDepth?: number;
+  isReachable(from: string, to: string, options?: TraverseFacadeOptions & {
+    signal?: AbortSignal;
+  }): Promise<{ reachable: boolean }>;
+  weightedShortestPath(from: string, to: string, options?: WeightedCostSelector & {
     dir?: 'out' | 'in' | 'both';
     labelFilter?: string | string[];
-  }): Promise<string[]>;
-  shortestPath(from: string, to: string, options?: {
-    maxDepth?: number;
+    signal?: AbortSignal;
+  }): Promise<{ path: string[]; totalCost: number }>;
+  aStarSearch(from: string, to: string, options?: WeightedCostSelector & {
     dir?: 'out' | 'in' | 'both';
     labelFilter?: string | string[];
-  }): Promise<{ found: boolean; path: string[]; length: number }>;
-  connectedComponent(start: string, options?: {
+    heuristicFn?: (nodeId: string, goalId: string) => number;
+    signal?: AbortSignal;
+  }): Promise<{ path: string[]; totalCost: number; nodesExplored: number }>;
+  bidirectionalAStar(from: string, to: string, options?: WeightedCostSelector & {
+    labelFilter?: string | string[];
+    forwardHeuristic?: (nodeId: string, goalId: string) => number;
+    backwardHeuristic?: (nodeId: string, goalId: string) => number;
+    signal?: AbortSignal;
+  }): Promise<{ path: string[]; totalCost: number; nodesExplored: number }>;
+  topologicalSort(start: string | string[], options?: {
+    dir?: 'out' | 'in' | 'both';
+    labelFilter?: string | string[];
+    throwOnCycle?: boolean;
+    signal?: AbortSignal;
+  }): Promise<{ sorted: string[]; hasCycle: boolean }>;
+  commonAncestors(nodes: string[], options?: {
     maxDepth?: number;
     labelFilter?: string | string[];
-  }): Promise<string[]>;
+    maxResults?: number;
+    signal?: AbortSignal;
+  }): Promise<{ ancestors: string[] }>;
+  weightedLongestPath(from: string, to: string, options?: WeightedCostSelector & {
+    dir?: 'out' | 'in' | 'both';
+    labelFilter?: string | string[];
+    signal?: AbortSignal;
+  }): Promise<{ path: string[]; totalCost: number }>;
 }
 
 /**
@@ -486,9 +523,9 @@ export class GlobalClockAdapter extends ClockPort {
  */
 export abstract class SeekCachePort {
   /** Retrieves a cached state buffer by key, or null on miss. */
-  abstract get(key: string): Promise<Buffer | null>;
+  abstract get(key: string): Promise<{ buffer: Buffer | Uint8Array; indexTreeOid?: string } | null>;
   /** Stores a state buffer under the given key. */
-  abstract set(key: string, buffer: Buffer): Promise<void>;
+  abstract set(key: string, buffer: Buffer | Uint8Array, options?: { indexTreeOid?: string }): Promise<void>;
   /** Checks whether a key exists in the cache index. */
   abstract has(key: string): Promise<boolean>;
   /** Lists all keys currently in the cache index. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-warp",
-  "version": "11.5.1",
+  "version": "12.0.0",
   "description": "Deterministic WARP graph over Git: graph-native storage, traversal, and tooling.",
   "type": "module",
   "license": "Apache-2.0",
@@ -107,7 +107,7 @@
     "roaring": "^2.7.0",
     "string-width": "^7.1.0",
     "wrap-ansi": "^9.0.0",
-    "zod": "^3.24.1"
+    "zod": "3.24.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",

package/src/domain/WarpGraph.js

@@ -19,6 +19,7 @@ import defaultClock from './utils/defaultClock.js';
 import LogicalTraversal from './services/LogicalTraversal.js';
 import LRUCache from './utils/LRUCache.js';
 import SyncController from './services/SyncController.js';
+import MaterializedViewService from './services/MaterializedViewService.js';
 import { wireWarpMethods } from './warp/_wire.js';
 import * as queryMethods from './warp/query.methods.js';
 import * as subscribeMethods from './warp/subscribe.methods.js';
@@ -40,6 +41,7 @@ const DEFAULT_ADJACENCY_CACHE_SIZE = 3;
  * @property {import('./services/JoinReducer.js').WarpStateV5} state
  * @property {string} stateHash
  * @property {{outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>>}} adjacency
+ * @property {import('./services/BitmapNeighborProvider.js').default} [provider]
  */
 
 /**
@@ -175,6 +177,24 @@ export default class WarpGraph {
 
     /** @type {SyncController} */
     this._syncController = new SyncController(this);
+
+    /** @type {MaterializedViewService} */
+    this._viewService = new MaterializedViewService({
+      codec: this._codec,
+      logger: this._logger || undefined,
+    });
+
+    /** @type {import('./services/BitmapNeighborProvider.js').LogicalIndex|null} */
+    this._logicalIndex = null;
+
+    /** @type {import('./services/PropertyIndexReader.js').default|null} */
+    this._propertyReader = null;
+
+    /** @type {string|null} */
+    this._cachedViewHash = null;
+
+    /** @type {Record<string, Uint8Array>|null} */
+    this._cachedIndexTree = null;
   }
 
   /**
@@ -218,6 +238,21 @@ export default class WarpGraph {
     }
   }
 
+  /**
+   * Extracts the maximum Lamport timestamp from a WarpStateV5.
+   *
+   * @param {import('./services/JoinReducer.js').WarpStateV5} state
+   * @returns {number} Maximum Lamport value (0 if frontier is empty)
+   * @private
+   */
+  _maxLamportFromState(state) {
+    let max = 0;
+    for (const v of state.observedFrontier.values()) {
+      if (v > max) { max = v; }
+    }
+    return max;
+  }
+
   /**
    * Opens a multi-writer graph.
    *
@@ -380,6 +415,11 @@ export default class WarpGraph {
           }
           return this._sortPatchesCausally(allPatches);
         },
+        loadCheckpoint: async () => {
+          const ck = await this._loadLatestCheckpoint();
+          if (!ck) { return null; }
+          return { state: ck.state, maxLamport: this._maxLamportFromState(ck.state) };
+        },
       });
     }
     return this._temporalQuery;

package/src/domain/errors/ShardIdOverflowError.js

@@ -0,0 +1,28 @@
+import IndexError from './IndexError.js';
+
+/**
+ * Thrown when a shard's local ID counter exceeds 2^24.
+ *
+ * Each shard byte supports up to 2^24 local IDs. When this limit
+ * is reached, no more nodes can be registered in that shard.
+ *
+ * The `code` property is set to `'E_SHARD_ID_OVERFLOW'` and is correctly
+ * forwarded through the IndexError -> WarpError chain: IndexError passes
+ * the options object to WarpError, which prefers `options.code` over its
+ * default code (`'INDEX_ERROR'`).
+ *
+ * @class ShardIdOverflowError
+ * @extends IndexError
+ */
+export default class ShardIdOverflowError extends IndexError {
+  /**
+   * @param {string} message
+   * @param {{ shardKey: string, nextLocalId: number }} context
+   */
+  constructor(message, { shardKey, nextLocalId }) {
+    super(message, {
+      code: 'E_SHARD_ID_OVERFLOW',
+      context: { shardKey, nextLocalId },
+    });
+  }
+}

package/src/domain/errors/index.js

@@ -12,6 +12,7 @@ export { default as OperationAbortedError } from './OperationAbortedError.js';
 export { default as QueryError } from './QueryError.js';
 export { default as SyncError } from './SyncError.js';
 export { default as ShardCorruptionError } from './ShardCorruptionError.js';
+export { default as ShardIdOverflowError } from './ShardIdOverflowError.js';
 export { default as ShardLoadError } from './ShardLoadError.js';
 export { default as ShardValidationError } from './ShardValidationError.js';
 export { default as StorageError } from './StorageError.js';