@git-stunts/git-warp 10.8.0 → 11.3.3

package/src/domain/trust/schemas.js

@@ -0,0 +1,160 @@
+/**
+ * Trust V1 Zod schemas.
+ *
+ * Schemas for trust record envelope, per-type subjects, policy config,
+ * and assessment output contract. These are the canonical validation
+ * boundary — all trust data passes through these schemas.
+ *
+ * @module domain/trust/schemas
+ * @see docs/specs/TRUST_V1_CRYPTO.md Sections 8–10, 14
+ */
+
+import { z } from 'zod';
+
+// ── Primitives ──────────────────────────────────────────────────────────
+
+export const KeyIdSchema = z.string().regex(
+  /^ed25519:[a-f0-9]{64}$/,
+  'keyId must be "ed25519:" followed by 64 hex chars',
+);
+
+export const RecordIdSchema = z.string().regex(
+  /^[a-f0-9]{64}$/,
+  'recordId must be 64 lowercase hex chars',
+);
+
+export const RecordTypeSchema = z.enum([
+  'KEY_ADD',
+  'KEY_REVOKE',
+  'WRITER_BIND_ADD',
+  'WRITER_BIND_REVOKE',
+]);
+
+// ── Signature ───────────────────────────────────────────────────────────
+
+export const TrustSignatureSchema = z.object({
+  alg: z.literal('ed25519'),
+  sig: z.string().min(1, 'signature must not be empty'),
+});
+
+// ── Per-type subject schemas ────────────────────────────────────────────
+
+export const KeyAddSubjectSchema = z.object({
+  keyId: KeyIdSchema,
+  publicKey: z.string().min(1, 'publicKey must not be empty'),
+});
+
+export const KeyRevokeSubjectSchema = z.object({
+  keyId: KeyIdSchema,
+  reasonCode: z.enum(['KEY_COMPROMISE', 'KEY_ROLLOVER', 'OPERATOR_REQUEST']),
+});
+
+export const WriterBindAddSubjectSchema = z.object({
+  writerId: z.string().trim().min(1),
+  keyId: KeyIdSchema,
+});
+
+export const WriterBindRevokeSubjectSchema = z.object({
+  writerId: z.string().trim().min(1),
+  keyId: KeyIdSchema,
+  reasonCode: z.enum(['ACCESS_REMOVED', 'ROTATION', 'KEY_REVOKED']),
+});
+
+// ── Trust record envelope ───────────────────────────────────────────────
+
+export const TrustRecordSchema = z.object({
+  schemaVersion: z.literal(1),
+  recordType: RecordTypeSchema,
+  recordId: RecordIdSchema,
+  issuerKeyId: KeyIdSchema,
+  issuedAt: z.string().datetime({ offset: false }),
+  prev: RecordIdSchema.nullable(),
+  subject: z.record(z.unknown()),
+  meta: z.record(z.unknown()).optional().default({}),
+  signature: TrustSignatureSchema,
+}).superRefine((record, ctx) => {
+  /** @param {string} message */
+  const addIssue = (message) =>
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message });
+
+  switch (record.recordType) {
+    case 'KEY_ADD': {
+      const r = KeyAddSubjectSchema.safeParse(record.subject);
+      if (!r.success) {
+        addIssue(`Invalid KEY_ADD subject: ${r.error.message}`);
+      } else {
+        record.subject = r.data;
+      }
+      break;
+    }
+    case 'KEY_REVOKE': {
+      const r = KeyRevokeSubjectSchema.safeParse(record.subject);
+      if (!r.success) {
+        addIssue(`Invalid KEY_REVOKE subject: ${r.error.message}`);
+      } else {
+        record.subject = r.data;
+      }
+      break;
+    }
+    case 'WRITER_BIND_ADD': {
+      const r = WriterBindAddSubjectSchema.safeParse(record.subject);
+      if (!r.success) {
+        addIssue(`Invalid WRITER_BIND_ADD subject: ${r.error.message}`);
+      } else {
+        record.subject = r.data;
+      }
+      break;
+    }
+    case 'WRITER_BIND_REVOKE': {
+      const r = WriterBindRevokeSubjectSchema.safeParse(record.subject);
+      if (!r.success) {
+        addIssue(`Invalid WRITER_BIND_REVOKE subject: ${r.error.message}`);
+      } else {
+        record.subject = r.data;
+      }
+      break;
+    }
+    default:
+      addIssue(`Unsupported recordType: ${/** @type {string} */ (record.recordType)}`);
+  }
+});
+
+// ── Policy config ───────────────────────────────────────────────────────
+
+export const TrustPolicySchema = z.object({
+  schemaVersion: z.literal(1),
+  mode: z.enum(['warn', 'enforce']),
+  writerPolicy: z.literal('all_writers_must_be_trusted'),
+});
+
+// ── Assessment output contract ──────────────────────────────────────────
+
+export const TrustExplanationSchema = z.object({
+  writerId: z.string().min(1),
+  trusted: z.boolean(),
+  reasonCode: z.string().min(1),
+  reason: z.string().min(1),
+});
+
+export const EvidenceSummarySchema = z.object({
+  recordsScanned: z.number().int().nonnegative(),
+  activeKeys: z.number().int().nonnegative(),
+  revokedKeys: z.number().int().nonnegative(),
+  activeBindings: z.number().int().nonnegative(),
+  revokedBindings: z.number().int().nonnegative(),
+});
+
+export const TrustAssessmentSchema = z.object({
+  trustSchemaVersion: z.literal(1),
+  mode: z.literal('signed_evidence_v1'),
+  trustVerdict: z.enum(['pass', 'fail', 'not_configured']),
+  trust: z.object({
+    status: z.enum(['configured', 'pinned', 'error', 'not_configured']),
+    source: z.enum(['ref', 'cli_pin', 'env_pin', 'none']),
+    sourceDetail: z.string().nullable(),
+    evaluatedWriters: z.array(z.string()),
+    untrustedWriters: z.array(z.string()),
+    explanations: z.array(TrustExplanationSchema),
+    evidenceSummary: EvidenceSummarySchema,
+  }),
+});

package/src/domain/trust/verdict.js

@@ -0,0 +1,42 @@
+/**
+ * Trust V1 verdict derivation.
+ *
+ * Deterministic mapping from TrustAssessment to verdict string.
+ * This is the single source of truth for verdict logic.
+ *
+ * @module domain/trust/verdict
+ * @see docs/specs/TRUST_V1_CRYPTO.md Section 13
+ */
+
+/**
+ * @typedef {Object} TrustAssessmentV1
+ * @property {'not_configured'|'configured'|'pinned'|'error'} status
+ * @property {string[]} untrustedWriters
+ */
+
+/**
+ * Derives the trust verdict from a V1 trust assessment.
+ *
+ * Mapping (evaluated in order):
+ * - status 'not_configured' → 'not_configured'
+ * - status 'error'          → 'fail'
+ * - untrustedWriters.length > 0 → 'fail'
+ * - otherwise               → 'pass'
+ *
+ * V1 has no 'degraded' verdict — untrusted writers are a hard failure.
+ *
+ * @param {TrustAssessmentV1} trust
+ * @returns {'pass'|'fail'|'not_configured'}
+ */
+export function deriveTrustVerdict(trust) {
+  if (trust.status === 'not_configured') {
+    return 'not_configured';
+  }
+  if (trust.status === 'error') {
+    return 'fail';
+  }
+  if (Array.isArray(trust.untrustedWriters) && trust.untrustedWriters.length > 0) {
+    return 'fail';
+  }
+  return 'pass';
+}

package/src/domain/types/TickReceipt.js

@@ -67,7 +67,7 @@ function validateOp(op, index) {
     throw new Error(`ops[${index}] must be an object`);
   }
 
-  const entry = /** @type {Record<string, *>} */ (op);
+  const entry = /** @type {Record<string, unknown>} */ (op);
   validateOpType(entry.op, index);
   validateOpTarget(entry.target, index);
   validateOpResult(entry.result, index);

package/src/domain/types/WarpErrors.js

@@ -0,0 +1,45 @@
+/**
+ * Error narrowing utilities for catch clauses.
+ *
+ * TypeScript catch variables are `unknown`. These helpers provide
+ * type-safe narrowing without wildcard casts.
+ *
+ * @module domain/types/WarpErrors
+ */
+
+/**
+ * Narrows an unknown value to an Error instance.
+ * @param {unknown} err
+ * @returns {err is Error}
+ */
+export function isError(err) {
+  return err instanceof Error;
+}
+
+/**
+ * Checks if an unknown value has a string `code` property.
+ * @param {unknown} err
+ * @returns {err is {code: string, message?: string, name?: string}}
+ */
+export function hasErrorCode(err) {
+  return (
+    typeof err === 'object' &&
+    err !== null &&
+    'code' in err &&
+    typeof (/** @type {Record<string, unknown>} */ (err)).code === 'string'
+  );
+}
+
+/**
+ * Narrows an unknown value to an object with a string `message` property.
+ * @param {unknown} err
+ * @returns {err is {message: string}}
+ */
+export function hasMessage(err) {
+  return (
+    typeof err === 'object' &&
+    err !== null &&
+    'message' in err &&
+    typeof (/** @type {Record<string, unknown>} */ (err)).message === 'string'
+  );
+}

package/src/domain/types/WarpOptions.js

@@ -0,0 +1,29 @@
+/**
+ * Shared options types for warp methods.
+ * @module domain/types/WarpOptions
+ */
+
+/**
+ * @typedef {Object} ServeOptions
+ * @property {number} port
+ * @property {string} [host='127.0.0.1']
+ * @property {string} [path='/sync']
+ * @property {number} [maxRequestBytes=4194304]
+ * @property {import('../../ports/HttpServerPort.js').default} httpPort
+ * @property {{keys: Record<string, string>, mode?: 'enforce'|'log-only', crypto?: import('../../ports/CryptoPort.js').default, logger?: import('../../ports/LoggerPort.js').default, wallClockMs?: () => number}} [auth]
+ * @property {string[]} [allowedWriters]
+ */
+
+/**
+ * @typedef {Object} MaterializeOptions
+ * @property {boolean} [receipts]
+ * @property {number|null} [ceiling]
+ */
+
+/**
+ * @typedef {Object} PatchCommitEvent
+ * @property {unknown} [patch]
+ * @property {string} sha
+ */
+
+export {};

package/src/domain/types/WarpPersistence.js

@@ -0,0 +1,41 @@
+/**
+ * Role-specific persistence port types.
+ *
+ * Instead of casting to `any` when accessing persistence methods,
+ * use these narrow types to document which port methods are actually needed.
+ *
+ * NOTE: CommitPort, BlobPort, TreePort, and RefPort each contain both
+ * read and write methods. True read/write separation would require
+ * splitting each port, which is deferred. For now, the role-named
+ * aliases below are identical — they exist to document *intent* at
+ * each call site, not to enforce access restrictions.
+ *
+ * @module domain/types/WarpPersistence
+ */
+
+/**
+ * Full persistence port — commit + blob + tree + ref + config.
+ * @typedef {import('../../ports/GraphPersistencePort.js').default} WarpPersistence
+ */
+
+/**
+ * Commit + blob + tree + ref (no config).
+ * Used by sync readers, checkpoint creators, patch writers, and
+ * materialize paths. Identical to CheckpointPersistence by design
+ * (see module-level note).
+ * @typedef {import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default & import('../../ports/RefPort.js').default} CorePersistence
+ */
+
+/**
+ * Ref-only persistence — ref reads, writes, CAS, listing.
+ * @typedef {import('../../ports/RefPort.js').default} RefPersistence
+ */
+
+/**
+ * Index storage — blob reads/writes, tree reads/writes, ref reads/writes.
+ * Matches the dynamically-composed IndexStoragePort interface.
+ * @typedef {import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default & import('../../ports/RefPort.js').default} IndexStorage
+ */
+
+// Export nothing at runtime — types only
+export {};

package/src/domain/types/WarpTypes.js

@@ -35,7 +35,7 @@
  * Inline value reference - value stored directly in the operation
  * @typedef {Object} ValueRefInline
  * @property {'inline'} type - Discriminator for inline values
- * @property {*} value - The actual value (any JSON-serializable type)
+ * @property {unknown} value - The actual value (any JSON-serializable type)
  */
 
 /**
@@ -70,7 +70,7 @@
 
 /**
  * Creates an inline value reference
- * @param {*} value - The value to store inline
+ * @param {unknown} value - The value to store inline
  * @returns {ValueRefInline} Inline value reference
  */
 export function createInlineValue(value) {

package/src/domain/types/WarpTypesV2.js

@@ -80,7 +80,7 @@
  * @property {'PropSet'} type - Operation type discriminator
  * @property {NodeId} node - Node ID to set property on
  * @property {string} key - Property key
- * @property {*} value - Property value (any JSON-serializable type)
+ * @property {unknown} value - Property value (any JSON-serializable type)
  */
 
 /**
@@ -156,7 +156,7 @@ export function createEdgeRemoveV2(from, to, label, observedDots) {
  * Creates a PropSet operation (no dot - uses EventId)
  * @param {NodeId} node - Node ID to set property on
  * @param {string} key - Property key
- * @param {*} value - Property value (any JSON-serializable type)
+ * @param {unknown} value - Property value (any JSON-serializable type)
  * @returns {OpV2PropSet} PropSet operation
  */
 export function createPropSetV2(node, key, value) {

package/src/domain/types/git-cas.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Type stub for @git-stunts/git-cas.
+ *
+ * Provides just enough shape for CasSeekCacheAdapter to typecheck.
+ */
+declare module '@git-stunts/git-cas' {
+  interface CasStore {
+    put(key: string, value: Uint8Array): Promise<string>;
+    get(key: string): Promise<Uint8Array | null>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+  }
+
+  interface ContentAddressableStore {
+    createCbor(opts: { plumbing: unknown }): CasStore;
+  }
+
+  const ContentAddressableStore: ContentAddressableStore;
+  export default ContentAddressableStore;
+}

package/src/domain/utils/MinHeap.js

@@ -3,20 +3,21 @@
  * Items with lowest priority are extracted first.
  *
  * @class MinHeap
+ * @template T
  */
 class MinHeap {
   /**
    * Creates an empty MinHeap.
    */
   constructor() {
-    /** @type {Array<{item: *, priority: number}>} */
+    /** @type {Array<{item: T, priority: number}>} */
     this.heap = [];
   }
 
   /**
    * Insert an item with given priority.
    *
-   * @param {*} item - The item to insert
+   * @param {T} item - The item to insert
    * @param {number} priority - Priority value (lower = higher priority)
    * @returns {void}
    */
@@ -28,14 +29,14 @@ class MinHeap {
   /**
    * Extract and return the item with minimum priority.
    *
-   * @returns {*} The item with lowest priority, or undefined if empty
+   * @returns {T | undefined} The item with lowest priority, or undefined if empty
    */
   extractMin() {
     if (this.heap.length === 0) { return undefined; }
-    if (this.heap.length === 1) { return /** @type {{item: *, priority: number}} */ (this.heap.pop()).item; }
+    if (this.heap.length === 1) { return /** @type {{item: T, priority: number}} */ (this.heap.pop()).item; }
 
     const min = this.heap[0];
-    this.heap[0] = /** @type {{item: *, priority: number}} */ (this.heap.pop());
+    this.heap[0] = /** @type {{item: T, priority: number}} */ (this.heap.pop());
     this._bubbleDown(0);
     return min.item;
   }

package/src/domain/utils/RefLayout.js

@@ -10,6 +10,8 @@
  * - refs/warp/<graph>/coverage/head
  * - refs/warp/<graph>/cursor/active
  * - refs/warp/<graph>/cursor/saved/<name>
+ * - refs/warp/<graph>/audit/<writer_id>
+ * - refs/warp/<graph>/trust/records
  *
  * @module domain/utils/RefLayout
  */
@@ -291,6 +293,43 @@ export function buildCursorSavedPrefix(graphName) {
   return `${REF_PREFIX}/${graphName}/cursor/saved/`;
 }
 
+/**
+ * Builds the audit ref path for the given graph and writer ID.
+ *
+ * Audit refs track the latest audit commit for each writer, forming
+ * an independent chain of tamper-evident receipts per writer.
+ *
+ * @param {string} graphName - The name of the graph
+ * @param {string} writerId - The writer's unique identifier
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/audit/<writerId>`
+ * @throws {Error} If graphName or writerId is invalid
+ *
+ * @example
+ * buildAuditRef('events', 'alice');
+ * // => 'refs/warp/events/audit/alice'
+ */
+export function buildAuditRef(graphName, writerId) {
+  validateGraphName(graphName);
+  validateWriterId(writerId);
+  return `${REF_PREFIX}/${graphName}/audit/${writerId}`;
+}
+
+/**
+ * Builds the audit ref prefix for listing all audit writers of a graph.
+ *
+ * @param {string} graphName - The name of the graph
+ * @returns {string} The ref prefix, e.g. `refs/warp/<graphName>/audit/`
+ * @throws {Error} If graphName is invalid
+ *
+ * @example
+ * buildAuditPrefix('events');
+ * // => 'refs/warp/events/audit/'
+ */
+export function buildAuditPrefix(graphName) {
+  validateGraphName(graphName);
+  return `${REF_PREFIX}/${graphName}/audit/`;
+}
+
 /**
  * Builds the seek cache ref path for the given graph.
  *
@@ -310,6 +349,26 @@ export function buildSeekCacheRef(graphName) {
   return `${REF_PREFIX}/${graphName}/seek-cache`;
 }
 
+/**
+ * Builds the trust record chain ref path for the given graph.
+ *
+ * The trust record ref points to the tip commit of the trust record
+ * chain — an append-only sequence of signed trust records (key adds,
+ * key revokes, writer bindings).
+ *
+ * @param {string} graphName - The name of the graph
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/trust/records`
+ * @throws {Error} If graphName is invalid
+ *
+ * @example
+ * buildTrustRecordRef('events');
+ * // => 'refs/warp/events/trust/records'
+ */
+export function buildTrustRecordRef(graphName) {
+  validateGraphName(graphName);
+  return `${REF_PREFIX}/${graphName}/trust/records`;
+}
+
 // -----------------------------------------------------------------------------
 // Parsers
 // -----------------------------------------------------------------------------

package/src/domain/utils/canonicalStringify.js

@@ -7,7 +7,7 @@
  * - Array elements that are undefined/function/symbol become "null"
  * - Object properties with undefined/function/symbol values are omitted
  *
- * @param {*} value - Any JSON-serializable value
+ * @param {unknown} value - Any JSON-serializable value
  * @returns {string} Canonical JSON string with sorted keys
  */
 export function canonicalStringify(value) {
@@ -28,14 +28,15 @@ export function canonicalStringify(value) {
     return `[${elements.join(',')}]`;
   }
   if (typeof value === 'object') {
+    const obj = /** @type {Record<string, unknown>} */ (value);
     // Filter out keys with undefined/function/symbol values, then sort
-    const keys = Object.keys(value)
+    const keys = Object.keys(obj)
       .filter(k => {
-        const v = value[k];
+        const v = obj[k];
         return v !== undefined && typeof v !== 'function' && typeof v !== 'symbol';
       })
       .sort();
-    const pairs = keys.map(k => `${JSON.stringify(k)}:${canonicalStringify(value[k])}`);
+    const pairs = keys.map(k => `${JSON.stringify(k)}:${canonicalStringify(obj[k])}`);
     return `{${pairs.join(',')}}`;
   }
   return JSON.stringify(value);

package/src/domain/utils/roaring.js

@@ -30,9 +30,35 @@
  */
 const NOT_CHECKED = Symbol('NOT_CHECKED');
 
+/**
+ * Shape of the lazily-loaded roaring module after ESM/CJS unwrapping.
+ * Uses Function instead of typeof import('roaring').RoaringBitmap32 to avoid
+ * duplicate import() references that crash Deno's JSR rewriter (deno_ast
+ * overlapping TextChange bug). The single import() reference lives on
+ * getRoaringBitmap32()'s @returns tag.
+ * @typedef {Object} RoaringModule
+ * @property {Function & { isNativelyInstalled?: () => boolean }} RoaringBitmap32
+ * @property {{ RoaringBitmap32: Function }} [default]
+ * @property {boolean} [isNativelyInstalled]
+ */
+
+/**
+ * Minimum structural contract of a RoaringBitmap32 as used by bitmap index code.
+ * Named "Subset" because it only covers methods actually called by index builders/readers.
+ * Using import('roaring').RoaringBitmap32 directly fails under checkJs + skipLibCheck
+ * because tsc doesn't fully resolve inherited methods from ReadonlyRoaringBitmap32.
+ * @typedef {Object} RoaringBitmapSubset
+ * @property {number} size
+ * @property {function(number): void} add
+ * @property {function(number): boolean} has
+ * @property {function(Iterable<number>): void} orInPlace
+ * @property {function(boolean): Uint8Array} serialize
+ * @property {function(): number[]} toArray
+ */
+
 /**
  * Cached reference to the loaded roaring module.
- * @type {any} // TODO(ts-cleanup): type lazy singleton
+ * @type {RoaringModule | null}
  * @private
  */
 let roaringModule = null;
@@ -51,7 +77,7 @@ let nativeAvailability = NOT_CHECKED;
  * Uses a top-level-await-friendly pattern with dynamic import.
  * The module is cached after first load.
  *
- * @returns {any} The roaring module exports
+ * @returns {RoaringModule} The roaring module exports
  * @throws {Error} If the roaring package is not installed or fails to load
  * @private
  */
@@ -67,7 +93,7 @@ function loadRoaring() {
  * This is called automatically via top-level await when the module is imported,
  * but can also be called manually with a pre-loaded module for testing.
  *
- * @param {Object} [mod] - Pre-loaded roaring module (for testing/DI)
+ * @param {RoaringModule} [mod] - Pre-loaded roaring module (for testing/DI)
  * @returns {Promise<void>}
  */
 export async function initRoaring(mod) {
@@ -76,7 +102,7 @@ export async function initRoaring(mod) {
     return;
   }
   if (!roaringModule) {
-    roaringModule = await import('roaring');
+    roaringModule = /** @type {RoaringModule} */ (await import('roaring'));
     // Handle both ESM default export and CJS module.exports
     if (roaringModule.default && roaringModule.default.RoaringBitmap32) {
       roaringModule = roaringModule.default;
@@ -116,7 +142,7 @@ try {
  * const intersection = RoaringBitmap32.and(a, b); // [2, 3]
  */
 export function getRoaringBitmap32() {
-  return loadRoaring().RoaringBitmap32;
+  return /** @type {typeof import('roaring').RoaringBitmap32} */ (loadRoaring().RoaringBitmap32);
 }
 
 /**

package/src/domain/warp/PatchSession.js

@@ -120,7 +120,7 @@ export class PatchSession {
    *
    * @param {string} nodeId - The node ID
    * @param {string} key - Property key
-   * @param {*} value - Property value (must be JSON-serializable)
+   * @param {unknown} value - Property value (must be JSON-serializable)
    * @returns {this} This session for chaining
    * @throws {Error} If this session has already been committed
    */
@@ -130,6 +130,24 @@ export class PatchSession {
     return this;
   }
 
+  /**
+   * Sets a property on an edge.
+   *
+   * @param {string} from - Source node ID
+   * @param {string} to - Target node ID
+   * @param {string} label - Edge label/type
+   * @param {string} key - Property key
+   * @param {unknown} value - Property value (must be JSON-serializable)
+   * @returns {this} This session for chaining
+   * @throws {Error} If this session has already been committed
+   */
+  // eslint-disable-next-line max-params -- direct delegate matching PatchBuilderV2 signature
+  setEdgeProperty(from, to, label, key, value) {
+    this._ensureNotCommitted();
+    this._builder.setEdgeProperty(from, to, label, key, value);
+    return this;
+  }
+
   /**
    * Builds the PatchV2 object without committing.
    *
@@ -176,23 +194,14 @@ export class PatchSession {
       const sha = await this._builder.commit();
       this._committed = true;
       return sha;
-    } catch (/** @type {any} */ err) { // TODO(ts-cleanup): type error
-      // Check if it's a concurrent commit error from PatchBuilderV2
-      if (err.message?.includes('Concurrent commit detected') ||
-          err.message?.includes('has advanced')) {
-        throw new WriterError(
-          'WRITER_REF_ADVANCED',
-          err.message,
-          err
-        );
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      const cause = err instanceof Error ? err : undefined;
+      if (errMsg.includes('Concurrent commit detected') ||
+          errMsg.includes('has advanced')) {
+        throw new WriterError('WRITER_REF_ADVANCED', errMsg, cause);
       }
-
-      // Wrap other errors
-      throw new WriterError(
-        'PERSIST_WRITE_FAILED',
-        `Failed to persist patch: ${err.message}`,
-        err
-      );
+      throw new WriterError('PERSIST_WRITE_FAILED', `Failed to persist patch: ${errMsg}`, cause);
     }
   }