@git-stunts/git-warp 12.1.0 → 12.2.1

package/README.md

@@ -8,10 +8,12 @@
   <img src="docs/images/hero.gif" alt="git-warp CLI demo" width="600">
 </p>
 
-## What's New in v12.1.0
+## What's New in v12.2.1
 
-- **Multi-pattern glob support** — `graph.observer()`, `query().match()`, and `translationCost()` now accept an array of glob patterns (e.g. `['campaign:*', 'milestone:*']`). Nodes matching *any* pattern in the array are included (OR semantics).
-- **Release preflight** — `npm run release:preflight` runs a 10-check local gate (version agreement, CHANGELOG, README, lint, types, tests, pack dry-runs) before tagging.
+- **M12 SCALPEL complete** — 42-item STANK audit fully resolved: 15 bug fixes, 20+ JSDoc/documentation improvements, and 6 refactors across CRDT core, services, sync, and CLI.
+- **Sync correctness hardened** — `join()` state install, `applySyncResponse` cache coherence, unknown-op rejection (fail-closed), and divergence pre-check all fixed.
+- **Incremental index improvements** — stale label ID collision fix, re-add edge restoration via adjacency cache, and bitmap churn reduction for node removal.
+- **canonicalStringify shared-reference fix** — cycle detection now correctly allows valid DAG structures (shared non-circular references).
 
 See the [full changelog](CHANGELOG.md) for details.
 
@@ -103,7 +105,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
 
@@ -472,6 +474,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/warp-graph.js

@@ -9,6 +9,13 @@ import { COMMANDS } from './cli/commands/registry.js';
 
 const VIEW_SUPPORTED_COMMANDS = ['info', 'check', 'history', 'path', 'materialize', 'query', 'seek'];
 
+// 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');
+
 /**
  * CLI entry point. Parses arguments, dispatches to the appropriate command handler,
  * and emits the result to stdout (JSON or human-readable).
@@ -78,8 +85,8 @@ main().catch((error) => {
     payload.error.cause = error.cause instanceof Error ? error.cause.message : error.cause;
   }
 
-  if (process.argv.includes('--json') || process.argv.includes('--ndjson')) {
-    const stringify = process.argv.includes('--ndjson') ? compactStringify : stableStringify;
+  if (hasJsonFlag || hasNdjsonFlag) {
+    const stringify = hasNdjsonFlag ? compactStringify : stableStringify;
     process.stdout.write(`${stringify(payload)}\n`);
   } else {
     process.stderr.write(renderError(payload));

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.
@@ -1915,7 +1931,7 @@ export default class WarpGraph {
 
   /** Filtered watcher that only fires for changes matching a glob pattern. */
   watch(
-    pattern: string,
+    pattern: string | string[],
     options: {
       onChange: (diff: StateDiffResult) => void;
       onError?: (error: Error) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-warp",
-  "version": "12.1.0",
+  "version": "12.2.1",
   "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]
  */
@@ -195,6 +195,9 @@ export default class WarpGraph {
 
     /** @type {Record<string, Uint8Array>|null} */
     this._cachedIndexTree = null;
+
+    /** @type {boolean} */
+    this._indexDegraded = false;
   }
 
   /**

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

@@ -221,24 +221,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);
   }
@@ -290,21 +292,50 @@ export function orsetJoin(a, b) {
  *   All replicas are known to have observed at least this causal context.
  */
 export function orsetCompact(set, includedVV) {
+  // Collect deletions in temp arrays to avoid mutation-during-iteration (J8)
+  /** @type {Array<{element: string, dot: string}>} */
+  const toDelete = [];
+
   for (const [element, dots] of set.entries) {
     for (const encodedDot of dots) {
       const dot = decodeDot(encodedDot);
       // Only compact if: (1) dot is tombstoned AND (2) dot <= includedVV
       if (set.tombstones.has(encodedDot) && vvContains(includedVV, dot)) {
-        dots.delete(encodedDot);
-        set.tombstones.delete(encodedDot);
+        toDelete.push({ element, dot: encodedDot });
       }
     }
-    if (dots.size === 0) {
-      set.entries.delete(element);
+  }
+
+  // Apply deletions
+  for (const { element, dot: encodedDot } of toDelete) {
+    const dots = set.entries.get(element);
+    if (dots) {
+      dots.delete(encodedDot);
+      if (dots.size === 0) {
+        set.entries.delete(element);
+      }
     }
+    set.tombstones.delete(encodedDot);
   }
 }
 
+/**
+ * Creates a deep clone of an ORSet.
+ *
+ * @param {ORSet} set - The ORSet to clone
+ * @returns {ORSet} A new ORSet with independent data structures
+ */
+export function orsetClone(set) {
+  const result = createORSet();
+  for (const [element, dots] of set.entries) {
+    result.entries.set(element, new Set(dots));
+  }
+  for (const dot of set.tombstones) {
+    result.tombstones.add(dot);
+  }
+  return result;
+}
+
 /**
  * Serializes an ORSet to a plain object for CBOR encoding.
  * Entries are sorted by element (stringified), dots within entries are sorted.
@@ -314,16 +345,19 @@ export function orsetCompact(set, includedVV) {
  * @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)
@@ -333,12 +367,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/SyncError.js

@@ -14,6 +14,7 @@ import WarpError from './WarpError.js';
  * | `E_SYNC_TIMEOUT` | Sync request exceeded timeout |
  * | `E_SYNC_REMOTE` | Remote server returned a 5xx error |
  * | `E_SYNC_PROTOCOL` | Protocol violation: 4xx, invalid JSON, or malformed response |
+ * | `E_SYNC_PAYLOAD_INVALID` | Sync payload failed shape/resource-limit validation (B64) |
  * | `SYNC_ERROR` | Generic/default sync error |
  *
  * @class SyncError

package/src/domain/errors/TrustError.js

@@ -9,6 +9,8 @@ import WarpError from './WarpError.js';
  * |------|-------------|
  * | `E_TRUST_UNSUPPORTED_ALGORITHM` | Algorithm is not `ed25519` |
  * | `E_TRUST_INVALID_KEY` | Public key is malformed (wrong length or bad base64) |
+ * | `E_TRUST_CAS_CONFLICT` | Concurrent append advanced the trust chain; caller must rebuild + re-sign |
+ * | `E_TRUST_CAS_EXHAUSTED` | CAS retry budget exhausted (transient failures) |
  * | `TRUST_ERROR` | Generic/default trust error |
  *
  * @class TrustError

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/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
@@ -667,7 +668,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 +735,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 {