@git-stunts/git-warp 11.2.1 → 11.5.0

package/src/domain/trust/TrustRecordService.js

@@ -22,8 +22,8 @@ import TrustError from '../errors/TrustError.js';
 export class TrustRecordService {
   /**
    * @param {Object} options
-   * @param {*} options.persistence - GraphPersistencePort adapter
-   * @param {*} options.codec - CodecPort adapter (CBOR)
+   * @param {import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default & import('../../ports/RefPort.js').default} options.persistence - GraphPersistencePort adapter
+   * @param {import('../../ports/CodecPort.js').default} options.codec - CodecPort adapter (CBOR)
    */
   constructor({ persistence, codec }) {
     this._persistence = persistence;
@@ -46,7 +46,7 @@ export class TrustRecordService {
    * evaluation when the full key set is available.
    *
    * @param {string} graphName
-   * @param {Record<string, *>} record - Complete signed trust record
+   * @param {Record<string, unknown>} record - Complete signed trust record
    * @param {AppendOptions} [options]
    * @returns {Promise<{commitSha: string, ref: string}>}
    */
@@ -95,7 +95,7 @@ export class TrustRecordService {
    * @param {string} graphName
    * @param {Object} [options]
    * @param {string} [options.tip] - Override tip commit (for pinned reads)
-   * @returns {Promise<Array<Record<string, *>>>}
+   * @returns {Promise<Array<Record<string, unknown>>>}
    */
   async readRecords(graphName, options = {}) {
     const ref = buildTrustRecordRef(graphName);
@@ -117,13 +117,16 @@ export class TrustRecordService {
 
     while (current) {
       const info = await this._persistence.getNodeInfo(current);
-      const record = this._codec.decode(
-        await this._persistence.readBlob(
-          (await this._persistence.readTreeOids(
-            await this._persistence.getCommitTree(current),
-          ))['record.cbor'],
-        ),
+      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);
 
@@ -145,7 +148,7 @@ export class TrustRecordService {
    * - Each record passes schema validation
    * - First record has prev=null
    *
-   * @param {Array<Record<string, *>>} records - Records in chain order (oldest first)
+   * @param {Array<Record<string, unknown>>} records - Records in chain order (oldest first)
    * @returns {{valid: boolean, errors: Array<{index: number, error: string}>}}
    */
   verifyChain(records) {
@@ -177,7 +180,7 @@ export class TrustRecordService {
       // Prev-link check
       if (i === 0) {
         if (record.prev !== null) {
-          errors.push({ index: i, error: `Genesis record must have prev=null, got ${record.prev}` });
+          errors.push({ index: i, error: `Genesis record must have prev=null, got ${JSON.stringify(record.prev)}` });
         }
       } else {
         const expectedPrev = records[i - 1].recordId;
@@ -200,12 +203,13 @@ export class TrustRecordService {
    * cryptographic verification — that requires the issuer's public key
    * from the trust state, which is resolved during evaluation.
    *
-   * @param {Record<string, *>} record
+   * @param {Record<string, unknown>} record
    * @throws {TrustError} if signature envelope is missing or malformed
    * @private
    */
   _verifySignatureEnvelope(record) {
-    if (!record.signature || !record.signature.sig || !record.signature.alg) {
+    const sig = /** @type {Record<string, unknown>|undefined} */ (record.signature);
+    if (!sig || !sig.sig || !sig.alg) {
       throw new TrustError(
         'Trust record missing or malformed signature',
         { code: 'E_TRUST_SIGNATURE_MISSING' },
@@ -237,14 +241,14 @@ export class TrustRecordService {
       return { tipSha, recordId: null };
     }
 
-    const record = this._codec.decode(await this._persistence.readBlob(blobOid));
-    return { tipSha, recordId: record.recordId ?? null };
+    const record = /** @type {Record<string, unknown>} */ (this._codec.decode(await this._persistence.readBlob(blobOid)));
+    return { tipSha, recordId: /** @type {string|null} */ (record.recordId) ?? null };
   }
 
   /**
    * Persists a trust record as a Git commit.
    * @param {string} ref
-   * @param {Record<string, *>} record
+   * @param {Record<string, unknown>} record
    * @param {string|null} parentSha - Resolved tip SHA (null for genesis)
    * @returns {Promise<string>} commit SHA
    * @private
@@ -252,16 +256,19 @@ export class TrustRecordService {
   async _persistRecord(ref, record, parentSha) {
     // Encode record as CBOR blob
     const encoded = this._codec.encode(record);
-    const blobOid = await this._persistence.writeBlob(encoded);
+    // Buffer.from() ensures Uint8Array from codec is accepted by writeBlob
+    const blobOid = await this._persistence.writeBlob(Buffer.from(encoded));
 
-    // Create tree with single entry
-    const treeOid = await this._persistence.writeTree({ 'record.cbor': blobOid });
+    // Create tree with single entry (mktree format)
+    const treeOid = await this._persistence.writeTree([`100644 blob ${blobOid}\trecord.cbor`]);
 
     const parents = parentSha ? [parentSha] : [];
-    const message = `trust: ${record.recordType} ${record.recordId.slice(0, 12)}`;
+    const rType = typeof record.recordType === 'string' ? record.recordType : '';
+    const rId = typeof record.recordId === 'string' ? record.recordId.slice(0, 12) : '';
+    const message = `trust: ${rType} ${rId}`;
 
-    const commitSha = await this._persistence.createCommit({
-      tree: treeOid,
+    const commitSha = await this._persistence.commitNodeWithTree({
+      treeOid,
       parents,
       message,
     });

package/src/domain/trust/TrustStateBuilder.js

@@ -12,6 +12,19 @@
 
 import { TrustRecordSchema } from './schemas.js';
 
+/**
+ * @typedef {Object} TrustRecord
+ * @property {string} recordType - Record type (KEY_ADD, KEY_REVOKE, WRITER_BIND_ADD, WRITER_BIND_REVOKE)
+ * @property {string} recordId - Content-addressed record identifier
+ * @property {Record<string, string>} subject - Subject fields (keyId, publicKey, writerId, reasonCode vary by type)
+ * @property {string} issuedAt - ISO timestamp
+ * @property {number} schemaVersion
+ * @property {string} issuerKeyId
+ * @property {string|null} prev
+ * @property {{alg: string, sig: string}} signature
+ * @property {Record<string, unknown>} [meta]
+ */
+
 /**
  * @typedef {Object} TrustState
  * @property {Map<string, {publicKey: string, addedAt: string}>} activeKeys - keyId → key info
@@ -30,7 +43,7 @@ import { TrustRecordSchema } from './schemas.js';
  * - Binding validity: WRITER_BIND_ADD requires the referenced key to be active
  * - Schema validation: each record is validated against TrustRecordSchema
  *
- * @param {Array<Record<string, *>>} records - Trust records in chain order
+ * @param {Array<Record<string, unknown>>} records - Trust records in chain order
  * @returns {TrustState} Frozen trust state
  */
 export function buildState(records) {
@@ -49,13 +62,13 @@ export function buildState(records) {
     const parsed = TrustRecordSchema.safeParse(record);
     if (!parsed.success) {
       errors.push({
-        recordId: record.recordId ?? '(unknown)',
+        recordId: typeof record.recordId === 'string' ? record.recordId : '(unknown)',
         error: `Schema validation failed: ${parsed.error.message}`,
       });
       continue;
     }
 
-    const rec = parsed.data;
+    const rec = /** @type {TrustRecord} */ (parsed.data);
     processRecord(rec, activeKeys, revokedKeys, writerBindings, revokedBindings, errors);
   }
 
@@ -63,7 +76,7 @@ export function buildState(records) {
 }
 
 /**
- * @param {*} rec
+ * @param {TrustRecord} rec
  * @param {Map<string, {publicKey: string, addedAt: string}>} activeKeys
  * @param {Map<string, {publicKey: string, revokedAt: string, reasonCode: string}>} revokedKeys
  * @param {Map<string, {keyId: string, boundAt: string}>} writerBindings
@@ -90,7 +103,7 @@ function processRecord(rec, activeKeys, revokedKeys, writerBindings, revokedBind
 }
 
 /**
- * @param {*} rec
+ * @param {TrustRecord} rec
  * @param {Map<string, {publicKey: string, addedAt: string}>} activeKeys
  * @param {Map<string, {publicKey: string, revokedAt: string, reasonCode: string}>} revokedKeys
  * @param {Array<{recordId: string, error: string}>} errors
@@ -118,7 +131,7 @@ function handleKeyAdd(rec, activeKeys, revokedKeys, errors) {
 }
 
 /**
- * @param {*} rec
+ * @param {TrustRecord} rec
  * @param {Map<string, {publicKey: string, addedAt: string}>} activeKeys
  * @param {Map<string, {publicKey: string, revokedAt: string, reasonCode: string}>} revokedKeys
  * @param {Array<{recordId: string, error: string}>} errors
@@ -152,7 +165,7 @@ function handleKeyRevoke(rec, activeKeys, revokedKeys, errors) {
 }
 
 /**
- * @param {*} rec
+ * @param {TrustRecord} rec
  * @param {Map<string, {publicKey: string, addedAt: string}>} activeKeys
  * @param {Map<string, {publicKey: string, revokedAt: string, reasonCode: string}>} revokedKeys
  * @param {Map<string, {keyId: string, boundAt: string}>} writerBindings
@@ -182,7 +195,7 @@ function handleBindAdd(rec, activeKeys, revokedKeys, writerBindings, errors) {
 }
 
 /**
- * @param {*} rec
+ * @param {TrustRecord} rec
  * @param {Map<string, {keyId: string, boundAt: string}>} writerBindings
  * @param {Map<string, {keyId: string, revokedAt: string, reasonCode: string}>} revokedBindings
  * @param {Array<{recordId: string, error: string}>} errors

package/src/domain/trust/canonical.js

@@ -24,8 +24,8 @@ export const TRUST_SIGN_DOMAIN = 'git-warp:trust-sign:v1\0';
  * Returns the record payload used for recordId computation.
  * Strips `recordId` and `signature` — these are derived, not inputs.
  *
- * @param {Record<string, *>} record
- * @returns {Record<string, *>}
+ * @param {Record<string, unknown>} record
+ * @returns {Record<string, unknown>}
  */
 export function unsignedRecordForId(record) {
   const out = { ...record };
@@ -38,8 +38,8 @@ export function unsignedRecordForId(record) {
  * Returns the record payload used for signature computation.
  * Strips `signature` only — `recordId` is included in signed payload.
  *
- * @param {Record<string, *>} record
- * @returns {Record<string, *>}
+ * @param {Record<string, unknown>} record
+ * @returns {Record<string, unknown>}
  */
 export function unsignedRecordForSignature(record) {
   const out = { ...record };
@@ -50,7 +50,7 @@ export function unsignedRecordForSignature(record) {
 /**
  * Computes the canonical string for recordId hashing.
  *
- * @param {Record<string, *>} record - Full record (recordId and signature will be stripped)
+ * @param {Record<string, unknown>} record - Full record (recordId and signature will be stripped)
  * @returns {string} Domain-separated canonical JSON string
  */
 export function recordIdPayload(record) {
@@ -60,7 +60,7 @@ export function recordIdPayload(record) {
 /**
  * Computes the canonical string for signature verification.
  *
- * @param {Record<string, *>} record - Full record (signature will be stripped)
+ * @param {Record<string, unknown>} record - Full record (signature will be stripped)
  * @returns {string} Domain-separated canonical JSON string
  */
 export function signaturePayload(record) {

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/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/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
    */
@@ -137,7 +137,7 @@ export class PatchSession {
    * @param {string} to - Target node ID
    * @param {string} label - Edge label/type
    * @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
    */
@@ -148,6 +148,37 @@ export class PatchSession {
     return this;
   }
 
+  /**
+   * Attaches content to a node.
+   *
+   * @param {string} nodeId - The node ID to attach content to
+   * @param {Buffer|string} content - The content to attach
+   * @returns {Promise<this>} This session for chaining
+   * @throws {Error} If this session has already been committed
+   */
+  async attachContent(nodeId, content) {
+    this._ensureNotCommitted();
+    await this._builder.attachContent(nodeId, content);
+    return this;
+  }
+
+  /**
+   * Attaches content to an edge.
+   *
+   * @param {string} from - Source node ID
+   * @param {string} to - Target node ID
+   * @param {string} label - Edge label/type
+   * @param {Buffer|string} content - The content to attach
+   * @returns {Promise<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
+  async attachEdgeContent(from, to, label, content) {
+    this._ensureNotCommitted();
+    await this._builder.attachEdgeContent(from, to, label, content);
+    return this;
+  }
+
   /**
    * Builds the PatchV2 object without committing.
    *
@@ -194,23 +225,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);
     }
   }