@git-stunts/git-warp 12.3.0 → 12.4.1

package/README.md

@@ -8,13 +8,12 @@
   <img src="docs/images/hero.gif" alt="git-warp CLI demo" width="600">
 </p>
 
-## What's New in v12.3.0
+## What's New in v12.4.1
 
-- **M13 ADR 1 — canonical edge property ops** — internal model now uses honest `NodePropSet`/`EdgePropSet` semantics. Legacy raw `PropSet` is normalized at reducer entry points and lowered back at write time. No wire-format change — persisted patches remain backward-compatible.
-- **Wire gate hardened** — sync boundary now explicitly rejects canonical-only op types (`NodePropSet`, `EdgePropSet`) arriving over the wire, preventing premature schema migration before ADR 2 capability cutover.
-- **Reserved-byte validation** — new writes reject node IDs containing `\0` or starting with `\x01`, preventing ambiguous legacy edge-property encoding.
-- **Version namespace separation** — patch schema and checkpoint schema constants are now distinct (`PATCH_SCHEMA_V2`/`V3` vs `CHECKPOINT_SCHEMA_STANDARD`/`INDEX_TREE`).
-- **ADR governance** — ADR 3 readiness gates formalize when the persisted wire-format migration may proceed, with GitHub issue template and go/no-go checklist.
+- **JSDoc total coverage** — eliminated all unsafe `{Object}`, `{Function}`, `{*}` type patterns across 135 files (190+ sites), replacing them with precise inline typed shapes.
+- **Zero tsc errors** — fixed tsconfig split-config includes and type divergences; 0 errors across all three tsconfig targets.
+- **JSR dry-run fix** — worked around a deno_ast 0.52.0 panic caused by overlapping text-change entries for duplicate import specifiers.
+- **`check-dts-surface.js` regex fix** — default-export parsing now correctly captures identifiers instead of keywords for `export default class/function` patterns.
 
 See the [full changelog](CHANGELOG.md) for details.
 

package/bin/cli/commands/info.js

@@ -17,11 +17,7 @@ import { createPersistence, listGraphNames, readActiveCursor, readCheckpointDate
  * Collects metadata about a single graph (writer count, refs, patches, checkpoint).
  * @param {Persistence} persistence
  * @param {string} graphName
- * @param {Object} [options]
- * @param {boolean} [options.includeWriterIds=false]
- * @param {boolean} [options.includeRefs=false]
- * @param {boolean} [options.includeWriterPatches=false]
- * @param {boolean} [options.includeCheckpointDate=false]
+ * @param {{ includeWriterIds?: boolean, includeRefs?: boolean, includeWriterPatches?: boolean, includeCheckpointDate?: boolean }} [options]
  * @returns {Promise<GraphInfoResult>}
  */
 async function getGraphInfo(persistence, graphName, {

package/bin/cli/infrastructure.js

@@ -127,10 +127,7 @@ Tree options:
 export class CliError extends Error {
   /**
    * @param {string} message - Human-readable error message
-   * @param {Object} [options]
-   * @param {string} [options.code='E_CLI'] - Machine-readable error code
-   * @param {number} [options.exitCode=3] - Process exit code
-   * @param {Error} [options.cause] - Underlying cause
+   * @param {{ code?: string, exitCode?: number, cause?: Error }} [options]
    */
   constructor(message, { code = 'E_CLI', exitCode = EXIT_CODES.INTERNAL, cause } = {}) {
     super(message);
@@ -337,12 +334,12 @@ export function parseArgs(argv) {
 /**
  * Parses command-level args using node:util.parseArgs + Zod validation.
  *
+ * @template T
  * @param {string[]} args - Command-specific args (after command name)
- * @param {Object} config - parseArgs options config
- * @param {import('zod').ZodType} schema - Zod schema to validate/transform parsed values
- * @param {Object} [opts]
- * @param {boolean} [opts.allowPositionals=false] - Whether to allow positional arguments
- * @returns {{values: *, positionals: string[]}}
+ * @param {Record<string, {type: string, short?: string, default?: unknown, multiple?: boolean}>} config - parseArgs options config
+ * @param {import('zod').ZodType<T, import('zod').ZodTypeDef, unknown>} schema - Zod schema to validate/transform parsed values
+ * @param {{ allowPositionals?: boolean }} [opts]
+ * @returns {{values: T, positionals: string[]}}
  */
 export function parseCommandArgs(args, config, schema, { allowPositionals = false } = {}) {
   /** @type {{ values: Record<string, string|boolean|string[]|boolean[]|undefined>, positionals: string[] }} */

package/bin/cli/shared.js

@@ -177,6 +177,10 @@ export async function readCheckpointDate(persistence, checkpointSha) {
   return info.date || null;
 }
 
+/**
+ * Create a HookInstaller wired with real filesystem dependencies.
+ * @returns {import('../../src/domain/services/HookInstaller.js').HookInstaller}
+ */
 export function createHookInstaller() {
   const __filename = new URL(import.meta.url).pathname;
   const __dirname = path.dirname(__filename);
@@ -211,6 +215,10 @@ export function execGitConfigValue(repoPath, key) {
   }
 }
 
+/**
+ * Check whether stderr is a TTY (interactive terminal).
+ * @returns {boolean}
+ */
 export function isInteractive() {
   return Boolean(process.stderr.isTTY);
 }

package/bin/warp-graph.js

@@ -55,20 +55,20 @@ async function main() {
     throw usageError(`--view is not supported for '${command}'. Supported commands: ${VIEW_SUPPORTED_COMMANDS.join(', ')}`);
   }
 
-  const result = await /** @type {Function} */ (handler)({
+  const result = await /** @type {(opts: {command: string, args: string[], options: Record<string, unknown>}) => Promise<unknown>} */ (handler)({
     command,
     args: commandArgs,
     options,
   });
 
-  /** @type {{payload: *, exitCode: number}} */
-  const normalized = result && typeof result === 'object' && 'payload' in result
-    ? result
+  /** @type {{payload: unknown, exitCode: number}} */
+  const normalized = result && typeof result === 'object' && 'payload' in /** @type {Record<string, unknown>} */ (result)
+    ? /** @type {{payload: unknown, exitCode: number}} */ (result)
     : { payload: result, exitCode: EXIT_CODES.OK };
 
   if (normalized.payload !== undefined) {
     const format = options.ndjson ? 'ndjson' : options.json ? 'json' : 'text';
-    present(normalized.payload, { format, command, view: options.view });
+    present(/** @type {Record<string, unknown>} */ (normalized.payload), { format, command, view: /** @type {string | null | boolean} */ (options.view ?? null) });
   }
   // Use process.exit() to avoid waiting for fire-and-forget I/O (e.g. seek cache writes).
   process.exit(normalized.exitCode ?? EXIT_CODES.OK);
@@ -78,7 +78,7 @@ main().catch((error) => {
   const exitCode = error instanceof CliError ? error.exitCode : EXIT_CODES.INTERNAL;
   const code = error instanceof CliError ? error.code : 'E_INTERNAL';
   const message = error instanceof Error ? error.message : 'Unknown error';
-  /** @type {{error: {code: string, message: string, cause?: *}}} */
+  /** @type {{error: {code: string, message: string, cause?: unknown}}} */
   const payload = { error: { code, message } };
 
   if (error && error.cause) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-warp",
-  "version": "12.3.0",
+  "version": "12.4.1",
   "description": "Deterministic WARP graph over Git: graph-native storage, traversal, and tooling.",
   "type": "module",
   "license": "Apache-2.0",

package/src/domain/WarpGraph.js

@@ -50,21 +50,7 @@ const DEFAULT_ADJACENCY_CACHE_SIZE = 3;
 export default class WarpGraph {
   /**
    * @private
-   * @param {Object} options
-   * @param {import('../ports/GraphPersistencePort.js').default} options.persistence - Git adapter
-   * @param {string} options.graphName - Graph namespace
-   * @param {string} options.writerId - This writer's ID
-   * @param {Object} [options.gcPolicy] - GC policy configuration (overrides defaults)
-   * @param {number} [options.adjacencyCacheSize] - Max materialized adjacency cache entries
-   * @param {{every: number}} [options.checkpointPolicy] - Auto-checkpoint policy; creates a checkpoint every N patches
-   * @param {boolean} [options.autoMaterialize=true] - If true, query methods auto-materialize instead of throwing
-   * @param {'reject'|'cascade'|'warn'} [options.onDeleteWithData='warn'] - Policy when deleting a node that still has edges or properties
-   * @param {import('../ports/LoggerPort.js').default} [options.logger] - Logger for structured logging
-   * @param {import('../ports/ClockPort.js').default} [options.clock] - Clock for timing instrumentation (defaults to performance-based clock)
-   * @param {import('../ports/CryptoPort.js').default} [options.crypto] - Crypto adapter for hashing
-   * @param {import('../ports/CodecPort.js').default} [options.codec] - Codec for CBOR serialization (defaults to domain-local codec)
-   * @param {import('../ports/SeekCachePort.js').default} [options.seekCache] - Persistent cache for seek materialization (optional)
-   * @param {boolean} [options.audit=false] - If true, creates audit receipts for each data commit
+   * @param {{ persistence: import('../ports/GraphPersistencePort.js').default, graphName: string, writerId: string, gcPolicy?: Record<string, unknown>, adjacencyCacheSize?: number, checkpointPolicy?: {every: number}, autoMaterialize?: boolean, onDeleteWithData?: 'reject'|'cascade'|'warn', logger?: import('../ports/LoggerPort.js').default, clock?: import('../ports/ClockPort.js').default, crypto?: import('../ports/CryptoPort.js').default, codec?: import('../ports/CodecPort.js').default, seekCache?: import('../ports/SeekCachePort.js').default, audit?: boolean }} options
    */
   constructor({ persistence, graphName, writerId, gcPolicy = {}, adjacencyCacheSize = DEFAULT_ADJACENCY_CACHE_SIZE, checkpointPolicy, autoMaterialize = true, onDeleteWithData = 'warn', logger, clock, crypto, codec, seekCache, audit = false }) {
     /** @type {FullPersistence} */
@@ -85,7 +71,7 @@ export default class WarpGraph {
     /** @type {boolean} */
     this._stateDirty = false;
 
-    /** @type {Object} */
+    /** @type {import('./services/GCPolicy.js').GCPolicy} */
     this._gcPolicy = { ...DEFAULT_GC_POLICY, ...gcPolicy };
 
     /** @type {number} */
@@ -224,9 +210,7 @@ export default class WarpGraph {
    * Logs a timing message for a completed or failed operation.
    * @param {string} op - Operation name (e.g. 'materialize')
    * @param {number} t0 - Start timestamp from this._clock.now()
-   * @param {Object} [opts] - Options
-   * @param {string} [opts.metrics] - Extra metrics string to append in parentheses
-   * @param {Error} [opts.error] - If set, logs a failure message instead
+   * @param {{ metrics?: string, error?: Error }} [opts] - Options
    */
   _logTiming(op, t0, { metrics, error } = {}) {
     if (!this._logger) {
@@ -259,21 +243,7 @@ export default class WarpGraph {
   /**
    * Opens a multi-writer graph.
    *
-   * @param {Object} options
-   * @param {import('../ports/GraphPersistencePort.js').default} options.persistence - Git adapter
-   * @param {string} options.graphName - Graph namespace
-   * @param {string} options.writerId - This writer's ID
-   * @param {Object} [options.gcPolicy] - GC policy configuration (overrides defaults)
-   * @param {number} [options.adjacencyCacheSize] - Max materialized adjacency cache entries
-   * @param {{every: number}} [options.checkpointPolicy] - Auto-checkpoint policy; creates a checkpoint every N patches
-   * @param {boolean} [options.autoMaterialize] - If true, query methods auto-materialize instead of throwing
-   * @param {'reject'|'cascade'|'warn'} [options.onDeleteWithData] - Policy when deleting a node that still has edges or properties (default: 'warn')
-   * @param {import('../ports/LoggerPort.js').default} [options.logger] - Logger for structured logging
-   * @param {import('../ports/ClockPort.js').default} [options.clock] - Clock for timing instrumentation (defaults to performance-based clock)
-   * @param {import('../ports/CryptoPort.js').default} [options.crypto] - Crypto adapter for hashing
-   * @param {import('../ports/CodecPort.js').default} [options.codec] - Codec for CBOR serialization (defaults to domain-local codec)
-   * @param {import('../ports/SeekCachePort.js').default} [options.seekCache] - Persistent cache for seek materialization (optional)
-   * @param {boolean} [options.audit=false] - If true, creates audit receipts for each data commit
+   * @param {{ persistence: import('../ports/GraphPersistencePort.js').default, graphName: string, writerId: string, gcPolicy?: Record<string, unknown>, adjacencyCacheSize?: number, checkpointPolicy?: {every: number}, autoMaterialize?: boolean, onDeleteWithData?: 'reject'|'cascade'|'warn', logger?: import('../ports/LoggerPort.js').default, clock?: import('../ports/ClockPort.js').default, crypto?: import('../ports/CryptoPort.js').default, codec?: import('../ports/CodecPort.js').default, seekCache?: import('../ports/SeekCachePort.js').default, audit?: boolean }} options
    * @returns {Promise<WarpGraph>} The opened graph instance
    * @throws {Error} If graphName, writerId, checkpointPolicy, or onDeleteWithData is invalid
    *
@@ -377,7 +347,7 @@ export default class WarpGraph {
   /**
    * Gets the current GC policy.
    *
-   * @returns {Object} The GC policy configuration
+   * @returns {import('./services/GCPolicy.js').GCPolicy} The GC policy configuration
    */
   get gcPolicy() {
     return { ...this._gcPolicy };

package/src/domain/crdt/VersionVector.js

@@ -155,7 +155,7 @@ export function vvContains(vv, dot) {
  * Keys are sorted for deterministic serialization.
  *
  * @param {VersionVector} vv
- * @returns {Object<string, number>}
+ * @returns {Record<string, number>}
  */
 export function vvSerialize(vv) {
   /** @type {Record<string, number>} */

package/src/domain/entities/GraphNode.js

@@ -38,12 +38,7 @@ export default class GraphNode {
   /**
    * Creates a new immutable GraphNode.
    *
-   * @param {Object} data - Node data
-   * @param {string} data.sha - The commit SHA (40 hex characters). Required.
-   * @param {string} data.message - The commit message/payload. Required.
-   * @param {string} [data.author] - The commit author name. Optional.
-   * @param {string} [data.date] - The commit date string. Optional.
-   * @param {string[]} [data.parents=[]] - Array of parent commit SHAs. Defaults to empty array.
+   * @param {{ sha: string, message: string, author?: string, date?: string, parents?: string[] }} data - Node data
    * @throws {Error} If sha is missing or not a string
    * @throws {Error} If message is missing or not a string
    * @throws {Error} If parents is not an array

package/src/domain/errors/ForkError.js

@@ -21,7 +21,7 @@ import WarpError from './WarpError.js';
  *
  * @property {string} name - Always 'ForkError' for instanceof checks
  * @property {string} code - Machine-readable error code for programmatic handling
- * @property {Object} context - Serializable context object with error details
+ * @property {Record<string, unknown>} context - Serializable context object with error details
  */
 export default class ForkError extends WarpError {
   /**

package/src/domain/errors/IndexError.js

@@ -8,7 +8,7 @@ import WarpError from './WarpError.js';
  *
  * @property {string} name - The error name ('IndexError')
  * @property {string} code - Error code for programmatic handling (default: 'INDEX_ERROR')
- * @property {Object} context - Serializable context object for debugging
+ * @property {Record<string, unknown>} context - Serializable context object for debugging
  *
  * @example
  * throw new IndexError('Failed to process index', {

package/src/domain/errors/OperationAbortedError.js

@@ -10,7 +10,7 @@ import WarpError from './WarpError.js';
  * @property {string} code - Error code for programmatic handling (default: 'OPERATION_ABORTED')
  * @property {string} operation - The name of the operation that was aborted
  * @property {string} reason - The reason the operation was aborted
- * @property {Object} context - Serializable context object for debugging
+ * @property {Record<string, unknown>} context - Serializable context object for debugging
  */
 export default class OperationAbortedError extends WarpError {
   /**

package/src/domain/errors/PatchError.js

@@ -14,7 +14,7 @@ import WarpError from './WarpError.js';
  *
  * @property {string} name - Always 'PatchError' for instanceof checks
  * @property {string} code - Machine-readable error code for programmatic handling
- * @property {Object} context - Serializable context object with error details
+ * @property {Record<string, unknown>} context - Serializable context object with error details
  */
 export default class PatchError extends WarpError {
   /**

package/src/domain/errors/PersistenceError.js

@@ -0,0 +1,45 @@
+import WarpError from './WarpError.js';
+
+/**
+ * Typed error codes for persistence adapter boundary failures.
+ *
+ * Replaces generic `Error` throws with machine-readable codes so callers
+ * can branch on `err.code` instead of brittle `err.message.includes()`.
+ *
+ * ## Error Codes
+ *
+ * | Code | Description |
+ * |------|-------------|
+ * | `E_MISSING_OBJECT` | Stored object (commit, blob, tree) does not exist |
+ * | `E_REF_NOT_FOUND` | Ref does not resolve to any object |
+ * | `E_REF_IO` | Ref update/delete failed (lock contention, permission, etc.) |
+ *
+ * @class PersistenceError
+ * @extends WarpError
+ *
+ * @property {string} name - Always 'PersistenceError' for instanceof checks
+ * @property {string} code - Machine-readable error code for programmatic handling
+ * @property {Record<string, unknown>} context - Serializable context object with error details
+ */
+export default class PersistenceError extends WarpError {
+  /** Stored object (commit, blob, tree) does not exist. */
+  static E_MISSING_OBJECT = 'E_MISSING_OBJECT';
+
+  /** Ref does not resolve to any object. */
+  static E_REF_NOT_FOUND = 'E_REF_NOT_FOUND';
+
+  /** Ref update/delete failed (lock contention, permission, etc.). */
+  static E_REF_IO = 'E_REF_IO';
+
+  /**
+   * @param {string} message - Human-readable error message
+   * @param {string} code - One of the E_* constants
+   * @param {{ cause?: Error, context?: Record<string, unknown> }} [options={}]
+   */
+  constructor(message, code, options = {}) {
+    super(message, code, { context: options.context });
+    if (options.cause) {
+      this.cause = options.cause;
+    }
+  }
+}

package/src/domain/errors/QueryError.js

@@ -30,7 +30,7 @@ import WarpError from './WarpError.js';
  *
  * @property {string} name - Always 'QueryError' for instanceof checks
  * @property {string} code - Machine-readable error code for programmatic handling
- * @property {Object} context - Serializable context object with error details
+ * @property {Record<string, unknown>} context - Serializable context object with error details
  */
 export default class QueryError extends WarpError {
   /**

package/src/domain/errors/SchemaUnsupportedError.js

@@ -8,7 +8,7 @@ import WarpError from './WarpError.js';
  *
  * @property {string} name - The error name ('SchemaUnsupportedError')
  * @property {string} code - Error code ('E_SCHEMA_UNSUPPORTED')
- * @property {Object} context - Serializable context object for debugging
+ * @property {Record<string, unknown>} context - Serializable context object for debugging
  */
 export default class SchemaUnsupportedError extends WarpError {
   /**

package/src/domain/errors/SyncError.js

@@ -22,7 +22,7 @@ import WarpError from './WarpError.js';
  *
  * @property {string} name - Always 'SyncError' for instanceof checks
  * @property {string} code - Machine-readable error code for programmatic handling
- * @property {Object} context - Serializable context object with error details
+ * @property {Record<string, unknown>} context - Serializable context object with error details
  */
 export default class SyncError extends WarpError {
   /**

package/src/domain/errors/TraversalError.js

@@ -8,7 +8,7 @@ import WarpError from './WarpError.js';
  *
  * @property {string} name - The error name ('TraversalError')
  * @property {string} code - Error code for programmatic handling (default: 'TRAVERSAL_ERROR')
- * @property {Object} context - Serializable context object for debugging
+ * @property {Record<string, unknown>} context - Serializable context object for debugging
  *
  * @example
  * throw new TraversalError('Node not found in index', {

package/src/domain/errors/TrustError.js

@@ -18,7 +18,7 @@ import WarpError from './WarpError.js';
  *
  * @property {string} name - Always 'TrustError' for instanceof checks
  * @property {string} code - Machine-readable error code for programmatic handling
- * @property {Object} context - Serializable context object with error details
+ * @property {Record<string, unknown>} context - Serializable context object with error details
  */
 export default class TrustError extends WarpError {
   /**

package/src/domain/errors/WormholeError.js

@@ -19,7 +19,7 @@ import WarpError from './WarpError.js';
  *
  * @property {string} name - Always 'WormholeError' for instanceof checks
  * @property {string} code - Machine-readable error code for programmatic handling
- * @property {Object} context - Serializable context object with error details
+ * @property {Record<string, unknown>} context - Serializable context object with error details
  */
 export default class WormholeError extends WarpError {
   /**

package/src/domain/errors/index.js

@@ -5,6 +5,7 @@
  */
 
 export { default as EmptyMessageError } from './EmptyMessageError.js';
+export { default as PersistenceError } from './PersistenceError.js';
 export { default as WarpError } from './WarpError.js';
 export { default as ForkError } from './ForkError.js';
 export { default as IndexError } from './IndexError.js';

package/src/domain/services/AdjacencyNeighborProvider.js

@@ -86,10 +86,7 @@ function mergeSorted(a, b) {
 
 export default class AdjacencyNeighborProvider extends NeighborProviderPort {
   /**
-   * @param {Object} params
-   * @param {Map<string, Array<{neighborId: string, label: string}>>} params.outgoing
-   * @param {Map<string, Array<{neighborId: string, label: string}>>} params.incoming
-   * @param {Set<string>} params.aliveNodes - Set of alive nodeIds for hasNode()
+   * @param {{ outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>>, aliveNodes: Set<string> }} params
    */
   constructor({ outgoing, incoming, aliveNodes }) {
     super();

package/src/domain/services/AnchorMessageCodec.js

@@ -23,9 +23,7 @@ import {
 /**
  * Encodes an anchor commit message.
  *
- * @param {Object} options - The anchor message options
- * @param {string} options.graph - The graph name
- * @param {number} [options.schema=2] - The schema version (defaults to 2 for new messages)
+ * @param {{ graph: string, schema?: number }} options - The anchor message options
  * @returns {string} The encoded commit message
  * @throws {Error} If any validation fails
  *

package/src/domain/services/AuditMessageCodec.js

@@ -24,11 +24,7 @@ import {
 /**
  * Encodes an audit commit message with trailers.
  *
- * @param {Object} options
- * @param {string} options.graph - The graph name
- * @param {string} options.writer - The writer ID
- * @param {string} options.dataCommit - The OID of the data commit being audited
- * @param {string} options.opsDigest - SHA-256 hex digest of the canonical ops JSON
+ * @param {{ graph: string, writer: string, dataCommit: string, opsDigest: string }} options
  * @returns {string} The encoded commit message
  * @throws {Error} If any validation fails
  */

package/src/domain/services/AuditReceiptService.js

@@ -90,16 +90,7 @@ const OID_HEX_PATTERN = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
 /**
  * Validates and builds a frozen receipt record with keys in sorted order.
  *
- * @param {Object} fields
- * @param {number} fields.version
- * @param {string} fields.graphName
- * @param {string} fields.writerId
- * @param {string} fields.dataCommit
- * @param {number} fields.tickStart
- * @param {number} fields.tickEnd
- * @param {string} fields.opsDigest
- * @param {string} fields.prevAuditCommit
- * @param {number} fields.timestamp
+ * @param {{ version: number, graphName: string, writerId: string, dataCommit: string, tickStart: number, tickEnd: number, opsDigest: string, prevAuditCommit: string, timestamp: number }} fields
  * @returns {Readonly<Record<string, unknown>>}
  * @throws {Error} If any field is invalid
  */
@@ -206,13 +197,7 @@ export function buildReceiptRecord(fields) {
  */
 export class AuditReceiptService {
   /**
-   * @param {Object} options
-   * @param {import('../../ports/RefPort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default & import('../../ports/CommitPort.js').default} options.persistence
-   * @param {string} options.graphName
-   * @param {string} options.writerId
-   * @param {import('../../ports/CodecPort.js').default} options.codec
-   * @param {import('../../ports/CryptoPort.js').default} options.crypto
-   * @param {import('../../ports/LoggerPort.js').default} [options.logger]
+   * @param {{ persistence: import('../../ports/RefPort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default & import('../../ports/CommitPort.js').default, graphName: string, writerId: string, codec: import('../../ports/CodecPort.js').default, crypto: import('../../ports/CryptoPort.js').default, logger?: import('../../ports/LoggerPort.js').default }} options
    */
   constructor({ persistence, graphName, writerId, codec, crypto, logger }) {
     this._persistence = persistence;

package/src/domain/services/AuditVerifierService.js

@@ -211,10 +211,7 @@ function validateTrailerConsistency(receipt, decoded) {
 
 export class AuditVerifierService {
   /**
-   * @param {Object} options
-   * @param {import('../../ports/CommitPort.js').default & import('../../ports/RefPort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default} options.persistence
-   * @param {import('../../ports/CodecPort.js').default} options.codec
-   * @param {import('../../ports/LoggerPort.js').default} [options.logger]
+   * @param {{ persistence: import('../../ports/CommitPort.js').default & import('../../ports/RefPort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default, codec: import('../../ports/CodecPort.js').default, logger?: import('../../ports/LoggerPort.js').default }} options
    */
   constructor({ persistence, codec, logger }) {
     this._persistence = persistence;
@@ -658,9 +655,7 @@ export class AuditVerifierService {
    * and returns a TrustAssessment.
    *
    * @param {string} graphName
-   * @param {Object} [options]
-   * @param {string} [options.pin] - Pinned trust chain commit SHA
-   * @param {string} [options.mode] - Policy mode ('warn' or 'enforce')
+   * @param {{ pin?: string, mode?: string }} [options]
    * @returns {Promise<import('../trust/TrustEvaluator.js').TrustAssessment>}
    */
   async evaluateTrust(graphName, options = {}) {

package/src/domain/services/BitmapIndexBuilder.js

@@ -12,7 +12,7 @@ export { SHARD_VERSION };
  * 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
  */
@@ -42,9 +42,9 @@ const ensureRoaringBitmap32 = () => {
 
 /**
  * Wraps data in a version/checksum envelope.
- * @param {Object} data - The data to wrap
+ * @param {Record<string, unknown>} data - The data to wrap
  * @param {import('../../ports/CryptoPort.js').default} crypto - CryptoPort instance
- * @returns {Promise<Object>} Envelope with version, checksum, and data
+ * @returns {Promise<{version: number, checksum: string, data: Record<string, unknown>}>} Envelope with version, checksum, and data
  */
 const wrapShard = async (data, crypto) => ({
   version: SHARD_VERSION,
@@ -95,9 +95,7 @@ export default class BitmapIndexBuilder {
    * - Forward edge bitmaps (parent → children)
    * - Reverse edge bitmaps (child → parents)
    *
-   * @param {Object} [options] - Configuration options
-   * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort instance for hashing
-   * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for serialization
+   * @param {{ crypto?: import('../../ports/CryptoPort.js').default, codec?: import('../../ports/CodecPort.js').default }} [options] - Configuration options
    */
   constructor({ crypto, codec } = {}) {
     /** @type {import('../../ports/CryptoPort.js').default} */
@@ -149,8 +147,7 @@ export default class BitmapIndexBuilder {
    *
    * Each shard is wrapped in a version/checksum envelope for integrity verification.
    *
-   * @param {Object} [options] - Serialization options
-   * @param {Map<string, string>} [options.frontier] - Writer→tip SHA map to include in the tree
+   * @param {{ frontier?: Map<string, string> }} [options] - Serialization options
    * @returns {Promise<Record<string, Buffer>>} Map of path → serialized content
    */
   async serialize({ frontier } = {}) {
@@ -217,10 +214,7 @@ export default class BitmapIndexBuilder {
 
   /**
    * Adds an ID to a node's bitmap.
-   * @param {Object} opts - Options
-   * @param {string} opts.sha - The SHA to use as key
-   * @param {number} opts.id - The ID to add to the bitmap
-   * @param {string} opts.type - 'fwd' or 'rev'
+   * @param {{ sha: string, id: number, type: string }} opts - Options
    * @private
    */
   _addToBitmap({ sha, id, type }) {

package/src/domain/services/BitmapIndexReader.js

@@ -29,7 +29,7 @@ const DEFAULT_MAX_CACHED_SHARDS = 100;
  * Computes a SHA-256 checksum of the given data.
  * Used to verify shard integrity on load.
  *
- * @param {Object} data - The data object to checksum
+ * @param {Record<string, unknown>} data - The data object to checksum
  * @param {number} version - Shard version (1 uses JSON.stringify, 2+ uses canonicalStringify)
  * @param {import('../../ports/CryptoPort.js').default} crypto - CryptoPort instance
  * @returns {Promise<string>} Hex-encoded SHA-256 hash
@@ -82,16 +82,9 @@ const computeChecksum = async (data, version, crypto) => {
 export default class BitmapIndexReader {
   /**
    * Creates a BitmapIndexReader instance.
-   * @param {Object} options
-   * @param {IndexStoragePort} options.storage - Storage adapter for reading index data
-   * @param {boolean} [options.strict=true] - If true, throw errors on validation failures; if false, log warnings and return empty shards
-   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for structured logging.
-   *   Defaults to NoOpLogger (no logging).
-   * @param {number} [options.maxCachedShards=100] - Maximum number of shards to keep in the LRU cache.
-   *   When exceeded, least recently used shards are evicted to free memory.
-   * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort instance for checksum verification.
+   * @param {{ storage: IndexStoragePort, strict?: boolean, logger?: import('../../ports/LoggerPort.js').default, maxCachedShards?: number, crypto?: import('../../ports/CryptoPort.js').default }} options
    */
-  constructor({ storage, strict = true, logger = nullLogger, maxCachedShards = DEFAULT_MAX_CACHED_SHARDS, crypto } = /** @type {{ storage: IndexStoragePort, strict?: boolean, logger?: LoggerPort, maxCachedShards?: number, crypto?: CryptoPort }} */ ({})) {
+  constructor({ storage, strict = true, logger = nullLogger, maxCachedShards = DEFAULT_MAX_CACHED_SHARDS, crypto }) {
     if (!storage) {
       throw new Error('BitmapIndexReader requires a storage adapter');
     }
@@ -321,10 +314,7 @@ export default class BitmapIndexReader {
   /**
    * Handles validation/corruption errors based on strict mode.
    * @param {ShardCorruptionError|ShardValidationError} err - The error to handle
-   * @param {Object} context - Error context
-   * @param {string} context.path - Shard path
-   * @param {string} context.oid - Object ID
-   * @param {string} context.format - 'json' or 'bitmap'
+   * @param {{ path: string, oid: string, format: string }} context - Error context
    * @returns {Record<string, string | number> | import('../utils/roaring.js').RoaringBitmapSubset} Empty shard (non-strict mode only)
    * @throws {ShardCorruptionError|ShardValidationError} In strict mode
    * @private
@@ -356,7 +346,7 @@ export default class BitmapIndexReader {
 
   /**
    * Parses and validates a shard buffer.
-   * @param {Buffer} buffer - Raw shard buffer
+   * @param {Uint8Array} buffer - Raw shard buffer
    * @param {string} path - Shard path (for error context)
    * @param {string} oid - Object ID (for error context)
    * @returns {Promise<Record<string, string | number>>} The validated data from the shard
@@ -373,7 +363,7 @@ export default class BitmapIndexReader {
    * Loads raw buffer from storage.
    * @param {string} path - Shard path
    * @param {string} oid - Object ID
-   * @returns {Promise<Buffer>} Raw buffer
+   * @returns {Promise<Uint8Array>} Raw buffer
    * @throws {ShardLoadError} When storage.readBlob fails
    * @private
    */
@@ -413,10 +403,7 @@ export default class BitmapIndexReader {
    * Attempts to handle a shard error based on its type.
    * Returns handled result for validation/corruption errors, null otherwise.
    * @param {unknown} err - The error to handle
-   * @param {Object} context - Error context
-   * @param {string} context.path - Shard path
-   * @param {string} context.oid - Object ID
-   * @param {string} context.format - 'json' or 'bitmap'
+   * @param {{ path: string, oid: string, format: string }} context - Error context
    * @returns {Record<string, string | number> | import('../utils/roaring.js').RoaringBitmapSubset | null} Handled result or null if error should be re-thrown
    * @private
    */

package/src/domain/services/BitmapNeighborProvider.js

@@ -59,9 +59,7 @@ function dedupSorted(edges) {
 
 export default class BitmapNeighborProvider extends NeighborProviderPort {
   /**
-   * @param {Object} params
-   * @param {BitmapIndexReader} [params.indexReader] - For commit DAG mode
-   * @param {LogicalIndex} [params.logicalIndex] - For logical graph mode
+   * @param {{ indexReader?: BitmapIndexReader, logicalIndex?: LogicalIndex }} params
    */
   constructor({ indexReader, logicalIndex }) {
     super();