@git-stunts/git-warp 12.2.0 → 12.3.0

package/src/domain/services/SyncController.js

@@ -51,6 +51,7 @@ import SyncTrustGate from './SyncTrustGate.js';
  * @property {number} _patchesSinceCheckpoint
  * @property {(op: string, t0: number, opts?: {metrics?: string, error?: Error}) => void} _logTiming
  * @property {(options?: Record<string, unknown>) => Promise<unknown>} materialize
+ * @property {(state: import('../services/JoinReducer.js').WarpStateV5) => Promise<unknown>} _setMaterializedState
  * @property {() => Promise<string[]>} discoverWriters
  */
 
@@ -299,7 +300,7 @@ export default class SyncController {
    * **Requires a cached state.**
    *
    * @param {import('./SyncProtocol.js').SyncResponse} response - The sync response
-   * @returns {Promise<{state: import('./JoinReducer.js').WarpStateV5, frontier: Map<string, string>, applied: number, trustVerdict?: string, writersApplied?: string[]}>} Result with updated state and frontier
+   * @returns {Promise<{state: import('./JoinReducer.js').WarpStateV5, frontier: Map<string, string>, applied: number, trustVerdict?: string, writersApplied?: string[], skippedWriters: Array<{writerId: string, reason: string, localSha: string, remoteSha: string|null}>}>} Result with updated state and frontier
    * @throws {import('../errors/QueryError.js').default} If no cached state exists (code: `E_NO_STATE`)
    * @throws {SyncError} If trust gate rejects untrusted writers (code: `E_SYNC_UNTRUSTED_WRITER`)
    */
@@ -333,8 +334,13 @@ export default class SyncController {
     const currentFrontier = this._host._lastFrontier || createFrontier();
     const result = /** @type {{state: import('./JoinReducer.js').WarpStateV5, frontier: Map<string, string>, applied: number}} */ (applySyncResponseImpl(response, this._host._cachedState, currentFrontier));
 
-    // Update cached state
-    this._host._cachedState = result.state;
+    // Route through canonical state-install path (B105 / C1 fix).
+    // _setMaterializedState sets _cachedState, clears _stateDirty, computes
+    // state hash, builds adjacency, and rebuilds indexes via _buildView().
+    // Bookkeeping is deferred until after install succeeds so that a failed
+    // _setMaterializedState does not leave _lastFrontier/_patchesSinceGC
+    // advanced while _cachedState remains stale.
+    await this._host._setMaterializedState(result.state);
 
     // Keep _lastFrontier in sync so hasFrontierChanged() won't misreport stale.
     this._host._lastFrontier = result.frontier;
@@ -342,32 +348,7 @@ export default class SyncController {
     // Track patches for GC
     this._host._patchesSinceGC += result.applied;
 
-    // Invalidate derived caches (C1) — sync changes underlying state
-    this._invalidateDerivedCaches();
-
-    // State is now in sync with the frontier -- clear dirty flag
-    this._host._stateDirty = false;
-
-    return { ...result, writersApplied };
-  }
-
-  /**
-   * Invalidates all derived caches on the host graph.
-   *
-   * Called after sync apply or join to ensure stale index/provider/view
-   * data is not returned to callers. The next query or traversal will
-   * trigger a rebuild.
-   *
-   * @private
-   */
-  _invalidateDerivedCaches() {
-    const h = /** @type {import('../WarpGraph.js').default} */ (this._host);
-    h._materializedGraph = null;
-    h._logicalIndex = null;
-    h._propertyReader = null;
-    h._cachedViewHash = null;
-    h._cachedIndexTree = null;
-    h._stateDirty = true;
+    return { ...result, writersApplied, skippedWriters: response.skippedWriters || [] };
   }
 
   /**
@@ -396,7 +377,7 @@ export default class SyncController {
    * @param {(event: {type: string, attempt: number, durationMs?: number, status?: number, error?: Error}) => void} [options.onStatus]
    * @param {boolean} [options.materialize=false] - Auto-materialize after sync
    * @param {{ secret: string, keyId?: string }} [options.auth] - Client auth credentials
-   * @returns {Promise<{applied: number, attempts: number, state?: import('./JoinReducer.js').WarpStateV5}>}
+   * @returns {Promise<{applied: number, attempts: number, skippedWriters: Array<{writerId: string, reason: string, localSha: string, remoteSha: string|null}>, state?: import('./JoinReducer.js').WarpStateV5}>}
    */
   async syncWith(remote, options = {}) {
     const t0 = this._host._clock.now();
@@ -550,7 +531,7 @@ export default class SyncController {
 
       const durationMs = this._host._clock.now() - attemptStart;
       emit('complete', { durationMs, applied: result.applied });
-      return { applied: result.applied, attempts: attempt };
+      return { applied: result.applied, attempts: attempt, skippedWriters: result.skippedWriters || [] };
     };
 
     try {

package/src/domain/services/SyncProtocol.js

@@ -39,7 +39,8 @@
 import defaultCodec from '../utils/defaultCodec.js';
 import nullLogger from '../utils/nullLogger.js';
 import { decodePatchMessage, assertOpsCompatible, SCHEMA_V3 } from './WarpMessageCodec.js';
-import { join, cloneStateV5 } 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';
 
@@ -81,6 +82,33 @@ function normalizePatch(patch) {
   return patch;
 }
 
+/**
+ * Converts a frontier Map to a plain object for JSON serialization.
+ *
+ * @param {Map<string, string>} map - Frontier as Map<writerId, sha>
+ * @returns {{ [x: string]: string }} Plain object representation
+ * @private
+ */
+function frontierToObject(map) {
+  /** @type {{ [x: string]: string }} */
+  const obj = {};
+  for (const [writerId, sha] of map) {
+    obj[writerId] = sha;
+  }
+  return obj;
+}
+
+/**
+ * Converts a frontier plain object back to a Map.
+ *
+ * @param {{ [x: string]: string }} obj - Frontier as plain object
+ * @returns {Map<string, string>} Frontier as Map<writerId, sha>
+ * @private
+ */
+function objectToFrontier(obj) {
+  return new Map(Object.entries(obj));
+}
+
 /**
  * Loads a patch from a commit.
  *
@@ -252,7 +280,8 @@ export function computeSyncDelta(localFrontier, remoteFrontier) {
       newWritersForLocal.push(writerId);
     } else if (localSha !== remoteSha) {
       // Different heads - local needs patches from its head to remote head
-      // Note: We assume remote is ahead; the caller should verify ancestry
+      // Direction is intentionally deferred: ancestry is verified by
+      // isAncestor() pre-check or loadPatchRange() in processSyncRequest()
       needFromRemote.set(writerId, { from: localSha, to: remoteSha });
     }
     // If localSha === remoteSha, already in sync for this writer
@@ -339,16 +368,9 @@ export function computeSyncDelta(localFrontier, remoteFrontier) {
  * // Send over HTTP: await fetch(url, { body: JSON.stringify(request) })
  */
 export function createSyncRequest(frontier) {
-  // Convert Map to plain object for serialization
-  /** @type {{ [x: string]: string }} */
-  const frontierObj = {};
-  for (const [writerId, sha] of frontier) {
-    frontierObj[writerId] = sha;
-  }
-
   return {
     type: /** @type {'sync-request'} */ ('sync-request'),
-    frontier: frontierObj,
+    frontier: frontierToObject(frontier),
   };
 }
 
@@ -393,8 +415,7 @@ export function createSyncRequest(frontier) {
 export async function processSyncRequest(request, localFrontier, persistence, graphName, { codec, logger } = /** @type {{ codec?: import('../../ports/CodecPort.js').default, logger?: import('../../ports/LoggerPort.js').default }} */ ({})) {
   const log = logger || nullLogger;
 
-  // Convert incoming frontier from object to Map
-  const remoteFrontier = new Map(Object.entries(request.frontier));
+  const remoteFrontier = objectToFrontier(request.frontier);
 
   // Compute what the requester needs
   const delta = computeSyncDelta(remoteFrontier, localFrontier);
@@ -406,6 +427,29 @@ export async function processSyncRequest(request, localFrontier, persistence, gr
 
   for (const [writerId, range] of delta.needFromRemote) {
     try {
+      // Pre-check ancestry to avoid expensive chain walk (B107 / S3 fix).
+      // If the persistence layer provides isAncestor, use it to detect
+      // divergence early without walking the full commit chain.
+      const hasIsAncestor = typeof /** @type {{isAncestor?: (...args: unknown[]) => unknown}} */ (persistence).isAncestor === 'function';
+      if (range.from && hasIsAncestor) {
+        const isAnc = await /** @type {{isAncestor: (a: string, b: string) => Promise<boolean>}} */ (/** @type {unknown} */ (persistence)).isAncestor(range.from, range.to);
+        if (!isAnc) {
+          const entry = {
+            writerId,
+            reason: 'E_SYNC_DIVERGENCE',
+            localSha: range.to,
+            remoteSha: range.from,
+          };
+          skippedWriters.push(entry);
+          log.warn('Sync divergence detected — skipping writer', {
+            code: 'E_SYNC_DIVERGENCE',
+            graphName,
+            ...entry,
+          });
+          continue;
+        }
+      }
+
       const writerPatches = await loadPatchRange(
         persistence,
         graphName,
@@ -440,16 +484,9 @@ export async function processSyncRequest(request, localFrontier, persistence, gr
     }
   }
 
-  // Convert local frontier to plain object
-  /** @type {{ [x: string]: string }} */
-  const frontierObj = {};
-  for (const [writerId, sha] of localFrontier) {
-    frontierObj[writerId] = sha;
-  }
-
   return {
     type: /** @type {'sync-response'} */ ('sync-response'),
-    frontier: frontierObj,
+    frontier: frontierToObject(localFrontier),
     patches,
     skippedWriters,
   };
@@ -503,7 +540,10 @@ export function applySyncResponse(response, state, frontier) {
   const newFrontier = cloneFrontier(frontier);
   let applied = 0;
 
-  // Group patches by writer to ensure proper ordering
+  // Patches arrive pre-grouped by writer from the sync response. This
+  // re-grouping is defensive — it handles edge cases where patches from
+  // multiple writers arrive interleaved (e.g., from a relay that merges
+  // streams).
   const patchesByWriter = new Map();
   for (const { writerId, sha, patch } of response.patches) {
     if (!patchesByWriter.has(writerId)) {
@@ -518,10 +558,20 @@ export function applySyncResponse(response, state, frontier) {
     for (const { sha, patch } of writerPatches) {
       // Normalize patch context (in case it came from network serialization)
       const normalizedPatch = normalizePatch(patch);
-      // Guard: reject patches containing ops we don't understand.
-      // Currently SCHEMA_V3 is the max, so this is a no-op for this
-      // codebase. If a future schema adds new op types, this check
-      // will prevent silent data loss until the reader is upgraded.
+      // Guard: reject patches with genuinely unknown op types (B106 / C2 fix).
+      // 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 (!isKnownRawOp(op)) {
+          throw new SchemaUnsupportedError(
+            `Patch ${sha} contains unknown op type: ${op.type}`
+          );
+        }
+      }
+      // Guard: reject patches exceeding our maximum supported schema version.
+      // 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
       join(newState, /** @type {Parameters<typeof join>[1]} */ (normalizedPatch), sha);
@@ -609,15 +659,9 @@ export function syncNeeded(localFrontier, remoteFrontier) {
  * }
  */
 export function createEmptySyncResponse(frontier) {
-  /** @type {{ [x: string]: string }} */
-  const frontierObj = {};
-  for (const [writerId, sha] of frontier) {
-    frontierObj[writerId] = sha;
-  }
-
   return {
     type: /** @type {'sync-response'} */ ('sync-response'),
-    frontier: frontierObj,
+    frontier: frontierToObject(frontier),
     patches: [],
   };
 }

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/trust/TrustRecordService.js

@@ -26,6 +26,10 @@ const MAX_CAS_ATTEMPTS = 3;
  * @property {boolean} [skipSignatureVerify=false] - Skip signature verification (for testing)
  */
 
+/**
+ * @typedef {{ok: true, records: Array<Record<string, unknown>>} | {ok: false, error: Error}} ReadRecordsResult
+ */
+
 export class TrustRecordService {
   /**
    * @param {Object} options
@@ -102,55 +106,65 @@ export class TrustRecordService {
    * @param {string} graphName
    * @param {Object} [options]
    * @param {string} [options.tip] - Override tip commit (for pinned reads)
-   * @returns {Promise<Array<Record<string, unknown>>>}
+   * @returns {Promise<ReadRecordsResult>}
    */
   async readRecords(graphName, options = {}) {
     const ref = buildTrustRecordRef(graphName);
     let tip = options.tip ?? null;
 
-    if (!tip) {
-      try {
-        tip = await this._persistence.readRef(ref);
-      } catch (err) {
-        // Distinguish "ref not found" from operational error (J15)
-        if (err instanceof Error && (err.message?.includes('not found') || err.message?.includes('does not exist'))) {
-          return [];
-        }
-        throw new TrustError(
-          `Failed to read trust chain ref: ${err instanceof Error ? err.message : String(err)}`,
-          { code: 'E_TRUST_READ_FAILED' },
-        );
-      }
+    try {
       if (!tip) {
-        return [];
+        try {
+          tip = await this._persistence.readRef(ref);
+        } catch (err) {
+          // Distinguish "ref not found" from operational error (J15)
+          if (err instanceof Error && (err.message?.includes('not found') || err.message?.includes('does not exist'))) {
+            return { ok: true, records: [] };
+          }
+          return {
+            ok: false,
+            error: new TrustError(
+              `Failed to read trust chain ref: ${err instanceof Error ? err.message : String(err)}`,
+              { code: 'E_TRUST_READ_FAILED' },
+            ),
+          };
+        }
+        if (!tip) {
+          return { ok: true, records: [] };
+        }
       }
-    }
 
-    const records = [];
-    let current = tip;
+      const records = [];
+      let current = tip;
 
-    while (current) {
-      const info = await this._persistence.getNodeInfo(current);
-      const entries = await this._persistence.readTreeOids(
-        await this._persistence.getCommitTree(current),
-      );
-      const blobOid = entries['record.cbor'];
-      if (!blobOid) {
-        break;
-      }
-      const record = /** @type {Record<string, unknown>} */ (this._codec.decode(
-        await this._persistence.readBlob(blobOid),
-      ));
+      while (current) {
+        const info = await this._persistence.getNodeInfo(current);
+        const entries = await this._persistence.readTreeOids(
+          await this._persistence.getCommitTree(current),
+        );
+        const blobOid = entries['record.cbor'];
+        if (!blobOid) {
+          break;
+        }
+        const record = /** @type {Record<string, unknown>} */ (this._codec.decode(
+          await this._persistence.readBlob(blobOid),
+        ));
 
-      records.unshift(record);
+        records.unshift(record);
 
-      if (info.parents.length === 0) {
-        break;
+        if (info.parents.length === 0) {
+          break;
+        }
+        current = info.parents[0];
       }
-      current = info.parents[0];
-    }
 
-    return records;
+      return { ok: true, records };
+    } catch (err) {
+      return {
+        ok: false,
+        error: err instanceof Error ? err : new Error(String(err)),
+      };
+    }
   }
 
   /**

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

@@ -54,6 +54,12 @@ class CachedValue {
     /** @type {T|null} */
     this._value = null;
 
+    /** @type {Promise<T>|null} */
+    this._inflight = null;
+
+    /** @type {number} */
+    this._generation = 0;
+
     /** @type {number} */
     this._cachedAt = 0;
 
@@ -71,12 +77,33 @@ class CachedValue {
       return /** @type {T} */ (this._value);
     }
 
-    const value = await this._compute();
-    this._value = value;
-    this._cachedAt = this._clock.now();
-    this._cachedAtIso = this._clock.timestamp();
+    if (this._inflight) {
+      return await this._inflight;
+    }
 
-    return value;
+    const generation = this._generation;
+
+    this._inflight = Promise.resolve(this._compute()).then(
+      (value) => {
+        // Ignore stale in-flight completion if cache was invalidated mid-flight.
+        if (generation !== this._generation) {
+          return value;
+        }
+        this._value = value;
+        this._cachedAt = this._clock.now();
+        this._cachedAtIso = this._clock.timestamp();
+        this._inflight = null;
+        return value;
+      },
+      (err) => {
+        if (generation === this._generation) {
+          this._inflight = null;
+        }
+        throw err;
+      },
+    );
+
+    return await this._inflight;
   }
 
   /**
@@ -99,7 +126,9 @@ class CachedValue {
    * Invalidates the cached value, forcing recomputation on next get().
    */
   invalidate() {
+    this._generation += 1;
     this._value = null;
+    this._inflight = null;
     this._cachedAt = 0;
     this._cachedAtIso = null;
   }

package/src/domain/utils/EventId.js

@@ -49,6 +49,9 @@ export function createEventId(lamport, writerId, patchSha, opIndex) {
  * Compares two EventIds lexicographically.
  * Order: lamport -> writerId -> patchSha -> opIndex
  *
+ * SHA tiebreaker uses lexicographic string comparison. This is arbitrary but
+ * deterministic — the specific order doesn't matter as long as all writers agree.
+ *
  * @param {EventId} a
  * @param {EventId} b
  * @returns {number} -1 if a < b, 0 if equal, 1 if a > b
@@ -64,7 +67,7 @@ export function compareEventIds(a, b) {
     return a.writerId < b.writerId ? -1 : 1;
   }
 
-  // 3. Compare patchSha as string
+  // 3. Compare patchSha as string (lexicographic — arbitrary but deterministic)
   if (a.patchSha !== b.patchSha) {
     return a.patchSha < b.patchSha ? -1 : 1;
   }

package/src/domain/utils/LRUCache.js

@@ -34,7 +34,9 @@ class LRUCache {
     if (!this._cache.has(key)) {
       return undefined;
     }
-    // Move to end (most recently used) by deleting and re-inserting
+    // Delete-reinsert maintains insertion order in the underlying Map, which
+    // serves as the LRU eviction order. This is O(1) amortized in V8's Map
+    // implementation despite appearing wasteful (2x Map ops per get).
     const value = /** @type {V} */ (this._cache.get(key));
     this._cache.delete(key);
     this._cache.set(key, value);

package/src/domain/utils/RefLayout.js

@@ -376,6 +376,10 @@ export function buildTrustRecordRef(graphName) {
 /**
  * Parses and extracts the writer ID from a writer ref path.
  *
+ * Returns null for any non-writer ref, including malformed refs. Callers that
+ * need to distinguish "not a writer ref" from "malformed ref" should validate
+ * the ref format separately before calling this method.
+ *
  * @param {string} refPath - The full ref path
  * @returns {string|null} The writer ID, or null if the path is not a valid writer ref
  *