@git-stunts/git-warp 11.5.0 → 12.0.0

package/src/domain/services/AdjacencyNeighborProvider.js

@@ -0,0 +1,140 @@
+/**
+ * NeighborProvider backed by in-memory adjacency maps.
+ *
+ * Wraps the { outgoing, incoming } Maps produced by _buildAdjacency().
+ * Adjacency lists are pre-sorted at construction by (neighborId, label)
+ * using strict codepoint comparison. Label filtering via Set.has() in-memory.
+ *
+ * @module domain/services/AdjacencyNeighborProvider
+ */
+
+import NeighborProviderPort from '../../ports/NeighborProviderPort.js';
+
+/**
+ * Comparator for (neighborId, label) sorting.
+ * Strict codepoint comparison — never localeCompare.
+ *
+ * @param {{ neighborId: string, label: string }} a
+ * @param {{ neighborId: string, label: string }} b
+ * @returns {number}
+ */
+function edgeCmp(a, b) {
+  if (a.neighborId < b.neighborId) { return -1; }
+  if (a.neighborId > b.neighborId) { return 1; }
+  if (a.label < b.label) { return -1; }
+  if (a.label > b.label) { return 1; }
+  return 0;
+}
+
+/**
+ * Pre-sorts all adjacency lists and freezes the result.
+ *
+ * @param {Map<string, Array<{neighborId: string, label: string}>>} adjMap
+ * @returns {Map<string, Array<{neighborId: string, label: string}>>}
+ */
+function sortAdjacencyMap(adjMap) {
+  const result = new Map();
+  for (const [nodeId, edges] of adjMap) {
+    const sorted = edges.slice().sort(edgeCmp);
+    result.set(nodeId, sorted);
+  }
+  return result;
+}
+
+/**
+ * Filters an edge list by a label set. Returns the original array when
+ * no filter is provided.
+ *
+ * @param {Array<{neighborId: string, label: string}>} edges
+ * @param {Set<string>|undefined} labels
+ * @returns {Array<{neighborId: string, label: string}>}
+ */
+function filterByLabels(edges, labels) {
+  if (!labels) {
+    return edges;
+  }
+  return edges.filter((e) => labels.has(e.label));
+}
+
+/**
+ * Merges two pre-sorted edge lists, deduplicating by (neighborId, label).
+ *
+ * @param {Array<{neighborId: string, label: string}>} a
+ * @param {Array<{neighborId: string, label: string}>} b
+ * @returns {Array<{neighborId: string, label: string}>}
+ */
+function mergeSorted(a, b) {
+  const result = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    const cmp = edgeCmp(a[i], b[j]);
+    if (cmp < 0) {
+      result.push(a[i++]);
+    } else if (cmp > 0) {
+      result.push(b[j++]);
+    } else {
+      // Duplicate — take one, skip both
+      result.push(a[i++]);
+      j++;
+    }
+  }
+  while (i < a.length) { result.push(a[i++]); }
+  while (j < b.length) { result.push(b[j++]); }
+  return result;
+}
+
+export default class AdjacencyNeighborProvider extends NeighborProviderPort {
+  /**
+   * @param {Object} params
+   * @param {Map<string, Array<{neighborId: string, label: string}>>} params.outgoing
+   * @param {Map<string, Array<{neighborId: string, label: string}>>} params.incoming
+   * @param {Set<string>} params.aliveNodes - Set of alive nodeIds for hasNode()
+   */
+  constructor({ outgoing, incoming, aliveNodes }) {
+    super();
+    if (!aliveNodes) {
+      throw new Error('AdjacencyNeighborProvider: aliveNodes is required');
+    }
+    /** @type {Map<string, Array<{neighborId: string, label: string}>>} */
+    this._outgoing = sortAdjacencyMap(outgoing);
+    /** @type {Map<string, Array<{neighborId: string, label: string}>>} */
+    this._incoming = sortAdjacencyMap(incoming);
+    /** @type {Set<string>} */
+    this._aliveNodes = aliveNodes;
+  }
+
+  /**
+   * @param {string} nodeId
+   * @param {import('../../ports/NeighborProviderPort.js').Direction} direction
+   * @param {import('../../ports/NeighborProviderPort.js').NeighborOptions} [options]
+   * @returns {Promise<import('../../ports/NeighborProviderPort.js').NeighborEdge[]>}
+   */
+  getNeighbors(nodeId, direction, options) {
+    const labels = options?.labels;
+    const outEdges = filterByLabels(this._outgoing.get(nodeId) || [], labels);
+    const inEdges = filterByLabels(this._incoming.get(nodeId) || [], labels);
+
+    if (direction === 'out') {
+      return Promise.resolve(outEdges);
+    }
+    if (direction === 'in') {
+      return Promise.resolve(inEdges);
+    }
+    // 'both': merge two pre-sorted lists, dedup by (neighborId, label)
+    return Promise.resolve(mergeSorted(outEdges, inEdges));
+  }
+
+  /**
+   * @param {string} nodeId
+   * @returns {Promise<boolean>}
+   */
+  hasNode(nodeId) {
+    return Promise.resolve(this._aliveNodes.has(nodeId));
+  }
+
+  /** @returns {'sync'} */
+  get latencyClass() {
+    return 'sync';
+  }
+}

package/src/domain/services/BitmapIndexReader.js

@@ -4,6 +4,7 @@ import nullLogger from '../utils/nullLogger.js';
 import LRUCache from '../utils/LRUCache.js';
 import { getRoaringBitmap32 } from '../utils/roaring.js';
 import { canonicalStringify } from '../utils/canonicalStringify.js';
+import { isValidShardOid } from '../utils/validateShardOid.js';
 
 /** @typedef {import('../../ports/IndexStoragePort.js').default} IndexStoragePort */
 /** @typedef {import('../types/WarpPersistence.js').IndexStorage} IndexStorage */
@@ -50,24 +51,24 @@ const computeChecksum = async (data, version, crypto) => {
  * - {@link ShardCorruptionError} for invalid shard format
  * - {@link ShardValidationError} for version or checksum mismatches
  *
- * In non-strict mode (default), validation failures are logged as warnings
+ * In non-strict mode (strict: false), validation failures are logged as warnings
  * and an empty shard is returned for graceful degradation.
  *
  * **Note**: Storage errors (e.g., `storage.readBlob` failures) always throw
  * {@link ShardLoadError} regardless of strict mode.
  *
  * @example
- * // Non-strict mode (default) - graceful degradation on validation errors
+ * // Strict mode (default) - throws on any validation failure
  * const reader = new BitmapIndexReader({ storage });
  * reader.setup(shardOids);
  * const parents = await reader.getParents('abc123...');
  *
  * @example
- * // Strict mode - throws on any validation failure
- * const strictReader = new BitmapIndexReader({ storage, strict: true });
- * strictReader.setup(shardOids);
+ * // Non-strict mode - graceful degradation on validation errors
+ * const lenientReader = new BitmapIndexReader({ storage, strict: false });
+ * lenientReader.setup(shardOids);
  * try {
- *   const parents = await strictReader.getParents('abc123...');
+ *   const parents = await lenientReader.getParents('abc123...');
  * } catch (err) {
  *   if (err instanceof ShardValidationError) {
  *     console.error('Shard validation failed:', err.field, err.expected, err.actual);
@@ -83,14 +84,14 @@ export default class BitmapIndexReader {
    * Creates a BitmapIndexReader instance.
    * @param {Object} options
    * @param {IndexStoragePort} options.storage - Storage adapter for reading index data
-   * @param {boolean} [options.strict=false] - If true, throw errors on validation failures; if false, log warnings and return empty shards
+   * @param {boolean} [options.strict=true] - If true, throw errors on validation failures; if false, log warnings and return empty shards
    * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for structured logging.
    *   Defaults to NoOpLogger (no logging).
    * @param {number} [options.maxCachedShards=100] - Maximum number of shards to keep in the LRU cache.
    *   When exceeded, least recently used shards are evicted to free memory.
    * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort instance for checksum verification.
    */
-  constructor({ storage, strict = false, logger = nullLogger, maxCachedShards = DEFAULT_MAX_CACHED_SHARDS, crypto } = /** @type {{ storage: IndexStoragePort, strict?: boolean, logger?: LoggerPort, maxCachedShards?: number, crypto?: CryptoPort }} */ ({})) {
+  constructor({ storage, strict = true, logger = nullLogger, maxCachedShards = DEFAULT_MAX_CACHED_SHARDS, crypto } = /** @type {{ storage: IndexStoragePort, strict?: boolean, logger?: LoggerPort, maxCachedShards?: number, crypto?: CryptoPort }} */ ({})) {
     if (!storage) {
       throw new Error('BitmapIndexReader requires a storage adapter');
     }
@@ -132,8 +133,29 @@ export default class BitmapIndexReader {
    * const parents = await reader.getParents('abcd1234...'); // loads meta_ab, shards_rev_ab
    */
   setup(shardOids) {
-    this.shardOids = new Map(Object.entries(shardOids));
-    this._idToShaCache = null; // Clear cache when shards change
+    const entries = Object.entries(shardOids);
+    /** @type {[string, string][]} */
+    const validEntries = [];
+    for (const [path, oid] of entries) {
+      if (isValidShardOid(oid)) {
+        validEntries.push([path, oid]);
+      } else if (this.strict) {
+        throw new ShardCorruptionError('Invalid shard OID', {
+          shardPath: path,
+          oid,
+          reason: 'invalid_oid',
+        });
+      } else {
+        this.logger.warn('Skipping shard with invalid OID', {
+          operation: 'setup',
+          shardPath: path,
+          oid,
+          reason: 'invalid_oid',
+        });
+      }
+    }
+    this.shardOids = new Map(validEntries);
+    this._idToShaCache = null;
     this.loadedShards.clear();
   }
 

package/src/domain/services/BitmapNeighborProvider.js

@@ -0,0 +1,178 @@
+/**
+ * NeighborProvider backed by bitmap indexes.
+ *
+ * Two modes:
+ * 1. **Commit DAG** (`indexReader`): Wraps BitmapIndexReader for parent/child
+ *    relationships. Edges use label = '' (empty string sentinel).
+ * 2. **Logical graph** (`logicalIndex`): Wraps CBOR-based logical bitmap index
+ *    with labeled edges, per-label bitmap filtering, and alive bitmap checks.
+ *
+ * @module domain/services/BitmapNeighborProvider
+ */
+
+import NeighborProviderPort from '../../ports/NeighborProviderPort.js';
+
+/** @typedef {import('./BitmapIndexReader.js').default} BitmapIndexReader */
+
+/**
+ * @typedef {Object} LogicalIndex
+ * @property {(nodeId: string) => number|undefined} getGlobalId
+ * @property {(nodeId: string) => boolean} isAlive
+ * @property {(globalId: number) => string|undefined} getNodeId
+ * @property {(nodeId: string, direction: string, labelIds?: number[]) => Array<{neighborId: string, label: string}>} getEdges
+ * @property {() => Map<string, number>} getLabelRegistry
+ */
+
+/**
+ * Sorts edges by (neighborId, label) using strict codepoint comparison.
+ *
+ * @param {Array<{neighborId: string, label: string}>} edges
+ * @returns {Array<{neighborId: string, label: string}>}
+ */
+function sortEdges(edges) {
+  return edges.sort((a, b) => {
+    if (a.neighborId < b.neighborId) { return -1; }
+    if (a.neighborId > b.neighborId) { return 1; }
+    if (a.label < b.label) { return -1; }
+    if (a.label > b.label) { return 1; }
+    return 0;
+  });
+}
+
+/**
+ * Deduplicates a sorted edge list by (neighborId, label).
+ *
+ * @param {Array<{neighborId: string, label: string}>} edges
+ * @returns {Array<{neighborId: string, label: string}>}
+ */
+function dedupSorted(edges) {
+  if (edges.length <= 1) { return edges; }
+  const result = [edges[0]];
+  for (let i = 1; i < edges.length; i++) {
+    const prev = result[result.length - 1];
+    if (edges[i].neighborId !== prev.neighborId || edges[i].label !== prev.label) {
+      result.push(edges[i]);
+    }
+  }
+  return result;
+}
+
+export default class BitmapNeighborProvider extends NeighborProviderPort {
+  /**
+   * @param {Object} params
+   * @param {BitmapIndexReader} [params.indexReader] - For commit DAG mode
+   * @param {LogicalIndex} [params.logicalIndex] - For logical graph mode
+   */
+  constructor({ indexReader, logicalIndex }) {
+    super();
+    if (!indexReader && !logicalIndex) {
+      throw new Error('BitmapNeighborProvider requires either indexReader or logicalIndex');
+    }
+    this._reader = indexReader ?? null;
+    this._logical = logicalIndex ?? null;
+  }
+
+  /**
+   * @param {string} nodeId
+   * @param {import('../../ports/NeighborProviderPort.js').Direction} direction
+   * @param {import('../../ports/NeighborProviderPort.js').NeighborOptions} [options]
+   * @returns {Promise<import('../../ports/NeighborProviderPort.js').NeighborEdge[]>}
+   */
+  async getNeighbors(nodeId, direction, options) {
+    if (this._logical) {
+      return this._getLogicalNeighbors(nodeId, direction, options);
+    }
+    return await this._getDagNeighbors(nodeId, direction, options);
+  }
+
+  /**
+   * @param {string} nodeId
+   * @returns {Promise<boolean>}
+   */
+  async hasNode(nodeId) {
+    if (this._logical) {
+      return this._logical.isAlive(nodeId);
+    }
+    if (this._reader) {
+      const id = await this._reader.lookupId(nodeId);
+      return id !== undefined;
+    }
+    return false;
+  }
+
+  /** @returns {'async-local'} */
+  get latencyClass() {
+    return 'async-local';
+  }
+
+  // ── Commit DAG mode ─────────────────────────────────────────────────
+
+  /**
+   * @param {string} nodeId
+   * @param {import('../../ports/NeighborProviderPort.js').Direction} direction
+   * @param {import('../../ports/NeighborProviderPort.js').NeighborOptions} [options]
+   * @returns {Promise<import('../../ports/NeighborProviderPort.js').NeighborEdge[]>}
+   * @private
+   */
+  async _getDagNeighbors(nodeId, direction, options) {
+    if (!this._reader) { return []; }
+
+    if (options?.labels) {
+      if (!options.labels.has('')) { return []; }
+    }
+
+    if (direction === 'out') {
+      const children = await this._reader.getChildren(nodeId);
+      return sortEdges(children.map((id) => ({ neighborId: id, label: '' })));
+    }
+
+    if (direction === 'in') {
+      const parents = await this._reader.getParents(nodeId);
+      return sortEdges(parents.map((id) => ({ neighborId: id, label: '' })));
+    }
+
+    const [children, parents] = await Promise.all([
+      this._reader.getChildren(nodeId),
+      this._reader.getParents(nodeId),
+    ]);
+    const all = children.map((id) => ({ neighborId: id, label: '' }))
+      .concat(parents.map((id) => ({ neighborId: id, label: '' })));
+    return dedupSorted(sortEdges(all));
+  }
+
+  // ── Logical graph mode ──────────────────────────────────────────────
+
+  /**
+   * @param {string} nodeId
+   * @param {import('../../ports/NeighborProviderPort.js').Direction} direction
+   * @param {import('../../ports/NeighborProviderPort.js').NeighborOptions} [options]
+   * @returns {import('../../ports/NeighborProviderPort.js').NeighborEdge[]}
+   * @private
+   */
+  _getLogicalNeighbors(nodeId, direction, options) {
+    const logical = /** @type {LogicalIndex} */ (this._logical);
+
+    // Resolve label filter to labelIds
+    /** @type {number[]|undefined} */
+    let labelIds;
+    if (options?.labels) {
+      const registry = logical.getLabelRegistry();
+      labelIds = [];
+      for (const label of options.labels) {
+        const id = registry.get(label);
+        if (id !== undefined) {
+          labelIds.push(id);
+        }
+      }
+      if (labelIds.length === 0) { return []; }
+    }
+
+    if (direction === 'both') {
+      const outEdges = logical.getEdges(nodeId, 'out', labelIds);
+      const inEdges = logical.getEdges(nodeId, 'in', labelIds);
+      return dedupSorted(sortEdges([...outEdges, ...inEdges]));
+    }
+
+    return sortEdges(logical.getEdges(nodeId, direction, labelIds));
+  }
+}

package/src/domain/services/CheckpointMessageCodec.js

@@ -60,8 +60,8 @@ export function encodeCheckpointMessage({ graph, stateHash, frontierOid, indexOi
     [TRAILER_KEYS.schema]: String(schema),
   };
 
-  // Add checkpoint version marker for V5 format (schema:2 and schema:3)
-  if (schema === 2 || schema === 3) {
+  // Add checkpoint version marker for V5 format (schema:2, schema:3, schema:4)
+  if (schema === 2 || schema === 3 || schema === 4) {
     trailers[TRAILER_KEYS.checkpointVersion] = 'v5';
   }
 
@@ -126,7 +126,7 @@ export function decodeCheckpointMessage(message) {
     throw new Error(`Invalid checkpoint message: eg-schema must be a positive integer, got '${schemaStr}'`);
   }
 
-  // Extract optional checkpoint version (v5 for schema:2)
+  // Extract optional checkpoint version (v5 for schema:2/3/4)
   const checkpointVersion = trailers[TRAILER_KEYS.checkpointVersion] || null;
 
   return {

package/src/domain/services/CheckpointService.js

@@ -1,10 +1,10 @@
 /**
  * Checkpoint Service for WARP multi-writer graph database.
  *
- * Provides functionality for creating and loading schema:2 and schema:3
+ * Provides functionality for creating and loading schema:2, schema:3, and schema:4
  * checkpoints, as well as incremental state materialization from checkpoints.
  *
- * This service supports schema:2 and schema:3 (V5) checkpoints. Schema:1 (V4)
+ * This service supports schema:2, schema:3, and schema:4 (V5) checkpoints. Schema:1 (V4)
  * checkpoints must be migrated before use.
  *
  * @module CheckpointService
@@ -28,6 +28,53 @@ import { cloneStateV5, reduceV5 } from './JoinReducer.js';
 import { encodeEdgeKey, encodePropKey, CONTENT_PROPERTY_KEY, decodePropKey, isEdgePropKey, decodeEdgePropKey } from './KeyCodec.js';
 import { ProvenanceIndex } from './ProvenanceIndex.js';
 
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+/**
+ * Writes index tree shards as blobs and creates a subtree.
+ *
+ * @param {Record<string, Uint8Array>} indexTree - path → buffer mapping
+ * @param {{ writeBlob(buf: Uint8Array): Promise<string>, writeTree(entries: string[]): Promise<string> }} persistence
+ * @returns {Promise<string>} subtree OID
+ */
+async function writeIndexSubtree(indexTree, persistence) {
+  const paths = Object.keys(indexTree).sort();
+  const oids = await Promise.all(
+    paths.map((p) => persistence.writeBlob(indexTree[p]))
+  );
+
+  const entries = paths.map(
+    (path, i) => `100644 blob ${oids[i]}\t${path}`
+  );
+  return await persistence.writeTree(entries);
+}
+
+/**
+ * Partitions readTreeOids output into core entries and index shard OIDs.
+ *
+ * Entries prefixed with `index/` are stripped and collected separately.
+ *
+ * @param {Record<string, string>} rawOids
+ * @returns {{ treeOids: Record<string, string>, indexShardOids: Record<string, string> }}
+ */
+function partitionTreeOids(rawOids) {
+  /** @type {Record<string, string>} */
+  const treeOids = {};
+  /** @type {Record<string, string>} */
+  const indexShardOids = {};
+
+  for (const [path, oid] of Object.entries(rawOids)) {
+    if (path.startsWith('index/')) {
+      indexShardOids[path.slice(6)] = oid;
+    } else {
+      treeOids[path] = oid;
+    }
+  }
+  return { treeOids, indexShardOids };
+}
+
 // ============================================================================
 // Checkpoint Creation (WARP spec Section 10)
 // ============================================================================
@@ -55,10 +102,11 @@ import { ProvenanceIndex } from './ProvenanceIndex.js';
  * @param {import('./ProvenanceIndex.js').ProvenanceIndex} [options.provenanceIndex] - Optional provenance index to persist
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for CBOR serialization
  * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort for state hash computation
+ * @param {Record<string, Uint8Array>} [options.indexTree] - Optional materialized view index tree (triggers schema 4)
  * @returns {Promise<string>} The checkpoint commit SHA
  */
-export async function create({ persistence, graphName, state, frontier, parents = [], compact = true, provenanceIndex, codec, crypto }) {
-  return await createV5({ persistence, graphName, state, frontier, parents, compact, provenanceIndex, codec, crypto });
+export async function create({ persistence, graphName, state, frontier, parents = [], compact = true, provenanceIndex, codec, crypto, indexTree }) {
+  return await createV5({ persistence, graphName, state, frontier, parents, compact, provenanceIndex, codec, crypto, indexTree });
 }
 
 /**
@@ -84,6 +132,7 @@ export async function create({ persistence, graphName, state, frontier, parents
  * @param {import('./ProvenanceIndex.js').ProvenanceIndex} [options.provenanceIndex] - Optional provenance index to persist
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for CBOR serialization
  * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort for state hash computation
+ * @param {Record<string, Uint8Array>} [options.indexTree] - Optional materialized view index tree (triggers schema 4)
  * @returns {Promise<string>} The checkpoint commit SHA
  */
 export async function createV5({
@@ -96,6 +145,7 @@ export async function createV5({
   provenanceIndex,
   codec,
   crypto,
+  indexTree,
 }) {
   // 1. Compute appliedVV from actual state dots
   const appliedVV = computeAppliedVV(state);
@@ -132,7 +182,13 @@ export async function createV5({
     provenanceIndexBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (provenanceIndexBuffer));
   }
 
-  // 6c. Collect content blob OIDs from state properties for GC anchoring.
+  // 6c. Optionally write index subtree (schema 4)
+  let indexSubtreeOid = null;
+  if (indexTree) {
+    indexSubtreeOid = await writeIndexSubtree(indexTree, persistence);
+  }
+
+  // 6d. Collect content blob OIDs from state properties for GC anchoring.
   // If patch commits are ever pruned, content blobs remain reachable via
   // the checkpoint tree. Without this, git gc would nuke content blobs
   // whose only anchor was the (now-pruned) patch commit tree.
@@ -159,6 +215,11 @@ export async function createV5({
     treeEntries.push(`100644 blob ${provenanceIndexBlobOid}\tprovenanceIndex.cbor`);
   }
 
+  // Add index subtree if present (schema 4)
+  if (indexSubtreeOid) {
+    treeEntries.push(`040000 tree ${indexSubtreeOid}\tindex`);
+  }
+
   // Add content blob anchors
   for (const oid of contentOids) {
     treeEntries.push(`100644 blob ${oid}\t_content_${oid}`);
@@ -168,7 +229,7 @@ export async function createV5({
   treeEntries.sort((a, b) => {
     const filenameA = a.split('\t')[1];
     const filenameB = b.split('\t')[1];
-    return filenameA.localeCompare(filenameB);
+    return filenameA < filenameB ? -1 : filenameA > filenameB ? 1 : 0;
   });
 
   const treeOid = await persistence.writeTree(treeEntries);
@@ -179,7 +240,7 @@ export async function createV5({
     stateHash,
     frontierOid: frontierBlobOid,
     indexOid: treeOid,
-    schema: 2,
+    schema: indexTree ? 4 : 2,
   });
 
   // 9. Create the checkpoint commit
@@ -212,7 +273,7 @@ export async function createV5({
  * @param {string} checkpointSha - The checkpoint commit SHA to load
  * @param {Object} [options] - Load options
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for CBOR deserialization
- * @returns {Promise<{state: import('./JoinReducer.js').WarpStateV5, frontier: import('./Frontier.js').Frontier, stateHash: string, schema: number, appliedVV: Map<string, number>|null, provenanceIndex?: import('./ProvenanceIndex.js').ProvenanceIndex}>} The loaded checkpoint data
+ * @returns {Promise<{state: import('./JoinReducer.js').WarpStateV5, frontier: import('./Frontier.js').Frontier, stateHash: string, schema: number, appliedVV: Map<string, number>|null, provenanceIndex?: import('./ProvenanceIndex.js').ProvenanceIndex, indexShardOids: Record<string, string>|null}>} The loaded checkpoint data
  * @throws {Error} If checkpoint is schema:1 (migration required)
  */
 export async function loadCheckpoint(persistence, checkpointSha, { codec } = {}) {
@@ -220,16 +281,19 @@ export async function loadCheckpoint(persistence, checkpointSha, { codec } = {})
   const message = await persistence.showNode(checkpointSha);
   const decoded = /** @type {{ schema: number, stateHash: string, indexOid: string }} */ (decodeCheckpointMessage(message));
 
-  // 2. Reject schema:1 checkpoints - migration required
-  if (decoded.schema !== 2 && decoded.schema !== 3) {
+  // 2. Reject unsupported schemas - migration required for schema:1
+  if (decoded.schema !== 2 && decoded.schema !== 3 && decoded.schema !== 4) {
     throw new Error(
       `Checkpoint ${checkpointSha} is schema:${decoded.schema}. ` +
-        `Only schema:2 and schema:3 checkpoints are supported. Please migrate using MigrationService.`
+        `Only schema:2, schema:3, and schema:4 checkpoints are supported. Please migrate using MigrationService.`
     );
   }
 
   // 3. Read tree entries via the indexOid from the message (points to the tree)
-  const treeOids = await persistence.readTreeOids(decoded.indexOid);
+  const rawTreeOids = await persistence.readTreeOids(decoded.indexOid);
+
+  // 3b. Partition: entries with 'index/' prefix are bitmap index shards
+  const { treeOids, indexShardOids } = partitionTreeOids(rawTreeOids);
 
   // 4. Read frontier.cbor blob
   const frontierOid = treeOids['frontier.cbor'];
@@ -272,6 +336,7 @@ export async function loadCheckpoint(persistence, checkpointSha, { codec } = {})
     schema: decoded.schema,
     appliedVV,
     provenanceIndex: provenanceIndex || undefined,
+    indexShardOids: Object.keys(indexShardOids).length > 0 ? indexShardOids : null,
   };
 }