@git-stunts/git-warp 10.1.1

package/src/domain/services/CheckpointSerializerV5.js

@@ -0,0 +1,281 @@
+/**
+ * Checkpoint Serialization for WARP V5
+ *
+ * Provides full V5 state serialization including ORSet internals (entries + tombstones).
+ * This is the AUTHORITATIVE checkpoint format for V5 state.
+ *
+ * Key differences from StateSerializerV5:
+ * - StateSerializerV5 serializes the VISIBLE PROJECTION (for hashing)
+ * - CheckpointSerializerV5 serializes the FULL INTERNAL STATE (for resume)
+ *
+ * @module CheckpointSerializerV5
+ * @see WARP Spec Section 10 (Checkpoints)
+ */
+
+import defaultCodec from '../utils/defaultCodec.js';
+import { orsetSerialize, orsetDeserialize } from '../crdt/ORSet.js';
+import { vvSerialize, vvDeserialize } from '../crdt/VersionVector.js';
+import { decodeDot } from '../crdt/Dot.js';
+import { createEmptyStateV5 } from './JoinReducer.js';
+
+// ============================================================================
+// Full State Serialization (for Checkpoints)
+// ============================================================================
+
+/**
+ * Serializes full V5 state including ORSet internals (entries + tombstones).
+ * This is the AUTHORITATIVE checkpoint format.
+ *
+ * Structure:
+ * {
+ *   nodeAlive: { entries: [[element, [dots...]], ...], tombstones: [dots...] },
+ *   edgeAlive: { entries: [[element, [dots...]], ...], tombstones: [dots...] },
+ *   prop: [[propKey, {eventId: {...}, value: ...}], ...],
+ *   observedFrontier: { writerId: counter, ... }
+ * }
+ *
+ * @param {import('./JoinReducer.js').WarpStateV5} state
+ * @param {Object} [options]
+ * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
+ * @returns {Buffer} CBOR-encoded full state
+ */
+export function serializeFullStateV5(state, { codec } = {}) {
+  const c = codec || defaultCodec;
+  // Serialize ORSets using existing serialization
+  const nodeAliveObj = orsetSerialize(state.nodeAlive);
+  const edgeAliveObj = orsetSerialize(state.edgeAlive);
+
+  // Serialize props as sorted array of [key, register] pairs
+  const propArray = [];
+  for (const [key, register] of state.prop) {
+    propArray.push([key, serializeLWWRegister(register)]);
+  }
+  // Sort by key for determinism
+  propArray.sort((a, b) => {
+    const keyA = /** @type {string} */ (a[0]);
+    const keyB = /** @type {string} */ (b[0]);
+    return keyA < keyB ? -1 : keyA > keyB ? 1 : 0;
+  });
+
+  // Serialize observedFrontier
+  const observedFrontierObj = vvSerialize(state.observedFrontier);
+
+  // Serialize edgeBirthEvent as sorted array of [edgeKey, eventId] pairs
+  const edgeBirthArray = [];
+  if (state.edgeBirthEvent) {
+    for (const [key, eventId] of state.edgeBirthEvent) {
+      edgeBirthArray.push([key, { lamport: eventId.lamport, writerId: eventId.writerId, patchSha: eventId.patchSha, opIndex: eventId.opIndex }]);
+    }
+    edgeBirthArray.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  }
+
+  const obj = {
+    version: 'full-v5',
+    nodeAlive: nodeAliveObj,
+    edgeAlive: edgeAliveObj,
+    prop: propArray,
+    observedFrontier: observedFrontierObj,
+    edgeBirthEvent: edgeBirthArray,
+  };
+
+  return c.encode(obj);
+}
+
+/**
+ * Deserializes full V5 state. Used for resume.
+ *
+ * @param {Buffer} buffer - CBOR-encoded full state
+ * @param {Object} [options]
+ * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
+ * @returns {import('./JoinReducer.js').WarpStateV5}
+ */
+// eslint-disable-next-line complexity
+export function deserializeFullStateV5(buffer, { codec: codecOpt } = {}) {
+  const codec = codecOpt || defaultCodec;
+  // Handle null/undefined buffer before attempting decode
+  if (buffer === null || buffer === undefined) {
+    return createEmptyStateV5();
+  }
+
+  const obj = codec.decode(buffer);
+
+  // Handle null/undefined decoded result: return empty state
+  if (obj === null || obj === undefined) {
+    return createEmptyStateV5();
+  }
+
+  // Handle version mismatch: throw with diagnostic info
+  // Accept both 'full-v5' and missing version (for backward compatibility with pre-versioned data)
+  if (obj.version !== undefined && obj.version !== 'full-v5') {
+    throw new Error(
+      `Unsupported full state version: expected 'full-v5', got '${obj.version}'`
+    );
+  }
+
+  return {
+    nodeAlive: orsetDeserialize(obj.nodeAlive || {}),
+    edgeAlive: orsetDeserialize(obj.edgeAlive || {}),
+    prop: deserializeProps(obj.prop),
+    observedFrontier: vvDeserialize(obj.observedFrontier || {}),
+    edgeBirthEvent: deserializeEdgeBirthEvent(obj),
+  };
+}
+
+// ============================================================================
+// AppliedVV Computation and Serialization
+// ============================================================================
+
+/**
+ * Computes appliedVV by scanning all dots in state.
+ * Scans state.nodeAlive.entries and state.edgeAlive.entries for all dots.
+ * Returns Map<writerId, maxCounter>.
+ *
+ * CRITICAL: This scans ALL dots, including those that may be tombstoned.
+ * The appliedVV represents what operations have been applied, not what is visible.
+ *
+ * @param {import('./JoinReducer.js').WarpStateV5} state
+ * @returns {Map<string, number>} Map<writerId, maxCounter>
+ */
+export function computeAppliedVV(state) {
+  const vv = new Map();
+
+  /**
+   * Helper to scan all dots from an ORSet and update vv with max counters.
+   * @param {import('../crdt/ORSet.js').ORSet} orset
+   */
+  function scanORSet(orset) {
+    for (const dots of orset.entries.values()) {
+      for (const encodedDot of dots) {
+        const dot = decodeDot(encodedDot);
+        const current = vv.get(dot.writerId) || 0;
+        if (dot.counter > current) {
+          vv.set(dot.writerId, dot.counter);
+        }
+      }
+    }
+  }
+
+  // Scan nodeAlive entries
+  scanORSet(state.nodeAlive);
+
+  // Scan edgeAlive entries
+  scanORSet(state.edgeAlive);
+
+  return vv;
+}
+
+/**
+ * Serializes appliedVV to CBOR format.
+ *
+ * @param {Map<string, number>} vv - Version vector (Map<writerId, counter>)
+ * @param {Object} [options]
+ * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
+ * @returns {Buffer} CBOR-encoded version vector
+ */
+export function serializeAppliedVV(vv, { codec } = {}) {
+  const c = codec || defaultCodec;
+  const obj = vvSerialize(vv);
+  return c.encode(obj);
+}
+
+/**
+ * Deserializes appliedVV from CBOR format.
+ *
+ * @param {Buffer} buffer - CBOR-encoded version vector
+ * @param {Object} [options]
+ * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
+ * @returns {Map<string, number>} Version vector
+ */
+export function deserializeAppliedVV(buffer, { codec } = {}) {
+  const c = codec || defaultCodec;
+  const obj = c.decode(buffer);
+  return vvDeserialize(obj);
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Deserializes the props array from checkpoint format.
+ * @param {Array} propArray - Array of [key, registerObj] pairs
+ * @returns {Map<string, import('../crdt/LWW.js').LWWRegister>}
+ */
+function deserializeProps(propArray) {
+  const prop = new Map();
+  if (propArray && Array.isArray(propArray)) {
+    for (const [key, registerObj] of propArray) {
+      prop.set(key, deserializeLWWRegister(registerObj));
+    }
+  }
+  return prop;
+}
+
+/**
+ * Deserializes edge birth event data, supporting both legacy and current formats.
+ * @param {Object} obj - The decoded checkpoint object
+ * @returns {Map<string, Object>}
+ */
+function deserializeEdgeBirthEvent(obj) {
+  const edgeBirthEvent = new Map();
+  const birthData = obj.edgeBirthEvent || obj.edgeBirthLamport;
+  if (birthData && Array.isArray(birthData)) {
+    for (const [key, val] of birthData) {
+      if (typeof val === 'number') {
+        // Legacy format: bare lamport number → synthesize minimal EventId.
+        // Empty writerId and placeholder patchSha are sentinels indicating
+        // this EventId was reconstructed from pre-v5 data, not a real writer.
+        edgeBirthEvent.set(key, { lamport: val, writerId: '', patchSha: '0000', opIndex: 0 });
+      } else {
+        // Shallow copy to avoid sharing a reference with the decoded CBOR object
+        edgeBirthEvent.set(key, { lamport: val.lamport, writerId: val.writerId, patchSha: val.patchSha, opIndex: val.opIndex });
+      }
+    }
+  }
+  return edgeBirthEvent;
+}
+
+/**
+ * Serializes an LWW register for CBOR encoding.
+ * EventId is serialized as a plain object with sorted keys.
+ *
+ * @param {import('../crdt/LWW.js').LWWRegister} register
+ * @returns {Object}
+ */
+function serializeLWWRegister(register) {
+  if (!register) {
+    return null;
+  }
+
+  return {
+    eventId: {
+      lamport: register.eventId.lamport,
+      opIndex: register.eventId.opIndex,
+      patchSha: register.eventId.patchSha,
+      writerId: register.eventId.writerId,
+    },
+    value: register.value,
+  };
+}
+
+/**
+ * Deserializes an LWW register from CBOR.
+ *
+ * @param {Object} obj
+ * @returns {import('../crdt/LWW.js').LWWRegister}
+ */
+function deserializeLWWRegister(obj) {
+  if (!obj) {
+    return null;
+  }
+
+  return {
+    eventId: {
+      lamport: obj.eventId.lamport,
+      writerId: obj.eventId.writerId,
+      patchSha: obj.eventId.patchSha,
+      opIndex: obj.eventId.opIndex,
+    },
+    value: obj.value,
+  };
+}

package/src/domain/services/CheckpointService.js

@@ -0,0 +1,384 @@
+/**
+ * Checkpoint Service for WARP multi-writer graph database.
+ *
+ * Provides functionality for creating and loading schema:2 and schema:3
+ * checkpoints, as well as incremental state materialization from checkpoints.
+ *
+ * This service supports schema:2 and schema:3 (V5) checkpoints. Schema:1 (V4)
+ * checkpoints must be migrated before use.
+ *
+ * @module CheckpointService
+ * @see WARP Spec Section 10
+ */
+
+import { serializeStateV5, computeStateHashV5 } from './StateSerializerV5.js';
+import {
+  serializeFullStateV5,
+  deserializeFullStateV5,
+  computeAppliedVV,
+  serializeAppliedVV,
+  deserializeAppliedVV,
+} from './CheckpointSerializerV5.js';
+import { serializeFrontier, deserializeFrontier } from './Frontier.js';
+import { encodeCheckpointMessage, decodeCheckpointMessage } from './WarpMessageCodec.js';
+import { createORSet, orsetAdd, orsetCompact } from '../crdt/ORSet.js';
+import { createDot } from '../crdt/Dot.js';
+import { createVersionVector } from '../crdt/VersionVector.js';
+import { cloneStateV5, reduceV5 } from './JoinReducer.js';
+import { encodeEdgeKey, encodePropKey } from './KeyCodec.js';
+import { ProvenanceIndex } from './ProvenanceIndex.js';
+
+// ============================================================================
+// Checkpoint Creation (WARP spec Section 10)
+// ============================================================================
+
+/**
+ * Creates a schema:2 checkpoint commit containing serialized V5 state and frontier.
+ *
+ * Tree structure:
+ * ```
+ * <checkpoint_commit_tree>/
+ * ├── state.cbor           # AUTHORITATIVE: Full V5 state (ORSets + props)
+ * ├── visible.cbor         # CACHE ONLY: Visible projection for fast queries
+ * ├── frontier.cbor        # Writer frontiers
+ * ├── appliedVV.cbor       # Version vector of dots in state
+ * └── provenanceIndex.cbor # Optional: node-to-patchSha index (HG/IO/2)
+ * ```
+ *
+ * @param {Object} options - Checkpoint creation options
+ * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Git persistence adapter
+ * @param {string} options.graphName - Name of the graph
+ * @param {import('./JoinReducer.js').WarpStateV5} options.state - The V5 state to checkpoint
+ * @param {import('./Frontier.js').Frontier} options.frontier - Writer frontier map
+ * @param {string[]} [options.parents=[]] - Parent commit SHAs (typically prior checkpoint or patch commits)
+ * @param {boolean} [options.compact=true] - Whether to compact tombstoned dots before saving
+ * @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
+ * @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 });
+}
+
+/**
+ * Creates a V5 checkpoint commit with full ORSet state.
+ *
+ * V5 Checkpoint Tree Structure:
+ * ```
+ * <checkpoint_tree>/
+ * ├── state.cbor           # AUTHORITATIVE: Full V5 state (ORSets + props)
+ * ├── visible.cbor         # CACHE ONLY: Visible projection for fast queries
+ * ├── frontier.cbor        # Writer frontiers
+ * ├── appliedVV.cbor       # Version vector of dots in state
+ * └── provenanceIndex.cbor # Optional: node-to-patchSha index (HG/IO/2)
+ * ```
+ *
+ * @param {Object} options - Checkpoint creation options
+ * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Git persistence adapter
+ * @param {string} options.graphName - Name of the graph
+ * @param {import('./JoinReducer.js').WarpStateV5} options.state - The V5 state to checkpoint
+ * @param {import('./Frontier.js').Frontier} options.frontier - Writer frontier map
+ * @param {string[]} [options.parents=[]] - Parent commit SHAs
+ * @param {boolean} [options.compact=true] - Whether to compact tombstoned dots before saving
+ * @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
+ * @returns {Promise<string>} The checkpoint commit SHA
+ */
+export async function createV5({
+  persistence,
+  graphName,
+  state,
+  frontier,
+  parents = [],
+  compact = true,
+  provenanceIndex,
+  codec,
+  crypto,
+}) {
+  // 1. Compute appliedVV from actual state dots
+  const appliedVV = computeAppliedVV(state);
+
+  // 2. Optionally compact (only tombstoned dots <= appliedVV)
+  let checkpointState = state;
+  if (compact) {
+    checkpointState = cloneStateV5(state);
+    orsetCompact(checkpointState.nodeAlive, appliedVV);
+    orsetCompact(checkpointState.edgeAlive, appliedVV);
+  }
+
+  // 3. Serialize full state (AUTHORITATIVE)
+  const stateBuffer = serializeFullStateV5(checkpointState, { codec });
+
+  // 4. Serialize visible projection (CACHE)
+  const visibleBuffer = serializeStateV5(checkpointState, { codec });
+  const stateHash = await computeStateHashV5(checkpointState, { codec, crypto });
+
+  // 5. Serialize frontier and appliedVV
+  const frontierBuffer = serializeFrontier(frontier, { codec });
+  const appliedVVBuffer = serializeAppliedVV(appliedVV, { codec });
+
+  // 6. Write blobs to git
+  const stateBlobOid = await persistence.writeBlob(stateBuffer);
+  const visibleBlobOid = await persistence.writeBlob(visibleBuffer);
+  const frontierBlobOid = await persistence.writeBlob(frontierBuffer);
+  const appliedVVBlobOid = await persistence.writeBlob(appliedVVBuffer);
+
+  // 6b. Optionally serialize and write provenance index
+  let provenanceIndexBlobOid = null;
+  if (provenanceIndex) {
+    const provenanceIndexBuffer = provenanceIndex.serialize({ codec });
+    provenanceIndexBlobOid = await persistence.writeBlob(provenanceIndexBuffer);
+  }
+
+  // 7. Create tree with sorted entries
+  const treeEntries = [
+    `100644 blob ${appliedVVBlobOid}\tappliedVV.cbor`,
+    `100644 blob ${frontierBlobOid}\tfrontier.cbor`,
+    `100644 blob ${stateBlobOid}\tstate.cbor`,
+    `100644 blob ${visibleBlobOid}\tvisible.cbor`,
+  ];
+
+  // Add provenance index if present
+  if (provenanceIndexBlobOid) {
+    treeEntries.push(`100644 blob ${provenanceIndexBlobOid}\tprovenanceIndex.cbor`);
+  }
+
+  // Sort entries by filename for deterministic tree (git requires sorted entries by path)
+  treeEntries.sort((a, b) => {
+    const filenameA = a.split('\t')[1];
+    const filenameB = b.split('\t')[1];
+    return filenameA.localeCompare(filenameB);
+  });
+
+  const treeOid = await persistence.writeTree(treeEntries);
+
+  // 8. Create checkpoint commit message with v5 trailer
+  const message = encodeCheckpointMessage({
+    graph: graphName,
+    stateHash,
+    frontierOid: frontierBlobOid,
+    indexOid: treeOid,
+    schema: 2,
+  });
+
+  // 9. Create the checkpoint commit
+  const checkpointSha = await persistence.commitNodeWithTree({
+    treeOid,
+    parents,
+    message,
+  });
+
+  return checkpointSha;
+}
+
+// ============================================================================
+// Checkpoint Loading
+// ============================================================================
+
+/**
+ * Loads a schema:2 checkpoint from a commit SHA.
+ *
+ * Reads the checkpoint commit, extracts the tree entries,
+ * and deserializes the V5 state and frontier.
+ *
+ * Loads state.cbor as AUTHORITATIVE full ORSet state
+ * (NEVER uses visible.cbor for resume - it's cache only)
+ *
+ * Schema:1 checkpoints are not supported and will throw an error.
+ * Use MigrationService to upgrade schema:1 checkpoints first.
+ *
+ * @param {import('../../ports/GraphPersistencePort.js').default} persistence - Git persistence adapter
+ * @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>, provenanceIndex?: import('./ProvenanceIndex.js').ProvenanceIndex}>} The loaded checkpoint data
+ * @throws {Error} If checkpoint is schema:1 (migration required)
+ */
+export async function loadCheckpoint(persistence, checkpointSha, { codec } = {}) {
+  // 1. Read commit message and decode
+  const message = await persistence.showNode(checkpointSha);
+  const decoded = decodeCheckpointMessage(message);
+
+  // 2. Reject schema:1 checkpoints - migration required
+  if (decoded.schema !== 2 && decoded.schema !== 3) {
+    throw new Error(
+      `Checkpoint ${checkpointSha} is schema:${decoded.schema}. ` +
+        `Only schema:2 and schema:3 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);
+
+  // 4. Read frontier.cbor blob
+  const frontierOid = treeOids['frontier.cbor'];
+  if (!frontierOid) {
+    throw new Error(`Checkpoint ${checkpointSha} missing frontier.cbor in tree`);
+  }
+  const frontierBuffer = await persistence.readBlob(frontierOid);
+  const frontier = deserializeFrontier(frontierBuffer, { codec });
+
+  // 5. Read state.cbor blob and deserialize as V5 full state
+  const stateOid = treeOids['state.cbor'];
+  if (!stateOid) {
+    throw new Error(`Checkpoint ${checkpointSha} missing state.cbor in tree`);
+  }
+  const stateBuffer = await persistence.readBlob(stateOid);
+
+  // V5: Load AUTHORITATIVE full state from state.cbor (NEVER use visible.cbor for resume)
+  const state = deserializeFullStateV5(stateBuffer, { codec });
+
+  // Load appliedVV if present
+  let appliedVV = null;
+  const appliedVVOid = treeOids['appliedVV.cbor'];
+  if (appliedVVOid) {
+    const appliedVVBuffer = await persistence.readBlob(appliedVVOid);
+    appliedVV = deserializeAppliedVV(appliedVVBuffer, { codec });
+  }
+
+  // Load provenanceIndex if present (HG/IO/2)
+  let provenanceIndex = null;
+  const provenanceIndexOid = treeOids['provenanceIndex.cbor'];
+  if (provenanceIndexOid) {
+    const provenanceIndexBuffer = await persistence.readBlob(provenanceIndexOid);
+    provenanceIndex = ProvenanceIndex.deserialize(provenanceIndexBuffer, { codec });
+  }
+
+  return {
+    state,
+    frontier,
+    stateHash: decoded.stateHash,
+    schema: decoded.schema,
+    appliedVV,
+    provenanceIndex,
+  };
+}
+
+// ============================================================================
+// Incremental Materialization
+// ============================================================================
+
+/**
+ * Materializes V5 state incrementally from a schema:2 checkpoint.
+ *
+ * Loads the checkpoint state and frontier, then applies all patches
+ * since the checkpoint frontier to reach the target frontier.
+ *
+ * Only supports schema:2 checkpoints. Schema:1 checkpoints will cause
+ * loadCheckpoint to throw an error.
+ *
+ * @param {Object} options - Materialization options
+ * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Git persistence adapter
+ * @param {string} options.graphName - Name of the graph
+ * @param {string} options.checkpointSha - The schema:2 checkpoint commit SHA to start from
+ * @param {import('./Frontier.js').Frontier} options.targetFrontier - The target frontier to materialize to
+ * @param {Function} options.patchLoader - Async function to load patches: (writerId, fromSha, toSha) => Array<{patch, sha}>
+ * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for CBOR deserialization
+ * @returns {Promise<import('./JoinReducer.js').WarpStateV5>} The materialized V5 state at targetFrontier
+ * @throws {Error} If checkpoint is schema:1 (migration required)
+ * @throws {Error} If checkpoint is missing required blobs (state.cbor, frontier.cbor)
+ */
+export async function materializeIncremental({
+  persistence,
+  graphName: _graphName,
+  checkpointSha,
+  targetFrontier,
+  patchLoader,
+  codec,
+}) {
+  // 1. Load checkpoint state and frontier (schema:2 returns full V5 state)
+  const checkpoint = await loadCheckpoint(persistence, checkpointSha, { codec });
+  const checkpointFrontier = checkpoint.frontier;
+
+  // 2. Use checkpoint state directly (schema:2 stores full V5 state)
+  const initialState = checkpoint.state;
+
+  // 3. Collect patches since checkpoint frontier for each writer
+  const allPatches = [];
+
+  for (const [writerId, targetSha] of targetFrontier) {
+    const cpSha = checkpointFrontier.get(writerId);
+
+    // If writer wasn't in checkpoint frontier, load all their patches up to targetSha
+    // If writer was in checkpoint, load patches from checkpoint SHA to target SHA
+    const patches = await patchLoader(writerId, cpSha || null, targetSha);
+    allPatches.push(...patches);
+  }
+
+  // 4. If no new patches, return the checkpoint state as-is
+  if (allPatches.length === 0) {
+    return initialState;
+  }
+
+  // 5. Apply new patches using V5 reducer with checkpoint state as initial
+  const finalState = reduceV5(allPatches, initialState);
+
+  return finalState;
+}
+
+/**
+ * Reconstructs WarpStateV5 (ORSet-based) from a checkpoint's visible projection.
+ *
+ * Creates ORSet-based state with synthetic dots for all visible elements.
+ * This is used when loading a v5 checkpoint for incremental materialization.
+ *
+ * @param {Object} visibleProjection - The checkpoint's visible projection
+ * @param {string[]} visibleProjection.nodes - Visible node IDs
+ * @param {Array<{from: string, to: string, label: string}>} visibleProjection.edges - Visible edges
+ * @param {Array<{node: string, key: string, value: *}>} visibleProjection.props - Visible properties
+ * @returns {import('./JoinReducer.js').WarpStateV5} Reconstructed WarpStateV5
+ * @public
+ */
+export function reconstructStateV5FromCheckpoint(visibleProjection) {
+  const { nodes, edges, props } = visibleProjection;
+
+  // Create a synthetic dot for checkpoint entries
+  // Uses a special writerId that won't conflict with real writers
+  // Counter starts at 1 (0 is invalid for dots)
+  const syntheticDot = createDot('__checkpoint__', 1);
+
+  // Create a synthetic eventId for LWW props
+  const syntheticEventId = {
+    lamport: 0,
+    writerId: '__checkpoint__',
+    patchSha: '0000000000000000000000000000000000000000',
+    opIndex: 0,
+  };
+
+  const nodeAlive = createORSet();
+  const edgeAlive = createORSet();
+  const prop = new Map();
+  const observedFrontier = createVersionVector();
+
+  // Reconstruct nodes as ORSet entries
+  for (const nodeId of nodes) {
+    orsetAdd(nodeAlive, nodeId, syntheticDot);
+  }
+
+  // Reconstruct edges as ORSet entries
+  for (const edge of edges) {
+    const edgeKey = encodeEdgeKey(edge.from, edge.to, edge.label);
+    orsetAdd(edgeAlive, edgeKey, syntheticDot);
+  }
+
+  // Reconstruct props with LWW registers (same as v4)
+  for (const p of props) {
+    const propKey = encodePropKey(p.node, p.key);
+    prop.set(propKey, {
+      eventId: syntheticEventId,
+      value: p.value,
+    });
+  }
+
+  // Reconstruct edgeBirthEvent: synthetic birth at lamport 0
+  // so checkpoint-loaded props pass the visibility filter
+  const edgeBirthEvent = new Map();
+  for (const edge of edges) {
+    const edgeKey = encodeEdgeKey(edge.from, edge.to, edge.label);
+    edgeBirthEvent.set(edgeKey, { lamport: 0, writerId: '', patchSha: '0000', opIndex: 0 });
+  }
+
+  return { nodeAlive, edgeAlive, prop, observedFrontier, edgeBirthEvent };
+}