@git-stunts/git-warp 12.2.1 → 12.4.1

package/src/domain/services/JoinReducer.js

@@ -15,7 +15,8 @@ import { lwwSet, lwwMax } from '../crdt/LWW.js';
 import { createEventId, compareEventIds } from '../utils/EventId.js';
 import { createTickReceipt, OP_TYPES } from '../types/TickReceipt.js';
 import { encodeDot } from '../crdt/Dot.js';
-import { encodeEdgeKey, decodeEdgeKey, encodePropKey } from './KeyCodec.js';
+import { encodeEdgeKey, decodeEdgeKey, encodePropKey, encodeEdgePropKey, EDGE_PROP_PREFIX } from './KeyCodec.js';
+import { normalizeRawOp } from './OpNormalizer.js';
 import { createEmptyDiff, mergeDiffs } from '../types/PatchDiff.js';
 import PatchError from '../errors/PatchError.js';
 
@@ -27,6 +28,9 @@ export {
   encodeEdgePropKey, isEdgePropKey, decodeEdgePropKey,
 } from './KeyCodec.js';
 
+// Re-export op normalization for consumers that operate on raw patches
+export { normalizeRawOp, lowerCanonicalOp } from './OpNormalizer.js';
+
 /**
  * @typedef {Object} WarpStateV5
  * @property {import('../crdt/ORSet.js').ORSet} nodeAlive - ORSet of alive nodes
@@ -40,6 +44,28 @@ export {
  *   always produces an empty Map for them.
  */
 
+/**
+ * @typedef {Object} OpLike
+ * @property {string} type - Operation type discriminator
+ * @property {string} [node] - Node ID (for NodeAdd, NodeRemove, PropSet)
+ * @property {import('../crdt/Dot.js').Dot} [dot] - Dot identifier (for NodeAdd, EdgeAdd)
+ * @property {string[]} [observedDots] - Encoded dots to remove (for NodeRemove, EdgeRemove)
+ * @property {string} [from] - Source node ID (for EdgeAdd, EdgeRemove)
+ * @property {string} [to] - Target node ID (for EdgeAdd, EdgeRemove)
+ * @property {string} [label] - Edge label (for EdgeAdd, EdgeRemove)
+ * @property {string} [key] - Property key (for PropSet)
+ * @property {unknown} [value] - Property value (for PropSet)
+ * @property {string} [oid] - Blob object ID (for BlobValue)
+ */
+
+/**
+ * @typedef {Object} PatchLike
+ * @property {string} writer - Writer ID who created this patch
+ * @property {number} lamport - Lamport timestamp of this patch
+ * @property {OpLike[]} ops - Ordered array of operations
+ * @property {Map<string, number>|Record<string, number>} context - Version vector context
+ */
+
 /**
  * Creates an empty V5 state with all CRDT structures initialized.
  *
@@ -78,33 +104,63 @@ export function createEmptyStateV5() {
  * clone the state first using `cloneStateV5()`.
  *
  * @param {WarpStateV5} state - The state to mutate. Modified in place.
- * @param {Object} op - The operation to apply
- * @param {string} op.type - One of: 'NodeAdd', 'NodeRemove', 'EdgeAdd', 'EdgeRemove', 'PropSet', 'BlobValue'
- * @param {string} [op.node] - Node ID (for NodeAdd, NodeRemove, PropSet)
- * @param {import('../crdt/Dot.js').Dot} [op.dot] - Dot identifier (for NodeAdd, EdgeAdd)
- * @param {string[]} [op.observedDots] - Encoded dots to remove (for NodeRemove, EdgeRemove)
- * @param {string} [op.from] - Source node ID (for EdgeAdd, EdgeRemove)
- * @param {string} [op.to] - Target node ID (for EdgeAdd, EdgeRemove)
- * @param {string} [op.label] - Edge label (for EdgeAdd, EdgeRemove)
- * @param {string} [op.key] - Property key (for PropSet)
- * @param {unknown} [op.value] - Property value (for PropSet)
+ * @param {OpLike} op - The operation to apply
  * @param {import('../utils/EventId.js').EventId} eventId - Event ID for causality tracking
  * @returns {void}
  */
 /**
- * Known V2 operation types. Used for forward-compatibility validation.
+ * Known raw (wire-format) V2 operation types. These are the 6 types that
+ * appear in persisted patches and on the sync wire.
+ * @type {ReadonlySet<string>}
+ */
+export const RAW_KNOWN_OPS = new Set([
+  'NodeAdd', 'NodeRemove', 'EdgeAdd', 'EdgeRemove',
+  'PropSet', 'BlobValue',
+]);
+
+/**
+ * Known canonical (internal) V2 operation types. Includes the 6 raw types
+ * plus the ADR 1 canonical split types `NodePropSet` and `EdgePropSet`.
  * @type {ReadonlySet<string>}
  */
-const KNOWN_OPS = new Set(['NodeAdd', 'NodeRemove', 'EdgeAdd', 'EdgeRemove', 'PropSet', 'BlobValue']);
+export const CANONICAL_KNOWN_OPS = new Set([
+  'NodeAdd', 'NodeRemove', 'EdgeAdd', 'EdgeRemove',
+  'PropSet', 'NodePropSet', 'EdgePropSet', 'BlobValue',
+]);
+
+/**
+ * Validates that an operation has a known raw (wire-format) type.
+ * Use this at sync/wire boundaries to fail-close on unknown or
+ * canonical-only types arriving over the wire.
+ *
+ * @param {{ type: string }} op
+ * @returns {boolean} True if the op type is in RAW_KNOWN_OPS
+ */
+export function isKnownRawOp(op) {
+  return Boolean(op && typeof op.type === 'string' && RAW_KNOWN_OPS.has(op.type));
+}
+
+/**
+ * Validates that an operation has a known canonical (internal) type.
+ * Use this for internal guards after normalization.
+ *
+ * @param {{ type: string }} op
+ * @returns {boolean} True if the op type is in CANONICAL_KNOWN_OPS
+ */
+export function isKnownCanonicalOp(op) {
+  return Boolean(op && typeof op.type === 'string' && CANONICAL_KNOWN_OPS.has(op.type));
+}
 
 /**
  * Validates that an operation has a known type.
  *
+ * @deprecated Use {@link isKnownRawOp} for wire validation or
+ * {@link isKnownCanonicalOp} for internal guards.
  * @param {{ type: string }} op
- * @returns {boolean} True if the op type is in KNOWN_OPS
+ * @returns {boolean} True if the op type is a known raw wire type
  */
 export function isKnownOp(op) {
-  return op && typeof op.type === 'string' && KNOWN_OPS.has(op.type);
+  return isKnownRawOp(op);
 }
 
 /**
@@ -206,6 +262,16 @@ function validateOp(op) {
       requireString(op, 'node');
       requireString(op, 'key');
       break;
+    case 'NodePropSet':
+      requireString(op, 'node');
+      requireString(op, 'key');
+      break;
+    case 'EdgePropSet':
+      requireString(op, 'from');
+      requireString(op, 'to');
+      requireString(op, 'label');
+      requireString(op, 'key');
+      break;
     default:
       // BlobValue and unknown types: no validation (forward-compat)
       break;
@@ -245,8 +311,34 @@ export function applyOpV2(state, op, eventId) {
     case 'EdgeRemove':
       orsetRemove(state.edgeAlive, /** @type {Set<string>} */ (/** @type {unknown} */ (op.observedDots)));
       break;
+    case 'NodePropSet': {
+      const key = encodePropKey(/** @type {string} */ (op.node), /** @type {string} */ (op.key));
+      const current = state.prop.get(key);
+      state.prop.set(key, /** @type {import('../crdt/LWW.js').LWWRegister<unknown>} */ (lwwMax(current, lwwSet(eventId, op.value))));
+      break;
+    }
+    case 'EdgePropSet': {
+      const key = encodeEdgePropKey(
+        /** @type {string} */ (op.from),
+        /** @type {string} */ (op.to),
+        /** @type {string} */ (op.label),
+        /** @type {string} */ (op.key),
+      );
+      const current = state.prop.get(key);
+      state.prop.set(key, /** @type {import('../crdt/LWW.js').LWWRegister<unknown>} */ (lwwMax(current, lwwSet(eventId, op.value))));
+      break;
+    }
     case 'PropSet': {
-      // Uses EventId-based LWW, same as v4
+      // Legacy raw PropSet — must NOT carry edge-property encoding at this point.
+      // If it does, normalization was skipped.
+      if (typeof op.node === 'string' && op.node[0] === EDGE_PROP_PREFIX) {
+        throw new PatchError(
+          'Unnormalized legacy edge-property PropSet reached canonical apply path. ' +
+          'Call normalizeRawOp() at the decode boundary.',
+          { context: { opType: 'PropSet', node: op.node } },
+        );
+      }
+      // Plain node property (backward-compat for callers that bypass normalization)
       const key = encodePropKey(/** @type {string} */ (op.node), /** @type {string} */ (op.key));
       const current = state.prop.get(key);
       state.prop.set(key, /** @type {import('../crdt/LWW.js').LWWRegister<unknown>} */ (lwwMax(current, lwwSet(eventId, op.value))));
@@ -270,7 +362,7 @@ export function applyOpV2(state, op, eventId) {
  * - EdgeRemove -> EdgeTombstone (CRDT tombstone semantics)
  * - All others pass through unchanged
  *
- * @const {Object<string, string>}
+ * @const {Record<string, string>}
  */
 const RECEIPT_OP_TYPE = {
   NodeAdd: 'NodeAdd',
@@ -278,6 +370,8 @@ const RECEIPT_OP_TYPE = {
   EdgeAdd: 'EdgeAdd',
   EdgeRemove: 'EdgeTombstone',
   PropSet: 'PropSet',
+  NodePropSet: 'NodePropSet',
+  EdgePropSet: 'EdgePropSet',
   BlobValue: 'BlobValue',
 };
 
@@ -295,9 +389,7 @@ const VALID_RECEIPT_OPS = new Set(OP_TYPES);
  * this add operation is effective or redundant (idempotent re-delivery).
  *
  * @param {import('../crdt/ORSet.js').ORSet} orset - The node OR-Set containing alive nodes
- * @param {Object} op - The NodeAdd operation
- * @param {string} op.node - The node ID being added
- * @param {import('../crdt/Dot.js').Dot} op.dot - The dot uniquely identifying this add event
+ * @param {{node: string, dot: import('../crdt/Dot.js').Dot}} op - The NodeAdd operation
  * @returns {{target: string, result: 'applied'|'redundant'}} Outcome with node ID as target
  */
 function nodeAddOutcome(orset, op) {
@@ -318,9 +410,7 @@ function nodeAddOutcome(orset, op) {
  * observed at the time the remove was issued.
  *
  * @param {import('../crdt/ORSet.js').ORSet} orset - The node OR-Set containing alive nodes
- * @param {Object} op - The NodeRemove operation
- * @param {string} [op.node] - The node ID being removed (may be absent for dot-only removes)
- * @param {string[]} op.observedDots - Array of encoded dots that were observed when the remove was issued
+ * @param {{node?: string, observedDots: string[] | Set<string>}} op - The NodeRemove operation
  * @returns {{target: string, result: 'applied'|'redundant'}} Outcome with node ID (or '*') as target
  */
 function nodeRemoveOutcome(orset, op) {
@@ -350,11 +440,7 @@ function nodeRemoveOutcome(orset, op) {
  * Unlike nodes, edges are keyed by the composite (from, to, label) tuple.
  *
  * @param {import('../crdt/ORSet.js').ORSet} orset - The edge OR-Set containing alive edges
- * @param {Object} op - The EdgeAdd operation
- * @param {string} op.from - Source node ID
- * @param {string} op.to - Target node ID
- * @param {string} op.label - Edge label
- * @param {import('../crdt/Dot.js').Dot} op.dot - The dot uniquely identifying this add event
+ * @param {{from: string, to: string, label: string, dot: import('../crdt/Dot.js').Dot}} op - The EdgeAdd operation
  * @param {string} edgeKey - Pre-encoded edge key (from\0to\0label format)
  * @returns {{target: string, result: 'applied'|'redundant'}} Outcome with encoded edge key as target
  */
@@ -379,11 +465,7 @@ function edgeAddOutcome(orset, op, edgeKey) {
  * otherwise falls back to '*' for wildcard/unknown targets.
  *
  * @param {import('../crdt/ORSet.js').ORSet} orset - The edge OR-Set containing alive edges
- * @param {Object} op - The EdgeRemove operation
- * @param {string} [op.from] - Source node ID (optional for computing target)
- * @param {string} [op.to] - Target node ID (optional for computing target)
- * @param {string} [op.label] - Edge label (optional for computing target)
- * @param {string[]} op.observedDots - Array of encoded dots that were observed when the remove was issued
+ * @param {{from?: string, to?: string, label?: string, observedDots: string[] | Set<string>}} op - The EdgeRemove operation
  * @returns {{target: string, result: 'applied'|'redundant'}} Outcome with encoded edge key (or '*') as target
  */
 function edgeRemoveOutcome(orset, op) {
@@ -409,7 +491,7 @@ function edgeRemoveOutcome(orset, op) {
 }
 
 /**
- * Determines the receipt outcome for a PropSet operation.
+ * Determines the receipt outcome for a property operation given a pre-computed key.
  *
  * Uses LWW (Last-Write-Wins) semantics to determine whether the incoming property
  * value wins over any existing value. The comparison is based on EventId ordering:
@@ -423,41 +505,55 @@ function edgeRemoveOutcome(orset, op) {
  * - `redundant`: Exact same write (identical EventId)
  *
  * @param {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} propMap - The properties map keyed by encoded prop keys
- * @param {Object} op - The PropSet operation
- * @param {string} op.node - Node ID owning the property
- * @param {string} op.key - Property key/name
- * @param {unknown} op.value - Property value to set
+ * @param {string} key - Pre-encoded property key (node or edge)
  * @param {import('../utils/EventId.js').EventId} eventId - The event ID for this operation, used for LWW comparison
  * @returns {{target: string, result: 'applied'|'superseded'|'redundant', reason?: string}}
  *          Outcome with encoded prop key as target; includes reason when superseded
  */
-function propSetOutcome(propMap, op, eventId) {
-  const key = encodePropKey(op.node, op.key);
+function propOutcomeForKey(propMap, key, eventId) {
   const current = propMap.get(key);
-  const target = key;
 
   if (!current) {
-    // No existing value -- this write wins
-    return { target, result: 'applied' };
+    return { target: key, result: 'applied' };
   }
 
-  // Compare the incoming EventId with the existing register's EventId
   const cmp = compareEventIds(eventId, current.eventId);
   if (cmp > 0) {
-    // Incoming write wins
-    return { target, result: 'applied' };
+    return { target: key, result: 'applied' };
   }
   if (cmp < 0) {
-    // Existing write wins
     const winner = current.eventId;
     return {
-      target,
+      target: key,
       result: 'superseded',
       reason: `LWW: writer ${winner.writerId} at lamport ${winner.lamport} wins`,
     };
   }
-  // Same EventId -- redundant (exact same write)
-  return { target, result: 'redundant' };
+  return { target: key, result: 'redundant' };
+}
+
+/**
+ * Determines the receipt outcome for a PropSet/NodePropSet operation.
+ *
+ * @param {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} propMap
+ * @param {{node: string, key: string}} op - The PropSet or NodePropSet operation
+ * @param {import('../utils/EventId.js').EventId} eventId
+ * @returns {{target: string, result: 'applied'|'superseded'|'redundant', reason?: string}}
+ */
+function propSetOutcome(propMap, op, eventId) {
+  return propOutcomeForKey(propMap, encodePropKey(op.node, op.key), eventId);
+}
+
+/**
+ * Determines the receipt outcome for an EdgePropSet operation.
+ *
+ * @param {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} propMap
+ * @param {{from: string, to: string, label: string, key: string}} op - The EdgePropSet operation
+ * @param {import('../utils/EventId.js').EventId} eventId
+ * @returns {{target: string, result: 'applied'|'superseded'|'redundant', reason?: string}}
+ */
+function edgePropSetOutcome(propMap, op, eventId) {
+  return propOutcomeForKey(propMap, encodeEdgePropKey(op.from, op.to, op.label, op.key), eventId);
 }
 
 /**
@@ -476,10 +572,7 @@ function foldPatchDot(frontier, writer, lamport) {
 /**
  * Merges a patch's context into state and folds the patch dot.
  * @param {WarpStateV5} state
- * @param {Object} patch
- * @param {string} patch.writer
- * @param {number} patch.lamport
- * @param {Map<string, number>|{[x: string]: number}} patch.context
+ * @param {{writer: string, lamport: number, context: Map<string, number>|Record<string, number>}} patch
  */
 function updateFrontierFromPatch(state, patch) {
   const contextVV = patch.context instanceof Map
@@ -493,18 +586,14 @@ function updateFrontierFromPatch(state, patch) {
  * Applies a patch to state without receipt collection (zero overhead).
  *
  * @param {WarpStateV5} state - The state to mutate in place
- * @param {Object} patch - The patch to apply
- * @param {string} patch.writer
- * @param {number} patch.lamport
- * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>} patch.ops
- * @param {Map<string, number>|{[x: string]: number}} patch.context
+ * @param {PatchLike} patch - The patch to apply
  * @param {string} patchSha - Git SHA of the patch commit
  * @returns {WarpStateV5} The mutated state
  */
 export function applyFast(state, patch, patchSha) {
   for (let i = 0; i < patch.ops.length; i++) {
     const eventId = createEventId(patch.lamport, patch.writer, patchSha, i);
-    applyOpV2(state, patch.ops[i], eventId);
+    applyOpV2(state, normalizeRawOp(patch.ops[i]), eventId);
   }
   updateFrontierFromPatch(state, patch);
   return state;
@@ -599,11 +688,17 @@ function snapshotBeforeOp(state, op) {
       const aliveBeforeEdges = aliveElementsForDots(state.edgeAlive, edgeDots);
       return { aliveBeforeEdges };
     }
-    case 'PropSet': {
+    case 'PropSet':
+    case 'NodePropSet': {
       const pk = encodePropKey(op.node, op.key);
       const reg = state.prop.get(pk);
       return { prevPropValue: reg ? reg.value : undefined, propKey: pk };
     }
+    case 'EdgePropSet': {
+      const epk = encodeEdgePropKey(op.from, op.to, op.label, op.key);
+      const ereg = state.prop.get(epk);
+      return { prevPropValue: ereg ? ereg.value : undefined, propKey: epk };
+    }
     default:
       return {};
   }
@@ -640,7 +735,8 @@ function accumulateOpDiff(diff, state, op, before) {
       collectEdgeRemovals(diff, state, before);
       break;
     }
-    case 'PropSet': {
+    case 'PropSet':
+    case 'NodePropSet': {
       const reg = state.prop.get(/** @type {string} */ (before.propKey));
       const newVal = reg ? reg.value : undefined;
       if (newVal !== before.prevPropValue) {
@@ -653,6 +749,19 @@ function accumulateOpDiff(diff, state, op, before) {
       }
       break;
     }
+    case 'EdgePropSet': {
+      const ereg = state.prop.get(/** @type {string} */ (before.propKey));
+      const eNewVal = ereg ? ereg.value : undefined;
+      if (eNewVal !== before.prevPropValue) {
+        diff.propsChanged.push({
+          nodeId: encodeEdgeKey(op.from, op.to, op.label),
+          key: op.key,
+          value: eNewVal,
+          prevValue: before.prevPropValue,
+        });
+      }
+      break;
+    }
     default:
       break;
   }
@@ -698,11 +807,7 @@ function collectEdgeRemovals(diff, state, before) {
  * winner changes. Redundant ops produce no diff entries.
  *
  * @param {WarpStateV5} state - The state to mutate in place
- * @param {Object} patch - The patch to apply
- * @param {string} patch.writer
- * @param {number} patch.lamport
- * @param {Array<Object>} patch.ops
- * @param {Map<string, number>|{[x: string]: number}} patch.context
+ * @param {PatchLike} patch - The patch to apply
  * @param {string} patchSha - Git SHA of the patch commit
  * @returns {{state: WarpStateV5, diff: import('../types/PatchDiff.js').PatchDiff}}
  */
@@ -710,13 +815,12 @@ export function applyWithDiff(state, patch, patchSha) {
   const diff = createEmptyDiff();
 
   for (let i = 0; i < patch.ops.length; i++) {
-    const op = patch.ops[i];
-    validateOp(/** @type {Record<string, unknown>} */ (op));
+    const canonOp = /** @type {import('../types/WarpTypesV2.js').CanonicalOpV2} */ (normalizeRawOp(patch.ops[i]));
+    validateOp(/** @type {Record<string, unknown>} */ (canonOp));
     const eventId = createEventId(patch.lamport, patch.writer, patchSha, i);
-    const typedOp = /** @type {import('../types/WarpTypesV2.js').OpV2} */ (op);
-    const before = snapshotBeforeOp(state, typedOp);
-    applyOpV2(state, typedOp, eventId);
-    accumulateOpDiff(diff, state, typedOp, before);
+    const before = snapshotBeforeOp(state, canonOp);
+    applyOpV2(state, canonOp, eventId);
+    accumulateOpDiff(diff, state, canonOp, before);
   }
 
   updateFrontierFromPatch(state, patch);
@@ -727,11 +831,7 @@ export function applyWithDiff(state, patch, patchSha) {
  * Applies a patch to state with receipt collection for provenance tracking.
  *
  * @param {WarpStateV5} state - The state to mutate in place
- * @param {Object} patch - The patch to apply
- * @param {string} patch.writer
- * @param {number} patch.lamport
- * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>} patch.ops
- * @param {Map<string, number>|{[x: string]: number}} patch.context
+ * @param {PatchLike} patch - The patch to apply
  * @param {string} patchSha - Git SHA of the patch commit
  * @returns {{state: WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}}
  */
@@ -739,41 +839,47 @@ export function applyWithReceipt(state, patch, patchSha) {
   /** @type {import('../types/TickReceipt.js').OpOutcome[]} */
   const opResults = [];
   for (let i = 0; i < patch.ops.length; i++) {
-    const op = patch.ops[i];
-    validateOp(/** @type {Record<string, unknown>} */ (op));
+    const canonOp = /** @type {import('../types/WarpTypesV2.js').OpV2} */ (normalizeRawOp(patch.ops[i]));
+    validateOp(/** @type {Record<string, unknown>} */ (canonOp));
     const eventId = createEventId(patch.lamport, patch.writer, patchSha, i);
 
     // Determine outcome BEFORE applying the op (state is pre-op)
     /** @type {{target: string, result: string, reason?: string}} */
     let outcome;
-    switch (op.type) {
+    switch (canonOp.type) {
       case 'NodeAdd':
-        outcome = nodeAddOutcome(state.nodeAlive, /** @type {{node: string, dot: import('../crdt/Dot.js').Dot}} */ (op));
+        outcome = nodeAddOutcome(state.nodeAlive, /** @type {{node: string, dot: import('../crdt/Dot.js').Dot}} */ (canonOp));
         break;
       case 'NodeRemove':
-        outcome = nodeRemoveOutcome(state.nodeAlive, /** @type {{node?: string, observedDots: string[]}} */ (op));
+        outcome = nodeRemoveOutcome(state.nodeAlive, /** @type {{node?: string, observedDots: string[]}} */ (canonOp));
         break;
       case 'EdgeAdd': {
-        const edgeKey = encodeEdgeKey(/** @type {string} */ (op.from), /** @type {string} */ (op.to), /** @type {string} */ (op.label));
-        outcome = edgeAddOutcome(state.edgeAlive, /** @type {{from: string, to: string, label: string, dot: import('../crdt/Dot.js').Dot}} */ (op), edgeKey);
+        const edgeKey = encodeEdgeKey(canonOp.from, canonOp.to, canonOp.label);
+        outcome = edgeAddOutcome(state.edgeAlive, /** @type {{from: string, to: string, label: string, dot: import('../crdt/Dot.js').Dot}} */ (canonOp), edgeKey);
         break;
       }
       case 'EdgeRemove':
-        outcome = edgeRemoveOutcome(state.edgeAlive, /** @type {{from?: string, to?: string, label?: string, observedDots: string[]}} */ (op));
+        outcome = edgeRemoveOutcome(state.edgeAlive, /** @type {{from?: string, to?: string, label?: string, observedDots: string[]}} */ (canonOp));
         break;
       case 'PropSet':
-        outcome = propSetOutcome(state.prop, /** @type {{node: string, key: string, value: *}} */ (op), eventId);
+      case 'NodePropSet':
+        outcome = propSetOutcome(state.prop, /** @type {{node: string, key: string, value: unknown}} */ (canonOp), eventId);
         break;
-      default:
+      case 'EdgePropSet':
+        outcome = edgePropSetOutcome(state.prop, /** @type {{from: string, to: string, label: string, key: string, value: unknown}} */ (canonOp), eventId);
+        break;
+      default: {
         // Unknown or BlobValue — always applied
-        outcome = { target: op.node || op.oid || '*', result: 'applied' };
+        const anyOp = /** @type {Record<string, string>} */ (canonOp);
+        outcome = { target: anyOp.node || anyOp.oid || '*', result: 'applied' };
         break;
+      }
     }
 
     // Apply the op (mutates state)
-    applyOpV2(state, op, eventId);
+    applyOpV2(state, canonOp, eventId);
 
-    const receiptOp = /** @type {Record<string, string>} */ (RECEIPT_OP_TYPE)[op.type] || op.type;
+    const receiptOp = /** @type {Record<string, string>} */ (RECEIPT_OP_TYPE)[canonOp.type] || canonOp.type;
     // Skip unknown/forward-compatible op types that aren't valid receipt ops
     if (!VALID_RECEIPT_OPS.has(receiptOp)) {
       continue;
@@ -814,11 +920,7 @@ export function applyWithReceipt(state, patch, patchSha) {
  * clone the state first using `cloneStateV5()`.
  *
  * @param {WarpStateV5} state - The state to mutate. Modified in place.
- * @param {Object} patch - The patch to apply
- * @param {string} patch.writer - Writer ID who created this patch
- * @param {number} patch.lamport - Lamport timestamp of this patch
- * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>} patch.ops - Array of operations to apply
- * @param {Map<string, number>|{[x: string]: number}} patch.context - Version vector context (Map or serialized form)
+ * @param {PatchLike} patch - The patch to apply
  * @param {string} patchSha - The Git SHA of the patch commit (used for EventId creation)
  * @param {boolean} [collectReceipts=false] - When true, computes and returns receipt data
  * @returns {WarpStateV5|{state: WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}}
@@ -927,11 +1029,9 @@ function mergeEdgeBirthEvent(a, b) {
  * - When `options.receipts` is true, returns a TickReceipt per patch for
  *   provenance tracking and debugging.
  *
- * @param {Array<{patch: {writer: string, lamport: number, ops: Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>, context: Map<string, number>|{[x: string]: number}}, sha: string}>} patches - Array of patch objects with their Git SHAs
+ * @param {Array<{patch: PatchLike, sha: string}>} patches - Array of patch objects with their Git SHAs
  * @param {WarpStateV5} [initialState] - Optional starting state (for incremental materialization from checkpoint)
- * @param {Object} [options] - Optional configuration
- * @param {boolean} [options.receipts=false] - When true, collect and return TickReceipts
- * @param {boolean} [options.trackDiff=false] - When true, collect and return PatchDiff
+ * @param {{receipts?: boolean, trackDiff?: boolean}} [options] - Optional configuration
  * @returns {WarpStateV5|{state: WarpStateV5, receipts: import('../types/TickReceipt.js').TickReceipt[]}|{state: WarpStateV5, diff: import('../types/PatchDiff.js').PatchDiff}}
  *          Returns state directly when no options;
  *          returns {state, receipts} when receipts is true;

package/src/domain/services/KeyCodec.js

@@ -91,6 +91,54 @@ export function encodeEdgePropKey(from, to, label, propKey) {
   return `${EDGE_PROP_PREFIX}${from}\0${to}\0${label}\0${propKey}`;
 }
 
+// -------------------------------------------------------------------------
+// Legacy edge-property node encoding (raw PropSet ↔ canonical EdgePropSet)
+// -------------------------------------------------------------------------
+
+/**
+ * Encodes edge identity as the legacy `node` field value for raw PropSet ops.
+ *
+ * Format: `\x01from\0to\0label`
+ *
+ * @param {string} from - Source node ID
+ * @param {string} to - Target node ID
+ * @param {string} label - Edge label
+ * @returns {string}
+ */
+export function encodeLegacyEdgePropNode(from, to, label) {
+  return `${EDGE_PROP_PREFIX}${from}\0${to}\0${label}`;
+}
+
+/**
+ * Returns true if a raw PropSet `node` field encodes an edge identity.
+ * @param {string} node - The `node` field from a raw PropSet op
+ * @returns {boolean}
+ */
+export function isLegacyEdgePropNode(node) {
+  return typeof node === 'string' && node.length > 0 && node[0] === EDGE_PROP_PREFIX;
+}
+
+/**
+ * Decodes a legacy edge-property `node` field back to its components.
+ * @param {string} node - The `node` field (must start with \x01)
+ * @returns {{from: string, to: string, label: string}}
+ * @throws {Error} If the node field is not a valid legacy edge-property encoding
+ */
+export function decodeLegacyEdgePropNode(node) {
+  if (!isLegacyEdgePropNode(node)) {
+    throw new Error('Invalid legacy edge-property node: missing \\x01 prefix');
+  }
+  const parts = node.slice(1).split('\0');
+  if (parts.length !== 3) {
+    throw new Error(`Invalid legacy edge-property node: expected 3 segments, got ${parts.length}`);
+  }
+  const [from, to, label] = parts;
+  if (!from || !to || !label) {
+    throw new Error('Invalid legacy edge-property node: empty segment in decoded parts');
+  }
+  return { from, to, label };
+}
+
 /**
  * Returns true if the encoded key is an edge property key.
  * @param {string} key - Encoded property key

package/src/domain/services/LogicalBitmapIndexBuilder.js

@@ -24,8 +24,7 @@ const MAX_LOCAL_ID = 1 << 24;
 
 export default class LogicalBitmapIndexBuilder {
   /**
-   * @param {Object} [options]
-   * @param {import('../../ports/CodecPort.js').default} [options.codec]
+   * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
    */
   constructor({ codec } = {}) {
     this._codec = codec || defaultCodec;

package/src/domain/services/LogicalIndexBuildService.js

@@ -17,9 +17,7 @@ import { nodeVisibleV5, edgeVisibleV5 } from './StateSerializerV5.js';
 
 export default class LogicalIndexBuildService {
   /**
-   * @param {Object} [options]
-   * @param {import('../../ports/CodecPort.js').default} [options.codec]
-   * @param {import('../../ports/LoggerPort.js').default} [options.logger]
+   * @param {{ codec?: import('../../ports/CodecPort.js').default, logger?: import('../../ports/LoggerPort.js').default }} [options]
    */
   constructor({ codec, logger } = {}) {
     this._codec = codec || defaultCodec;
@@ -30,9 +28,7 @@ export default class LogicalIndexBuildService {
    * Builds a complete logical index from materialized state.
    *
    * @param {import('./JoinReducer.js').WarpStateV5} state
-   * @param {Object} [options]
-   * @param {Record<string, { nodeToGlobal: Record<string, number>, nextLocalId: number }>} [options.existingMeta] - Prior meta shards for ID stability
-   * @param {Record<string, number>|Array<[string, number]>} [options.existingLabels] - Prior label registry for append-only stability
+   * @param {{ existingMeta?: Record<string, { nodeToGlobal: Record<string, number>, nextLocalId: number }>, existingLabels?: Record<string, number>|Array<[string, number]> }} [options]
    * @returns {{ tree: Record<string, Uint8Array>, receipt: Record<string, unknown> }}
    */
   build(state, options = {}) {

package/src/domain/services/LogicalIndexReader.js

@@ -89,8 +89,7 @@ function classifyShards(items) {
 
 export default class LogicalIndexReader {
   /**
-   * @param {Object} [options]
-   * @param {import('../../ports/CodecPort.js').default} [options.codec]
+   * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
    */
   constructor({ codec } = {}) {
     this._codec = codec || defaultCodec;