truthguard-ai 0.2.0 → 0.3.0

package/dist-npm/Grounding/index.js

@@ -0,0 +1,1433 @@
+"use strict";
+/**
+ * Grounding Engine
+ *
+ * Orchestrates the full grounding validation pipeline:
+ *
+ *   1. Extract claims from the final response.
+ *   2. For each claim, search tool outputs for a matching source value.
+ *   3. Produce a per-claim ClaimVerdict.
+ *   4. Run the grounding failure rules.
+ *   5. Return a GroundingReport.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GroundingEngine = void 0;
+const types_1 = require("../types");
+const Config_1 = require("../Config");
+const Claims_1 = require("../Claims");
+const node_crypto_1 = require("node:crypto");
+const Matchers_1 = require("../Matchers");
+const Rules_1 = require("../Rules");
+const Trace_1 = require("../Trace");
+const Registry_1 = require("../Registry");
+const TraceReadiness_1 = require("../TraceReadiness");
+const L2_1 = require("../L2");
+// ---------------------------------------------------------------------------
+// GroundingEngine options
+// ---------------------------------------------------------------------------
+/** Fields whose string values are likely person/entity names. */
+// Use (?:^|[_\W]) / (?:$|[_\W]) instead of \b so that underscore-separated
+// keys like "employee_name" or "full_name" still match individual words.
+const NAME_FIELD_RE = /(?:^|[_\W])(name|first_name|last_name|full_name|employee|agent|assignee|customer|user|patient|client|manager|supervisor|owner)(?:$|[_\W])/i;
+/** Fields whose string values are likely dates/timestamps. */
+const DATE_FIELD_RE = /(?:^|[_\W])(date|datum|created|updated|modified|timestamp|time|start|end|due|deadline|expir|birth|dob|hired|joined|scheduled|completed|resolved|closed|opened)(?:$|[_\W])/i;
+/**
+ * Extract the leaf field name from a dotted key path.
+ * E.g. "tardiness_from_daily_stats.by_date.2026-03-15.people[0].name" → "name"
+ * This prevents parent path segments (like "by_date") from triggering
+ * field-type heuristics meant for the leaf key.
+ */
+function leafFieldName(path) {
+    if (!path)
+        return undefined;
+    // Strip array indices, split on dots, take last segment
+    const clean = path.replace(/\[\d+\]/g, '');
+    const parts = clean.split('.');
+    return parts[parts.length - 1] || path;
+}
+// ---------------------------------------------------------------------------
+// Error response detection — early exit for API failures (HTTP 529, etc.)
+// ---------------------------------------------------------------------------
+const ERROR_RESPONSE_PATTERNS = [
+    /^\[API Error\]/i,
+    /\b(?:HTTP|status)\s+[45]\d{2}\b/i,
+    /\b(?:overloaded|preoptere[cć]en|service unavailable)\b/i,
+    /\bAI servis.*(?:nije dostupan|preoptere[cć]en)\b/i,
+    /\b(?:server|service)\s+(?:is\s+)?(?:unavailable|down|error)\b/i,
+];
+/** Check if a final response step is an error message rather than a real AI response. */
+function isErrorResponse(step) {
+    // Explicit metadata flag set by buildErrorTrace / proxy
+    if (step.metadata?.apiError === true)
+        return true;
+    const content = (step.content ?? '').trim();
+    // Error responses may include long URLs / org IDs / headers, so allow up
+    // to 800 chars. The [API Error] prefix is our own tag so it's reliable.
+    if (content.length < 800 && ERROR_RESPONSE_PATTERNS.some((p) => p.test(content))) {
+        return true;
+    }
+    return false;
+}
+/** Build a DetectedFailure for ai_unavailable from an error step. */
+function detectAIUnavailableFromStep(step) {
+    const content = (step.content ?? '').trim();
+    const statusCode = step.metadata?.statusCode;
+    const errorType = step.metadata?.errorType ?? 'unknown';
+    return {
+        type: 'orchestration.ai_unavailable',
+        description: statusCode
+            ? `AI service returned HTTP ${statusCode} error instead of a response.`
+            : `AI service error: ${content.substring(0, 120)}`,
+        confidence: 'high',
+        severity: 'critical',
+        role: 'primary',
+        claimIds: [],
+        diagnosis: `The AI provider did not return a usable response (${errorType}). No claims can be extracted or verified.`,
+        suggestedFix: 'Retry the request. If persistent, check provider status page or switch to a fallback model.',
+    };
+}
+/**
+ * Extract single-word proper names from tool outputs that are mentioned
+ * in the response but were not captured by the 2+-word NAME_REGEX in Claims.
+ * This is a context-aware pass: we only create name claims for words that
+ * actually exist as person-name values in tool data.
+ */
+function extractToolContextNameClaims(trace, responseText, stepId, existingClaims) {
+    const toolSteps = Trace_1.TraceUtils.getToolOutputSteps(trace);
+    if (!toolSteps.length)
+        return [];
+    // Collect candidate name strings from name-like fields
+    const nameStrings = new Set();
+    const fullNameStrings = new Set();
+    for (const step of toolSteps) {
+        for (const to of step.toolOutputs ?? []) {
+            collectNameStrings(to.output, nameStrings, fullNameStrings);
+        }
+    }
+    if (nameStrings.size === 0)
+        return [];
+    // Already-claimed name values (lowercase)
+    const existingNames = new Set(existingClaims
+        .filter((c) => c.type === 'name')
+        .flatMap((c) => {
+        const v = String(c.value).toLowerCase();
+        return [v, ...v.split(/\s+/)];
+    }));
+    // Build per-word ambiguity count: how many distinct full names contain each word.
+    // Words that appear in 2+ different full names (e.g. shared surnames like "Tasić"
+    // in "Filip Tasić" and "Slađana Tasić") are ambiguous and should NOT become
+    // standalone claims — they could match the wrong person.
+    const wordFullNameCount = new Map();
+    for (const fullName of fullNameStrings) {
+        const tokens = fullName.toLowerCase().split(/\s+/);
+        for (const t of tokens) {
+            wordFullNameCount.set(t, (wordFullNameCount.get(t) ?? 0) + 1);
+        }
+    }
+    const lowResp = responseText.toLowerCase();
+    const claims = [];
+    for (const name of nameStrings) {
+        const low = name.toLowerCase();
+        // Skip if already covered by an existing claim
+        if (existingNames.has(low))
+            continue;
+        // Must be a single word (multi-word names are caught by NAME_REGEX)
+        if (name.includes(' '))
+            continue;
+        // Must be at least 3 chars to avoid matching "Mr", "Dr" etc.
+        if (name.length < 3)
+            continue;
+        // Skip words that appear in 2+ different full names (ambiguous — shared surname)
+        if ((wordFullNameCount.get(low) ?? 0) > 1)
+            continue;
+        // Check if the name appears in the response as a whole word
+        const re = new RegExp(`\\b${escapeRegExp(low)}\\b`, 'i');
+        if (!re.test(lowResp))
+            continue;
+        // Find the raw match position for rawText
+        const match = new RegExp(`\\b${escapeRegExp(name)}\\b`, 'i').exec(responseText);
+        const rawText = match ? match[0] : name;
+        claims.push({
+            claimId: (0, node_crypto_1.randomUUID)(),
+            type: 'name',
+            value: rawText,
+            rawText,
+            source: {
+                stepId,
+                role: 'final_response',
+                rawText,
+            },
+        });
+        existingNames.add(low);
+    }
+    return claims;
+}
+function collectNameStrings(output, names, fullNames, key) {
+    if (output === null || output === undefined)
+        return;
+    if (typeof output === 'string' && key && NAME_FIELD_RE.test(key)) {
+        // Split compound names: "Ana Jović" → ["Ana Jović", "Ana", "Jović"]
+        const trimmed = output.trim();
+        if (trimmed.length >= 2 && trimmed.length < 100) {
+            // Track the full name string for ambiguity detection
+            if (trimmed.includes(' '))
+                fullNames.add(trimmed);
+            const words = trimmed.split(/\s+/);
+            for (const w of words) {
+                if (w.length >= 2 && /^[\p{Lu}]/u.test(w))
+                    names.add(w);
+            }
+        }
+    }
+    else if (Array.isArray(output)) {
+        output.forEach((item) => collectNameStrings(item, names, fullNames, key));
+    }
+    else if (typeof output === 'object') {
+        for (const [k, val] of Object.entries(output)) {
+            collectNameStrings(val, names, fullNames, k);
+        }
+    }
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// ---------------------------------------------------------------------------
+// Verdict builder helpers
+// ---------------------------------------------------------------------------
+function buildUnverifiable(claim, reason) {
+    return {
+        claim,
+        verdict: 'UNVERIFIABLE',
+        explanation: reason,
+        ruleUsed: 'unverifiable',
+    };
+}
+/**
+ * Compute severity based on claim type and verdict.
+ *
+ * - HIGH: UNGROUNDED count or date (exact match required, any deviation is serious)
+ * - MEDIUM: UNGROUNDED number (tolerance-based, deviation is meaningful)
+ * - LOW: APPROXIMATE_MATCH, or UNGROUNDED name
+ */
+function computeSeverity(v) {
+    if (v.verdict === 'GROUNDED')
+        return 'LOW';
+    if (v.verdict === 'APPROXIMATE_MATCH')
+        return 'LOW';
+    if (v.verdict === 'UNVERIFIABLE' || v.verdict === 'MULTI_STEP')
+        return 'LOW';
+    // UNGROUNDED
+    if (v.claim.type === 'count' || v.claim.type === 'date')
+        return 'HIGH';
+    if (v.claim.type === 'number')
+        return 'MEDIUM';
+    return 'MEDIUM'; // name
+}
+// ---------------------------------------------------------------------------
+// Empty-result output detection
+// ---------------------------------------------------------------------------
+/**
+ * Detect tool outputs that represent "no data found" results —
+ * e.g. {total: 0, data: []} or {count: 0, results: []}.
+ * These should NOT count as "substantive data" for scoring purposes.
+ */
+function isEmptyResultOutput(output) {
+    if (output === null || output === undefined)
+        return true;
+    if (Array.isArray(output) && output.length === 0)
+        return true;
+    if (typeof output === 'object' && !Array.isArray(output)) {
+        const obj = output;
+        const keys = Object.keys(obj);
+        if (keys.length === 0)
+            return true;
+        const vals = Object.values(obj);
+        // {total: 0, data: []} pattern
+        const countKeys = ['total', 'count', 'length', 'total_count', 'totalCount'];
+        const dataKeys = ['data', 'results', 'items', 'records', 'rows', 'employees', 'entries'];
+        const hasZeroCount = countKeys.some((k) => obj[k] === 0);
+        const hasEmptyArray = dataKeys.some((k) => Array.isArray(obj[k]) && obj[k].length === 0);
+        if (hasZeroCount && hasEmptyArray)
+            return true;
+        // All values are zero, null, empty string, or empty array
+        if (vals.every((v) => v === 0 || v === null || v === undefined || v === '' ||
+            (Array.isArray(v) && v.length === 0)))
+            return true;
+    }
+    return false;
+}
+/**
+ * Walk a JSON record and check if any name-like field matches the given entity.
+ */
+function recordBelongsToEntity(record, entityName) {
+    if (record === null || record === undefined || typeof record !== 'object')
+        return false;
+    if (Array.isArray(record))
+        return false;
+    for (const [key, val] of Object.entries(record)) {
+        if (typeof val === 'string' && NAME_FIELD_RE.test(key)) {
+            if ((0, Claims_1.entitiesMatch)(val, entityName))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Extract SourceEntries from tool outputs, filtered to only records
+ * that belong to the given entity. Used for entity-aware grounding.
+ */
+function extractEntityScopedValues(trace, entityName, claimType) {
+    const entries = [];
+    const toolOutputSteps = Trace_1.TraceUtils.getToolOutputSteps(trace);
+    for (const step of toolOutputSteps) {
+        for (const to of step.toolOutputs ?? []) {
+            const output = to.output;
+            const records = [];
+            if (Array.isArray(output)) {
+                for (const item of output) {
+                    if (recordBelongsToEntity(item, entityName))
+                        records.push(item);
+                }
+            }
+            else if (typeof output === 'object' && output !== null) {
+                if (recordBelongsToEntity(output, entityName))
+                    records.push(output);
+            }
+            for (const record of records) {
+                if (claimType === 'count') {
+                    const cnt = (0, Matchers_1.extractCountFromOutput)(record);
+                    if (cnt !== null) {
+                        entries.push({ stepId: step.stepId, value: cnt, toolName: to.toolName });
+                    }
+                }
+                const vals = (0, Matchers_1.extractValuesWithKeys)(record);
+                for (const v of vals) {
+                    entries.push({
+                        stepId: step.stepId,
+                        value: v.value,
+                        toolName: to.toolName,
+                        fieldName: v.fieldName,
+                    });
+                }
+            }
+        }
+    }
+    return entries;
+}
+/**
+ * Extract grounding-relevant values from the system prompt step.
+ * The system prompt is free text, so we use the claim extractor to parse
+ * individual numbers, names, and dates from it — then expose their values
+ * as potential grounding sources.
+ */
+function extractSystemPromptValues(trace) {
+    const sysStep = Trace_1.TraceUtils.getSystemPrompt(trace);
+    if (!sysStep)
+        return [];
+    const claims = (0, Claims_1.extractClaims)(sysStep.content, {
+        sourceStepId: sysStep.stepId,
+        sourceRole: 'system_prompt',
+    });
+    return claims.map((c) => ({
+        stepId: sysStep.stepId,
+        value: c.value,
+        toolName: 'system_prompt',
+    }));
+}
+/**
+ * Extract grounding values from conversation history (previous turns).
+ *
+ * In proxy mode, each HTTP request is a separate trace. The AI sends the full
+ * conversation history in messages, but tool outputs from earlier proxy
+ * requests are lost. When the AI references data from a previous turn
+ * (e.g., correcting a user's claim about "6738 hours"), those values exist
+ * only in prior user_input and final_response steps.
+ *
+ * This function extracts numeric and text values from all user_input and
+ * prior final_response steps so they can be used as grounding sources.
+ */
+function extractConversationHistoryValues(trace) {
+    const entries = [];
+    const steps = trace.steps ?? [];
+    // Find the last final_response — we don't extract from the active response
+    // (that's the text we're verifying, not a grounding source).
+    const finalResponseIndices = [];
+    for (let i = 0; i < steps.length; i++) {
+        if (steps[i].role === 'final_response')
+            finalResponseIndices.push(i);
+    }
+    const lastFinalIdx = finalResponseIndices.length > 0
+        ? finalResponseIndices[finalResponseIndices.length - 1]
+        : steps.length;
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        // Include prior final_response steps only (not the last one being verified).
+        // We intentionally skip user_input steps — grounding against the user's
+        // own question would create circular "user_input_echo" matches.
+        if (step.role !== 'final_response')
+            continue;
+        if (i >= lastFinalIdx)
+            continue;
+        if (!step.content)
+            continue;
+        const claims = (0, Claims_1.extractClaims)(step.content, {
+            sourceStepId: step.stepId,
+            sourceRole: step.role,
+        });
+        for (const c of claims) {
+            entries.push({
+                stepId: step.stepId,
+                value: c.value,
+                toolName: `conversation_${step.role}`,
+            });
+        }
+    }
+    return entries;
+}
+// ---------------------------------------------------------------------------
+// Text-level date search fallback
+// ---------------------------------------------------------------------------
+/**
+ * Search for an ISO date (YYYY-MM-DD) in the full text of all tool outputs.
+ * Also checks European (DD.MM.YYYY) and slash (MM/DD/YYYY) variants.
+ * Returns an explanation string if found, null otherwise.
+ */
+function dateTextFallback(isoValue, toolOutputSteps) {
+    const isoDate = isoValue.substring(0, 10);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(isoDate))
+        return null;
+    // Build full text from all tool output content and serialized output objects
+    const parts = [];
+    for (const step of toolOutputSteps) {
+        if (step.content)
+            parts.push(step.content);
+        for (const to of step.toolOutputs ?? []) {
+            if (typeof to.output === 'string') {
+                parts.push(to.output);
+            }
+            else if (to.output != null) {
+                parts.push(JSON.stringify(to.output));
+            }
+        }
+    }
+    const fullText = parts.join(' ');
+    // 1. ISO format (2026-03-01)
+    if (fullText.includes(isoDate)) {
+        return `Date "${isoDate}" found in tool output text.`;
+    }
+    const [y, m, d] = isoDate.split('-');
+    // 2. European DD.MM.YYYY (01.03.2026 or 1.3.2026)
+    const euFull = `${d}.${m}.${y}`;
+    const euShort = `${parseInt(d)}.${parseInt(m)}.${y}`;
+    if (fullText.includes(euFull) || fullText.includes(euShort)) {
+        const fmt = fullText.includes(euFull) ? euFull : euShort;
+        return `Date "${isoDate}" found as "${fmt}" in tool output text.`;
+    }
+    // 3. Slash MM/DD/YYYY
+    const slashMDY = `${m}/${d}/${y}`;
+    if (fullText.includes(slashMDY)) {
+        return `Date "${isoDate}" found as "${slashMDY}" in tool output text.`;
+    }
+    // 4. Extract all date-like patterns from text and try parsing them
+    const datePatterns = fullText.match(/\b\d{1,2}[.\-/]\d{1,2}[.\-/]\d{2,4}\b/g);
+    if (datePatterns) {
+        for (const dp of datePatterns) {
+            const parsed = (0, Claims_1.tryParseDate)(dp);
+            if (parsed && parsed.substring(0, 10) === isoDate) {
+                return `Date "${isoDate}" found as "${dp}" in tool output text.`;
+            }
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Per-claim grounding logic
+// ---------------------------------------------------------------------------
+/**
+ * Check whether a date claim can be grounded via user input echo, relative
+ * date word resolution, or tool call parameter context — i.e. the date is
+ * "contextual" rather than a factual data claim from tool output.
+ *
+ * Returns a ClaimVerdict if the claim is contextually grounded, or null.
+ */
+function tryDateContextGrounding(claim, trace) {
+    if (claim.type !== 'date' || typeof claim.value !== 'string')
+        return null;
+    const userInputSteps = (trace.steps ?? []).filter((s) => s.role === 'user_input');
+    const claimDateLower = claim.value.toLowerCase();
+    const claimRawLower = (claim.rawText ?? '').toLowerCase();
+    // Check 1: literal match in user input
+    const isEchoedFromUser = userInputSteps.some((s) => {
+        const uLower = (s.content ?? '').toLowerCase();
+        return ((claimRawLower && uLower.includes(claimRawLower)) ||
+            uLower.includes(claimDateLower));
+    });
+    // Check 2: relative date words in user input resolve to the claim date
+    const RELATIVE_TODAY = /\b(danas|today)\b/i;
+    const RELATIVE_YESTERDAY = /\b(ju[čc]e|yesterday)\b/i;
+    const RELATIVE_TOMORROW = /\b(sutra|tomorrow)\b/i;
+    const traceDate = trace.startedAt ? new Date(trace.startedAt) : new Date();
+    const toISODay = (d) => d.toISOString().substring(0, 10);
+    const todayISO = toISODay(traceDate);
+    const yesterdayD = new Date(traceDate);
+    yesterdayD.setDate(yesterdayD.getDate() - 1);
+    const tomorrowD = new Date(traceDate);
+    tomorrowD.setDate(tomorrowD.getDate() + 1);
+    let isRelativeDateMatch = false;
+    const allUserText = userInputSteps.map((s) => s.content ?? '').join(' ');
+    // Check both user input AND claim rawText for relative date words
+    const textToCheck = allUserText + ' ' + claimRawLower;
+    if (RELATIVE_TODAY.test(textToCheck) && claimDateLower === todayISO) {
+        isRelativeDateMatch = true;
+    }
+    else if (RELATIVE_YESTERDAY.test(textToCheck) && claimDateLower === toISODay(yesterdayD)) {
+        isRelativeDateMatch = true;
+    }
+    else if (RELATIVE_TOMORROW.test(textToCheck) && claimDateLower === toISODay(tomorrowD)) {
+        isRelativeDateMatch = true;
+    }
+    // Check 3: date appears in tool_call parameters (query context dates)
+    const toolCallSteps = (trace.steps ?? []).filter((s) => s.role === 'tool_call');
+    const isInToolCallParams = toolCallSteps.some((s) => (s.toolCalls ?? []).some((tc) => {
+        const paramStr = JSON.stringify(tc.parameters ?? {}).toLowerCase();
+        return paramStr.includes(claimDateLower);
+    }));
+    // Check 4: period-reference patterns — user says "first half of March" and
+    // the AI echoes "1-15. mart" → the 15th is a logical derivation, not a data claim.
+    let isPeriodRangeEcho = false;
+    if (!isEchoedFromUser && !isRelativeDateMatch && !isInToolCallParams) {
+        // Patterns that imply a date-range boundary the AI would derive
+        const FIRST_HALF = /\b(prv[aueoi]\s+polovin[aueoi]|first\s+half)\b/i;
+        const SECOND_HALF = /\b(drug[aueoi]\s+polovin[aueoi]|second\s+half)\b/i;
+        const FIRST_WEEK = /\b(prv[aueoi]\s+nedelj[aueoi]|prv[aueoi]\s+sedmic[aueoi]|first\s+week)\b/i;
+        const claimDay = parseInt(claimDateLower.split('-')[2], 10);
+        if (FIRST_HALF.test(allUserText) && (claimDay === 15 || claimDay === 1)) {
+            isPeriodRangeEcho = true;
+        }
+        else if (SECOND_HALF.test(allUserText) && (claimDay === 16 || claimDay >= 28)) {
+            isPeriodRangeEcho = true;
+        }
+        else if (FIRST_WEEK.test(allUserText) && (claimDay === 7 || claimDay === 1)) {
+            isPeriodRangeEcho = true;
+        }
+    }
+    if (isEchoedFromUser || isRelativeDateMatch || isInToolCallParams || isPeriodRangeEcho) {
+        const reason = isEchoedFromUser
+            ? 'appears in the user\'s question'
+            : isRelativeDateMatch
+                ? 'is a relative date word that resolves to the correct date'
+                : isInToolCallParams
+                    ? 'appears in tool call parameters (query context)'
+                    : 'is a period boundary derived from the user\'s time-range request';
+        const v = {
+            claim,
+            verdict: 'GROUNDED',
+            ruleUsed: 'user_input_echo',
+            explanation: `Date "${claim.rawText ?? claim.value}" ${reason} — ` +
+                `AI is echoing context, not making a data claim.`,
+        };
+        v.severity = computeSeverity(v);
+        return v;
+    }
+    return null;
+}
+/**
+ * If a name claim appears (wholly or partially) in user input, the AI is
+ * echoing the user's context rather than hallucinating. Return GROUNDED
+ * so these don't penalise the score when there's no tool data to verify.
+ */
+function tryNameContextGrounding(claim, trace) {
+    if (claim.type !== 'name' || typeof claim.value !== 'string')
+        return null;
+    const userInputSteps = (trace.steps ?? []).filter((s) => s.role === 'user_input');
+    if (userInputSteps.length === 0)
+        return null;
+    const allUserText = (0, Claims_1.normalizeDiacritics)(userInputSteps.map((s) => (s.content ?? '').toLowerCase()).join(' '));
+    const nameWords = (0, Claims_1.normalizeDiacritics)(claim.value.toLowerCase()).split(/\s+/);
+    // At least one substantial word of the name (>2 chars) must appear in user input
+    const matchCount = nameWords.filter((w) => w.length > 2 && allUserText.includes(w)).length;
+    if (matchCount === 0)
+        return null;
+    const v = {
+        claim,
+        verdict: 'GROUNDED',
+        ruleUsed: 'user_input_echo',
+        explanation: `Name "${claim.value}" appears in the user's conversation context — ` +
+            `AI is referencing a name the user mentioned, not fabricating one.`,
+    };
+    v.severity = computeSeverity(v);
+    return v;
+}
+/**
+ * Try to ground a single claim against all available tool outputs.
+ * Returns the best ClaimVerdict found.
+ */
+function groundClaim(claim, trace, tolerances) {
+    const toolOutputSteps = Trace_1.TraceUtils.getToolOutputSteps(trace);
+    // Also collect values from system prompt as a secondary grounding source
+    const systemPromptValues = extractSystemPromptValues(trace);
+    // Cross-turn grounding: extract values from prior conversation turns
+    // (user_input + previous final_response steps) so the AI can reference
+    // data discussed earlier without being penalised.
+    const conversationValues = extractConversationHistoryValues(trace);
+    if (toolOutputSteps.length === 0 && systemPromptValues.length === 0 && conversationValues.length === 0) {
+        return buildUnverifiable(claim, 'No tool outputs or system prompt found in trace.');
+    }
+    // Collect all (stepId, value) pairs from tool outputs
+    const allValues = [];
+    for (const step of toolOutputSteps) {
+        for (const to of step.toolOutputs ?? []) {
+            // For count claims, also extract the count of array outputs
+            if (claim.type === 'count') {
+                const cnt = (0, Matchers_1.extractCountFromOutput)(to.output);
+                if (cnt !== null) {
+                    allValues.push({ stepId: step.stepId, value: cnt, toolName: to.toolName });
+                }
+            }
+            const vals = (0, Matchers_1.extractValuesWithKeys)(to.output);
+            for (const v of vals) {
+                allValues.push({
+                    stepId: step.stepId,
+                    value: v.value,
+                    toolName: to.toolName,
+                    fieldName: v.fieldName,
+                });
+            }
+        }
+    }
+    // Add system prompt values as secondary source
+    for (const entry of systemPromptValues) {
+        allValues.push(entry);
+    }
+    // Add conversation history values as tertiary source (cross-turn data)
+    for (const entry of conversationValues) {
+        allValues.push(entry);
+    }
+    // -------------------------------------------------------------------------
+    // L2 fast-path: structured claims carry sourceFieldValue from extraction
+    // -------------------------------------------------------------------------
+    if (claim.sourceFieldValue !== undefined) {
+        let l2Result = null;
+        let ruleUsed = '';
+        if (claim.type === 'boolean') {
+            l2Result = (0, L2_1.matchBoolean)(claim.value, claim.sourceFieldValue);
+            ruleUsed = 'boolean_match';
+        }
+        else if (claim.type === 'enum') {
+            l2Result = (0, L2_1.matchEnum)(claim.value, claim.sourceFieldValue);
+            ruleUsed = 'enum_match';
+        }
+        else if (claim.type === 'list_items' && claim.expectedItems && claim.mentionedItems) {
+            l2Result = (0, L2_1.matchListItems)(claim.expectedItems, claim.mentionedItems);
+            ruleUsed = 'list_items_match';
+        }
+        else if (claim.type === 'key_value') {
+            l2Result = (0, L2_1.matchKeyValue)(claim.value, claim.sourceFieldValue);
+            ruleUsed = 'key_value_match';
+        }
+        else if (claim.type === 'aggregation' && claim.computedValue !== undefined) {
+            l2Result = (0, L2_1.matchAggregation)(claim.value, claim.computedValue, claim.aggregationOp ?? 'sum');
+            ruleUsed = 'aggregation_match';
+        }
+        else if (claim.type === 'range') {
+            l2Result = (0, L2_1.matchRange)(claim.value, claim.sourceFieldValue);
+            ruleUsed = 'range_match';
+        }
+        if (l2Result) {
+            let verdictType = l2Result.matched ? 'GROUNDED' : 'UNGROUNDED';
+            let explanation = l2Result.explanation;
+            // Sibling-scope: weak_scope claims that fail grounding get downgraded
+            // to APPROXIMATE_MATCH with LOW severity — prevents false positives from
+            // sibling groups that only have a single incidental mention.
+            if (!l2Result.matched && claim.siblingScope === 'weak_scope') {
+                verdictType = 'APPROXIMATE_MATCH';
+                explanation += ` [weak_scope sibling — penalty suppressed; family: ${claim.siblingFamilyPattern ?? 'unknown'}]`;
+            }
+            const verdict = {
+                claim,
+                verdict: verdictType,
+                sourceValue: claim.sourceFieldValue,
+                sourceStepId: claim.source.stepId,
+                ruleUsed,
+                explanation,
+            };
+            verdict.severity = computeSeverity(verdict);
+            // Force LOW severity for weak_scope downgrades
+            if (claim.siblingScope === 'weak_scope' && verdictType === 'APPROXIMATE_MATCH') {
+                verdict.severity = 'LOW';
+            }
+            return verdict;
+        }
+    }
+    if (allValues.length === 0) {
+        // Check if tool outputs are empty ([], null, {}) — this means the claim
+        // has no grounding source and is fabricated, not just unverifiable.
+        const allOutputsEmpty = toolOutputSteps.every((step) => (step.toolOutputs ?? []).every((to) => {
+            const o = to.output;
+            if (o === null || o === undefined)
+                return true;
+            if (Array.isArray(o) && o.length === 0)
+                return true;
+            if (typeof o === 'string' && o.trim() === '')
+                return true;
+            if (typeof o === 'object' && !Array.isArray(o) && Object.keys(o).length === 0)
+                return true;
+            return false;
+        }));
+        if (allOutputsEmpty) {
+            // Before declaring UNGROUNDED, check if a date/name claim can be grounded
+            // via user-question echo or tool call parameter context.
+            const ctxVerdict = tryDateContextGrounding(claim, trace)
+                ?? tryNameContextGrounding(claim, trace);
+            if (ctxVerdict)
+                return ctxVerdict;
+            const v = {
+                claim,
+                verdict: 'UNGROUNDED',
+                explanation: 'All tool outputs are empty — claim has no grounding source.',
+                ruleUsed: 'empty_output',
+            };
+            v.severity = computeSeverity(v);
+            return v;
+        }
+        return buildUnverifiable(claim, 'Tool outputs contain no extractable values.');
+    }
+    // -------------------------------------------------------------------------
+    // Entity-aware grounding: when claim has an entity, prefer values from
+    // the tool output record belonging to that entity. This prevents
+    // cross-entity false groundings (e.g. "Ana: 11 lates" matching Gordana's 11).
+    // -------------------------------------------------------------------------
+    let valuesToSearch = allValues;
+    if (claim.entity) {
+        const entityScoped = extractEntityScopedValues(trace, claim.entity, claim.type);
+        if (entityScoped.length > 0) {
+            valuesToSearch = entityScoped;
+        }
+    }
+    // Try to find the best match among extracted values
+    let bestVerdict = null;
+    let bestScore = -Infinity;
+    for (const entry of valuesToSearch) {
+        const { stepId, value: sourceValue } = entry;
+        let verdict = 'UNGROUNDED';
+        let deviation;
+        let similarity;
+        let explanation = '';
+        let ruleUsed = '';
+        if (claim.type === 'number' && typeof sourceValue === 'number') {
+            // Try unit-aware matching first
+            const sourceUnit = (0, Matchers_1.inferUnitFromFieldName)(entry.fieldName);
+            const res = (0, Matchers_1.matchNumericWithUnits)(claim.value, claim.unit, sourceValue, sourceUnit, tolerances);
+            deviation = res.deviation;
+            explanation = res.explanation;
+            ruleUsed = 'numeric_match';
+            if (res.matched) {
+                verdict = deviation !== undefined && deviation === 0 ? 'GROUNDED' : 'APPROXIMATE_MATCH';
+            }
+        }
+        else if (claim.type === 'count' && typeof sourceValue === 'number') {
+            const res = (0, Matchers_1.matchCount)(claim.value, sourceValue, tolerances);
+            deviation = res.deviation;
+            explanation = res.explanation;
+            ruleUsed = 'count_match';
+            if (res.matched)
+                verdict = 'GROUNDED';
+        }
+        else if (claim.type === 'date' && typeof sourceValue === 'string') {
+            // Don't compare date claims against name-like fields (e.g. "Filip Tasić")
+            const dateLeaf = leafFieldName(entry.fieldName);
+            if (dateLeaf && NAME_FIELD_RE.test(dateLeaf))
+                continue;
+            const res = (0, Matchers_1.matchDate)(claim.value, sourceValue, tolerances);
+            explanation = res.explanation;
+            ruleUsed = 'date_match';
+            if (res.matched)
+                verdict = 'GROUNDED';
+        }
+        else if (claim.type === 'name' && typeof sourceValue === 'string') {
+            // Don't compare name claims against date-like fields (e.g. "2026-03-22")
+            const nameLeaf = leafFieldName(entry.fieldName);
+            if (nameLeaf && DATE_FIELD_RE.test(nameLeaf))
+                continue;
+            const res = (0, Matchers_1.matchName)(claim.value, sourceValue, tolerances);
+            similarity = res.similarity;
+            explanation = res.explanation;
+            ruleUsed = 'name_fuzzy_match';
+            if (res.matched)
+                verdict = 'GROUNDED';
+        }
+        else {
+            // Type mismatch between claim and source value — skip
+            continue;
+        }
+        // Score: GROUNDED=3, APPROXIMATE_MATCH=2, UNGROUNDED with low deviation=1
+        let score = 0;
+        if (verdict === 'GROUNDED')
+            score = 3;
+        else if (verdict === 'APPROXIMATE_MATCH')
+            score = 2;
+        else if (verdict === 'UNGROUNDED' && deviation !== undefined)
+            score = 1 - deviation;
+        else if (verdict === 'UNGROUNDED' && similarity !== undefined)
+            score = similarity;
+        if (score > bestScore) {
+            bestScore = score;
+            bestVerdict = {
+                claim,
+                verdict,
+                sourceValue,
+                sourceStepId: stepId,
+                deviation,
+                ruleUsed,
+                explanation,
+            };
+        }
+    }
+    if (bestVerdict === null) {
+        // -----------------------------------------------------------------------
+        // Text-level date search fallback: when no value of compatible type was
+        // found (e.g. tool output is a prose string), search the full tool output
+        // text for the ISO date string or common format variants.
+        // -----------------------------------------------------------------------
+        if (claim.type === 'date' && typeof claim.value === 'string') {
+            const textMatch = dateTextFallback(claim.value, toolOutputSteps);
+            if (textMatch) {
+                const v = {
+                    claim,
+                    verdict: 'GROUNDED',
+                    ruleUsed: 'date_text_search',
+                    explanation: textMatch,
+                };
+                v.severity = computeSeverity(v);
+                return v;
+            }
+        }
+        return buildUnverifiable(claim, `No tool output value of compatible type (${claim.type}) found.`);
+    }
+    // -------------------------------------------------------------------------
+    // Text-level date search fallback: if date claim is UNGROUNDED after the
+    // per-value matching loop, search full tool output text for the date.
+    // -------------------------------------------------------------------------
+    if (bestVerdict.verdict === 'UNGROUNDED' &&
+        claim.type === 'date' &&
+        typeof claim.value === 'string') {
+        const textMatch = dateTextFallback(claim.value, toolOutputSteps);
+        if (textMatch) {
+            bestVerdict.verdict = 'GROUNDED';
+            bestVerdict.ruleUsed = 'date_text_search';
+            bestVerdict.explanation = textMatch;
+        }
+    }
+    // Transposed digits detection: if a numeric claim is UNGROUNDED and its
+    // digits are a transposition of the source, flag as APPROXIMATE_MATCH
+    // with a specific explanation. This catches common LLM copy errors (23→32).
+    if (bestVerdict.verdict === 'UNGROUNDED' &&
+        (claim.type === 'number' || claim.type === 'count') &&
+        typeof bestVerdict.sourceValue === 'number' &&
+        (0, Matchers_1.isTransposedDigits)(claim.value, bestVerdict.sourceValue)) {
+        bestVerdict.verdict = 'APPROXIMATE_MATCH';
+        bestVerdict.ruleUsed = 'transposed_digits';
+        bestVerdict.explanation =
+            `${claim.value} appears to be a digit transposition of ${bestVerdict.sourceValue} (swapped adjacent digits).`;
+    }
+    // ---------------------------------------------------------------------------
+    // User-input echo detection: if a date or name claim is UNGROUNDED but
+    // appears in a user_input step, the AI is echoing the user's context —
+    // not a factual claim from tool data. Treat as GROUNDED.
+    // ---------------------------------------------------------------------------
+    if (bestVerdict.verdict === 'UNGROUNDED' &&
+        claim.type === 'date' &&
+        typeof claim.value === 'string') {
+        const ctxVerdict = tryDateContextGrounding(claim, trace);
+        if (ctxVerdict) {
+            bestVerdict.verdict = ctxVerdict.verdict;
+            bestVerdict.ruleUsed = ctxVerdict.ruleUsed;
+            bestVerdict.explanation = ctxVerdict.explanation;
+        }
+    }
+    if (bestVerdict.verdict === 'UNGROUNDED' && claim.type === 'name') {
+        const nameCtx = tryNameContextGrounding(claim, trace);
+        if (nameCtx) {
+            bestVerdict.verdict = nameCtx.verdict;
+            bestVerdict.ruleUsed = nameCtx.ruleUsed;
+            bestVerdict.explanation = nameCtx.explanation;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Source=0 noise guard: when the best numeric match has sourceValue=0 and
+    // the claimed value is very large, the 0 is almost certainly from an
+    // unrelated field (e.g. total_sessions=0 matched against work hours).
+    // Downgrade to UNVERIFIABLE to avoid misleading "AI=6738 vs Source=0" verdicts.
+    // Only applies for large claim values where 0 is clearly noise, not for
+    // small counts where 0 could be a real mismatch (e.g. tool says 0, AI says 3).
+    // ---------------------------------------------------------------------------
+    if (bestVerdict.verdict === 'UNGROUNDED' &&
+        (claim.type === 'number' || claim.type === 'count') &&
+        bestVerdict.sourceValue === 0 &&
+        typeof claim.value === 'number' &&
+        Math.abs(claim.value) >= 100) {
+        bestVerdict.verdict = 'UNVERIFIABLE';
+        bestVerdict.explanation =
+            `No plausible source value found for ${claim.type} claim "${claim.value}". ` +
+                `Closest match was 0 from an unrelated field.`;
+        bestVerdict.ruleUsed = 'source_zero_noise';
+    }
+    bestVerdict.severity = computeSeverity(bestVerdict);
+    return bestVerdict;
+}
+// ---------------------------------------------------------------------------
+// GroundingEngine
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Root Cause Analysis
+// ---------------------------------------------------------------------------
+const SEVERITY_ORDER = { critical: 4, high: 3, medium: 2, low: 1 };
+/**
+ * Build a root-cause summary from orchestrated detected failures.
+ *
+ * Returns `{ rootCause, summary }` where:
+ * - `rootCause` is a one-sentence explanation derived from the highest-severity
+ *   primary failure and its diagnosis.
+ * - `summary` is a multi-sentence narrative covering all primary failures,
+ *   their causal chain (secondary suppressions), and suggested fixes.
+ *
+ * Returns undefined fields when no failures are present.
+ */
+// ---------------------------------------------------------------------------
+// Resolution assessment
+// ---------------------------------------------------------------------------
+/**
+ * Determines whether the user's question was actually resolved.
+ * This is a meta-signal derived from detected failures — not a new rule.
+ */
+function assessResolution(detectedFailures, claimsTotal, claimsVerified, claimsSkipped) {
+    if (detectedFailures.length === 0) {
+        if (claimsTotal === 0) {
+            return { resolved: true, resolutionNote: 'No verifiable claims in response.' };
+        }
+        return { resolved: true };
+    }
+    const primaryFailures = detectedFailures.filter((f) => f.role === 'primary');
+    // Failure types that definitively mean "question not resolved"
+    const UNRESOLVED_TYPES = {
+        'orchestration.answer_refusal': 'AI explicitly refused to answer.',
+        'orchestration.ai_unavailable': 'AI service was unavailable.',
+        'grounding.question_not_answered': 'The user\'s question was not addressed.',
+        'grounding.empty_fabrication': 'Response was fabricated without tool data.',
+        'grounding.no_tool_call': 'AI did not call any tools to gather data.',
+    };
+    for (const f of primaryFailures) {
+        if (f.type in UNRESOLVED_TYPES) {
+            return {
+                resolved: false,
+                resolutionNote: UNRESOLVED_TYPES[f.type],
+            };
+        }
+    }
+    // Partial resolution: high-severity completeness failures
+    const PARTIAL_TYPES = new Set([
+        'grounding.incomplete_response',
+        'orchestration.tool_budget_exhaustion',
+        'orchestration.tool_selection_error',
+    ]);
+    const hasPartialFailure = primaryFailures.some((f) => PARTIAL_TYPES.has(f.type) && (f.severity === 'critical' || f.severity === 'high'));
+    if (hasPartialFailure) {
+        const verifiable = claimsTotal - claimsSkipped;
+        const verifiedRatio = verifiable > 0 ? claimsVerified / verifiable : 1;
+        if (verifiedRatio < 0.3) {
+            return {
+                resolved: false,
+                resolutionNote: `Only ${Math.round(verifiedRatio * 100)}% of claims verified due to incomplete data.`,
+            };
+        }
+    }
+    return { resolved: true };
+}
+function buildRootCauseSummary(detectedFailures, hypotheses) {
+    if (detectedFailures.length === 0 && hypotheses.length === 0)
+        return {};
+    const primaries = detectedFailures
+        .filter((f) => f.role === 'primary')
+        .sort((a, b) => (SEVERITY_ORDER[b.severity] ?? 0) - (SEVERITY_ORDER[a.severity] ?? 0));
+    const secondaries = detectedFailures.filter((f) => f.role === 'secondary');
+    if (primaries.length === 0) {
+        // Only hypotheses, no confirmed failures
+        const hypoLine = hypotheses.length > 0
+            ? `${hypotheses.length} low-confidence hypothesis(es) detected but no confirmed failures.`
+            : undefined;
+        return { summary: hypoLine };
+    }
+    // --- rootCause: one-sentence from highest-severity primary ---
+    const top = primaries[0];
+    const rootCause = top.diagnosis
+        ? `[${top.type}] ${top.diagnosis}`
+        : `[${top.type}] ${top.description}`;
+    // --- repair sequence: topological order from suppression graph ---
+    const activeTypes = detectedFailures
+        .filter((f) => f.role === 'primary' || f.role === 'secondary')
+        .map((f) => f.type);
+    const repairSequence = (0, Registry_1.getRepairOrder)(activeTypes);
+    // --- summary: multi-line narrative ---
+    const lines = [];
+    // Primary failures
+    lines.push(`${primaries.length} primary failure(s) detected:`);
+    for (const f of primaries) {
+        const diag = f.diagnosis ? ` — ${f.diagnosis}` : '';
+        const fix = f.suggestedFix ? ` Fix: ${f.suggestedFix}` : '';
+        lines.push(`  • [${f.severity.toUpperCase()}] ${f.type}: ${f.description}${diag}${fix}`);
+    }
+    // Secondary (suppressed) failures
+    if (secondaries.length > 0) {
+        lines.push(`${secondaries.length} secondary failure(s) (caused by primary):`);
+        for (const f of secondaries) {
+            lines.push(`  • ${f.type} (suppressed by ${f.suppressedBy})`);
+        }
+    }
+    // Hypotheses
+    if (hypotheses.length > 0) {
+        lines.push(`${hypotheses.length} hypothesis(es) for human review.`);
+    }
+    // Repair sequence
+    if (repairSequence.length > 1) {
+        lines.push('Recommended repair order:');
+        for (let i = 0; i < repairSequence.length; i++) {
+            const step = repairSequence[i];
+            lines.push(`  ${i + 1}. ${step.type} — ${step.reason}`);
+        }
+    }
+    return { rootCause, summary: lines.join('\n'), repairSequence };
+}
+/**
+ * Main entry point for grounding validation.
+// ---------------------------------------------------------------------------
+// Report confidence — meta-assessment of the analysis itself
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute how much we trust the grounding report.
+ *
+ * This is NOT the grounding score — it answers a different question:
+ * "Given the trace quality and claim coverage, should the user trust this report?"
+ *
+ * Logic:
+ * 1. Hard blockers → instant "low" (no tool_outputs, no final_response, 0 claims, completeness < 35%)
+ * 2. Weighted composite score from 3 factors:
+ *    - Trace completeness (55%) — from TraceReadiness
+ *    - Grounded ratio (30%) — verified / verifiable claims
+ *    - cannotVerify penalty (15%) — -0.05 per disabled check
+ * 3. Map score to tier: >= 0.80 → high, 0.50–0.79 → medium, < 0.50 → low
+ */
+function computeReportConfidence(input) {
+    const { traceQuality, claimsTotal, claimsVerified, claimsSkipped } = input;
+    const reasons = [];
+    // --- Hard blockers → instant low ---
+    const hasToolOutputs = traceQuality.checklist.some((c) => c.element === 'tool_outputs' && c.present);
+    const hasFinalResponse = traceQuality.checklist.some((c) => c.element === 'final_response' && c.present);
+    if (!hasFinalResponse) {
+        reasons.push('missing_final_response');
+        return {
+            level: 'low',
+            score: 0,
+            note: 'No final response found in trace — nothing to analyse.',
+            reasons,
+        };
+    }
+    if (!hasToolOutputs) {
+        reasons.push('missing_tool_outputs');
+        return {
+            level: 'low',
+            score: 0.1,
+            note: 'No tool outputs in trace — claims cannot be verified against source data.',
+            reasons,
+        };
+    }
+    if (claimsTotal === 0) {
+        reasons.push('no_claims_extracted');
+        return {
+            level: 'low',
+            score: 0.15,
+            note: 'No verifiable claims found in the response — analysis has nothing to check.',
+            reasons,
+        };
+    }
+    if (traceQuality.completeness < 35) {
+        reasons.push('trace_too_incomplete');
+        return {
+            level: 'low',
+            score: 0.2,
+            note: `Trace completeness is only ${traceQuality.completeness}% — too little data for reliable analysis.`,
+            reasons,
+        };
+    }
+    // --- Factor A: Trace completeness (55% weight) ---
+    const completenessScore = traceQuality.completeness / 100;
+    if (traceQuality.quality === 'HIGH')
+        reasons.push('complete_trace');
+    else if (traceQuality.quality === 'MEDIUM')
+        reasons.push('partial_trace');
+    // --- Factor B: Grounded ratio (30% weight) ---
+    const verifiable = claimsTotal - claimsSkipped;
+    const groundedRatio = verifiable > 0 ? claimsVerified / verifiable : 0;
+    if (groundedRatio >= 0.8)
+        reasons.push('high_grounded_ratio');
+    else if (groundedRatio >= 0.5)
+        reasons.push('moderate_grounded_ratio');
+    else
+        reasons.push('low_grounded_ratio');
+    if (verifiable >= 3)
+        reasons.push('sufficient_claims');
+    else
+        reasons.push('few_verifiable_claims');
+    // --- Factor C: cannotVerify penalty (15% weight) ---
+    const cannotVerifyCount = traceQuality.cannotVerify.length;
+    // Each disabled check costs 0.05, capped at 1.0 total penalty
+    const cannotVerifyPenalty = Math.min(1.0, cannotVerifyCount * 0.05);
+    const cannotVerifyFactor = 1.0 - cannotVerifyPenalty;
+    if (cannotVerifyCount > 0)
+        reasons.push(`disabled_checks_${cannotVerifyCount}`);
+    // --- Composite score ---
+    const score = Math.max(0, Math.min(1, completenessScore * 0.55 +
+        groundedRatio * 0.30 +
+        cannotVerifyFactor * 0.15));
+    // --- Map to tier ---
+    let level;
+    if (score >= 0.80)
+        level = 'high';
+    else if (score >= 0.50)
+        level = 'medium';
+    else
+        level = 'low';
+    // --- Build note ---
+    let note;
+    if (level === 'high') {
+        note = 'Analysis is reliable — complete trace with sufficient verified claims.';
+    }
+    else if (level === 'medium') {
+        const caveats = [];
+        if (traceQuality.quality !== 'HIGH')
+            caveats.push('trace is partially complete');
+        if (verifiable < 3)
+            caveats.push('few verifiable claims');
+        if (groundedRatio < 0.8)
+            caveats.push('not all claims could be verified');
+        if (cannotVerifyCount > 0)
+            caveats.push(`${cannotVerifyCount} check(s) disabled`);
+        note = `Analysis may be incomplete: ${caveats.join(', ')}.`;
+    }
+    else {
+        note = 'Analysis has limited reliability — results should be treated with caution.';
+    }
+    return { level, score: Math.round(score * 100) / 100, note, reasons };
+}
+class GroundingEngine {
+    constructor(options = {}) {
+        if (options.configFile) {
+            this.tolerances = (0, Config_1.loadTolerancesFromFile)(options.configFile);
+        }
+        else {
+            this.tolerances = {
+                ...types_1.DEFAULT_TOLERANCES,
+                ...(options.tolerances ?? {}),
+            };
+        }
+    }
+    /**
+     * Evaluate a trace and return a {@link GroundingReport}.
+     */
+    /**
+     * Evaluate a trace and return a {@link GroundingReport}.
+     * @param trace The trace to evaluate
+     * @param mode 'guardrail' (default) or 'analytics'. In guardrail mode, only S/A tier failures are returned in detectedFailures; others go to hypotheses.
+     */
+    evaluate(trace, mode = 'guardrail') {
+        // Normalise external trace formats (OpenAI, Anthropic, custom) to TG
+        // canonical roles before any processing. This is idempotent.
+        Trace_1.TraceUtils.normalizeTrace(trace);
+        // Multi-turn: scope evaluation to the active (last) turn only.
+        // The original trace is kept for metadata; the scoped trace is used for
+        // claims extraction, grounding, and rule detection.
+        const isMultiTurn = Trace_1.TraceUtils.isMultiTurn(trace);
+        const turns = Trace_1.TraceUtils.getConversationTurns(trace);
+        const turnCount = turns.length;
+        const evalTrace = isMultiTurn ? Trace_1.TraceUtils.buildActiveTurnTrace(trace) : trace;
+        // 1. Find the final response step
+        const finalStep = Trace_1.TraceUtils.getFinalResponse(evalTrace);
+        const responseText = finalStep?.content ?? '';
+        // 1b. Early exit for error responses (HTTP 529, API failures, etc.)
+        // When the AI service returned an error instead of a real response,
+        // skip claim extraction and rule detection entirely — only report
+        // ai_unavailable. This prevents false positives from extracting
+        // HTTP status codes as numeric claims, instruction_violation on
+        // error messages, or data_ignored when AI never responded.
+        if (finalStep && isErrorResponse(finalStep)) {
+            const errorFailure = detectAIUnavailableFromStep(finalStep);
+            return {
+                traceId: trace.traceId,
+                generatedAt: new Date().toISOString(),
+                claimsTotal: 0,
+                claimsVerified: 0,
+                claimsSkipped: 0,
+                claimsFailed: 0,
+                groundingScore: 1.0,
+                verdicts: [],
+                detectedFailures: errorFailure ? [errorFailure] : [],
+                hypotheses: [],
+                failureCounts: { high: errorFailure ? 1 : 0, medium: 0, low: 0 },
+                tolerancesUsed: this.tolerances,
+                traceQuality: (0, TraceReadiness_1.assessTraceQuality)(trace),
+                rootCause: errorFailure?.type ?? undefined,
+                summary: errorFailure?.description ?? 'AI service error — no response to evaluate.',
+                repairSequence: [],
+                resolved: false,
+                resolutionNote: 'AI service did not produce a response.',
+                reportConfidence: {
+                    level: 'low',
+                    score: 0,
+                    note: 'AI service returned an error — no response to analyse.',
+                    reasons: ['ai_service_error'],
+                },
+                ...(isMultiTurn ? { turnCount, activeTurnIndex: turnCount - 1 } : {}),
+            };
+        }
+        // 2. Extract claims (L1: regex-based)
+        // Pass trace startedAt as reference date so relative-date resolution
+        // ("sutra", "yesterday") uses the correct temporal context.
+        const refDate = evalTrace.startedAt
+            ? new Date(evalTrace.startedAt)
+            : undefined;
+        const l1Claims = finalStep
+            ? (0, Claims_1.extractClaims)(responseText, {
+                sourceStepId: finalStep.stepId,
+                sourceRole: 'final_response',
+                referenceDate: refDate,
+            })
+            : [];
+        // 2b. Extract L2 structured context claims
+        const l2Claims = finalStep
+            ? [
+                ...(0, L2_1.extractStructuredClaims)(evalTrace, responseText, finalStep.stepId),
+                ...(0, L2_1.extractListItemsClaims)(evalTrace, responseText, finalStep.stepId),
+                ...(0, L2_1.extractKeyValueClaims)(evalTrace, responseText, finalStep.stepId),
+                ...(0, L2_1.extractAggregationClaims)(evalTrace, responseText, finalStep.stepId),
+                ...(0, L2_1.extractRangeClaims)(evalTrace, responseText, finalStep.stepId),
+            ]
+            : [];
+        // Cross-layer deduplication: when L2 produces a claim covering the same
+        // numeric value as an L1 claim, the L2 claim is more precise (has
+        // sourceFieldValue, aggregationOp, etc.) and should take precedence.
+        // This prevents L1 "number" claims from scoring UNGROUNDED for values
+        // that L2 correctly identifies as SUM/AVG/aggregation.
+        const l2CoveredValues = new Set();
+        for (const c of l2Claims) {
+            if (typeof c.value === 'number')
+                l2CoveredValues.add(c.value);
+            if (c.type === 'aggregation' && c.computedValue !== undefined) {
+                l2CoveredValues.add(c.computedValue);
+            }
+        }
+        const dedupedL1 = l1Claims.filter((c) => {
+            if ((c.type === 'number' || c.type === 'count') && typeof c.value === 'number') {
+                return !l2CoveredValues.has(c.value);
+            }
+            return true;
+        });
+        const claims = [...dedupedL1, ...l2Claims];
+        // 2d. Extract single-word name claims from tool context
+        if (finalStep) {
+            const contextNames = extractToolContextNameClaims(evalTrace, responseText, finalStep.stepId, claims);
+            claims.push(...contextNames);
+        }
+        // 2c. Enrich claims with period from tool call parameters
+        const period = Trace_1.TraceUtils.inferPeriod(evalTrace);
+        if (period) {
+            for (const claim of claims) {
+                if (!claim.period)
+                    claim.period = period;
+            }
+        }
+        // 3. Ground each claim
+        // For multi-turn traces, if a claim is UNGROUNDED or UNVERIFIABLE against
+        // the active turn, try the full trace as fallback (the response may
+        // reference data from earlier turns in the conversation).
+        const verdicts = claims.map((claim) => {
+            const v = groundClaim(claim, evalTrace, this.tolerances);
+            if (isMultiTurn &&
+                (v.verdict === 'UNGROUNDED' || v.verdict === 'UNVERIFIABLE') &&
+                evalTrace !== trace) {
+                const fullV = groundClaim(claim, trace, this.tolerances);
+                if (fullV.verdict === 'GROUNDED' || fullV.verdict === 'APPROXIMATE_MATCH') {
+                    return fullV;
+                }
+            }
+            return v;
+        });
+        // 4. Detect multi-step claims: UNVERIFIABLE where multiple tool calls exist
+        // and the claim may depend on combined outputs — upgrade to MULTI_STEP
+        const toolCallCount = Trace_1.TraceUtils.getAllToolCalls(evalTrace).length;
+        const processedVerdicts = verdicts.map((v) => {
+            if (v.verdict === 'UNVERIFIABLE' && toolCallCount > 1) {
+                return {
+                    ...v,
+                    verdict: 'MULTI_STEP',
+                    explanation: v.explanation +
+                        ' Multiple tool calls present — verification may require cross-step analysis.',
+                    ruleUsed: 'multi_step',
+                };
+            }
+            return v;
+        });
+        // 5. Run grounding failure rules
+        // Pass the full trace as well so cross-turn rules (e.g.
+        // stale_cross_turn_reuse) can see all conversation turns.
+        const allFindings = (0, Rules_1.runAllRules)(evalTrace, claims, processedVerdicts, trace);
+        let detectedFailures;
+        let hypotheses;
+        if (mode === 'guardrail') {
+            // Only S/A tier (block/warn) go to detectedFailures, others to hypotheses
+            detectedFailures = allFindings.filter((f) => {
+                const reg = Registry_1.FAILURE_REGISTRY.find(r => r.type === f.type);
+                return reg && (reg.tier === 'S' || reg.tier === 'A') && f.confidence !== 'low';
+            });
+            hypotheses = allFindings.filter((f) => {
+                const reg = Registry_1.FAILURE_REGISTRY.find(r => r.type === f.type);
+                return !reg || (reg.tier !== 'S' && reg.tier !== 'A') || f.confidence === 'low';
+            });
+        }
+        else {
+            detectedFailures = allFindings.filter((f) => f.confidence !== 'low');
+            hypotheses = allFindings.filter((f) => f.confidence === 'low');
+        }
+        // 6. Compute aggregate stats
+        const claimsTotal = claims.length;
+        const claimsVerified = processedVerdicts.filter((v) => v.verdict === 'GROUNDED' || v.verdict === 'APPROXIMATE_MATCH').length;
+        const claimsSkipped = processedVerdicts.filter((v) => v.verdict === 'UNVERIFIABLE' || v.verdict === 'MULTI_STEP').length;
+        const claimsFailed = processedVerdicts.filter((v) => v.verdict === 'UNGROUNDED').length;
+        // ═══════════════════════════════════════════════════════════════════
+        // PHASE 1 — Claim-based score
+        // Ratio of verified claim weight to total claim weight, using
+        // severity tiers (HIGH = 3, MEDIUM = 2, LOW = 1).  Defaults to
+        // 1.0 when there are no verifiable claims.  Three zero-score
+        // guards then correct vacuously-true or entirely-ungrounded cases.
+        // ═══════════════════════════════════════════════════════════════════
+        // In guardrail mode, aggregation and list_items claims (red zone — high FP)
+        // are excluded from score calculation. They still appear in verdicts.
+        const GUARDRAIL_SCORE_EXCLUDED_TYPES = new Set(['aggregation', 'list_items']);
+        const SEVERITY_WEIGHT = { HIGH: 3, MEDIUM: 2, LOW: 1 };
+        const verifiableVerdicts = processedVerdicts.filter((v) => v.verdict !== 'UNVERIFIABLE' && v.verdict !== 'MULTI_STEP'
+            && (mode !== 'guardrail' || !GUARDRAIL_SCORE_EXCLUDED_TYPES.has(v.claim.type)));
+        // All non-UNVERIFIABLE/MULTI_STEP verdicts (for severity assignment)
+        const allVerifiableVerdicts = processedVerdicts.filter((v) => v.verdict !== 'UNVERIFIABLE' && v.verdict !== 'MULTI_STEP');
+        let totalWeight = 0;
+        let verifiedWeight = 0;
+        for (const v of allVerifiableVerdicts) {
+            const sev = computeSeverity(v);
+            v.severity = sev;
+        }
+        for (const v of verifiableVerdicts) {
+            const w = SEVERITY_WEIGHT[v.severity];
+            totalWeight += w;
+            if (v.verdict === 'GROUNDED' || v.verdict === 'APPROXIMATE_MATCH') {
+                verifiedWeight += w;
+            }
+        }
+        let groundingScore = totalWeight > 0 ? verifiedWeight / totalWeight : 1.0;
+        // Zero-score guards — force 0 when the response has no grounding
+        // substance.  Each branch captures a distinct failure mode:
+        //   (a) 0 claims + tool data exists → response ignored data entirely
+        //   (b) incomplete_response fired + 0 claims → vacuously true 1.0
+        //   (c) no_tool_call + all claims unverified + single-turn → ungrounded
+        const hasIncompleteResponse = detectedFailures.some((f) => f.type === 'grounding.incomplete_response');
+        const hasNoToolCall = detectedFailures.some((f) => f.type === 'grounding.no_tool_call');
+        const isFollowUp = turnCount > 1;
+        if (claimsTotal === 0) {
+            const toolOutputSteps = Trace_1.TraceUtils.getToolOutputSteps(evalTrace);
+            const hasToolData = toolOutputSteps.some((step) => (step.toolOutputs ?? []).some((to) => {
+                if (isEmptyResultOutput(to.output))
+                    return false;
+                const vals = (0, Matchers_1.extractValuesFromOutput)(to.output);
+                return vals.length > 0;
+            }));
+            if (hasToolData || hasIncompleteResponse) {
+                groundingScore = 0;
+            }
+        }
+        else if (hasNoToolCall && claimsVerified === 0 && !isFollowUp) {
+            groundingScore = 0;
+        }
+        // ═══════════════════════════════════════════════════════════════════
+        // PHASE 2 — Structural adjustments
+        // Penalties from structural failures (arithmetic errors, fabrication,
+        // tool budget exhaustion, etc.) that are NOT reflected in claim
+        // verdicts, plus a hard cap when all tool calls errored.
+        // ═══════════════════════════════════════════════════════════════════
+        const FAILURE_PENALTY = {
+            critical: 0.15,
+            high: 0.10,
+            medium: 0.05,
+            low: 0.02,
+        };
+        const primaryFailures = detectedFailures.filter((f) => f.role === 'primary');
+        let totalPenalty = 0;
+        for (const f of primaryFailures) {
+            totalPenalty += FAILURE_PENALTY[f.severity] ?? 0.05;
+        }
+        if (totalPenalty > 0) {
+            groundingScore = Math.max(0, groundingScore - totalPenalty);
+        }
+        // When EVERY tool call in the active turn returned an error/not-found,
+        // the AI had zero valid data — cap the score at 0.30.
+        const activeToolOutputs = Trace_1.TraceUtils.getActiveToolOutputs(evalTrace);
+        if (activeToolOutputs.length >= 2) {
+            const allErrors = activeToolOutputs.every((to) => {
+                const outputStr = typeof to.output === 'string'
+                    ? to.output
+                    : JSON.stringify(to.output ?? '');
+                return /\berror\b/i.test(outputStr) || /\bnot\s+found\b/i.test(outputStr)
+                    || /\blimit poziva\b/i.test(outputStr);
+            });
+            if (allErrors) {
+                groundingScore = Math.min(groundingScore, 0.30);
+            }
+        }
+        const { rootCause, summary: rcaSummary, repairSequence } = buildRootCauseSummary(detectedFailures, hypotheses);
+        // --- Resolution assessment ---
+        const { resolved, resolutionNote } = assessResolution(detectedFailures, claimsTotal, claimsVerified, claimsSkipped);
+        // --- Report confidence (meta-assessment of the analysis itself) ---
+        const traceQuality = (0, TraceReadiness_1.assessTraceQuality)(trace);
+        const reportConfidence = computeReportConfidence({
+            traceQuality,
+            claimsTotal,
+            claimsVerified,
+            claimsSkipped,
+            groundingScore,
+        });
+        return {
+            traceId: trace.traceId,
+            generatedAt: new Date().toISOString(),
+            claimsTotal,
+            claimsVerified,
+            claimsSkipped,
+            claimsFailed,
+            groundingScore,
+            verdicts: processedVerdicts,
+            detectedFailures,
+            hypotheses,
+            failureCounts: {
+                high: allFindings.filter((f) => f.confidence === 'high').length,
+                medium: allFindings.filter((f) => f.confidence === 'medium').length,
+                low: hypotheses.length,
+            },
+            tolerancesUsed: this.tolerances,
+            traceQuality,
+            rootCause,
+            summary: rcaSummary,
+            repairSequence,
+            resolved,
+            resolutionNote,
+            reportConfidence,
+            ...(isMultiTurn ? { turnCount, activeTurnIndex: turnCount - 1 } : {}),
+        };
+    }
+}
+exports.GroundingEngine = GroundingEngine;
+//# sourceMappingURL=index.js.map