@git-stunts/git-warp 12.2.1 → 12.4.1

package/src/domain/services/LogicalTraversal.js

@@ -83,10 +83,7 @@ export default class LogicalTraversal {
    * multiple starts or no start at all (topologicalSort, commonAncestors).
    *
    * @private
-   * @param {Object} opts - The traversal options
-   * @param {'out'|'in'|'both'} [opts.dir] - Edge direction to follow
-   * @param {string|string[]} [opts.labelFilter] - Edge label(s) to include
-   * @param {number} [opts.maxDepth] - Maximum depth to traverse
+   * @param {{ dir?: 'out'|'in'|'both', labelFilter?: string|string[], maxDepth?: number }} opts - The traversal options
    * @returns {Promise<{engine: GraphTraversal, direction: 'out'|'in'|'both', options: {labels?: Set<string>}|undefined, depthLimit: number}>}
    * @throws {TraversalError} If the direction is invalid (INVALID_DIRECTION)
    * @throws {TraversalError} If the labelFilter is invalid (INVALID_LABEL_FILTER)
@@ -120,10 +117,7 @@ export default class LogicalTraversal {
    *
    * @private
    * @param {string} start - The starting node ID for traversal
-   * @param {Object} opts - The traversal options
-   * @param {'out'|'in'|'both'} [opts.dir] - Edge direction to follow
-   * @param {string|string[]} [opts.labelFilter] - Edge label(s) to include
-   * @param {number} [opts.maxDepth] - Maximum depth to traverse
+   * @param {{ dir?: 'out'|'in'|'both', labelFilter?: string|string[], maxDepth?: number }} opts - The traversal options
    * @returns {Promise<{engine: GraphTraversal, direction: 'out'|'in'|'both', options: {labels?: Set<string>}|undefined, depthLimit: number}>}
    * @throws {TraversalError} If the start node is not found (NODE_NOT_FOUND)
    * @throws {TraversalError} If the direction is invalid (INVALID_DIRECTION)
@@ -146,10 +140,7 @@ export default class LogicalTraversal {
    * Breadth-first traversal.
    *
    * @param {string} start - Starting node ID
-   * @param {Object} [options] - Traversal options
-   * @param {number} [options.maxDepth] - Maximum depth to traverse
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @param {{ maxDepth?: number, dir?: 'out'|'in'|'both', labelFilter?: string|string[] }} [options] - Traversal options
    * @returns {Promise<string[]>} Node IDs in visit order
    * @throws {TraversalError} If the start node is not found or direction is invalid
    */
@@ -169,10 +160,7 @@ export default class LogicalTraversal {
    * Depth-first traversal (pre-order).
    *
    * @param {string} start - Starting node ID
-   * @param {Object} [options] - Traversal options
-   * @param {number} [options.maxDepth] - Maximum depth to traverse
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @param {{ maxDepth?: number, dir?: 'out'|'in'|'both', labelFilter?: string|string[] }} [options] - Traversal options
    * @returns {Promise<string[]>} Node IDs in visit order
    * @throws {TraversalError} If the start node is not found or direction is invalid
    */
@@ -193,10 +181,7 @@ export default class LogicalTraversal {
    *
    * @param {string} from - Source node ID
    * @param {string} to - Target node ID
-   * @param {Object} [options] - Traversal options
-   * @param {number} [options.maxDepth] - Maximum search depth
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @param {{ maxDepth?: number, dir?: 'out'|'in'|'both', labelFilter?: string|string[] }} [options] - Traversal options
    * @returns {Promise<{found: boolean, path: string[], length: number}>}
    *   When `found` is true, `path` contains the node IDs from `from` to `to` and
    *   `length` is the hop count. When `found` is false, `path` is empty and `length` is -1.
@@ -219,9 +204,7 @@ export default class LogicalTraversal {
    * Connected component (undirected by default).
    *
    * @param {string} start - Starting node ID
-   * @param {Object} [options] - Traversal options
-   * @param {number} [options.maxDepth] - Maximum depth to traverse (default: 1000)
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @param {{ maxDepth?: number, labelFilter?: string|string[] }} [options] - Traversal options
    * @returns {Promise<string[]>} Node IDs in visit order
    * @throws {TraversalError} If the start node is not found
    */
@@ -236,11 +219,7 @@ export default class LogicalTraversal {
    *
    * @param {string} from - Source node ID
    * @param {string} to - Target node ID
-   * @param {Object} [options] - Traversal options
-   * @param {number} [options.maxDepth] - Maximum search depth
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
-   * @param {AbortSignal} [options.signal] - Abort signal
+   * @param {{ maxDepth?: number, dir?: 'out'|'in'|'both', labelFilter?: string|string[], signal?: AbortSignal }} [options] - Traversal options
    * @returns {Promise<{reachable: boolean}>}
    */
   async isReachable(from, to, options = {}) {
@@ -262,12 +241,7 @@ export default class LogicalTraversal {
    *
    * @param {string} from - Source node ID
    * @param {string} to - Target node ID
-   * @param {Object} [options] - Traversal options
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
-   * @param {(from: string, to: string, label: string) => number | Promise<number>} [options.weightFn] - Edge weight function
-   * @param {(nodeId: string) => number | Promise<number>} [options.nodeWeightFn] - Node weight function (mutually exclusive with weightFn)
-   * @param {AbortSignal} [options.signal] - Abort signal
+   * @param {{ dir?: 'out'|'in'|'both', labelFilter?: string|string[], weightFn?: (from: string, to: string, label: string) => number | Promise<number>, nodeWeightFn?: (nodeId: string) => number | Promise<number>, signal?: AbortSignal }} [options] - Traversal options
    * @returns {Promise<{path: string[], totalCost: number}>}
    * @throws {TraversalError} code 'NO_PATH' if unreachable
    * @throws {TraversalError} code 'E_WEIGHT_FN_CONFLICT' if both weightFn and nodeWeightFn provided
@@ -292,13 +266,7 @@ export default class LogicalTraversal {
    *
    * @param {string} from - Source node ID
    * @param {string} to - Target node ID
-   * @param {Object} [options] - Traversal options
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
-   * @param {(from: string, to: string, label: string) => number | Promise<number>} [options.weightFn] - Edge weight function
-   * @param {(nodeId: string) => number | Promise<number>} [options.nodeWeightFn] - Node weight function (mutually exclusive with weightFn)
-   * @param {(nodeId: string, goalId: string) => number} [options.heuristicFn] - Heuristic function
-   * @param {AbortSignal} [options.signal] - Abort signal
+   * @param {{ dir?: 'out'|'in'|'both', labelFilter?: string|string[], weightFn?: (from: string, to: string, label: string) => number | Promise<number>, nodeWeightFn?: (nodeId: string) => number | Promise<number>, heuristicFn?: (nodeId: string, goalId: string) => number, signal?: AbortSignal }} [options] - Traversal options
    * @returns {Promise<{path: string[], totalCost: number, nodesExplored: number}>}
    * @throws {TraversalError} code 'NO_PATH' if unreachable
    * @throws {TraversalError} code 'E_WEIGHT_FN_CONFLICT' if both weightFn and nodeWeightFn provided
@@ -326,13 +294,7 @@ export default class LogicalTraversal {
    *
    * @param {string} from - Source node ID
    * @param {string} to - Target node ID
-   * @param {Object} [options] - Traversal options
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
-   * @param {(from: string, to: string, label: string) => number | Promise<number>} [options.weightFn] - Edge weight function
-   * @param {(nodeId: string) => number | Promise<number>} [options.nodeWeightFn] - Node weight function (mutually exclusive with weightFn)
-   * @param {(nodeId: string, goalId: string) => number} [options.forwardHeuristic] - Forward heuristic
-   * @param {(nodeId: string, goalId: string) => number} [options.backwardHeuristic] - Backward heuristic
-   * @param {AbortSignal} [options.signal] - Abort signal
+   * @param {{ labelFilter?: string|string[], weightFn?: (from: string, to: string, label: string) => number | Promise<number>, nodeWeightFn?: (nodeId: string) => number | Promise<number>, forwardHeuristic?: (nodeId: string, goalId: string) => number, backwardHeuristic?: (nodeId: string, goalId: string) => number, signal?: AbortSignal }} [options] - Traversal options
    * @returns {Promise<{path: string[], totalCost: number, nodesExplored: number}>}
    * @throws {TraversalError} code 'NO_PATH' if unreachable
    * @throws {TraversalError} code 'E_WEIGHT_FN_CONFLICT' if both weightFn and nodeWeightFn provided
@@ -365,11 +327,7 @@ export default class LogicalTraversal {
    * Topological sort (Kahn's algorithm).
    *
    * @param {string|string[]} start - One or more start nodes
-   * @param {Object} [options] - Traversal options
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
-   * @param {boolean} [options.throwOnCycle] - Whether to throw on cycle detection
-   * @param {AbortSignal} [options.signal] - Abort signal
+   * @param {{ dir?: 'out'|'in'|'both', labelFilter?: string|string[], throwOnCycle?: boolean, signal?: AbortSignal }} [options] - Traversal options
    * @returns {Promise<{sorted: string[], hasCycle: boolean}>}
    * @throws {TraversalError} code 'ERR_GRAPH_HAS_CYCLES' if throwOnCycle and cycle found
    * @throws {TraversalError} code 'NODE_NOT_FOUND' if a start node does not exist
@@ -405,11 +363,7 @@ export default class LogicalTraversal {
    * Direction is fixed to 'in' (backward BFS).
    *
    * @param {string[]} nodes - Nodes to find common ancestors of
-   * @param {Object} [options] - Traversal options
-   * @param {number} [options.maxDepth] - Maximum search depth
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
-   * @param {number} [options.maxResults] - Maximum number of results
-   * @param {AbortSignal} [options.signal] - Abort signal
+   * @param {{ maxDepth?: number, labelFilter?: string|string[], maxResults?: number, signal?: AbortSignal }} [options] - Traversal options
    * @returns {Promise<{ancestors: string[]}>}
    * @throws {TraversalError} code 'NODE_NOT_FOUND' if a node does not exist
    */
@@ -443,12 +397,7 @@ export default class LogicalTraversal {
    *
    * @param {string} from - Source node ID
    * @param {string} to - Target node ID
-   * @param {Object} [options] - Traversal options
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
-   * @param {(from: string, to: string, label: string) => number | Promise<number>} [options.weightFn] - Edge weight function
-   * @param {(nodeId: string) => number | Promise<number>} [options.nodeWeightFn] - Node weight function (mutually exclusive with weightFn)
-   * @param {AbortSignal} [options.signal] - Abort signal
+   * @param {{ dir?: 'out'|'in'|'both', labelFilter?: string|string[], weightFn?: (from: string, to: string, label: string) => number | Promise<number>, nodeWeightFn?: (nodeId: string) => number | Promise<number>, signal?: AbortSignal }} [options] - Traversal options
    * @returns {Promise<{path: string[], totalCost: number}>}
    * @throws {TraversalError} code 'ERR_GRAPH_HAS_CYCLES' if graph has cycles
    * @throws {TraversalError} code 'NO_PATH' if unreachable

package/src/domain/services/MaterializedViewService.js

@@ -207,11 +207,7 @@ function canonicalizeNeighborSignatures(edges) {
 /**
  * Compares bitmap index neighbors against ground-truth adjacency for one node.
  *
- * @param {Object} params
- * @param {string} params.nodeId
- * @param {string} params.direction
- * @param {LogicalIndex} params.logicalIndex
- * @param {Map<string, Array<{neighborId: string, label: string}>>} params.truthMap
+ * @param {{ nodeId: string, direction: string, logicalIndex: LogicalIndex, truthMap: Map<string, Array<{neighborId: string, label: string}>> }} params
  * @returns {VerifyError|null}
  */
 function compareNodeDirection({ nodeId, direction, logicalIndex, truthMap }) {
@@ -232,9 +228,7 @@ function compareNodeDirection({ nodeId, direction, logicalIndex, truthMap }) {
 
 export default class MaterializedViewService {
   /**
-   * @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;
@@ -308,10 +302,7 @@ export default class MaterializedViewService {
   /**
    * Applies a PatchDiff incrementally to an existing index tree.
    *
-   * @param {Object} params
-   * @param {Record<string, Uint8Array>} params.existingTree
-   * @param {import('../types/PatchDiff.js').PatchDiff} params.diff
-   * @param {import('./JoinReducer.js').WarpStateV5} params.state
+   * @param {{ existingTree: Record<string, Uint8Array>, diff: import('../types/PatchDiff.js').PatchDiff, state: import('./JoinReducer.js').WarpStateV5 }} params
    * @returns {BuildResult}
    */
   applyDiff({ existingTree, diff, state }) {
@@ -345,16 +336,11 @@ export default class MaterializedViewService {
    * Verifies index integrity by sampling alive nodes and comparing
    * bitmap neighbor queries against adjacency-based ground truth.
    *
-   * @param {Object} params
-   * @param {import('./JoinReducer.js').WarpStateV5} params.state
-   * @param {LogicalIndex} params.logicalIndex
-   * @param {Object} [params.options]
-   * @param {number} [params.options.seed] - PRNG seed for reproducible sampling
-   * @param {number} [params.options.sampleRate] - Fraction of nodes to check (>0 and <=1, default 0.1)
+   * @param {{ state: import('./JoinReducer.js').WarpStateV5, logicalIndex: LogicalIndex, options?: { seed?: number, sampleRate?: number } }} params
    * @returns {VerifyResult}
    */
   verifyIndex({ state, logicalIndex, options = {} }) {
-    const seed = options.seed ?? (Date.now() & 0x7FFFFFFF);
+    const seed = options.seed ?? (Math.random() * 0x7FFFFFFF >>> 0);
     const sampleRate = options.sampleRate ?? 0.1;
     const allNodes = [...orsetElements(state.nodeAlive)].sort();
     const sampled = sampleNodes(allNodes, sampleRate, seed);

package/src/domain/services/MessageSchemaDetector.js

@@ -20,17 +20,33 @@ import { getCodec, TRAILER_KEYS } from './MessageCodecInternal.js';
 // -----------------------------------------------------------------------------
 
 /**
- * Schema version for classic node-only patches (V5 format).
+ * Patch schema version for classic node-only patches (V5 format).
  * @type {number}
  */
 export const SCHEMA_V2 = 2;
 
 /**
- * Schema version for patches that may contain edge property PropSet ops.
+ * Patch schema version for patches that may contain edge property PropSet ops.
  * @type {number}
  */
 export const SCHEMA_V3 = 3;
 
+/**
+ * Alias: patch schema v2 (classic node-only patches).
+ * Use this when you need to be explicit that you mean *patch* schema,
+ * not checkpoint schema.
+ * @type {number}
+ */
+export const PATCH_SCHEMA_V2 = SCHEMA_V2;
+
+/**
+ * Alias: patch schema v3 (edge-property-aware patches).
+ * Use this when you need to be explicit that you mean *patch* schema,
+ * not checkpoint schema.
+ * @type {number}
+ */
+export const PATCH_SCHEMA_V3 = SCHEMA_V3;
+
 // -----------------------------------------------------------------------------
 // Schema Version Detection
 // -----------------------------------------------------------------------------
@@ -50,6 +66,14 @@ export function detectSchemaVersion(ops) {
     return SCHEMA_V2;
   }
   for (const op of ops) {
+    if (!op || typeof op !== 'object') {
+      continue;
+    }
+    // Canonical EdgePropSet always implies schema 3
+    if (op.type === 'EdgePropSet') {
+      return SCHEMA_V3;
+    }
+    // Legacy raw PropSet with edge-property encoding
     if (op.type === 'PropSet' && typeof op.node === 'string' && op.node.startsWith(EDGE_PROP_PREFIX)) {
       return SCHEMA_V3;
     }
@@ -90,10 +114,16 @@ export function assertOpsCompatible(ops, maxSchema) {
     return;
   }
   for (const op of ops) {
+    if (!op || typeof op !== 'object') {
+      continue;
+    }
     if (
-      op.type === 'PropSet' &&
-      typeof op.node === 'string' &&
-      op.node.startsWith(EDGE_PROP_PREFIX)
+      // Canonical EdgePropSet (ADR 1) — should never appear on wire pre-ADR 2,
+      // but reject defensively for v2 readers
+      op.type === 'EdgePropSet' ||
+      (op.type === 'PropSet' &&
+        typeof op.node === 'string' &&
+        op.node.startsWith(EDGE_PROP_PREFIX))
     ) {
       throw new SchemaUnsupportedError(
         'Upgrade to >=7.3.0 (WEIGHTED) to sync edge properties.',

package/src/domain/services/MigrationService.js

@@ -13,10 +13,7 @@ import { createVersionVector, vvIncrement } from '../crdt/VersionVector.js';
  * writer, rebuilds the ORSet structures, and copies only properties belonging
  * to visible nodes (dropping dangling props from deleted nodes).
  *
- * @param {Object} v4State - The V4 materialized state (visible projection)
- * @param {Map<string, {value: boolean}>} v4State.nodeAlive - V4 node alive map
- * @param {Map<string, {value: boolean}>} v4State.edgeAlive - V4 edge alive map
- * @param {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} v4State.prop - V4 property map
+ * @param {{ nodeAlive: Map<string, {value: boolean}>, edgeAlive: Map<string, {value: boolean}>, prop: Map<string, import('../crdt/LWW.js').LWWRegister<unknown>> }} v4State - The V4 materialized state (visible projection)
  * @param {string} migrationWriterId - Writer ID to use for synthetic dots
  * @returns {import('./JoinReducer.js').WarpStateV5} The migrated V5 state
  */

package/src/domain/services/ObserverView.js

@@ -156,13 +156,7 @@ export default class ObserverView {
   /**
    * Creates a new ObserverView.
    *
-   * @param {Object} options
-   * @param {string} options.name - Observer name
-   * @param {Object} options.config - Observer configuration
-   * @param {string|string[]} options.config.match - Glob pattern(s) for visible nodes
-   * @param {string[]} [options.config.expose] - Property keys to include
-   * @param {string[]} [options.config.redact] - Property keys to exclude (takes precedence over expose)
-   * @param {import('../WarpGraph.js').default} options.graph - The source WarpGraph instance
+   * @param {{ name: string, config: { match: string|string[], expose?: string[], redact?: string[] }, graph: import('../WarpGraph.js').default }} options
    */
   constructor({ name, config, graph }) {
     /** @type {string} */

package/src/domain/services/OpNormalizer.js

@@ -0,0 +1,79 @@
+/**
+ * OpNormalizer — raw ↔ canonical operation conversion.
+ *
+ * ADR 1 (Canonicalize Edge Property Operations Internally) requires that
+ * reducers, provenance, receipts, and queries operate on canonical ops:
+ *
+ *   Raw (persisted):      NodeAdd, NodeRemove, EdgeAdd, EdgeRemove, PropSet, BlobValue
+ *   Canonical (internal): NodeAdd, NodeRemove, EdgeAdd, EdgeRemove, NodePropSet, EdgePropSet, BlobValue
+ *
+ * **Current normalization location:** Normalization is performed at the
+ * reducer entry points (`applyFast`, `applyWithReceipt`, `applyWithDiff`
+ * in JoinReducer.js), not at the CBOR decode boundary as originally
+ * planned in ADR 1. This is a pragmatic deviation — the reducer calls
+ * `normalizeRawOp()` on each op before dispatch. Lowering happens in
+ * `PatchBuilderV2.build()`/`commit()` via `lowerCanonicalOp()`.
+ *
+ * @module domain/services/OpNormalizer
+ */
+
+import { createNodePropSetV2, createEdgePropSetV2, createPropSetV2 } from '../types/WarpTypesV2.js';
+import { isLegacyEdgePropNode, decodeLegacyEdgePropNode, encodeLegacyEdgePropNode } from './KeyCodec.js';
+
+/**
+ * Normalizes a single raw (persisted) op into its canonical form.
+ *
+ * - Raw `PropSet` with \x01-prefixed node → canonical `EdgePropSet`
+ * - Raw `PropSet` without prefix → canonical `NodePropSet`
+ * - All other op types pass through unchanged.
+ *
+ * @param {import('../types/WarpTypesV2.js').RawOpV2 | {type: string}} rawOp
+ * @returns {import('../types/WarpTypesV2.js').CanonicalOpV2 | {type: string}}
+ */
+export function normalizeRawOp(rawOp) {
+  if (!rawOp || typeof rawOp !== 'object' || typeof rawOp.type !== 'string') {
+    return rawOp;
+  }
+  if (rawOp.type !== 'PropSet') {
+    return rawOp;
+  }
+  const op = /** @type {import('../types/WarpTypesV2.js').OpV2PropSet} */ (rawOp);
+  if (isLegacyEdgePropNode(op.node)) {
+    const { from, to, label } = decodeLegacyEdgePropNode(op.node);
+    return createEdgePropSetV2(from, to, label, op.key, op.value);
+  }
+  return createNodePropSetV2(op.node, op.key, op.value);
+}
+
+/**
+ * Lowers a single canonical op back to raw (persisted) form.
+ *
+ * - Canonical `NodePropSet` → raw `PropSet`
+ * - Canonical `EdgePropSet` → raw `PropSet` with legacy \x01-prefixed node
+ * - All other op types pass through unchanged.
+ *
+ * In M13, this always produces legacy raw PropSet for property ops.
+ * A future graph capability cutover (ADR 2) may allow emitting raw
+ * `EdgePropSet` directly.
+ *
+ * @param {import('../types/WarpTypesV2.js').CanonicalOpV2 | {type: string}} canonicalOp
+ * @returns {import('../types/WarpTypesV2.js').RawOpV2 | {type: string}}
+ */
+export function lowerCanonicalOp(canonicalOp) {
+  switch (canonicalOp.type) {
+    case 'NodePropSet': {
+      const op = /** @type {import('../types/WarpTypesV2.js').OpV2NodePropSet} */ (canonicalOp);
+      return createPropSetV2(op.node, op.key, op.value);
+    }
+    case 'EdgePropSet': {
+      const op = /** @type {import('../types/WarpTypesV2.js').OpV2EdgePropSet} */ (canonicalOp);
+      return createPropSetV2(
+        encodeLegacyEdgePropNode(op.from, op.to, op.label),
+        op.key,
+        op.value,
+      );
+    }
+    default:
+      return canonicalOp;
+  }
+}

package/src/domain/services/PatchBuilderV2.js

@@ -20,10 +20,12 @@ import {
   createNodeRemoveV2,
   createEdgeAddV2,
   createEdgeRemoveV2,
-  createPropSetV2,
+  createNodePropSetV2,
+  createEdgePropSetV2,
   createPatchV2,
 } from '../types/WarpTypesV2.js';
-import { encodeEdgeKey, EDGE_PROP_PREFIX, CONTENT_PROPERTY_KEY } from './KeyCodec.js';
+import { encodeEdgeKey, FIELD_SEPARATOR, EDGE_PROP_PREFIX, CONTENT_PROPERTY_KEY } from './KeyCodec.js';
+import { lowerCanonicalOp } from './OpNormalizer.js';
 import { encodePatchMessage, decodePatchMessage, detectMessageKind } from './WarpMessageCodec.js';
 import { buildWriterRef } from '../utils/RefLayout.js';
 import WriterError from '../errors/WriterError.js';
@@ -66,6 +68,30 @@ function findAttachedData(state, nodeId) {
   return { edges, props, hasData: edges.length > 0 || props.length > 0 };
 }
 
+/**
+ * Validates that an identifier does not contain reserved bytes that would
+ * make the legacy edge-property encoding ambiguous.
+ *
+ * Rejects:
+ * - Identifiers containing \0 (field separator)
+ * - Identifiers starting with \x01 (edge property prefix)
+ *
+ * @param {string} value - Identifier to validate
+ * @param {string} label - Human-readable label for error messages
+ * @throws {Error} If the identifier contains reserved bytes
+ */
+function _assertNoReservedBytes(value, label) {
+  if (typeof value !== 'string') {
+    throw new Error(`${label} must be a string, got ${typeof value}`);
+  }
+  if (value.includes(FIELD_SEPARATOR)) {
+    throw new Error(`${label} must not contain null bytes (\\0): ${JSON.stringify(value)}`);
+  }
+  if (value.length > 0 && value[0] === EDGE_PROP_PREFIX) {
+    throw new Error(`${label} must not start with reserved prefix \\x01: ${JSON.stringify(value)}`);
+  }
+}
+
 /**
  * Fluent builder for creating WARP v5 patches with dots and observed-remove semantics.
  */
@@ -73,19 +99,7 @@ export class PatchBuilderV2 {
   /**
    * Creates a new PatchBuilderV2.
    *
-   * @param {Object} options
-   * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Git adapter
-   *   (uses CommitPort + RefPort + BlobPort + TreePort methods)
-   * @param {string} options.graphName - Graph namespace
-   * @param {string} options.writerId - This writer's ID
-   * @param {number} options.lamport - Lamport timestamp for this patch
-   * @param {import('../crdt/VersionVector.js').VersionVector} options.versionVector - Current version vector
-   * @param {Function} options.getCurrentState - Function that returns the current materialized state
-   * @param {string|null} [options.expectedParentSha] - Expected parent SHA for race detection
-   * @param {Function|null} [options.onCommitSuccess] - Callback invoked after successful commit
-   * @param {'reject'|'cascade'|'warn'} [options.onDeleteWithData='warn'] - Policy when deleting a node with attached data
-   * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
-   * @param {{ warn: Function }} [options.logger] - Logger for non-fatal warnings
+   * @param {{ persistence: import('../../ports/GraphPersistencePort.js').default, graphName: string, writerId: string, lamport: number, versionVector: import('../crdt/VersionVector.js').VersionVector, getCurrentState: () => import('../services/JoinReducer.js').WarpStateV5 | null, expectedParentSha?: string|null, onCommitSuccess?: ((result: {patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}) => void | Promise<void>)|null, onDeleteWithData?: 'reject'|'cascade'|'warn', codec?: import('../../ports/CodecPort.js').default, logger?: import('../../ports/LoggerPort.js').default }} options
    */
   constructor({ persistence, graphName, writerId, lamport, versionVector, getCurrentState, expectedParentSha = null, onCommitSuccess = null, onDeleteWithData = 'warn', codec, logger }) {
     /** @type {import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default} */
@@ -103,8 +117,8 @@ export class PatchBuilderV2 {
     /** @type {import('../crdt/VersionVector.js').VersionVector} */
     this._vv = vvClone(versionVector); // Clone to track local increments
 
-    /** @type {Function} */
-    this._getCurrentState = getCurrentState; // Function to get current materialized state
+    /** @type {() => import('../services/JoinReducer.js').WarpStateV5 | null} */
+    this._getCurrentState = getCurrentState;
 
     /**
      * Snapshot of state captured at construction time (C4).
@@ -133,7 +147,7 @@ export class PatchBuilderV2 {
     /** @type {import('../../ports/CodecPort.js').default} */
     this._codec = codec || defaultCodec;
 
-    /** @type {{ warn: Function }} */
+    /** @type {import('../../ports/LoggerPort.js').default} */
     this._logger = logger || nullLogger;
 
     /**
@@ -233,6 +247,7 @@ export class PatchBuilderV2 {
    */
   addNode(nodeId) {
     this._assertNotCommitted();
+    _assertNoReservedBytes(nodeId, 'nodeId');
     const dot = vvIncrement(this._vv, this._writerId);
     this._ops.push(createNodeAddV2(nodeId, dot));
     // Provenance: NodeAdd writes the node
@@ -305,8 +320,7 @@ export class PatchBuilderV2 {
         }
 
         if (this._onDeleteWithData === 'warn') {
-          // eslint-disable-next-line no-console
-          console.warn(
+          this._logger.warn(
             `[warp] Deleting node '${nodeId}' which has attached data (${summary}). ` +
             `Orphaned data will remain in state.`
           );
@@ -349,6 +363,9 @@ export class PatchBuilderV2 {
    */
   addEdge(from, to, label) {
     this._assertNotCommitted();
+    _assertNoReservedBytes(from, 'from node ID');
+    _assertNoReservedBytes(to, 'to node ID');
+    _assertNoReservedBytes(label, 'edge label');
     const dot = vvIncrement(this._vv, this._writerId);
     this._ops.push(createEdgeAddV2(from, to, label, dot));
     const edgeKey = encodeEdgeKey(from, to, label);
@@ -428,9 +445,11 @@ export class PatchBuilderV2 {
    */
   setProperty(nodeId, key, value) {
     this._assertNotCommitted();
-    // Props don't use dots - they use EventId from patch context
-    this._ops.push(createPropSetV2(nodeId, key, value));
-    // Provenance: PropSet reads the node (implicit existence check) and writes the node
+    _assertNoReservedBytes(nodeId, 'nodeId');
+    _assertNoReservedBytes(key, 'property key');
+    // Canonical NodePropSet — lowered to raw PropSet at commit time
+    this._ops.push(createNodePropSetV2(nodeId, key, value));
+    // Provenance: NodePropSet reads the node (implicit existence check) and writes the node
     this._observedOperands.add(nodeId);
     this._writes.add(nodeId);
     return this;
@@ -475,6 +494,10 @@ export class PatchBuilderV2 {
    */
   setEdgeProperty(from, to, label, key, value) {
     this._assertNotCommitted();
+    _assertNoReservedBytes(from, 'from node ID');
+    _assertNoReservedBytes(to, 'to node ID');
+    _assertNoReservedBytes(label, 'edge label');
+    _assertNoReservedBytes(key, 'property key');
     // Validate edge exists in this patch or in current state
     const ek = encodeEdgeKey(from, to, label);
     if (!this._edgesAdded.has(ek)) {
@@ -484,15 +507,10 @@ export class PatchBuilderV2 {
       }
     }
 
-    // Encode the edge identity as the "node" field with the \x01 prefix.
-    // When JoinReducer processes: encodePropKey(op.node, op.key)
-    //   = `\x01from\0to\0label` + `\0` + key
-    //   = `\x01from\0to\0label\0key`
-    //   = encodeEdgePropKey(from, to, label, key)
-    const edgeNode = `${EDGE_PROP_PREFIX}${from}\0${to}\0${label}`;
-    this._ops.push(createPropSetV2(edgeNode, key, value));
+    // Canonical EdgePropSet — lowered to legacy raw PropSet at commit time
+    this._ops.push(createEdgePropSetV2(from, to, label, key, value));
     this._hasEdgeProps = true;
-    // Provenance: setEdgeProperty reads the edge (implicit existence check) and writes the edge
+    // Provenance: EdgePropSet reads the edge (implicit existence check) and writes the edge
     this._observedOperands.add(ek);
     this._writes.add(ek);
     return this;
@@ -510,11 +528,14 @@ export class PatchBuilderV2 {
    * only sets the `_content` property — it does not create the node.
    *
    * @param {string} nodeId - The node ID to attach content to
-   * @param {Buffer|string} content - The content to attach
+   * @param {Uint8Array|string} content - The content to attach
    * @returns {Promise<PatchBuilderV2>} This builder instance for method chaining
    */
   async attachContent(nodeId, content) {
     this._assertNotCommitted();
+    // Validate identifiers before writing blob to avoid orphaned blobs
+    _assertNoReservedBytes(nodeId, 'nodeId');
+    _assertNoReservedBytes(CONTENT_PROPERTY_KEY, 'key');
     const oid = await this._persistence.writeBlob(content);
     this.setProperty(nodeId, CONTENT_PROPERTY_KEY, oid);
     this._contentBlobs.push(oid);
@@ -528,11 +549,16 @@ export class PatchBuilderV2 {
    * @param {string} from - Source node ID
    * @param {string} to - Target node ID
    * @param {string} label - Edge label
-   * @param {Buffer|string} content - The content to attach
+   * @param {Uint8Array|string} content - The content to attach
    * @returns {Promise<PatchBuilderV2>} This builder instance for method chaining
    */
   async attachEdgeContent(from, to, label, content) {
     this._assertNotCommitted();
+    // Validate identifiers before writing blob to avoid orphaned blobs
+    _assertNoReservedBytes(from, 'from');
+    _assertNoReservedBytes(to, 'to');
+    _assertNoReservedBytes(label, 'label');
+    _assertNoReservedBytes(CONTENT_PROPERTY_KEY, 'key');
     const oid = await this._persistence.writeBlob(content);
     this.setEdgeProperty(from, to, label, CONTENT_PROPERTY_KEY, oid);
     this._contentBlobs.push(oid);
@@ -559,12 +585,14 @@ export class PatchBuilderV2 {
    */
   build() {
     const schema = this._hasEdgeProps ? 3 : 2;
+    // Lower canonical ops to raw form for the persisted patch
+    const rawOps = /** @type {import('../types/WarpTypesV2.js').RawOpV2[]} */ (this._ops.map(lowerCanonicalOp));
     return createPatchV2({
       schema,
       writer: this._writerId,
       lamport: this._lamport,
       context: vvSerialize(this._vv),
-      ops: this._ops,
+      ops: rawOps,
       reads: [...this._observedOperands].sort(),
       writes: [...this._writes].sort(),
     });
@@ -678,20 +706,21 @@ export class PatchBuilderV2 {
       // For now, we use the calculated lamport for the patch metadata.
       // The dots themselves are independent of patch lamport (they use VV counters).
       const schema = this._hasEdgeProps ? 3 : 2;
-      // Use createPatchV2 for consistent patch construction (DRY with build())
+      // Lower canonical ops to raw form for the persisted patch
+      const rawOps = /** @type {import('../types/WarpTypesV2.js').RawOpV2[]} */ (this._ops.map(lowerCanonicalOp));
       const patch = createPatchV2({
         schema,
         writer: this._writerId,
         lamport,
         context: vvSerialize(this._vv),
-        ops: this._ops,
+        ops: rawOps,
         reads: [...this._observedOperands].sort(),
         writes: [...this._writes].sort(),
       });
 
       // 6. Encode patch as CBOR and write as a Git blob
       const patchCbor = this._codec.encode(patch);
-      const patchBlobOid = await this._persistence.writeBlob(/** @type {Buffer} */ (patchCbor));
+      const patchBlobOid = await this._persistence.writeBlob(patchCbor);
 
       // 7. Create tree with the patch blob + any content blobs (deduplicated)
       // Format for mktree: "mode type oid\tpath"
@@ -726,7 +755,7 @@ export class PatchBuilderV2 {
           await this._onCommitSuccess({ patch, sha: newCommitSha });
         } catch (err) {
           // Commit is already persisted — log but don't fail the caller.
-          this._logger.warn(`[warp] onCommitSuccess callback failed (sha=${newCommitSha}):`, err);
+          this._logger.warn(`[warp] onCommitSuccess callback failed (sha=${newCommitSha}):`, { error: err });
         }
       }
 

package/src/domain/services/PatchMessageCodec.js

@@ -25,12 +25,7 @@ import {
 /**
  * Encodes a patch commit message.
  *
- * @param {Object} options - The patch message options
- * @param {string} options.graph - The graph name
- * @param {string} options.writer - The writer ID
- * @param {number} options.lamport - The Lamport timestamp (must be a positive integer)
- * @param {string} options.patchOid - The OID of the patch blob
- * @param {number} [options.schema=2] - The schema version (defaults to 2 for new messages)
+ * @param {{ graph: string, writer: string, lamport: number, patchOid: string, schema?: number }} options - The patch message options
  * @returns {string} The encoded commit message
  * @throws {Error} If any validation fails
  *