@git-stunts/git-warp 11.2.1 → 11.3.3

package/src/domain/services/TranslationCost.js

@@ -16,6 +16,8 @@
 import { orsetElements, orsetContains } from '../crdt/ORSet.js';
 import { decodeEdgeKey, decodePropKey, isEdgePropKey } from './KeyCodec.js';
 
+/** @typedef {import('./JoinReducer.js').WarpStateV5} WarpStateV5 */
+
 /**
  * Tests whether a string matches a glob-style pattern.
  *
@@ -38,7 +40,7 @@ function matchGlob(pattern, str) {
 /**
  * Computes the set of property keys visible under an observer config.
  *
- * @param {Map<string, *>} allNodeProps - Map of propKey -> placeholder
+ * @param {Map<string, unknown>} allNodeProps - Map of propKey -> placeholder
  * @param {string[]|undefined} expose - Whitelist of property keys
  * @param {string[]|undefined} redact - Blacklist of property keys
  * @returns {Set<string>} Visible property keys
@@ -63,7 +65,7 @@ function visiblePropKeys(allNodeProps, expose, redact) {
 /**
  * Collects node property keys from state for a given node.
  *
- * @param {*} state - WarpStateV5 materialized state
+ * @param {WarpStateV5} state - WarpStateV5 materialized state
  * @param {string} nodeId - The node ID
  * @returns {Map<string, boolean>} Map of propKey -> true
  */
@@ -111,7 +113,7 @@ function countMissing(source, targetSet) {
 /**
  * Computes edge loss between two observer node sets.
  *
- * @param {*} state - WarpStateV5
+ * @param {WarpStateV5} state
  * @param {Set<string>} nodesASet - Nodes visible to A
  * @param {Set<string>} nodesBSet - Nodes visible to B
  * @returns {number} edgeLoss fraction
@@ -156,7 +158,7 @@ function countNodePropLoss(nodeProps, { configA, configB, nodeInB }) {
 /**
  * Computes property loss across all A-visible nodes.
  *
- * @param {*} state - WarpStateV5
+ * @param {WarpStateV5} state - WarpStateV5
  * @param {{ nodesA: string[], nodesBSet: Set<string>, configA: {expose?: string[], redact?: string[]}, configB: {expose?: string[], redact?: string[]} }} opts
  * @returns {number} propLoss fraction
  */
@@ -193,7 +195,7 @@ function computePropLoss(state, { nodesA, nodesBSet, configA, configB }) {
  * @param {string} configB.match - Glob pattern for visible nodes
  * @param {string[]} [configB.expose] - Property keys to include
  * @param {string[]} [configB.redact] - Property keys to exclude
- * @param {*} state - WarpStateV5 materialized state
+ * @param {WarpStateV5} state - WarpStateV5 materialized state
  * @returns {{ cost: number, breakdown: { nodeLoss: number, edgeLoss: number, propLoss: number } }}
  */
 export function computeTranslationCost(configA, configB, state) {

package/src/domain/services/WormholeService.js

@@ -27,7 +27,7 @@ import { detectMessageKind, decodePatchMessage } from './WarpMessageCodec.js';
 
 /**
  * Validates that a SHA parameter is a non-empty string.
- * @param {*} sha - The SHA to validate
+ * @param {unknown} sha - The SHA to validate
  * @param {string} paramName - Parameter name for error messages
  * @throws {WormholeError} If SHA is invalid
  * @private
@@ -321,7 +321,7 @@ export function deserializeWormhole(json) {
     });
   }
 
-  const /** @type {Record<string, *>} */ typedJson = /** @type {Record<string, *>} */ (json);
+  const /** @type {Record<string, unknown>} */ typedJson = /** @type {Record<string, unknown>} */ (json);
   const requiredFields = ['fromSha', 'toSha', 'writerId', 'patchCount', 'payload'];
   for (const field of requiredFields) {
     if (typedJson[field] === undefined) {
@@ -332,6 +332,15 @@ export function deserializeWormhole(json) {
     }
   }
 
+  for (const field of ['fromSha', 'toSha', 'writerId']) {
+    if (typeof typedJson[field] !== 'string') {
+      throw new WormholeError(`Invalid wormhole JSON: '${field}' must be a string`, {
+        code: 'E_INVALID_WORMHOLE_JSON',
+        context: { [field]: typedJson[field] },
+      });
+    }
+  }
+
   if (typeof typedJson.patchCount !== 'number' || typedJson.patchCount < 0) {
     throw new WormholeError('Invalid wormhole JSON: patchCount must be a non-negative number', {
       code: 'E_INVALID_WORMHOLE_JSON',
@@ -340,11 +349,11 @@ export function deserializeWormhole(json) {
   }
 
   return {
-    fromSha: typedJson.fromSha,
-    toSha: typedJson.toSha,
-    writerId: typedJson.writerId,
-    patchCount: typedJson.patchCount,
-    payload: ProvenancePayload.fromJSON(typedJson.payload),
+    fromSha: /** @type {string} */ (typedJson.fromSha),
+    toSha: /** @type {string} */ (typedJson.toSha),
+    writerId: /** @type {string} */ (typedJson.writerId),
+    patchCount: /** @type {number} */ (typedJson.patchCount),
+    payload: ProvenancePayload.fromJSON(/** @type {import('./ProvenancePayload.js').PatchEntry[]} */ (typedJson.payload)),
   };
 }
 

package/src/domain/trust/TrustCanonical.js

@@ -14,7 +14,7 @@ import { recordIdPayload, signaturePayload } from './canonical.js';
 /**
  * Computes the record ID (SHA-256 hex digest) for a trust record.
  *
- * @param {Record<string, *>} record - Full trust record
+ * @param {Record<string, unknown>} record - Full trust record
  * @returns {string} 64-character lowercase hex string
  */
 export function computeRecordId(record) {
@@ -24,7 +24,7 @@ export function computeRecordId(record) {
 /**
  * Computes the signature payload as a Buffer (UTF-8 bytes).
  *
- * @param {Record<string, *>} record - Full trust record (signature will be stripped)
+ * @param {Record<string, unknown>} record - Full trust record (signature will be stripped)
  * @returns {Buffer} UTF-8 encoded bytes of the domain-separated canonical string
  */
 export function computeSignaturePayload(record) {
@@ -34,7 +34,7 @@ export function computeSignaturePayload(record) {
 /**
  * Verifies that a record's recordId matches its content.
  *
- * @param {Record<string, *>} record - Trust record with `recordId` field
+ * @param {Record<string, unknown>} record - Trust record with `recordId` field
  * @returns {boolean} true if recordId matches computed value
  */
 export function verifyRecordId(record) {

package/src/domain/trust/TrustEvaluator.js

@@ -16,6 +16,21 @@ import { deriveTrustVerdict } from './verdict.js';
  * @typedef {import('./TrustStateBuilder.js').TrustState} TrustState
  */
 
+/**
+ * @typedef {Object} TrustAssessment
+ * @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
+ */
+
 /**
  * Evaluates trust status for a set of writers against the current trust state.
  *
@@ -25,8 +40,8 @@ import { deriveTrustVerdict } from './verdict.js';
  *
  * @param {string[]} writerIds - Writer IDs to evaluate
  * @param {TrustState} trustState - Built trust state from TrustStateBuilder
- * @param {Record<string, *>} policy - Trust policy configuration
- * @returns {Record<string, *>} Frozen TrustAssessment object
+ * @param {Record<string, unknown>} policy - Trust policy configuration
+ * @returns {TrustAssessment} Frozen TrustAssessment object
  */
 export function evaluateWriters(writerIds, trustState, policy) {
   const policyResult = TrustPolicySchema.safeParse(policy);
@@ -130,7 +145,7 @@ function evaluateSingleWriter(writerId, trustState) {
  *
  * @param {string[]} writerIds
  * @param {string} reasonCode
- * @returns {Record<string, *>}
+ * @returns {TrustAssessment}
  */
 function buildErrorAssessment(writerIds, reasonCode) {
   const sortedWriters = [...writerIds].sort();

package/src/domain/trust/TrustRecordService.js

@@ -22,8 +22,8 @@ import TrustError from '../errors/TrustError.js';
 export class TrustRecordService {
   /**
    * @param {Object} options
-   * @param {*} options.persistence - GraphPersistencePort adapter
-   * @param {*} options.codec - CodecPort adapter (CBOR)
+   * @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)
    */
   constructor({ persistence, codec }) {
     this._persistence = persistence;
@@ -46,7 +46,7 @@ export class TrustRecordService {
    * evaluation when the full key set is available.
    *
    * @param {string} graphName
-   * @param {Record<string, *>} record - Complete signed trust record
+   * @param {Record<string, unknown>} record - Complete signed trust record
    * @param {AppendOptions} [options]
    * @returns {Promise<{commitSha: string, ref: string}>}
    */
@@ -95,7 +95,7 @@ export class TrustRecordService {
    * @param {string} graphName
    * @param {Object} [options]
    * @param {string} [options.tip] - Override tip commit (for pinned reads)
-   * @returns {Promise<Array<Record<string, *>>>}
+   * @returns {Promise<Array<Record<string, unknown>>>}
    */
   async readRecords(graphName, options = {}) {
     const ref = buildTrustRecordRef(graphName);
@@ -117,13 +117,16 @@ export class TrustRecordService {
 
     while (current) {
       const info = await this._persistence.getNodeInfo(current);
-      const record = this._codec.decode(
-        await this._persistence.readBlob(
-          (await this._persistence.readTreeOids(
-            await this._persistence.getCommitTree(current),
-          ))['record.cbor'],
-        ),
+      const entries = await this._persistence.readTreeOids(
+        await this._persistence.getCommitTree(current),
       );
+      const blobOid = entries['record.cbor'];
+      if (!blobOid) {
+        break;
+      }
+      const record = /** @type {Record<string, unknown>} */ (this._codec.decode(
+        await this._persistence.readBlob(blobOid),
+      ));
 
       records.unshift(record);
 
@@ -145,7 +148,7 @@ export class TrustRecordService {
    * - Each record passes schema validation
    * - First record has prev=null
    *
-   * @param {Array<Record<string, *>>} records - Records in chain order (oldest first)
+   * @param {Array<Record<string, unknown>>} records - Records in chain order (oldest first)
    * @returns {{valid: boolean, errors: Array<{index: number, error: string}>}}
    */
   verifyChain(records) {
@@ -177,7 +180,7 @@ export class TrustRecordService {
       // Prev-link check
       if (i === 0) {
         if (record.prev !== null) {
-          errors.push({ index: i, error: `Genesis record must have prev=null, got ${record.prev}` });
+          errors.push({ index: i, error: `Genesis record must have prev=null, got ${JSON.stringify(record.prev)}` });
         }
       } else {
         const expectedPrev = records[i - 1].recordId;
@@ -200,12 +203,13 @@ export class TrustRecordService {
    * cryptographic verification — that requires the issuer's public key
    * from the trust state, which is resolved during evaluation.
    *
-   * @param {Record<string, *>} record
+   * @param {Record<string, unknown>} record
    * @throws {TrustError} if signature envelope is missing or malformed
    * @private
    */
   _verifySignatureEnvelope(record) {
-    if (!record.signature || !record.signature.sig || !record.signature.alg) {
+    const sig = /** @type {Record<string, unknown>|undefined} */ (record.signature);
+    if (!sig || !sig.sig || !sig.alg) {
       throw new TrustError(
         'Trust record missing or malformed signature',
         { code: 'E_TRUST_SIGNATURE_MISSING' },
@@ -237,14 +241,14 @@ export class TrustRecordService {
       return { tipSha, recordId: null };
     }
 
-    const record = this._codec.decode(await this._persistence.readBlob(blobOid));
-    return { tipSha, recordId: record.recordId ?? null };
+    const record = /** @type {Record<string, unknown>} */ (this._codec.decode(await this._persistence.readBlob(blobOid)));
+    return { tipSha, recordId: /** @type {string|null} */ (record.recordId) ?? null };
   }
 
   /**
    * Persists a trust record as a Git commit.
    * @param {string} ref
-   * @param {Record<string, *>} record
+   * @param {Record<string, unknown>} record
    * @param {string|null} parentSha - Resolved tip SHA (null for genesis)
    * @returns {Promise<string>} commit SHA
    * @private
@@ -252,16 +256,19 @@ export class TrustRecordService {
   async _persistRecord(ref, record, parentSha) {
     // Encode record as CBOR blob
     const encoded = this._codec.encode(record);
-    const blobOid = await this._persistence.writeBlob(encoded);
+    // Buffer.from() ensures Uint8Array from codec is accepted by writeBlob
+    const blobOid = await this._persistence.writeBlob(Buffer.from(encoded));
 
-    // Create tree with single entry
-    const treeOid = await this._persistence.writeTree({ 'record.cbor': blobOid });
+    // Create tree with single entry (mktree format)
+    const treeOid = await this._persistence.writeTree([`100644 blob ${blobOid}\trecord.cbor`]);
 
     const parents = parentSha ? [parentSha] : [];
-    const message = `trust: ${record.recordType} ${record.recordId.slice(0, 12)}`;
+    const rType = typeof record.recordType === 'string' ? record.recordType : '';
+    const rId = typeof record.recordId === 'string' ? record.recordId.slice(0, 12) : '';
+    const message = `trust: ${rType} ${rId}`;
 
-    const commitSha = await this._persistence.createCommit({
-      tree: treeOid,
+    const commitSha = await this._persistence.commitNodeWithTree({
+      treeOid,
       parents,
       message,
     });

package/src/domain/trust/TrustStateBuilder.js

@@ -12,6 +12,19 @@
 
 import { TrustRecordSchema } from './schemas.js';
 
+/**
+ * @typedef {Object} TrustRecord
+ * @property {string} recordType - Record type (KEY_ADD, KEY_REVOKE, WRITER_BIND_ADD, WRITER_BIND_REVOKE)
+ * @property {string} recordId - Content-addressed record identifier
+ * @property {Record<string, string>} subject - Subject fields (keyId, publicKey, writerId, reasonCode vary by type)
+ * @property {string} issuedAt - ISO timestamp
+ * @property {number} schemaVersion
+ * @property {string} issuerKeyId
+ * @property {string|null} prev
+ * @property {{alg: string, sig: string}} signature
+ * @property {Record<string, unknown>} [meta]
+ */
+
 /**
  * @typedef {Object} TrustState
  * @property {Map<string, {publicKey: string, addedAt: string}>} activeKeys - keyId → key info
@@ -30,7 +43,7 @@ import { TrustRecordSchema } from './schemas.js';
  * - Binding validity: WRITER_BIND_ADD requires the referenced key to be active
  * - Schema validation: each record is validated against TrustRecordSchema
  *
- * @param {Array<Record<string, *>>} records - Trust records in chain order
+ * @param {Array<Record<string, unknown>>} records - Trust records in chain order
  * @returns {TrustState} Frozen trust state
  */
 export function buildState(records) {
@@ -49,13 +62,13 @@ export function buildState(records) {
     const parsed = TrustRecordSchema.safeParse(record);
     if (!parsed.success) {
       errors.push({
-        recordId: record.recordId ?? '(unknown)',
+        recordId: typeof record.recordId === 'string' ? record.recordId : '(unknown)',
         error: `Schema validation failed: ${parsed.error.message}`,
       });
       continue;
     }
 
-    const rec = parsed.data;
+    const rec = /** @type {TrustRecord} */ (parsed.data);
     processRecord(rec, activeKeys, revokedKeys, writerBindings, revokedBindings, errors);
   }
 
@@ -63,7 +76,7 @@ export function buildState(records) {
 }
 
 /**
- * @param {*} rec
+ * @param {TrustRecord} rec
  * @param {Map<string, {publicKey: string, addedAt: string}>} activeKeys
  * @param {Map<string, {publicKey: string, revokedAt: string, reasonCode: string}>} revokedKeys
  * @param {Map<string, {keyId: string, boundAt: string}>} writerBindings
@@ -90,7 +103,7 @@ function processRecord(rec, activeKeys, revokedKeys, writerBindings, revokedBind
 }
 
 /**
- * @param {*} rec
+ * @param {TrustRecord} rec
  * @param {Map<string, {publicKey: string, addedAt: string}>} activeKeys
  * @param {Map<string, {publicKey: string, revokedAt: string, reasonCode: string}>} revokedKeys
  * @param {Array<{recordId: string, error: string}>} errors
@@ -118,7 +131,7 @@ function handleKeyAdd(rec, activeKeys, revokedKeys, errors) {
 }
 
 /**
- * @param {*} rec
+ * @param {TrustRecord} rec
  * @param {Map<string, {publicKey: string, addedAt: string}>} activeKeys
  * @param {Map<string, {publicKey: string, revokedAt: string, reasonCode: string}>} revokedKeys
  * @param {Array<{recordId: string, error: string}>} errors
@@ -152,7 +165,7 @@ function handleKeyRevoke(rec, activeKeys, revokedKeys, errors) {
 }
 
 /**
- * @param {*} rec
+ * @param {TrustRecord} rec
  * @param {Map<string, {publicKey: string, addedAt: string}>} activeKeys
  * @param {Map<string, {publicKey: string, revokedAt: string, reasonCode: string}>} revokedKeys
  * @param {Map<string, {keyId: string, boundAt: string}>} writerBindings
@@ -182,7 +195,7 @@ function handleBindAdd(rec, activeKeys, revokedKeys, writerBindings, errors) {
 }
 
 /**
- * @param {*} rec
+ * @param {TrustRecord} rec
  * @param {Map<string, {keyId: string, boundAt: string}>} writerBindings
  * @param {Map<string, {keyId: string, revokedAt: string, reasonCode: string}>} revokedBindings
  * @param {Array<{recordId: string, error: string}>} errors

package/src/domain/trust/canonical.js

@@ -24,8 +24,8 @@ export const TRUST_SIGN_DOMAIN = 'git-warp:trust-sign:v1\0';
  * Returns the record payload used for recordId computation.
  * Strips `recordId` and `signature` — these are derived, not inputs.
  *
- * @param {Record<string, *>} record
- * @returns {Record<string, *>}
+ * @param {Record<string, unknown>} record
+ * @returns {Record<string, unknown>}
  */
 export function unsignedRecordForId(record) {
   const out = { ...record };
@@ -38,8 +38,8 @@ export function unsignedRecordForId(record) {
  * Returns the record payload used for signature computation.
  * Strips `signature` only — `recordId` is included in signed payload.
  *
- * @param {Record<string, *>} record
- * @returns {Record<string, *>}
+ * @param {Record<string, unknown>} record
+ * @returns {Record<string, unknown>}
  */
 export function unsignedRecordForSignature(record) {
   const out = { ...record };
@@ -50,7 +50,7 @@ export function unsignedRecordForSignature(record) {
 /**
  * Computes the canonical string for recordId hashing.
  *
- * @param {Record<string, *>} record - Full record (recordId and signature will be stripped)
+ * @param {Record<string, unknown>} record - Full record (recordId and signature will be stripped)
  * @returns {string} Domain-separated canonical JSON string
  */
 export function recordIdPayload(record) {
@@ -60,7 +60,7 @@ export function recordIdPayload(record) {
 /**
  * Computes the canonical string for signature verification.
  *
- * @param {Record<string, *>} record - Full record (signature will be stripped)
+ * @param {Record<string, unknown>} record - Full record (signature will be stripped)
  * @returns {string} Domain-separated canonical JSON string
  */
 export function signaturePayload(record) {

package/src/domain/types/TickReceipt.js

@@ -67,7 +67,7 @@ function validateOp(op, index) {
     throw new Error(`ops[${index}] must be an object`);
   }
 
-  const entry = /** @type {Record<string, *>} */ (op);
+  const entry = /** @type {Record<string, unknown>} */ (op);
   validateOpType(entry.op, index);
   validateOpTarget(entry.target, index);
   validateOpResult(entry.result, index);

package/src/domain/types/WarpErrors.js

@@ -0,0 +1,45 @@
+/**
+ * Error narrowing utilities for catch clauses.
+ *
+ * TypeScript catch variables are `unknown`. These helpers provide
+ * type-safe narrowing without wildcard casts.
+ *
+ * @module domain/types/WarpErrors
+ */
+
+/**
+ * Narrows an unknown value to an Error instance.
+ * @param {unknown} err
+ * @returns {err is Error}
+ */
+export function isError(err) {
+  return err instanceof Error;
+}
+
+/**
+ * Checks if an unknown value has a string `code` property.
+ * @param {unknown} err
+ * @returns {err is {code: string, message?: string, name?: string}}
+ */
+export function hasErrorCode(err) {
+  return (
+    typeof err === 'object' &&
+    err !== null &&
+    'code' in err &&
+    typeof (/** @type {Record<string, unknown>} */ (err)).code === 'string'
+  );
+}
+
+/**
+ * Narrows an unknown value to an object with a string `message` property.
+ * @param {unknown} err
+ * @returns {err is {message: string}}
+ */
+export function hasMessage(err) {
+  return (
+    typeof err === 'object' &&
+    err !== null &&
+    'message' in err &&
+    typeof (/** @type {Record<string, unknown>} */ (err)).message === 'string'
+  );
+}

package/src/domain/types/WarpOptions.js

@@ -0,0 +1,29 @@
+/**
+ * Shared options types for warp methods.
+ * @module domain/types/WarpOptions
+ */
+
+/**
+ * @typedef {Object} ServeOptions
+ * @property {number} port
+ * @property {string} [host='127.0.0.1']
+ * @property {string} [path='/sync']
+ * @property {number} [maxRequestBytes=4194304]
+ * @property {import('../../ports/HttpServerPort.js').default} httpPort
+ * @property {{keys: Record<string, string>, mode?: 'enforce'|'log-only', crypto?: import('../../ports/CryptoPort.js').default, logger?: import('../../ports/LoggerPort.js').default, wallClockMs?: () => number}} [auth]
+ * @property {string[]} [allowedWriters]
+ */
+
+/**
+ * @typedef {Object} MaterializeOptions
+ * @property {boolean} [receipts]
+ * @property {number|null} [ceiling]
+ */
+
+/**
+ * @typedef {Object} PatchCommitEvent
+ * @property {unknown} [patch]
+ * @property {string} sha
+ */
+
+export {};

package/src/domain/types/WarpPersistence.js

@@ -0,0 +1,41 @@
+/**
+ * Role-specific persistence port types.
+ *
+ * Instead of casting to `any` when accessing persistence methods,
+ * use these narrow types to document which port methods are actually needed.
+ *
+ * NOTE: CommitPort, BlobPort, TreePort, and RefPort each contain both
+ * read and write methods. True read/write separation would require
+ * splitting each port, which is deferred. For now, the role-named
+ * aliases below are identical — they exist to document *intent* at
+ * each call site, not to enforce access restrictions.
+ *
+ * @module domain/types/WarpPersistence
+ */
+
+/**
+ * Full persistence port — commit + blob + tree + ref + config.
+ * @typedef {import('../../ports/GraphPersistencePort.js').default} WarpPersistence
+ */
+
+/**
+ * Commit + blob + tree + ref (no config).
+ * Used by sync readers, checkpoint creators, patch writers, and
+ * materialize paths. Identical to CheckpointPersistence by design
+ * (see module-level note).
+ * @typedef {import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default & import('../../ports/RefPort.js').default} CorePersistence
+ */
+
+/**
+ * Ref-only persistence — ref reads, writes, CAS, listing.
+ * @typedef {import('../../ports/RefPort.js').default} RefPersistence
+ */
+
+/**
+ * Index storage — blob reads/writes, tree reads/writes, ref reads/writes.
+ * Matches the dynamically-composed IndexStoragePort interface.
+ * @typedef {import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default & import('../../ports/RefPort.js').default} IndexStorage
+ */
+
+// Export nothing at runtime — types only
+export {};

package/src/domain/types/WarpTypes.js

@@ -35,7 +35,7 @@
  * Inline value reference - value stored directly in the operation
  * @typedef {Object} ValueRefInline
  * @property {'inline'} type - Discriminator for inline values
- * @property {*} value - The actual value (any JSON-serializable type)
+ * @property {unknown} value - The actual value (any JSON-serializable type)
  */
 
 /**
@@ -70,7 +70,7 @@
 
 /**
  * Creates an inline value reference
- * @param {*} value - The value to store inline
+ * @param {unknown} value - The value to store inline
  * @returns {ValueRefInline} Inline value reference
  */
 export function createInlineValue(value) {

package/src/domain/types/WarpTypesV2.js

@@ -80,7 +80,7 @@
  * @property {'PropSet'} type - Operation type discriminator
  * @property {NodeId} node - Node ID to set property on
  * @property {string} key - Property key
- * @property {*} value - Property value (any JSON-serializable type)
+ * @property {unknown} value - Property value (any JSON-serializable type)
  */
 
 /**
@@ -156,7 +156,7 @@ export function createEdgeRemoveV2(from, to, label, observedDots) {
  * Creates a PropSet operation (no dot - uses EventId)
  * @param {NodeId} node - Node ID to set property on
  * @param {string} key - Property key
- * @param {*} value - Property value (any JSON-serializable type)
+ * @param {unknown} value - Property value (any JSON-serializable type)
  * @returns {OpV2PropSet} PropSet operation
  */
 export function createPropSetV2(node, key, value) {

package/src/domain/utils/MinHeap.js

@@ -3,20 +3,21 @@
  * Items with lowest priority are extracted first.
  *
  * @class MinHeap
+ * @template T
  */
 class MinHeap {
   /**
    * Creates an empty MinHeap.
    */
   constructor() {
-    /** @type {Array<{item: *, priority: number}>} */
+    /** @type {Array<{item: T, priority: number}>} */
     this.heap = [];
   }
 
   /**
    * Insert an item with given priority.
    *
-   * @param {*} item - The item to insert
+   * @param {T} item - The item to insert
    * @param {number} priority - Priority value (lower = higher priority)
    * @returns {void}
    */
@@ -28,14 +29,14 @@ class MinHeap {
   /**
    * Extract and return the item with minimum priority.
    *
-   * @returns {*} The item with lowest priority, or undefined if empty
+   * @returns {T | undefined} The item with lowest priority, or undefined if empty
    */
   extractMin() {
     if (this.heap.length === 0) { return undefined; }
-    if (this.heap.length === 1) { return /** @type {{item: *, priority: number}} */ (this.heap.pop()).item; }
+    if (this.heap.length === 1) { return /** @type {{item: T, priority: number}} */ (this.heap.pop()).item; }
 
     const min = this.heap[0];
-    this.heap[0] = /** @type {{item: *, priority: number}} */ (this.heap.pop());
+    this.heap[0] = /** @type {{item: T, priority: number}} */ (this.heap.pop());
     this._bubbleDown(0);
     return min.item;
   }

package/src/domain/utils/canonicalStringify.js

@@ -7,7 +7,7 @@
  * - Array elements that are undefined/function/symbol become "null"
  * - Object properties with undefined/function/symbol values are omitted
  *
- * @param {*} value - Any JSON-serializable value
+ * @param {unknown} value - Any JSON-serializable value
  * @returns {string} Canonical JSON string with sorted keys
  */
 export function canonicalStringify(value) {
@@ -28,14 +28,15 @@ export function canonicalStringify(value) {
     return `[${elements.join(',')}]`;
   }
   if (typeof value === 'object') {
+    const obj = /** @type {Record<string, unknown>} */ (value);
     // Filter out keys with undefined/function/symbol values, then sort
-    const keys = Object.keys(value)
+    const keys = Object.keys(obj)
       .filter(k => {
-        const v = value[k];
+        const v = obj[k];
         return v !== undefined && typeof v !== 'function' && typeof v !== 'symbol';
       })
       .sort();
-    const pairs = keys.map(k => `${JSON.stringify(k)}:${canonicalStringify(value[k])}`);
+    const pairs = keys.map(k => `${JSON.stringify(k)}:${canonicalStringify(obj[k])}`);
     return `{${pairs.join(',')}}`;
   }
   return JSON.stringify(value);