@git-stunts/git-warp 12.2.0 → 12.3.0

package/src/domain/services/MaterializedViewService.js

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