@git-stunts/git-warp 10.8.0 → 11.3.3

package/src/domain/services/SyncProtocol.js

@@ -42,6 +42,16 @@ import { join, cloneStateV5 } from './JoinReducer.js';
 import { cloneFrontier, updateFrontier } from './Frontier.js';
 import { vvDeserialize } from '../crdt/VersionVector.js';
 
+/**
+ * A decoded patch object after CBOR deserialization.
+ * @typedef {Object} DecodedPatch
+ * @property {Object | Map<string, number>} [context] - VersionVector (Map after normalization, plain object before)
+ * @property {import('../types/WarpTypesV2.js').OpV2[]} ops - Ordered array of operations
+ * @property {string} [writer] - Writer ID
+ * @property {number} [lamport] - Lamport timestamp
+ * @property {number} [schema] - Schema version
+ */
+
 // -----------------------------------------------------------------------------
 // Patch Loading
 // -----------------------------------------------------------------------------
@@ -56,9 +66,9 @@ import { vvDeserialize } from '../crdt/VersionVector.js';
  * **Mutation**: This function mutates the input patch object for efficiency.
  * The original object reference is returned.
  *
- * @param {{ context?: Object | Map<any, any>, ops: any[] }} patch - The raw decoded patch from CBOR.
+ * @param {DecodedPatch} patch - The raw decoded patch from CBOR.
  *   If context is present as a plain object, it will be converted to a Map.
- * @returns {{ context?: Object | Map<any, any>, ops: any[] }} The same patch object with context converted to Map
+ * @returns {DecodedPatch} The same patch object with context converted to Map
  * @private
  */
 function normalizePatch(patch) {
@@ -88,7 +98,7 @@ function normalizePatch(patch) {
  * @param {string} sha - The 40-character commit SHA to load the patch from
  * @param {Object} [options]
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
- * @returns {Promise<{ context?: Object | Map<any, any>, ops: any[] }>} The decoded and normalized patch object containing:
+ * @returns {Promise<DecodedPatch>} The decoded and normalized patch object containing:
  *   - `ops`: Array of patch operations
  *   - `context`: VersionVector (Map) of causal dependencies
  *   - `writerId`: The writer who created this patch
@@ -99,7 +109,7 @@ function normalizePatch(patch) {
  * @throws {Error} If the patch blob cannot be CBOR-decoded (corrupted data)
  * @private
  */
-async function loadPatchFromCommit(persistence, sha, { codec: codecOpt } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+async function loadPatchFromCommit(persistence, sha, { codec: codecOpt } = /** @type {{ codec?: import('../../ports/CodecPort.js').default }} */ ({})) {
   const codec = codecOpt || defaultCodec;
   // Read commit message to extract patch OID
   const message = await persistence.showNode(sha);
@@ -107,7 +117,7 @@ async function loadPatchFromCommit(persistence, sha, { codec: codecOpt } = /** @
 
   // Read and decode the patch blob
   const patchBuffer = await persistence.readBlob(decoded.patchOid);
-  const patch = /** @type {{ context?: Object | Map<any, any>, ops: any[] }} */ (codec.decode(patchBuffer));
+  const patch = /** @type {DecodedPatch} */ (codec.decode(patchBuffer));
 
   // Normalize the patch (convert context from object to Map)
   return normalizePatch(patch);
@@ -134,7 +144,9 @@ async function loadPatchFromCommit(persistence, sha, { codec: codecOpt } = /** @
  * @param {string|null} fromSha - Start SHA (exclusive). Pass null to load ALL patches
  *   for this writer from the beginning of their chain.
  * @param {string} toSha - End SHA (inclusive). This is typically the writer's current tip.
- * @returns {Promise<Array<{patch: Object, sha: string}>>} Array of patch objects in
+ * @param {Object} [options]
+ * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
+ * @returns {Promise<Array<{patch: DecodedPatch, sha: string}>>} Array of patch objects in
  *   chronological order (oldest first). Each entry contains:
  *   - `patch`: The decoded patch object
  *   - `sha`: The commit SHA this patch came from
@@ -152,7 +164,7 @@ async function loadPatchFromCommit(persistence, sha, { codec: codecOpt } = /** @
  * // Load ALL patches for a new writer
  * const patches = await loadPatchRange(persistence, 'events', 'new-writer', null, tipSha);
  */
-export async function loadPatchRange(persistence, graphName, writerId, fromSha, toSha, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+export async function loadPatchRange(persistence, graphName, writerId, fromSha, toSha, { codec } = /** @type {{ codec?: import('../../ports/CodecPort.js').default }} */ ({})) {
   const patches = [];
   let cur = toSha;
 
@@ -298,7 +310,7 @@ export function computeSyncDelta(localFrontier, remoteFrontier) {
  * @property {'sync-response'} type - Message type discriminator for protocol parsing
  * @property {Object.<string, string>} frontier - Responder's frontier as a plain object.
  *   Keys are writer IDs, values are SHAs.
- * @property {Array<{writerId: string, sha: string, patch: Object}>} patches - Patches
+ * @property {Array<{writerId: string, sha: string, patch: DecodedPatch}>} patches - Patches
  *   the requester needs, in chronological order per writer. Contains:
  *   - `writerId`: The writer who created this patch
  *   - `sha`: The commit SHA this patch came from (for frontier updates)
@@ -361,6 +373,8 @@ export function createSyncRequest(frontier) {
  * @param {import('../../ports/GraphPersistencePort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default} persistence - Git persistence
  *   layer for loading patches (uses CommitPort + BlobPort methods)
  * @param {string} graphName - Graph name for error messages and logging
+ * @param {Object} [options]
+ * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
  * @returns {Promise<SyncResponse>} Response containing local frontier and patches.
  *   Patches are ordered chronologically within each writer.
  * @throws {Error} If patch loading fails for reasons other than divergence
@@ -374,7 +388,7 @@ export function createSyncRequest(frontier) {
  *   res.json(response);
  * });
  */
-export async function processSyncRequest(request, localFrontier, persistence, graphName, { codec } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+export async function processSyncRequest(request, localFrontier, persistence, graphName, { codec } = /** @type {{ codec?: import('../../ports/CodecPort.js').default }} */ ({})) {
   // Convert incoming frontier from object to Map
   const remoteFrontier = new Map(Object.entries(request.frontier));
 
@@ -401,7 +415,7 @@ export async function processSyncRequest(request, localFrontier, persistence, gr
     } catch (err) {
       // If we detect divergence, skip this writer
       // The requester may need to handle this separately
-      if (/** @type {any} */ (err).code === 'E_SYNC_DIVERGENCE' || /** @type {any} */ (err).message?.includes('Divergence detected')) { // TODO(ts-cleanup): type error
+      if ((err instanceof Error && 'code' in err && /** @type {{ code: string }} */ (err).code === 'E_SYNC_DIVERGENCE') || (err instanceof Error && err.message?.includes('Divergence detected'))) {
         continue;
       }
       throw err;
@@ -491,7 +505,7 @@ export function applySyncResponse(response, state, frontier) {
       // will prevent silent data loss until the reader is upgraded.
       assertOpsCompatible(normalizedPatch.ops, SCHEMA_V3);
       // Apply patch to state
-      join(newState, /** @type {*} */ (normalizedPatch), sha); // TODO(ts-cleanup): type patch array
+      join(newState, /** @type {Parameters<typeof join>[1]} */ (normalizedPatch), sha);
       applied++;
     }
 

package/src/domain/services/TemporalQuery.js

@@ -36,13 +36,16 @@ import { orsetContains } from '../crdt/ORSet.js';
  * InlineValue objects `{ type: 'inline', value: ... }` are unwrapped
  * to their inner value. All other values pass through unchanged.
  *
- * @param {*} value - Property value (potentially InlineValue-wrapped)
- * @returns {*} The unwrapped value
+ * @param {unknown} value - Property value (potentially InlineValue-wrapped)
+ * @returns {unknown} The unwrapped value
  * @private
  */
 function unwrapValue(value) {
-  if (value && typeof value === 'object' && value.type === 'inline') {
-    return value.value;
+  if (value && typeof value === 'object' && 'type' in value) {
+    const rec = /** @type {Record<string, unknown>} */ (value);
+    if (rec.type === 'inline') {
+      return rec.value;
+    }
   }
   return value;
 }
@@ -60,11 +63,11 @@ function unwrapValue(value) {
  *
  * @param {import('./JoinReducer.js').WarpStateV5} state - Current state
  * @param {string} nodeId - Node ID to extract
- * @returns {{ id: string, exists: boolean, props: Record<string, *> }}
+ * @returns {{ id: string, exists: boolean, props: Record<string, unknown> }}
  */
 function extractNodeSnapshot(state, nodeId) {
   const exists = orsetContains(state.nodeAlive, nodeId);
-  /** @type {Record<string, *>} */
+  /** @type {Record<string, unknown>} */
   const props = {};
 
   if (exists) {

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/WarpMessageCodec.js

@@ -2,16 +2,18 @@
  * WARP Message Codec — facade re-exporting all message encoding, decoding,
  * and schema utilities.
  *
- * This module provides backward-compatible access to the three types of
+ * This module provides backward-compatible access to the four types of
  * WARP (Write-Ahead Reference Protocol) commit messages:
  * - Patch: Contains graph mutations from a single writer
  * - Checkpoint: Contains a snapshot of materialized graph state
  * - Anchor: Marks a merge point in the WARP DAG
+ * - Audit: Records tamper-evident audit receipts for data commits
  *
  * Implementation is split across focused sub-modules:
  * - {@link module:domain/services/PatchMessageCodec}
  * - {@link module:domain/services/CheckpointMessageCodec}
  * - {@link module:domain/services/AnchorMessageCodec}
+ * - {@link module:domain/services/AuditMessageCodec}
  * - {@link module:domain/services/MessageSchemaDetector}
  *
  * @module domain/services/WarpMessageCodec
@@ -20,6 +22,7 @@
 export { encodePatchMessage, decodePatchMessage } from './PatchMessageCodec.js';
 export { encodeCheckpointMessage, decodeCheckpointMessage } from './CheckpointMessageCodec.js';
 export { encodeAnchorMessage, decodeAnchorMessage } from './AnchorMessageCodec.js';
+export { encodeAuditMessage, decodeAuditMessage } from './AuditMessageCodec.js';
 export {
   detectSchemaVersion,
   detectMessageKind,

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

@@ -0,0 +1,42 @@
+/**
+ * SHA-256 hashing layer on top of canonical.js string payloads.
+ *
+ * Computes record IDs (content-addressed hex digests) and
+ * signature payloads (raw UTF-8 bytes) for trust records.
+ *
+ * @module domain/trust/TrustCanonical
+ * @see docs/specs/TRUST_V1_CRYPTO.md
+ */
+
+import { createHash } from 'node:crypto';
+import { recordIdPayload, signaturePayload } from './canonical.js';
+
+/**
+ * Computes the record ID (SHA-256 hex digest) for a trust record.
+ *
+ * @param {Record<string, unknown>} record - Full trust record
+ * @returns {string} 64-character lowercase hex string
+ */
+export function computeRecordId(record) {
+  return createHash('sha256').update(recordIdPayload(record)).digest('hex');
+}
+
+/**
+ * Computes the signature payload as a Buffer (UTF-8 bytes).
+ *
+ * @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) {
+  return Buffer.from(signaturePayload(record), 'utf8');
+}
+
+/**
+ * Verifies that a record's recordId matches its content.
+ *
+ * @param {Record<string, unknown>} record - Trust record with `recordId` field
+ * @returns {boolean} true if recordId matches computed value
+ */
+export function verifyRecordId(record) {
+  return record.recordId === computeRecordId(record);
+}

package/src/domain/trust/TrustCrypto.js

@@ -0,0 +1,111 @@
+/**
+ * Ed25519 cryptographic operations for trust records.
+ *
+ * Uses `node:crypto` directly — Ed25519 is trust-specific and does not
+ * belong on the general CryptoPort hash/hmac interface.
+ *
+ * @module domain/trust/TrustCrypto
+ * @see docs/specs/TRUST_V1_CRYPTO.md
+ */
+
+import { createHash, createPublicKey, verify } from 'node:crypto';
+import TrustError from '../errors/TrustError.js';
+
+/** Algorithms supported by this module. */
+export const SUPPORTED_ALGORITHMS = new Set(['ed25519']);
+
+const ED25519_PUBLIC_KEY_LENGTH = 32;
+
+/**
+ * Decodes a base64-encoded Ed25519 public key and validates its length.
+ *
+ * @param {string} base64 - Base64-encoded raw public key bytes
+ * @returns {Buffer} 32-byte raw key
+ * @throws {TrustError} E_TRUST_INVALID_KEY if base64 is malformed or wrong length
+ */
+function decodePublicKey(base64) {
+  /** @type {Buffer} */
+  let raw;
+  try {
+    raw = Buffer.from(base64, 'base64');
+  } catch {
+    throw new TrustError('Malformed base64 in public key', {
+      code: 'E_TRUST_INVALID_KEY',
+    });
+  }
+
+  // Buffer.from with 'base64' never throws on bad input — it silently
+  // produces an empty or truncated buffer. Validate that the round-trip
+  // matches to detect garbage input.
+  if (raw.toString('base64') !== base64) {
+    throw new TrustError('Malformed base64 in public key', {
+      code: 'E_TRUST_INVALID_KEY',
+    });
+  }
+
+  if (raw.length !== ED25519_PUBLIC_KEY_LENGTH) {
+    throw new TrustError(
+      `Ed25519 public key must be ${ED25519_PUBLIC_KEY_LENGTH} bytes, got ${raw.length}`,
+      { code: 'E_TRUST_INVALID_KEY' },
+    );
+  }
+
+  return raw;
+}
+
+/**
+ * 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
+ * @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
+ */
+export function verifySignature({
+  algorithm,
+  publicKeyBase64,
+  signatureBase64,
+  payload,
+}) {
+  if (!SUPPORTED_ALGORITHMS.has(algorithm)) {
+    throw new TrustError(`Unsupported algorithm: ${algorithm}`, {
+      code: 'E_TRUST_UNSUPPORTED_ALGORITHM',
+      context: { algorithm },
+    });
+  }
+
+  const raw = decodePublicKey(publicKeyBase64);
+
+  const keyObject = createPublicKey({
+    key: Buffer.concat([
+      // DER prefix for Ed25519 public key (RFC 8410)
+      Buffer.from('302a300506032b6570032100', 'hex'),
+      raw,
+    ]),
+    format: 'der',
+    type: 'spki',
+  });
+
+  const sig = Buffer.from(signatureBase64, 'base64');
+
+  return verify(null, payload, keyObject, sig);
+}
+
+/**
+ * Computes the key fingerprint for an Ed25519 public key.
+ *
+ * Format: `"ed25519:" + sha256_hex(rawBytes)`
+ *
+ * @param {string} publicKeyBase64 - Base64-encoded 32-byte public key
+ * @returns {string} Fingerprint string, e.g. "ed25519:abcd1234..."
+ * @throws {TrustError} E_TRUST_INVALID_KEY for malformed key
+ */
+export function computeKeyFingerprint(publicKeyBase64) {
+  const raw = decodePublicKey(publicKeyBase64);
+  const hash = createHash('sha256').update(raw).digest('hex');
+  return `ed25519:${hash}`;
+}

package/src/domain/trust/TrustEvaluator.js

@@ -0,0 +1,195 @@
+/**
+ * Trust V1 evaluator.
+ *
+ * Pure function that evaluates writer trust status against a built
+ * trust state and policy configuration. No I/O, no side effects.
+ *
+ * @module domain/trust/TrustEvaluator
+ * @see docs/specs/TRUST_V1_CRYPTO.md Section 12
+ */
+
+import { TrustPolicySchema } from './schemas.js';
+import { TRUST_REASON_CODES } from './reasonCodes.js';
+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.
+ *
+ * For each writer (sorted deterministically), checks:
+ * 1. Whether any active binding exists for that writer
+ * 2. Whether the bound key is still active (not revoked)
+ *
+ * @param {string[]} writerIds - Writer IDs to evaluate
+ * @param {TrustState} trustState - Built trust state from TrustStateBuilder
+ * @param {Record<string, unknown>} policy - Trust policy configuration
+ * @returns {TrustAssessment} Frozen TrustAssessment object
+ */
+export function evaluateWriters(writerIds, trustState, policy) {
+  const policyResult = TrustPolicySchema.safeParse(policy);
+  if (!policyResult.success) {
+    return buildErrorAssessment(writerIds, TRUST_REASON_CODES.TRUST_POLICY_INVALID);
+  }
+
+  const sortedWriters = [...writerIds].sort();
+  const explanations = sortedWriters.map((writerId) =>
+    evaluateSingleWriter(writerId, trustState),
+  );
+
+  const untrustedWriters = explanations
+    .filter((e) => !e.trusted)
+    .map((e) => e.writerId);
+
+  const trust = {
+    status: /** @type {'configured'|'pinned'|'error'|'not_configured'} */ ('configured'),
+    source: 'ref',
+    sourceDetail: null,
+    evaluatedWriters: sortedWriters,
+    untrustedWriters,
+    explanations: explanations.map((e) => Object.freeze(e)),
+    evidenceSummary: buildEvidenceSummary(trustState),
+  };
+
+  const trustVerdict = deriveTrustVerdict(trust);
+
+  return Object.freeze({
+    trustSchemaVersion: 1,
+    mode: 'signed_evidence_v1',
+    trustVerdict,
+    trust: Object.freeze(trust),
+  });
+}
+
+/**
+ * Evaluates trust for a single writer.
+ *
+ * @param {string} writerId
+ * @param {TrustState} trustState
+ * @returns {{writerId: string, trusted: boolean, reasonCode: string, reason: string}}
+ */
+function evaluateSingleWriter(writerId, trustState) {
+  // Check all bindings for this writer
+  const activeBindingKeys = [];
+  for (const [bindingKey, binding] of trustState.writerBindings) {
+    if (bindingKey.startsWith(`${writerId}\0`)) {
+      activeBindingKeys.push({ bindingKey, keyId: binding.keyId });
+    }
+  }
+
+  // Check revoked bindings too (for reason code accuracy)
+  let hasRevokedBinding = false;
+  for (const bindingKey of trustState.revokedBindings.keys()) {
+    if (bindingKey.startsWith(`${writerId}\0`)) {
+      hasRevokedBinding = true;
+    }
+  }
+
+  if (activeBindingKeys.length === 0) {
+    if (hasRevokedBinding) {
+      return {
+        writerId,
+        trusted: false,
+        reasonCode: TRUST_REASON_CODES.BINDING_REVOKED,
+        reason: `Writer '${writerId}' has no active bindings (all revoked)`,
+      };
+    }
+    return {
+      writerId,
+      trusted: false,
+      reasonCode: TRUST_REASON_CODES.WRITER_HAS_NO_ACTIVE_BINDING,
+      reason: `Writer '${writerId}' has no active bindings`,
+    };
+  }
+
+  // Check if any active binding points to an active key
+  for (const { keyId } of activeBindingKeys) {
+    if (trustState.activeKeys.has(keyId)) {
+      return {
+        writerId,
+        trusted: true,
+        reasonCode: TRUST_REASON_CODES.WRITER_BOUND_TO_ACTIVE_KEY,
+        reason: `Writer '${writerId}' is bound to active key ${keyId}`,
+      };
+    }
+  }
+
+  // All bindings point to revoked keys
+  return {
+    writerId,
+    trusted: false,
+    reasonCode: TRUST_REASON_CODES.WRITER_BOUND_KEY_REVOKED,
+    reason: `Writer '${writerId}' is bound only to revoked keys`,
+  };
+}
+
+/**
+ * Builds an error assessment when policy validation fails.
+ *
+ * @param {string[]} writerIds
+ * @param {string} reasonCode
+ * @returns {TrustAssessment}
+ */
+function buildErrorAssessment(writerIds, reasonCode) {
+  const sortedWriters = [...writerIds].sort();
+  const trust = {
+    status: /** @type {'configured'|'pinned'|'error'|'not_configured'} */ ('error'),
+    source: 'none',
+    sourceDetail: null,
+    evaluatedWriters: sortedWriters,
+    untrustedWriters: sortedWriters,
+    explanations: sortedWriters.map((writerId) => Object.freeze({
+      writerId,
+      trusted: false,
+      reasonCode,
+      reason: `Policy validation failed: ${reasonCode}`,
+    })),
+    evidenceSummary: {
+      recordsScanned: 0,
+      activeKeys: 0,
+      revokedKeys: 0,
+      activeBindings: 0,
+      revokedBindings: 0,
+    },
+  };
+
+  return Object.freeze({
+    trustSchemaVersion: 1,
+    mode: 'signed_evidence_v1',
+    trustVerdict: deriveTrustVerdict(trust),
+    trust: Object.freeze(trust),
+  });
+}
+
+/**
+ * Builds the evidence summary from trust state.
+ *
+ * @param {TrustState} trustState
+ * @returns {{recordsScanned: number, activeKeys: number, revokedKeys: number, activeBindings: number, revokedBindings: number}}
+ */
+function buildEvidenceSummary(trustState) {
+  return Object.freeze({
+    recordsScanned: trustState.recordsProcessed,
+    activeKeys: trustState.activeKeys.size,
+    revokedKeys: trustState.revokedKeys.size,
+    activeBindings: trustState.writerBindings.size,
+    revokedBindings: trustState.revokedBindings.size,
+  });
+}