@git-stunts/git-warp 10.3.2 → 10.7.0

package/src/domain/services/IndexRebuildService.js

@@ -40,17 +40,17 @@ export default class IndexRebuildService {
    * Creates an IndexRebuildService instance.
    *
    * @param {Object} options - Configuration options
-   * @param {Object} options.graphService - Graph service providing node iteration.
-   *   Must implement `iterateNodes({ ref, limit }) => AsyncGenerator<GraphNode>`.
+   * @param {{ iterateNodes: (opts: { ref: string, limit: number }) => AsyncIterable<{ sha: string, parents: string[] }> }} options.graphService - Graph service providing node iteration.
    * @param {import('../../ports/IndexStoragePort.js').default} options.storage - Storage adapter
    *   for persisting index blobs and trees. Typically GitGraphAdapter.
    * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for
    *   structured logging. Defaults to null logger (no logging).
+   * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
    * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - Crypto adapter for checksums
    * @throws {Error} If graphService is not provided
    * @throws {Error} If storage adapter is not provided
    */
-  constructor({ graphService, storage, logger = nullLogger, codec, crypto }) {
+  constructor({ graphService, storage, logger = nullLogger, codec, crypto } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
     if (!graphService) {
       throw new Error('IndexRebuildService requires a graphService');
     }
@@ -156,7 +156,7 @@ export default class IndexRebuildService {
         operation: 'rebuild',
         ref,
         mode,
-        error: err.message,
+        error: /** @type {any} */ (err).message, // TODO(ts-cleanup): type error
         durationMs,
       });
       throw err;
@@ -247,12 +247,12 @@ export default class IndexRebuildService {
    * @private
    */
   async _rebuildStreaming(ref, { limit, maxMemoryBytes, onFlush, onProgress, signal, frontier }) {
-    const builder = new StreamingBitmapIndexBuilder({
+    const builder = new StreamingBitmapIndexBuilder(/** @type {*} */ ({ // TODO(ts-cleanup): narrow port type
       storage: this.storage,
       maxMemoryBytes,
       onFlush,
       crypto: this._crypto,
-    });
+    }));
 
     let processedNodes = 0;
 
@@ -266,7 +266,7 @@ export default class IndexRebuildService {
       if (processedNodes % 10000 === 0) {
         checkAborted(signal, 'rebuild');
         if (onProgress) {
-          const stats = builder.getMemoryStats();
+          const stats = /** @type {any} */ (builder).getMemoryStats(); // TODO(ts-cleanup): narrow port type
           onProgress({
             processedNodes,
             currentMemoryBytes: stats.estimatedBitmapBytes,
@@ -275,7 +275,7 @@ export default class IndexRebuildService {
       }
     }
 
-    return await builder.finalize({ signal, frontier });
+    return await /** @type {any} */ (builder).finalize({ signal, frontier }); // TODO(ts-cleanup): narrow port type
   }
 
   /**
@@ -302,10 +302,10 @@ export default class IndexRebuildService {
     const treeStructure = await builder.serialize({ frontier });
     const flatEntries = [];
     for (const [path, buffer] of Object.entries(treeStructure)) {
-      const oid = await this.storage.writeBlob(buffer);
+      const oid = await /** @type {import('../../ports/BlobPort.js').default} */ (/** @type {unknown} */ (this.storage)).writeBlob(buffer);
       flatEntries.push(`100644 blob ${oid}\t${path}`);
     }
-    return await this.storage.writeTree(flatEntries);
+    return await /** @type {import('../../ports/TreePort.js').default} */ (/** @type {unknown} */ (this.storage)).writeTree(flatEntries);
   }
 
   /**
@@ -384,12 +384,12 @@ export default class IndexRebuildService {
     }
 
     const startTime = performance.now();
-    const shardOids = await this.storage.readTreeOids(treeOid);
+    const shardOids = await /** @type {import('../../ports/TreePort.js').default} */ (/** @type {unknown} */ (this.storage)).readTreeOids(treeOid);
     const shardCount = Object.keys(shardOids).length;
 
     // Staleness check
     if (currentFrontier) {
-      const indexFrontier = await loadIndexFrontier(shardOids, this.storage, { codec: this._codec });
+      const indexFrontier = await loadIndexFrontier(shardOids, /** @type {*} */ (this.storage), { codec: this._codec }); // TODO(ts-cleanup): narrow port type
       if (indexFrontier) {
         const result = checkStaleness(indexFrontier, currentFrontier);
         if (result.stale) {

package/src/domain/services/IndexStalenessChecker.js

@@ -5,7 +5,11 @@
 
 import defaultCodec from '../utils/defaultCodec.js';
 
-/** @private */
+/**
+ * @param {*} envelope
+ * @param {string} label
+ * @private
+ */
 function validateEnvelope(envelope, label) {
   if (!envelope || typeof envelope !== 'object' || !envelope.frontier || typeof envelope.frontier !== 'object') {
     throw new Error(`invalid frontier envelope for ${label}`);
@@ -16,17 +20,17 @@ function validateEnvelope(envelope, label) {
  * Loads the frontier from an index tree's shard OIDs.
  *
  * @param {Record<string, string>} shardOids - Map of path → blob OID from readTreeOids
- * @param {import('../../ports/IndexStoragePort.js').default} storage - Storage adapter
+ * @param {import('../../ports/IndexStoragePort.js').default & import('../../ports/BlobPort.js').default} storage - Storage adapter
  * @param {Object} [options]
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
  * @returns {Promise<Map<string, string>|null>} Frontier map, or null if not present (legacy index)
  */
-export async function loadIndexFrontier(shardOids, storage, { codec } = {}) {
+export async function loadIndexFrontier(shardOids, storage, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   const c = codec || defaultCodec;
   const cborOid = shardOids['frontier.cbor'];
   if (cborOid) {
     const buffer = await storage.readBlob(cborOid);
-    const envelope = c.decode(buffer);
+    const envelope = /** @type {{ frontier: Record<string, string> }} */ (c.decode(buffer));
     validateEnvelope(envelope, 'frontier.cbor');
     return new Map(Object.entries(envelope.frontier));
   }
@@ -34,7 +38,7 @@ export async function loadIndexFrontier(shardOids, storage, { codec } = {}) {
   const jsonOid = shardOids['frontier.json'];
   if (jsonOid) {
     const buffer = await storage.readBlob(jsonOid);
-    const envelope = JSON.parse(buffer.toString('utf-8'));
+    const envelope = /** @type {{ frontier: Record<string, string> }} */ (JSON.parse(buffer.toString('utf-8')));
     validateEnvelope(envelope, 'frontier.json');
     return new Map(Object.entries(envelope.frontier));
   }
@@ -51,7 +55,10 @@ export async function loadIndexFrontier(shardOids, storage, { codec } = {}) {
  * @property {string[]} removedWriters - Writers in index but not current
  */
 
-/** @private */
+/**
+ * @param {{ stale: boolean, advancedWriters: string[], newWriters: string[], removedWriters: string[] }} opts
+ * @private
+ */
 function buildReason({ stale, advancedWriters, newWriters, removedWriters }) {
   if (!stale) {
     return 'index is current';

package/src/domain/services/JoinReducer.js

@@ -29,7 +29,7 @@ export {
  * @typedef {Object} WarpStateV5
  * @property {import('../crdt/ORSet.js').ORSet} nodeAlive - ORSet of alive nodes
  * @property {import('../crdt/ORSet.js').ORSet} edgeAlive - ORSet of alive edges
- * @property {Map<string, import('../crdt/LWW.js').LWWRegister>} prop - Properties with LWW
+ * @property {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} prop - Properties with LWW
  * @property {import('../crdt/VersionVector.js').VersionVector} observedFrontier - Observed version vector
  * @property {Map<string, import('../utils/EventId.js').EventId>} edgeBirthEvent - EdgeKey → EventId of most recent EdgeAdd (for clean-slate prop visibility)
  */
@@ -88,14 +88,14 @@ export function createEmptyStateV5() {
 export function applyOpV2(state, op, eventId) {
   switch (op.type) {
     case 'NodeAdd':
-      orsetAdd(state.nodeAlive, op.node, op.dot);
+      orsetAdd(state.nodeAlive, /** @type {string} */ (op.node), /** @type {import('../crdt/Dot.js').Dot} */ (op.dot));
       break;
     case 'NodeRemove':
-      orsetRemove(state.nodeAlive, op.observedDots);
+      orsetRemove(state.nodeAlive, /** @type {Set<string>} */ (/** @type {unknown} */ (op.observedDots)));
       break;
     case 'EdgeAdd': {
-      const edgeKey = encodeEdgeKey(op.from, op.to, op.label);
-      orsetAdd(state.edgeAlive, edgeKey, op.dot);
+      const edgeKey = encodeEdgeKey(/** @type {string} */ (op.from), /** @type {string} */ (op.to), /** @type {string} */ (op.label));
+      orsetAdd(state.edgeAlive, edgeKey, /** @type {import('../crdt/Dot.js').Dot} */ (op.dot));
       // Track the EventId at which this edge incarnation was born.
       // On re-add after remove, the greater EventId replaces the old one,
       // allowing the query layer to filter out stale properties.
@@ -108,13 +108,13 @@ export function applyOpV2(state, op, eventId) {
       break;
     }
     case 'EdgeRemove':
-      orsetRemove(state.edgeAlive, op.observedDots);
+      orsetRemove(state.edgeAlive, /** @type {Set<string>} */ (/** @type {unknown} */ (op.observedDots)));
       break;
     case 'PropSet': {
       // Uses EventId-based LWW, same as v4
-      const key = encodePropKey(op.node, op.key);
+      const key = encodePropKey(/** @type {string} */ (op.node), /** @type {string} */ (op.key));
       const current = state.prop.get(key);
-      state.prop.set(key, lwwMax(current, lwwSet(eventId, op.value)));
+      state.prop.set(key, /** @type {import('../crdt/LWW.js').LWWRegister<*>} */ (lwwMax(current, lwwSet(eventId, op.value))));
       break;
     }
     default:
@@ -290,7 +290,7 @@ function edgeRemoveOutcome(orset, op) {
  * - `superseded`: An existing value with higher EventId wins
  * - `redundant`: Exact same write (identical EventId)
  *
- * @param {Map<string, import('../crdt/LWW.js').LWWRegister>} propMap - The properties map keyed by encoded prop keys
+ * @param {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} propMap - The properties map keyed by encoded prop keys
  * @param {Object} op - The PropSet operation
  * @param {string} op.node - Node ID owning the property
  * @param {string} op.key - Property key/name
@@ -347,8 +347,8 @@ function propSetOutcome(propMap, op, eventId) {
  * @param {Object} patch - The patch to apply
  * @param {string} patch.writer - Writer ID who created this patch
  * @param {number} patch.lamport - Lamport timestamp of this patch
- * @param {Object[]} patch.ops - Array of operations to apply
- * @param {Map|Object} patch.context - Version vector context (Map or serialized form)
+ * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: *, oid?: string}>} patch.ops - Array of operations to apply
+ * @param {Map<string, number>|{[x: string]: number}} patch.context - Version vector context (Map or serialized form)
  * @param {string} patchSha - The Git SHA of the patch commit (used for EventId creation)
  * @param {boolean} [collectReceipts=false] - When true, computes and returns receipt data
  * @returns {WarpStateV5|{state: WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}}
@@ -370,30 +370,32 @@ export function join(state, patch, patchSha, collectReceipts) {
   }
 
   // Receipt-enabled path
+  /** @type {import('../types/TickReceipt.js').OpOutcome[]} */
   const opResults = [];
   for (let i = 0; i < patch.ops.length; i++) {
     const op = patch.ops[i];
     const eventId = createEventId(patch.lamport, patch.writer, patchSha, i);
 
     // Determine outcome BEFORE applying the op (state is pre-op)
+    /** @type {{target: string, result: string, reason?: string}} */
     let outcome;
     switch (op.type) {
       case 'NodeAdd':
-        outcome = nodeAddOutcome(state.nodeAlive, op);
+        outcome = nodeAddOutcome(state.nodeAlive, /** @type {{node: string, dot: import('../crdt/Dot.js').Dot}} */ (op));
         break;
       case 'NodeRemove':
-        outcome = nodeRemoveOutcome(state.nodeAlive, op);
+        outcome = nodeRemoveOutcome(state.nodeAlive, /** @type {{node?: string, observedDots: string[]}} */ (op));
         break;
       case 'EdgeAdd': {
-        const edgeKey = encodeEdgeKey(op.from, op.to, op.label);
-        outcome = edgeAddOutcome(state.edgeAlive, op, edgeKey);
+        const edgeKey = encodeEdgeKey(/** @type {string} */ (op.from), /** @type {string} */ (op.to), /** @type {string} */ (op.label));
+        outcome = edgeAddOutcome(state.edgeAlive, /** @type {{from: string, to: string, label: string, dot: import('../crdt/Dot.js').Dot}} */ (op), edgeKey);
         break;
       }
       case 'EdgeRemove':
-        outcome = edgeRemoveOutcome(state.edgeAlive, op);
+        outcome = edgeRemoveOutcome(state.edgeAlive, /** @type {{from?: string, to?: string, label?: string, observedDots: string[]}} */ (op));
         break;
       case 'PropSet':
-        outcome = propSetOutcome(state.prop, op, eventId);
+        outcome = propSetOutcome(state.prop, /** @type {{node: string, key: string, value: *}} */ (op), eventId);
         break;
       default:
         // Unknown or BlobValue — always applied
@@ -404,12 +406,13 @@ export function join(state, patch, patchSha, collectReceipts) {
     // Apply the op (mutates state)
     applyOpV2(state, op, eventId);
 
-    const receiptOp = RECEIPT_OP_TYPE[op.type] || op.type;
+    const receiptOp = /** @type {Record<string, string>} */ (RECEIPT_OP_TYPE)[op.type] || op.type;
     // Skip unknown/forward-compatible op types that aren't valid receipt ops
     if (!VALID_RECEIPT_OPS.has(receiptOp)) {
       continue;
     }
-    const entry = { op: receiptOp, target: outcome.target, result: outcome.result };
+    /** @type {import('../types/TickReceipt.js').OpOutcome} */
+    const entry = { op: receiptOp, target: outcome.target, result: /** @type {'applied'|'superseded'|'redundant'} */ (outcome.result) };
     if (outcome.reason) {
       entry.reason = outcome.reason;
     }
@@ -467,16 +470,16 @@ export function joinStates(a, b) {
  *
  * This is a pure function that does not mutate its inputs.
  *
- * @param {Map<string, import('../crdt/LWW.js').LWWRegister>} a - First property map
- * @param {Map<string, import('../crdt/LWW.js').LWWRegister>} b - Second property map
- * @returns {Map<string, import('../crdt/LWW.js').LWWRegister>} New map containing merged properties
+ * @param {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} a - First property map
+ * @param {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} b - Second property map
+ * @returns {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} New map containing merged properties
  */
 function mergeProps(a, b) {
   const result = new Map(a);
 
   for (const [key, regB] of b) {
     const regA = result.get(key);
-    result.set(key, lwwMax(regA, regB));
+    result.set(key, /** @type {import('../crdt/LWW.js').LWWRegister<*>} */ (lwwMax(regA, regB)));
   }
 
   return result;
@@ -527,9 +530,7 @@ function mergeEdgeBirthEvent(a, b) {
  * - When `options.receipts` is true, returns a TickReceipt per patch for
  *   provenance tracking and debugging.
  *
- * @param {Array<{patch: Object, sha: string}>} patches - Array of patch objects with their Git SHAs
- * @param {Object} patches[].patch - The decoded patch object (writer, lamport, ops, context)
- * @param {string} patches[].sha - The Git SHA of the patch commit
+ * @param {Array<{patch: {writer: string, lamport: number, ops: Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: *, oid?: string}>, context: Map<string, number>|{[x: string]: number}}, sha: string}>} patches - Array of patch objects with their Git SHAs
  * @param {WarpStateV5} [initialState] - Optional starting state (for incremental materialization from checkpoint)
  * @param {Object} [options] - Optional configuration
  * @param {boolean} [options.receipts=false] - When true, collect and return TickReceipts
@@ -544,7 +545,7 @@ export function reduceV5(patches, initialState, options) {
   if (options && options.receipts) {
     const receipts = [];
     for (const { patch, sha } of patches) {
-      const result = join(state, patch, sha, true);
+      const result = /** @type {{state: WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}} */ (join(state, patch, sha, true));
       receipts.push(result.receipt);
     }
     return { state, receipts };

package/src/domain/services/LogicalTraversal.js

@@ -145,14 +145,14 @@ export default class LogicalTraversal {
    * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
    * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
    * @param {number} [options.maxDepth] - Maximum depth to traverse
-   * @returns {Promise<{dir: 'out'|'in'|'both', labelSet: Set<string>|null, adjacency: Object, depthLimit: number}>}
+   * @returns {Promise<{dir: 'out'|'in'|'both', labelSet: Set<string>|null, adjacency: {outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>>}, depthLimit: number}>}
    *   The normalized traversal parameters
    * @throws {TraversalError} If the start node is not found (NODE_NOT_FOUND)
    * @throws {TraversalError} If the direction is invalid (INVALID_DIRECTION)
    * @throws {TraversalError} If the labelFilter is invalid (INVALID_LABEL_FILTER)
    */
   async _prepare(start, { dir, labelFilter, maxDepth }) {
-    const materialized = await this._graph._materializeGraph();
+    const materialized = await /** @type {any} */ (this._graph)._materializeGraph(); // TODO(ts-cleanup): narrow port type
 
     if (!(await this._graph.hasNode(start))) {
       throw new TraversalError(`Start node not found: ${start}`, {
@@ -187,7 +187,7 @@ export default class LogicalTraversal {
     const result = [];
 
     while (queue.length > 0) {
-      const current = queue.shift();
+      const current = /** @type {{nodeId: string, depth: number}} */ (queue.shift());
       if (visited.has(current.nodeId)) {
         continue;
       }
@@ -237,7 +237,7 @@ export default class LogicalTraversal {
     const result = [];
 
     while (stack.length > 0) {
-      const current = stack.pop();
+      const current = /** @type {{nodeId: string, depth: number}} */ (stack.pop());
       if (visited.has(current.nodeId)) {
         continue;
       }
@@ -298,7 +298,7 @@ export default class LogicalTraversal {
     visited.add(from);
 
     while (queue.length > 0) {
-      const current = queue.shift();
+      const current = /** @type {{nodeId: string, depth: number}} */ (queue.shift());
       if (current.depth >= depthLimit) {
         continue;
       }
@@ -319,10 +319,11 @@ export default class LogicalTraversal {
 
         if (edge.neighborId === to) {
           const path = [to];
+          /** @type {string|undefined} */
           let cursor = current.nodeId;
           while (cursor) {
             path.push(cursor);
-            cursor = parent.get(cursor) || null;
+            cursor = parent.get(cursor);
           }
           path.reverse();
           return { found: true, path, length: path.length - 1 };

package/src/domain/services/MessageCodecInternal.js

@@ -12,6 +12,7 @@
  * @private
  */
 
+// @ts-expect-error -- no declaration file for @git-stunts/trailer-codec
 import { TrailerCodec, TrailerCodecService } from '@git-stunts/trailer-codec';
 
 // -----------------------------------------------------------------------------
@@ -62,6 +63,7 @@ const SHA256_PATTERN = /^[0-9a-f]{64}$/;
 // -----------------------------------------------------------------------------
 
 // Lazy singleton codec instance
+/** @type {*} */ // TODO(ts-cleanup): type lazy singleton
 let _codec = null;
 
 /**

package/src/domain/services/ObserverView.js

@@ -102,7 +102,7 @@ export default class ObserverView {
     this._graph = graph;
 
     /** @type {LogicalTraversal} */
-    this.traverse = new LogicalTraversal(this);
+    this.traverse = new LogicalTraversal(/** @type {*} */ (this)); // TODO(ts-cleanup): type observer cast
   }
 
   /**
@@ -124,11 +124,11 @@ export default class ObserverView {
    * Builds a filtered adjacency structure that only includes edges
    * where both endpoints pass the match filter.
    *
-   * @returns {Promise<{state: *, stateHash: string, adjacency: {outgoing: Map, incoming: Map}}>}
+   * @returns {Promise<{state: *, stateHash: string, adjacency: {outgoing: Map<string, *[]>, incoming: Map<string, *[]>}}>}
    * @private
    */
   async _materializeGraph() {
-    const materialized = await this._graph._materializeGraph();
+    const materialized = await /** @type {*} */ (this._graph)._materializeGraph(); // TODO(ts-cleanup): narrow port type
     const { state, stateHash } = materialized;
 
     // Build filtered adjacency: only edges where both endpoints match
@@ -159,8 +159,8 @@ export default class ObserverView {
       incoming.get(to).push({ neighborId: from, label });
     }
 
-    const sortNeighbors = (list) => {
-      list.sort((a, b) => {
+    const sortNeighbors = (/** @type {{ neighborId: string, label: string }[]} */ list) => {
+      list.sort((/** @type {{ neighborId: string, label: string }} */ a, /** @type {{ neighborId: string, label: string }} */ b) => {
         if (a.neighborId !== b.neighborId) {
           return a.neighborId < b.neighborId ? -1 : 1;
         }
@@ -260,6 +260,6 @@ export default class ObserverView {
    * @returns {QueryBuilder} A query builder scoped to this observer
    */
   query() {
-    return new QueryBuilder(this);
+    return new QueryBuilder(/** @type {*} */ (this)); // TODO(ts-cleanup): type observer cast
   }
 }

package/src/domain/services/PatchBuilderV2.js

@@ -85,8 +85,8 @@ export class PatchBuilderV2 {
    * @param {{ warn: Function }} [options.logger] - Logger for non-fatal warnings
    */
   constructor({ persistence, graphName, writerId, lamport, versionVector, getCurrentState, expectedParentSha = null, onCommitSuccess = null, onDeleteWithData = 'warn', codec, logger }) {
-    /** @type {import('../../ports/GraphPersistencePort.js').default} */
-    this._persistence = persistence;
+    /** @type {import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default} */
+    this._persistence = /** @type {*} */ (persistence); // TODO(ts-cleanup): narrow port type
 
     /** @type {string} */
     this._graphName = graphName;
@@ -214,7 +214,7 @@ export class PatchBuilderV2 {
       const { edges } = findAttachedData(state, nodeId);
       for (const edgeKey of edges) {
         const [from, to, label] = edgeKey.split('\0');
-        const edgeDots = [...orsetGetDots(state.edgeAlive, edgeKey)];
+        const edgeDots = /** @type {import('../crdt/Dot.js').Dot[]} */ (/** @type {unknown} */ ([...orsetGetDots(state.edgeAlive, edgeKey)]));
         this._ops.push(createEdgeRemoveV2(from, to, label, edgeDots));
         // Provenance: cascade-generated EdgeRemove reads the edge key (to observe its dots)
         this._reads.add(edgeKey);
@@ -251,7 +251,7 @@ export class PatchBuilderV2 {
       }
     }
 
-    const observedDots = state ? [...orsetGetDots(state.nodeAlive, nodeId)] : [];
+    const observedDots = /** @type {import('../crdt/Dot.js').Dot[]} */ (/** @type {unknown} */ (state ? [...orsetGetDots(state.nodeAlive, nodeId)] : []));
     this._ops.push(createNodeRemoveV2(nodeId, observedDots));
     // Provenance: NodeRemove reads the node (to observe its dots)
     this._reads.add(nodeId);
@@ -325,7 +325,7 @@ export class PatchBuilderV2 {
     // Get observed dots from current state (orsetGetDots returns already-encoded dot strings)
     const state = this._getCurrentState();
     const edgeKey = encodeEdgeKey(from, to, label);
-    const observedDots = state ? [...orsetGetDots(state.edgeAlive, edgeKey)] : [];
+    const observedDots = /** @type {import('../crdt/Dot.js').Dot[]} */ (/** @type {unknown} */ (state ? [...orsetGetDots(state.edgeAlive, edgeKey)] : []));
     this._ops.push(createEdgeRemoveV2(from, to, label, observedDots));
     // Provenance: EdgeRemove reads the edge key (to observe its dots)
     this._reads.add(edgeKey);
@@ -454,7 +454,7 @@ export class PatchBuilderV2 {
       schema,
       writer: this._writerId,
       lamport: this._lamport,
-      context: this._vv,
+      context: /** @type {*} */ (this._vv), // TODO(ts-cleanup): narrow port type
       ops: this._ops,
       reads: [...this._reads].sort(),
       writes: [...this._writes].sort(),
@@ -515,10 +515,10 @@ export class PatchBuilderV2 {
     const currentRefSha = await this._persistence.readRef(writerRef);
 
     if (currentRefSha !== this._expectedParentSha) {
-      const err = new WriterError(
+      const err = /** @type {WriterError & { expectedSha: string|null, actualSha: string|null }} */ (new WriterError(
         'WRITER_CAS_CONFLICT',
         'Commit failed: writer ref was updated by another process. Re-materialize and retry.'
-      );
+      ));
       err.expectedSha = this._expectedParentSha;
       err.actualSha = currentRefSha;
       throw err;
@@ -556,7 +556,7 @@ export class PatchBuilderV2 {
     const patchCbor = this._codec.encode(patch);
 
     // 5. Write patch.cbor blob
-    const patchBlobOid = await this._persistence.writeBlob(patchCbor);
+    const patchBlobOid = await this._persistence.writeBlob(/** @type {Buffer} */ (patchCbor));
 
     // 6. Create tree with the blob
     // Format for mktree: "mode type oid\tpath"

package/src/domain/services/PatchMessageCodec.js

@@ -72,13 +72,7 @@ export function encodePatchMessage({ graph, writer, lamport, patchOid, schema =
  * Decodes a patch commit message.
  *
  * @param {string} message - The raw commit message
- * @returns {Object} The decoded patch message
- * @returns {string} return.kind - Always 'patch'
- * @returns {string} return.graph - The graph name
- * @returns {string} return.writer - The writer ID
- * @returns {number} return.lamport - The Lamport timestamp
- * @returns {string} return.patchOid - The patch blob OID
- * @returns {number} return.schema - The schema version
+ * @returns {{ kind: 'patch', graph: string, writer: string, lamport: number, patchOid: string, schema: number }} The decoded patch message
  * @throws {Error} If the message is not a valid patch message
  *
  * @example

package/src/domain/services/ProvenanceIndex.js

@@ -52,7 +52,6 @@ class ProvenanceIndex {
   /**
    * Internal index mapping nodeId/edgeKey to Set of patch SHAs.
    * @type {Map<string, Set<string>>}
-   * @private
    */
   #index;
 
@@ -120,7 +119,6 @@ class ProvenanceIndex {
    *
    * @param {string} entityId - The node ID or edge key
    * @param {string} patchSha - The patch SHA
-   * @private
    */
   #addEntry(entityId, patchSha) {
     let shas = this.#index.get(entityId);
@@ -227,12 +225,12 @@ class ProvenanceIndex {
    * Returns sorted entries for deterministic output.
    *
    * @returns {Array<[string, string[]]>} Sorted array of [entityId, sortedShas[]] pairs
-   * @private
    */
   #sortedEntries() {
+    /** @type {Array<[string, string[]]>} */
     const entries = [];
     for (const [entityId, shas] of this.#index) {
-      entries.push([entityId, [...shas].sort()]);
+      entries.push(/** @type {[string, string[]]} */ ([entityId, [...shas].sort()]));
     }
     entries.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
     return entries;
@@ -246,7 +244,7 @@ class ProvenanceIndex {
    *
    * @param {Object} [options]
    * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
-   * @returns {Buffer} CBOR-encoded index
+   * @returns {Buffer|Uint8Array} CBOR-encoded index
    */
   serialize({ codec } = {}) {
     const c = codec || defaultCodec;
@@ -258,7 +256,6 @@ class ProvenanceIndex {
    *
    * @param {Array<[string, string[]]>} entries - Array of [entityId, shas[]] pairs
    * @returns {Map<string, Set<string>>} The built index
-   * @private
    */
   static #buildIndex(entries) {
     const index = new Map();
@@ -279,7 +276,8 @@ class ProvenanceIndex {
    */
   static deserialize(buffer, { codec } = {}) {
     const c = codec || defaultCodec;
-    const obj = c.decode(buffer);
+    /** @type {{ version?: number, entries?: Array<[string, string[]]> }} */
+    const obj = /** @type {any} */ (c.decode(buffer)); // TODO(ts-cleanup): narrow port type
 
     if (obj.version !== 1) {
       throw new Error(`Unsupported ProvenanceIndex version: ${obj.version}`);
@@ -304,7 +302,7 @@ class ProvenanceIndex {
   /**
    * Creates a ProvenanceIndex from a JSON representation.
    *
-   * @param {Object} json - Object with version and entries array
+   * @param {{ version?: number, entries?: Array<[string, string[]]> }} json - Object with version and entries array
    * @returns {ProvenanceIndex} The deserialized index
    * @throws {Error} If the JSON contains an unsupported version
    */

package/src/domain/services/ProvenancePayload.js

@@ -68,7 +68,6 @@ class ProvenancePayload {
   /**
    * The internal array of patch entries. Frozen after construction.
    * @type {ReadonlyArray<PatchEntry>}
-   * @private
    */
   #patches;
 
@@ -173,7 +172,7 @@ class ProvenancePayload {
     // Use JoinReducer's reduceV5 for deterministic materialization.
     // Note: reduceV5 returns { state, receipts } when options.receipts is truthy,
     // but returns bare WarpStateV5 when no options passed (as here).
-    return reduceV5(this.#patches, initialState);
+    return /** @type {import('./JoinReducer.js').WarpStateV5} */ (reduceV5(/** @type {*} */ (this.#patches), initialState)); // TODO(ts-cleanup): type patch array
   }
 
   /**