@git-stunts/git-warp 12.2.1 → 12.3.0

package/README.md

@@ -8,12 +8,13 @@
   <img src="docs/images/hero.gif" alt="git-warp CLI demo" width="600">
 </p>
 
-## What's New in v12.2.1
+## What's New in v12.3.0
 
-- **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).
+- **M13 ADR 1 — canonical edge property ops** — internal model now uses honest `NodePropSet`/`EdgePropSet` semantics. Legacy raw `PropSet` is normalized at reducer entry points and lowered back at write time. No wire-format change — persisted patches remain backward-compatible.
+- **Wire gate hardened** — sync boundary now explicitly rejects canonical-only op types (`NodePropSet`, `EdgePropSet`) arriving over the wire, preventing premature schema migration before ADR 2 capability cutover.
+- **Reserved-byte validation** — new writes reject node IDs containing `\0` or starting with `\x01`, preventing ambiguous legacy edge-property encoding.
+- **Version namespace separation** — patch schema and checkpoint schema constants are now distinct (`PATCH_SCHEMA_V2`/`V3` vs `CHECKPOINT_SCHEMA_STANDARD`/`INDEX_TREE`).
+- **ADR governance** — ADR 3 readiness gates formalize when the persisted wire-format migration may proceed, with GitHub issue template and go/no-go checklist.
 
 See the [full changelog](CHANGELOG.md) for details.
 

package/bin/presenters/text.js

@@ -291,7 +291,8 @@ function formatOpSummaryPlain(summary) {
   const order = [
     ['NodeAdd', '+', 'node'],
     ['EdgeAdd', '+', 'edge'],
-    ['PropSet', '~', 'prop'],
+    ['prop', '~', 'prop'],       // coalesced PropSet + NodePropSet
+    ['EdgePropSet', '~', 'eprop'],
     ['NodeTombstone', '-', 'node'],
     ['EdgeTombstone', '-', 'edge'],
     ['BlobValue', '+', 'blob'],
@@ -299,7 +300,10 @@ function formatOpSummaryPlain(summary) {
 
   const parts = [];
   for (const [opType, symbol, label] of order) {
-    const n = summary?.[opType];
+    // Coalesce PropSet + NodePropSet into one bucket
+    const n = opType === 'prop'
+      ? (summary?.PropSet || 0) + (summary?.NodePropSet || 0) || undefined
+      : summary?.[opType];
     if (typeof n === 'number' && Number.isFinite(n) && n > 0) {
       parts.push(`${symbol}${n}${label}`);
     }
@@ -612,9 +616,12 @@ function formatPatchOp(op) {
   if (op.type === 'EdgeTombstone') {
     return `  - edge ${op.from} -[${op.label}]-> ${op.to}`;
   }
-  if (op.type === 'PropSet') {
+  if (op.type === 'PropSet' || op.type === 'NodePropSet') {
     return `  ~ ${op.node}.${op.key} = ${JSON.stringify(op.value)}`;
   }
+  if (op.type === 'EdgePropSet') {
+    return `  ~ edge(${op.from} -[${op.label}]-> ${op.to}).${op.key} = ${JSON.stringify(op.value)}`;
+  }
   if (op.type === 'BlobValue') {
     return `  + blob ${op.node}`;
   }

package/package.json

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

package/src/domain/crdt/ORSet.js

@@ -116,6 +116,9 @@ export function createORSet() {
  * @param {import('./Dot.js').Dot} dot - The dot representing this add operation
  */
 export function orsetAdd(set, element, dot) {
+  if (!dot || typeof dot.writerId !== 'string' || !Number.isInteger(dot.counter)) {
+    throw new Error(`orsetAdd: invalid dot -- expected {writerId: string, counter: integer}, got ${JSON.stringify(dot)}`);
+  }
   const encoded = encodeDot(dot);
 
   let dots = set.entries.get(element);

package/src/domain/services/AuditReceiptService.js

@@ -339,7 +339,8 @@ export class AuditReceiptService {
     // Compute opsDigest
     const opsDigest = await computeOpsDigest(ops, this._crypto);
 
-    // Timestamp
+    // Wall-clock timestamp for audit receipt (not a perf timer)
+    // eslint-disable-next-line no-restricted-syntax
     const timestamp = Date.now();
 
     // Determine prevAuditCommit

package/src/domain/services/AuditVerifierService.js

@@ -257,6 +257,7 @@ export class AuditVerifierService {
 
     return {
       graph: graphName,
+      // eslint-disable-next-line no-restricted-syntax -- wall-clock timestamp for audit report
       verifiedAt: new Date().toISOString(),
       summary: { total: chains.length, valid, partial, invalid },
       chains,

package/src/domain/services/BoundaryTransitionRecord.js

@@ -164,6 +164,7 @@ export async function createBTR(initialState, payload, options) {
     throw new TypeError('payload must be a ProvenancePayload');
   }
 
+  // eslint-disable-next-line no-restricted-syntax -- wall-clock default for BTR timestamp
   const { key, timestamp = new Date().toISOString(), crypto, codec } = options;
 
   // Validate HMAC key is not empty/falsy

package/src/domain/services/CheckpointMessageCodec.js

@@ -5,6 +5,11 @@
  * materialized graph state. See {@link module:domain/services/WarpMessageCodec}
  * for the facade that re-exports all codec functions.
  *
+ * **Schema namespace note:** Checkpoint schema versions (2, 3, 4) are
+ * distinct from patch schema versions (PATCH_SCHEMA_V2, PATCH_SCHEMA_V3).
+ * See {@link module:domain/services/CheckpointService} for named constants
+ * `CHECKPOINT_SCHEMA_STANDARD` and `CHECKPOINT_SCHEMA_INDEX_TREE`.
+ *
  * @module domain/services/CheckpointMessageCodec
  */
 

package/src/domain/services/CheckpointService.js

@@ -28,6 +28,24 @@ import { cloneStateV5, reduceV5 } from './JoinReducer.js';
 import { encodeEdgeKey, encodePropKey, CONTENT_PROPERTY_KEY, decodePropKey, isEdgePropKey, decodeEdgePropKey } from './KeyCodec.js';
 import { ProvenanceIndex } from './ProvenanceIndex.js';
 
+// ============================================================================
+// Checkpoint Schema Constants
+// ============================================================================
+
+/**
+ * Standard checkpoint schema — full V5 state without index tree.
+ * Distinct from the patch schema namespace (PATCH_SCHEMA_V2/V3).
+ * @type {number}
+ */
+export const CHECKPOINT_SCHEMA_STANDARD = 2;
+
+/**
+ * Index-tree checkpoint schema — full V5 state with bitmap index tree.
+ * Distinct from the patch schema namespace (PATCH_SCHEMA_V2/V3).
+ * @type {number}
+ */
+export const CHECKPOINT_SCHEMA_INDEX_TREE = 4;
+
 // ============================================================================
 // Internal Helpers
 // ============================================================================
@@ -244,7 +262,7 @@ export async function createV5({
     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,
+    schema: indexTree ? CHECKPOINT_SCHEMA_INDEX_TREE : CHECKPOINT_SCHEMA_STANDARD,
   });
 
   // 9. Create the checkpoint commit

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
@@ -92,19 +96,58 @@ export function createEmptyStateV5() {
  * @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 +249,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 +298,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))));
@@ -278,6 +357,8 @@ const RECEIPT_OP_TYPE = {
   EdgeAdd: 'EdgeAdd',
   EdgeRemove: 'EdgeTombstone',
   PropSet: 'PropSet',
+  NodePropSet: 'NodePropSet',
+  EdgePropSet: 'EdgePropSet',
   BlobValue: 'BlobValue',
 };
 
@@ -409,7 +490,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 +504,61 @@ 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 {Object} op
+ * @param {string} op.node - Node ID owning the property
+ * @param {string} op.key - Property key/name
+ * @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 {Object} op
+ * @param {string} op.from
+ * @param {string} op.to
+ * @param {string} op.label
+ * @param {string} op.key
+ * @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);
 }
 
 /**
@@ -504,7 +605,7 @@ function updateFrontierFromPatch(state, patch) {
 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 +700,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 +747,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 +761,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;
   }
@@ -701,7 +822,7 @@ function collectEdgeRemovals(diff, state, before) {
  * @param {Object} patch - The patch to apply
  * @param {string} patch.writer
  * @param {number} patch.lamport
- * @param {Array<Object>} patch.ops
+ * @param {Array<import('../types/WarpTypesV2.js').OpV2 | {type: string}>} patch.ops
  * @param {Map<string, number>|{[x: string]: number}} patch.context
  * @param {string} patchSha - Git SHA of the patch commit
  * @returns {{state: WarpStateV5, diff: import('../types/PatchDiff.js').PatchDiff}}
@@ -710,13 +831,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);
@@ -739,41 +859,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: *}} */ (canonOp), eventId);
         break;
-      default:
+      case 'EdgePropSet':
+        outcome = edgePropSetOutcome(state.prop, /** @type {{from: string, to: string, label: string, key: string, value: *}} */ (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;

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/MaterializedViewService.js

@@ -354,7 +354,7 @@ export default class MaterializedViewService {
    * @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/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.
  */
@@ -85,7 +111,7 @@ export class PatchBuilderV2 {
    * @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 {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for non-fatal warnings
    */
   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} */
@@ -133,7 +159,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 +259,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 +332,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 +375,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 +457,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 +506,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 +519,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;
@@ -515,6 +545,9 @@ export class PatchBuilderV2 {
    */
   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);
@@ -533,6 +566,11 @@ export class PatchBuilderV2 {
    */
   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 +597,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,13 +718,14 @@ 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(),
       });
@@ -726,7 +767,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/SyncAuthService.js

@@ -68,6 +68,8 @@ export function buildCanonicalPayload({ keyId, method, path, timestamp, nonce, c
  */
 export async function signSyncRequest({ method, path, contentType, body, secret, keyId }, { crypto } = {}) {
   const c = crypto || defaultCrypto;
+  // Wall-clock timestamp required for HMAC replay protection (not a perf timer)
+  // eslint-disable-next-line no-restricted-syntax
   const timestamp = String(Date.now());
   const nonce = globalThis.crypto.randomUUID();
 
@@ -187,6 +189,7 @@ export default class SyncAuthService {
     this._mode = mode;
     this._crypto = crypto || defaultCrypto;
     this._logger = logger || nullLogger;
+    // eslint-disable-next-line no-restricted-syntax -- wall-clock fallback for HMAC verification
     this._wallClockMs = wallClockMs || (() => Date.now());
     this._maxClockSkewMs = typeof maxClockSkewMs === 'number' ? maxClockSkewMs : MAX_CLOCK_SKEW_MS;
     this._nonceCache = new LRUCache(nonceCapacity || DEFAULT_NONCE_CAPACITY);

package/src/domain/services/SyncProtocol.js

@@ -39,7 +39,7 @@
 import defaultCodec from '../utils/defaultCodec.js';
 import nullLogger from '../utils/nullLogger.js';
 import { decodePatchMessage, assertOpsCompatible, SCHEMA_V3 } from './WarpMessageCodec.js';
-import { join, cloneStateV5, isKnownOp } from './JoinReducer.js';
+import { join, cloneStateV5, isKnownRawOp } from './JoinReducer.js';
 import SchemaUnsupportedError from '../errors/SchemaUnsupportedError.js';
 import { cloneFrontier, updateFrontier } from './Frontier.js';
 import { vvDeserialize } from '../crdt/VersionVector.js';
@@ -559,17 +559,18 @@ export function applySyncResponse(response, state, frontier) {
       // Normalize patch context (in case it came from network serialization)
       const normalizedPatch = normalizePatch(patch);
       // Guard: reject patches with genuinely unknown op types (B106 / C2 fix).
-      // This prevents silent data loss when a newer writer sends ops we
-      // don't recognise — fail closed rather than silently ignoring.
+      // Uses isKnownRawOp to accept only the 6 wire-format types. Canonical-only
+      // types (NodePropSet, EdgePropSet) must never appear on the wire before
+      // ADR 2 capability cutover — reject them here to fail closed.
       for (const op of normalizedPatch.ops) {
-        if (!isKnownOp(op)) {
+        if (!isKnownRawOp(op)) {
           throw new SchemaUnsupportedError(
             `Patch ${sha} contains unknown op type: ${op.type}`
           );
         }
       }
       // Guard: reject patches exceeding our maximum supported schema version.
-      // isKnownOp() above checks op-type recognition; this checks the schema
+      // isKnownRawOp() above checks op-type recognition; this checks the schema
       // version ceiling. Currently SCHEMA_V3 is the max.
       assertOpsCompatible(normalizedPatch.ops, SCHEMA_V3);
       // Apply patch to state

package/src/domain/services/WarpMessageCodec.js

@@ -29,4 +29,6 @@ export {
   assertOpsCompatible,
   SCHEMA_V2,
   SCHEMA_V3,
+  PATCH_SCHEMA_V2,
+  PATCH_SCHEMA_V3,
 } from './MessageSchemaDetector.js';

package/src/domain/trust/TrustCrypto.js

@@ -16,6 +16,13 @@ export const SUPPORTED_ALGORITHMS = new Set(['ed25519']);
 
 const ED25519_PUBLIC_KEY_LENGTH = 32;
 
+/**
+ * DER-encoded SPKI prefix for Ed25519 public keys (RFC 8410, Section 4).
+ * Prepend to a 32-byte raw key to form a valid SPKI structure for `createPublicKey()`.
+ * @see https://www.rfc-editor.org/rfc/rfc8410#section-4
+ */
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
 /**
  * Decodes a base64-encoded Ed25519 public key and validates its length.
  *
@@ -81,11 +88,7 @@ export function verifySignature({
   const raw = decodePublicKey(publicKeyBase64);
 
   const keyObject = createPublicKey({
-    key: Buffer.concat([
-      // DER prefix for Ed25519 public key (RFC 8410)
-      Buffer.from('302a300506032b6570032100', 'hex'),
-      raw,
-    ]),
+    key: Buffer.concat([ED25519_SPKI_PREFIX, raw]),
     format: 'der',
     type: 'spki',
   });

package/src/domain/types/TickReceipt.js

@@ -25,6 +25,8 @@ export const OP_TYPES = Object.freeze([
   'EdgeAdd',
   'EdgeTombstone',
   'PropSet',
+  'NodePropSet',
+  'EdgePropSet',
   'BlobValue',
 ]);
 
@@ -80,9 +82,9 @@ function validateOp(op, index) {
 /**
  * Validates that an operation type is one of the allowed OP_TYPES.
  *
- * Valid operation types correspond to the six patch operations defined
- * in PatchBuilderV2: NodeAdd, NodeTombstone, EdgeAdd, EdgeTombstone,
- * PropSet, and BlobValue.
+ * Valid operation types correspond to the eight receipt operation types:
+ * NodeAdd, NodeTombstone, EdgeAdd, EdgeTombstone, PropSet, NodePropSet,
+ * EdgePropSet, and BlobValue.
  *
  * @param {unknown} value - The operation type to validate
  * @param {number} i - Index of the operation in the ops array (for error messages)
@@ -156,7 +158,7 @@ function validateOpResult(value, i) {
 
 /**
  * @typedef {Object} OpOutcome
- * @property {string} op - Operation type ('NodeAdd' | 'NodeTombstone' | 'EdgeAdd' | 'EdgeTombstone' | 'PropSet' | 'BlobValue')
+ * @property {string} op - Operation type ('NodeAdd' | 'NodeTombstone' | 'EdgeAdd' | 'EdgeTombstone' | 'PropSet' | 'NodePropSet' | 'EdgePropSet' | 'BlobValue')
  * @property {string} target - Node ID or edge key
  * @property {'applied' | 'superseded' | 'redundant'} result - Outcome of the operation
  * @property {string} [reason] - Human-readable explanation (e.g., "LWW: writer bob at lamport 43 wins")

package/src/domain/types/WarpTypesV2.js

@@ -74,18 +74,64 @@
  */
 
 /**
- * Property set operation - sets a property value on a node
- * Uses EventId for identification (derived from patch context)
+ * Property set operation - sets a property value on a node (raw/persisted form).
+ * Uses EventId for identification (derived from patch context).
+ *
+ * In raw patches, edge properties are also encoded as PropSet with the node
+ * field carrying a \x01-prefixed edge identity. See {@link OpV2NodePropSet}
+ * and {@link OpV2EdgePropSet} for the canonical (internal) representations.
+ *
  * @typedef {Object} OpV2PropSet
  * @property {'PropSet'} type - Operation type discriminator
+ * @property {NodeId} node - Node ID to set property on (may contain \x01 prefix for edge props)
+ * @property {string} key - Property key
+ * @property {unknown} value - Property value (any JSON-serializable type)
+ */
+
+/**
+ * Canonical node property set operation (internal only — never persisted).
+ * @typedef {Object} OpV2NodePropSet
+ * @property {'NodePropSet'} type - Operation type discriminator
  * @property {NodeId} node - Node ID to set property on
  * @property {string} key - Property key
  * @property {unknown} value - Property value (any JSON-serializable type)
  */
 
 /**
- * Union of all v2 operation types
- * @typedef {OpV2NodeAdd | OpV2NodeRemove | OpV2EdgeAdd | OpV2EdgeRemove | OpV2PropSet} OpV2
+ * Canonical edge property set operation (internal only — never persisted).
+ * @typedef {Object} OpV2EdgePropSet
+ * @property {'EdgePropSet'} type - Operation type discriminator
+ * @property {NodeId} from - Source node ID
+ * @property {NodeId} to - Target node ID
+ * @property {string} label - Edge label
+ * @property {string} key - Property key
+ * @property {unknown} value - Property value (any JSON-serializable type)
+ */
+
+/**
+ * Blob value reference operation.
+ * @typedef {Object} OpV2BlobValue
+ * @property {'BlobValue'} type - Operation type discriminator
+ * @property {string} node - Node ID the blob is attached to
+ * @property {string} oid - Blob object ID in the Git object store
+ */
+
+/**
+ * Union of all raw (persisted) v2 operation types.
+ * @typedef {OpV2NodeAdd | OpV2NodeRemove | OpV2EdgeAdd | OpV2EdgeRemove | OpV2PropSet | OpV2BlobValue} RawOpV2
+ */
+
+/**
+ * Union of all canonical (internal) v2 operation types.
+ * Reducers, provenance, receipts, and queries operate on canonical ops only.
+ * @typedef {OpV2NodeAdd | OpV2NodeRemove | OpV2EdgeAdd | OpV2EdgeRemove | OpV2NodePropSet | OpV2EdgePropSet | OpV2BlobValue} CanonicalOpV2
+ */
+
+/**
+ * Union of all v2 operation types (raw + canonical).
+ * Used in patch containers that may hold either raw ops (from disk)
+ * or canonical ops (after normalization).
+ * @typedef {RawOpV2 | CanonicalOpV2} OpV2
  */
 
 // ============================================================================
@@ -153,7 +199,9 @@ export function createEdgeRemoveV2(from, to, label, observedDots) {
 }
 
 /**
- * Creates a PropSet operation (no dot - uses EventId)
+ * Creates a raw PropSet operation (no dot - uses EventId).
+ * This is the persisted form. For internal use, prefer
+ * {@link createNodePropSetV2} or {@link createEdgePropSetV2}.
  * @param {NodeId} node - Node ID to set property on
  * @param {string} key - Property key
  * @param {unknown} value - Property value (any JSON-serializable type)
@@ -163,6 +211,30 @@ export function createPropSetV2(node, key, value) {
   return { type: 'PropSet', node, key, value };
 }
 
+/**
+ * Creates a canonical NodePropSet operation (internal only).
+ * @param {NodeId} node - Node ID to set property on
+ * @param {string} key - Property key
+ * @param {unknown} value - Property value (any JSON-serializable type)
+ * @returns {OpV2NodePropSet} NodePropSet operation
+ */
+export function createNodePropSetV2(node, key, value) {
+  return { type: 'NodePropSet', node, key, value };
+}
+
+/**
+ * Creates a canonical EdgePropSet operation (internal only).
+ * @param {NodeId} from - Source node ID
+ * @param {NodeId} to - Target node ID
+ * @param {string} label - Edge label
+ * @param {string} key - Property key
+ * @param {unknown} value - Property value (any JSON-serializable type)
+ * @returns {OpV2EdgePropSet} EdgePropSet operation
+ */
+export function createEdgePropSetV2(from, to, label, key, value) {
+  return { type: 'EdgePropSet', from, to, label, key, value };
+}
+
 // ============================================================================
 // Factory Functions - Patch
 // ============================================================================

package/src/domain/utils/defaultClock.js

@@ -13,6 +13,7 @@ const defaultClock = {
     return performance.now();
   },
   timestamp() {
+    // eslint-disable-next-line no-restricted-syntax -- ClockPort implementation
     return new Date().toISOString();
   },
 };

package/src/domain/warp/Writer.js

@@ -15,6 +15,7 @@
  */
 
 import defaultCodec from '../utils/defaultCodec.js';
+import nullLogger from '../utils/nullLogger.js';
 import { validateWriterId, buildWriterRef } from '../utils/RefLayout.js';
 import { PatchSession } from './PatchSession.js';
 import { PatchBuilderV2 } from '../services/PatchBuilderV2.js';
@@ -44,8 +45,9 @@ export class Writer {
    * @param {(result: {patch: Object, sha: string}) => void | Promise<void>} [options.onCommitSuccess] - Callback invoked after successful commit with { patch, sha }
    * @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 CBOR serialization (defaults to domain-local codec)
+   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger port
    */
-  constructor({ persistence, graphName, writerId, versionVector, getCurrentState, onCommitSuccess, onDeleteWithData = 'warn', codec }) {
+  constructor({ persistence, graphName, writerId, versionVector, getCurrentState, onCommitSuccess, onDeleteWithData = 'warn', codec, logger }) {
     validateWriterId(writerId);
 
     /** @type {import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default & import('../../ports/CommitPort.js').default} */
@@ -72,6 +74,9 @@ export class Writer {
     /** @type {import('../../ports/CodecPort.js').default|undefined} */
     this._codec = codec || defaultCodec;
 
+    /** @type {import('../../ports/LoggerPort.js').default} */
+    this._logger = logger || nullLogger;
+
     /** @type {boolean} */
     this._commitInProgress = false;
   }
@@ -151,6 +156,7 @@ export class Writer {
       onCommitSuccess: this._onCommitSuccess,
       onDeleteWithData: this._onDeleteWithData,
       codec: this._codec,
+      logger: this._logger,
     });
 
     // Return PatchSession wrapping the builder

package/src/domain/warp/fork.methods.js

@@ -104,7 +104,7 @@ export async function fork({ from, at, forkName, forkWriterId }) {
 
     // 4. Generate or validate fork name (add random suffix to prevent collisions)
     const resolvedForkName =
-      forkName ?? `${this._graphName}-fork-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+      forkName ?? `${this._graphName}-fork-${Math.random().toString(36).slice(2, 10).padEnd(8, '0')}`;
     try {
       validateGraphName(resolvedForkName);
     } catch (err) {

package/src/domain/warp/patch.methods.js

@@ -291,6 +291,7 @@ export async function writer(writerId) {
     onDeleteWithData: this._onDeleteWithData,
     onCommitSuccess: /** @type {(result: {patch: Object, sha: string}) => void} */ (/** @type {unknown} */ ((/** @type {{patch?: import('../types/WarpTypesV2.js').PatchV2, sha?: string}} */ opts) => this._onPatchCommitted(resolvedWriterId, opts))),
     codec: this._codec,
+    logger: this._logger || undefined,
   });
 }
 
@@ -349,6 +350,7 @@ export async function createWriter(opts = {}) {
     onDeleteWithData: this._onDeleteWithData,
     onCommitSuccess: /** @type {(result: {patch: Object, sha: string}) => void} */ (/** @type {unknown} */ ((/** @type {{patch?: import('../types/WarpTypesV2.js').PatchV2, sha?: string}} */ commitOpts) => this._onPatchCommitted(freshWriterId, commitOpts))),
     codec: this._codec,
+    logger: this._logger || undefined,
   });
 }