@git-stunts/git-warp 10.3.2 → 10.4.2

package/src/domain/services/StateSerializerV5.js

@@ -1,4 +1,5 @@
 import defaultCodec from '../utils/defaultCodec.js';
+import defaultCrypto from '../utils/defaultCrypto.js';
 import { orsetContains, orsetElements } from '../crdt/ORSet.js';
 import { decodeEdgeKey, decodePropKey } from './KeyCodec.js';
 
@@ -75,7 +76,7 @@ export function propVisibleV5(state, propKey) {
  * @param {import('./JoinReducer.js').WarpStateV5} state
  * @param {Object} [options]
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
- * @returns {Buffer}
+ * @returns {Buffer|Uint8Array}
  */
 export function serializeStateV5(state, { codec } = {}) {
   const c = codec || defaultCodec;
@@ -122,13 +123,14 @@ export function serializeStateV5(state, { codec } = {}) {
  * Computes SHA-256 hash of canonical state bytes.
  * @param {import('./JoinReducer.js').WarpStateV5} state
  * @param {Object} [options] - Options
- * @param {import('../../ports/CryptoPort.js').default} options.crypto - CryptoPort instance
+ * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort instance
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
- * @returns {Promise<string|null>} Hex-encoded SHA-256 hash, or null if no crypto
+ * @returns {Promise<string>} Hex-encoded SHA-256 hash
  */
-export async function computeStateHashV5(state, { crypto, codec } = {}) {
+export async function computeStateHashV5(state, { crypto, codec } = /** @type {{crypto?: import('../../ports/CryptoPort.js').default, codec?: import('../../ports/CodecPort.js').default}} */ ({})) {
+  const c = crypto || defaultCrypto;
   const serialized = serializeStateV5(state, { codec });
-  return crypto ? await crypto.hash('sha256', serialized) : null;
+  return await c.hash('sha256', serialized);
 }
 
 /**
@@ -141,7 +143,7 @@ export async function computeStateHashV5(state, { crypto, codec } = {}) {
  */
 export function deserializeStateV5(buffer, { codec } = {}) {
   const c = codec || defaultCodec;
-  return c.decode(buffer);
+  return /** @type {{nodes: string[], edges: Array<{from: string, to: string, label: string}>, props: Array<{node: string, key: string, value: *}>}} */ (c.decode(buffer));
 }
 
 // ============================================================================

package/src/domain/services/StreamingBitmapIndexBuilder.js

@@ -1,4 +1,5 @@
 import defaultCodec from '../utils/defaultCodec.js';
+import defaultCrypto from '../utils/defaultCrypto.js';
 import ShardCorruptionError from '../errors/ShardCorruptionError.js';
 import ShardValidationError from '../errors/ShardValidationError.js';
 import nullLogger from '../utils/nullLogger.js';
@@ -36,10 +37,9 @@ const BITMAP_BASE_OVERHEAD = 64;
  *
  * @param {Object} data - The data object to checksum
  * @param {import('../../ports/CryptoPort.js').default} crypto - CryptoPort instance
- * @returns {Promise<string|null>} Hex-encoded SHA-256 hash
+ * @returns {Promise<string>} Hex-encoded SHA-256 hash
  */
 const computeChecksum = async (data, crypto) => {
-  if (!crypto) { return null; }
   const json = canonicalStringify(data);
   return await crypto.hash('sha256', json);
 };
@@ -89,6 +89,8 @@ export default class StreamingBitmapIndexBuilder {
    *   Receives { flushedBytes, totalFlushedBytes, flushCount }.
    * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for structured logging.
    *   Defaults to NoOpLogger (no logging).
+   * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort instance for hashing
+   * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
    */
   constructor({ storage, maxMemoryBytes = DEFAULT_MAX_MEMORY_BYTES, onFlush, logger = nullLogger, crypto, codec }) {
     if (!storage) {
@@ -99,9 +101,9 @@ export default class StreamingBitmapIndexBuilder {
     }
 
     /** @type {import('../../ports/CryptoPort.js').default} */
-    this._crypto = crypto;
+    this._crypto = crypto || defaultCrypto;
 
-    /** @type {import('../../ports/CodecPort.js').default|undefined} */
+    /** @type {import('../../ports/CodecPort.js').default} */
     this._codec = codec || defaultCodec;
 
     /** @type {Object} */
@@ -122,7 +124,7 @@ export default class StreamingBitmapIndexBuilder {
     /** @type {string[]} ID → SHA reverse mapping (kept in memory) */
     this.idToSha = [];
 
-    /** @type {Map<string, RoaringBitmap32>} Current in-memory bitmaps */
+    /** @type {Map<string, any>} Current in-memory bitmaps */
     this.bitmaps = new Map();
 
     /** @type {number} Estimated bytes used by current bitmaps */
@@ -137,8 +139,8 @@ export default class StreamingBitmapIndexBuilder {
     /** @type {number} Number of flush operations performed */
     this.flushCount = 0;
 
-    /** @type {typeof import('roaring').RoaringBitmap32} Cached constructor */
-    this._RoaringBitmap32 = getRoaringBitmap32();
+    /** @type {any} Cached Roaring bitmap constructor */ // TODO(ts-cleanup): type lazy singleton
+    this._RoaringBitmap32 = getRoaringBitmap32(); // TODO(ts-cleanup): type lazy singleton
   }
 
   /**
@@ -189,11 +191,12 @@ export default class StreamingBitmapIndexBuilder {
    * Groups bitmaps by type ('fwd' or 'rev') and SHA prefix (first 2 hex chars).
    * Each bitmap is serialized to a portable format and base64-encoded.
    *
-   * @returns {{fwd: Object<string, Object<string, string>>, rev: Object<string, Object<string, string>>}}
+   * @returns {Record<string, Record<string, Record<string, string>>>}
    *   Object with 'fwd' and 'rev' keys, each mapping prefix to SHA→base64Bitmap entries
    * @private
    */
   _serializeBitmapsToShards() {
+    /** @type {Record<string, Record<string, Record<string, string>>>} */
     const bitmapShards = { fwd: {}, rev: {} };
     for (const [key, bitmap] of this.bitmaps) {
       const type = key.substring(0, 3);
@@ -215,7 +218,7 @@ export default class StreamingBitmapIndexBuilder {
    * The resulting blob OIDs are tracked in `flushedChunks` for later merging.
    * Writes are performed in parallel for efficiency.
    *
-   * @param {{fwd: Object<string, Object<string, string>>, rev: Object<string, Object<string, string>>}} bitmapShards
+   * @param {Record<string, Record<string, Record<string, string>>>} bitmapShards
    *   Object with 'fwd' and 'rev' keys containing prefix-grouped bitmap data
    * @returns {Promise<void>} Resolves when all shards have been written
    * @async
@@ -235,11 +238,11 @@ export default class StreamingBitmapIndexBuilder {
               data: shardData,
             };
             const buffer = Buffer.from(JSON.stringify(envelope));
-            const oid = await this.storage.writeBlob(buffer);
+            const oid = await /** @type {any} */ (this.storage).writeBlob(buffer); // TODO(ts-cleanup): narrow port type
             if (!this.flushedChunks.has(path)) {
               this.flushedChunks.set(path, []);
             }
-            this.flushedChunks.get(path).push(oid);
+            /** @type {string[]} */ (this.flushedChunks.get(path)).push(oid);
           })
         );
       }
@@ -310,6 +313,7 @@ export default class StreamingBitmapIndexBuilder {
    * @private
    */
   _buildMetaShards() {
+    /** @type {Record<string, Record<string, number>>} */
     const idShards = {};
     for (const [sha, id] of this.shaToId) {
       const prefix = sha.substring(0, 2);
@@ -344,7 +348,7 @@ export default class StreamingBitmapIndexBuilder {
           data: map,
         };
         const buffer = Buffer.from(JSON.stringify(envelope));
-        const oid = await this.storage.writeBlob(buffer);
+        const oid = await /** @type {any} */ (this.storage).writeBlob(buffer); // TODO(ts-cleanup): narrow port type
         return `100644 blob ${oid}\t${path}`;
       })
     );
@@ -436,18 +440,19 @@ export default class StreamingBitmapIndexBuilder {
 
     // Store frontier metadata for staleness detection
     if (frontier) {
+      /** @type {Record<string, number|undefined>} */
       const sorted = {};
       for (const key of Array.from(frontier.keys()).sort()) {
         sorted[key] = frontier.get(key);
       }
       const envelope = { version: 1, writerCount: frontier.size, frontier: sorted };
-      const cborOid = await this.storage.writeBlob(Buffer.from(this._codec.encode(envelope)));
+      const cborOid = await /** @type {any} */ (this.storage).writeBlob(Buffer.from(/** @type {any} */ (this._codec).encode(envelope))); // TODO(ts-cleanup): narrow port type
       flatEntries.push(`100644 blob ${cborOid}\tfrontier.cbor`);
-      const jsonOid = await this.storage.writeBlob(Buffer.from(canonicalStringify(envelope)));
+      const jsonOid = await /** @type {any} */ (this.storage).writeBlob(Buffer.from(canonicalStringify(envelope))); // TODO(ts-cleanup): narrow port type
       flatEntries.push(`100644 blob ${jsonOid}\tfrontier.json`);
     }
 
-    const treeOid = await this.storage.writeTree(flatEntries);
+    const treeOid = await /** @type {any} */ (this.storage).writeTree(flatEntries); // TODO(ts-cleanup): narrow port type
 
     this.logger.debug('Index finalized', {
       operation: 'finalize',
@@ -501,7 +506,7 @@ export default class StreamingBitmapIndexBuilder {
    */
   _getOrCreateId(sha) {
     if (this.shaToId.has(sha)) {
-      return this.shaToId.get(sha);
+      return /** @type {number} */ (this.shaToId.get(sha));
     }
     const id = this.idToSha.length;
     this.idToSha.push(sha);
@@ -564,7 +569,7 @@ export default class StreamingBitmapIndexBuilder {
    * @private
    */
   async _loadAndValidateChunk(oid) {
-    const buffer = await this.storage.readBlob(oid);
+    const buffer = await /** @type {any} */ (this.storage).readBlob(oid); // TODO(ts-cleanup): narrow port type
     let envelope;
     try {
       envelope = JSON.parse(buffer.toString('utf-8'));
@@ -572,14 +577,13 @@ export default class StreamingBitmapIndexBuilder {
       throw new ShardCorruptionError('Failed to parse shard JSON', {
         oid,
         reason: 'invalid_format',
-        originalError: err.message,
+        context: { originalError: /** @type {any} */ (err).message }, // TODO(ts-cleanup): type error
       });
     }
 
     // Validate version
     if (envelope.version !== SHARD_VERSION) {
       throw new ShardValidationError('Shard version mismatch', {
-        oid,
         expected: SHARD_VERSION,
         actual: envelope.version,
         field: 'version',
@@ -610,7 +614,7 @@ export default class StreamingBitmapIndexBuilder {
    * it using `orInPlace` to combine edge sets.
    *
    * @param {Object} opts - Options object
-   * @param {Object<string, RoaringBitmap32>} opts.merged - Object mapping SHA to
+   * @param {Record<string, any>} opts.merged - Object mapping SHA to
    *   RoaringBitmap32 instances (mutated in place)
    * @param {string} opts.sha - The SHA key for this bitmap (40-character hex string)
    * @param {string} opts.base64Bitmap - Base64-encoded serialized RoaringBitmap32 data
@@ -627,7 +631,7 @@ export default class StreamingBitmapIndexBuilder {
       throw new ShardCorruptionError('Failed to deserialize bitmap', {
         oid,
         reason: 'invalid_bitmap',
-        originalError: err.message,
+        context: { originalError: /** @type {any} */ (err).message }, // TODO(ts-cleanup): type error
       });
     }
 
@@ -671,6 +675,7 @@ export default class StreamingBitmapIndexBuilder {
    */
   async _mergeChunks(oids, { signal } = {}) {
     // Load all chunks and merge bitmaps by SHA
+    /** @type {Record<string, any>} */
     const merged = {};
 
     for (const oid of oids) {
@@ -683,6 +688,7 @@ export default class StreamingBitmapIndexBuilder {
     }
 
     // Serialize merged result
+    /** @type {Record<string, string>} */
     const result = {};
     for (const [sha, bitmap] of Object.entries(merged)) {
       result[sha] = bitmap.serialize(true).toString('base64');
@@ -701,9 +707,9 @@ export default class StreamingBitmapIndexBuilder {
     } catch (err) {
       throw new ShardCorruptionError('Failed to serialize merged shard', {
         reason: 'serialization_error',
-        originalError: err.message,
+        context: { originalError: /** @type {any} */ (err).message }, // TODO(ts-cleanup): type error
       });
     }
-    return this.storage.writeBlob(serialized);
+    return /** @type {any} */ (this.storage).writeBlob(serialized); // TODO(ts-cleanup): narrow port type
   }
 }

package/src/domain/services/SyncProtocol.js

@@ -56,18 +56,16 @@ import { vvDeserialize } from '../crdt/VersionVector.js';
  * **Mutation**: This function mutates the input patch object for efficiency.
  * The original object reference is returned.
  *
- * @param {Object} patch - The raw decoded patch from CBOR
- * @param {Object|Map} [patch.context] - The causal context (version vector).
- *   If present as a plain object, will be converted to a Map.
- * @param {Array} patch.ops - The patch operations (not modified)
- * @returns {Object} The same patch object with context converted to Map
+ * @param {{ context?: Object | Map<any, any>, ops: any[] }} patch - The raw decoded patch from CBOR.
+ *   If context is present as a plain object, it will be converted to a Map.
+ * @returns {{ context?: Object | Map<any, any>, ops: any[] }} The same patch object with context converted to Map
  * @private
  */
 function normalizePatch(patch) {
   // Convert context from plain object to Map (VersionVector)
   // CBOR deserialization returns plain objects, but join() expects a Map
   if (patch.context && !(patch.context instanceof Map)) {
-    patch.context = vvDeserialize(patch.context);
+    patch.context = vvDeserialize(/** @type {{ [x: string]: number }} */ (patch.context));
   }
   return patch;
 }
@@ -85,12 +83,12 @@ function normalizePatch(patch) {
  * **Commit message format**: The message is encoded using WarpMessageCodec
  * and contains metadata (schema version, writer info) plus the patch OID.
  *
- * @param {import('../../ports/GraphPersistencePort.js').default} persistence - Git persistence layer
+ * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default} persistence - Git persistence layer
  *   (uses CommitPort.showNode() + BlobPort.readBlob() methods)
  * @param {string} sha - The 40-character commit SHA to load the patch from
  * @param {Object} [options]
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
- * @returns {Promise<Object>} The decoded and normalized patch object containing:
+ * @returns {Promise<{ context?: Object | Map<any, any>, ops: any[] }>} The decoded and normalized patch object containing:
  *   - `ops`: Array of patch operations
  *   - `context`: VersionVector (Map) of causal dependencies
  *   - `writerId`: The writer who created this patch
@@ -101,7 +99,7 @@ function normalizePatch(patch) {
  * @throws {Error} If the patch blob cannot be CBOR-decoded (corrupted data)
  * @private
  */
-async function loadPatchFromCommit(persistence, sha, { codec: codecOpt } = {}) {
+async function loadPatchFromCommit(persistence, sha, { codec: codecOpt } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   const codec = codecOpt || defaultCodec;
   // Read commit message to extract patch OID
   const message = await persistence.showNode(sha);
@@ -109,7 +107,7 @@ async function loadPatchFromCommit(persistence, sha, { codec: codecOpt } = {}) {
 
   // Read and decode the patch blob
   const patchBuffer = await persistence.readBlob(decoded.patchOid);
-  const patch = codec.decode(patchBuffer);
+  const patch = /** @type {{ context?: Object | Map<any, any>, ops: any[] }} */ (codec.decode(patchBuffer));
 
   // Normalize the patch (convert context from object to Map)
   return normalizePatch(patch);
@@ -129,7 +127,7 @@ async function loadPatchFromCommit(persistence, sha, { codec: codecOpt } = {}) {
  * **Performance**: O(N) where N is the number of commits between fromSha and toSha.
  * Each commit requires two reads: commit info (for parent) and patch blob.
  *
- * @param {import('../../ports/GraphPersistencePort.js').default} persistence - Git persistence layer
+ * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default} persistence - Git persistence layer
  *   (uses CommitPort.getNodeInfo()/showNode() + BlobPort.readBlob() methods)
  * @param {string} graphName - Graph name (used in error messages, not for lookups)
  * @param {string} writerId - Writer ID (used in error messages, not for lookups)
@@ -154,7 +152,7 @@ async function loadPatchFromCommit(persistence, sha, { codec: codecOpt } = {}) {
  * // Load ALL patches for a new writer
  * const patches = await loadPatchRange(persistence, 'events', 'new-writer', null, tipSha);
  */
-export async function loadPatchRange(persistence, graphName, writerId, fromSha, toSha, { codec } = {}) {
+export async function loadPatchRange(persistence, graphName, writerId, fromSha, toSha, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   const patches = [];
   let cur = toSha;
 
@@ -172,9 +170,9 @@ export async function loadPatchRange(persistence, graphName, writerId, fromSha,
 
   // If fromSha was specified but we didn't reach it, we have divergence
   if (fromSha && cur === null) {
-    const err = new Error(
+    const err = /** @type {Error & { code: string }} */ (new Error(
       `Divergence detected: ${toSha} does not descend from ${fromSha} for writer ${writerId}`
-    );
+    ));
     err.code = 'E_SYNC_DIVERGENCE';
     throw err;
   }
@@ -214,11 +212,7 @@ export async function loadPatchRange(persistence, graphName, writerId, fromSha,
  *   Maps writerId to the SHA of their latest patch commit.
  * @param {Map<string, string>} remoteFrontier - Remote writer heads.
  *   Maps writerId to the SHA of their latest patch commit.
- * @returns {Object} Sync delta containing:
- *   - `needFromRemote`: Map<writerId, {from: string|null, to: string}> - Patches local needs
- *   - `needFromLocal`: Map<writerId, {from: string|null, to: string}> - Patches remote needs
- *   - `newWritersForLocal`: string[] - Writers that local has never seen
- *   - `newWritersForRemote`: string[] - Writers that remote has never seen
+ * @returns {{ needFromRemote: Map<string, {from: string|null, to: string}>, needFromLocal: Map<string, {from: string|null, to: string}>, newWritersForLocal: string[], newWritersForRemote: string[] }} Sync delta
  *
  * @example
  * const local = new Map([['w1', 'sha-a'], ['w2', 'sha-b']]);
@@ -333,13 +327,14 @@ export function computeSyncDelta(localFrontier, remoteFrontier) {
  */
 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: 'sync-request',
+    type: /** @type {'sync-request'} */ ('sync-request'),
     frontier: frontierObj,
   };
 }
@@ -363,7 +358,7 @@ export function createSyncRequest(frontier) {
  *
  * @param {SyncRequest} request - Incoming sync request containing the requester's frontier
  * @param {Map<string, string>} localFrontier - Local frontier (what this node has)
- * @param {import('../../ports/GraphPersistencePort.js').default} persistence - Git persistence
+ * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default} persistence - Git persistence
  *   layer for loading patches (uses CommitPort + BlobPort methods)
  * @param {string} graphName - Graph name for error messages and logging
  * @returns {Promise<SyncResponse>} Response containing local frontier and patches.
@@ -379,7 +374,7 @@ export function createSyncRequest(frontier) {
  *   res.json(response);
  * });
  */
-export async function processSyncRequest(request, localFrontier, persistence, graphName, { codec } = {}) {
+export async function processSyncRequest(request, localFrontier, persistence, graphName, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
   // Convert incoming frontier from object to Map
   const remoteFrontier = new Map(Object.entries(request.frontier));
 
@@ -406,7 +401,7 @@ export async function processSyncRequest(request, localFrontier, persistence, gr
     } catch (err) {
       // If we detect divergence, skip this writer
       // The requester may need to handle this separately
-      if (err.code === 'E_SYNC_DIVERGENCE' || err.message.includes('Divergence detected')) {
+      if (/** @type {any} */ (err).code === 'E_SYNC_DIVERGENCE' || /** @type {any} */ (err).message?.includes('Divergence detected')) { // TODO(ts-cleanup): type error
         continue;
       }
       throw err;
@@ -414,13 +409,14 @@ export async function processSyncRequest(request, localFrontier, persistence, gr
   }
 
   // Convert local frontier to plain object
+  /** @type {{ [x: string]: string }} */
   const frontierObj = {};
   for (const [writerId, sha] of localFrontier) {
     frontierObj[writerId] = sha;
   }
 
   return {
-    type: 'sync-response',
+    type: /** @type {'sync-response'} */ ('sync-response'),
     frontier: frontierObj,
     patches,
   };
@@ -495,7 +491,7 @@ export function applySyncResponse(response, state, frontier) {
       // will prevent silent data loss until the reader is upgraded.
       assertOpsCompatible(normalizedPatch.ops, SCHEMA_V3);
       // Apply patch to state
-      join(newState, normalizedPatch, sha);
+      join(newState, /** @type {*} */ (normalizedPatch), sha); // TODO(ts-cleanup): type patch array
       applied++;
     }
 
@@ -580,13 +576,14 @@ 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: 'sync-response',
+    type: /** @type {'sync-response'} */ ('sync-response'),
     frontier: frontierObj,
     patches: [],
   };

package/src/domain/services/TemporalQuery.js

@@ -60,10 +60,11 @@ function unwrapValue(value) {
  *
  * @param {import('./JoinReducer.js').WarpStateV5} state - Current state
  * @param {string} nodeId - Node ID to extract
- * @returns {{ id: string, exists: boolean, props: Object<string, *> }}
+ * @returns {{ id: string, exists: boolean, props: Record<string, *> }}
  */
 function extractNodeSnapshot(state, nodeId) {
   const exists = orsetContains(state.nodeAlive, nodeId);
+  /** @type {Record<string, *>} */
   const props = {};
 
   if (exists) {
@@ -108,7 +109,7 @@ export class TemporalQuery {
    * @param {string} nodeId - The node ID to evaluate
    * @param {Function} predicate - Predicate receiving node snapshot
    *   `{ id, exists, props }`. Should return boolean.
-   * @param {{ since?: number }} [options={}] - Options
+   * @param {Object} [options={}] - Options
    * @param {number} [options.since=0] - Minimum Lamport tick (inclusive).
    *   Only patches with lamport >= since are considered.
    * @returns {Promise<boolean>} True if predicate held at every tick
@@ -161,7 +162,7 @@ export class TemporalQuery {
    * @param {string} nodeId - The node ID to evaluate
    * @param {Function} predicate - Predicate receiving node snapshot
    *   `{ id, exists, props }`. Should return boolean.
-   * @param {{ since?: number }} [options={}] - Options
+   * @param {Object} [options={}] - Options
    * @param {number} [options.since=0] - Minimum Lamport tick (inclusive).
    *   Only patches with lamport >= since are considered.
    * @returns {Promise<boolean>} True if predicate held at any tick

package/src/domain/services/TranslationCost.js

@@ -94,8 +94,8 @@ function zeroCost() {
 /**
  * Counts how many items in `source` are absent from `targetSet`.
  *
- * @param {Array|Set} source - Source collection
- * @param {Set} targetSet - Target set to test against
+ * @param {Array<string>|Set<string>} source - Source collection
+ * @param {Set<string>} targetSet - Target set to test against
  * @returns {number}
  */
 function countMissing(source, targetSet) {
@@ -141,7 +141,7 @@ function computeEdgeLoss(state, nodesASet, nodesBSet) {
  * Counts lost properties for a single node between two observer configs.
  *
  * @param {Map<string, boolean>} nodeProps - Property keys for the node
- * @param {{ configA: Object, configB: Object, nodeInB: boolean }} opts
+ * @param {{ configA: {expose?: string[], redact?: string[]}, configB: {expose?: string[], redact?: string[]}, nodeInB: boolean }} opts
  * @returns {{ propsInA: number, lostProps: number }}
  */
 function countNodePropLoss(nodeProps, { configA, configB, nodeInB }) {
@@ -157,7 +157,7 @@ function countNodePropLoss(nodeProps, { configA, configB, nodeInB }) {
  * Computes property loss across all A-visible nodes.
  *
  * @param {*} state - WarpStateV5
- * @param {{ nodesA: string[], nodesBSet: Set<string>, configA: Object, configB: Object }} opts
+ * @param {{ nodesA: string[], nodesBSet: Set<string>, configA: {expose?: string[], redact?: string[]}, configB: {expose?: string[], redact?: string[]} }} opts
  * @returns {number} propLoss fraction
  */
 function computePropLoss(state, { nodesA, nodesBSet, configA, configB }) {

package/src/domain/services/WormholeService.js

@@ -43,7 +43,7 @@ function validateSha(sha, paramName) {
 
 /**
  * Verifies that a SHA exists in the repository.
- * @param {Object} persistence - Git persistence adapter
+ * @param {{ nodeExists: (sha: string) => Promise<boolean> }} persistence - Git persistence adapter
  * @param {string} sha - The SHA to verify
  * @param {string} paramName - Parameter name for error messages
  * @throws {WormholeError} If SHA doesn't exist
@@ -62,10 +62,11 @@ async function verifyShaExists(persistence, sha, paramName) {
 /**
  * Processes a single commit in the wormhole chain.
  * @param {Object} opts - Options
- * @param {Object} opts.persistence - Git persistence adapter
+ * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default} opts.persistence - Git persistence adapter
  * @param {string} opts.sha - The commit SHA
  * @param {string} opts.graphName - Expected graph name
  * @param {string|null} opts.expectedWriter - Expected writer ID (null for first commit)
+ * @param {import('../../ports/CodecPort.js').default} [opts.codec] - Codec for deserialization
  * @returns {Promise<{patch: Object, sha: string, writerId: string, parentSha: string|null}>}
  * @throws {WormholeError} On validation errors
  * @private
@@ -100,7 +101,7 @@ async function processCommit({ persistence, sha, graphName, expectedWriter, code
   }
 
   const patchBuffer = await persistence.readBlob(patchMeta.patchOid);
-  const patch = codec.decode(patchBuffer);
+  const patch = /** @type {Object} */ (codec.decode(patchBuffer));
 
   return {
     patch,
@@ -135,10 +136,11 @@ async function processCommit({ persistence, sha, graphName, expectedWriter, code
  * are inclusive in the wormhole.
  *
  * @param {Object} options - Wormhole creation options
- * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Git persistence adapter
+ * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default} options.persistence - Git persistence adapter
  * @param {string} options.graphName - Name of the graph
  * @param {string} options.fromSha - SHA of the first (oldest) patch commit
  * @param {string} options.toSha - SHA of the last (newest) patch commit
+ * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
  * @returns {Promise<WormholeEdge>} The created wormhole
  * @throws {WormholeError} If fromSha or toSha doesn't exist (E_WORMHOLE_SHA_NOT_FOUND)
  * @throws {WormholeError} If fromSha is not an ancestor of toSha (E_WORMHOLE_INVALID_RANGE)
@@ -156,7 +158,7 @@ export async function createWormhole({ persistence, graphName, fromSha, toSha, c
   // Reverse to get oldest-first order (as required by ProvenancePayload)
   patches.reverse();
 
-  const writerId = patches.length > 0 ? patches[0].writerId : null;
+  const writerId = patches.length > 0 ? patches[0].writerId : /** @type {string} */ ('');
   // Strip writerId to match ProvenancePayload's PatchEntry typedef ({patch, sha})
   const payload = new ProvenancePayload(patches.map(({ patch, sha }) => ({ patch, sha })));
 
@@ -170,10 +172,11 @@ export async function createWormhole({ persistence, graphName, fromSha, toSha, c
  * validating each commit along the way.
  *
  * @param {Object} options
- * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Git persistence adapter
+ * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default} options.persistence - Git persistence adapter
  * @param {string} options.graphName - Expected graph name
  * @param {string} options.fromSha - SHA of the first (oldest) patch commit
  * @param {string} options.toSha - SHA of the last (newest) patch commit
+ * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
  * @returns {Promise<Array<{patch: Object, sha: string, writerId: string}>>} Patches in newest-first order
  * @throws {WormholeError} If fromSha is not an ancestor of toSha or range is empty
  * @private
@@ -230,7 +233,7 @@ async function collectPatchRange({ persistence, graphName, fromSha, toSha, codec
  * @param {WormholeEdge} first - The earlier (older) wormhole
  * @param {WormholeEdge} second - The later (newer) wormhole
  * @param {Object} [options] - Composition options
- * @param {import('../../ports/GraphPersistencePort.js').default} [options.persistence] - Git persistence adapter (for validation)
+ * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default} [options.persistence] - Git persistence adapter (for validation)
  * @returns {Promise<WormholeEdge>} The composed wormhole
  * @throws {WormholeError} If wormholes are from different writers (E_WORMHOLE_MULTI_WRITER)
  * @throws {WormholeError} If wormholes are not consecutive (E_WORMHOLE_INVALID_RANGE)
@@ -318,9 +321,10 @@ export function deserializeWormhole(json) {
     });
   }
 
+  const /** @type {Record<string, *>} */ typedJson = /** @type {Record<string, *>} */ (json);
   const requiredFields = ['fromSha', 'toSha', 'writerId', 'patchCount', 'payload'];
   for (const field of requiredFields) {
-    if (json[field] === undefined) {
+    if (typedJson[field] === undefined) {
       throw new WormholeError(`Invalid wormhole JSON: missing required field '${field}'`, {
         code: 'E_INVALID_WORMHOLE_JSON',
         context: { missingField: field },
@@ -328,19 +332,19 @@ export function deserializeWormhole(json) {
     }
   }
 
-  if (typeof json.patchCount !== 'number' || json.patchCount < 0) {
+  if (typeof typedJson.patchCount !== 'number' || typedJson.patchCount < 0) {
     throw new WormholeError('Invalid wormhole JSON: patchCount must be a non-negative number', {
       code: 'E_INVALID_WORMHOLE_JSON',
-      context: { patchCount: json.patchCount },
+      context: { patchCount: typedJson.patchCount },
     });
   }
 
   return {
-    fromSha: json.fromSha,
-    toSha: json.toSha,
-    writerId: json.writerId,
-    patchCount: json.patchCount,
-    payload: ProvenancePayload.fromJSON(json.payload),
+    fromSha: typedJson.fromSha,
+    toSha: typedJson.toSha,
+    writerId: typedJson.writerId,
+    patchCount: typedJson.patchCount,
+    payload: ProvenancePayload.fromJSON(typedJson.payload),
   };
 }
 

package/src/domain/types/TickReceipt.js

@@ -67,11 +67,12 @@ function validateOp(op, index) {
     throw new Error(`ops[${index}] must be an object`);
   }
 
-  validateOpType(op.op, index);
-  validateOpTarget(op.target, index);
-  validateOpResult(op.result, index);
+  const entry = /** @type {Record<string, *>} */ (op);
+  validateOpType(entry.op, index);
+  validateOpTarget(entry.target, index);
+  validateOpResult(entry.result, index);
 
-  if (op.reason !== undefined && typeof op.reason !== 'string') {
+  if (entry.reason !== undefined && typeof entry.reason !== 'string') {
     throw new Error(`ops[${index}].reason must be a string or undefined`);
   }
 }
@@ -208,6 +209,7 @@ export function createTickReceipt({ patchSha, writer, lamport, ops }) {
   // Build frozen op copies (defensive: don't alias caller's objects)
   const frozenOps = Object.freeze(
     ops.map((o) => {
+      /** @type {{ op: string, target: string, result: 'applied' | 'superseded' | 'redundant', reason?: string }} */
       const entry = { op: o.op, target: o.target, result: o.result };
       if (o.reason !== undefined) {
         entry.reason = o.reason;
@@ -275,9 +277,11 @@ export function canonicalJson(receipt) {
  */
 function sortedReplacer(_key, value) {
   if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    /** @type {{ [x: string]: * }} */
     const sorted = {};
-    for (const k of Object.keys(value).sort()) {
-      sorted[k] = value[k];
+    const obj = /** @type {{ [x: string]: * }} */ (value);
+    for (const k of Object.keys(obj).sort()) {
+      sorted[k] = obj[k];
     }
     return sorted;
   }