@git-stunts/git-warp 12.3.0 → 12.4.1

package/src/domain/services/WormholeService.js

@@ -61,13 +61,8 @@ async function verifyShaExists(persistence, sha, paramName) {
 
 /**
  * Processes a single commit in the wormhole chain.
- * @param {Object} opts - Options
- * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default} opts.persistence - Git persistence adapter
- * @param {string} opts.sha - The commit SHA
- * @param {string} opts.graphName - Expected graph name
- * @param {string|null} opts.expectedWriter - Expected writer ID (null for first commit)
- * @param {import('../../ports/CodecPort.js').default} [opts.codec] - Codec for deserialization
- * @returns {Promise<{patch: Object, sha: string, writerId: string, parentSha: string|null}>}
+ * @param {{ persistence: import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default, sha: string, graphName: string, expectedWriter: string|null, codec?: import('../../ports/CodecPort.js').default }} opts - Options
+ * @returns {Promise<{patch: import('../types/WarpTypesV2.js').PatchV2, sha: string, writerId: string, parentSha: string|null}>}
  * @throws {WormholeError} On validation errors
  * @private
  */
@@ -101,7 +96,7 @@ async function processCommit({ persistence, sha, graphName, expectedWriter, code
   }
 
   const patchBuffer = await persistence.readBlob(patchMeta.patchOid);
-  const patch = /** @type {Object} */ (codec.decode(patchBuffer));
+  const patch = /** @type {import('../types/WarpTypesV2.js').PatchV2} */ (codec.decode(patchBuffer));
 
   return {
     patch,
@@ -135,12 +130,7 @@ async function processCommit({ persistence, sha, graphName, expectedWriter, code
  * must be an ancestor of `toSha` in the writer's patch chain. Both endpoints
  * are inclusive in the wormhole.
  *
- * @param {Object} options - Wormhole creation options
- * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default} options.persistence - Git persistence adapter
- * @param {string} options.graphName - Name of the graph
- * @param {string} options.fromSha - SHA of the first (oldest) patch commit
- * @param {string} options.toSha - SHA of the last (newest) patch commit
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
+ * @param {{ persistence: import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default, graphName: string, fromSha: string, toSha: string, codec?: import('../../ports/CodecPort.js').default }} options - Wormhole creation options
  * @returns {Promise<WormholeEdge>} The created wormhole
  * @throws {WormholeError} If fromSha or toSha doesn't exist (E_WORMHOLE_SHA_NOT_FOUND)
  * @throws {WormholeError} If fromSha is not an ancestor of toSha (E_WORMHOLE_INVALID_RANGE)
@@ -171,13 +161,8 @@ export async function createWormhole({ persistence, graphName, fromSha, toSha, c
  * Walks the parent chain from toSha towards fromSha, collecting and
  * validating each commit along the way.
  *
- * @param {Object} options
- * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default} options.persistence - Git persistence adapter
- * @param {string} options.graphName - Expected graph name
- * @param {string} options.fromSha - SHA of the first (oldest) patch commit
- * @param {string} options.toSha - SHA of the last (newest) patch commit
- * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
- * @returns {Promise<Array<{patch: Object, sha: string, writerId: string}>>} Patches in newest-first order
+ * @param {{ persistence: import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default, graphName: string, fromSha: string, toSha: string, codec?: import('../../ports/CodecPort.js').default }} options
+ * @returns {Promise<Array<{patch: import('../types/WarpTypesV2.js').PatchV2, sha: string, writerId: string}>>} Patches in newest-first order
  * @throws {WormholeError} If fromSha is not an ancestor of toSha or range is empty
  * @private
  */
@@ -232,8 +217,7 @@ async function collectPatchRange({ persistence, graphName, fromSha, toSha, codec
  *
  * @param {WormholeEdge} first - The earlier (older) wormhole
  * @param {WormholeEdge} second - The later (newer) wormhole
- * @param {Object} [options] - Composition options
- * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default} [options.persistence] - Git persistence adapter (for validation)
+ * @param {{ persistence?: import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default }} [options] - Composition options
  * @returns {Promise<WormholeEdge>} The composed wormhole
  * @throws {WormholeError} If wormholes are from different writers (E_WORMHOLE_MULTI_WRITER)
  * @throws {WormholeError} If wormholes are not consecutive (E_WORMHOLE_INVALID_RANGE)
@@ -294,7 +278,7 @@ export function replayWormhole(wormhole, initialState) {
  * Serializes a wormhole to a JSON-serializable object.
  *
  * @param {WormholeEdge} wormhole - The wormhole to serialize
- * @returns {Object} JSON-serializable representation
+ * @returns {Record<string, unknown>} JSON-serializable representation
  */
 export function serializeWormhole(wormhole) {
   return {
@@ -309,7 +293,7 @@ export function serializeWormhole(wormhole) {
 /**
  * Deserializes a wormhole from a JSON object.
  *
- * @param {Object} json - The JSON object to deserialize
+ * @param {Record<string, unknown>} json - The JSON object to deserialize
  * @returns {WormholeEdge} The deserialized wormhole
  * @throws {WormholeError} If the JSON structure is invalid
  */

package/src/domain/trust/TrustCrypto.js

@@ -63,11 +63,7 @@ function decodePublicKey(base64) {
 /**
  * Verifies an Ed25519 signature against a payload.
  *
- * @param {Object} params
- * @param {string} params.algorithm - Must be 'ed25519'
- * @param {string} params.publicKeyBase64 - Base64-encoded 32-byte public key
- * @param {string} params.signatureBase64 - Base64-encoded signature
- * @param {Buffer} params.payload - Bytes to verify
+ * @param {{ algorithm: string, publicKeyBase64: string, signatureBase64: string, payload: Buffer }} params
  * @returns {boolean} true if signature is valid
  * @throws {TrustError} E_TRUST_UNSUPPORTED_ALGORITHM for non-ed25519
  * @throws {TrustError} E_TRUST_INVALID_KEY for malformed public key

package/src/domain/trust/TrustEvaluator.js

@@ -21,14 +21,7 @@ import { deriveTrustVerdict } from './verdict.js';
  * @property {number} trustSchemaVersion
  * @property {string} mode
  * @property {string} trustVerdict
- * @property {Object} trust
- * @property {'configured'|'pinned'|'error'|'not_configured'} trust.status
- * @property {string} trust.source
- * @property {string|null} trust.sourceDetail
- * @property {string[]} trust.evaluatedWriters
- * @property {string[]} trust.untrustedWriters
- * @property {ReadonlyArray<{writerId: string, trusted: boolean, reasonCode: string, reason: string}>} trust.explanations
- * @property {Record<string, number> & {recordsScanned: number, activeKeys: number, revokedKeys: number, activeBindings: number, revokedBindings: number}} trust.evidenceSummary
+ * @property {{ status: 'configured'|'pinned'|'error'|'not_configured', source: string, sourceDetail: string|null, evaluatedWriters: string[], untrustedWriters: string[], explanations: ReadonlyArray<{writerId: string, trusted: boolean, reasonCode: string, reason: string}>, evidenceSummary: Record<string, number> & {recordsScanned: number, activeKeys: number, revokedKeys: number, activeBindings: number, revokedBindings: number} }} trust
  */
 
 /**

package/src/domain/trust/TrustRecordService.js

@@ -12,6 +12,7 @@
 import { buildTrustRecordRef } from '../utils/RefLayout.js';
 import { TrustRecordSchema } from './schemas.js';
 import { verifyRecordId } from './TrustCanonical.js';
+import PersistenceError from '../errors/PersistenceError.js';
 import TrustError from '../errors/TrustError.js';
 
 /**
@@ -32,9 +33,7 @@ const MAX_CAS_ATTEMPTS = 3;
 
 export class TrustRecordService {
   /**
-   * @param {Object} options
-   * @param {import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default & import('../../ports/RefPort.js').default} options.persistence - GraphPersistencePort adapter
-   * @param {import('../../ports/CodecPort.js').default} options.codec - CodecPort adapter (CBOR)
+   * @param {{ persistence: import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default & import('../../ports/RefPort.js').default, codec: import('../../ports/CodecPort.js').default }} options
    */
   constructor({ persistence, codec }) {
     this._persistence = persistence;
@@ -104,8 +103,7 @@ export class TrustRecordService {
    * Reads all trust records from the chain, oldest first.
    *
    * @param {string} graphName
-   * @param {Object} [options]
-   * @param {string} [options.tip] - Override tip commit (for pinned reads)
+   * @param {{ tip?: string }} [options]
    * @returns {Promise<ReadRecordsResult>}
    */
   async readRecords(graphName, options = {}) {
@@ -118,7 +116,7 @@ export class TrustRecordService {
           tip = await this._persistence.readRef(ref);
         } catch (err) {
           // Distinguish "ref not found" from operational error (J15)
-          if (err instanceof Error && (err.message?.includes('not found') || err.message?.includes('does not exist'))) {
+          if (err instanceof PersistenceError && err.code === PersistenceError.E_REF_NOT_FOUND) {
             return { ok: true, records: [] };
           }
           return {
@@ -234,10 +232,7 @@ export class TrustRecordService {
    *
    * @param {string} graphName
    * @param {Record<string, unknown>} record - Complete signed trust record
-   * @param {Object} [options]
-   * @param {number} [options.maxRetries=3] - Maximum rebuild-and-retry attempts
-   * @param {((record: Record<string, unknown>) => Promise<Record<string, unknown>>)|null} [options.resign] - Function to re-sign a rebuilt record (null for unsigned)
-   * @param {boolean} [options.skipSignatureVerify=false] - Skip signature verification
+   * @param {{ maxRetries?: number, resign?: ((record: Record<string, unknown>) => Promise<Record<string, unknown>>)|null, skipSignatureVerify?: boolean }} [options]
    * @returns {Promise<{commitSha: string, ref: string, attempts: number}>}
    * @throws {TrustError} E_TRUST_CAS_EXHAUSTED if all retries fail
    */

package/src/domain/types/TickReceipt.js

@@ -175,11 +175,7 @@ function validateOpResult(value, i) {
 /**
  * Creates an immutable TickReceipt.
  *
- * @param {Object} params
- * @param {string} params.patchSha - SHA of the patch commit
- * @param {string} params.writer - Writer ID
- * @param {number} params.lamport - Lamport timestamp (non-negative integer)
- * @param {OpOutcome[]} params.ops - Per-operation outcome records
+ * @param {{ patchSha: string, writer: string, lamport: number, ops: OpOutcome[] }} params
  * @returns {Readonly<TickReceipt>} Frozen tick receipt
  * @throws {Error} If any parameter is invalid
  */
@@ -279,9 +275,9 @@ export function canonicalJson(receipt) {
  */
 function sortedReplacer(_key, value) {
   if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
-    /** @type {{ [x: string]: * }} */
+    /** @type {{ [x: string]: unknown }} */
     const sorted = {};
-    const obj = /** @type {{ [x: string]: * }} */ (value);
+    const obj = /** @type {{ [x: string]: unknown }} */ (value);
     for (const k of Object.keys(obj).sort()) {
       sorted[k] = obj[k];
     }

package/src/domain/types/WarpTypes.js

@@ -197,11 +197,7 @@ export function createPropSet(node, key, value) {
 
 /**
  * Creates an EventId
- * @param {Object} options - EventId options
- * @param {number} options.lamport - Lamport timestamp
- * @param {string} options.writerId - Writer ID
- * @param {string} options.patchSha - Patch SHA
- * @param {number} options.opIndex - Operation index within patch
+ * @param {{ lamport: number, writerId: string, patchSha: string, opIndex: number }} options - EventId options
  * @returns {EventId} EventId object
  */
 export function createEventId({ lamport, writerId, patchSha, opIndex }) {

package/src/domain/types/WarpTypesV2.js

@@ -241,14 +241,7 @@ export function createEdgePropSetV2(from, to, label, key, value) {
 
 /**
  * Creates a PatchV2
- * @param {Object} options - Patch options
- * @param {2|3} [options.schema=2] - Schema version (2 for node-only, 3 for edge properties)
- * @param {string} options.writer - Writer ID
- * @param {number} options.lamport - Lamport timestamp
- * @param {VersionVector} options.context - Writer's observed frontier
- * @param {OpV2[]} options.ops - Array of operations
- * @param {string[]} [options.reads] - Node/edge IDs read by this patch (for provenance tracking)
- * @param {string[]} [options.writes] - Node/edge IDs written by this patch (for provenance tracking)
+ * @param {{ schema?: 2|3, writer: string, lamport: number, context: VersionVector, ops: OpV2[], reads?: string[], writes?: string[] }} options - Patch options
  * @returns {PatchV2} PatchV2 object
  */
 export function createPatchV2({ schema = 2, writer, lamport, context, ops, reads, writes }) {

package/src/domain/utils/CachedValue.js

@@ -28,10 +28,7 @@ class CachedValue {
   /**
    * Creates a CachedValue instance.
    *
-   * @param {Object} options
-   * @param {import('../../ports/ClockPort.js').default} options.clock - Clock port for timing
-   * @param {number} options.ttlMs - Time-to-live in milliseconds
-   * @param {() => T | Promise<T>} options.compute - Function to compute the value when cache is stale
+   * @param {{ clock: import('../../ports/ClockPort.js').default, ttlMs: number, compute: () => T | Promise<T> }} options
    * @throws {Error} If ttlMs is not a positive number
    */
   constructor({ clock, ttlMs, compute }) {

package/src/domain/utils/MinHeap.js

@@ -9,9 +9,9 @@ class MinHeap {
   /**
    * Creates an empty MinHeap.
    *
-   * @param {Object} [options] - Configuration options
-   * @param {((a: T, b: T) => number)} [options.tieBreaker] - Comparator invoked when two
-   *   entries have equal priority. Negative return = a wins (comes out first).
+   * @param {{ tieBreaker?: (a: T, b: T) => number }} [options] - Configuration options.
+   *   `tieBreaker`: comparator invoked when two entries have equal priority.
+   *   Negative return = a wins (comes out first).
    *   When omitted, equal-priority extraction order is unspecified (heap-natural).
    */
   constructor(options) {

package/src/domain/utils/RefLayout.js

@@ -45,6 +45,23 @@ const WRITER_ID_PATTERN = /^[A-Za-z0-9._-]+$/;
  */
 const PATH_TRAVERSAL_PATTERN = /\.\./;
 
+/**
+ * Ref-layout keywords that must not appear as any `/`-delimited segment
+ * of a graph name. Using one of these would create an ambiguous ref path
+ * (e.g. `refs/warp/writers/writers/alice`).
+ *
+ * @type {Set<string>}
+ */
+export const RESERVED_GRAPH_NAME_SEGMENTS = new Set([
+  'writers',
+  'checkpoints',
+  'coverage',
+  'cursor',
+  'audit',
+  'trust',
+  'seek-cache',
+]);
+
 // -----------------------------------------------------------------------------
 // Validators
 // -----------------------------------------------------------------------------
@@ -94,6 +111,15 @@ export function validateGraphName(name) {
   if (name.includes('\0')) {
     throw new Error(`Invalid graph name: contains null byte: ${name}`);
   }
+
+  const segments = name.split('/');
+  for (const seg of segments) {
+    if (RESERVED_GRAPH_NAME_SEGMENTS.has(seg)) {
+      throw new Error(
+        `Invalid graph name: segment '${seg}' is a reserved ref-layout keyword: ${name}`
+      );
+    }
+  }
 }
 
 /**

package/src/domain/utils/WriterId.js

@@ -116,8 +116,7 @@ function crockfordBase32(bytes) {
  * Uses 128 bits of entropy (16 bytes) encoded as Crockford Base32.
  * The result is prefixed with `w_` for a total length of 28 characters.
  *
- * @param {Object} [options]
- * @param {(n: number) => Uint8Array} [options.randomBytes] - Custom RNG for testing
+ * @param {{ randomBytes?: (n: number) => Uint8Array }} [options] - Options with optional custom RNG for testing
  * @returns {string} A canonical writer ID (e.g., 'w_0123456789abcdefghjkmnpqrs')
  * @throws {WriterIdError} If RNG is unavailable or returns wrong shape
  *
@@ -148,11 +147,7 @@ export function generateWriterId({ randomBytes } = {}) {
  * 2. Load from git config key `warp.writerId.<graphName>`
  * 3. If missing or invalid, generate new canonical ID, persist, and return
  *
- * @param {Object} args
- * @param {string} args.graphName - The graph name
- * @param {string|undefined} args.explicitWriterId - Optional explicit writer ID
- * @param {(key: string) => Promise<string|null>} args.configGet - Function to read git config
- * @param {(key: string, value: string) => Promise<void>} args.configSet - Function to write git config
+ * @param {{ graphName: string, explicitWriterId: string|null|undefined, configGet: (key: string) => Promise<string|null>, configSet: (key: string, value: string) => Promise<void> }} args
  * @returns {Promise<string>} The resolved writer ID
  * @throws {WriterIdError} If config operations fail
  *

package/src/domain/utils/canonicalCbor.js

@@ -28,7 +28,7 @@ export function encodeCanonicalCbor(value) {
 /**
  * Decodes CBOR bytes to a value.
  *
- * @param {Buffer|Uint8Array} buffer - CBOR bytes
+ * @param {Uint8Array} buffer - CBOR bytes
  * @returns {unknown} Decoded value
  */
 export function decodeCanonicalCbor(buffer) {

package/src/domain/utils/defaultCodec.js

@@ -34,7 +34,7 @@ function sortKeys(value) {
     }
     return sorted;
   }
-  if (typeof value === 'object' && (/** @type {Object} */ (value).constructor === Object || /** @type {Object} */ (value).constructor === undefined)) {
+  if (typeof value === 'object' && (/** @type {Record<string, unknown>} */ (value).constructor === Object || /** @type {Record<string, unknown>} */ (value).constructor === undefined)) {
     /** @type {Record<string, unknown>} */
     const sorted = {};
     for (const key of Object.keys(value).sort()) {

package/src/domain/utils/parseCursorBlob.js

@@ -5,13 +5,13 @@
  */
 
 /**
- * Parses and validates a cursor blob (Buffer) into a cursor object.
+ * Parses and validates a cursor blob (Uint8Array) into a cursor object.
  *
  * The blob must contain UTF-8-encoded JSON representing a plain object with at
  * minimum a finite numeric `tick` field.  Any additional fields (e.g. `mode`,
  * `name`) are preserved in the returned object.
  *
- * @param {Buffer} buf - Raw blob contents (UTF-8 encoded JSON)
+ * @param {Uint8Array} buf - Raw blob contents (UTF-8 encoded JSON)
  * @param {string} label - Human-readable label used in error messages
  *   (e.g. `"active cursor"`, `"saved cursor 'foo'"`)
  * @returns {{ tick: number, mode?: string, [key: string]: unknown }}
@@ -23,13 +23,13 @@
  *   Infinity
  *
  * @example
- * const buf = Buffer.from('{"tick":5,"mode":"lamport"}', 'utf8');
+ * const buf = new TextEncoder().encode('{"tick":5,"mode":"lamport"}');
  * const cursor = parseCursorBlob(buf, 'active cursor');
  * // => { tick: 5, mode: 'lamport' }
  *
  * @example
  * // Throws: "Corrupted active cursor: blob is not valid JSON"
- * parseCursorBlob(Buffer.from('not json', 'utf8'), 'active cursor');
+ * parseCursorBlob(new TextEncoder().encode('not json'), 'active cursor');
  */
 export function parseCursorBlob(buf, label) {
   let obj;

package/src/domain/warp/PatchSession.js

@@ -19,12 +19,7 @@ export class PatchSession {
   /**
    * Creates a new PatchSession.
    *
-   * @param {Object} options
-   * @param {import('../services/PatchBuilderV2.js').PatchBuilderV2} options.builder - Internal builder
-   * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default} options.persistence - Git adapter
-   * @param {string} options.graphName - Graph namespace
-   * @param {string} options.writerId - Writer ID
-   * @param {string|null} options.expectedOldHead - Expected parent SHA for CAS
+   * @param {{ builder: import('../services/PatchBuilderV2.js').PatchBuilderV2, persistence: import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default, graphName: string, writerId: string, expectedOldHead: string|null }} options
    */
   constructor({ builder, persistence, graphName, writerId, expectedOldHead }) {
     /** @type {import('../services/PatchBuilderV2.js').PatchBuilderV2} */
@@ -152,7 +147,7 @@ export class PatchSession {
    * Attaches content to a node.
    *
    * @param {string} nodeId - The node ID to attach content to
-   * @param {Buffer|string} content - The content to attach
+   * @param {Uint8Array|string} content - The content to attach
    * @returns {Promise<this>} This session for chaining
    * @throws {WriterError} SESSION_COMMITTED if already committed
    */
@@ -168,7 +163,7 @@ export class PatchSession {
    * @param {string} from - Source node ID
    * @param {string} to - Target node ID
    * @param {string} label - Edge label/type
-   * @param {Buffer|string} content - The content to attach
+   * @param {Uint8Array|string} content - The content to attach
    * @returns {Promise<this>} This session for chaining
    * @throws {WriterError} SESSION_COMMITTED if already committed
    */

package/src/domain/warp/Writer.js

@@ -36,16 +36,7 @@ export class Writer {
   /**
    * Creates a new Writer instance.
    *
-   * @param {Object} options
-   * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default & import('../../ports/CommitPort.js').default} options.persistence - Git adapter
-   * @param {string} options.graphName - Graph namespace
-   * @param {string} options.writerId - This writer's ID
-   * @param {import('../crdt/VersionVector.js').VersionVector} options.versionVector - Current version vector
-   * @param {() => Promise<import('../services/JoinReducer.js').WarpStateV5>} options.getCurrentState - Async function returning the current materialized V5 state
-   * @param {(result: {patch: Object, sha: string}) => void | Promise<void>} [options.onCommitSuccess] - Callback invoked after successful commit with { patch, sha }
-   * @param {'reject'|'cascade'|'warn'} [options.onDeleteWithData='warn'] - Policy when deleting a node with attached data
-   * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for CBOR serialization (defaults to domain-local codec)
-   * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger port
+   * @param {{ persistence: import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default & import('../../ports/CommitPort.js').default, graphName: string, writerId: string, versionVector: import('../crdt/VersionVector.js').VersionVector, getCurrentState: () => import('../services/JoinReducer.js').WarpStateV5 | null, onCommitSuccess?: (result: {patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}) => void | Promise<void>, onDeleteWithData?: 'reject'|'cascade'|'warn', codec?: import('../../ports/CodecPort.js').default, logger?: import('../../ports/LoggerPort.js').default }} options
    */
   constructor({ persistence, graphName, writerId, versionVector, getCurrentState, onCommitSuccess, onDeleteWithData = 'warn', codec, logger }) {
     validateWriterId(writerId);
@@ -62,10 +53,10 @@ export class Writer {
     /** @type {import('../crdt/VersionVector.js').VersionVector} */
     this._versionVector = versionVector;
 
-    /** @type {Function} */
+    /** @type {() => import('../services/JoinReducer.js').WarpStateV5 | null} */
     this._getCurrentState = getCurrentState;
 
-    /** @type {Function|undefined} */
+    /** @type {((result: {patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}) => void | Promise<void>)|undefined} */
     this._onCommitSuccess = onCommitSuccess;
 
     /** @type {'reject'|'cascade'|'warn'} */

package/src/domain/warp/_wire.js

@@ -14,8 +14,8 @@
  * become method names on the prototype. Duplicates across modules are
  * detected eagerly and throw at import time (not at call time).
  *
- * @param {Function} Class - The class constructor whose prototype to extend
- * @param {Array<Record<string, Function>>} methodModules - Array of method module namespace objects
+ * @param {{ prototype: object, name: string }} Class - The class constructor whose prototype to extend
+ * @param {Array<Record<string, unknown>>} methodModules - Array of method module namespace objects
  * @throws {Error} If a method name appears in more than one module
  */
 export function wireWarpMethods(Class, methodModules) {

package/src/domain/warp/_wiredMethods.d.ts

@@ -179,13 +179,11 @@ declare module '../WarpGraph.js' {
     // ── provenance.methods.js ─────────────────────────────────────────────
     patchesFor(entityId: string): Promise<string[]>;
     materializeSlice(nodeId: string, options?: { receipts?: boolean }): Promise<{ state: WarpStateV5; patchCount: number; receipts?: TickReceipt[] }>;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- internal method; `any` avoids breaking provenance.methods.js callers
-    _computeBackwardCone(nodeId: string): Promise<Map<string, any>>;
-    loadPatchBySha(sha: string): Promise<{ patch: PatchV2; sha: string }>;
-    _loadPatchBySha(sha: string): Promise<{ patch: PatchV2; sha: string }>;
+    _computeBackwardCone(nodeId: string): Promise<Map<string, PatchV2>>;
+    loadPatchBySha(sha: string): Promise<PatchV2>;
+    _loadPatchBySha(sha: string): Promise<PatchV2>;
     _loadPatchesBySha(shas: string[]): Promise<Array<{ patch: PatchV2; sha: string }>>;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- internal method; `any` avoids breaking provenance.methods.js callers
-    _sortPatchesCausally(patches: Array<{ patch: any; sha: string }>): Array<{ patch: any; sha: string }>;
+    _sortPatchesCausally(patches: Array<{ patch: PatchV2; sha: string }>): Array<{ patch: PatchV2; sha: string }>;
 
     // ── fork.methods.js ───────────────────────────────────────────────────
     fork(options: { from: string; at: string; forkName?: string; forkWriterId?: string }): Promise<WarpGraph>;
@@ -251,7 +249,7 @@ declare module '../WarpGraph.js' {
     _buildView(state: WarpStateV5, stateHash: string, diff?: import('../types/PatchDiff.js').PatchDiff): void;
     _setMaterializedState(state: WarpStateV5, optionsOrDiff?: import('../types/PatchDiff.js').PatchDiff | { diff?: import('../types/PatchDiff.js').PatchDiff | null }): Promise<{ state: WarpStateV5; stateHash: string; adjacency: unknown }>;
     _materializeWithCeiling(ceiling: number, collectReceipts: boolean, t0: number): Promise<WarpStateV5 | { state: WarpStateV5; receipts: TickReceipt[] }>;
-    _persistSeekCacheEntry(cacheKey: string, buf: Buffer, state: WarpStateV5): Promise<void>;
+    _persistSeekCacheEntry(cacheKey: string, buf: Uint8Array, state: WarpStateV5): Promise<void>;
     _restoreIndexFromCache(indexTreeOid: string): Promise<void>;
     materializeAt(checkpointSha: string): Promise<WarpStateV5>;
     verifyIndex(options?: { seed?: number; sampleRate?: number }): { passed: number; failed: number; errors: Array<{ nodeId: string; direction: string; expected: string[]; actual: string[] }> };

package/src/domain/warp/checkpoint.methods.js

@@ -375,7 +375,7 @@ export function _maybeRunGC(state) {
  * **Requires a cached state.**
  *
  * @this {import('../WarpGraph.js').default}
- * @returns {{ran: boolean, result: Object|null, reasons: string[]}} GC result
+ * @returns {{ran: boolean, result: import('../services/GCPolicy.js').GCExecuteResult|null, reasons: string[]}} GC result
  *
  * @example
  * await graph.materialize();

package/src/domain/warp/fork.methods.js

@@ -31,11 +31,7 @@ import { createWormhole as createWormholeImpl } from '../services/WormholeServic
  * - History up to the fork point is shared (content-addressed dedup)
  *
  * @this {import('../WarpGraph.js').default}
- * @param {Object} options - Fork configuration
- * @param {string} options.from - Writer ID whose chain to fork from
- * @param {string} options.at - Patch SHA to fork at (must be in the writer's chain)
- * @param {string} [options.forkName] - Name for the forked graph. Defaults to `<graphName>-fork-<timestamp>`
- * @param {string} [options.forkWriterId] - Writer ID for the fork. Defaults to a new canonical ID.
+ * @param {{ from: string, at: string, forkName?: string, forkWriterId?: string }} options - Fork configuration
  * @returns {Promise<import('../WarpGraph.js').default>} A new WarpGraph instance for the fork
  * @throws {ForkError} If `from` writer does not exist (code: `E_FORK_WRITER_NOT_FOUND`)
  * @throws {ForkError} If `at` SHA does not exist (code: `E_FORK_PATCH_NOT_FOUND`)

package/src/domain/warp/materializeAdvanced.methods.js

@@ -351,7 +351,7 @@ export async function _materializeWithCeiling(ceiling, collectReceipts, t0) {
       cacheKey = buildSeekCacheKey(ceiling, frontier);
     }
     const buf = serializeFullStateV5(state, { codec: this._codec });
-    this._persistSeekCacheEntry(cacheKey, /** @type {Buffer} */ (buf), state)
+    this._persistSeekCacheEntry(cacheKey, buf, state)
       .catch(() => {});
   }
 
@@ -377,7 +377,7 @@ export async function _materializeWithCeiling(ceiling, collectReceipts, t0) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string} cacheKey - Seek cache key
- * @param {Buffer} buf - Serialized WarpStateV5 buffer
+ * @param {Uint8Array} buf - Serialized WarpStateV5 buffer
  * @param {import('../services/JoinReducer.js').WarpStateV5} state
  * @returns {Promise<void>}
  * @private
@@ -473,7 +473,7 @@ export async function materializeAt(checkpointSha) {
 
       const patchMeta = decodePatchMessage(message);
       const patchBuffer = await this._persistence.readBlob(patchMeta.patchOid);
-      const patch = this._codec.decode(patchBuffer);
+      const patch = /** @type {import('../types/WarpTypesV2.js').PatchV2} */ (this._codec.decode(patchBuffer));
 
       patches.push({ patch, sha: currentSha });
 

package/src/domain/warp/patch.methods.js

@@ -287,9 +287,9 @@ export async function writer(writerId) {
     graphName: this._graphName,
     writerId: resolvedWriterId,
     versionVector: this._versionVector,
-    getCurrentState: /** @type {() => Promise<import('../services/JoinReducer.js').WarpStateV5>} */ (/** @type {unknown} */ (() => this._cachedState)),
+    getCurrentState: () => this._cachedState,
     onDeleteWithData: this._onDeleteWithData,
-    onCommitSuccess: /** @type {(result: {patch: Object, sha: string}) => void} */ (/** @type {unknown} */ ((/** @type {{patch?: import('../types/WarpTypesV2.js').PatchV2, sha?: string}} */ opts) => this._onPatchCommitted(resolvedWriterId, opts))),
+    onCommitSuccess: /** @type {(result: {patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}) => void} */ ((/** @type {{patch?: import('../types/WarpTypesV2.js').PatchV2, sha?: string}} */ opts) => this._onPatchCommitted(resolvedWriterId, opts)),
     codec: this._codec,
     logger: this._logger || undefined,
   });
@@ -304,9 +304,7 @@ export async function writer(writerId) {
  *
  * @deprecated Use `writer()` to resolve a stable ID from git config, or `writer(id)` with an explicit ID.
  * @this {import('../WarpGraph.js').default}
- * @param {Object} [opts]
- * @param {'config'|'none'} [opts.persist='none'] - Whether to persist the new ID to git config
- * @param {string} [opts.alias] - Optional alias for config key (used with persist:'config')
+ * @param {{ persist?: 'config'|'none', alias?: string }} [opts]
  * @returns {Promise<Writer>} A Writer instance with new canonical ID
  * @throws {Error} If config operations fail (when persist:'config')
  *
@@ -346,9 +344,9 @@ export async function createWriter(opts = {}) {
     graphName: this._graphName,
     writerId: freshWriterId,
     versionVector: this._versionVector,
-    getCurrentState: /** @type {() => Promise<import('../services/JoinReducer.js').WarpStateV5>} */ (/** @type {unknown} */ (() => this._cachedState)),
+    getCurrentState: () => this._cachedState,
     onDeleteWithData: this._onDeleteWithData,
-    onCommitSuccess: /** @type {(result: {patch: Object, sha: string}) => void} */ (/** @type {unknown} */ ((/** @type {{patch?: import('../types/WarpTypesV2.js').PatchV2, sha?: string}} */ commitOpts) => this._onPatchCommitted(freshWriterId, commitOpts))),
+    onCommitSuccess: /** @type {(result: {patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}) => void} */ ((/** @type {{patch?: import('../types/WarpTypesV2.js').PatchV2, sha?: string}} */ commitOpts) => this._onPatchCommitted(freshWriterId, commitOpts)),
     codec: this._codec,
     logger: this._logger || undefined,
   });
@@ -484,7 +482,7 @@ export async function discoverTicks() {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {import('../services/JoinReducer.js').WarpStateV5} otherState - The state to merge in
- * @returns {{state: import('../services/JoinReducer.js').WarpStateV5, receipt: Object}} Merged state and receipt
+ * @returns {{state: import('../services/JoinReducer.js').WarpStateV5, receipt: {nodesAdded: number, nodesRemoved: number, edgesAdded: number, edgesRemoved: number, propsChanged: number, frontierMerged: boolean}}} Merged state and receipt
  * @throws {QueryError} If no cached state exists (code: `E_NO_STATE`)
  * @throws {Error} If otherState is invalid
  */

package/src/domain/warp/provenance.methods.js

@@ -152,7 +152,7 @@ export async function materializeSlice(nodeId, options) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string} nodeId - The target node ID
- * @returns {Promise<Map<string, Object>>} Map of patch SHA to loaded patch object
+ * @returns {Promise<Map<string, import('../types/WarpTypesV2.js').PatchV2>>} Map of patch SHA to loaded patch object
  */
 export async function _computeBackwardCone(nodeId) {
   if (!this._provenanceIndex) {
@@ -209,7 +209,7 @@ export async function _computeBackwardCone(nodeId) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string} sha - The patch commit SHA
- * @returns {Promise<Object>} The decoded patch object
+ * @returns {Promise<import('../types/WarpTypesV2.js').PatchV2>} The decoded patch object
  * @throws {Error} If the commit is not a patch or loading fails
  */
 export async function loadPatchBySha(sha) {
@@ -221,7 +221,7 @@ export async function loadPatchBySha(sha) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string} sha - The patch commit SHA
- * @returns {Promise<Object>} The decoded patch object
+ * @returns {Promise<import('../types/WarpTypesV2.js').PatchV2>} The decoded patch object
  * @throws {Error} If the commit is not a patch or loading fails
  */
 export async function _loadPatchBySha(sha) {
@@ -234,7 +234,7 @@ export async function _loadPatchBySha(sha) {
 
   const patchMeta = decodePatchMessage(nodeInfo.message);
   const patchBuffer = await this._persistence.readBlob(patchMeta.patchOid);
-  return /** @type {Object} */ (this._codec.decode(patchBuffer));
+  return /** @type {import('../types/WarpTypesV2.js').PatchV2} */ (this._codec.decode(patchBuffer));
 }
 
 /**
@@ -242,7 +242,7 @@ export async function _loadPatchBySha(sha) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string[]} shas - Array of patch commit SHAs
- * @returns {Promise<Array<{patch: Object, sha: string}>>} Array of patch entries
+ * @returns {Promise<Array<{patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}>>} Array of patch entries
  * @throws {Error} If any SHA is not a patch or loading fails
  */
 export async function _loadPatchesBySha(shas) {