@git-stunts/git-warp 12.1.0 → 12.2.1

package/src/domain/services/SyncProtocol.js

@@ -37,8 +37,10 @@
  */
 
 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, isKnownOp } from './JoinReducer.js';
+import SchemaUnsupportedError from '../errors/SchemaUnsupportedError.js';
 import { cloneFrontier, updateFrontier } from './Frontier.js';
 import { vvDeserialize } from '../crdt/VersionVector.js';
 
@@ -80,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.
  *
@@ -251,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
@@ -267,11 +297,9 @@ export function computeSyncDelta(localFrontier, remoteFrontier) {
       newWritersForRemote.push(writerId);
     } else if (remoteSha !== localSha) {
       // Different heads - remote might need patches from its head to local head
-      // Only add if not already in needFromRemote (avoid double-counting)
-      // This handles the case where local is ahead of remote
-      if (!needFromRemote.has(writerId)) {
-        needFromLocal.set(writerId, { from: remoteSha, to: localSha });
-      }
+      // Always add both directions — ancestry is verified during loadPatchRange()
+      // which will throw E_SYNC_DIVERGENCE if neither side descends from the other (S3)
+      needFromLocal.set(writerId, { from: remoteSha, to: localSha });
     }
   }
 
@@ -315,6 +343,8 @@ export function computeSyncDelta(localFrontier, remoteFrontier) {
  *   - `writerId`: The writer who created this patch
  *   - `sha`: The commit SHA this patch came from (for frontier updates)
  *   - `patch`: The decoded patch object with ops and context
+ * @property {Array<{writerId: string, reason: string, localSha: string, remoteSha: string|null}>} [skippedWriters] - Writers that were skipped during sync
+ *   (e.g. due to trust gate filtering, divergence, or missing refs)
  */
 
 /**
@@ -338,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),
   };
 }
 
@@ -375,6 +398,7 @@ export function createSyncRequest(frontier) {
  * @param {string} graphName - Graph name for error messages and logging
  * @param {Object} [options]
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
+ * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for divergence warnings
  * @returns {Promise<SyncResponse>} Response containing local frontier and patches.
  *   Patches are ordered chronologically within each writer.
  * @throws {Error} If patch loading fails for reasons other than divergence
@@ -388,18 +412,44 @@ export function createSyncRequest(frontier) {
  *   res.json(response);
  * });
  */
-export async function processSyncRequest(request, localFrontier, persistence, graphName, { codec } = /** @type {{ codec?: import('../../ports/CodecPort.js').default }} */ ({})) {
-  // Convert incoming frontier from object to Map
-  const remoteFrontier = new Map(Object.entries(request.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;
+
+  const remoteFrontier = objectToFrontier(request.frontier);
 
   // Compute what the requester needs
   const delta = computeSyncDelta(remoteFrontier, localFrontier);
 
   // Load patches that the requester needs (from local to requester)
   const patches = [];
+  /** @type {Array<{writerId: string, reason: string, localSha: string, remoteSha: string|null}>} */
+  const skippedWriters = [];
 
   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,
@@ -413,26 +463,32 @@ export async function processSyncRequest(request, localFrontier, persistence, gr
         patches.push({ writerId, sha, patch });
       }
     } catch (err) {
-      // If we detect divergence, skip this writer
-      // The requester may need to handle this separately
+      // If we detect divergence, log and skip this writer (B65).
+      // The requester will not receive patches for this writer.
       if ((err instanceof Error && 'code' in err && /** @type {{ code: string }} */ (err).code === 'E_SYNC_DIVERGENCE') || (err instanceof Error && err.message?.includes('Divergence detected'))) {
+        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;
       }
       throw err;
     }
   }
 
-  // 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,
   };
 }
 
@@ -484,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)) {
@@ -499,10 +558,19 @@ 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).
+      // This prevents silent data loss when a newer writer sends ops we
+      // don't recognise — fail closed rather than silently ignoring.
+      for (const op of normalizedPatch.ops) {
+        if (!isKnownOp(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
+      // 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);
@@ -590,15 +658,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/SyncTrustGate.js

@@ -0,0 +1,146 @@
+/**
+ * SyncTrustGate -- Encapsulates trust evaluation for sync operations.
+ *
+ * Evaluates whether inbound patch authors are trusted according to the
+ * trust record chain. Used by SyncController to validate HTTP sync
+ * responses before applying patches.
+ *
+ * Trust-gates on `writersApplied` (patch authors being ingested), not
+ * frontier keys (which are claims, not effects).
+ *
+ * @module domain/services/SyncTrustGate
+ * @see B1 -- Signed sync ingress
+ */
+
+import nullLogger from '../utils/nullLogger.js';
+
+/**
+ * @typedef {'enforce'|'log-only'|'off'} TrustMode
+ */
+
+/**
+ * @typedef {Object} TrustGateResult
+ * @property {boolean} allowed - Whether the writers are trusted
+ * @property {string[]} untrustedWriters - Writers that failed trust evaluation
+ * @property {string} verdict - Human-readable verdict
+ */
+
+/** @type {() => TrustGateResult} */
+const PASS = () => ({ allowed: true, untrustedWriters: [], verdict: 'pass' });
+
+export default class SyncTrustGate {
+  /**
+   * @param {Object} options
+   * @param {{evaluateWriters: (writerIds: string[]) => Promise<{trusted: Set<string>}>}} [options.trustEvaluator] - Trust evaluator instance
+   * @param {TrustMode} [options.trustMode='off'] - Trust enforcement mode
+   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger
+   */
+  constructor({ trustEvaluator, trustMode = 'off', logger } = {}) {
+    this._evaluator = trustEvaluator || null;
+    this._mode = trustMode;
+    this._logger = logger || nullLogger;
+  }
+
+  /**
+   * Evaluates whether the given patch writers are trusted.
+   *
+   * @param {string[]} writerIds - Writer IDs from patches being applied
+   * @param {Object} [context] - Additional context for logging
+   * @param {string} [context.graphName] - Graph name
+   * @param {string} [context.peerId] - Remote peer identity (if authenticated)
+   * @returns {Promise<TrustGateResult>}
+   */
+  async evaluate(writerIds, context = {}) {
+    if (this._mode === 'off' || !this._evaluator) {
+      return { allowed: true, untrustedWriters: [], verdict: 'trust_disabled' };
+    }
+    if (writerIds.length === 0) {
+      return { allowed: true, untrustedWriters: [], verdict: 'no_writers' };
+    }
+
+    try {
+      const result = await this._evaluator.evaluateWriters(writerIds);
+      const untrusted = writerIds.filter((id) => !result.trusted.has(id));
+      return this._decide(untrusted, writerIds, context);
+    } catch (err) {
+      return this._handleError(err, writerIds, context);
+    }
+  }
+
+  /**
+   * Decides the gate result based on untrusted writers and mode.
+   * @param {string[]} untrusted
+   * @param {string[]} writerIds
+   * @param {Object} context
+   * @returns {TrustGateResult}
+   * @private
+   */
+  _decide(untrusted, writerIds, context) {
+    this._logger.info('Trust gate decision', {
+      code: 'SYNC_TRUST_GATE',
+      mode: this._mode,
+      writersApplied: writerIds,
+      untrustedWriters: untrusted,
+      verdict: untrusted.length === 0 ? 'pass' : 'fail',
+      ...context,
+    });
+
+    if (untrusted.length === 0) {
+      return PASS();
+    }
+
+    if (this._mode === 'enforce') {
+      this._logger.warn('Trust gate rejected untrusted writers', {
+        code: 'SYNC_TRUST_REJECTED',
+        untrustedWriters: untrusted,
+        ...context,
+      });
+      return { allowed: false, untrustedWriters: untrusted, verdict: 'rejected' };
+    }
+
+    this._logger.warn('Trust gate: untrusted writers allowed (log-only mode)', {
+      code: 'SYNC_TRUST_WARN',
+      untrustedWriters: untrusted,
+      ...context,
+    });
+    return { allowed: true, untrustedWriters: untrusted, verdict: 'warn_allowed' };
+  }
+
+  /**
+   * Handles trust evaluation errors with fail-open/fail-closed semantics.
+   * @param {unknown} err
+   * @param {string[]} writerIds
+   * @param {Object} context
+   * @returns {TrustGateResult}
+   * @private
+   */
+  _handleError(err, writerIds, context) {
+    this._logger.error('Trust gate evaluation failed', {
+      code: 'SYNC_TRUST_ERROR',
+      error: err instanceof Error ? err.message : String(err),
+      ...context,
+    });
+
+    if (this._mode === 'enforce') {
+      return { allowed: false, untrustedWriters: writerIds, verdict: 'error_rejected' };
+    }
+    return { allowed: true, untrustedWriters: [], verdict: 'error_allowed' };
+  }
+
+  /**
+   * Extracts writer IDs from patches in a sync response.
+   * These are the actual data authors being ingested — the trust target.
+   *
+   * @param {Array<{writerId: string}>} patches - Patches from sync response
+   * @returns {string[]} Deduplicated writer IDs
+   */
+  static extractWritersFromPatches(patches) {
+    const writers = new Set();
+    for (const { writerId } of patches) {
+      if (writerId) {
+        writers.add(writerId);
+      }
+    }
+    return [...writers];
+  }
+}

package/src/domain/services/TranslationCost.js

@@ -182,10 +182,10 @@ function computePropLoss(state, { nodesA, nodesBSet, configA, configB }) {
  */
 export function computeTranslationCost(configA, configB, state) {
   /** @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 (!configA || !isValidMatch(configA.match) ||
       !configB || !isValidMatch(configB.match)) {
-    throw new Error('configA.match and configB.match must be strings or arrays of strings');
+    throw new Error('configA.match and configB.match must be non-empty strings or non-empty arrays of strings');
   }
   const allNodes = [...orsetElements(state.nodeAlive)];
   const nodesA = allNodes.filter((id) => matchGlob(configA.match, id));

package/src/domain/trust/TrustRecordService.js

@@ -14,11 +14,22 @@ 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)
  */
 
+/**
+ * @typedef {{ok: true, records: Array<Record<string, unknown>>} | {ok: false, error: Error}} ReadRecordsResult
+ */
+
 export class TrustRecordService {
   /**
    * @param {Object} options
@@ -95,48 +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 {
-        return [];
-      }
+    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;
-
-    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),
-      ));
+      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),
+        ));
 
-      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)),
+      };
+    }
   }
 
   /**
@@ -196,6 +224,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 +330,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 +365,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' });
   }
 }