@git-stunts/git-warp 12.2.0 → 12.2.1

package/README.md

@@ -8,12 +8,12 @@
   <img src="docs/images/hero.gif" alt="git-warp CLI demo" width="600">
 </p>
 
-## What's New in v12.2.0
+## What's New in v12.2.1
 
-- **O(N log N) topological sort** — `topologicalSort()` now uses a MinHeap ready queue instead of sorted-array merging, eliminating the O(N²) hot path for large DAGs.
-- **QueryBuilder batching + memoization** — property fetches are now bounded (chunks of 100) and cached per-run, reducing redundant I/O across where-clauses, result building, and aggregation.
-- **Fast materialization guard** — `_materializeGraph()` skips full materialization when cached state is clean, improving query/traversal latency.
-- **Checkpoint `visible.cbor` removed** — checkpoints no longer write the unused visible-projection blob, saving one serialize + blob write per checkpoint.
+- **M12 SCALPEL complete** — 42-item STANK audit fully resolved: 15 bug fixes, 20+ JSDoc/documentation improvements, and 6 refactors across CRDT core, services, sync, and CLI.
+- **Sync correctness hardened** — `join()` state install, `applySyncResponse` cache coherence, unknown-op rejection (fail-closed), and divergence pre-check all fixed.
+- **Incremental index improvements** — stale label ID collision fix, re-add edge restoration via adjacency cache, and bitmap churn reduction for node removal.
+- **canonicalStringify shared-reference fix** — cycle detection now correctly allows valid DAG structures (shared non-circular references).
 
 See the [full changelog](CHANGELOG.md) for details.
 
@@ -105,7 +105,7 @@ When you want to read the graph, you **materialize** — which means replaying a
 
 Every operation gets a unique **EventId** — `(lamport, writerId, patchSha, opIndex)` — which creates a total ordering that makes merge results identical no matter which machine runs them.
 
-**Checkpoints** snapshot the materialized state into a single commit for fast incremental recovery. Subsequent materializations only need to replay patches created after the checkpoint.
+**Checkpoints** snapshot the materialized state into a single commit for fast incremental recovery. Subsequent materializations only need to replay patches created after the checkpoint. During incremental replay, checkpoint ancestry is validated once per writer tip (not once per patch), which keeps long writer chains efficient.
 
 ## Multi-Writer Collaboration
 
@@ -474,6 +474,8 @@ const graph = await WarpGraph.open({
 });
 ```
 
+When cached state is clean, local commits take an eager path that applies the patch in-memory and threads a patch diff into view rebuild (`_setMaterializedState(..., { diff })`). That allows incremental bitmap index updates on the hot write path instead of full index rebuilds.
+
 ## Observability
 
 ```javascript

package/bin/cli/commands/trust.js

@@ -14,6 +14,7 @@ import defaultCodec from '../../../src/domain/utils/defaultCodec.js';
 import { TrustRecordService } from '../../../src/domain/trust/TrustRecordService.js';
 import { buildState } from '../../../src/domain/trust/TrustStateBuilder.js';
 import { evaluateWriters } from '../../../src/domain/trust/TrustEvaluator.js';
+import { TRUST_REASON_CODES } from '../../../src/domain/trust/reasonCodes.js';
 
 /** @typedef {import('../types.js').CliOptions} CliOptions */
 
@@ -112,8 +113,43 @@ export default async function handleTrust({ options, args }) {
   const { pin, source, sourceDetail, status } = resolveTrustPin(trustPin);
 
   // Read trust records
-  const records = await recordService.readRecords(graphName, pin ? { tip: pin } : {});
+  const recordsResult = await recordService.readRecords(graphName, pin ? { tip: pin } : {});
+  if (!recordsResult.ok) {
+    const payload = {
+      graph: graphName,
+      trustSchemaVersion: 1,
+      mode: 'signed_evidence_v1',
+      trustVerdict: 'fail',
+      trust: {
+        status: 'error',
+        source,
+        sourceDetail,
+        evaluatedWriters: [],
+        untrustedWriters: [],
+        explanations: [
+          {
+            writerId: '*',
+            trusted: false,
+            reasonCode: TRUST_REASON_CODES.TRUST_RECORD_CHAIN_INVALID,
+            reason: `Trust chain read failed: ${recordsResult.error.message}`,
+          },
+        ],
+        evidenceSummary: {
+          recordsScanned: 0,
+          activeKeys: 0,
+          revokedKeys: 0,
+          activeBindings: 0,
+          revokedBindings: 0,
+        },
+      },
+    };
+    return {
+      payload,
+      exitCode: mode === 'enforce' ? EXIT_CODES.TRUST_FAIL : EXIT_CODES.OK,
+    };
+  }
 
+  const { records } = recordsResult;
   if (records.length === 0) {
     return buildNotConfiguredResult(graphName);
   }

package/bin/cli/infrastructure.js

@@ -166,6 +166,12 @@ const BASE_OPTIONS = {
  * Pre-processes argv to handle --view's optional-value semantics.
  * If --view is followed by a command name or flag (or is last), injects 'ascii'.
  * Validates the view mode value.
+ *
+ * When --view is passed without a value, we inject 'ascii' as the default.
+ * This happens before validation so the downstream parser sees a concrete
+ * value. The synthetic injection is intentional — parseArgs requires --view
+ * to have a value even though the CLI allows bare --view.
+ *
  * @param {string[]} argv
  * @returns {string[]}
  */
@@ -223,6 +229,7 @@ function extractBaseArgs(argv) {
   const rest = [];
   /** @type {string|undefined} */
   let command;
+  // Phase 1: Pre-command — scan for base flags (--repo, --json, --view, etc.)
   let pastCommand = false;
 
   for (let i = 0; i < argv.length; i++) {
@@ -266,7 +273,13 @@ function extractBaseArgs(argv) {
       continue;
     }
 
-    if (!pastCommand && !arg.startsWith('-')) {
+    if (pastCommand) {
+      // Phase 2: Post-command — remaining args are command-specific, stop scanning
+      rest.push(arg);
+      continue;
+    }
+
+    if (!arg.startsWith('-')) {
       command = arg;
       pastCommand = true;
       continue;

package/bin/cli/schemas.js

@@ -36,7 +36,7 @@ export const pathSchema = z.object({
   to: z.string().optional(),
   dir: z.enum(['out', 'in', 'both']).optional(),
   label: z.union([z.string(), z.array(z.string())]).optional(),
-  'max-depth': z.coerce.number().int().nonnegative().optional(),
+  'max-depth': z.coerce.number().int().nonnegative().refine(n => Number.isFinite(n), { message: 'must be a finite number' }).optional(),
 }).strict().transform((val) => ({
   from: val.from ?? null,
   to: val.to ?? null,
@@ -102,7 +102,7 @@ export const seekSchema = z.object({
   'clear-cache': z.boolean().default(false),
   'no-persistent-cache': z.boolean().default(false),
   diff: z.boolean().default(false),
-  'diff-limit': z.coerce.number().int({ message: '--diff-limit must be a positive integer' }).positive({ message: '--diff-limit must be a positive integer' }).default(2000),
+  'diff-limit': z.coerce.number().int({ message: '--diff-limit must be a positive integer' }).positive({ message: '--diff-limit must be a positive integer' }).refine(n => Number.isFinite(n), { message: '--diff-limit must be a finite number' }).default(2000),
 }).strict().superRefine((val, ctx) => {
   // Count mutually exclusive action flags
   const actions = [
@@ -181,8 +181,8 @@ export const seekSchema = z.object({
 // ============================================================================
 
 export const verifyIndexSchema = z.object({
-  seed: z.coerce.number().int().min(-2147483648).max(2147483647).optional(),
-  'sample-rate': z.coerce.number().gt(0, '--sample-rate must be greater than 0').max(1).optional().default(0.1),
+  seed: z.coerce.number().int().min(-2147483648).max(2147483647).refine(n => Number.isFinite(n), { message: 'must be a finite number' }).optional(),
+  'sample-rate': z.coerce.number().gt(0, '--sample-rate must be greater than 0').max(1).refine(n => Number.isFinite(n), { message: 'must be a finite number' }).optional().default(0.1),
 }).strict().transform((val) => ({
   seed: val.seed,
   sampleRate: val['sample-rate'],

package/bin/warp-graph.js

@@ -9,7 +9,10 @@ import { COMMANDS } from './cli/commands/registry.js';
 
 const VIEW_SUPPORTED_COMMANDS = ['info', 'check', 'history', 'path', 'materialize', 'query', 'seek'];
 
-// C8: Capture output format early so the error handler can use it
+// Output format must be captured from raw process.argv BEFORE parseArgs() runs.
+// If parseArgs() itself throws (e.g., unknown flag, malformed input), the `options`
+// object will not exist, so the error handler cannot read `options.json`. By
+// pre-scanning argv, the error handler can still emit structured output.
 const hasJsonFlag = process.argv.includes('--json');
 const hasNdjsonFlag = process.argv.includes('--ndjson');
 

package/index.d.ts

@@ -1060,6 +1060,20 @@ export class SchemaUnsupportedError extends Error {
   });
 }
 
+/**
+ * Error class for malformed or invalid patch operations.
+ */
+export class PatchError extends Error {
+  readonly name: 'PatchError';
+  readonly code: string;
+  readonly context: Record<string, unknown>;
+
+  constructor(message: string, options?: {
+    code?: string;
+    context?: Record<string, unknown>;
+  });
+}
+
 /**
  * Error class for sync transport operations.
  */
@@ -1530,6 +1544,7 @@ export interface SyncResponse {
   type: 'sync-response';
   frontier: Record<string, string>;
   patches: Array<{ writerId: string; sha: string; patch: unknown }>;
+  skippedWriters?: Array<{ writerId: string; reason: string; localSha: string; remoteSha: string | null }>;
 }
 
 /**
@@ -1539,6 +1554,7 @@ export interface ApplySyncResult {
   state: WarpStateV5;
   frontier: Map<string, number>;
   applied: number;
+  skippedWriters: Array<{ writerId: string; reason: string; localSha: string; remoteSha: string | null }>;
 }
 
 /**
@@ -1831,7 +1847,7 @@ export default class WarpGraph {
     auth?: SyncAuthClientOptions;
     /** Auto-materialize after sync; when true, result includes `state` */
     materialize?: boolean;
-  }): Promise<{ applied: number; attempts: number; state?: WarpStateV5 }>;
+  }): Promise<{ applied: number; attempts: number; skippedWriters: Array<{ writerId: string; reason: string; localSha: string; remoteSha: string | null }>; state?: WarpStateV5 }>;
 
   /**
    * Creates a fork of this graph at a specific point in a writer's history.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-warp",
-  "version": "12.2.0",
+  "version": "12.2.1",
   "description": "Deterministic WARP graph over Git: graph-native storage, traversal, and tooling.",
   "type": "module",
   "license": "Apache-2.0",

package/src/domain/WarpGraph.js

@@ -39,7 +39,7 @@ const DEFAULT_ADJACENCY_CACHE_SIZE = 3;
 /**
  * @typedef {Object} MaterializedGraph
  * @property {import('./services/JoinReducer.js').WarpStateV5} state
- * @property {string} stateHash
+ * @property {string|null} stateHash
  * @property {{outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>>}} adjacency
  * @property {import('./services/BitmapNeighborProvider.js').default} [provider]
  */

package/src/domain/crdt/Dot.js

@@ -109,6 +109,11 @@ export function encodeDot(dot) {
 /**
  * Decodes an encoded dot string back to a Dot object.
  *
+ * Writer IDs are parsed using lastIndexOf(':') as separator. Writer IDs
+ * containing colons are supported because the counter (after the last colon)
+ * is always numeric. However, empty writer IDs or IDs ending with a colon
+ * may produce unexpected results.
+ *
  * @param {string} encoded - Format: "writerId:counter"
  * @returns {Dot}
  * @throws {Error} If format is invalid

package/src/domain/crdt/LWW.js

@@ -126,7 +126,9 @@ export function lwwSet(eventId, value) {
  * @returns {LWWRegister<T> | null} Register with greater EventId, or null if both null/undefined
  */
 export function lwwMax(a, b) {
-  // Handle null/undefined cases
+  // Null/undefined values are handled defensively for forward compatibility.
+  // Current callers always provide non-null values, but the LWW register
+  // contract permits null as a valid tombstone value.
   if ((a === null || a === undefined) && (b === null || b === undefined)) {
     return null;
   }

package/src/domain/crdt/ORSet.js

@@ -221,24 +221,26 @@ export function orsetGetDots(set, element) {
 export function orsetJoin(a, b) {
   const result = createORSet();
 
-  // Union entries from a
+  // Copy entries from a into result — each dot set is shallow-copied so the
+  // caller cannot mutate the original through the result.
   for (const [element, dots] of a.entries) {
     result.entries.set(element, new Set(dots));
   }
 
-  // Union entries from b
+  // Merge entries from b — if the element already exists (from a), add into
+  // the cloned set; otherwise clone b's dot set the same way for consistency.
   for (const [element, dots] of b.entries) {
-    let resultDots = result.entries.get(element);
-    if (!resultDots) {
-      resultDots = new Set();
-      result.entries.set(element, resultDots);
-    }
-    for (const dot of dots) {
-      resultDots.add(dot);
+    const existing = result.entries.get(element);
+    if (existing) {
+      for (const dot of dots) {
+        existing.add(dot);
+      }
+    } else {
+      result.entries.set(element, new Set(dots));
     }
   }
 
-  // Union tombstones
+  // Union tombstones from both sides
   for (const dot of a.tombstones) {
     result.tombstones.add(dot);
   }
@@ -343,16 +345,19 @@ export function orsetClone(set) {
  * @returns {{entries: Array<[string, string[]]>, tombstones: string[]}}
  */
 export function orsetSerialize(set) {
-  // Serialize entries: convert Map to array of [element, sortedDots]
+  // Serialize entries: convert Map to array of [element, sortedDots].
+  // Pre-decode dots before sorting to avoid O(N log N) decodeDot calls
+  // during comparisons.
   /** @type {Array<[string, string[]]>} */
   const entriesArray = [];
   for (const [element, dots] of set.entries) {
-    const sortedDots = [...dots].sort((a, b) => {
-      const dotA = decodeDot(a);
-      const dotB = decodeDot(b);
-      return compareDots(dotA, dotB);
-    });
-    entriesArray.push([element, sortedDots]);
+    /** @type {Array<{encoded: string, decoded: import('./Dot.js').Dot}>} */
+    const pairs = [];
+    for (const encoded of dots) {
+      pairs.push({ encoded, decoded: decodeDot(encoded) });
+    }
+    pairs.sort((a, b) => compareDots(a.decoded, b.decoded));
+    entriesArray.push([element, pairs.map((p) => p.encoded)]);
   }
 
   // Sort entries by element (stringified for consistency)
@@ -362,12 +367,14 @@ export function orsetSerialize(set) {
     return keyA < keyB ? -1 : keyA > keyB ? 1 : 0;
   });
 
-  // Serialize tombstones: sorted array
-  const sortedTombstones = [...set.tombstones].sort((a, b) => {
-    const dotA = decodeDot(a);
-    const dotB = decodeDot(b);
-    return compareDots(dotA, dotB);
-  });
+  // Serialize tombstones: pre-decode then sort
+  /** @type {Array<{encoded: string, decoded: import('./Dot.js').Dot}>} */
+  const tombPairs = [];
+  for (const encoded of set.tombstones) {
+    tombPairs.push({ encoded, decoded: decodeDot(encoded) });
+  }
+  tombPairs.sort((a, b) => compareDots(a.decoded, b.decoded));
+  const sortedTombstones = tombPairs.map((p) => p.encoded);
 
   return {
     entries: entriesArray,

package/src/domain/crdt/VersionVector.js

@@ -160,11 +160,19 @@ export function vvContains(vv, dot) {
 export function vvSerialize(vv) {
   /** @type {Record<string, number>} */
   const obj = {};
+  // Key sort is required for deterministic serialization. The writer count
+  // is typically small (<100), so the O(W log W) cost is negligible.
   const sortedKeys = [...vv.keys()].sort();
 
   for (const key of sortedKeys) {
     const val = vv.get(key);
     if (val !== undefined) {
+      // Invariant assertion — not input validation. Zero counters must never
+      // appear in a VersionVector. They carry no causal information and would
+      // be elided on deserialization, breaking round-trip equality.
+      if (val === 0) {
+        throw new Error(`vvSerialize: zero counter for writerId "${key}" — VersionVector must not contain zero counters`);
+      }
       obj[key] = val;
     }
   }
@@ -175,6 +183,10 @@ export function vvSerialize(vv) {
 /**
  * Deserializes a plain object back to a VersionVector.
  *
+ * Zero counters are elided during deserialization. This is intentional — a
+ * counter of 0 carries no causal information and wastes space. Serialization
+ * must never emit zero counters.
+ *
  * @param {Object<string, number>} obj
  * @returns {VersionVector}
  * @throws {Error} If any counter value is not a non-negative integer

package/src/domain/errors/PatchError.js

@@ -0,0 +1,27 @@
+import WarpError from './WarpError.js';
+
+/**
+ * Error class for malformed or invalid patch operations.
+ *
+ * ## Error Codes
+ *
+ * | Code | Description |
+ * |------|-------------|
+ * | `E_PATCH_MALFORMED` | Operation is missing required fields or has invalid types |
+ *
+ * @class PatchError
+ * @extends WarpError
+ *
+ * @property {string} name - Always 'PatchError' for instanceof checks
+ * @property {string} code - Machine-readable error code for programmatic handling
+ * @property {Object} context - Serializable context object with error details
+ */
+export default class PatchError extends WarpError {
+  /**
+   * @param {string} message
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
+   */
+  constructor(message, options = {}) {
+    super(message, 'E_PATCH_MALFORMED', options);
+  }
+}

package/src/domain/errors/StorageError.js

@@ -3,6 +3,10 @@ import IndexError from './IndexError.js';
 /**
  * Error thrown when a storage operation fails.
  *
+ * StorageError extends IndexError because storage errors originate from
+ * index operations. This hierarchy is intentional — IndexError provides
+ * the storage-specific error context.
+ *
  * This error indicates that a read or write operation to storage failed,
  * typically due to I/O errors, permission issues, or storage unavailability.
  *
@@ -31,6 +35,10 @@ export default class StorageError extends IndexError {
   /**
    * Creates a new StorageError.
    *
+   * Context is merged via Object.assign — duplicate keys from the second
+   * argument overwrite the first. Callers should ensure context keys don't
+   * collide, or use unique prefixes.
+   *
    * @param {string} message - Human-readable error message
    * @param {{ operation?: string, oid?: string, cause?: Error, context?: Record<string, unknown> }} [options={}] - Error options
    */

package/src/domain/errors/WriterError.js

@@ -26,6 +26,11 @@ import WarpError from './WarpError.js';
  */
 export default class WriterError extends WarpError {
   /**
+   * Note: constructor parameter order differs from other WarpError subclasses
+   * (code, message vs message, code). This is intentional to match the most
+   * common call sites in PatchSession and PatchBuilderV2 where the error code
+   * is the primary discriminator.
+   *
    * @param {string} code - Error code
    * @param {string} message - Human-readable error message
    * @param {Error} [cause] - Original error that caused this error

package/src/domain/errors/index.js

@@ -9,6 +9,7 @@ export { default as WarpError } from './WarpError.js';
 export { default as ForkError } from './ForkError.js';
 export { default as IndexError } from './IndexError.js';
 export { default as OperationAbortedError } from './OperationAbortedError.js';
+export { default as PatchError } from './PatchError.js';
 export { default as QueryError } from './QueryError.js';
 export { default as SyncError } from './SyncError.js';
 export { default as ShardCorruptionError } from './ShardCorruptionError.js';

package/src/domain/services/AuditVerifierService.js

@@ -34,6 +34,7 @@ import { decodeAuditMessage } from './AuditMessageCodec.js';
 import { TrustRecordService } from '../trust/TrustRecordService.js';
 import { buildState } from '../trust/TrustStateBuilder.js';
 import { evaluateWriters } from '../trust/TrustEvaluator.js';
+import { TRUST_REASON_CODES } from '../trust/reasonCodes.js';
 
 // ============================================================================
 // Constants
@@ -667,7 +668,37 @@ export class AuditVerifierService {
       codec: this._codec,
     });
 
-    const records = await recordService.readRecords(graphName, options.pin ? { tip: options.pin } : {});
+    const recordsResult = await recordService.readRecords(graphName, options.pin ? { tip: options.pin } : {});
+    if (!recordsResult.ok) {
+      return {
+        trustSchemaVersion: 1,
+        mode: 'signed_evidence_v1',
+        trustVerdict: 'fail',
+        trust: {
+          status: 'error',
+          source: options.pin ? 'pinned' : 'ref',
+          sourceDetail: options.pin ?? null,
+          evaluatedWriters: [],
+          untrustedWriters: [],
+          explanations: [
+            {
+              writerId: '*',
+              trusted: false,
+              reasonCode: TRUST_REASON_CODES.TRUST_RECORD_CHAIN_INVALID,
+              reason: `Trust chain read failed: ${recordsResult.error.message}`,
+            },
+          ],
+          evidenceSummary: {
+            recordsScanned: 0,
+            activeKeys: 0,
+            revokedKeys: 0,
+            activeBindings: 0,
+            revokedBindings: 0,
+          },
+        },
+      };
+    }
+    const { records } = recordsResult;
 
     if (records.length === 0) {
       return {
@@ -704,4 +735,3 @@ export class AuditVerifierService {
     return evaluateWriters(writerIds, trustState, policy);
   }
 }
-

package/src/domain/services/BitmapIndexBuilder.js

@@ -22,12 +22,20 @@ const computeChecksum = async (data, crypto) => {
 };
 
 /** @type {boolean|null} Whether native Roaring bindings are available (null = unknown until first use) */
-export let NATIVE_ROARING_AVAILABLE = null;
+let _nativeRoaringAvailable = null;
+
+/**
+ * Resets native Roaring availability detection (test-only utility).
+ * @returns {void}
+ */
+export function resetNativeRoaringFlag() {
+  _nativeRoaringAvailable = null;
+}
 
 const ensureRoaringBitmap32 = () => {
   const RoaringBitmap32 = getRoaringBitmap32();
-  if (NATIVE_ROARING_AVAILABLE === null) {
-    NATIVE_ROARING_AVAILABLE = getNativeRoaringAvailable();
+  if (_nativeRoaringAvailable === null) {
+    _nativeRoaringAvailable = getNativeRoaringAvailable();
   }
   return RoaringBitmap32;
 };
@@ -71,14 +79,11 @@ function serializeFrontierToTree(frontier, tree, codec) {
  * BlobPort + TreePort + RefPort from the persistence layer.
  *
  * **Performance Note**: Uses Roaring Bitmaps for compression. Native bindings
- * provide best performance. Check `NATIVE_ROARING_AVAILABLE` export if
- * performance is critical.
+ * provide best performance. Use `getNativeRoaringAvailable()` from
+ * `src/domain/utils/roaring.js` if runtime capability checks are needed.
  *
  * @example
- * import BitmapIndexBuilder, { NATIVE_ROARING_AVAILABLE } from './BitmapIndexBuilder.js';
- * if (NATIVE_ROARING_AVAILABLE === false) {
- *   console.warn('Consider installing native Roaring bindings for better performance');
- * }
+ * import BitmapIndexBuilder from './BitmapIndexBuilder.js';
  * const builder = new BitmapIndexBuilder();
  */
 export default class BitmapIndexBuilder {

package/src/domain/services/CheckpointService.js

@@ -148,7 +148,9 @@ export async function createV5({
   // 1. Compute appliedVV from actual state dots
   const appliedVV = computeAppliedVV(state);
 
-  // 2. Optionally compact (only tombstoned dots <= appliedVV)
+  // 2. Optionally compact (only tombstoned dots <= appliedVV).
+  // When compact=false, checkpointState aliases the caller's state but the
+  // remaining path is read-only (serialize + hash), so no clone is needed.
   let checkpointState = state;
   if (compact) {
     checkpointState = cloneStateV5(state);
@@ -188,6 +190,11 @@ export async function createV5({
   // 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.
+  //
+  // O(P) scan over all properties — acceptable because checkpoint creation
+  // is infrequent. The property key format is deterministic (encodePropKey /
+  // encodeEdgePropKey), but content keys are interleaved with regular keys
+  // so no prefix filter can skip non-content entries without decoding.
   const contentOids = new Set();
   for (const [propKey, register] of checkpointState.prop) {
     const { propKey: decodedKey } = isEdgePropKey(propKey)
@@ -235,6 +242,8 @@ export async function createV5({
     stateHash,
     frontierOid: frontierBlobOid,
     indexOid: treeOid,
+    // Schema 3 was used for edge-property-aware patches but is never emitted
+    // by checkpoint creation. Schema 4 indicates an index tree is present.
     schema: indexTree ? 4 : 2,
   });
 

package/src/domain/services/GCPolicy.js

@@ -4,6 +4,7 @@
 
 import { orsetCompact } from '../crdt/ORSet.js';
 import { collectGCMetrics } from './GCMetrics.js';
+import WarpError from '../errors/WarpError.js';
 
 /**
  * @typedef {Object} GCPolicy
@@ -92,21 +93,41 @@ export function shouldRunGC(metrics, policy) {
 
 /**
  * Executes GC on state. Only compacts tombstoned dots <= appliedVV.
- * Mutates state in place.
+ * Mutates state **in place** — callers must clone-then-swap to preserve
+ * a rollback copy (see CheckpointService for the canonical pattern).
  *
  * @param {import('./JoinReducer.js').WarpStateV5} state - State to compact (mutated!)
  * @param {import('../crdt/VersionVector.js').VersionVector} appliedVV - Version vector cutoff
  * @returns {GCExecuteResult}
+ * @throws {WarpError} E_GC_INVALID_VV if appliedVV is not a Map
+ * @throws {WarpError} E_GC_COMPACT_FAILED if orsetCompact throws
  */
 export function executeGC(state, appliedVV) {
+  if (!(appliedVV instanceof Map)) {
+    throw new WarpError(
+      'executeGC requires appliedVV to be a Map (VersionVector)',
+      'E_GC_INVALID_VV',
+    );
+  }
+
   const startTime = performance.now();
 
   // Collect metrics before compaction
   const beforeMetrics = collectGCMetrics(state);
 
-  // Compact both ORSets
-  orsetCompact(state.nodeAlive, appliedVV);
-  orsetCompact(state.edgeAlive, appliedVV);
+  // Compact both ORSets — wrap each phase so partial failure is diagnosable
+  let nodesDone = false;
+  try {
+    orsetCompact(state.nodeAlive, appliedVV);
+    nodesDone = true;
+    orsetCompact(state.edgeAlive, appliedVV);
+  } catch {
+    throw new WarpError(
+      `GC compaction failed during ${nodesDone ? 'edgeAlive' : 'nodeAlive'} phase`,
+      'E_GC_COMPACT_FAILED',
+      { context: { phase: nodesDone ? 'edgeAlive' : 'nodeAlive', partialCompaction: nodesDone } },
+    );
+  }
 
   // Collect metrics after compaction
   const afterMetrics = collectGCMetrics(state);

package/src/domain/services/GraphTraversal.js

@@ -165,7 +165,9 @@ export default class GraphTraversal {
       return await this._provider.getNeighbors(nodeId, direction, options);
     }
 
-    const labelsKey = options?.labels ? JSON.stringify([...options.labels].sort()) : '*';
+    const labelsKey = options?.labels
+      ? [...options.labels].sort().join('\0')
+      : '*';
     const key = `${nodeId}\0${direction}\0${labelsKey}`;
     const cached = cache.get(key);
     if (cached !== undefined) {