@git-stunts/git-warp 12.1.0 → 12.2.1

package/src/domain/services/JoinReducer.js

@@ -9,7 +9,7 @@
  * }
  */
 
-import { createORSet, orsetAdd, orsetRemove, orsetJoin, orsetContains } from '../crdt/ORSet.js';
+import { createORSet, orsetAdd, orsetRemove, orsetJoin, orsetContains, orsetClone } from '../crdt/ORSet.js';
 import { createVersionVector, vvMerge, vvClone, vvDeserialize } from '../crdt/VersionVector.js';
 import { lwwSet, lwwMax } from '../crdt/LWW.js';
 import { createEventId, compareEventIds } from '../utils/EventId.js';
@@ -17,6 +17,7 @@ import { createTickReceipt, OP_TYPES } from '../types/TickReceipt.js';
 import { encodeDot } from '../crdt/Dot.js';
 import { encodeEdgeKey, decodeEdgeKey, encodePropKey } from './KeyCodec.js';
 import { createEmptyDiff, mergeDiffs } from '../types/PatchDiff.js';
+import PatchError from '../errors/PatchError.js';
 
 // Re-export key codec functions for backward compatibility
 export {
@@ -32,7 +33,11 @@ export {
  * @property {import('../crdt/ORSet.js').ORSet} edgeAlive - ORSet of alive edges
  * @property {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} prop - Properties with LWW
  * @property {import('../crdt/VersionVector.js').VersionVector} observedFrontier - Observed version vector
- * @property {Map<string, import('../utils/EventId.js').EventId>} edgeBirthEvent - EdgeKey → EventId of most recent EdgeAdd (for clean-slate prop visibility)
+ * @property {Map<string, import('../utils/EventId.js').EventId>} edgeBirthEvent - EdgeKey → EventId of most recent EdgeAdd (for clean-slate prop visibility).
+ *   Always present at runtime (initialized to empty Map by createEmptyStateV5 and
+ *   deserializeFullStateV5). Edge birth events were introduced in a later schema
+ *   version; older checkpoints serialize without this field, but the deserializer
+ *   always produces an empty Map for them.
  */
 
 /**
@@ -86,7 +91,136 @@ export function createEmptyStateV5() {
  * @param {import('../utils/EventId.js').EventId} eventId - Event ID for causality tracking
  * @returns {void}
  */
+/**
+ * Known V2 operation types. Used for forward-compatibility validation.
+ * @type {ReadonlySet<string>}
+ */
+const KNOWN_OPS = new Set(['NodeAdd', 'NodeRemove', 'EdgeAdd', 'EdgeRemove', 'PropSet', 'BlobValue']);
+
+/**
+ * Validates that an operation has a known type.
+ *
+ * @param {{ type: string }} op
+ * @returns {boolean} True if the op type is in KNOWN_OPS
+ */
+export function isKnownOp(op) {
+  return op && typeof op.type === 'string' && KNOWN_OPS.has(op.type);
+}
+
+/**
+ * Asserts that `op[field]` is a string. Throws PatchError if not.
+ * @param {Record<string, unknown>} op
+ * @param {string} field
+ */
+function requireString(op, field) {
+  if (typeof op[field] !== 'string') {
+    throw new PatchError(
+      `${op.type} op requires '${field}' to be a string, got ${typeof op[field]}`,
+      { context: { opType: op.type, field, actual: typeof op[field] } },
+    );
+  }
+}
+
+/**
+ * Asserts that `op[field]` is iterable (Array, Set, or any Symbol.iterator).
+ * @param {Record<string, unknown>} op
+ * @param {string} field
+ */
+function requireIterable(op, field) {
+  const val = op[field];
+  if (
+    val === null ||
+    val === undefined ||
+    typeof val !== 'object' ||
+    typeof /** @type {Iterable<unknown>} */ (val)[Symbol.iterator] !== 'function'
+  ) {
+    throw new PatchError(
+      `${op.type} op requires '${field}' to be iterable, got ${typeof val}`,
+      { context: { opType: op.type, field, actual: typeof val } },
+    );
+  }
+}
+
+/**
+ * Asserts that `op.dot` is an object with writerId (string) and counter (number).
+ * @param {Record<string, unknown>} op
+ */
+function requireDot(op) {
+  const { dot } = op;
+  if (!dot || typeof dot !== 'object') {
+    throw new PatchError(
+      `${op.type} op requires 'dot' to be an object, got ${typeof dot}`,
+      { context: { opType: op.type, field: 'dot', actual: typeof dot } },
+    );
+  }
+  const d = /** @type {Record<string, unknown>} */ (dot);
+  if (typeof d.writerId !== 'string') {
+    throw new PatchError(
+      `${op.type} op requires 'dot.writerId' to be a string, got ${typeof d.writerId}`,
+      { context: { opType: op.type, field: 'dot.writerId', actual: typeof d.writerId } },
+    );
+  }
+  if (typeof d.counter !== 'number') {
+    throw new PatchError(
+      `${op.type} op requires 'dot.counter' to be a number, got ${typeof d.counter}`,
+      { context: { opType: op.type, field: 'dot.counter', actual: typeof d.counter } },
+    );
+  }
+}
+
+/**
+ * Validates that an operation has the required fields for its type.
+ * Throws PatchError for malformed ops. Unknown/BlobValue types pass through
+ * for forward compatibility.
+ *
+ * @param {Record<string, unknown>} op
+ */
+function validateOp(op) {
+  if (!op || typeof op.type !== 'string') {
+    throw new PatchError(
+      `Invalid op: expected object with string 'type', got ${op === null || op === undefined ? String(op) : typeof op.type}`,
+      { context: { actual: op === null || op === undefined ? String(op) : typeof op.type } },
+    );
+  }
+
+  switch (op.type) {
+    case 'NodeAdd':
+      requireString(op, 'node');
+      requireDot(op);
+      break;
+    case 'NodeRemove':
+      // node is optional (informational for receipts); observedDots is required for mutation
+      requireIterable(op, 'observedDots');
+      break;
+    case 'EdgeAdd':
+      requireString(op, 'from');
+      requireString(op, 'to');
+      requireString(op, 'label');
+      requireDot(op);
+      break;
+    case 'EdgeRemove':
+      // from/to/label are optional (informational for receipts); observedDots is required for mutation
+      requireIterable(op, 'observedDots');
+      break;
+    case 'PropSet':
+      requireString(op, 'node');
+      requireString(op, 'key');
+      break;
+    default:
+      // BlobValue and unknown types: no validation (forward-compat)
+      break;
+  }
+}
+
+/**
+ * Applies a single V2 operation to the given CRDT state.
+ *
+ * @param {WarpStateV5} state - The mutable CRDT state to update
+ * @param {{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}} op - The operation to apply
+ * @param {import('../utils/EventId.js').EventId} eventId - The event ID for LWW ordering
+ */
 export function applyOpV2(state, op, eventId) {
+  validateOp(/** @type {Record<string, unknown>} */ (op));
   switch (op.type) {
     case 'NodeAdd':
       orsetAdd(state.nodeAlive, /** @type {string} */ (op.node), /** @type {import('../crdt/Dot.js').Dot} */ (op.dot));
@@ -190,21 +324,18 @@ function nodeAddOutcome(orset, op) {
  * @returns {{target: string, result: 'applied'|'redundant'}} Outcome with node ID (or '*') as target
  */
 function nodeRemoveOutcome(orset, op) {
-  // Check if any of the observed dots are currently non-tombstoned
+  // Build a reverse index (dot → elementId) for the observed dots to avoid
+  // O(|observedDots| × |entries|) scanning. Same pattern as buildDotToElement.
+  const targetDots = op.observedDots instanceof Set
+    ? op.observedDots
+    : new Set(op.observedDots);
+  const dotToElement = buildDotToElement(orset, targetDots);
+
   let effective = false;
-  for (const encodedDot of op.observedDots) {
-    if (!orset.tombstones.has(encodedDot)) {
-      // This dot exists and is not yet tombstoned, so the remove is effective
-      // Check if any entry actually has this dot
-      for (const dots of orset.entries.values()) {
-        if (dots.has(encodedDot)) {
-          effective = true;
-          break;
-        }
-      }
-      if (effective) {
-        break;
-      }
+  for (const encodedDot of targetDots) {
+    if (!orset.tombstones.has(encodedDot) && dotToElement.has(encodedDot)) {
+      effective = true;
+      break;
     }
   }
   const target = op.node || '*';
@@ -256,18 +387,18 @@ function edgeAddOutcome(orset, op, edgeKey) {
  * @returns {{target: string, result: 'applied'|'redundant'}} Outcome with encoded edge key (or '*') as target
  */
 function edgeRemoveOutcome(orset, op) {
+  // Build a reverse index (dot → elementId) for the observed dots to avoid
+  // O(|observedDots| × |entries|) scanning. Same pattern as buildDotToElement.
+  const targetDots = op.observedDots instanceof Set
+    ? op.observedDots
+    : new Set(op.observedDots);
+  const dotToElement = buildDotToElement(orset, targetDots);
+
   let effective = false;
-  for (const encodedDot of op.observedDots) {
-    if (!orset.tombstones.has(encodedDot)) {
-      for (const dots of orset.entries.values()) {
-        if (dots.has(encodedDot)) {
-          effective = true;
-          break;
-        }
-      }
-      if (effective) {
-        break;
-      }
+  for (const encodedDot of targetDots) {
+    if (!orset.tombstones.has(encodedDot) && dotToElement.has(encodedDot)) {
+      effective = true;
+      break;
     }
   }
   // Construct target from op fields if available
@@ -580,6 +711,7 @@ export function applyWithDiff(state, patch, patchSha) {
 
   for (let i = 0; i < patch.ops.length; i++) {
     const op = patch.ops[i];
+    validateOp(/** @type {Record<string, unknown>} */ (op));
     const eventId = createEventId(patch.lamport, patch.writer, patchSha, i);
     const typedOp = /** @type {import('../types/WarpTypesV2.js').OpV2} */ (op);
     const before = snapshotBeforeOp(state, typedOp);
@@ -608,6 +740,7 @@ export function applyWithReceipt(state, patch, patchSha) {
   const opResults = [];
   for (let i = 0; i < patch.ops.length; i++) {
     const op = patch.ops[i];
+    validateOp(/** @type {Record<string, unknown>} */ (op));
     const eventId = createEventId(patch.lamport, patch.writer, patchSha, i);
 
     // Determine outcome BEFORE applying the op (state is pre-op)
@@ -845,16 +978,16 @@ export function reduceV5(patches, initialState, options) {
  * - Creating a branch point for speculative execution
  * - Ensuring immutability when passing state across API boundaries
  *
- * **Implementation Note**: OR-Sets are cloned by joining with an empty set,
- * which creates new data structures with identical contents.
+ * **Implementation Note**: OR-Sets are cloned via `orsetClone()` which
+ * directly copies entries and tombstones without merge logic overhead.
  *
  * @param {WarpStateV5} state - The state to clone
  * @returns {WarpStateV5} A new state with identical contents but independent data structures
  */
 export function cloneStateV5(state) {
   return {
-    nodeAlive: orsetJoin(state.nodeAlive, createORSet()),
-    edgeAlive: orsetJoin(state.edgeAlive, createORSet()),
+    nodeAlive: orsetClone(state.nodeAlive),
+    edgeAlive: orsetClone(state.edgeAlive),
     prop: new Map(state.prop),
     observedFrontier: vvClone(state.observedFrontier),
     edgeBirthEvent: new Map(state.edgeBirthEvent || []),

package/src/domain/services/MaterializedViewService.js

@@ -21,6 +21,9 @@ import IncrementalIndexUpdater from './IncrementalIndexUpdater.js';
 import { orsetElements, orsetContains } from '../crdt/ORSet.js';
 import { decodeEdgeKey } from './KeyCodec.js';
 
+/** Prefix for property shard paths in the index tree. */
+const PROPS_PREFIX = 'props_';
+
 /**
  * @typedef {import('./BitmapNeighborProvider.js').LogicalIndex} LogicalIndex
  */
@@ -66,7 +69,7 @@ function buildInMemoryPropertyReader(tree, codec) {
   /** @type {Record<string, string>} */
   const propShardOids = {};
   for (const path of Object.keys(tree)) {
-    if (path.startsWith('props_')) {
+    if (path.startsWith(PROPS_PREFIX)) {
       propShardOids[path] = path;
     }
   }
@@ -93,7 +96,7 @@ function partitionShardOids(shardOids) {
   const propOids = {};
 
   for (const [path, oid] of Object.entries(shardOids)) {
-    if (path.startsWith('props_')) {
+    if (path.startsWith(PROPS_PREFIX)) {
       propOids[path] = oid;
     } else {
       indexOids[path] = oid;
@@ -105,6 +108,10 @@ function partitionShardOids(shardOids) {
 /**
  * Mulberry32 PRNG — deterministic 32-bit generator from a seed.
  *
+ * mulberry32 is a fast 32-bit PRNG by Tommy Ettinger. The magic constants
+ * (0x6D2B79F5, shifts 15/13/16) are part of the published algorithm.
+ * See: https://gist.github.com/tommyettinger/46a874533244883189143505d203312c
+ *
  * @param {number} seed
  * @returns {() => number} Returns values in [0, 1)
  */
@@ -134,6 +141,10 @@ function sampleNodes(allNodes, sampleRate, seed) {
   }
   const rng = mulberry32(seed);
   const sampled = allNodes.filter(() => rng() < sampleRate);
+  // When the initial sample is empty (e.g., graph has fewer nodes than
+  // sample size), we fall back to using all available nodes. This changes
+  // the distribution but is acceptable since the sample is only used for
+  // layout heuristics.
   if (sampled.length === 0) {
     sampled.push(allNodes[Math.floor(rng() * allNodes.length)]);
   }