@git-stunts/git-warp 12.3.0 → 12.4.1

package/src/domain/services/ProvenancePayload.js

@@ -22,7 +22,7 @@ import { reduceV5, createEmptyStateV5, cloneStateV5 } from './JoinReducer.js';
  * A single patch entry in the provenance payload.
  *
  * @typedef {Object} PatchEntry
- * @property {Object} patch - The decoded patch object (writer, lamport, ops, context)
+ * @property {import('../types/WarpTypesV2.js').PatchV2} patch - The decoded patch object
  * @property {string} sha - The Git SHA of the patch commit
  */
 

package/src/domain/services/QueryBuilder.js

@@ -307,11 +307,7 @@ function buildEdgesSnapshot(edges, directionKey) {
  * The snapshot includes the node's ID, properties, outgoing edges, and incoming edges.
  * All data is deeply frozen to prevent mutation.
  *
- * @param {Object} params - Node data
- * @param {string} params.id - The node ID
- * @param {Map<string, unknown>} params.propsMap - Map of property names to values
- * @param {Array<{label: string, neighborId: string}>} params.edgesOut - Outgoing edges
- * @param {Array<{label: string, neighborId: string}>} params.edgesIn - Incoming edges
+ * @param {{ id: string, propsMap: Map<string, unknown>, edgesOut: Array<{label: string, neighborId: string}>, edgesIn: Array<{label: string, neighborId: string}> }} params - Node data
  * @returns {Readonly<QueryNodeSnapshot>} Frozen node snapshot
  * @private
  */
@@ -385,11 +381,7 @@ function normalizeDepth(depth) {
  * Collects all neighbors reachable via one edge in the specified direction,
  * optionally filtered by edge label.
  *
- * @param {Object} params - Traversal parameters
- * @param {'outgoing' | 'incoming'} params.direction - Direction of traversal
- * @param {string | undefined} params.label - Edge label filter (undefined = all labels)
- * @param {string[]} params.workingSet - Current set of node IDs to traverse from
- * @param {AdjacencyMaps} params.adjacency - Adjacency maps from materialized state
+ * @param {{ direction: 'outgoing' | 'incoming', label: string | undefined, workingSet: string[], adjacency: AdjacencyMaps }} params - Traversal parameters
  * @returns {string[]} Sorted array of neighbor node IDs
  * @private
  */
@@ -420,12 +412,7 @@ function applyHop({ direction, label, workingSet, adjacency }) {
  *
  * If minDepth is 0, the starting nodes themselves are included in the result.
  *
- * @param {Object} params - Traversal parameters
- * @param {'outgoing' | 'incoming'} params.direction - Direction of traversal
- * @param {string | undefined} params.label - Edge label filter (undefined = all labels)
- * @param {string[]} params.workingSet - Current set of node IDs to traverse from
- * @param {AdjacencyMaps} params.adjacency - Adjacency maps from materialized state
- * @param {[number, number]} params.depth - Tuple of [minDepth, maxDepth]
+ * @param {{ direction: 'outgoing' | 'incoming', label: string | undefined, workingSet: string[], adjacency: AdjacencyMaps, depth: [number, number] }} params - Traversal parameters
  * @returns {string[]} Sorted array of reachable node IDs within the depth range
  * @private
  */

package/src/domain/services/StateDiff.js

@@ -38,15 +38,9 @@ import { decodeEdgeKey, decodePropKey, isEdgePropKey } from './KeyCodec.js';
 
 /**
  * @typedef {Object} StateDiffResult
- * @property {Object} nodes - Node changes
- * @property {string[]} nodes.added - Added node IDs (sorted)
- * @property {string[]} nodes.removed - Removed node IDs (sorted)
- * @property {Object} edges - Edge changes
- * @property {EdgeChange[]} edges.added - Added edges (sorted)
- * @property {EdgeChange[]} edges.removed - Removed edges (sorted)
- * @property {Object} props - Property changes
- * @property {PropSet[]} props.set - Set/changed properties (sorted)
- * @property {PropRemoved[]} props.removed - Removed properties (sorted)
+ * @property {{ added: string[], removed: string[] }} nodes - Node changes
+ * @property {{ added: EdgeChange[], removed: EdgeChange[] }} edges - Edge changes
+ * @property {{ set: PropSet[], removed: PropRemoved[] }} props - Property changes
  */
 
 /**

package/src/domain/services/StateSerializerV5.js

@@ -74,9 +74,8 @@ export function propVisibleV5(state, propKey) {
  * Same canonical ordering as v4 for visible projection.
  *
  * @param {import('./JoinReducer.js').WarpStateV5} state
- * @param {Object} [options]
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
- * @returns {Buffer|Uint8Array}
+ * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
+ * @returns {Uint8Array}
  */
 export function serializeStateV5(state, { codec } = {}) {
   const c = codec || defaultCodec;
@@ -119,15 +118,17 @@ export function serializeStateV5(state, { codec } = {}) {
   return c.encode({ nodes, edges: visibleEdges, props: visibleProps });
 }
 
+/**
+ * @typedef {{ crypto?: import('../../ports/CryptoPort.js').default, codec?: import('../../ports/CodecPort.js').default }} StateHashOptions
+ */
+
 /**
  * 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/CodecPort.js').default} [options.codec] - Codec for serialization
+ * @param {StateHashOptions} [options] - Options
  * @returns {Promise<string>} Hex-encoded SHA-256 hash
  */
-export async function computeStateHashV5(state, { crypto, codec } = /** @type {{crypto?: import('../../ports/CryptoPort.js').default, codec?: import('../../ports/CodecPort.js').default}} */ ({})) {
+export async function computeStateHashV5(state, { crypto, codec } = /** @type {StateHashOptions} */ ({})) {
   const c = crypto || defaultCrypto;
   const serialized = serializeStateV5(state, { codec });
   return await c.hash('sha256', serialized);
@@ -136,9 +137,8 @@ export async function computeStateHashV5(state, { crypto, codec } = /** @type {{
 /**
  * Deserializes state from CBOR bytes.
  * Note: This reconstructs the visible projection only.
- * @param {Buffer} buffer
- * @param {Object} [options]
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
+ * @param {Uint8Array} buffer
+ * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
  * @returns {{nodes: string[], edges: Array<{from: string, to: string, label: string}>, props: Array<{node: string, key: string, value: unknown}>}}
  */
 export function deserializeStateV5(buffer, { codec } = {}) {

package/src/domain/services/StreamingBitmapIndexBuilder.js

@@ -37,7 +37,7 @@ const BITMAP_BASE_OVERHEAD = 64;
  * Uses canonical JSON stringification for deterministic output
  * across different JavaScript engines.
  *
- * @param {Object} data - The data object to checksum
+ * @param {Record<string, unknown>} data - The data object to checksum
  * @param {import('../../ports/CryptoPort.js').default} crypto - CryptoPort instance
  * @returns {Promise<string>} Hex-encoded SHA-256 hash
  */
@@ -82,17 +82,7 @@ export default class StreamingBitmapIndexBuilder {
   /**
    * Creates a new StreamingBitmapIndexBuilder instance.
    *
-   * @param {Object} options - Configuration options
-   * @param {import('../../ports/IndexStoragePort.js').default} options.storage - Storage adapter implementing IndexStoragePort.
-   *   Required methods: writeBlob, writeTree, readBlob
-   * @param {number} [options.maxMemoryBytes=52428800] - Maximum bitmap memory before flush (default 50MB).
-   *   Note: SHA→ID mappings are not counted against this limit as they must remain in memory.
-   * @param {Function} [options.onFlush] - Optional callback invoked on each flush.
-   *   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
+   * @param {{ storage: import('../../ports/IndexStoragePort.js').default, maxMemoryBytes?: number, onFlush?: (stats: {flushedBytes: number, totalFlushedBytes: number, flushCount: number}) => void, logger?: import('../../ports/LoggerPort.js').default, crypto?: import('../../ports/CryptoPort.js').default, codec?: import('../../ports/CodecPort.js').default }} options - Configuration options
    */
   constructor({ storage, maxMemoryBytes = DEFAULT_MAX_MEMORY_BYTES, onFlush, logger = nullLogger, crypto, codec }) {
     if (!storage) {
@@ -114,7 +104,7 @@ export default class StreamingBitmapIndexBuilder {
     /** @type {number} */
     this.maxMemoryBytes = maxMemoryBytes;
 
-    /** @type {Function|undefined} */
+    /** @type {((stats: {flushedBytes: number, totalFlushedBytes: number, flushCount: number}) => void)|undefined} */
     this.onFlush = onFlush;
 
     /** @type {import('../../ports/LoggerPort.js').default} */
@@ -310,7 +300,7 @@ export default class StreamingBitmapIndexBuilder {
    * of the SHA. This enables efficient loading of only relevant shards
    * during index reads.
    *
-   * @returns {Object<string, Object<string, number>>} Object mapping 2-char hex prefix
+   * @returns {Record<string, Record<string, number>>} Object mapping 2-char hex prefix
    *   to objects of SHA→numeric ID mappings
    * @private
    */
@@ -333,7 +323,7 @@ export default class StreamingBitmapIndexBuilder {
    * Each shard is wrapped in a versioned envelope with checksum before writing.
    * Writes are performed in parallel using Promise.all for efficiency.
    *
-   * @param {Object<string, Object<string, number>>} idShards - Object mapping 2-char hex prefix
+   * @param {Record<string, Record<string, number>>} idShards - Object mapping 2-char hex prefix
    *   to objects of SHA→numeric ID mappings
    * @returns {Promise<string[]>} Array of Git tree entry strings in format
    *   "100644 blob <oid>\tmeta_<prefix>.json"
@@ -365,9 +355,7 @@ export default class StreamingBitmapIndexBuilder {
    *
    * Processing is parallelized across shard paths for efficiency.
    *
-   * @param {Object} [options] - Options
-   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation.
-   *   If aborted, throws an error with code 'ABORT_ERR'.
+   * @param {{ signal?: AbortSignal }} [options] - Options
    * @returns {Promise<string[]>} Array of Git tree entry strings in format
    *   "100644 blob <oid>\tshards_<type>_<prefix>.json"
    * @throws {Error} If the operation is aborted via signal
@@ -409,12 +397,7 @@ export default class StreamingBitmapIndexBuilder {
    *   frontier.json                       # Optional: JSON-encoded frontier
    * ```
    *
-   * @param {Object} [options] - Finalization options
-   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation.
-   *   If aborted, throws an error with code 'ABORT_ERR'.
-   * @param {Map<string, string>} [options.frontier] - Optional writer frontier
-   *   (writerId → tip SHA) for staleness detection. If provided, frontier.cbor and
-   *   frontier.json files are included in the tree.
+   * @param {{ signal?: AbortSignal, frontier?: Map<string, string> }} [options] - Finalization options
    * @returns {Promise<string>} OID of the created Git tree containing the complete index
    * @throws {Error} If the operation is aborted via signal
    * @throws {ShardValidationError} If a chunk has an unsupported version during merge
@@ -472,7 +455,7 @@ export default class StreamingBitmapIndexBuilder {
    * Useful for understanding memory pressure during index building and
    * tuning the `maxMemoryBytes` threshold.
    *
-   * @returns {Object} Memory statistics object
+   * @returns {{estimatedBitmapBytes: number, estimatedMappingBytes: number, totalFlushedBytes: number, flushCount: number, nodeCount: number, bitmapCount: number}} Memory statistics object
    * @property {number} estimatedBitmapBytes - Current estimated size of in-memory bitmaps in bytes.
    *   This is an approximation based on bitmap operations; actual memory usage may vary.
    * @property {number} estimatedMappingBytes - Estimated size of SHA→ID mappings in bytes.
@@ -527,11 +510,7 @@ export default class StreamingBitmapIndexBuilder {
    * - New bitmap: adds BITMAP_BASE_OVERHEAD (64 bytes)
    * - New entry in existing bitmap: adds ~4 bytes (approximation)
    *
-   * @param {Object} opts - Options object
-   * @param {string} opts.sha - The SHA to use as bitmap key (40-character hex string)
-   * @param {number} opts.id - The numeric ID to add to the bitmap
-   * @param {'fwd'|'rev'} opts.type - Edge direction type: 'fwd' for forward edges
-   *   (this node's children), 'rev' for reverse edges (this node's parents)
+   * @param {{ sha: string, id: number, type: 'fwd'|'rev' }} opts - Options object
    * @private
    */
   _addToBitmap({ sha, id, type }) {
@@ -562,7 +541,7 @@ export default class StreamingBitmapIndexBuilder {
    * 4. Recomputes and validates checksum (throws ShardCorruptionError if mismatch)
    *
    * @param {string} oid - Git blob OID of the chunk to load (40-character hex string)
-   * @returns {Promise<Object<string, string>>} The validated chunk data (SHA→base64Bitmap mappings)
+   * @returns {Promise<Record<string, string>>} The validated chunk data (SHA→base64Bitmap mappings)
    * @throws {ShardCorruptionError} If the chunk cannot be parsed as JSON or checksum is invalid.
    *   Error context includes: oid, reason ('invalid_format' or 'invalid_checksum'), originalError
    * @throws {ShardValidationError} If the chunk has an unsupported version.
@@ -574,7 +553,7 @@ export default class StreamingBitmapIndexBuilder {
     const buffer = await this.storage.readBlob(oid);
     let envelope;
     try {
-      envelope = JSON.parse(buffer.toString('utf-8'));
+      envelope = JSON.parse(new TextDecoder().decode(buffer));
     } catch (err) {
       throw new ShardCorruptionError('Failed to parse shard JSON', {
         oid,
@@ -615,12 +594,7 @@ export default class StreamingBitmapIndexBuilder {
    * is stored directly. If a bitmap already exists, the new bitmap is ORed into
    * it using `orInPlace` to combine edge sets.
    *
-   * @param {Object} opts - Options object
-   * @param {Record<string, import('../utils/roaring.js').RoaringBitmapSubset>} 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
-   * @param {string} opts.oid - Git blob OID of the source chunk (for error reporting)
+   * @param {{ merged: Record<string, import('../utils/roaring.js').RoaringBitmapSubset>, sha: string, base64Bitmap: string, oid: string }} opts - Options object
    * @throws {ShardCorruptionError} If the bitmap cannot be deserialized from base64.
    *   Error context includes: oid, reason ('invalid_bitmap'), originalError
    * @private
@@ -662,9 +636,7 @@ export default class StreamingBitmapIndexBuilder {
    * Supports cancellation via AbortSignal between chunk processing iterations.
    *
    * @param {string[]} oids - Git blob OIDs of chunks to merge (40-character hex strings)
-   * @param {Object} [options] - Options object
-   * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation.
-   *   Checked between chunk iterations; if aborted, throws with code 'ABORT_ERR'.
+   * @param {{ signal?: AbortSignal }} [options] - Options object
    * @returns {Promise<string>} Git blob OID of the merged shard (40-character hex string)
    * @throws {Error} If the operation is aborted via signal
    * @throws {ShardValidationError} If a chunk has an unsupported version.

package/src/domain/services/SyncAuthService.js

@@ -38,14 +38,7 @@ export function canonicalizePath(url) {
 /**
  * Builds the canonical string that gets signed.
  *
- * @param {Object} params
- * @param {string} params.keyId - Key identifier
- * @param {string} params.method - HTTP method (uppercased by caller)
- * @param {string} params.path - Canonical path
- * @param {string} params.timestamp - Epoch milliseconds as string
- * @param {string} params.nonce - UUIDv4 nonce
- * @param {string} params.contentType - Content-Type header value
- * @param {string} params.bodySha256 - Hex SHA-256 of request body
+ * @param {{ keyId: string, method: string, path: string, timestamp: string, nonce: string, contentType: string, bodySha256: string }} params
  * @returns {string} Pipe-delimited canonical payload
  */
 export function buildCanonicalPayload({ keyId, method, path, timestamp, nonce, contentType, bodySha256 }) {
@@ -55,15 +48,8 @@ export function buildCanonicalPayload({ keyId, method, path, timestamp, nonce, c
 /**
  * Signs an outgoing sync request.
  *
- * @param {Object} params
- * @param {string} params.method - HTTP method
- * @param {string} params.path - Canonical path
- * @param {string} params.contentType - Content-Type header value
- * @param {Buffer|Uint8Array} params.body - Raw request body
- * @param {string} params.secret - Shared secret
- * @param {string} params.keyId - Key identifier
- * @param {Object} deps
- * @param {import('../../ports/CryptoPort.js').default} [deps.crypto] - Crypto port
+ * @param {{ method: string, path: string, contentType: string, body: Buffer|Uint8Array, secret: string, keyId: string }} params
+ * @param {{ crypto?: import('../../ports/CryptoPort.js').default }} [deps]
  * @returns {Promise<Record<string, string>>} Auth headers
  */
 export async function signSyncRequest({ method, path, contentType, body, secret, keyId }, { crypto } = {}) {
@@ -173,15 +159,7 @@ function _validateAllowedWriters(allowedWriters) {
 
 export default class SyncAuthService {
   /**
-   * @param {Object} options
-   * @param {Record<string, string>} options.keys - Key-id to secret mapping
-   * @param {'enforce'|'log-only'} [options.mode='enforce'] - Auth enforcement mode
-   * @param {number} [options.nonceCapacity] - Nonce LRU capacity
-   * @param {number} [options.maxClockSkewMs] - Max clock skew tolerance
-   * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - Crypto port
-   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger port
-   * @param {() => number} [options.wallClockMs] - Wall clock function
-   * @param {string[]} [options.allowedWriters] - Optional whitelist of allowed writer IDs. If set, sync requests with unlisted writers are rejected with 403.
+   * @param {{ keys: Record<string, string>, mode?: 'enforce'|'log-only', nonceCapacity?: number, maxClockSkewMs?: number, crypto?: import('../../ports/CryptoPort.js').default, logger?: import('../../ports/LoggerPort.js').default, wallClockMs?: () => number, allowedWriters?: string[] }} options
    */
   constructor({ keys, mode = 'enforce', nonceCapacity, maxClockSkewMs, crypto, logger, wallClockMs, allowedWriters } = /** @type {{ keys: Record<string, string> }} */ ({})) {
     _validateKeys(keys);
@@ -289,12 +267,7 @@ export default class SyncAuthService {
   /**
    * Verifies the HMAC signature against the canonical payload.
    *
-   * @param {Object} params
-   * @param {{ method: string, url: string, headers: Record<string, string>, body?: Buffer|Uint8Array }} params.request
-   * @param {string} params.secret
-   * @param {string} params.keyId
-   * @param {string} params.timestamp
-   * @param {string} params.nonce
+   * @param {{ request: { method: string, url: string, headers: Record<string, string>, body?: Buffer|Uint8Array }, secret: string, keyId: string, timestamp: string, nonce: string }} params
    * @returns {Promise<{ ok: false, reason: string, status: number } | { ok: true }>}
    * @private
    */

package/src/domain/services/SyncController.js

@@ -98,11 +98,7 @@ function normalizeSyncPath(path) {
 /**
  * Builds auth headers for an outgoing sync request if auth is configured.
  *
- * @param {Object} params
- * @param {{ secret: string, keyId?: string }|undefined} params.auth
- * @param {string} params.bodyStr - Serialized request body
- * @param {URL} params.targetUrl
- * @param {import('../../ports/CryptoPort.js').default} params.crypto
+ * @param {{ auth: ({ secret: string, keyId?: string }|undefined), bodyStr: string, targetUrl: URL, crypto: import('../../ports/CryptoPort.js').default }} params
  * @returns {Promise<Record<string, string>>}
  */
 async function buildSyncAuthHeaders({ auth, bodyStr, targetUrl, crypto }) {
@@ -131,8 +127,7 @@ async function buildSyncAuthHeaders({ auth, bodyStr, targetUrl, crypto }) {
 export default class SyncController {
   /**
    * @param {SyncHost} host - The WarpGraph instance (or any object satisfying SyncHost)
-   * @param {Object} [options]
-   * @param {SyncTrustGate} [options.trustGate] - Trust gate for evaluating patch authors
+   * @param {{ trustGate?: SyncTrustGate }} [options]
    */
   constructor(host, options = {}) {
     /** @type {SyncHost} */
@@ -367,16 +362,7 @@ export default class SyncController {
    * Syncs with a remote peer (HTTP or direct graph instance).
    *
    * @param {string|import('../WarpGraph.js').default} remote - URL or peer graph instance
-   * @param {Object} [options]
-   * @param {string} [options.path='/sync'] - Sync path (HTTP mode)
-   * @param {number} [options.retries=3] - Retry count
-   * @param {number} [options.baseDelayMs=250] - Base backoff delay
-   * @param {number} [options.maxDelayMs=2000] - Max backoff delay
-   * @param {number} [options.timeoutMs=10000] - Request timeout
-   * @param {AbortSignal} [options.signal] - Abort signal
-   * @param {(event: {type: string, attempt: number, durationMs?: number, status?: number, error?: Error}) => void} [options.onStatus]
-   * @param {boolean} [options.materialize=false] - Auto-materialize after sync
-   * @param {{ secret: string, keyId?: string }} [options.auth] - Client auth credentials
+   * @param {{ path?: string, retries?: number, baseDelayMs?: number, maxDelayMs?: number, timeoutMs?: number, signal?: AbortSignal, onStatus?: (event: {type: string, attempt: number, durationMs?: number, status?: number, error?: Error}) => void, materialize?: boolean, auth?: { secret: string, keyId?: string } }} [options]
    * @returns {Promise<{applied: number, attempts: number, skippedWriters: Array<{writerId: string, reason: string, localSha: string, remoteSha: string|null}>, state?: import('./JoinReducer.js').WarpStateV5}>}
    */
   async syncWith(remote, options = {}) {
@@ -583,13 +569,7 @@ export default class SyncController {
   /**
    * Starts a built-in sync server for this graph.
    *
-   * @param {Object} options
-   * @param {number} options.port - Port to listen on
-   * @param {string} [options.host='127.0.0.1'] - Host to bind
-   * @param {string} [options.path='/sync'] - Path to handle sync requests
-   * @param {number} [options.maxRequestBytes=4194304] - Max request size in bytes
-   * @param {import('../../ports/HttpServerPort.js').default} options.httpPort - HTTP server adapter
-   * @param {{ keys: Record<string, string>, mode?: 'enforce'|'log-only' }} [options.auth] - Auth configuration
+   * @param {{ port: number, host?: string, path?: string, maxRequestBytes?: number, httpPort: import('../../ports/HttpServerPort.js').default, auth?: { keys: Record<string, string>, mode?: 'enforce'|'log-only' } }} options
    * @returns {Promise<{close: () => Promise<void>, url: string}>} Server handle
    * @throws {Error} If port is not a number
    * @throws {Error} If httpPort adapter is not provided
@@ -608,7 +588,7 @@ export default class SyncController {
 
     const httpServer = new HttpSyncServer({
       httpPort,
-      graph: /** @type {{ processSyncRequest: Function }} */ (/** @type {unknown} */ (this._host)),
+      graph: /** @type {{ processSyncRequest: (req: import('./SyncProtocol.js').SyncRequest) => Promise<unknown> }} */ (/** @type {unknown} */ (this._host)),
       path,
       host,
       maxRequestBytes,

package/src/domain/services/SyncProtocol.js

@@ -125,8 +125,7 @@ function objectToFrontier(obj) {
  * @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
+ * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
  * @returns {Promise<DecodedPatch>} The decoded and normalized patch object containing:
  *   - `ops`: Array of patch operations
  *   - `context`: VersionVector (Map) of causal dependencies
@@ -173,8 +172,7 @@ async function loadPatchFromCommit(persistence, sha, { codec: codecOpt } = /** @
  * @param {string|null} fromSha - Start SHA (exclusive). Pass null to load ALL patches
  *   for this writer from the beginning of their chain.
  * @param {string} toSha - End SHA (inclusive). This is typically the writer's current tip.
- * @param {Object} [options]
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
+ * @param {{ codec?: import('../../ports/CodecPort.js').default }} [options]
  * @returns {Promise<Array<{patch: DecodedPatch, sha: string}>>} Array of patch objects in
  *   chronological order (oldest first). Each entry contains:
  *   - `patch`: The decoded patch object
@@ -396,9 +394,7 @@ export function createSyncRequest(frontier) {
  * @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
- * @param {Object} [options]
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
- * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for divergence warnings
+ * @param {{ codec?: import('../../ports/CodecPort.js').default, logger?: import('../../ports/LoggerPort.js').default }} [options]
  * @returns {Promise<SyncResponse>} Response containing local frontier and patches.
  *   Patches are ordered chronologically within each writer.
  * @throws {Error} If patch loading fails for reasons other than divergence
@@ -518,7 +514,7 @@ export async function processSyncRequest(request, localFrontier, persistence, gr
  * @param {import('./JoinReducer.js').WarpStateV5} state - Current CRDT state
  *   (nodeAlive, edgeAlive, prop, observedFrontier)
  * @param {Map<string, string>} frontier - Current frontier mapping writer IDs to SHAs
- * @returns {Object} Result containing:
+ * @returns {{state: import('./JoinReducer.js').WarpStateV5, frontier: Map<string, string>, applied: number}} Result containing:
  *   - `state`: New WarpStateV5 with patches applied
  *   - `frontier`: New frontier with updated writer tips
  *   - `applied`: Number of patches successfully applied

package/src/domain/services/SyncTrustGate.js

@@ -30,10 +30,7 @@ const PASS = () => ({ allowed: true, untrustedWriters: [], verdict: 'pass' });
 
 export default class SyncTrustGate {
   /**
-   * @param {Object} options
-   * @param {{evaluateWriters: (writerIds: string[]) => Promise<{trusted: Set<string>}>}} [options.trustEvaluator] - Trust evaluator instance
-   * @param {TrustMode} [options.trustMode='off'] - Trust enforcement mode
-   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger
+   * @param {{ trustEvaluator?: {evaluateWriters: (writerIds: string[]) => Promise<{trusted: Set<string>}>}, trustMode?: TrustMode, logger?: import('../../ports/LoggerPort.js').default }} [options]
    */
   constructor({ trustEvaluator, trustMode = 'off', logger } = {}) {
     this._evaluator = trustEvaluator || null;
@@ -45,9 +42,7 @@ export default class SyncTrustGate {
    * Evaluates whether the given patch writers are trusted.
    *
    * @param {string[]} writerIds - Writer IDs from patches being applied
-   * @param {Object} [context] - Additional context for logging
-   * @param {string} [context.graphName] - Graph name
-   * @param {string} [context.peerId] - Remote peer identity (if authenticated)
+   * @param {{ graphName?: string, peerId?: string }} [context] - Additional context for logging
    * @returns {Promise<TrustGateResult>}
    */
   async evaluate(writerIds, context = {}) {
@@ -71,7 +66,7 @@ export default class SyncTrustGate {
    * Decides the gate result based on untrusted writers and mode.
    * @param {string[]} untrusted
    * @param {string[]} writerIds
-   * @param {Object} context
+   * @param {Record<string, unknown>} context
    * @returns {TrustGateResult}
    * @private
    */
@@ -110,7 +105,7 @@ export default class SyncTrustGate {
    * Handles trust evaluation errors with fail-open/fail-closed semantics.
    * @param {unknown} err
    * @param {string[]} writerIds
-   * @param {Object} context
+   * @param {Record<string, unknown>} context
    * @returns {TrustGateResult}
    * @private
    */

package/src/domain/services/TemporalQuery.js

@@ -86,12 +86,7 @@ function extractNodeSnapshot(state, nodeId) {
 /**
  * Evaluates checkpoint boundary semantics for `always()`.
  *
- * @param {Object} params
- * @param {import('./JoinReducer.js').WarpStateV5} params.state
- * @param {string} params.nodeId
- * @param {Function} params.predicate
- * @param {number|null} params.checkpointMaxLamport
- * @param {number} params.since
+ * @param {{ state: import('./JoinReducer.js').WarpStateV5, nodeId: string, predicate: (snapshot: {id: string, exists: boolean, props: Record<string, unknown>}) => boolean, checkpointMaxLamport: number|null, since: number }} params
  * @returns {{ nodeEverExisted: boolean, shouldReturn: boolean, returnValue: boolean }}
  * @private
  */
@@ -118,12 +113,7 @@ function evaluateAlwaysCheckpointBoundary({
 /**
  * Evaluates checkpoint boundary semantics for `eventually()`.
  *
- * @param {Object} params
- * @param {import('./JoinReducer.js').WarpStateV5} params.state
- * @param {string} params.nodeId
- * @param {Function} params.predicate
- * @param {number|null} params.checkpointMaxLamport
- * @param {number} params.since
+ * @param {{ state: import('./JoinReducer.js').WarpStateV5, nodeId: string, predicate: (snapshot: {id: string, exists: boolean, props: Record<string, unknown>}) => boolean, checkpointMaxLamport: number|null, since: number }} params
  * @returns {boolean}
  * @private
  */
@@ -149,16 +139,12 @@ function evaluateEventuallyCheckpointBoundary({
  */
 export class TemporalQuery {
   /**
-   * @param {Object} options
-   * @param {Function} options.loadAllPatches - Async function that returns
-   *   all patches as Array<{ patch, sha }> in causal order.
-   * @param {Function} [options.loadCheckpoint] - Async function returning
-   *   { state: WarpStateV5, maxLamport: number } or null.
+   * @param {{ loadAllPatches: () => Promise<Array<{patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}>>, loadCheckpoint?: () => Promise<{state: import('./JoinReducer.js').WarpStateV5, maxLamport: number}|null> }} options
    */
   constructor({ loadAllPatches, loadCheckpoint }) {
-    /** @type {Function} */
+    /** @type {() => Promise<Array<{patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}>>} */
     this._loadAllPatches = loadAllPatches;
-    /** @type {Function|null} */
+    /** @type {(() => Promise<{state: import('./JoinReducer.js').WarpStateV5, maxLamport: number}|null>)|null} */
     this._loadCheckpoint = loadCheckpoint || null;
   }
 
@@ -172,11 +158,9 @@ export class TemporalQuery {
    * Returns false if the node never existed in the range.
    *
    * @param {string} nodeId - The node ID to evaluate
-   * @param {Function} predicate - Predicate receiving node snapshot
+   * @param {(snapshot: {id: string, exists: boolean, props: Record<string, unknown>}) => boolean} predicate - Predicate receiving node snapshot
    *   `{ id, exists, props }`. Should return boolean.
-   * @param {Object} [options={}] - Options
-   * @param {number} [options.since=0] - Minimum Lamport tick (inclusive).
-   *   Only patches with lamport >= since are considered.
+   * @param {{ since?: number }} [options={}] - Options
    * @returns {Promise<boolean>} True if predicate held at every tick
    *
    * @example
@@ -232,11 +216,9 @@ export class TemporalQuery {
    * soon as the predicate returns true at any tick.
    *
    * @param {string} nodeId - The node ID to evaluate
-   * @param {Function} predicate - Predicate receiving node snapshot
+   * @param {(snapshot: {id: string, exists: boolean, props: Record<string, unknown>}) => boolean} predicate - Predicate receiving node snapshot
    *   `{ id, exists, props }`. Should return boolean.
-   * @param {Object} [options={}] - Options
-   * @param {number} [options.since=0] - Minimum Lamport tick (inclusive).
-   *   Only patches with lamport >= since are considered.
+   * @param {{ since?: number }} [options={}] - Options
    * @returns {Promise<boolean>} True if predicate held at any tick
    *
    * @example

package/src/domain/services/TranslationCost.js

@@ -169,14 +169,8 @@ function computePropLoss(state, { nodesA, nodesBSet, configA, configB }) {
  * The cost measures how much information is lost when translating from
  * A's view to B's view. It is asymmetric: cost(A->B) != cost(B->A) in general.
  *
- * @param {Object} configA - Observer configuration for A
- * @param {string|string[]} configA.match - Glob pattern(s) for visible nodes
- * @param {string[]} [configA.expose] - Property keys to include
- * @param {string[]} [configA.redact] - Property keys to exclude
- * @param {Object} configB - Observer configuration for B
- * @param {string|string[]} configB.match - Glob pattern(s) for visible nodes
- * @param {string[]} [configB.expose] - Property keys to include
- * @param {string[]} [configB.redact] - Property keys to exclude
+ * @param {{ match: string|string[], expose?: string[], redact?: string[] }} configA - Observer configuration for A
+ * @param {{ match: string|string[], expose?: string[], redact?: string[] }} configB - Observer configuration for B
  * @param {WarpStateV5} state - WarpStateV5 materialized state
  * @returns {{ cost: number, breakdown: { nodeLoss: number, edgeLoss: number, propLoss: number } }}
  */

package/src/domain/services/WarpStateIndexBuilder.js

@@ -30,8 +30,7 @@ import { decodeEdgeKey } from './KeyCodec.js';
 export default class WarpStateIndexBuilder {
   /**
    * Creates a new WarpStateIndexBuilder.
-   * @param {Object} [options] - Configuration
-   * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort for shard checksums
+   * @param {{ crypto?: import('../../ports/CryptoPort.js').default }} [options] - Configuration
    */
   constructor({ crypto } = {}) {
     /** @type {BitmapIndexBuilder} */
@@ -109,8 +108,7 @@ export default class WarpStateIndexBuilder {
  * Convenience function to build and serialize a WARP state index.
  *
  * @param {import('./JoinReducer.js').WarpStateV5} state - The materialized state
- * @param {Object} [options] - Configuration
- * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort for shard checksums
+ * @param {{ crypto?: import('../../ports/CryptoPort.js').default }} [options] - Configuration
  * @returns {Promise<{tree: Record<string, Buffer>, stats: {nodes: number, edges: number}}>} Serialized index and stats
  *
  * @example