@git-stunts/git-warp 12.2.1 → 12.4.1

package/src/domain/services/TemporalQuery.js

@@ -86,12 +86,7 @@ function extractNodeSnapshot(state, nodeId) {
 /**
  * Evaluates checkpoint boundary semantics for `always()`.
  *
- * @param {Object} params
- * @param {import('./JoinReducer.js').WarpStateV5} params.state
- * @param {string} params.nodeId
- * @param {Function} params.predicate
- * @param {number|null} params.checkpointMaxLamport
- * @param {number} params.since
+ * @param {{ state: import('./JoinReducer.js').WarpStateV5, nodeId: string, predicate: (snapshot: {id: string, exists: boolean, props: Record<string, unknown>}) => boolean, checkpointMaxLamport: number|null, since: number }} params
  * @returns {{ nodeEverExisted: boolean, shouldReturn: boolean, returnValue: boolean }}
  * @private
  */
@@ -118,12 +113,7 @@ function evaluateAlwaysCheckpointBoundary({
 /**
  * Evaluates checkpoint boundary semantics for `eventually()`.
  *
- * @param {Object} params
- * @param {import('./JoinReducer.js').WarpStateV5} params.state
- * @param {string} params.nodeId
- * @param {Function} params.predicate
- * @param {number|null} params.checkpointMaxLamport
- * @param {number} params.since
+ * @param {{ state: import('./JoinReducer.js').WarpStateV5, nodeId: string, predicate: (snapshot: {id: string, exists: boolean, props: Record<string, unknown>}) => boolean, checkpointMaxLamport: number|null, since: number }} params
  * @returns {boolean}
  * @private
  */
@@ -149,16 +139,12 @@ function evaluateEventuallyCheckpointBoundary({
  */
 export class TemporalQuery {
   /**
-   * @param {Object} options
-   * @param {Function} options.loadAllPatches - Async function that returns
-   *   all patches as Array<{ patch, sha }> in causal order.
-   * @param {Function} [options.loadCheckpoint] - Async function returning
-   *   { state: WarpStateV5, maxLamport: number } or null.
+   * @param {{ loadAllPatches: () => Promise<Array<{patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}>>, loadCheckpoint?: () => Promise<{state: import('./JoinReducer.js').WarpStateV5, maxLamport: number}|null> }} options
    */
   constructor({ loadAllPatches, loadCheckpoint }) {
-    /** @type {Function} */
+    /** @type {() => Promise<Array<{patch: import('../types/WarpTypesV2.js').PatchV2, sha: string}>>} */
     this._loadAllPatches = loadAllPatches;
-    /** @type {Function|null} */
+    /** @type {(() => Promise<{state: import('./JoinReducer.js').WarpStateV5, maxLamport: number}|null>)|null} */
     this._loadCheckpoint = loadCheckpoint || null;
   }
 
@@ -172,11 +158,9 @@ export class TemporalQuery {
    * Returns false if the node never existed in the range.
    *
    * @param {string} nodeId - The node ID to evaluate
-   * @param {Function} predicate - Predicate receiving node snapshot
+   * @param {(snapshot: {id: string, exists: boolean, props: Record<string, unknown>}) => boolean} predicate - Predicate receiving node snapshot
    *   `{ id, exists, props }`. Should return boolean.
-   * @param {Object} [options={}] - Options
-   * @param {number} [options.since=0] - Minimum Lamport tick (inclusive).
-   *   Only patches with lamport >= since are considered.
+   * @param {{ since?: number }} [options={}] - Options
    * @returns {Promise<boolean>} True if predicate held at every tick
    *
    * @example
@@ -232,11 +216,9 @@ export class TemporalQuery {
    * soon as the predicate returns true at any tick.
    *
    * @param {string} nodeId - The node ID to evaluate
-   * @param {Function} predicate - Predicate receiving node snapshot
+   * @param {(snapshot: {id: string, exists: boolean, props: Record<string, unknown>}) => boolean} predicate - Predicate receiving node snapshot
    *   `{ id, exists, props }`. Should return boolean.
-   * @param {Object} [options={}] - Options
-   * @param {number} [options.since=0] - Minimum Lamport tick (inclusive).
-   *   Only patches with lamport >= since are considered.
+   * @param {{ since?: number }} [options={}] - Options
    * @returns {Promise<boolean>} True if predicate held at any tick
    *
    * @example

package/src/domain/services/TranslationCost.js

@@ -169,14 +169,8 @@ function computePropLoss(state, { nodesA, nodesBSet, configA, configB }) {
  * The cost measures how much information is lost when translating from
  * A's view to B's view. It is asymmetric: cost(A->B) != cost(B->A) in general.
  *
- * @param {Object} configA - Observer configuration for A
- * @param {string|string[]} configA.match - Glob pattern(s) for visible nodes
- * @param {string[]} [configA.expose] - Property keys to include
- * @param {string[]} [configA.redact] - Property keys to exclude
- * @param {Object} configB - Observer configuration for B
- * @param {string|string[]} configB.match - Glob pattern(s) for visible nodes
- * @param {string[]} [configB.expose] - Property keys to include
- * @param {string[]} [configB.redact] - Property keys to exclude
+ * @param {{ match: string|string[], expose?: string[], redact?: string[] }} configA - Observer configuration for A
+ * @param {{ match: string|string[], expose?: string[], redact?: string[] }} configB - Observer configuration for B
  * @param {WarpStateV5} state - WarpStateV5 materialized state
  * @returns {{ cost: number, breakdown: { nodeLoss: number, edgeLoss: number, propLoss: number } }}
  */

package/src/domain/services/WarpMessageCodec.js

@@ -29,4 +29,6 @@ export {
   assertOpsCompatible,
   SCHEMA_V2,
   SCHEMA_V3,
+  PATCH_SCHEMA_V2,
+  PATCH_SCHEMA_V3,
 } from './MessageSchemaDetector.js';

package/src/domain/services/WarpStateIndexBuilder.js

@@ -30,8 +30,7 @@ import { decodeEdgeKey } from './KeyCodec.js';
 export default class WarpStateIndexBuilder {
   /**
    * Creates a new WarpStateIndexBuilder.
-   * @param {Object} [options] - Configuration
-   * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort for shard checksums
+   * @param {{ crypto?: import('../../ports/CryptoPort.js').default }} [options] - Configuration
    */
   constructor({ crypto } = {}) {
     /** @type {BitmapIndexBuilder} */
@@ -109,8 +108,7 @@ export default class WarpStateIndexBuilder {
  * Convenience function to build and serialize a WARP state index.
  *
  * @param {import('./JoinReducer.js').WarpStateV5} state - The materialized state
- * @param {Object} [options] - Configuration
- * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort for shard checksums
+ * @param {{ crypto?: import('../../ports/CryptoPort.js').default }} [options] - Configuration
  * @returns {Promise<{tree: Record<string, Buffer>, stats: {nodes: number, edges: number}}>} Serialized index and stats
  *
  * @example

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

@@ -16,6 +16,13 @@ export const SUPPORTED_ALGORITHMS = new Set(['ed25519']);
 
 const ED25519_PUBLIC_KEY_LENGTH = 32;
 
+/**
+ * DER-encoded SPKI prefix for Ed25519 public keys (RFC 8410, Section 4).
+ * Prepend to a 32-byte raw key to form a valid SPKI structure for `createPublicKey()`.
+ * @see https://www.rfc-editor.org/rfc/rfc8410#section-4
+ */
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
 /**
  * Decodes a base64-encoded Ed25519 public key and validates its length.
  *
@@ -56,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
@@ -81,11 +84,7 @@ export function verifySignature({
   const raw = decodePublicKey(publicKeyBase64);
 
   const keyObject = createPublicKey({
-    key: Buffer.concat([
-      // DER prefix for Ed25519 public key (RFC 8410)
-      Buffer.from('302a300506032b6570032100', 'hex'),
-      raw,
-    ]),
+    key: Buffer.concat([ED25519_SPKI_PREFIX, raw]),
     format: 'der',
     type: 'spki',
   });

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

@@ -25,6 +25,8 @@ export const OP_TYPES = Object.freeze([
   'EdgeAdd',
   'EdgeTombstone',
   'PropSet',
+  'NodePropSet',
+  'EdgePropSet',
   'BlobValue',
 ]);
 
@@ -80,9 +82,9 @@ function validateOp(op, index) {
 /**
  * Validates that an operation type is one of the allowed OP_TYPES.
  *
- * Valid operation types correspond to the six patch operations defined
- * in PatchBuilderV2: NodeAdd, NodeTombstone, EdgeAdd, EdgeTombstone,
- * PropSet, and BlobValue.
+ * Valid operation types correspond to the eight receipt operation types:
+ * NodeAdd, NodeTombstone, EdgeAdd, EdgeTombstone, PropSet, NodePropSet,
+ * EdgePropSet, and BlobValue.
  *
  * @param {unknown} value - The operation type to validate
  * @param {number} i - Index of the operation in the ops array (for error messages)
@@ -156,7 +158,7 @@ function validateOpResult(value, i) {
 
 /**
  * @typedef {Object} OpOutcome
- * @property {string} op - Operation type ('NodeAdd' | 'NodeTombstone' | 'EdgeAdd' | 'EdgeTombstone' | 'PropSet' | 'BlobValue')
+ * @property {string} op - Operation type ('NodeAdd' | 'NodeTombstone' | 'EdgeAdd' | 'EdgeTombstone' | 'PropSet' | 'NodePropSet' | 'EdgePropSet' | 'BlobValue')
  * @property {string} target - Node ID or edge key
  * @property {'applied' | 'superseded' | 'redundant'} result - Outcome of the operation
  * @property {string} [reason] - Human-readable explanation (e.g., "LWW: writer bob at lamport 43 wins")
@@ -173,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
  */
@@ -277,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

@@ -74,18 +74,64 @@
  */
 
 /**
- * Property set operation - sets a property value on a node
- * Uses EventId for identification (derived from patch context)
+ * Property set operation - sets a property value on a node (raw/persisted form).
+ * Uses EventId for identification (derived from patch context).
+ *
+ * In raw patches, edge properties are also encoded as PropSet with the node
+ * field carrying a \x01-prefixed edge identity. See {@link OpV2NodePropSet}
+ * and {@link OpV2EdgePropSet} for the canonical (internal) representations.
+ *
  * @typedef {Object} OpV2PropSet
  * @property {'PropSet'} type - Operation type discriminator
+ * @property {NodeId} node - Node ID to set property on (may contain \x01 prefix for edge props)
+ * @property {string} key - Property key
+ * @property {unknown} value - Property value (any JSON-serializable type)
+ */
+
+/**
+ * Canonical node property set operation (internal only — never persisted).
+ * @typedef {Object} OpV2NodePropSet
+ * @property {'NodePropSet'} type - Operation type discriminator
  * @property {NodeId} node - Node ID to set property on
  * @property {string} key - Property key
  * @property {unknown} value - Property value (any JSON-serializable type)
  */
 
 /**
- * Union of all v2 operation types
- * @typedef {OpV2NodeAdd | OpV2NodeRemove | OpV2EdgeAdd | OpV2EdgeRemove | OpV2PropSet} OpV2
+ * Canonical edge property set operation (internal only — never persisted).
+ * @typedef {Object} OpV2EdgePropSet
+ * @property {'EdgePropSet'} type - Operation type discriminator
+ * @property {NodeId} from - Source node ID
+ * @property {NodeId} to - Target node ID
+ * @property {string} label - Edge label
+ * @property {string} key - Property key
+ * @property {unknown} value - Property value (any JSON-serializable type)
+ */
+
+/**
+ * Blob value reference operation.
+ * @typedef {Object} OpV2BlobValue
+ * @property {'BlobValue'} type - Operation type discriminator
+ * @property {string} node - Node ID the blob is attached to
+ * @property {string} oid - Blob object ID in the Git object store
+ */
+
+/**
+ * Union of all raw (persisted) v2 operation types.
+ * @typedef {OpV2NodeAdd | OpV2NodeRemove | OpV2EdgeAdd | OpV2EdgeRemove | OpV2PropSet | OpV2BlobValue} RawOpV2
+ */
+
+/**
+ * Union of all canonical (internal) v2 operation types.
+ * Reducers, provenance, receipts, and queries operate on canonical ops only.
+ * @typedef {OpV2NodeAdd | OpV2NodeRemove | OpV2EdgeAdd | OpV2EdgeRemove | OpV2NodePropSet | OpV2EdgePropSet | OpV2BlobValue} CanonicalOpV2
+ */
+
+/**
+ * Union of all v2 operation types (raw + canonical).
+ * Used in patch containers that may hold either raw ops (from disk)
+ * or canonical ops (after normalization).
+ * @typedef {RawOpV2 | CanonicalOpV2} OpV2
  */
 
 // ============================================================================
@@ -153,7 +199,9 @@ export function createEdgeRemoveV2(from, to, label, observedDots) {
 }
 
 /**
- * Creates a PropSet operation (no dot - uses EventId)
+ * Creates a raw PropSet operation (no dot - uses EventId).
+ * This is the persisted form. For internal use, prefer
+ * {@link createNodePropSetV2} or {@link createEdgePropSetV2}.
  * @param {NodeId} node - Node ID to set property on
  * @param {string} key - Property key
  * @param {unknown} value - Property value (any JSON-serializable type)
@@ -163,20 +211,37 @@ export function createPropSetV2(node, key, value) {
   return { type: 'PropSet', node, key, value };
 }
 
+/**
+ * Creates a canonical NodePropSet operation (internal only).
+ * @param {NodeId} node - Node ID to set property on
+ * @param {string} key - Property key
+ * @param {unknown} value - Property value (any JSON-serializable type)
+ * @returns {OpV2NodePropSet} NodePropSet operation
+ */
+export function createNodePropSetV2(node, key, value) {
+  return { type: 'NodePropSet', node, key, value };
+}
+
+/**
+ * Creates a canonical EdgePropSet operation (internal only).
+ * @param {NodeId} from - Source node ID
+ * @param {NodeId} to - Target node ID
+ * @param {string} label - Edge label
+ * @param {string} key - Property key
+ * @param {unknown} value - Property value (any JSON-serializable type)
+ * @returns {OpV2EdgePropSet} EdgePropSet operation
+ */
+export function createEdgePropSetV2(from, to, label, key, value) {
+  return { type: 'EdgePropSet', from, to, label, key, value };
+}
+
 // ============================================================================
 // Factory Functions - Patch
 // ============================================================================
 
 /**
  * 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/defaultClock.js

@@ -13,6 +13,7 @@ const defaultClock = {
     return performance.now();
   },
   timestamp() {
+    // eslint-disable-next-line no-restricted-syntax -- ClockPort implementation
     return new Date().toISOString();
   },
 };

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()) {