@git-stunts/git-warp 12.2.0 → 12.3.0

package/README.md

@@ -8,12 +8,13 @@
   <img src="docs/images/hero.gif" alt="git-warp CLI demo" width="600">
 </p>
 
-## What's New in v12.2.0
+## What's New in v12.3.0
 
-- **O(N log N) topological sort** — `topologicalSort()` now uses a MinHeap ready queue instead of sorted-array merging, eliminating the O(N²) hot path for large DAGs.
-- **QueryBuilder batching + memoization** — property fetches are now bounded (chunks of 100) and cached per-run, reducing redundant I/O across where-clauses, result building, and aggregation.
-- **Fast materialization guard** — `_materializeGraph()` skips full materialization when cached state is clean, improving query/traversal latency.
-- **Checkpoint `visible.cbor` removed** — checkpoints no longer write the unused visible-projection blob, saving one serialize + blob write per checkpoint.
+- **M13 ADR 1 — canonical edge property ops** — internal model now uses honest `NodePropSet`/`EdgePropSet` semantics. Legacy raw `PropSet` is normalized at reducer entry points and lowered back at write time. No wire-format change — persisted patches remain backward-compatible.
+- **Wire gate hardened** — sync boundary now explicitly rejects canonical-only op types (`NodePropSet`, `EdgePropSet`) arriving over the wire, preventing premature schema migration before ADR 2 capability cutover.
+- **Reserved-byte validation** — new writes reject node IDs containing `\0` or starting with `\x01`, preventing ambiguous legacy edge-property encoding.
+- **Version namespace separation** — patch schema and checkpoint schema constants are now distinct (`PATCH_SCHEMA_V2`/`V3` vs `CHECKPOINT_SCHEMA_STANDARD`/`INDEX_TREE`).
+- **ADR governance** — ADR 3 readiness gates formalize when the persisted wire-format migration may proceed, with GitHub issue template and go/no-go checklist.
 
 See the [full changelog](CHANGELOG.md) for details.
 
@@ -105,7 +106,7 @@ When you want to read the graph, you **materialize** — which means replaying a
 
 Every operation gets a unique **EventId** — `(lamport, writerId, patchSha, opIndex)` — which creates a total ordering that makes merge results identical no matter which machine runs them.
 
-**Checkpoints** snapshot the materialized state into a single commit for fast incremental recovery. Subsequent materializations only need to replay patches created after the checkpoint.
+**Checkpoints** snapshot the materialized state into a single commit for fast incremental recovery. Subsequent materializations only need to replay patches created after the checkpoint. During incremental replay, checkpoint ancestry is validated once per writer tip (not once per patch), which keeps long writer chains efficient.
 
 ## Multi-Writer Collaboration
 
@@ -474,6 +475,8 @@ const graph = await WarpGraph.open({
 });
 ```
 
+When cached state is clean, local commits take an eager path that applies the patch in-memory and threads a patch diff into view rebuild (`_setMaterializedState(..., { diff })`). That allows incremental bitmap index updates on the hot write path instead of full index rebuilds.
+
 ## Observability
 
 ```javascript

package/bin/cli/commands/trust.js

@@ -14,6 +14,7 @@ import defaultCodec from '../../../src/domain/utils/defaultCodec.js';
 import { TrustRecordService } from '../../../src/domain/trust/TrustRecordService.js';
 import { buildState } from '../../../src/domain/trust/TrustStateBuilder.js';
 import { evaluateWriters } from '../../../src/domain/trust/TrustEvaluator.js';
+import { TRUST_REASON_CODES } from '../../../src/domain/trust/reasonCodes.js';
 
 /** @typedef {import('../types.js').CliOptions} CliOptions */
 
@@ -112,8 +113,43 @@ export default async function handleTrust({ options, args }) {
   const { pin, source, sourceDetail, status } = resolveTrustPin(trustPin);
 
   // Read trust records
-  const records = await recordService.readRecords(graphName, pin ? { tip: pin } : {});
+  const recordsResult = await recordService.readRecords(graphName, pin ? { tip: pin } : {});
+  if (!recordsResult.ok) {
+    const payload = {
+      graph: graphName,
+      trustSchemaVersion: 1,
+      mode: 'signed_evidence_v1',
+      trustVerdict: 'fail',
+      trust: {
+        status: 'error',
+        source,
+        sourceDetail,
+        evaluatedWriters: [],
+        untrustedWriters: [],
+        explanations: [
+          {
+            writerId: '*',
+            trusted: false,
+            reasonCode: TRUST_REASON_CODES.TRUST_RECORD_CHAIN_INVALID,
+            reason: `Trust chain read failed: ${recordsResult.error.message}`,
+          },
+        ],
+        evidenceSummary: {
+          recordsScanned: 0,
+          activeKeys: 0,
+          revokedKeys: 0,
+          activeBindings: 0,
+          revokedBindings: 0,
+        },
+      },
+    };
+    return {
+      payload,
+      exitCode: mode === 'enforce' ? EXIT_CODES.TRUST_FAIL : EXIT_CODES.OK,
+    };
+  }
 
+  const { records } = recordsResult;
   if (records.length === 0) {
     return buildNotConfiguredResult(graphName);
   }

package/bin/cli/infrastructure.js

@@ -166,6 +166,12 @@ const BASE_OPTIONS = {
  * Pre-processes argv to handle --view's optional-value semantics.
  * If --view is followed by a command name or flag (or is last), injects 'ascii'.
  * Validates the view mode value.
+ *
+ * When --view is passed without a value, we inject 'ascii' as the default.
+ * This happens before validation so the downstream parser sees a concrete
+ * value. The synthetic injection is intentional — parseArgs requires --view
+ * to have a value even though the CLI allows bare --view.
+ *
  * @param {string[]} argv
  * @returns {string[]}
  */
@@ -223,6 +229,7 @@ function extractBaseArgs(argv) {
   const rest = [];
   /** @type {string|undefined} */
   let command;
+  // Phase 1: Pre-command — scan for base flags (--repo, --json, --view, etc.)
   let pastCommand = false;
 
   for (let i = 0; i < argv.length; i++) {
@@ -266,7 +273,13 @@ function extractBaseArgs(argv) {
       continue;
     }
 
-    if (!pastCommand && !arg.startsWith('-')) {
+    if (pastCommand) {
+      // Phase 2: Post-command — remaining args are command-specific, stop scanning
+      rest.push(arg);
+      continue;
+    }
+
+    if (!arg.startsWith('-')) {
       command = arg;
       pastCommand = true;
       continue;

package/bin/cli/schemas.js

@@ -36,7 +36,7 @@ export const pathSchema = z.object({
   to: z.string().optional(),
   dir: z.enum(['out', 'in', 'both']).optional(),
   label: z.union([z.string(), z.array(z.string())]).optional(),
-  'max-depth': z.coerce.number().int().nonnegative().optional(),
+  'max-depth': z.coerce.number().int().nonnegative().refine(n => Number.isFinite(n), { message: 'must be a finite number' }).optional(),
 }).strict().transform((val) => ({
   from: val.from ?? null,
   to: val.to ?? null,
@@ -102,7 +102,7 @@ export const seekSchema = z.object({
   'clear-cache': z.boolean().default(false),
   'no-persistent-cache': z.boolean().default(false),
   diff: z.boolean().default(false),
-  'diff-limit': z.coerce.number().int({ message: '--diff-limit must be a positive integer' }).positive({ message: '--diff-limit must be a positive integer' }).default(2000),
+  'diff-limit': z.coerce.number().int({ message: '--diff-limit must be a positive integer' }).positive({ message: '--diff-limit must be a positive integer' }).refine(n => Number.isFinite(n), { message: '--diff-limit must be a finite number' }).default(2000),
 }).strict().superRefine((val, ctx) => {
   // Count mutually exclusive action flags
   const actions = [
@@ -181,8 +181,8 @@ export const seekSchema = z.object({
 // ============================================================================
 
 export const verifyIndexSchema = z.object({
-  seed: z.coerce.number().int().min(-2147483648).max(2147483647).optional(),
-  'sample-rate': z.coerce.number().gt(0, '--sample-rate must be greater than 0').max(1).optional().default(0.1),
+  seed: z.coerce.number().int().min(-2147483648).max(2147483647).refine(n => Number.isFinite(n), { message: 'must be a finite number' }).optional(),
+  'sample-rate': z.coerce.number().gt(0, '--sample-rate must be greater than 0').max(1).refine(n => Number.isFinite(n), { message: 'must be a finite number' }).optional().default(0.1),
 }).strict().transform((val) => ({
   seed: val.seed,
   sampleRate: val['sample-rate'],

package/bin/presenters/text.js

@@ -291,7 +291,8 @@ function formatOpSummaryPlain(summary) {
   const order = [
     ['NodeAdd', '+', 'node'],
     ['EdgeAdd', '+', 'edge'],
-    ['PropSet', '~', 'prop'],
+    ['prop', '~', 'prop'],       // coalesced PropSet + NodePropSet
+    ['EdgePropSet', '~', 'eprop'],
     ['NodeTombstone', '-', 'node'],
     ['EdgeTombstone', '-', 'edge'],
     ['BlobValue', '+', 'blob'],
@@ -299,7 +300,10 @@ function formatOpSummaryPlain(summary) {
 
   const parts = [];
   for (const [opType, symbol, label] of order) {
-    const n = summary?.[opType];
+    // Coalesce PropSet + NodePropSet into one bucket
+    const n = opType === 'prop'
+      ? (summary?.PropSet || 0) + (summary?.NodePropSet || 0) || undefined
+      : summary?.[opType];
     if (typeof n === 'number' && Number.isFinite(n) && n > 0) {
       parts.push(`${symbol}${n}${label}`);
     }
@@ -612,9 +616,12 @@ function formatPatchOp(op) {
   if (op.type === 'EdgeTombstone') {
     return `  - edge ${op.from} -[${op.label}]-> ${op.to}`;
   }
-  if (op.type === 'PropSet') {
+  if (op.type === 'PropSet' || op.type === 'NodePropSet') {
     return `  ~ ${op.node}.${op.key} = ${JSON.stringify(op.value)}`;
   }
+  if (op.type === 'EdgePropSet') {
+    return `  ~ edge(${op.from} -[${op.label}]-> ${op.to}).${op.key} = ${JSON.stringify(op.value)}`;
+  }
   if (op.type === 'BlobValue') {
     return `  + blob ${op.node}`;
   }

package/bin/warp-graph.js

@@ -9,7 +9,10 @@ import { COMMANDS } from './cli/commands/registry.js';
 
 const VIEW_SUPPORTED_COMMANDS = ['info', 'check', 'history', 'path', 'materialize', 'query', 'seek'];
 
-// C8: Capture output format early so the error handler can use it
+// Output format must be captured from raw process.argv BEFORE parseArgs() runs.
+// If parseArgs() itself throws (e.g., unknown flag, malformed input), the `options`
+// object will not exist, so the error handler cannot read `options.json`. By
+// pre-scanning argv, the error handler can still emit structured output.
 const hasJsonFlag = process.argv.includes('--json');
 const hasNdjsonFlag = process.argv.includes('--ndjson');
 

package/index.d.ts

@@ -1060,6 +1060,20 @@ export class SchemaUnsupportedError extends Error {
   });
 }
 
+/**
+ * Error class for malformed or invalid patch operations.
+ */
+export class PatchError extends Error {
+  readonly name: 'PatchError';
+  readonly code: string;
+  readonly context: Record<string, unknown>;
+
+  constructor(message: string, options?: {
+    code?: string;
+    context?: Record<string, unknown>;
+  });
+}
+
 /**
  * Error class for sync transport operations.
  */
@@ -1530,6 +1544,7 @@ export interface SyncResponse {
   type: 'sync-response';
   frontier: Record<string, string>;
   patches: Array<{ writerId: string; sha: string; patch: unknown }>;
+  skippedWriters?: Array<{ writerId: string; reason: string; localSha: string; remoteSha: string | null }>;
 }
 
 /**
@@ -1539,6 +1554,7 @@ export interface ApplySyncResult {
   state: WarpStateV5;
   frontier: Map<string, number>;
   applied: number;
+  skippedWriters: Array<{ writerId: string; reason: string; localSha: string; remoteSha: string | null }>;
 }
 
 /**
@@ -1831,7 +1847,7 @@ export default class WarpGraph {
     auth?: SyncAuthClientOptions;
     /** Auto-materialize after sync; when true, result includes `state` */
     materialize?: boolean;
-  }): Promise<{ applied: number; attempts: number; state?: WarpStateV5 }>;
+  }): Promise<{ applied: number; attempts: number; skippedWriters: Array<{ writerId: string; reason: string; localSha: string; remoteSha: string | null }>; state?: WarpStateV5 }>;
 
   /**
    * Creates a fork of this graph at a specific point in a writer's history.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-warp",
-  "version": "12.2.0",
+  "version": "12.3.0",
   "description": "Deterministic WARP graph over Git: graph-native storage, traversal, and tooling.",
   "type": "module",
   "license": "Apache-2.0",

package/src/domain/WarpGraph.js

@@ -39,7 +39,7 @@ const DEFAULT_ADJACENCY_CACHE_SIZE = 3;
 /**
  * @typedef {Object} MaterializedGraph
  * @property {import('./services/JoinReducer.js').WarpStateV5} state
- * @property {string} stateHash
+ * @property {string|null} stateHash
  * @property {{outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>>}} adjacency
  * @property {import('./services/BitmapNeighborProvider.js').default} [provider]
  */

package/src/domain/crdt/Dot.js

@@ -109,6 +109,11 @@ export function encodeDot(dot) {
 /**
  * Decodes an encoded dot string back to a Dot object.
  *
+ * Writer IDs are parsed using lastIndexOf(':') as separator. Writer IDs
+ * containing colons are supported because the counter (after the last colon)
+ * is always numeric. However, empty writer IDs or IDs ending with a colon
+ * may produce unexpected results.
+ *
  * @param {string} encoded - Format: "writerId:counter"
  * @returns {Dot}
  * @throws {Error} If format is invalid

package/src/domain/crdt/LWW.js

@@ -126,7 +126,9 @@ export function lwwSet(eventId, value) {
  * @returns {LWWRegister<T> | null} Register with greater EventId, or null if both null/undefined
  */
 export function lwwMax(a, b) {
-  // Handle null/undefined cases
+  // Null/undefined values are handled defensively for forward compatibility.
+  // Current callers always provide non-null values, but the LWW register
+  // contract permits null as a valid tombstone value.
   if ((a === null || a === undefined) && (b === null || b === undefined)) {
     return null;
   }

package/src/domain/crdt/ORSet.js

@@ -116,6 +116,9 @@ export function createORSet() {
  * @param {import('./Dot.js').Dot} dot - The dot representing this add operation
  */
 export function orsetAdd(set, element, dot) {
+  if (!dot || typeof dot.writerId !== 'string' || !Number.isInteger(dot.counter)) {
+    throw new Error(`orsetAdd: invalid dot -- expected {writerId: string, counter: integer}, got ${JSON.stringify(dot)}`);
+  }
   const encoded = encodeDot(dot);
 
   let dots = set.entries.get(element);
@@ -221,24 +224,26 @@ export function orsetGetDots(set, element) {
 export function orsetJoin(a, b) {
   const result = createORSet();
 
-  // Union entries from a
+  // Copy entries from a into result — each dot set is shallow-copied so the
+  // caller cannot mutate the original through the result.
   for (const [element, dots] of a.entries) {
     result.entries.set(element, new Set(dots));
   }
 
-  // Union entries from b
+  // Merge entries from b — if the element already exists (from a), add into
+  // the cloned set; otherwise clone b's dot set the same way for consistency.
   for (const [element, dots] of b.entries) {
-    let resultDots = result.entries.get(element);
-    if (!resultDots) {
-      resultDots = new Set();
-      result.entries.set(element, resultDots);
-    }
-    for (const dot of dots) {
-      resultDots.add(dot);
+    const existing = result.entries.get(element);
+    if (existing) {
+      for (const dot of dots) {
+        existing.add(dot);
+      }
+    } else {
+      result.entries.set(element, new Set(dots));
     }
   }
 
-  // Union tombstones
+  // Union tombstones from both sides
   for (const dot of a.tombstones) {
     result.tombstones.add(dot);
   }
@@ -343,16 +348,19 @@ export function orsetClone(set) {
  * @returns {{entries: Array<[string, string[]]>, tombstones: string[]}}
  */
 export function orsetSerialize(set) {
-  // Serialize entries: convert Map to array of [element, sortedDots]
+  // Serialize entries: convert Map to array of [element, sortedDots].
+  // Pre-decode dots before sorting to avoid O(N log N) decodeDot calls
+  // during comparisons.
   /** @type {Array<[string, string[]]>} */
   const entriesArray = [];
   for (const [element, dots] of set.entries) {
-    const sortedDots = [...dots].sort((a, b) => {
-      const dotA = decodeDot(a);
-      const dotB = decodeDot(b);
-      return compareDots(dotA, dotB);
-    });
-    entriesArray.push([element, sortedDots]);
+    /** @type {Array<{encoded: string, decoded: import('./Dot.js').Dot}>} */
+    const pairs = [];
+    for (const encoded of dots) {
+      pairs.push({ encoded, decoded: decodeDot(encoded) });
+    }
+    pairs.sort((a, b) => compareDots(a.decoded, b.decoded));
+    entriesArray.push([element, pairs.map((p) => p.encoded)]);
   }
 
   // Sort entries by element (stringified for consistency)
@@ -362,12 +370,14 @@ export function orsetSerialize(set) {
     return keyA < keyB ? -1 : keyA > keyB ? 1 : 0;
   });
 
-  // Serialize tombstones: sorted array
-  const sortedTombstones = [...set.tombstones].sort((a, b) => {
-    const dotA = decodeDot(a);
-    const dotB = decodeDot(b);
-    return compareDots(dotA, dotB);
-  });
+  // Serialize tombstones: pre-decode then sort
+  /** @type {Array<{encoded: string, decoded: import('./Dot.js').Dot}>} */
+  const tombPairs = [];
+  for (const encoded of set.tombstones) {
+    tombPairs.push({ encoded, decoded: decodeDot(encoded) });
+  }
+  tombPairs.sort((a, b) => compareDots(a.decoded, b.decoded));
+  const sortedTombstones = tombPairs.map((p) => p.encoded);
 
   return {
     entries: entriesArray,

package/src/domain/crdt/VersionVector.js

@@ -160,11 +160,19 @@ export function vvContains(vv, dot) {
 export function vvSerialize(vv) {
   /** @type {Record<string, number>} */
   const obj = {};
+  // Key sort is required for deterministic serialization. The writer count
+  // is typically small (<100), so the O(W log W) cost is negligible.
   const sortedKeys = [...vv.keys()].sort();
 
   for (const key of sortedKeys) {
     const val = vv.get(key);
     if (val !== undefined) {
+      // Invariant assertion — not input validation. Zero counters must never
+      // appear in a VersionVector. They carry no causal information and would
+      // be elided on deserialization, breaking round-trip equality.
+      if (val === 0) {
+        throw new Error(`vvSerialize: zero counter for writerId "${key}" — VersionVector must not contain zero counters`);
+      }
       obj[key] = val;
     }
   }
@@ -175,6 +183,10 @@ export function vvSerialize(vv) {
 /**
  * Deserializes a plain object back to a VersionVector.
  *
+ * Zero counters are elided during deserialization. This is intentional — a
+ * counter of 0 carries no causal information and wastes space. Serialization
+ * must never emit zero counters.
+ *
  * @param {Object<string, number>} obj
  * @returns {VersionVector}
  * @throws {Error} If any counter value is not a non-negative integer

package/src/domain/errors/PatchError.js

@@ -0,0 +1,27 @@
+import WarpError from './WarpError.js';
+
+/**
+ * Error class for malformed or invalid patch operations.
+ *
+ * ## Error Codes
+ *
+ * | Code | Description |
+ * |------|-------------|
+ * | `E_PATCH_MALFORMED` | Operation is missing required fields or has invalid types |
+ *
+ * @class PatchError
+ * @extends WarpError
+ *
+ * @property {string} name - Always 'PatchError' for instanceof checks
+ * @property {string} code - Machine-readable error code for programmatic handling
+ * @property {Object} context - Serializable context object with error details
+ */
+export default class PatchError extends WarpError {
+  /**
+   * @param {string} message
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
+   */
+  constructor(message, options = {}) {
+    super(message, 'E_PATCH_MALFORMED', options);
+  }
+}

package/src/domain/errors/StorageError.js

@@ -3,6 +3,10 @@ import IndexError from './IndexError.js';
 /**
  * Error thrown when a storage operation fails.
  *
+ * StorageError extends IndexError because storage errors originate from
+ * index operations. This hierarchy is intentional — IndexError provides
+ * the storage-specific error context.
+ *
  * This error indicates that a read or write operation to storage failed,
  * typically due to I/O errors, permission issues, or storage unavailability.
  *
@@ -31,6 +35,10 @@ export default class StorageError extends IndexError {
   /**
    * Creates a new StorageError.
    *
+   * Context is merged via Object.assign — duplicate keys from the second
+   * argument overwrite the first. Callers should ensure context keys don't
+   * collide, or use unique prefixes.
+   *
    * @param {string} message - Human-readable error message
    * @param {{ operation?: string, oid?: string, cause?: Error, context?: Record<string, unknown> }} [options={}] - Error options
    */

package/src/domain/errors/WriterError.js

@@ -26,6 +26,11 @@ import WarpError from './WarpError.js';
  */
 export default class WriterError extends WarpError {
   /**
+   * Note: constructor parameter order differs from other WarpError subclasses
+   * (code, message vs message, code). This is intentional to match the most
+   * common call sites in PatchSession and PatchBuilderV2 where the error code
+   * is the primary discriminator.
+   *
    * @param {string} code - Error code
    * @param {string} message - Human-readable error message
    * @param {Error} [cause] - Original error that caused this error

package/src/domain/errors/index.js

@@ -9,6 +9,7 @@ export { default as WarpError } from './WarpError.js';
 export { default as ForkError } from './ForkError.js';
 export { default as IndexError } from './IndexError.js';
 export { default as OperationAbortedError } from './OperationAbortedError.js';
+export { default as PatchError } from './PatchError.js';
 export { default as QueryError } from './QueryError.js';
 export { default as SyncError } from './SyncError.js';
 export { default as ShardCorruptionError } from './ShardCorruptionError.js';

package/src/domain/services/AuditReceiptService.js

@@ -339,7 +339,8 @@ export class AuditReceiptService {
     // Compute opsDigest
     const opsDigest = await computeOpsDigest(ops, this._crypto);
 
-    // Timestamp
+    // Wall-clock timestamp for audit receipt (not a perf timer)
+    // eslint-disable-next-line no-restricted-syntax
     const timestamp = Date.now();
 
     // Determine prevAuditCommit

package/src/domain/services/AuditVerifierService.js

@@ -34,6 +34,7 @@ import { decodeAuditMessage } from './AuditMessageCodec.js';
 import { TrustRecordService } from '../trust/TrustRecordService.js';
 import { buildState } from '../trust/TrustStateBuilder.js';
 import { evaluateWriters } from '../trust/TrustEvaluator.js';
+import { TRUST_REASON_CODES } from '../trust/reasonCodes.js';
 
 // ============================================================================
 // Constants
@@ -256,6 +257,7 @@ export class AuditVerifierService {
 
     return {
       graph: graphName,
+      // eslint-disable-next-line no-restricted-syntax -- wall-clock timestamp for audit report
       verifiedAt: new Date().toISOString(),
       summary: { total: chains.length, valid, partial, invalid },
       chains,
@@ -667,7 +669,37 @@ export class AuditVerifierService {
       codec: this._codec,
     });
 
-    const records = await recordService.readRecords(graphName, options.pin ? { tip: options.pin } : {});
+    const recordsResult = await recordService.readRecords(graphName, options.pin ? { tip: options.pin } : {});
+    if (!recordsResult.ok) {
+      return {
+        trustSchemaVersion: 1,
+        mode: 'signed_evidence_v1',
+        trustVerdict: 'fail',
+        trust: {
+          status: 'error',
+          source: options.pin ? 'pinned' : 'ref',
+          sourceDetail: options.pin ?? null,
+          evaluatedWriters: [],
+          untrustedWriters: [],
+          explanations: [
+            {
+              writerId: '*',
+              trusted: false,
+              reasonCode: TRUST_REASON_CODES.TRUST_RECORD_CHAIN_INVALID,
+              reason: `Trust chain read failed: ${recordsResult.error.message}`,
+            },
+          ],
+          evidenceSummary: {
+            recordsScanned: 0,
+            activeKeys: 0,
+            revokedKeys: 0,
+            activeBindings: 0,
+            revokedBindings: 0,
+          },
+        },
+      };
+    }
+    const { records } = recordsResult;
 
     if (records.length === 0) {
       return {
@@ -704,4 +736,3 @@ export class AuditVerifierService {
     return evaluateWriters(writerIds, trustState, policy);
   }
 }
-

package/src/domain/services/BitmapIndexBuilder.js

@@ -22,12 +22,20 @@ const computeChecksum = async (data, crypto) => {
 };
 
 /** @type {boolean|null} Whether native Roaring bindings are available (null = unknown until first use) */
-export let NATIVE_ROARING_AVAILABLE = null;
+let _nativeRoaringAvailable = null;
+
+/**
+ * Resets native Roaring availability detection (test-only utility).
+ * @returns {void}
+ */
+export function resetNativeRoaringFlag() {
+  _nativeRoaringAvailable = null;
+}
 
 const ensureRoaringBitmap32 = () => {
   const RoaringBitmap32 = getRoaringBitmap32();
-  if (NATIVE_ROARING_AVAILABLE === null) {
-    NATIVE_ROARING_AVAILABLE = getNativeRoaringAvailable();
+  if (_nativeRoaringAvailable === null) {
+    _nativeRoaringAvailable = getNativeRoaringAvailable();
   }
   return RoaringBitmap32;
 };
@@ -71,14 +79,11 @@ function serializeFrontierToTree(frontier, tree, codec) {
  * BlobPort + TreePort + RefPort from the persistence layer.
  *
  * **Performance Note**: Uses Roaring Bitmaps for compression. Native bindings
- * provide best performance. Check `NATIVE_ROARING_AVAILABLE` export if
- * performance is critical.
+ * provide best performance. Use `getNativeRoaringAvailable()` from
+ * `src/domain/utils/roaring.js` if runtime capability checks are needed.
  *
  * @example
- * import BitmapIndexBuilder, { NATIVE_ROARING_AVAILABLE } from './BitmapIndexBuilder.js';
- * if (NATIVE_ROARING_AVAILABLE === false) {
- *   console.warn('Consider installing native Roaring bindings for better performance');
- * }
+ * import BitmapIndexBuilder from './BitmapIndexBuilder.js';
  * const builder = new BitmapIndexBuilder();
  */
 export default class BitmapIndexBuilder {

package/src/domain/services/BoundaryTransitionRecord.js

@@ -164,6 +164,7 @@ export async function createBTR(initialState, payload, options) {
     throw new TypeError('payload must be a ProvenancePayload');
   }
 
+  // eslint-disable-next-line no-restricted-syntax -- wall-clock default for BTR timestamp
   const { key, timestamp = new Date().toISOString(), crypto, codec } = options;
 
   // Validate HMAC key is not empty/falsy

package/src/domain/services/CheckpointMessageCodec.js

@@ -5,6 +5,11 @@
  * materialized graph state. See {@link module:domain/services/WarpMessageCodec}
  * for the facade that re-exports all codec functions.
  *
+ * **Schema namespace note:** Checkpoint schema versions (2, 3, 4) are
+ * distinct from patch schema versions (PATCH_SCHEMA_V2, PATCH_SCHEMA_V3).
+ * See {@link module:domain/services/CheckpointService} for named constants
+ * `CHECKPOINT_SCHEMA_STANDARD` and `CHECKPOINT_SCHEMA_INDEX_TREE`.
+ *
  * @module domain/services/CheckpointMessageCodec
  */