@git-stunts/git-warp 12.1.0 → 12.2.0

package/src/domain/trust/TrustRecordService.js

@@ -14,6 +14,13 @@ import { TrustRecordSchema } from './schemas.js';
 import { verifyRecordId } from './TrustCanonical.js';
 import TrustError from '../errors/TrustError.js';
 
+/**
+ * Maximum CAS attempts for _persistRecord before giving up.
+ * Handles transient failures (lock contention, I/O race).
+ * @type {number}
+ */
+const MAX_CAS_ATTEMPTS = 3;
+
 /**
  * @typedef {Object} AppendOptions
  * @property {boolean} [skipSignatureVerify=false] - Skip signature verification (for testing)
@@ -104,8 +111,15 @@ export class TrustRecordService {
     if (!tip) {
       try {
         tip = await this._persistence.readRef(ref);
-      } catch {
-        return [];
+      } 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' },
+        );
       }
       if (!tip) {
         return [];
@@ -196,6 +210,62 @@ export class TrustRecordService {
     return { valid: errors.length === 0, errors };
   }
 
+  /**
+   * Appends a trust record with automatic retry on CAS conflict.
+   *
+   * On E_TRUST_CAS_CONFLICT, re-reads the chain tip, rebuilds the record
+   * with the new prev pointer, re-signs if a signer is provided, and
+   * retries. This is the higher-level API callers should use when they
+   * want automatic convergence under concurrent appenders.
+   *
+   * @param {string} graphName
+   * @param {Record<string, unknown>} record - Complete signed trust record
+   * @param {Object} [options]
+   * @param {number} [options.maxRetries=3] - Maximum rebuild-and-retry attempts
+   * @param {((record: Record<string, unknown>) => Promise<Record<string, unknown>>)|null} [options.resign] - Function to re-sign a rebuilt record (null for unsigned)
+   * @param {boolean} [options.skipSignatureVerify=false] - Skip signature verification
+   * @returns {Promise<{commitSha: string, ref: string, attempts: number}>}
+   * @throws {TrustError} E_TRUST_CAS_EXHAUSTED if all retries fail
+   */
+  async appendRecordWithRetry(graphName, record, options = {}) {
+    const { maxRetries = 3, resign = null, skipSignatureVerify = false } = options;
+    let currentRecord = record;
+    let attempts = 0;
+
+    for (let i = 0; i <= maxRetries; i++) {
+      attempts++;
+      try {
+        const result = await this.appendRecord(graphName, currentRecord, { skipSignatureVerify });
+        return { ...result, attempts };
+      } catch (err) {
+        if (!(err instanceof TrustError) || err.code !== 'E_TRUST_CAS_CONFLICT') {
+          throw err;
+        }
+
+        if (i === maxRetries) {
+          throw new TrustError(
+            `Trust CAS exhausted after ${attempts} attempts (with retry)`,
+            { code: 'E_TRUST_CAS_EXHAUSTED' },
+          );
+        }
+
+        // Rebuild: re-read chain tip, update prev pointer
+        const freshTipRecordId = err.context?.actualTipRecordId ?? null;
+
+        // Update prev to the new chain tip's recordId
+        currentRecord = { ...currentRecord, prev: freshTipRecordId };
+
+        // Re-sign if signer is provided
+        if (resign) {
+          currentRecord = await resign(currentRecord);
+        }
+      }
+    }
+
+    // Unreachable
+    throw new TrustError('Trust CAS failed', { code: 'E_TRUST_CAS_EXHAUSTED' });
+  }
+
   /**
    * Validates that a record's signature envelope is structurally complete.
    *
@@ -246,7 +316,15 @@ export class TrustRecordService {
   }
 
   /**
-   * Persists a trust record as a Git commit.
+   * Persists a trust record as a Git commit with CAS retry.
+   *
+   * On transient CAS failures (ref unchanged, e.g. lock contention), retries
+   * up to MAX_CAS_ATTEMPTS total. On real concurrent appends (ref advanced),
+   * throws E_TRUST_CAS_CONFLICT so the caller can rebuild + re-sign the record.
+   *
+   * The record's prev, recordId, and signature form a cryptographic chain.
+   * Only the original signer can rebuild, so we never silently rebase.
+   *
    * @param {string} ref
    * @param {Record<string, unknown>} record
    * @param {string|null} parentSha - Resolved tip SHA (null for genesis)
@@ -273,9 +351,44 @@ export class TrustRecordService {
       message,
     });
 
-    // CAS update ref — fails atomically if a concurrent append changed the tip
-    await this._persistence.compareAndSwapRef(ref, commitSha, parentSha);
+    // CAS update ref with retry for transient failures
+    for (let attempt = 1; attempt <= MAX_CAS_ATTEMPTS; attempt++) {
+      try {
+        await this._persistence.compareAndSwapRef(ref, commitSha, parentSha);
+        return commitSha;
+      } catch {
+        // Read fresh tip to distinguish transient vs real conflict
+        const { tipSha: freshTipSha, recordId: freshRecordId } = await this._readTip(ref);
+
+        if (freshTipSha === parentSha) {
+          // Ref unchanged — transient failure (lock contention, I/O race).
+          // Retry the same CAS with same commit.
+          if (attempt === MAX_CAS_ATTEMPTS) {
+            throw new TrustError(
+              `Trust CAS exhausted after ${MAX_CAS_ATTEMPTS} attempts`,
+              { code: 'E_TRUST_CAS_EXHAUSTED' },
+            );
+          }
+          continue;
+        }
+
+        // Ref changed — real concurrent append. Our record's prev no longer
+        // matches the chain tip. The caller must rebuild, re-sign, and retry.
+        throw new TrustError(
+          `Trust CAS conflict: chain advanced from ${parentSha} to ${freshTipSha}`,
+          {
+            code: 'E_TRUST_CAS_CONFLICT',
+            context: {
+              expectedTipSha: parentSha,
+              actualTipSha: freshTipSha,
+              actualTipRecordId: freshRecordId,
+            },
+          },
+        );
+      }
+    }
 
-    return commitSha;
+    // Unreachable, but satisfies type checker
+    throw new TrustError('Trust CAS failed', { code: 'E_TRUST_CAS_EXHAUSTED' });
   }
 }

package/src/domain/warp/Writer.js

@@ -128,12 +128,14 @@ export class Writer {
       const commitMessage = await this._persistence.showNode(expectedOldHead);
       const kind = detectMessageKind(commitMessage);
       if (kind === 'patch') {
-        try {
-          const patchInfo = decodePatchMessage(commitMessage);
-          lamport = patchInfo.lamport + 1;
-        } catch {
-          // Malformed message, start at 1
+        const patchInfo = decodePatchMessage(commitMessage);
+        if (typeof patchInfo.lamport !== 'number' || !Number.isFinite(patchInfo.lamport) || patchInfo.lamport < 1) {
+          throw new WriterError(
+            'E_LAMPORT_CORRUPT',
+            `Malformed Lamport timestamp in commit ${expectedOldHead}: ${JSON.stringify(patchInfo.lamport)}`,
+          );
         }
+        lamport = patchInfo.lamport + 1;
       }
     }
 

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

@@ -9,12 +9,13 @@
 
 import { QueryError, E_NO_STATE_MSG } from './_internal.js';
 import { buildWriterRef, buildCheckpointRef, buildCoverageRef } from '../utils/RefLayout.js';
-import { createFrontier, updateFrontier } from '../services/Frontier.js';
+import { createFrontier, updateFrontier, frontierFingerprint } from '../services/Frontier.js';
 import { loadCheckpoint, create as createCheckpointCommit } from '../services/CheckpointService.js';
 import { decodePatchMessage, detectMessageKind, encodeAnchorMessage } from '../services/WarpMessageCodec.js';
 import { shouldRunGC, executeGC } from '../services/GCPolicy.js';
 import { collectGCMetrics } from '../services/GCMetrics.js';
 import { computeAppliedVV } from '../services/CheckpointSerializerV5.js';
+import { cloneStateV5 } from '../services/JoinReducer.js';
 
 /** @typedef {import('../types/WarpPersistence.js').CorePersistence} CorePersistence */
 
@@ -267,6 +268,12 @@ export async function _hasSchema1Patches() {
  * Post-materialize GC check. Warn by default; execute only when enabled.
  * GC failure never breaks materialize.
  *
+ * Uses clone-then-swap pattern for snapshot isolation (B63):
+ * 1. Snapshot frontier fingerprint before GC
+ * 2. Clone state, run executeGC on clone
+ * 3. Compare frontier after GC — if changed, discard clone + mark dirty
+ * 4. If unchanged, swap compacted clone into _cachedState
+ *
  * @this {import('../WarpGraph.js').default}
  * @param {import('../services/JoinReducer.js').WarpStateV5} state
  * @private
@@ -287,8 +294,35 @@ export function _maybeRunGC(state) {
     }
 
     if (/** @type {import('../services/GCPolicy.js').GCPolicy} */ (this._gcPolicy).enabled) {
-      const appliedVV = computeAppliedVV(state);
-      const result = executeGC(state, appliedVV);
+      // Snapshot frontier before GC
+      const preGcFingerprint = this._lastFrontier
+        ? frontierFingerprint(this._lastFrontier)
+        : null;
+
+      // Clone state so executeGC doesn't mutate live state
+      const clonedState = cloneStateV5(state);
+      const appliedVV = computeAppliedVV(clonedState);
+      const result = executeGC(clonedState, appliedVV);
+
+      // Check if frontier changed during GC (concurrent write)
+      const postGcFingerprint = this._lastFrontier
+        ? frontierFingerprint(this._lastFrontier)
+        : null;
+
+      if (preGcFingerprint !== postGcFingerprint) {
+        // Frontier changed — discard compacted state, mark dirty
+        this._stateDirty = true;
+        if (this._logger) {
+          this._logger.warn(
+            'Auto-GC discarded: frontier changed during compaction (concurrent write)',
+            { reasons, preGcFingerprint, postGcFingerprint },
+          );
+        }
+        return;
+      }
+
+      // Frontier unchanged — swap in compacted state
+      this._cachedState = clonedState;
       this._lastGCTime = this._clock.now();
       this._patchesSinceGC = 0;
       if (this._logger) {
@@ -348,11 +382,17 @@ export function maybeRunGC() {
  * Explicitly runs GC on the cached state.
  * Compacts tombstoned dots that are covered by the appliedVV.
  *
+ * Uses clone-then-swap pattern for snapshot isolation (B63):
+ * clones state, runs executeGC on clone, verifies frontier unchanged,
+ * then swaps in compacted clone. If frontier changed during GC,
+ * throws E_GC_STALE so the caller can retry after re-materializing.
+ *
  * **Requires a cached state.**
  *
  * @this {import('../WarpGraph.js').default}
  * @returns {{nodesCompacted: number, edgesCompacted: number, tombstonesRemoved: number, durationMs: number}}
  * @throws {QueryError} If no cached state exists (code: `E_NO_STATE`)
+ * @throws {QueryError} If frontier changed during GC (code: `E_GC_STALE`)
  *
  * @example
  * await graph.materialize();
@@ -368,13 +408,30 @@ export function runGC() {
       });
     }
 
-    // Compute appliedVV from current state
-    const appliedVV = computeAppliedVV(this._cachedState);
-
-    // Execute GC (mutates cached state)
-    const result = executeGC(this._cachedState, appliedVV);
+    // Snapshot frontier before GC
+    const preGcFingerprint = this._lastFrontier
+      ? frontierFingerprint(this._lastFrontier)
+      : null;
+
+    // Clone state so executeGC doesn't mutate live state until verified
+    const clonedState = cloneStateV5(this._cachedState);
+    const appliedVV = computeAppliedVV(clonedState);
+    const result = executeGC(clonedState, appliedVV);
+
+    // Verify frontier unchanged (concurrent write detection)
+    const postGcFingerprint = this._lastFrontier
+      ? frontierFingerprint(this._lastFrontier)
+      : null;
+
+    if (preGcFingerprint !== postGcFingerprint) {
+      throw new QueryError(
+        'GC aborted: frontier changed during compaction (concurrent write detected)',
+        { code: 'E_GC_STALE' },
+      );
+    }
 
-    // Update GC tracking
+    // Frontier unchanged — swap in compacted state
+    this._cachedState = clonedState;
     this._lastGCTime = this._clock.now();
     this._patchesSinceGC = 0;
 

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

@@ -242,6 +242,9 @@ export async function materialize(options) {
  * @private
  */
 export async function _materializeGraph() {
+  if (!this._stateDirty && this._materializedGraph) {
+    return this._materializedGraph;
+  }
   const state = await this.materialize();
   if (!this._materializedGraph || this._materializedGraph.state !== state) {
     await this._setMaterializedState(/** @type {import('../services/JoinReducer.js').WarpStateV5} */ (state));

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

@@ -167,6 +167,7 @@ export function _buildView(state, stateHash, diff) {
     this._propertyReader = result.propertyReader;
     this._cachedViewHash = stateHash;
     this._cachedIndexTree = result.tree;
+    this._indexDegraded = false;
 
     const provider = new BitmapNeighborProvider({ logicalIndex: result.logicalIndex });
     if (this._materializedGraph) {
@@ -176,6 +177,7 @@ export function _buildView(state, stateHash, diff) {
     this._logger?.warn('[warp] index build failed, falling back to linear scan', {
       error: /** @type {Error} */ (err).message,
     });
+    this._indexDegraded = true;
     this._logicalIndex = null;
     this._propertyReader = null;
     this._cachedIndexTree = null;

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

@@ -530,6 +530,14 @@ export function join(otherState) {
   // Update cached state
   this._cachedState = mergedState;
 
+  // Invalidate derived caches (C1) — join changes underlying state
+  this._materializedGraph = null;
+  this._logicalIndex = null;
+  this._propertyReader = null;
+  this._cachedViewHash = null;
+  this._cachedIndexTree = null;
+  this._stateDirty = true;
+
   return { state: mergedState, receipt };
 }
 

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

@@ -319,9 +319,9 @@ export function query() {
  */
 export async function observer(name, config) {
   /** @param {unknown} m */
-  const isValidMatch = (m) => typeof m === 'string' || (Array.isArray(m) && m.every(/** @param {unknown} i */ i => typeof i === 'string'));
+  const isValidMatch = (m) => typeof m === 'string' || (Array.isArray(m) && m.length > 0 && m.every(/** @param {unknown} i */ i => typeof i === 'string'));
   if (!config || !isValidMatch(config.match)) {
-    throw new Error('observer config.match must be a string or array of strings');
+    throw new Error('observer config.match must be a non-empty string or non-empty array of strings');
   }
   await this._ensureFreshState();
   return new ObserverView({ name, config, graph: this });
@@ -332,11 +332,11 @@ export async function observer(name, config) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {Object} configA - Observer configuration for A
- * @param {string} configA.match - Glob pattern for visible nodes
+ * @param {string|string[]} configA.match - Glob pattern(s) for visible nodes
  * @param {string[]} [configA.expose] - Property keys to include
  * @param {string[]} [configA.redact] - Property keys to exclude
  * @param {Object} configB - Observer configuration for B
- * @param {string} configB.match - Glob pattern for visible nodes
+ * @param {string|string[]} configB.match - Glob pattern(s) for visible nodes
  * @param {string[]} [configB.expose] - Property keys to include
  * @param {string[]} [configB.redact] - Property keys to exclude
  * @returns {Promise<{cost: number, breakdown: {nodeLoss: number, edgeLoss: number, propLoss: number}}>}

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

@@ -6,6 +6,7 @@
  */
 
 import { diffStates, isEmptyDiff } from '../services/StateDiff.js';
+import { matchGlob } from '../utils/matchGlob.js';
 
 /**
  * Subscribes to graph changes.
@@ -101,13 +102,13 @@ export function subscribe({ onChange, onError, replay = false }) {
  * be at least 1000ms.
  *
  * @this {import('../WarpGraph.js').default}
- * @param {string} pattern - Glob pattern (e.g., 'user:*', 'order:123', '*')
+ * @param {string|string[]} pattern - Glob pattern(s) (e.g., 'user:*', 'order:123', '*')
  * @param {Object} options - Watch options
  * @param {(diff: import('../services/StateDiff.js').StateDiffResult) => void} options.onChange - Called with filtered diff when matching changes occur
  * @param {(error: Error) => void} [options.onError] - Called if onChange throws an error
  * @param {number} [options.poll] - Poll interval in ms (min 1000); checks frontier and auto-materializes
  * @returns {{unsubscribe: () => void}} Subscription handle
- * @throws {Error} If pattern is not a string
+ * @throws {Error} If pattern is not a string or array of strings
  * @throws {Error} If onChange is not a function
  * @throws {Error} If poll is provided but less than 1000
  *
@@ -130,31 +131,22 @@ export function subscribe({ onChange, onError, replay = false }) {
  * unsubscribe();
  */
 export function watch(pattern, { onChange, onError, poll }) {
-  if (typeof pattern !== 'string') {
-    throw new Error('pattern must be a string');
+  const isValidPattern = (/** @type {string|string[]} */ p) => typeof p === 'string' || (Array.isArray(p) && p.length > 0 && p.every(i => typeof i === 'string'));
+  if (!isValidPattern(pattern)) {
+    throw new Error('pattern must be a non-empty string or non-empty array of strings');
   }
   if (typeof onChange !== 'function') {
     throw new Error('onChange must be a function');
   }
   if (poll !== undefined) {
-    if (typeof poll !== 'number' || poll < 1000) {
-      throw new Error('poll must be a number >= 1000');
+    if (typeof poll !== 'number' || !Number.isFinite(poll) || poll < 1000) {
+      throw new Error('poll must be a finite number >= 1000');
     }
   }
 
-  // Pattern matching: same logic as QueryBuilder.match()
-  // Pre-compile pattern matcher once for performance
+  // Pattern matching logic
   /** @type {(nodeId: string) => boolean} */
-  let matchesPattern;
-  if (pattern === '*') {
-    matchesPattern = () => true;
-  } else if (pattern.includes('*')) {
-    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
-    const regex = new RegExp(`^${escaped.replace(/\*/g, '.*')}$`);
-    matchesPattern = (/** @type {string} */ nodeId) => regex.test(nodeId);
-  } else {
-    matchesPattern = (/** @type {string} */ nodeId) => nodeId === pattern;
-  }
+  const matchesPattern = (nodeId) => matchGlob(pattern, nodeId);
 
   // Filtered onChange that only passes matching changes
   const filteredOnChange = (/** @type {import('../services/StateDiff.js').StateDiffResult} */ diff) => {
@@ -194,7 +186,7 @@ export function watch(pattern, { onChange, onError, poll }) {
   /** @type {ReturnType<typeof setInterval>|null} */
   let pollIntervalId = null;
   let pollInFlight = false;
-  if (poll) {
+  if (poll !== undefined) {
     pollIntervalId = setInterval(() => {
       if (pollInFlight) {
         return;

package/src/infrastructure/adapters/GitGraphAdapter.js

@@ -575,8 +575,8 @@ export default class GitGraphAdapter extends GraphPersistencePort {
   async compareAndSwapRef(ref, newOid, expectedOid) {
     this._validateRef(ref);
     this._validateOid(newOid);
-    // null means "ref must not exist" → use zero OID
-    const oldArg = expectedOid || '0'.repeat(newOid.length);
+    // null means "ref must not exist" → use zero OID (always 40 chars for SHA-1)
+    const oldArg = expectedOid || '0'.repeat(40);
     if (expectedOid) {
       this._validateOid(expectedOid);
     }