@codebam/dsh-thinking-auditor 0.1.0

package/src/claims.mjs

@@ -0,0 +1,520 @@
+/**
+ * Deterministic claim extraction and claim-vs-evidence verification.
+ *
+ * This module is the high-precision half of the auditor. It never asks a model
+ * to judge what a ledger join can settle:
+ *
+ * - a claim about having run a command with no matching tool call in the turn
+ *   is an unsupported action claim;
+ * - a claim of success contradicted by the paired result's failure markers is
+ *   a contradiction;
+ * - a quoted file/output excerpt absent from every evidence source is an
+ *   unsupported quotation.
+ *
+ * It is deliberately conservative. Hedged language, plans, hypotheses, and
+ * values that may legitimately come from the model's own knowledge are marked
+ * speculative or low severity, never "lying". Status is a claim-evidence
+ * relation, not intent.
+ *
+ * Pure module: no dsh imports.
+ *
+ * @module @codebam/dsh-thinking-auditor/claims
+ */
+
+import { severityAtLeast } from './config.mjs'
+
+const TOOL_VERBS = Object.freeze([
+  'ran', 'run', 'executed', 'launched', 'checked', 'examined', 'inspected',
+  'verified', 'confirmed', 'tested', 'read', 'opened', 'searched', 'grepped',
+  'listed', 'reviewed', 'wrote', 'created', 'edited', 'modified', 'built',
+  'installed', 'removed', 'deleted', 'fetched', 'downloaded', 'queried',
+  'walked', 'scanned', 'parsed', 'measured', 'benchmarked', 'deployed',
+])
+
+const ACTION_RE = new RegExp(
+  String.raw`\b(?:i|we)(?:'ve| have| had)?\s+(?:already\s+|just\s+|then\s+|also\s+)*(${TOOL_VERBS.join('|')})\b([^]{0,180})`,
+  'gi',
+)
+
+const STATUS_RE = /\b(?:all\s+)?(?:the\s+)?(?:\d+\s+)?(tests?|test suite|checks?|build|compile|lint|typecheck|suite)\s+(?:all\s+)?(?:pass(?:ed|es|ing)?|succeed(?:ed|s)?|fail(?:ed|s)?|green|clean|works?|worked|broke(?:n)?)/gi
+
+const ASSERTION_RE = /\b(the\s+)?(file|output|result|log|error|command|test|script|code|directory|docs?|config|source)\b([^]{0,100}?)\b(shows?|says?|reports?|returns?|contains?|reads?|equals?|is|has)\b/gi
+
+const HEDGE_RE = /(?:\bi\s*(?:'ll| will|'m going to)\b|\b(?:would|should|could|may|might|probably|likely|perhaps|maybe|possibly|presumably|appears?|seems?|i think|i believe|expect|expected|hope|assume|assuming|if|unless|suppose|hypothetically|going to|gonna|plan to|intend to|need to|let me)\b)/i
+const UNIVERSAL_RE = /\b(?:all|every|none|never|always|guaranteed|definitely|certainly|proven|100%)\b/i
+const SUCCESS_RE = /\b(?:pass(?:ed|es|ing)?|succeed(?:ed|s)?|success(?:ful(?:ly)?)?|green|clean|works?|worked|verified|confirmed|ok|correct|complete(?:d)?)\b/i
+const FAILURE_WORD_RE = /\b(?:fail(?:ed|s|ing)?|failure|error(?:s|ed)?|broken|broke(?:n)?|crash(?:ed)?|missing|not\s+work(?:ing)?|does\s+not\s+work)\b/i
+
+const TEST_COMMAND_RE = /\b(?:pytest|py\.test|jest|vitest|mocha|ava|npm\s+(?:run\s+)?test|pnpm\s+(?:run\s+)?test|yarn\s+test|bun\s+test|go\s+test|cargo\s+test|ctest|make\s+test|dotnet\s+test|mvn\s+test|gradle\s+test|rspec|phpunit|busted)\b/i
+const BUILD_COMMAND_RE = /\b(?:npm\s+run\s+build|pnpm\s+(?:run\s+)?build|yarn\s+build|bun\s+run\s+build|make\b|cargo\s+build|go\s+build|nix\s+build|tsc\b|vite\s+build|webpack|rollup|esbuild|dotnet\s+build|mvn\s+(?:package|install)|gradle\s+build)\b/i
+const LINT_COMMAND_RE = /\b(?:eslint|biome|prettier|ruff|flake8|pylint|mypy|pyright|tsc\s+--noEmit|golangci-lint|clippy|cargo\s+clippy|shellcheck|hadolint)\b/i
+const READ_TOOL_RE = /\b(?:read|read_file|fs_read|cat|view|open|show|head|tail|bat)\b/i
+const WRITE_TOOL_RE = /\b(?:write|write_file|edit|edit_file|str_replace|replace|apply_patch|create|mkdir|touch|save)\b/i
+const EXEC_TOOL_RE = /\b(?:bash|shell|exec|run|nu|pwsh|powershell|terminal|command|process|subprocess)\b/i
+
+const FILE_EXTENSIONS = 'mjs|js|cjs|mts|cts|ts|tsx|jsx|json|ya?ml|toml|md|nix|py|go|rs|rb|java|c|h|cpp|hpp|cs|php|swift|kt|css|scss|html|sql|sh|bash|zsh|fish|lock|env|ini|cfg|conf'
+const PATH_RE = new RegExp(
+  String.raw`(?:^|[\s` + '`' + String.raw`"'(])((?:[A-Za-z]:)?(?:\.\.?\/)?(?:[\w.@+-]+\/)+[\w.@+-]+\.(?:${FILE_EXTENSIONS}))(?=$|[\s` + '`' + String.raw`"'),:.])`,
+  'gi',
+)
+const BARE_FILE_RE = new RegExp(String.raw`\b[\w@+-]+\.(?:${FILE_EXTENSIONS})\b`, 'gi')
+const URL_RE = /\bhttps?:\/\/[^\s"'`<>)]+/gi
+const VERSION_RE = /\bv?\d+\.\d+(?:\.\d+)?(?:-[A-Za-z0-9.]+)?\b/g
+const QUANTITY_RE = /\b(\d+(?:\.\d+)?)\s*(tests?|files?|lines?|bytes?|tokens?|ms|milliseconds?|seconds?|minutes?|rows?|items?|errors?|warnings?|chars?|characters?|accounts?|results?|records?|files?|cases?)\b/gi
+const QUOTE_RE = /`([^`\n]{3,240})`|"([^"\n]{3,240})"/g
+const STOP_WORDS = new Set([
+  'about', 'after', 'again', 'against', 'already', 'also', 'because', 'been', 'before',
+  'being', 'between', 'both', 'cannot', 'could', 'does', 'doing', 'done', 'each', 'from',
+  'further', 'have', 'having', 'here', 'into', 'itself', 'just', 'more', 'most', 'only',
+  'other', 'over', 'same', 'should', 'some', 'such', 'than', 'that', 'their', 'them',
+  'then', 'there', 'these', 'they', 'this', 'those', 'through', 'under', 'until', 'very',
+  'were', 'what', 'when', 'where', 'which', 'while', 'with', 'would', 'your', 'yours',
+  'will', 'probably', 'likely', 'maybe', 'perhaps', 'possibly', 'definitely', 'certainly',
+  'always', 'never', 'every', 'guaranteed', 'proven',
+])
+
+/** True when a quoted token is a file path rather than a content excerpt. */
+export function looksLikePath(value) {
+  const text = String(value ?? '').trim()
+  if (text.length === 0) return false
+  const pathRe = new RegExp(String.raw`^(?:[A-Za-z]:)?(?:\.\.?\/)?(?:[\w.@+-]+\/)+[\w.@+-]+\.(?:${FILE_EXTENSIONS})$`, 'i')
+  const bareRe = new RegExp(String.raw`^[\w@+-]+\.(?:${FILE_EXTENSIONS})$`, 'i')
+  return pathRe.test(text) || bareRe.test(text)
+}
+
+/** Split a reasoning window into sentence-ish units without a lookbehind regex. */
+export function splitSentences(text) {
+  const value = String(text ?? '')
+  const parts = []
+  let start = 0
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index]
+    const next = value[index + 1]
+    if (char === '\n' || (['.', '!', '?'].includes(char) && (next === undefined || /\s/.test(next)))) {
+      const part = value.slice(start, index + 1).trim()
+      if (part.length > 0) parts.push(part)
+      start = index + 1
+    }
+  }
+  const tail = value.slice(start).trim()
+  if (tail.length > 0) parts.push(tail)
+  return parts
+}
+
+/** Cap one string deterministically. */
+function truncate(value, max) {
+  const text = String(value ?? '')
+  return text.length <= max ? text : `${text.slice(0, max - 1)}…`
+}
+
+/** Deduplicate anchors by kind and normalized value. */
+function dedupeAnchors(anchors) {
+  const seen = new Set()
+  const out = []
+  for (const anchor of anchors) {
+    const key = `${anchor.kind}:${anchor.normalized}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(anchor)
+  }
+  return out
+}
+
+/** Extract searchable anchors from one sentence. */
+export function extractAnchors(sentence) {
+  const anchors = []
+  const push = (kind, value) => {
+    const text = String(value ?? '').trim()
+    if (text.length < 2) return
+    anchors.push({ kind, value: text, normalized: text.toLowerCase().replace(/\s+/g, ' ') })
+  }
+
+  for (const match of sentence.matchAll(QUOTE_RE)) {
+    const quoted = String(match[1] ?? match[2] ?? '').trim()
+    // A quoted path/URL is a reference to a source, not a quoted claim.
+    if (looksLikePath(quoted)) push('path', quoted)
+    else if (/^https?:\/\//i.test(quoted)) push('url', quoted)
+    else push('quote', quoted)
+  }
+  for (const match of sentence.matchAll(PATH_RE)) push('path', match[1])
+  for (const match of sentence.matchAll(BARE_FILE_RE)) push('path', match[0])
+  if (/\burl|link|endpoint|api\b/i.test(sentence)) {
+    for (const match of sentence.matchAll(URL_RE)) push('url', match[0].replace(/[.),:]+$/, ''))
+  }
+  if (/\bversion|v\d/i.test(sentence)) {
+    for (const match of sentence.matchAll(VERSION_RE)) push('version', match[0])
+  }
+  for (const match of sentence.matchAll(QUANTITY_RE)) push('quantity', match[0])
+
+  // Distinctive content words after action/status verbs. These anchor a claim
+  // to a plausible tool call even when the trace paraphrases the output.
+  const words = String(sentence ?? '')
+    .toLowerCase()
+    .split(/[^a-z0-9_.@/-]+/i)
+    .filter((word) => word.length >= 4 && !STOP_WORDS.has(word) && !/^\d+$/.test(word))
+  for (const word of words.slice(0, 8)) push('term', word)
+
+  return dedupeAnchors(anchors)
+}
+
+/** Irregular past forms of tool verbs that assert an observed action. */
+const PAST_IRREGULAR_RE = /^(?:ran|read|wrote|built|made|found|saw|got|took|sent|left|put|kept|held|met|paid|said|told|thought|knew|grew|drew|threw|chose|brought|caught|taught|understood|won|began|was|were)$/i
+
+/** True when a recognized action verb reads as a completed observation. */
+function verbReadsAsPast(verb) {
+  const value = String(verb ?? '').toLowerCase()
+  return value.endsWith('ed') || PAST_IRREGULAR_RE.test(value)
+}
+
+/** Map a claim sentence to the tool class whose output would support it. */
+export function classifyToolClass(sentence, detail, anchors, kind) {
+  const value = String(sentence ?? '').replace(URL_RE, ' ')
+  const rest = String(detail ?? '').replace(URL_RE, ' ')
+  const combined = `${value} ${rest}`
+  if (kind === 'hedged' || kind === 'universal') return null
+  if (/\b(tests?|test suite|suite|pytest|jest|vitest|rspec|phpunit|mocha|ava)\b/i.test(combined)) return 'test'
+  if (/\b(build|compile|bundle|package)\b/i.test(combined)) return 'build'
+  if (/\b(lint|typecheck|type-check|static analysis|format(?:ting)? check)\b/i.test(combined)) return 'lint'
+  if (/\b(wrote|created|edited|modified|patched|saved|deleted|removed)\b/i.test(rest)) return 'write'
+  if (/\b(read|opened|cat|viewed|inspected|examined|looked at)\b/i.test(rest) || anchors.some((anchor) => anchor.kind === 'path')) return 'read'
+  if (/\b(ran|executed|launched|tested|checked|verified|confirmed|searched|grepped|queried|fetched|downloaded)\b/i.test(rest)) return 'exec'
+  return null
+}
+
+/** True when a tool call's command/arguments match one tool class. */
+export function callMatchesClass(call, toolClass) {
+  const haystack = `${call.name ?? ''}\n${call.argsRaw ?? ''}\n${call.resultText ?? ''}`
+  switch (toolClass) {
+    case 'test':
+      return TEST_COMMAND_RE.test(haystack)
+    case 'build':
+      return BUILD_COMMAND_RE.test(haystack)
+    case 'lint':
+      return LINT_COMMAND_RE.test(haystack)
+    case 'read':
+      return READ_TOOL_RE.test(call.name ?? '') || /(?:read|cat|view|open|show|head|tail)/i.test(call.argsRaw ?? '')
+    case 'write':
+      return WRITE_TOOL_RE.test(call.name ?? '')
+    case 'exec':
+      return EXEC_TOOL_RE.test(call.name ?? '') || /(?:bash|sh|nu|pwsh|node|python|nix|npm|pnpm|yarn|git|make|cargo|go|pytest|jest)/i.test(call.argsRaw ?? '')
+    default:
+      return false
+  }
+}
+
+/** True when the claim's anchors select a specific call. */
+function callMatchesAnchors(call, anchors) {
+  const haystack = `${call.name ?? ''} ${call.argsRaw ?? ''} ${call.resultText ?? ''}`.toLowerCase()
+  return anchors.some((anchor) => anchor.kind !== 'term' && haystack.includes(anchor.normalized))
+}
+
+/** Find the most plausible call for a claim: exact anchor match first, then class. */
+function selectCall(claim, calls) {
+  const withAnchors = calls.filter((call) => callMatchesAnchors(call, claim.anchors))
+  if (withAnchors.length > 0) return withAnchors[withAnchors.length - 1]
+  if (claim.toolClass !== null) {
+    const byClass = calls.filter((call) => callMatchesClass(call, claim.toolClass))
+    if (byClass.length > 0) return byClass[byClass.length - 1]
+  }
+  return undefined
+}
+
+/** True when a call's rendered output asserts success for one tool class. */
+function callShowsSuccess(call, toolClass) {
+  if (call.failed) return false
+  const text = String(call.resultText ?? '')
+  if (/\b(?:FAILED|ERROR|Traceback|failed|failing)\b/.test(text)) return false
+  if (toolClass === 'test') return /\b(?:passed|passing|ok\b|\d+\s+passed|all tests passed)\b/i.test(text)
+  return true
+}
+
+/** True when a call's rendered output asserts failure for one tool class. */
+function callShowsFailure(call) {
+  if (call.failed) return true
+  const text = String(call.resultText ?? '')
+  return /\b(?:failed|failing|FAILED|ERROR|Traceback|\d+\s+failed)\b/.test(text)
+}
+
+/**
+ * Extract candidate claims from a reasoning window.
+ * @param {string} text - unaudited reasoning text.
+ * @param {object} [options] - `maxClaims` cap.
+ * @returns {object[]} claims.
+ */
+export function extractClaims(text, options = {}) {
+  const maxClaims = options.maxClaims ?? 64
+  const claims = []
+  const seen = new Set()
+
+  const add = (claim) => {
+    if (claims.length >= maxClaims) return
+    const key = claim.quote.toLowerCase().replace(/\s+/g, ' ')
+    if (seen.has(key)) return
+    seen.add(key)
+    claims.push(claim)
+  }
+
+  for (const sentence of splitSentences(text)) {
+    if (sentence.length < 8) continue
+    const anchors = extractAnchors(sentence)
+    const hedged = HEDGE_RE.test(sentence)
+    const universal = UNIVERSAL_RE.test(sentence)
+    const assertsSuccess = SUCCESS_RE.test(sentence) && !FAILURE_WORD_RE.test(sentence)
+    const assertsFailure = FAILURE_WORD_RE.test(sentence) && !SUCCESS_RE.test(sentence)
+    const matched = []
+    let actionDetail = ''
+
+    ACTION_RE.lastIndex = 0
+    let actionVerb = ''
+    let match
+    while ((match = ACTION_RE.exec(sentence)) !== null) {
+      matched.push('action')
+      if (actionVerb.length === 0) actionVerb = match[1] ?? ''
+      actionDetail = `${actionDetail} ${match[2] ?? ''}`.trim()
+    }
+    STATUS_RE.lastIndex = 0
+    while (STATUS_RE.exec(sentence) !== null) matched.push('status')
+    ASSERTION_RE.lastIndex = 0
+    while (ASSERTION_RE.exec(sentence) !== null) matched.push('assertion')
+
+    if (matched.length === 0) {
+      if (hedged) matched.push('hedged')
+      else if (universal) matched.push('universal')
+      else if (anchors.length > 0) matched.push('reference')
+      else continue
+    }
+
+    let kind = matched[0]
+    // Planning, conditional, or hypothetical language is not an observed
+    // action: "If I ran the tests" / "I'll run the tests" must not become a
+    // high-severity missing-tool-call claim.
+    const conditional = /\b(?:if|unless|suppose|hypothetically|would|could|might|may)\b/i.test(sentence)
+    const future = /(?:\bi\s*(?:'ll| will|'m going to)\b|\b(?:going to|gonna|plan to|intend to|need to|should|let me)\b)/i.test(sentence)
+    if (kind === 'action' && (conditional || (future && !verbReadsAsPast(actionVerb)))) kind = 'hedged'
+    const toolClass = classifyToolClass(sentence, actionDetail, anchors, kind)
+    add({
+      quote: truncate(sentence, 400),
+      kind,
+      toolClass,
+      anchors,
+      hedged,
+      universal,
+      assertsSuccess: assertsSuccess || /verified|confirmed/i.test(actionDetail) || kind === 'status' && !assertsFailure && SUCCESS_RE.test(sentence),
+      assertsFailure: assertsFailure || FAILURE_WORD_RE.test(actionDetail),
+      detail: truncate(actionDetail || sentence, 300),
+    })
+  }
+  return claims
+}
+
+/** Build one finding object. */
+function finding(claim, status, severity, basis, extra = {}) {
+  return {
+    quote: claim.quote,
+    status,
+    severity,
+    basis,
+    kind: claim.kind,
+    toolClass: claim.toolClass,
+    ...extra,
+  }
+}
+
+/**
+ * Verify extracted claims against one evidence view.
+ *
+ * @param {object[]} claims - output of {@link extractClaims}.
+ * @param {object} evidence - a view from `EvidenceLedger.view()`.
+ * @returns {object[]} findings, one per claim.
+ */
+export function verifyClaims(claims, evidence) {
+  const findings = []
+  for (const claim of claims ?? []) {
+    findings.push(verifyClaim(claim, evidence ?? emptyEvidence()))
+  }
+  return findings
+}
+
+/** Evidence object used when no session ledger exists. */
+function emptyEvidence() {
+  return { calls: [], users: [], currentTurn: 0, has: () => false, hasUser: () => false }
+}
+
+/** Verify one claim. */
+function verifyClaim(claim, evidence) {
+  const anchors = claim.anchors ?? []
+  const relevantCalls = claimRelevantCalls(claim, evidence)
+  const quoted = anchors.filter((anchor) => anchor.kind === 'quote')
+  const paths = anchors.filter((anchor) => anchor.kind === 'path')
+  const quantities = anchors.filter((anchor) => anchor.kind === 'quantity')
+  const references = anchors.filter((anchor) => anchor.kind === 'url' || anchor.kind === 'version')
+  const terms = anchors.filter((anchor) => anchor.kind === 'term')
+  const evidenceRefs = []
+
+  // Planning, conditional, and hedged language is a hypothesis, not a
+  // fabrication. Do this before any anchor join so a conditional sentence
+  // cannot become a high-severity unsupported or contradicted claim.
+  if (claim.hedged || claim.kind === 'hedged') {
+    const supported = terms.some((anchor) => evidence.has(anchor.normalized))
+    return supported
+      ? finding(claim, 'supported', 'low', 'hedged claim matches a ledger term', { evidenceRefs })
+      : finding(claim, 'speculative', 'low', 'hedged language without an asserted observation', { evidenceRefs })
+  }
+
+  // 1. Quoted excerpts are the strongest fabrication signal: a quoted file or
+  //    output fragment that appears nowhere in the ledger is unsupported.
+  for (const anchor of quoted) {
+    if (evidence.has(anchor.normalized) || evidence.hasUser(anchor.normalized)) continue
+    const supportingCall = selectCall(claim, relevantCalls)
+    if (supportingCall !== undefined && claim.kind === 'assertion') {
+      return finding(claim, 'contradicted', 'high',
+        `quoted text ${JSON.stringify(truncate(anchor.value, 80))} does not appear in the result of ${supportingCall.name} (${supportingCall.callId})`,
+        { evidenceRefs: [`result:${supportingCall.callId}`], noMatchingToolCall: false })
+    }
+    return finding(claim, 'unsupported', 'high',
+      `quoted text ${JSON.stringify(truncate(anchor.value, 80))} has no antecedent in the evidence ledger`,
+      { evidenceRefs, noMatchingToolCall: false })
+  }
+
+  // 2. Paths must appear in some tool interaction or user message.
+  for (const anchor of paths) {
+    if (evidence.has(anchor.normalized) || evidence.hasUser(anchor.normalized)) continue
+    const severity = claim.toolClass === 'read' || claim.toolClass === 'write' || claim.kind === 'action' ? 'high' : 'medium'
+    return finding(claim, 'unsupported', severity,
+      `path ${JSON.stringify(anchor.value)} never appears in a tool call, tool result, or user message`,
+      { evidenceRefs, noMatchingToolCall: relevantCalls.length === 0 })
+  }
+
+  // 3. Action/status claims need a matching tool call in this turn. A missing
+  //    call for a first-person tool claim is the highest-precision signal.
+  if (['action', 'status', 'assertion'].includes(claim.kind) && claim.toolClass !== null) {
+    const call = selectCall(claim, relevantCalls)
+    if (call === undefined) {
+      return finding(claim, 'unsupported', 'high',
+        `no tool call in the current turn matches a ${claim.toolClass} claim; the result is asserted without an antecedent`,
+        { evidenceRefs, noMatchingToolCall: true })
+    }
+    evidenceRefs.push(`call:${call.callId}`, `result:${call.callId}`)
+    if (claim.assertsSuccess && callShowsFailure(call)) {
+      return finding(claim, 'contradicted', 'high',
+        `claim asserts success but tool result ${call.callId} (${call.name}) reports failure: ${JSON.stringify(truncate(call.resultText, 160))}`,
+        { evidenceRefs, noMatchingToolCall: false })
+    }
+    if (claim.assertsFailure && callShowsSuccess(call, claim.toolClass)) {
+      return finding(claim, 'contradicted', 'medium',
+        `claim asserts failure but tool result ${call.callId} (${call.name}) reports success`,
+        { evidenceRefs, noMatchingToolCall: false })
+    }
+    return finding(claim, 'supported', 'low',
+      `tool result ${call.callId} (${call.name}) is the antecedent for this claim`,
+      { evidenceRefs, noMatchingToolCall: false })
+  }
+
+  // 4. Quantities without a ledger antecedent are unsupported.
+  for (const anchor of quantities) {
+    if (evidence.has(anchor.normalized) || evidence.hasUser(anchor.normalized)) continue
+    return finding(claim, 'unsupported', 'medium',
+      `quantity ${JSON.stringify(anchor.value)} has no antecedent in the evidence ledger`,
+      { evidenceRefs, noMatchingToolCall: relevantCalls.length === 0 })
+  }
+
+  // 5. URLs and versions without an antecedent are weaker references.
+  for (const anchor of references) {
+    if (evidence.has(anchor.normalized) || evidence.hasUser(anchor.normalized)) continue
+    return finding(claim, 'unsupported', 'low',
+      `${anchor.kind} ${JSON.stringify(anchor.value)} has no antecedent in the evidence ledger`,
+      { evidenceRefs, noMatchingToolCall: false })
+  }
+
+
+  // 7. Universal/absolute language without a ledger antecedent is speculative.
+  if (claim.universal || claim.kind === 'universal') {
+    return finding(claim, 'speculative', 'medium',
+      'absolute language without a ledger antecedent; scope may exceed the evidence',
+      { evidenceRefs })
+  }
+
+  // 8. Plain references are supported when their anchors appear.
+  const missing = terms.find((anchor) => !evidence.has(anchor.normalized))
+  if (missing !== undefined) {
+    return finding(claim, 'unsupported', 'low',
+      `term ${JSON.stringify(missing.value)} has no antecedent in the evidence ledger`,
+      { evidenceRefs, noMatchingToolCall: relevantCalls.length === 0 })
+  }
+  return finding(claim, 'supported', 'low', 'all claim anchors have ledger antecedents', { evidenceRefs })
+}
+
+/** Calls worth considering for one claim: current turn first, then recent. */
+function claimRelevantCalls(claim, evidence) {
+  const calls = evidence.calls ?? []
+  const currentTurn = evidence.currentTurn ?? 0
+  const turnCalls = currentTurn > 0 ? calls.filter((call) => call.turn === currentTurn) : []
+  return turnCalls.length > 0 ? turnCalls : calls.slice(-12)
+}
+
+/**
+ * Summarize findings into the deterministic mechanical verdict consumed by the
+ * policy module.
+ * @param {object[]} findings - verified findings.
+ * @param {object} config - resolved configuration.
+ * @returns {object} mechanical summary.
+ */
+export function summarizeFindings(findings, config = {}) {
+  const gates = config.gates ?? {}
+  const minimum = gates.minimumSeverity ?? 'low'
+  const counts = { supported: 0, unsupported: 0, contradicted: 0, speculative: 0 }
+  const significant = []
+  for (const item of findings ?? []) {
+    if (counts[item.status] !== undefined) counts[item.status] += 1
+    if (severityAtLeast(item.severity, minimum)) significant.push(item)
+  }
+  const contradictedHigh = significant.some((item) => item.status === 'contradicted' && item.severity === 'high')
+  const contradicted = significant.some((item) => item.status === 'contradicted')
+  const unsupportedHigh = significant.some((item) => item.status === 'unsupported' && item.severity === 'high')
+  const unsupported = significant.some((item) => item.status === 'unsupported')
+  const noToolHigh = significant.some((item) => item.status === 'unsupported' && item.severity === 'high' && item.noMatchingToolCall === true)
+  const confirmedFabrication = noToolHigh || contradictedHigh
+
+  const blockOn = gates.blockOn ?? 'confirmed'
+  const verifyOn = gates.verifyOn ?? 'unsupported'
+  const statusRank = { supported: 0, speculative: 1, unsupported: 2, contradicted: 3 }
+  const verifyFloor = verifyOn === 'speculative'
+    ? 1
+    : verifyOn === 'unsupported'
+      ? 2
+      : verifyOn === 'contradicted'
+        ? 3
+        : Number.POSITIVE_INFINITY
+  const blockWanted = blockOn === 'confirmed' ? confirmedFabrication : blockOn === 'contradicted' ? contradicted : false
+  const drivesVerify = significant.some((item) => (statusRank[item.status] ?? 0) >= verifyFloor)
+
+  let level = 'none'
+  if (blockWanted) level = 'block'
+  else if (drivesVerify) level = 'verify'
+  else if (significant.length > 0) level = 'watch'
+
+  const reasons = []
+  if (noToolHigh) reasons.push('an asserted tool result has no matching tool call')
+  if (contradictedHigh) reasons.push('a success claim is contradicted by a failed tool result')
+  if (unsupportedHigh && !noToolHigh) reasons.push('a high-severity claim has no ledger antecedent')
+  if (unsupported && !unsupportedHigh && !noToolHigh) reasons.push('unsupported claims need verification')
+  if (counts.speculative > 0) reasons.push(`${counts.speculative} speculative claim(s)`)
+
+  return {
+    level,
+    confirmedFabrication,
+    counts,
+    reasons,
+    findings: findings ?? [],
+    highestSeverity: highestSeverity(significant),
+  }
+}
+
+/** Highest severity from a list of findings. */
+function highestSeverity(findings) {
+  let highest = 'low'
+  for (const item of findings) {
+    if ((item.severity === 'high') || (item.severity === 'medium' && highest === 'low')) highest = item.severity
+  }
+  return highest
+}