@git-stunts/git-warp 11.5.1 → 12.1.0

package/src/domain/warp/materializeAdvanced.methods.js

@@ -18,6 +18,7 @@ import { serializeFullStateV5, deserializeFullStateV5 } from '../services/Checkp
 import { buildSeekCacheKey } from '../utils/seekCacheKey.js';
 import { materializeIncremental } from '../services/CheckpointService.js';
 import { createFrontier, updateFrontier } from '../services/Frontier.js';
+import BitmapNeighborProvider from '../services/BitmapNeighborProvider.js';
 
 /** @typedef {import('../types/WarpPersistence.js').CorePersistence} CorePersistence */
 /** @typedef {import('../services/JoinReducer.js').WarpStateV5} WarpStateV5 */
@@ -106,10 +107,11 @@ export function _buildAdjacency(state) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {import('../services/JoinReducer.js').WarpStateV5} state
+ * @param {import('../types/PatchDiff.js').PatchDiff} [diff] - Optional diff for incremental index
  * @returns {Promise<MaterializedResult>}
  * @private
  */
-export async function _setMaterializedState(state) {
+export async function _setMaterializedState(state, diff) {
   this._cachedState = state;
   this._stateDirty = false;
   this._versionVector = vvClone(state.observedFrontier);
@@ -128,9 +130,58 @@ export async function _setMaterializedState(state) {
   }
 
   this._materializedGraph = { state, stateHash, adjacency };
+  this._buildView(state, stateHash, diff);
   return this._materializedGraph;
 }
 
+/**
+ * Builds the MaterializedView (logicalIndex + propertyReader) and attaches
+ * a BitmapNeighborProvider to the materialized graph. Skips rebuild when
+ * the stateHash matches the previous build. Uses incremental update when
+ * a diff and cached index tree are available.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {import('../services/JoinReducer.js').WarpStateV5} state
+ * @param {string} stateHash
+ * @param {import('../types/PatchDiff.js').PatchDiff} [diff] - Optional diff for incremental update
+ * @private
+ */
+export function _buildView(state, stateHash, diff) {
+  if (this._cachedViewHash === stateHash) {
+    return;
+  }
+  try {
+    /** @type {import('../services/MaterializedViewService.js').BuildResult} */
+    let result;
+    if (diff && this._cachedIndexTree) {
+      result = this._viewService.applyDiff({
+        existingTree: this._cachedIndexTree,
+        diff,
+        state,
+      });
+    } else {
+      result = this._viewService.build(state);
+    }
+
+    this._logicalIndex = result.logicalIndex;
+    this._propertyReader = result.propertyReader;
+    this._cachedViewHash = stateHash;
+    this._cachedIndexTree = result.tree;
+
+    const provider = new BitmapNeighborProvider({ logicalIndex: result.logicalIndex });
+    if (this._materializedGraph) {
+      this._materializedGraph.provider = provider;
+    }
+  } catch (err) {
+    this._logger?.warn('[warp] index build failed, falling back to linear scan', {
+      error: /** @type {Error} */ (err).message,
+    });
+    this._logicalIndex = null;
+    this._propertyReader = null;
+    this._cachedIndexTree = null;
+  }
+}
+
 /**
  * Materializes the graph with a Lamport ceiling (time-travel).
  *
@@ -196,12 +247,15 @@ export async function _materializeWithCeiling(ceiling, collectReceipts, t0) {
       const cached = await this._seekCache.get(cacheKey);
       if (cached) {
         try {
-          const state = deserializeFullStateV5(cached, { codec: this._codec });
+          const state = deserializeFullStateV5(cached.buffer, { codec: this._codec });
           this._provenanceIndex = new ProvenanceIndex();
           this._provenanceDegraded = true;
           await this._setMaterializedState(state);
           this._cachedCeiling = ceiling;
           this._cachedFrontier = frontier;
+          if (cached.indexTreeOid) {
+            await this._restoreIndexFromCache(cached.indexTreeOid);
+          }
           this._logTiming('materialize', t0, { metrics: `cache hit (ceiling=${ceiling})` });
           return state;
         } catch {
@@ -258,7 +312,8 @@ export async function _materializeWithCeiling(ceiling, collectReceipts, t0) {
       cacheKey = buildSeekCacheKey(ceiling, frontier);
     }
     const buf = serializeFullStateV5(state, { codec: this._codec });
-    this._seekCache.set(cacheKey, /** @type {Buffer} */ (buf)).catch(() => {});
+    this._persistSeekCacheEntry(cacheKey, /** @type {Buffer} */ (buf), state)
+      .catch(() => {});
   }
 
   // Skip auto-checkpoint and GC — this is an exploratory read
@@ -270,6 +325,62 @@ export async function _materializeWithCeiling(ceiling, collectReceipts, t0) {
   return state;
 }
 
+/**
+ * Persists a seek cache entry with an optional index tree snapshot.
+ *
+ * Builds the bitmap index tree from the materialized state, writes it
+ * to Git storage, and includes the resulting tree OID in the cache
+ * entry metadata. Index persistence failure is non-fatal — the state
+ * buffer is still cached without the index.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} cacheKey - Seek cache key
+ * @param {Buffer} buf - Serialized WarpStateV5 buffer
+ * @param {import('../services/JoinReducer.js').WarpStateV5} state
+ * @returns {Promise<void>}
+ * @private
+ */
+export async function _persistSeekCacheEntry(cacheKey, buf, state) {
+  /** @type {{ indexTreeOid?: string }} */
+  const opts = {};
+  try {
+    const { tree } = this._viewService.build(state);
+    opts.indexTreeOid = await this._viewService.persistIndexTree(
+      tree,
+      this._persistence,
+    );
+  } catch {
+    // Non-fatal — cache the state without the index
+  }
+  if (this._seekCache) {
+    await this._seekCache.set(cacheKey, buf, opts);
+  }
+}
+
+/**
+ * Restores a LogicalIndex and PropertyReader from a cached index tree OID.
+ *
+ * Reads the tree entries from Git storage and delegates hydration to
+ * the MaterializedViewService. Failure is non-fatal — the in-memory
+ * index built by `_buildView` remains as fallback.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} indexTreeOid - Git tree OID of the bitmap index snapshot
+ * @returns {Promise<void>}
+ * @private
+ */
+export async function _restoreIndexFromCache(indexTreeOid) {
+  try {
+    const shardOids = await this._persistence.readTreeOids(indexTreeOid);
+    const { logicalIndex, propertyReader } =
+      await this._viewService.loadFromOids(shardOids, this._persistence);
+    this._logicalIndex = logicalIndex;
+    this._propertyReader = propertyReader;
+  } catch {
+    // Non-fatal — fall back to in-memory index from _buildView
+  }
+}
+
 /**
  * Materializes the graph state at a specific checkpoint.
  *
@@ -348,3 +459,31 @@ export async function materializeAt(checkpointSha) {
   await this._setMaterializedState(state);
   return state;
 }
+
+/**
+ * Verifies the bitmap index against adjacency ground truth.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {{ seed?: number, sampleRate?: number }} [options]
+ * @returns {{ passed: number, failed: number, errors: Array<{nodeId: string, direction: string, expected: string[], actual: string[]}> }}
+ */
+export function verifyIndex(options) {
+  if (!this._logicalIndex || !this._cachedState || !this._viewService) {
+    throw new Error('Cannot verify index: graph not materialized or index not built');
+  }
+  return this._viewService.verifyIndex({
+    state: this._cachedState,
+    logicalIndex: this._logicalIndex,
+    options,
+  });
+}
+
+/**
+ * Clears the cached bitmap index, forcing a full rebuild on next materialize.
+ *
+ * @this {import('../WarpGraph.js').default}
+ */
+export function invalidateIndex() {
+  this._cachedIndexTree = null;
+  this._cachedViewHash = null;
+}

package/src/domain/warp/query.methods.js

@@ -42,6 +42,18 @@ export async function hasNode(nodeId) {
  */
 export async function getNodeProps(nodeId) {
   await this._ensureFreshState();
+
+  // ── Indexed fast path (positive results only; stale index falls through) ──
+  if (this._propertyReader && this._logicalIndex?.isAlive(nodeId)) {
+    try {
+      const record = await this._propertyReader.getNodeProps(nodeId);
+      return record ? new Map(Object.entries(record)) : new Map();
+    } catch {
+      // Fall through to linear scan on index read failures.
+    }
+  }
+
+  // ── Linear scan fallback ─────────────────────────────────────────────
   const s = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (this._cachedState);
 
   if (!orsetContains(s.nodeAlive, nodeId)) {
@@ -103,6 +115,17 @@ export async function getEdgeProps(from, to, label) {
   return props;
 }
 
+/**
+ * Converts NeighborEdge[] to the query-method shape with a direction tag.
+ *
+ * @param {Array<{neighborId: string, label: string}>} edges
+ * @param {'outgoing' | 'incoming'} dir
+ * @returns {Array<{nodeId: string, label: string, direction: 'outgoing' | 'incoming'}>}
+ */
+function tagDirection(edges, dir) {
+  return edges.map((e) => ({ nodeId: e.neighborId, label: e.label, direction: dir }));
+}
+
 /**
  * Gets neighbors of a node from the materialized state.
  *
@@ -115,28 +138,71 @@ export async function getEdgeProps(from, to, label) {
  */
 export async function neighbors(nodeId, direction = 'both', edgeLabel = undefined) {
   await this._ensureFreshState();
-  const s = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (this._cachedState);
 
+  // ── Indexed fast path (only when node is in index; stale falls through) ──
+  const provider = this._materializedGraph?.provider;
+  if (provider && this._logicalIndex?.isAlive(nodeId)) {
+    try {
+      const opts = edgeLabel ? { labels: new Set([edgeLabel]) } : undefined;
+      return await _indexedNeighbors(provider, nodeId, direction, opts);
+    } catch {
+      // Fall through to linear scan on index/provider failures.
+    }
+  }
+
+  // ── Linear scan fallback ─────────────────────────────────────────────
+  return _linearNeighbors(/** @type {import('../services/JoinReducer.js').WarpStateV5} */ (this._cachedState), nodeId, direction, edgeLabel);
+}
+
+/**
+ * Indexed neighbor lookup using BitmapNeighborProvider.
+ *
+ * @param {import('../../ports/NeighborProviderPort.js').default} provider
+ * @param {string} nodeId
+ * @param {'outgoing' | 'incoming' | 'both'} direction
+ * @param {import('../../ports/NeighborProviderPort.js').NeighborOptions} [opts]
+ * @returns {Promise<Array<{nodeId: string, label: string, direction: 'outgoing' | 'incoming'}>>}
+ */
+async function _indexedNeighbors(provider, nodeId, direction, opts) {
+  if (direction === 'both') {
+    const [outEdges, inEdges] = await Promise.all([
+      provider.getNeighbors(nodeId, 'out', opts),
+      provider.getNeighbors(nodeId, 'in', opts),
+    ]);
+    return [...tagDirection(outEdges, 'outgoing'), ...tagDirection(inEdges, 'incoming')];
+  }
+  const dir = direction === 'outgoing' ? 'out' : 'in';
+  const edges = await provider.getNeighbors(nodeId, dir, opts);
+  const tag = direction === 'outgoing' ? /** @type {const} */ ('outgoing') : /** @type {const} */ ('incoming');
+  return tagDirection(edges, tag);
+}
+
+/**
+ * Linear-scan neighbor lookup from raw CRDT state.
+ *
+ * @param {import('../services/JoinReducer.js').WarpStateV5} cachedState
+ * @param {string} nodeId
+ * @param {'outgoing' | 'incoming' | 'both'} direction
+ * @param {string} [edgeLabel]
+ * @returns {Array<{nodeId: string, label: string, direction: 'outgoing' | 'incoming'}>}
+ */
+function _linearNeighbors(cachedState, nodeId, direction, edgeLabel) {
+  const s = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (cachedState);
   /** @type {Array<{nodeId: string, label: string, direction: 'outgoing' | 'incoming'}>} */
   const result = [];
+  const checkOut = direction === 'outgoing' || direction === 'both';
+  const checkIn = direction === 'incoming' || direction === 'both';
 
   for (const edgeKey of orsetElements(s.edgeAlive)) {
     const { from, to, label } = decodeEdgeKey(edgeKey);
-
     if (edgeLabel !== undefined && label !== edgeLabel) {
       continue;
     }
-
-    if ((direction === 'outgoing' || direction === 'both') && from === nodeId) {
-      if (orsetContains(s.nodeAlive, to)) {
-        result.push({ nodeId: to, label, direction: /** @type {const} */ ('outgoing') });
-      }
+    if (checkOut && from === nodeId && orsetContains(s.nodeAlive, to)) {
+      result.push({ nodeId: to, label, direction: /** @type {const} */ ('outgoing') });
     }
-
-    if ((direction === 'incoming' || direction === 'both') && to === nodeId) {
-      if (orsetContains(s.nodeAlive, from)) {
-        result.push({ nodeId: from, label, direction: /** @type {const} */ ('incoming') });
-      }
+    if (checkIn && to === nodeId && orsetContains(s.nodeAlive, from)) {
+      result.push({ nodeId: from, label, direction: /** @type {const} */ ('incoming') });
     }
   }
 
@@ -246,14 +312,16 @@ export function query() {
  * @this {import('../WarpGraph.js').default}
  * @param {string} name - Observer name
  * @param {Object} config - Observer configuration
- * @param {string} config.match - Glob pattern for visible nodes
+ * @param {string|string[]} config.match - Glob pattern(s) for visible nodes
  * @param {string[]} [config.expose] - Property keys to include
  * @param {string[]} [config.redact] - Property keys to exclude
  * @returns {Promise<import('../services/ObserverView.js').default>} A read-only observer view
  */
 export async function observer(name, config) {
-  if (!config || typeof config.match !== 'string') {
-    throw new Error('observer config.match must be a string');
+  /** @param {unknown} m */
+  const isValidMatch = (m) => typeof m === 'string' || (Array.isArray(m) && m.every(/** @param {unknown} i */ i => typeof i === 'string'));
+  if (!config || !isValidMatch(config.match)) {
+    throw new Error('observer config.match must be a string or array of strings');
   }
   await this._ensureFreshState();
   return new ObserverView({ name, config, graph: this });

package/src/infrastructure/adapters/CasSeekCacheAdapter.js

@@ -39,6 +39,7 @@ const MAX_CAS_RETRIES = 3;
  * @property {string} codec - Codec identifier (e.g. 'cbor-v1')
  * @property {number} schemaVersion - Index entry schema version
  * @property {string} [lastAccessedAt] - ISO 8601 timestamp of last read (for LRU eviction)
+ * @property {string} [indexTreeOid] - Git tree OID of the bitmap index snapshot
  */
 
 /**
@@ -203,9 +204,18 @@ export default class CasSeekCacheAdapter extends SeekCachePort {
   // ---------------------------------------------------------------------------
 
   /**
+   * Retrieves a cached state buffer by key.
+   *
+   * Note: This method reads the index twice — once here for the entry lookup,
+   * and again inside `_mutateIndex` for the `lastAccessedAt` update. The
+   * double-read is a known trade-off: `_mutateIndex` re-reads to provide
+   * CAS-safe retry semantics, and deduplicating the reads would complicate
+   * the retry logic without meaningful performance impact (the index is a
+   * single small JSON blob).
+   *
    * @override
    * @param {string} key
-   * @returns {Promise<Buffer|null>}
+   * @returns {Promise<{ buffer: Buffer|Uint8Array, indexTreeOid?: string } | null>}
    */
   async get(key) {
     const cas = await this._getCas();
@@ -225,7 +235,12 @@ export default class CasSeekCacheAdapter extends SeekCachePort {
         }
         return idx;
       });
-      return buffer;
+      /** @type {{ buffer: Buffer|Uint8Array, indexTreeOid?: string }} */
+      const result = { buffer };
+      if (entry.indexTreeOid) {
+        result.indexTreeOid = entry.indexTreeOid;
+      }
+      return result;
     } catch {
       // Blob GC'd or corrupted — self-heal by removing dead entry
       await this._mutateIndex((idx) => {
@@ -239,10 +254,11 @@ export default class CasSeekCacheAdapter extends SeekCachePort {
   /**
    * @override
    * @param {string} key
-   * @param {Buffer} buffer
+   * @param {Buffer|Uint8Array} buffer
+   * @param {{ indexTreeOid?: string }} [options]
    * @returns {Promise<void>}
    */
-  async set(key, buffer) {
+  async set(key, buffer, options) {
     const cas = await this._getCas();
     const { ceiling, frontierHash } = this._parseKey(key);
 
@@ -257,7 +273,8 @@ export default class CasSeekCacheAdapter extends SeekCachePort {
 
     // Update index with rich metadata
     await this._mutateIndex((index) => {
-      index.entries[key] = {
+      /** @type {IndexEntry} */
+      const entry = {
         treeOid,
         createdAt: new Date().toISOString(),
         ceiling,
@@ -266,6 +283,10 @@ export default class CasSeekCacheAdapter extends SeekCachePort {
         codec: 'cbor-v1',
         schemaVersion: INDEX_SCHEMA_VERSION,
       };
+      if (options?.indexTreeOid) {
+        entry.indexTreeOid = options.indexTreeOid;
+      }
+      index.entries[key] = entry;
       return this._enforceMaxEntries(index);
     });
   }

package/src/ports/BlobPort.js

@@ -10,7 +10,7 @@
 export default class BlobPort {
   /**
    * Writes content as a Git blob and returns its OID.
-   * @param {Buffer|string} _content - The blob content to write
+   * @param {Uint8Array|Buffer|string} _content - The blob content to write
    * @returns {Promise<string>} The Git OID of the created blob
    * @throws {Error} If not implemented by a concrete adapter
    */

package/src/ports/NeighborProviderPort.js

@@ -0,0 +1,59 @@
+/**
+ * Port interface for neighbor lookups on any graph.
+ *
+ * Concrete providers back this with in-memory adjacency maps, bitmap indexes,
+ * or remote APIs. All providers MUST return edges sorted by (neighborId, label)
+ * using strict codepoint comparison (never localeCompare).
+ *
+ * @abstract
+ */
+
+/** @typedef {'out' | 'in' | 'both'} Direction */
+/** @typedef {{ labels?: Set<string> }} NeighborOptions */
+/** @typedef {{ neighborId: string, label: string }} NeighborEdge */
+
+export default class NeighborProviderPort {
+  /**
+   * Returns neighbor edges for a node, sorted by (neighborId, label).
+   *
+   * For direction 'both', returns the union of out and in edges
+   * deduped by (neighborId, label). A consumer cannot tell if an
+   * edge was outgoing or incoming — this is intentionally lossy.
+   *
+   * @param {string} _nodeId - The node to look up
+   * @param {Direction} _direction - Edge direction: 'out', 'in', or 'both'
+   * @param {NeighborOptions} [_options] - Optional label filter
+   * @returns {Promise<NeighborEdge[]>} Sorted by (neighborId, label) via codepoint comparison
+   * @throws {Error} If not implemented by a concrete provider
+   */
+  async getNeighbors(_nodeId, _direction, _options) {
+    throw new Error('NeighborProviderPort.getNeighbors() not implemented');
+  }
+
+  /**
+   * Checks whether a node is alive in this view.
+   *
+   * Semantics: "alive in this view" (visible projection), NOT "ever existed."
+   *
+   * @param {string} _nodeId - The node to check
+   * @returns {Promise<boolean>} True if the node is alive
+   * @throws {Error} If not implemented by a concrete provider
+   */
+  async hasNode(_nodeId) {
+    throw new Error('NeighborProviderPort.hasNode() not implemented');
+  }
+
+  /**
+   * Returns the latency class of this provider.
+   *
+   * Used by GraphTraversal to decide whether to enable neighbor memoization.
+   * - 'sync': in-memory, no benefit from caching (e.g., AdjacencyNeighborProvider)
+   * - 'async-local': disk-backed, caching avoids repeated reads (e.g., BitmapNeighborProvider)
+   * - 'async-remote': network-backed, caching critical
+   *
+   * @returns {'sync' | 'async-local' | 'async-remote'}
+   */
+  get latencyClass() {
+    return 'async-local';
+  }
+}

package/src/ports/SeekCachePort.js

@@ -14,7 +14,7 @@ export default class SeekCachePort {
   /**
    * Retrieves a cached state buffer by key.
    * @param {string} _key - Cache key (e.g., 'v1:t42-<frontierHash>')
-   * @returns {Promise<Buffer|null>} The cached buffer, or null on miss
+   * @returns {Promise<{ buffer: Buffer|Uint8Array, indexTreeOid?: string } | null>} The cached entry, or null on miss
    * @throws {Error} If not implemented by a concrete adapter
    */
   async get(_key) {
@@ -24,11 +24,12 @@ export default class SeekCachePort {
   /**
    * Stores a state buffer under the given key.
    * @param {string} _key - Cache key
-   * @param {Buffer} _buffer - Serialized state to cache
+   * @param {Buffer|Uint8Array} _buffer - Serialized state to cache
+   * @param {{ indexTreeOid?: string }} [_options] - Optional metadata
    * @returns {Promise<void>}
    * @throws {Error} If not implemented by a concrete adapter
    */
-  async set(_key, _buffer) {
+  async set(_key, _buffer, _options) {
     throw new Error('SeekCachePort.set() not implemented');
   }