@git-stunts/git-warp 10.3.2 → 10.7.0

package/src/infrastructure/adapters/adapterValidation.js

@@ -0,0 +1,90 @@
+/**
+ * Shared input validation for persistence adapters.
+ *
+ * These functions are extracted from GitGraphAdapter so that both Git-backed
+ * and in-memory adapters apply identical validation rules. This prevents
+ * divergence and ensures conformance tests exercise the same constraints.
+ *
+ * @module infrastructure/adapters/adapterValidation
+ */
+
+/**
+ * Validates that an OID is a safe hex string (4–64 characters).
+ * @param {string} oid - The OID to validate
+ * @throws {Error} If OID is invalid
+ */
+export function validateOid(oid) {
+  if (!oid || typeof oid !== 'string') {
+    throw new Error('OID must be a non-empty string');
+  }
+  if (oid.length > 64) {
+    throw new Error(`OID too long: ${oid.length} chars. Maximum is 64`);
+  }
+  const validOidPattern = /^[0-9a-fA-F]{4,64}$/;
+  if (!validOidPattern.test(oid)) {
+    throw new Error(`Invalid OID format: ${oid}`);
+  }
+}
+
+/**
+ * Validates that a ref is safe to use in git commands.
+ * Prevents command injection via malicious ref names.
+ * @param {string} ref - The ref to validate
+ * @throws {Error} If ref contains invalid characters, is too long, or starts with -/--
+ */
+export function validateRef(ref) {
+  if (!ref || typeof ref !== 'string') {
+    throw new Error('Ref must be a non-empty string');
+  }
+  if (ref.length > 1024) {
+    throw new Error(`Ref too long: ${ref.length} chars. Maximum is 1024`);
+  }
+  if (ref.startsWith('-')) {
+    throw new Error(`Invalid ref: ${ref}. Refs cannot start with - or --. See https://github.com/git-stunts/git-warp#security`);
+  }
+  const validRefPattern = /^[a-zA-Z0-9._/-]+((~\d*|\^\d*|\.\.[a-zA-Z0-9._/-]+)*)$/;
+  if (!validRefPattern.test(ref)) {
+    throw new Error(`Invalid ref format: ${ref}. Only alphanumeric characters, ., /, -, _, ^, ~, and range operators are allowed. See https://github.com/git-stunts/git-warp#ref-validation`);
+  }
+}
+
+/**
+ * Validates that a limit is a safe positive integer (max 10M).
+ * @param {number} limit - The limit to validate
+ * @throws {Error} If limit is invalid
+ */
+export function validateLimit(limit) {
+  if (typeof limit !== 'number' || !Number.isFinite(limit)) {
+    throw new Error('Limit must be a finite number');
+  }
+  if (!Number.isInteger(limit)) {
+    throw new Error('Limit must be an integer');
+  }
+  if (limit <= 0) {
+    throw new Error('Limit must be a positive integer');
+  }
+  if (limit > 10_000_000) {
+    throw new Error(`Limit too large: ${limit}. Maximum is 10,000,000`);
+  }
+}
+
+/**
+ * Validates that a config key is safe and well-formed.
+ * @param {string} key - The config key to validate
+ * @throws {Error} If key is invalid
+ */
+export function validateConfigKey(key) {
+  if (!key || typeof key !== 'string') {
+    throw new Error('Config key must be a non-empty string');
+  }
+  if (key.length > 256) {
+    throw new Error(`Config key too long: ${key.length} chars. Maximum is 256`);
+  }
+  if (key.startsWith('-')) {
+    throw new Error(`Invalid config key: ${key}. Keys cannot start with -`);
+  }
+  const validKeyPattern = /^[a-zA-Z][a-zA-Z0-9._-]*$/;
+  if (!validKeyPattern.test(key)) {
+    throw new Error(`Invalid config key format: ${key}`);
+  }
+}

package/src/infrastructure/codecs/CborCodec.js

@@ -83,17 +83,18 @@ const encoder = new Encoder({
  * @private
  */
 function isPlainObject(value) {
-  return typeof value === 'object' && (value.constructor === Object || value.constructor === undefined);
+  return typeof value === 'object' && value !== null && (value.constructor === Object || value.constructor === undefined);
 }
 
 /**
  * Sorts the keys of a plain object and recursively processes values.
  *
- * @param {Object} obj - The plain object to process
- * @returns {Object} A new object with sorted keys
+ * @param {Record<string, unknown>} obj - The plain object to process
+ * @returns {Record<string, unknown>} A new object with sorted keys
  * @private
  */
 function sortPlainObject(obj) {
+  /** @type {Record<string, unknown>} */
   const sorted = {};
   const keys = Object.keys(obj).sort();
   for (const key of keys) {
@@ -106,8 +107,8 @@ function sortPlainObject(obj) {
  * Converts a Map to a sorted plain object with recursive value processing.
  * Validates that all Map keys are strings (required for CBOR encoding).
  *
- * @param {Map} map - The Map instance to convert
- * @returns {Object} A plain object with sorted keys
+ * @param {Map<string, unknown>} map - The Map instance to convert
+ * @returns {Record<string, unknown>} A plain object with sorted keys
  * @throws {TypeError} If any Map key is not a string
  * @private
  */
@@ -118,6 +119,7 @@ function sortMapToObject(map) {
       throw new TypeError(`Map keys must be strings for CBOR encoding, got ${typeof key}`);
     }
   }
+  /** @type {Record<string, unknown>} */
   const sorted = {};
   keys.sort();
   for (const key of keys) {
@@ -198,7 +200,7 @@ function sortKeys(value) {
 
   // Plain objects: sort keys and recursively process values
   if (isPlainObject(value)) {
-    return sortPlainObject(value);
+    return sortPlainObject(/** @type {Record<string, unknown>} */ (value));
   }
 
   // Map instances: convert to sorted object
@@ -370,12 +372,18 @@ export function decode(buffer) {
  * @extends CodecPort
  */
 export class CborCodec extends CodecPort {
-  /** @inheritdoc */
+  /**
+   * @param {unknown} data
+   * @returns {Buffer|Uint8Array}
+   */
   encode(data) {
     return encode(data);
   }
 
-  /** @inheritdoc */
+  /**
+   * @param {Buffer|Uint8Array} buffer
+   * @returns {unknown}
+   */
   decode(buffer) {
     return decode(buffer);
   }

package/src/ports/BlobPort.js

@@ -10,7 +10,7 @@
 export default class BlobPort {
   /**
    * Writes content as a Git blob and returns its OID.
-   * @param {Buffer|string} content - The blob content to write
+   * @param {Buffer|string} _content - The blob content to write
    * @returns {Promise<string>} The Git OID of the created blob
    * @throws {Error} If not implemented by a concrete adapter
    */
@@ -20,7 +20,7 @@ export default class BlobPort {
 
   /**
    * Reads the content of a Git blob.
-   * @param {string} oid - The blob OID to read
+   * @param {string} _oid - The blob OID to read
    * @returns {Promise<Buffer>} The blob content
    * @throws {Error} If not implemented by a concrete adapter
    */

package/src/ports/CodecPort.js

@@ -7,7 +7,7 @@
 export default class CodecPort {
   /**
    * Encodes data to binary format.
-   * @param {unknown} data - Data to encode
+   * @param {unknown} _data - Data to encode
    * @returns {Buffer|Uint8Array} Encoded bytes
    */
   encode(_data) {
@@ -16,7 +16,7 @@ export default class CodecPort {
 
   /**
    * Decodes binary data back to a JavaScript value.
-   * @param {Buffer|Uint8Array} bytes - Encoded bytes to decode
+   * @param {Buffer|Uint8Array} _bytes - Encoded bytes to decode
    * @returns {unknown} Decoded value
    */
   decode(_bytes) {

package/src/ports/CommitPort.js

@@ -10,10 +10,7 @@
 export default class CommitPort {
   /**
    * Creates a commit pointing to the empty tree.
-   * @param {Object} options
-   * @param {string} options.message - The commit message (typically CBOR-encoded patch data)
-   * @param {string[]} [options.parents=[]] - Parent commit SHAs for the commit graph
-   * @param {boolean} [options.sign=false] - Whether to GPG-sign the commit
+   * @param {{ message: string, parents?: string[], sign?: boolean }} _options
    * @returns {Promise<string>} The SHA of the created commit
    * @throws {Error} If not implemented by a concrete adapter
    */
@@ -23,7 +20,7 @@ export default class CommitPort {
 
   /**
    * Retrieves the raw commit message for a given SHA.
-   * @param {string} sha - The commit SHA to read
+   * @param {string} _sha - The commit SHA to read
    * @returns {Promise<string>} The raw commit message content
    * @throws {Error} If not implemented by a concrete adapter
    */
@@ -33,7 +30,7 @@ export default class CommitPort {
 
   /**
    * Gets full commit metadata for a node.
-   * @param {string} sha - The commit SHA to retrieve
+   * @param {string} _sha - The commit SHA to retrieve
    * @returns {Promise<{sha: string, message: string, author: string, date: string, parents: string[]}>}
    *   Full commit metadata including SHA, message, author, date, and parent SHAs
    * @throws {Error} If not implemented by a concrete adapter
@@ -44,10 +41,7 @@ export default class CommitPort {
 
   /**
    * Returns raw git log output for a ref.
-   * @param {Object} options
-   * @param {string} options.ref - The Git ref to log from
-   * @param {number} [options.limit=50] - Maximum number of commits to return
-   * @param {string} [options.format] - Custom format string for git log
+   * @param {{ ref: string, limit?: number, format?: string }} _options
    * @returns {Promise<string>} The raw log output
    * @throws {Error} If not implemented by a concrete adapter
    */
@@ -57,10 +51,7 @@ export default class CommitPort {
 
   /**
    * Streams git log output for a ref.
-   * @param {Object} options
-   * @param {string} options.ref - The Git ref to log from
-   * @param {number} [options.limit=1000000] - Maximum number of commits to return
-   * @param {string} [options.format] - Custom format string for git log
+   * @param {{ ref: string, limit?: number, format?: string }} _options
    * @returns {Promise<import('node:stream').Readable>} A readable stream of log output
    * @throws {Error} If not implemented by a concrete adapter
    */
@@ -70,7 +61,7 @@ export default class CommitPort {
 
   /**
    * Counts nodes reachable from a ref without loading them into memory.
-   * @param {string} ref - Git ref to count from (e.g., 'HEAD', 'main', or a SHA)
+   * @param {string} _ref - Git ref to count from (e.g., 'HEAD', 'main', or a SHA)
    * @returns {Promise<number>} The count of reachable nodes
    * @throws {Error} If not implemented by a concrete adapter
    */
@@ -81,11 +72,7 @@ export default class CommitPort {
   /**
    * Creates a commit pointing to a specified tree (not the empty tree).
    * Used by CheckpointService and PatchBuilderV2 for tree-backed commits.
-   * @param {Object} options
-   * @param {string} options.treeOid - The tree OID to commit
-   * @param {string[]} [options.parents=[]] - Parent commit SHAs
-   * @param {string} options.message - The commit message
-   * @param {boolean} [options.sign=false] - Whether to GPG-sign the commit
+   * @param {{ treeOid: string, parents?: string[], message: string, sign?: boolean }} _options
    * @returns {Promise<string>} The SHA of the created commit
    * @throws {Error} If not implemented by a concrete adapter
    */
@@ -95,7 +82,7 @@ export default class CommitPort {
 
   /**
    * Checks whether a commit exists in the repository.
-   * @param {string} sha - The commit SHA to check
+   * @param {string} _sha - The commit SHA to check
    * @returns {Promise<boolean>} True if the commit exists
    * @throws {Error} If not implemented by a concrete adapter
    */

package/src/ports/ConfigPort.js

@@ -10,7 +10,7 @@
 export default class ConfigPort {
   /**
    * Reads a git config value.
-   * @param {string} key - The config key to read (e.g., 'warp.writerId.events')
+   * @param {string} _key - The config key to read (e.g., 'warp.writerId.events')
    * @returns {Promise<string|null>} The config value, or null if not set
    * @throws {Error} If not implemented by a concrete adapter
    */
@@ -20,8 +20,8 @@ export default class ConfigPort {
 
   /**
    * Sets a git config value.
-   * @param {string} key - The config key to set (e.g., 'warp.writerId.events')
-   * @param {string} value - The value to set
+   * @param {string} _key - The config key to set (e.g., 'warp.writerId.events')
+   * @param {string} _value - The value to set
    * @returns {Promise<void>}
    * @throws {Error} If not implemented by a concrete adapter
    */

package/src/ports/CryptoPort.js

@@ -7,8 +7,8 @@
 export default class CryptoPort {
   /**
    * Computes a hash digest of the given data.
-   * @param {string} algorithm - Hash algorithm (e.g. 'sha1', 'sha256')
-   * @param {string|Buffer|Uint8Array} data - Data to hash
+   * @param {string} _algorithm - Hash algorithm (e.g. 'sha1', 'sha256')
+   * @param {string|Buffer|Uint8Array} _data - Data to hash
    * @returns {Promise<string>} Hex-encoded digest
    */
   async hash(_algorithm, _data) {
@@ -17,9 +17,9 @@ export default class CryptoPort {
 
   /**
    * Computes an HMAC of the given data.
-   * @param {string} algorithm - Hash algorithm (e.g. 'sha256')
-   * @param {string|Buffer|Uint8Array} key - HMAC key
-   * @param {string|Buffer|Uint8Array} data - Data to authenticate
+   * @param {string} _algorithm - Hash algorithm (e.g. 'sha256')
+   * @param {string|Buffer|Uint8Array} _key - HMAC key
+   * @param {string|Buffer|Uint8Array} _data - Data to authenticate
    * @returns {Promise<Buffer|Uint8Array>} Raw HMAC digest
    */
   async hmac(_algorithm, _key, _data) {
@@ -28,8 +28,8 @@ export default class CryptoPort {
 
   /**
    * Constant-time comparison of two buffers.
-   * @param {Buffer|Uint8Array} a - First buffer
-   * @param {Buffer|Uint8Array} b - Second buffer
+   * @param {Buffer|Uint8Array} _a - First buffer
+   * @param {Buffer|Uint8Array} _b - Second buffer
    * @returns {boolean} True if buffers are equal
    */
   timingSafeEqual(_a, _b) {

package/src/ports/GraphPersistencePort.js

@@ -1,3 +1,9 @@
+import CommitPort from './CommitPort.js';
+import BlobPort from './BlobPort.js';
+import TreePort from './TreePort.js';
+import RefPort from './RefPort.js';
+import ConfigPort from './ConfigPort.js';
+
 /**
  * Abstract port for graph persistence operations.
  *
@@ -20,27 +26,19 @@
  * All methods throw by default and must be overridden by implementations.
  *
  * @abstract
- * @implements {CommitPort}
- * @implements {BlobPort}
- * @implements {TreePort}
- * @implements {RefPort}
- * @implements {ConfigPort}
  */
-
-import CommitPort from './CommitPort.js';
-import BlobPort from './BlobPort.js';
-import TreePort from './TreePort.js';
-import RefPort from './RefPort.js';
-import ConfigPort from './ConfigPort.js';
-
 class GraphPersistencePort {}
 
+/** @type {Array<typeof CommitPort | typeof BlobPort | typeof TreePort | typeof RefPort | typeof ConfigPort>} */
 const focusedPorts = [CommitPort, BlobPort, TreePort, RefPort, ConfigPort];
 const seen = new Map();
 
 for (const Port of focusedPorts) {
-  const descriptors = Object.getOwnPropertyDescriptors(Port.prototype);
-  delete descriptors.constructor;
+  const allDescriptors = Object.getOwnPropertyDescriptors(Port.prototype);
+  /** @type {Record<string, PropertyDescriptor>} */
+  const descriptors = Object.fromEntries(
+    Object.entries(allDescriptors).filter(([k]) => k !== 'constructor'),
+  );
 
   for (const [name, descriptor] of Object.entries(descriptors)) {
     if (seen.has(name)) {

package/src/ports/HttpServerPort.js

@@ -12,11 +12,7 @@ export default class HttpServerPort {
    * and must return `{ status, headers, body }`. No raw req/res objects
    * are exposed to the domain.
    *
-   * @param {Function} requestHandler - Async function (request) => response
-   * @param {string} requestHandler.method - HTTP method
-   * @param {string} requestHandler.url - Request URL
-   * @param {Object} requestHandler.headers - Request headers (lowercased keys)
-   * @param {Buffer|undefined} requestHandler.body - Request body (undefined if none)
+   * @param {(request: { method: string, url: string, headers: Object, body: Buffer|undefined }) => Promise<{ status: number, headers: Object, body: string|Buffer }>} _requestHandler - Async function (request) => response
    * @returns {{ listen: Function, close: Function, address: Function }} Server with listen(port, [host], cb(err)), close(cb), and address()
    */
   createServer(_requestHandler) {

package/src/ports/IndexStoragePort.js

@@ -18,6 +18,7 @@ import RefPort from './RefPort.js';
 
 class IndexStoragePort {}
 
+/** @type {Array<[{ prototype: object, name: string }, string[]]>} */
 const picks = [
   [BlobPort, ['writeBlob', 'readBlob']],
   [TreePort, ['writeTree', 'readTreeOids']],

package/src/ports/LoggerPort.js

@@ -13,8 +13,8 @@
 export default class LoggerPort {
   /**
    * Log a debug-level message.
-   * @param {string} message - The log message
-   * @param {Record<string, unknown>} [context] - Structured metadata
+   * @param {string} _message - The log message
+   * @param {Record<string, unknown>} [_context] - Structured metadata
    * @returns {void}
    * @abstract
    */
@@ -24,8 +24,8 @@ export default class LoggerPort {
 
   /**
    * Log an info-level message.
-   * @param {string} message - The log message
-   * @param {Record<string, unknown>} [context] - Structured metadata
+   * @param {string} _message - The log message
+   * @param {Record<string, unknown>} [_context] - Structured metadata
    * @returns {void}
    * @abstract
    */
@@ -35,8 +35,8 @@ export default class LoggerPort {
 
   /**
    * Log a warning-level message.
-   * @param {string} message - The log message
-   * @param {Record<string, unknown>} [context] - Structured metadata
+   * @param {string} _message - The log message
+   * @param {Record<string, unknown>} [_context] - Structured metadata
    * @returns {void}
    * @abstract
    */
@@ -46,8 +46,8 @@ export default class LoggerPort {
 
   /**
    * Log an error-level message.
-   * @param {string} message - The log message
-   * @param {Record<string, unknown>} [context] - Structured metadata
+   * @param {string} _message - The log message
+   * @param {Record<string, unknown>} [_context] - Structured metadata
    * @returns {void}
    * @abstract
    */
@@ -58,7 +58,7 @@ export default class LoggerPort {
   /**
    * Create a child logger with additional base context.
    * Child loggers inherit parent context and merge with their own.
-   * @param {Record<string, unknown>} context - Base context for the child logger
+   * @param {Record<string, unknown>} _context - Base context for the child logger
    * @returns {LoggerPort} A new logger instance with merged context
    * @abstract
    */

package/src/ports/RefPort.js

@@ -10,8 +10,8 @@
 export default class RefPort {
   /**
    * Updates a ref to point to an OID.
-   * @param {string} ref - The ref name (e.g., 'refs/warp/events/writers/alice')
-   * @param {string} oid - The OID to point to
+   * @param {string} _ref - The ref name (e.g., 'refs/warp/events/writers/alice')
+   * @param {string} _oid - The OID to point to
    * @returns {Promise<void>}
    * @throws {Error} If not implemented by a concrete adapter
    */
@@ -21,7 +21,7 @@ export default class RefPort {
 
   /**
    * Reads the OID a ref points to.
-   * @param {string} ref - The ref name
+   * @param {string} _ref - The ref name
    * @returns {Promise<string|null>} The OID, or null if the ref does not exist
    * @throws {Error} If not implemented by a concrete adapter
    */
@@ -31,7 +31,7 @@ export default class RefPort {
 
   /**
    * Deletes a ref.
-   * @param {string} ref - The ref name to delete
+   * @param {string} _ref - The ref name to delete
    * @returns {Promise<void>}
    * @throws {Error} If not implemented by a concrete adapter
    */
@@ -41,7 +41,7 @@ export default class RefPort {
 
   /**
    * Lists refs matching a prefix.
-   * @param {string} prefix - The ref prefix to match (e.g., 'refs/warp/events/writers/')
+   * @param {string} _prefix - The ref prefix to match (e.g., 'refs/warp/events/writers/')
    * @returns {Promise<string[]>} Array of matching ref names
    * @throws {Error} If not implemented by a concrete adapter
    */

package/src/ports/SeekCachePort.js

@@ -0,0 +1,73 @@
+/**
+ * Port interface for seek materialization cache operations.
+ *
+ * Defines the contract for caching and retrieving serialized WarpStateV5
+ * snapshots keyed by (ceiling, frontier) tuples. Used by the seek time-travel
+ * feature to avoid full re-materialization for previously-visited ticks.
+ *
+ * Concrete adapters (e.g., CasSeekCacheAdapter) implement this interface
+ * to store cached states in different backends (git-cas, filesystem, etc.).
+ *
+ * @abstract
+ */
+export default class SeekCachePort {
+  /**
+   * Retrieves a cached state buffer by key.
+   * @param {string} _key - Cache key (e.g., 'v1:t42-<frontierHash>')
+   * @returns {Promise<Buffer|null>} The cached buffer, or null on miss
+   * @throws {Error} If not implemented by a concrete adapter
+   */
+  async get(_key) {
+    throw new Error('SeekCachePort.get() not implemented');
+  }
+
+  /**
+   * Stores a state buffer under the given key.
+   * @param {string} _key - Cache key
+   * @param {Buffer} _buffer - Serialized state to cache
+   * @returns {Promise<void>}
+   * @throws {Error} If not implemented by a concrete adapter
+   */
+  async set(_key, _buffer) {
+    throw new Error('SeekCachePort.set() not implemented');
+  }
+
+  /**
+   * Checks whether a key exists in the cache.
+   * @param {string} _key - Cache key
+   * @returns {Promise<boolean>}
+   * @throws {Error} If not implemented by a concrete adapter
+   */
+  async has(_key) {
+    throw new Error('SeekCachePort.has() not implemented');
+  }
+
+  /**
+   * Lists all keys currently in the cache index.
+   * Note: keys may reference GC'd blobs; callers should handle miss on get().
+   * @returns {Promise<string[]>}
+   * @throws {Error} If not implemented by a concrete adapter
+   */
+  async keys() {
+    throw new Error('SeekCachePort.keys() not implemented');
+  }
+
+  /**
+   * Removes a single entry from the cache.
+   * @param {string} _key - Cache key to remove
+   * @returns {Promise<boolean>} True if the entry existed and was removed
+   * @throws {Error} If not implemented by a concrete adapter
+   */
+  async delete(_key) {
+    throw new Error('SeekCachePort.delete() not implemented');
+  }
+
+  /**
+   * Removes all entries from the cache.
+   * @returns {Promise<void>}
+   * @throws {Error} If not implemented by a concrete adapter
+   */
+  async clear() {
+    throw new Error('SeekCachePort.clear() not implemented');
+  }
+}

package/src/ports/TreePort.js

@@ -10,7 +10,7 @@
 export default class TreePort {
   /**
    * Creates a Git tree from mktree-formatted entries.
-   * @param {string[]} entries - Lines in git mktree format (e.g., "100644 blob <oid>\t<path>")
+   * @param {string[]} _entries - Lines in git mktree format (e.g., "100644 blob <oid>\t<path>")
    * @returns {Promise<string>} The Git OID of the created tree
    * @throws {Error} If not implemented by a concrete adapter
    */
@@ -20,7 +20,7 @@ export default class TreePort {
 
   /**
    * Reads a tree and returns a map of path to content.
-   * @param {string} treeOid - The tree OID to read
+   * @param {string} _treeOid - The tree OID to read
    * @returns {Promise<Record<string, Buffer>>} Map of file path to blob content
    * @throws {Error} If not implemented by a concrete adapter
    */
@@ -31,7 +31,7 @@ export default class TreePort {
   /**
    * Reads a tree and returns a map of path to blob OID.
    * Useful for lazy-loading shards without reading all blob contents.
-   * @param {string} treeOid - The tree OID to read
+   * @param {string} _treeOid - The tree OID to read
    * @returns {Promise<Record<string, string>>} Map of file path to blob OID
    * @throws {Error} If not implemented by a concrete adapter
    */

package/src/visualization/layouts/converters.js

@@ -6,13 +6,19 @@
  *   { nodes: [{ id, label, props? }], edges: [{ from, to, label? }] }
  */
 
+/**
+ * @typedef {{ id: string, label: string, props?: Record<string, any> }} GraphDataNode
+ * @typedef {{ from: string, to: string, label?: string }} GraphDataEdge
+ * @typedef {{ nodes: GraphDataNode[], edges: GraphDataEdge[] }} GraphData
+ */
+
 /**
  * Converts a query result payload + edge array into graph data.
  * Edges are filtered to only those connecting matched nodes.
  *
- * @param {Object} payload - Query result { nodes: [{id, props}] }
- * @param {Array}  edges   - Edge array from graph.getEdges()
- * @returns {{ nodes: Array, edges: Array }}
+ * @param {{ nodes?: Array<{ id: string, props?: Record<string, any> }> } | null} payload - Query result
+ * @param {Array<{ from: string, to: string, label?: string }>}  edges   - Edge array from graph.getEdges()
+ * @returns {GraphData}
  */
 export function queryResultToGraphData(payload, edges) {
   const nodes = (payload?.nodes ?? []).map((n) => ({
@@ -34,8 +40,8 @@ export function queryResultToGraphData(payload, edges) {
  * Converts a path result payload into graph data.
  * Builds a linear chain of nodes with labelled edges.
  *
- * @param {Object} payload - Path result { path: string[], edges?: string[] }
- * @returns {{ nodes: Array, edges: Array }}
+ * @param {{ path?: string[], edges?: string[] } | null} payload - Path result
+ * @returns {GraphData}
  */
 export function pathResultToGraphData(payload) {
   const pathArr = payload?.path ?? [];
@@ -43,6 +49,7 @@ export function pathResultToGraphData(payload) {
 
   const nodes = pathArr.map((id) => ({ id, label: id }));
 
+  /** @type {GraphDataEdge[]} */
   const edges = [];
   for (let i = 0; i < pathArr.length - 1; i++) {
     edges.push({
@@ -59,8 +66,8 @@ export function pathResultToGraphData(payload) {
  * Converts raw getNodes() + getEdges() output into graph data.
  *
  * @param {string[]} nodeIds - Array of node IDs
- * @param {Array}    edges   - Edge array from graph.getEdges()
- * @returns {{ nodes: Array, edges: Array }}
+ * @param {Array<{ from: string, to: string, label?: string }>}    edges   - Edge array from graph.getEdges()
+ * @returns {GraphData}
  */
 export function rawGraphToGraphData(nodeIds, edges) {
   const nodes = (nodeIds ?? []).map((id) => ({ id, label: id }));