@git-stunts/git-warp 11.5.0 → 12.0.0

package/src/domain/warp/_wiredMethods.d.ts

@@ -151,6 +151,7 @@ interface CheckpointData {
   stateHash: string;
   schema: number;
   provenanceIndex?: unknown;
+  indexShardOids?: Record<string, string>;
 }
 
 export {};
@@ -193,7 +194,7 @@ declare module '../WarpGraph.js' {
     _relationToCheckpointHead(ckHead: string, incomingSha: string): Promise<string>;
     _validatePatchAgainstCheckpoint(writerId: string, incomingSha: string, checkpoint: unknown): Promise<void>;
 
-    // ── sync.methods.js ───────────────────────────────────────────────────
+    // ── SyncController (direct delegation) ─────────────────────────────────
     getFrontier(): Promise<Map<string, string>>;
     hasFrontierChanged(): Promise<boolean>;
     status(): Promise<WarpGraphStatus>;
@@ -247,8 +248,13 @@ declare module '../WarpGraph.js' {
     // ── materializeAdvanced.methods.js ────────────────────────────────────
     _resolveCeiling(options?: { ceiling?: number | null }): number | null;
     _buildAdjacency(state: WarpStateV5): { outgoing: Map<string, Array<{ neighborId: string; label: string }>>; incoming: Map<string, Array<{ neighborId: string; label: string }>> };
-    _setMaterializedState(state: WarpStateV5): Promise<{ state: WarpStateV5; stateHash: string; adjacency: unknown }>;
+    _buildView(state: WarpStateV5, stateHash: string, diff?: import('../types/PatchDiff.js').PatchDiff): void;
+    _setMaterializedState(state: WarpStateV5, diff?: import('../types/PatchDiff.js').PatchDiff): Promise<{ state: WarpStateV5; stateHash: string; adjacency: unknown }>;
     _materializeWithCeiling(ceiling: number, collectReceipts: boolean, t0: number): Promise<WarpStateV5 | { state: WarpStateV5; receipts: TickReceipt[] }>;
+    _persistSeekCacheEntry(cacheKey: string, buf: Buffer, state: WarpStateV5): Promise<void>;
+    _restoreIndexFromCache(indexTreeOid: string): Promise<void>;
     materializeAt(checkpointSha: string): Promise<WarpStateV5>;
+    verifyIndex(options?: { seed?: number; sampleRate?: number }): { passed: number; failed: number; errors: Array<{ nodeId: string; direction: string; expected: string[]; actual: string[] }> };
+    invalidateIndex(): void;
   }
 }

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

@@ -60,7 +60,22 @@ export async function createCheckpoint() {
       this._checkpointing = prevCheckpointing;
     }
 
-    // 4. Call CheckpointService.create() with provenance index if available
+    // 4. Reuse cached index tree or rebuild from view service
+    let indexTree = this._cachedIndexTree;
+    if (!indexTree && this._viewService) {
+      try {
+        const { tree } = this._viewService.build(state);
+        indexTree = tree;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        this._logger?.warn('[warp] checkpoint index build failed; saving checkpoint without index', {
+          error: message,
+        });
+        indexTree = null;
+      }
+    }
+
+    // 5. Create checkpoint commit with provenance index + index tree
     /** @type {CorePersistence} */
     const persistence = this._persistence;
     const checkpointSha = await createCheckpointCommit({
@@ -72,15 +87,16 @@ export async function createCheckpoint() {
       provenanceIndex: this._provenanceIndex || undefined,
       crypto: this._crypto,
       codec: this._codec,
+      indexTree: indexTree || undefined,
     });
 
-    // 5. Update checkpoint ref
+    // 6. Update checkpoint ref
     const checkpointRef = buildCheckpointRef(this._graphName);
     await this._persistence.updateRef(checkpointRef, checkpointSha);
 
     this._logTiming('createCheckpoint', t0);
 
-    // 6. Return checkpoint SHA
+    // 7. Return checkpoint SHA
     return checkpointSha;
   } catch (err) {
     this._logTiming('createCheckpoint', t0, { error: /** @type {Error} */ (err) });
@@ -137,7 +153,7 @@ export async function syncCoverage() {
  * Loads the latest checkpoint for this graph.
  *
  * @this {import('../WarpGraph.js').default}
- * @returns {Promise<{state: import('../services/JoinReducer.js').WarpStateV5, frontier: Map<string, string>, stateHash: string, schema: number, provenanceIndex?: import('../services/ProvenanceIndex.js').ProvenanceIndex}|null>} The checkpoint or null
+ * @returns {Promise<{state: import('../services/JoinReducer.js').WarpStateV5, frontier: Map<string, string>, stateHash: string, schema: number, provenanceIndex?: import('../services/ProvenanceIndex.js').ProvenanceIndex, indexShardOids?: Record<string, string>|null}|null>} The checkpoint or null
  * @private
  */
 export async function _loadLatestCheckpoint() {
@@ -197,7 +213,7 @@ export async function _loadPatchesSince(checkpoint) {
  */
 export async function _validateMigrationBoundary() {
   const checkpoint = await this._loadLatestCheckpoint();
-  if (checkpoint?.schema === 2 || checkpoint?.schema === 3) {
+  if (checkpoint?.schema === 2 || checkpoint?.schema === 3 || checkpoint?.schema === 4) {
     return;  // Already migrated
   }
 

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

@@ -51,6 +51,7 @@ function scanPatchesForMaxLamport(graph, patches) {
   }
 }
 
+
 /**
  * Materializes the current graph state.
  *
@@ -99,10 +100,13 @@ export async function materialize(options) {
     let state;
     /** @type {import('../types/TickReceipt.js').TickReceipt[]|undefined} */
     let receipts;
+    /** @type {import('../types/PatchDiff.js').PatchDiff|undefined} */
+    let diff;
     let patchCount = 0;
+    const wantDiff = !collectReceipts && !!this._cachedIndexTree;
 
     // If checkpoint exists, use incremental materialization
-    if (checkpoint?.schema === 2 || checkpoint?.schema === 3) {
+    if (checkpoint?.schema === 2 || checkpoint?.schema === 3 || checkpoint?.schema === 4) {
       const patches = await this._loadPatchesSince(checkpoint);
       // Update max observed Lamport so _nextLamport() issues globally-monotonic ticks.
       // Read the checkpoint frontier's tip commit messages to capture the pre-checkpoint max,
@@ -115,6 +119,10 @@ export async function materialize(options) {
         const result = /** @type {{state: import('../services/JoinReducer.js').WarpStateV5, receipts: import('../types/TickReceipt.js').TickReceipt[]}} */ (reduceV5(/** @type {Parameters<typeof reduceV5>[0]} */ (patches), checkpoint.state, { receipts: true }));
         state = result.state;
         receipts = result.receipts;
+      } else if (wantDiff) {
+        const result = /** @type {{state: import('../services/JoinReducer.js').WarpStateV5, diff: import('../types/PatchDiff.js').PatchDiff}} */ (reduceV5(/** @type {Parameters<typeof reduceV5>[0]} */ (patches), checkpoint.state, { trackDiff: true }));
+        state = result.state;
+        diff = result.diff;
       } else {
         state = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (reduceV5(/** @type {Parameters<typeof reduceV5>[0]} */ (patches), checkpoint.state));
       }
@@ -164,6 +172,10 @@ export async function materialize(options) {
             const result = /** @type {{state: import('../services/JoinReducer.js').WarpStateV5, receipts: import('../types/TickReceipt.js').TickReceipt[]}} */ (reduceV5(/** @type {Parameters<typeof reduceV5>[0]} */ (allPatches), undefined, { receipts: true }));
             state = result.state;
             receipts = result.receipts;
+          } else if (wantDiff) {
+            const result = /** @type {{state: import('../services/JoinReducer.js').WarpStateV5, diff: import('../types/PatchDiff.js').PatchDiff}} */ (reduceV5(/** @type {Parameters<typeof reduceV5>[0]} */ (allPatches), undefined, { trackDiff: true }));
+            state = result.state;
+            diff = result.diff;
           } else {
             state = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (reduceV5(/** @type {Parameters<typeof reduceV5>[0]} */ (allPatches)));
           }
@@ -178,7 +190,7 @@ export async function materialize(options) {
       }
     }
 
-    await this._setMaterializedState(state);
+    await this._setMaterializedState(state, diff);
     this._provenanceDegraded = false;
     this._cachedCeiling = null;
     this._cachedFrontier = null;
@@ -202,9 +214,9 @@ export async function materialize(options) {
     // Also handles deferred replay for subscribers added with replay: true before cached state
     if (this._subscribers.length > 0) {
       const hasPendingReplay = this._subscribers.some(s => s.pendingReplay);
-      const diff = diffStates(this._lastNotifiedState, state);
-      if (!isEmptyDiff(diff) || hasPendingReplay) {
-        this._notifySubscribers(diff, state);
+      const stateDelta = diffStates(this._lastNotifiedState, state);
+      if (!isEmptyDiff(stateDelta) || hasPendingReplay) {
+        this._notifySubscribers(stateDelta, state);
       }
     }
     // Clone state to prevent eager path mutations from affecting the baseline

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') });
     }
   }
 

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');
   }