@git-stunts/git-warp 11.2.1 → 11.5.0

package/src/domain/services/JoinReducer.js

@@ -29,7 +29,7 @@ export {
  * @typedef {Object} WarpStateV5
  * @property {import('../crdt/ORSet.js').ORSet} nodeAlive - ORSet of alive nodes
  * @property {import('../crdt/ORSet.js').ORSet} edgeAlive - ORSet of alive edges
- * @property {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} prop - Properties with LWW
+ * @property {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} prop - Properties with LWW
  * @property {import('../crdt/VersionVector.js').VersionVector} observedFrontier - Observed version vector
  * @property {Map<string, import('../utils/EventId.js').EventId>} edgeBirthEvent - EdgeKey → EventId of most recent EdgeAdd (for clean-slate prop visibility)
  */
@@ -81,7 +81,7 @@ export function createEmptyStateV5() {
  * @param {string} [op.to] - Target node ID (for EdgeAdd, EdgeRemove)
  * @param {string} [op.label] - Edge label (for EdgeAdd, EdgeRemove)
  * @param {string} [op.key] - Property key (for PropSet)
- * @param {*} [op.value] - Property value (for PropSet)
+ * @param {unknown} [op.value] - Property value (for PropSet)
  * @param {import('../utils/EventId.js').EventId} eventId - Event ID for causality tracking
  * @returns {void}
  */
@@ -114,7 +114,7 @@ export function applyOpV2(state, op, eventId) {
       // Uses EventId-based LWW, same as v4
       const key = encodePropKey(/** @type {string} */ (op.node), /** @type {string} */ (op.key));
       const current = state.prop.get(key);
-      state.prop.set(key, /** @type {import('../crdt/LWW.js').LWWRegister<*>} */ (lwwMax(current, lwwSet(eventId, op.value))));
+      state.prop.set(key, /** @type {import('../crdt/LWW.js').LWWRegister<unknown>} */ (lwwMax(current, lwwSet(eventId, op.value))));
       break;
     }
     default:
@@ -290,11 +290,11 @@ function edgeRemoveOutcome(orset, op) {
  * - `superseded`: An existing value with higher EventId wins
  * - `redundant`: Exact same write (identical EventId)
  *
- * @param {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} propMap - The properties map keyed by encoded prop keys
+ * @param {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} propMap - The properties map keyed by encoded prop keys
  * @param {Object} op - The PropSet operation
  * @param {string} op.node - Node ID owning the property
  * @param {string} op.key - Property key/name
- * @param {*} op.value - Property value to set
+ * @param {unknown} op.value - Property value to set
  * @param {import('../utils/EventId.js').EventId} eventId - The event ID for this operation, used for LWW comparison
  * @returns {{target: string, result: 'applied'|'superseded'|'redundant', reason?: string}}
  *          Outcome with encoded prop key as target; includes reason when superseded
@@ -328,6 +328,19 @@ function propSetOutcome(propMap, op, eventId) {
   return { target, result: 'redundant' };
 }
 
+/**
+ * Folds a patch's own dot into the observed frontier.
+ * @param {Map<string, number>} frontier
+ * @param {string} writer
+ * @param {number} lamport
+ */
+function foldPatchDot(frontier, writer, lamport) {
+  const current = frontier.get(writer) || 0;
+  if (lamport > current) {
+    frontier.set(writer, lamport);
+  }
+}
+
 /**
  * Joins a patch into state, applying all operations in order.
  *
@@ -347,7 +360,7 @@ function propSetOutcome(propMap, op, eventId) {
  * @param {Object} patch - The patch to apply
  * @param {string} patch.writer - Writer ID who created this patch
  * @param {number} patch.lamport - Lamport timestamp of this patch
- * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: *, oid?: string}>} patch.ops - Array of operations to apply
+ * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>} patch.ops - Array of operations to apply
  * @param {Map<string, number>|{[x: string]: number}} patch.context - Version vector context (Map or serialized form)
  * @param {string} patchSha - The Git SHA of the patch commit (used for EventId creation)
  * @param {boolean} [collectReceipts=false] - When true, computes and returns receipt data
@@ -366,6 +379,7 @@ export function join(state, patch, patchSha, collectReceipts) {
       ? patch.context
       : vvDeserialize(patch.context);
     state.observedFrontier = vvMerge(state.observedFrontier, contextVV);
+    foldPatchDot(state.observedFrontier, patch.writer, patch.lamport);
     return state;
   }
 
@@ -423,6 +437,7 @@ export function join(state, patch, patchSha, collectReceipts) {
     ? patch.context
     : vvDeserialize(patch.context);
   state.observedFrontier = vvMerge(state.observedFrontier, contextVV);
+  foldPatchDot(state.observedFrontier, patch.writer, patch.lamport);
 
   const receipt = createTickReceipt({
     patchSha,
@@ -470,16 +485,16 @@ export function joinStates(a, b) {
  *
  * This is a pure function that does not mutate its inputs.
  *
- * @param {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} a - First property map
- * @param {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} b - Second property map
- * @returns {Map<string, import('../crdt/LWW.js').LWWRegister<*>>} New map containing merged properties
+ * @param {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} a - First property map
+ * @param {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} b - Second property map
+ * @returns {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} New map containing merged properties
  */
 function mergeProps(a, b) {
   const result = new Map(a);
 
   for (const [key, regB] of b) {
     const regA = result.get(key);
-    result.set(key, /** @type {import('../crdt/LWW.js').LWWRegister<*>} */ (lwwMax(regA, regB)));
+    result.set(key, /** @type {import('../crdt/LWW.js').LWWRegister<unknown>} */ (lwwMax(regA, regB)));
   }
 
   return result;
@@ -530,7 +545,7 @@ function mergeEdgeBirthEvent(a, b) {
  * - When `options.receipts` is true, returns a TickReceipt per patch for
  *   provenance tracking and debugging.
  *
- * @param {Array<{patch: {writer: string, lamport: number, ops: Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: *, oid?: string}>, context: Map<string, number>|{[x: string]: number}}, sha: string}>} patches - Array of patch objects with their Git SHAs
+ * @param {Array<{patch: {writer: string, lamport: number, ops: Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>, context: Map<string, number>|{[x: string]: number}}, sha: string}>} patches - Array of patch objects with their Git SHAs
  * @param {WarpStateV5} [initialState] - Optional starting state (for incremental materialization from checkpoint)
  * @param {Object} [options] - Optional configuration
  * @param {boolean} [options.receipts=false] - When true, collect and return TickReceipts

package/src/domain/services/KeyCodec.js

@@ -18,6 +18,13 @@ export const FIELD_SEPARATOR = '\0';
  */
 export const EDGE_PROP_PREFIX = '\x01';
 
+/**
+ * Well-known property key for content attachment.
+ * Stores a content-addressed blob OID as the property value.
+ * @const {string}
+ */
+export const CONTENT_PROPERTY_KEY = '_content';
+
 /**
  * Encodes an edge key to a string for Map storage.
  *

package/src/domain/services/LogicalTraversal.js

@@ -152,7 +152,7 @@ export default class LogicalTraversal {
    * @throws {TraversalError} If the labelFilter is invalid (INVALID_LABEL_FILTER)
    */
   async _prepare(start, { dir, labelFilter, maxDepth }) {
-    const materialized = await /** @type {any} */ (this._graph)._materializeGraph(); // TODO(ts-cleanup): narrow port type
+    const materialized = await /** @type {{ _materializeGraph: () => Promise<{adjacency: {outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>>}}> }} */ (this._graph)._materializeGraph();
 
     if (!(await this._graph.hasNode(start))) {
       throw new TraversalError(`Start node not found: ${start}`, {

package/src/domain/services/MessageCodecInternal.js

@@ -66,7 +66,7 @@ const SHA256_PATTERN = /^[0-9a-f]{64}$/;
 // -----------------------------------------------------------------------------
 
 // Lazy singleton codec instance
-/** @type {*} */ // TODO(ts-cleanup): type lazy singleton
+/** @type {TrailerCodec|null} */
 let _codec = null;
 
 /**

package/src/domain/services/MigrationService.js

@@ -16,7 +16,7 @@ import { createVersionVector, vvIncrement } from '../crdt/VersionVector.js';
  * @param {Object} v4State - The V4 materialized state (visible projection)
  * @param {Map<string, {value: boolean}>} v4State.nodeAlive - V4 node alive map
  * @param {Map<string, {value: boolean}>} v4State.edgeAlive - V4 edge alive map
- * @param {Map<string, *>} v4State.prop - V4 property map
+ * @param {Map<string, import('../crdt/LWW.js').LWWRegister<unknown>>} v4State.prop - V4 property map
  * @param {string} migrationWriterId - Writer ID to use for synthetic dots
  * @returns {import('./JoinReducer.js').WarpStateV5} The migrated V5 state
  */

package/src/domain/services/ObserverView.js

@@ -43,10 +43,10 @@ function matchGlob(pattern, str) {
  * - If `expose` is provided and non-empty, only keys in `expose` are included.
  * - If `expose` is absent/empty, all non-redacted keys are included.
  *
- * @param {Map<string, *>} propsMap - The full properties Map
+ * @param {Map<string, unknown>} propsMap - The full properties Map
  * @param {string[]|undefined} expose - Whitelist of property keys to include
  * @param {string[]|undefined} redact - Blacklist of property keys to exclude
- * @returns {Map<string, *>} Filtered properties Map
+ * @returns {Map<string, unknown>} Filtered properties Map
  */
 function filterProps(propsMap, expose, redact) {
   const redactSet = redact && redact.length > 0 ? new Set(redact) : null;
@@ -102,7 +102,7 @@ export default class ObserverView {
     this._graph = graph;
 
     /** @type {LogicalTraversal} */
-    this.traverse = new LogicalTraversal(/** @type {*} */ (this)); // TODO(ts-cleanup): type observer cast
+    this.traverse = new LogicalTraversal(/** @type {import('../WarpGraph.js').default} */ (/** @type {unknown} */ (this)));
   }
 
   /**
@@ -124,11 +124,11 @@ export default class ObserverView {
    * Builds a filtered adjacency structure that only includes edges
    * where both endpoints pass the match filter.
    *
-   * @returns {Promise<{state: *, stateHash: string, adjacency: {outgoing: Map<string, *[]>, incoming: Map<string, *[]>}}>}
+   * @returns {Promise<{state: unknown, stateHash: string, adjacency: {outgoing: Map<string, unknown[]>, incoming: Map<string, unknown[]>}}>}
    * @private
    */
   async _materializeGraph() {
-    const materialized = await /** @type {*} */ (this._graph)._materializeGraph(); // TODO(ts-cleanup): narrow port type
+    const materialized = await /** @type {{ _materializeGraph: () => Promise<{state: import('./JoinReducer.js').WarpStateV5, stateHash: string, adjacency: {outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>>}}> }} */ (this._graph)._materializeGraph();
     const { state, stateHash } = materialized;
 
     // Build filtered adjacency: only edges where both endpoints match
@@ -212,7 +212,7 @@ export default class ObserverView {
    * the observer pattern.
    *
    * @param {string} nodeId - The node ID to get properties for
-   * @returns {Promise<Map<string, *>|null>} Filtered properties Map, or null
+   * @returns {Promise<Map<string, unknown>|null>} Filtered properties Map, or null
    */
   async getNodeProps(nodeId) {
     if (!matchGlob(this._matchPattern, nodeId)) {
@@ -234,7 +234,7 @@ export default class ObserverView {
    *
    * An edge is visible only when both endpoints match the observer pattern.
    *
-   * @returns {Promise<Array<{from: string, to: string, label: string, props: Record<string, *>}>>}
+   * @returns {Promise<Array<{from: string, to: string, label: string, props: Record<string, unknown>}>>}
    */
   async getEdges() {
     const allEdges = await this._graph.getEdges();
@@ -260,6 +260,6 @@ export default class ObserverView {
    * @returns {QueryBuilder} A query builder scoped to this observer
    */
   query() {
-    return new QueryBuilder(/** @type {*} */ (this)); // TODO(ts-cleanup): type observer cast
+    return new QueryBuilder(/** @type {import('../WarpGraph.js').default} */ (/** @type {unknown} */ (this)));
   }
 }

package/src/domain/services/PatchBuilderV2.js

@@ -23,8 +23,8 @@ import {
   createPropSetV2,
   createPatchV2,
 } from '../types/WarpTypesV2.js';
-import { encodeEdgeKey, EDGE_PROP_PREFIX } from './KeyCodec.js';
-import { encodePatchMessage, decodePatchMessage } from './WarpMessageCodec.js';
+import { encodeEdgeKey, EDGE_PROP_PREFIX, CONTENT_PROPERTY_KEY } from './KeyCodec.js';
+import { encodePatchMessage, decodePatchMessage, detectMessageKind } from './WarpMessageCodec.js';
 import { buildWriterRef } from '../utils/RefLayout.js';
 import WriterError from '../errors/WriterError.js';
 
@@ -86,7 +86,7 @@ export class PatchBuilderV2 {
    */
   constructor({ persistence, graphName, writerId, lamport, versionVector, getCurrentState, expectedParentSha = null, onCommitSuccess = null, onDeleteWithData = 'warn', codec, logger }) {
     /** @type {import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default} */
-    this._persistence = /** @type {*} */ (persistence); // TODO(ts-cleanup): narrow port type
+    this._persistence = /** @type {import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default} */ (persistence);
 
     /** @type {string} */
     this._graphName = graphName;
@@ -124,6 +124,13 @@ export class PatchBuilderV2 {
     /** @type {{ warn: Function }} */
     this._logger = logger || nullLogger;
 
+    /**
+     * Content blob OIDs written during this patch via attachContent/attachEdgeContent.
+     * These are embedded in the commit tree for GC protection.
+     * @type {string[]}
+     */
+    this._contentBlobs = [];
+
     /**
      * Nodes/edges read by this patch (for provenance tracking).
      *
@@ -346,7 +353,7 @@ export class PatchBuilderV2 {
    *
    * @param {string} nodeId - The node ID to set the property on
    * @param {string} key - Property key (should not contain null bytes)
-   * @param {*} value - Property value. Must be JSON-serializable (strings,
+   * @param {unknown} value - Property value. Must be JSON-serializable (strings,
    *   numbers, booleans, arrays, plain objects, or null). Use `null` to
    *   effectively delete a property (LWW semantics).
    * @returns {PatchBuilderV2} This builder instance for method chaining
@@ -389,7 +396,7 @@ export class PatchBuilderV2 {
    * @param {string} to - Target node ID (edge destination)
    * @param {string} label - Edge label/type identifying which edge to modify
    * @param {string} key - Property key (should not contain null bytes)
-   * @param {*} value - Property value. Must be JSON-serializable (strings,
+   * @param {unknown} value - Property value. Must be JSON-serializable (strings,
    *   numbers, booleans, arrays, plain objects, or null). Use `null` to
    *   effectively delete a property (LWW semantics).
    * @returns {PatchBuilderV2} This builder instance for method chaining
@@ -430,6 +437,45 @@ export class PatchBuilderV2 {
     return this;
   }
 
+  /**
+   * Attaches content to a node by writing the blob to the Git object store
+   * and storing the blob OID as the `_content` property.
+   *
+   * The blob OID is also tracked for embedding in the commit tree, which
+   * ensures content blobs survive `git gc` (GC protection via reachability).
+   *
+   * Note: The node must exist in the materialized state (or be added in
+   * this patch) for `getContent()` to find it later. `attachContent()`
+   * only sets the `_content` property — it does not create the node.
+   *
+   * @param {string} nodeId - The node ID to attach content to
+   * @param {Buffer|string} content - The content to attach
+   * @returns {Promise<PatchBuilderV2>} This builder instance for method chaining
+   */
+  async attachContent(nodeId, content) {
+    const oid = await this._persistence.writeBlob(content);
+    this.setProperty(nodeId, CONTENT_PROPERTY_KEY, oid);
+    this._contentBlobs.push(oid);
+    return this;
+  }
+
+  /**
+   * Attaches content to an edge by writing the blob to the Git object store
+   * and storing the blob OID as the `_content` edge property.
+   *
+   * @param {string} from - Source node ID
+   * @param {string} to - Target node ID
+   * @param {string} label - Edge label
+   * @param {Buffer|string} content - The content to attach
+   * @returns {Promise<PatchBuilderV2>} This builder instance for method chaining
+   */
+  async attachEdgeContent(from, to, label, content) {
+    const oid = await this._persistence.writeBlob(content);
+    this.setEdgeProperty(from, to, label, CONTENT_PROPERTY_KEY, oid);
+    this._contentBlobs.push(oid);
+    return this;
+  }
+
   /**
    * Builds the PatchV2 object without committing.
    *
@@ -454,7 +500,7 @@ export class PatchBuilderV2 {
       schema,
       writer: this._writerId,
       lamport: this._lamport,
-      context: /** @type {*} */ (this._vv), // TODO(ts-cleanup): narrow port type
+      context: vvSerialize(this._vv),
       ops: this._ops,
       reads: [...this._reads].sort(),
       writes: [...this._writes].sort(),
@@ -468,11 +514,12 @@ export class PatchBuilderV2 {
    * 1. Validates the patch is non-empty
    * 2. Checks for concurrent modifications (compare-and-swap on writer ref)
    * 3. Calculates the next lamport timestamp from the parent commit
-   * 4. Encodes the patch as CBOR and writes it as a Git blob
-   * 5. Creates a Git tree containing the patch blob
-   * 6. Creates a commit with proper trailers linking to the parent
-   * 7. Updates the writer ref to point to the new commit
-   * 8. Invokes the success callback if provided (for eager re-materialization)
+   * 4. Builds the PatchV2 structure with the resolved lamport
+   * 5. Encodes the patch as CBOR and writes it as a Git blob
+   * 6. Creates a Git tree containing the patch blob
+   * 7. Creates a commit with proper trailers linking to the parent
+   * 8. Updates the writer ref to point to the new commit
+   * 9. Invokes the success callback if provided (for eager re-materialization)
    *
    * The commit is written to the writer's patch chain at:
    * `refs/warp/<graphName>/writers/<writerId>`
@@ -524,19 +571,39 @@ export class PatchBuilderV2 {
       throw err;
     }
 
-    // 3. Calculate lamport and parent from current ref state
-    let lamport = 1;
+    // 3. Calculate lamport and parent from current ref state.
+    // Start from this._lamport (set by _nextLamport() in createPatch()), which already
+    // incorporates the globally-observed max Lamport tick via _maxObservedLamport.
+    // This ensures a first-time writer whose own chain is empty still commits at a tick
+    // above any previously-observed writer, winning LWW tiebreakers correctly.
+    let lamport = this._lamport;
     let parentCommit = null;
 
     if (currentRefSha) {
-      // Read the current patch commit to get its lamport timestamp
-      const commitMessage = await this._persistence.showNode(currentRefSha);
-      const patchInfo = decodePatchMessage(commitMessage);
-      lamport = patchInfo.lamport + 1;
       parentCommit = currentRefSha;
+      // Read the current patch commit to get its lamport timestamp and take the max,
+      // so the chain stays monotonic even if the ref advanced since createPatch().
+      const commitMessage = await this._persistence.showNode(currentRefSha);
+      const kind = detectMessageKind(commitMessage);
+
+      if (kind === 'patch') {
+        let patchInfo;
+        try {
+          patchInfo = decodePatchMessage(commitMessage);
+        } catch (err) {
+          throw new Error(
+            `Failed to parse lamport from writer ref ${writerRef}: ` +
+            `commit ${currentRefSha} has invalid patch message format`,
+            { cause: err }
+          );
+        }
+        lamport = Math.max(this._lamport, patchInfo.lamport + 1);
+      }
+      // Non-patch ref (checkpoint, etc.): keep lamport from this._lamport
+      // (already incorporates _maxObservedLamport), matching _nextLamport() behavior.
     }
 
-    // 3. Build PatchV2 structure with correct lamport
+    // 4. Build PatchV2 structure with correct lamport
     // Note: Dots were assigned using constructor lamport, but commit lamport may differ.
     // For now, we use the calculated lamport for the patch metadata.
     // The dots themselves are independent of patch lamport (they use VV counters).
@@ -552,18 +619,20 @@ export class PatchBuilderV2 {
       writes: [...this._writes].sort(),
     });
 
-    // 4. Encode patch as CBOR
+    // 5. Encode patch as CBOR and write as a Git blob
     const patchCbor = this._codec.encode(patch);
-
-    // 5. Write patch.cbor blob
     const patchBlobOid = await this._persistence.writeBlob(/** @type {Buffer} */ (patchCbor));
 
-    // 6. Create tree with the blob
+    // 6. Create tree with the patch blob + any content blobs (deduplicated)
     // Format for mktree: "mode type oid\tpath"
-    const treeEntry = `100644 blob ${patchBlobOid}\tpatch.cbor`;
-    const treeOid = await this._persistence.writeTree([treeEntry]);
+    const treeEntries = [`100644 blob ${patchBlobOid}\tpatch.cbor`];
+    const uniqueBlobs = [...new Set(this._contentBlobs)];
+    for (const blobOid of uniqueBlobs) {
+      treeEntries.push(`100644 blob ${blobOid}\t_content_${blobOid}`);
+    }
+    const treeOid = await this._persistence.writeTree(treeEntries);
 
-    // 7. Create patch commit message with trailers (schema:2)
+    // 7. Create commit with proper trailers linking to the parent
     const commitMessage = encodePatchMessage({
       graph: this._graphName,
       writer: this._writerId,
@@ -571,8 +640,6 @@ export class PatchBuilderV2 {
       patchOid: patchBlobOid,
       schema,
     });
-
-    // 8. Create commit with tree, linking to previous patch as parent if exists
     const parents = parentCommit ? [parentCommit] : [];
     const newCommitSha = await this._persistence.commitNodeWithTree({
       treeOid,
@@ -580,10 +647,10 @@ export class PatchBuilderV2 {
       message: commitMessage,
     });
 
-    // 9. Update writer ref to point to new commit
+    // 8. Update writer ref to point to new commit
     await this._persistence.updateRef(writerRef, newCommitSha);
 
-    // 10. Notify success callback (updates graph's version vector + eager re-materialize)
+    // 9. Notify success callback (updates graph's version vector + eager re-materialize)
     if (this._onCommitSuccess) {
       try {
         await this._onCommitSuccess({ patch, sha: newCommitSha });
@@ -593,7 +660,6 @@ export class PatchBuilderV2 {
       }
     }
 
-    // 11. Return the new commit SHA
     return newCommitSha;
   }
 

package/src/domain/services/ProvenanceIndex.js

@@ -277,7 +277,7 @@ class ProvenanceIndex {
   static deserialize(buffer, { codec } = {}) {
     const c = codec || defaultCodec;
     /** @type {{ version?: number, entries?: Array<[string, string[]]> }} */
-    const obj = /** @type {any} */ (c.decode(buffer)); // TODO(ts-cleanup): narrow port type
+    const obj = /** @type {{ version?: number, entries?: Array<[string, string[]]> }} */ (c.decode(buffer));
 
     if (obj.version !== 1) {
       throw new Error(`Unsupported ProvenanceIndex version: ${obj.version}`);

package/src/domain/services/ProvenancePayload.js

@@ -172,7 +172,7 @@ class ProvenancePayload {
     // Use JoinReducer's reduceV5 for deterministic materialization.
     // Note: reduceV5 returns { state, receipts } when options.receipts is truthy,
     // but returns bare WarpStateV5 when no options passed (as here).
-    return /** @type {import('./JoinReducer.js').WarpStateV5} */ (reduceV5(/** @type {*} */ (this.#patches), initialState)); // TODO(ts-cleanup): type patch array
+    return /** @type {import('./JoinReducer.js').WarpStateV5} */ (reduceV5(/** @type {Parameters<typeof reduceV5>[0]} */ ([...this.#patches]), initialState));
   }
 
   /**

package/src/domain/services/QueryBuilder.js

@@ -675,7 +675,7 @@ export default class QueryBuilder {
    * @throws {QueryError} If an unknown select field is specified (code: E_QUERY_SELECT_FIELD)
    */
   async run() {
-    const materialized = await /** @type {any} */ (this._graph)._materializeGraph(); // TODO(ts-cleanup): narrow port type
+    const materialized = await /** @type {{ _materializeGraph: () => Promise<{adjacency: AdjacencyMaps, stateHash: string}> }} */ (this._graph)._materializeGraph();
     const { adjacency, stateHash } = materialized;
     const allNodes = sortIds(await this._graph.getNodes());
 
@@ -805,11 +805,11 @@ export default class QueryBuilder {
       for (const nodeId of workingSet) {
         const propsMap = (await this._graph.getNodeProps(nodeId)) || new Map();
         for (const { segments, values } of propsByAgg.values()) {
-          /** @type {*} */ // TODO(ts-cleanup): type deep property traversal
+          /** @type {unknown} */
           let value = propsMap.get(segments[0]);
           for (let i = 1; i < segments.length; i++) {
             if (value && typeof value === 'object') {
-              value = value[segments[i]];
+              value = /** @type {Record<string, unknown>} */ (value)[segments[i]];
             } else {
               value = undefined;
               break;

package/src/domain/services/StateDiff.js

@@ -24,8 +24,8 @@ import { decodeEdgeKey, decodePropKey, isEdgePropKey } from './KeyCodec.js';
  * @property {string} key - Encoded property key
  * @property {string} nodeId - Node ID (for node props)
  * @property {string} propKey - Property name
- * @property {*} oldValue - Previous value (undefined if new)
- * @property {*} newValue - New value
+ * @property {unknown} oldValue - Previous value (undefined if new)
+ * @property {unknown} newValue - New value
  */
 
 /**
@@ -33,7 +33,7 @@ import { decodeEdgeKey, decodePropKey, isEdgePropKey } from './KeyCodec.js';
  * @property {string} key - Encoded property key
  * @property {string} nodeId - Node ID (for node props)
  * @property {string} propKey - Property name
- * @property {*} oldValue - Previous value
+ * @property {unknown} oldValue - Previous value
  */
 
 /**
@@ -86,8 +86,8 @@ function compareProps(a, b) {
 
 /**
  * Checks if two arrays are deeply equal.
- * @param {Array<*>} a
- * @param {Array<*>} b
+ * @param {Array<unknown>} a
+ * @param {Array<unknown>} b
  * @returns {boolean}
  */
 function arraysEqual(a, b) {
@@ -104,8 +104,8 @@ function arraysEqual(a, b) {
 
 /**
  * Checks if two objects are deeply equal.
- * @param {Record<string, *>} a
- * @param {Record<string, *>} b
+ * @param {Record<string, unknown>} a
+ * @param {Record<string, unknown>} b
  * @returns {boolean}
  */
 function objectsEqual(a, b) {
@@ -127,8 +127,8 @@ function objectsEqual(a, b) {
 
 /**
  * Checks if two values are deeply equal (for property comparison).
- * @param {*} a
- * @param {*} b
+ * @param {unknown} a
+ * @param {unknown} b
  * @returns {boolean}
  */
 function deepEqual(a, b) {
@@ -148,9 +148,12 @@ function deepEqual(a, b) {
     return false;
   }
   if (Array.isArray(a)) {
-    return arraysEqual(a, b);
+    return arraysEqual(a, /** @type {unknown[]} */ (b));
   }
-  return objectsEqual(a, b);
+  return objectsEqual(
+    /** @type {Record<string, unknown>} */ (a),
+    /** @type {Record<string, unknown>} */ (b),
+  );
 }
 
 /**

package/src/domain/services/StateSerializerV5.js

@@ -139,11 +139,11 @@ export async function computeStateHashV5(state, { crypto, codec } = /** @type {{
  * @param {Buffer} buffer
  * @param {Object} [options]
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
- * @returns {{nodes: string[], edges: Array<{from: string, to: string, label: string}>, props: Array<{node: string, key: string, value: *}>}}
+ * @returns {{nodes: string[], edges: Array<{from: string, to: string, label: string}>, props: Array<{node: string, key: string, value: unknown}>}}
  */
 export function deserializeStateV5(buffer, { codec } = {}) {
   const c = codec || defaultCodec;
-  return /** @type {{nodes: string[], edges: Array<{from: string, to: string, label: string}>, props: Array<{node: string, key: string, value: *}>}} */ (c.decode(buffer));
+  return /** @type {{nodes: string[], edges: Array<{from: string, to: string, label: string}>, props: Array<{node: string, key: string, value: unknown}>}} */ (c.decode(buffer));
 }
 
 // ============================================================================