truthguard-ai 0.2.0 → 0.3.0

package/dist-npm/Registry/index.js

@@ -0,0 +1,818 @@
+"use strict";
+/**
+ * TruthGuard Failure Registry — Machine-Readable Source of Truth
+ *
+ * Central catalog of all failure types with metadata:
+ * severity, category, blockability, suppression rules, version status.
+ *
+ * This is the SINGLE source of truth — docs and UI derive from this.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAILURE_REGISTRY = void 0;
+exports.getRegistryEntry = getRegistryEntry;
+exports.getDefaultSeverity = getDefaultSeverity;
+exports.getDefaultAction = getDefaultAction;
+exports.getByCategory = getByCategory;
+exports.computeSeverity = computeSeverity;
+exports.getSuppressedTypes = getSuppressedTypes;
+exports.compareSeverity = compareSeverity;
+exports.getRepairOrder = getRepairOrder;
+exports.getTierMaxAction = getTierMaxAction;
+exports.capActionToTier = capActionToTier;
+// ---------------------------------------------------------------------------
+// The Registry
+// ---------------------------------------------------------------------------
+exports.FAILURE_REGISTRY = [
+    // ── Grounding ──────────────────────────────────────────────
+    {
+        type: 'grounding.empty_fabrication',
+        label: 'Empty Fabrication',
+        category: 'grounding',
+        defaultSeverity: 'critical',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'Agent produced claims with no tool data whatsoever — pure hallucination.',
+        suppresses: [
+            'grounding.data_ignored',
+            'grounding.irrelevant_context',
+            'reasoning.overconfident_language',
+        ],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'grounding.no_tool_call',
+        label: 'No Tool Call',
+        category: 'grounding',
+        defaultSeverity: 'high',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'Agent answered a factual question without calling any tools.',
+        suppresses: [
+            'grounding.irrelevant_context',
+            'reasoning.overconfident_language',
+            'grounding.unverified_value',
+        ],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'grounding.unverified_value',
+        label: 'Unverified Value',
+        category: 'grounding',
+        defaultSeverity: 'medium',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'Tools were called but specific values in the response could not be verified in tool outputs.',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'grounding.math_error',
+        label: 'Math Error',
+        category: 'grounding',
+        defaultSeverity: 'high',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'Numeric claim deviates significantly from tool output values, or inline arithmetic/unit conversion is wrong.',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'grounding.data_ignored',
+        label: 'Data Ignored',
+        category: 'grounding',
+        defaultSeverity: 'high',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'Tool returned data but agent used a different, ungrounded value, or omitted significant data without instruction to summarize.',
+        suppresses: ['reasoning.overconfident_language'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'grounding.wrong_query',
+        label: 'Wrong Query',
+        category: 'grounding',
+        defaultSeverity: 'high',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'Tool was called with parameters that don\'t match user\'s question.',
+        suppresses: ['grounding.irrelevant_context', 'reasoning.scope_mismatch'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'grounding.incomplete_response',
+        label: 'Incomplete Response',
+        category: 'grounding',
+        defaultSeverity: 'medium',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'Tools returned data but agent produced empty or trivial response.',
+        suppresses: ['grounding.question_not_answered'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'grounding.contradictory_claims',
+        label: 'Contradictory Claims',
+        category: 'grounding',
+        defaultSeverity: 'high',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'Agent made multiple claims that contradict each other.',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'legal'],
+        tier: 'C',
+    },
+    {
+        type: 'grounding.tool_error_ignored',
+        label: 'Tool Error Ignored',
+        category: 'grounding',
+        defaultSeverity: 'high',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'Tool returned an error but agent proceeded as if it succeeded.',
+        suppresses: [
+            'grounding.data_ignored',
+            'grounding.irrelevant_context',
+            'reasoning.overconfident_language',
+        ],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'grounding.excessive_tool_calls',
+        label: 'Excessive Tool Calls',
+        category: 'grounding',
+        defaultSeverity: 'medium',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'Agent called the same tool repeatedly, suggesting a loop or retry storm.',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'grounding.stale_knowledge',
+        label: 'Stale Knowledge',
+        category: 'grounding',
+        defaultSeverity: 'medium',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'Agent used outdated information when fresher tool data was available.',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'legal'],
+        tier: 'B',
+    },
+    {
+        type: 'grounding.irrelevant_context',
+        label: 'Irrelevant Context',
+        category: 'grounding',
+        defaultSeverity: 'medium',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'Tool returned data unrelated to the user\'s question.',
+        suppresses: [],
+        industries: ['healthcare', 'logistics'],
+        tier: 'C',
+    },
+    {
+        type: 'grounding.hallucinated_entity',
+        label: 'Hallucinated Entity',
+        category: 'grounding',
+        defaultSeverity: 'high',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'Agent mentioned a person or entity name not found in any tool output or system prompt.',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'grounding.question_not_answered',
+        label: 'Question Not Answered',
+        category: 'grounding',
+        defaultSeverity: 'high',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'Agent returned correct data but did not perform the operation the user asked for, or only addressed some parts of a multi-part question.',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    // ── Reasoning ──────────────────────────────────────────────
+    {
+        type: 'reasoning.scope_mismatch',
+        label: 'Scope Mismatch',
+        category: 'reasoning',
+        defaultSeverity: 'high',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'Agent applied narrow/filtered data to answer a broad or different scope question.',
+        suppresses: [],
+        industries: ['hr', 'finance', 'logistics'],
+        tier: 'B',
+    },
+    {
+        type: 'reasoning.overconfident_language',
+        label: 'Overconfident Language',
+        category: 'reasoning',
+        defaultSeverity: 'low',
+        defaultAction: 'observe',
+        status: 'stable',
+        description: 'Agent used certainty language ("exactly", "confirmed") on approximate/unverifiable data.',
+        suppresses: [],
+        industries: ['finance', 'healthcare', 'legal'],
+        tier: 'B',
+    },
+    {
+        type: 'reasoning.language_mismatch',
+        label: 'Language Mismatch',
+        category: 'reasoning',
+        defaultSeverity: 'medium',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'Agent responded in a different language than the user\'s input (e.g., English reply to Serbian question).',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'B',
+    },
+    // ── Orchestration ──────────────────────────────────────────
+    {
+        type: 'orchestration.malformed_tool_input',
+        label: 'Malformed Tool Input',
+        category: 'orchestration',
+        defaultSeverity: 'high',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'Tool was called with empty or structurally invalid input, causing an API validation error.',
+        suppresses: [
+            'grounding.tool_error_ignored',
+            'grounding.excessive_tool_calls',
+        ],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'orchestration.raw_output_leak',
+        label: 'Raw Output Leak',
+        category: 'orchestration',
+        defaultSeverity: 'critical',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'Final response contains raw tool call markup (XML/JSON) instead of a user-facing answer.',
+        suppresses: [
+            'grounding.incomplete_response',
+            'grounding.hallucinated_entity',
+        ],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'orchestration.intermediate_response_leak',
+        label: 'Intermediate Response Leak',
+        category: 'orchestration',
+        defaultSeverity: 'high',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'Final response contains intermediate LLM reasoning or planning text instead of a synthesized answer.',
+        suppresses: [
+            'grounding.incomplete_response',
+        ],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'orchestration.token_limit_truncation',
+        label: 'Token Limit Truncation',
+        category: 'orchestration',
+        defaultSeverity: 'high',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'Response was truncated because the model hit the token limit (finish_reason: length).',
+        suppresses: [
+            'grounding.incomplete_response',
+            'grounding.question_not_answered',
+        ],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'orchestration.rate_limit_degradation',
+        label: 'Rate Limit Degradation',
+        category: 'orchestration',
+        defaultSeverity: 'high',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'API rate limit (429) was hit during execution, potentially degrading response quality.',
+        suppresses: [
+            'grounding.tool_error_ignored',
+            'grounding.incomplete_response',
+        ],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'orchestration.quota_exhaustion',
+        label: 'Quota Exhaustion',
+        category: 'orchestration',
+        defaultSeverity: 'critical',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'API quota or billing limit reached (402/quota errors), causing degraded or fabricated responses.',
+        suppresses: [
+            'grounding.empty_fabrication',
+            'grounding.tool_error_ignored',
+            'grounding.incomplete_response',
+        ],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'orchestration.model_fallback',
+        label: 'Model Fallback',
+        category: 'orchestration',
+        defaultSeverity: 'medium',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'A different (potentially lower-tier) model was used than what was requested.',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'B',
+    },
+    // ── Safety ─────────────────────────────────────────────────
+    {
+        type: 'safety.prompt_leak',
+        label: 'Prompt Leak',
+        category: 'safety',
+        defaultSeverity: 'critical',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'System prompt content was exposed in the agent\'s response.',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'safety.sensitive_data_exposure',
+        label: 'Sensitive Data Exposure',
+        category: 'safety',
+        defaultSeverity: 'critical',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'Response contains PII, credentials, or other sensitive data patterns.',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'grounding.entity_value_swap',
+        label: 'Entity Value Swap',
+        category: 'grounding',
+        defaultSeverity: 'high',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'Values from different entities were swapped — entity A\'s data was attributed to entity B.',
+        suppresses: ['grounding.contradictory_claims'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'reasoning.instruction_violation',
+        label: 'Instruction Violation',
+        category: 'reasoning',
+        defaultSeverity: 'high',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'Response violates an explicit system prompt directive (e.g., forbidden content, required format).',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'B',
+    },
+    // ── Instrumentation ────────────────────────────────────────────
+    {
+        type: 'instrumentation.duplicate_user_input',
+        label: 'Duplicate User Input',
+        category: 'instrumentation',
+        defaultSeverity: 'medium',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'Identical user input appears consecutively — the agent framework is double-sending or replaying messages.',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'B',
+    },
+    // ── Orchestration: Tool Budget ─────────────────────────────────
+    {
+        type: 'orchestration.tool_budget_exhaustion',
+        label: 'Tool Budget Exhaustion',
+        category: 'orchestration',
+        defaultSeverity: 'medium',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'The agent hit the platform tool-call limit before completing the task, forcing a premature answer based on incomplete data.',
+        suppresses: ['grounding.question_not_answered', 'grounding.incomplete_response', 'grounding.data_ignored', 'grounding.stale_cross_turn_reuse'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'B',
+    },
+    {
+        type: 'orchestration.tool_period_mismatch',
+        label: 'Tool Period Mismatch',
+        category: 'orchestration',
+        defaultSeverity: 'high',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'Tool was called with correct date parameters but returned data for a different time period.',
+        suppresses: ['grounding.data_ignored', 'grounding.wrong_query'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'grounding.stale_cross_turn_reuse',
+        label: 'Stale Cross-Turn Reuse',
+        category: 'grounding',
+        defaultSeverity: 'high',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'Response uses numeric values from earlier conversation turns without making fresh tool calls in the current turn.',
+        suppresses: ['grounding.data_ignored', 'grounding.unverified_value'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'orchestration.tool_capability_gap',
+        label: 'Tool Capability Gap',
+        category: 'orchestration',
+        defaultSeverity: 'medium',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'Tool returned empty results for a query the user expected to work, because the tool does not support that search type or filter.',
+        suppresses: ['grounding.incomplete_response', 'grounding.question_not_answered'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'B',
+    },
+    {
+        type: 'grounding.period_label_mismatch',
+        label: 'Period Label Mismatch',
+        category: 'grounding',
+        defaultSeverity: 'high',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'Response labels data as belonging to a specific time period (e.g. Q1, March) but the actual dates in tool output correspond to a different period.',
+        suppresses: ['grounding.data_ignored', 'reasoning.overconfident_language'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'grounding.aggregation_scope_error',
+        label: 'Aggregation Scope Error',
+        category: 'grounding',
+        defaultSeverity: 'high',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'An aggregation (sum, average, etc.) was computed over the wrong subset of data — typically a period mismatch between what the user requested and what was actually summed.',
+        suppresses: ['grounding.question_not_answered'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'grounding.missing_grouping',
+        label: 'Missing Grouping Dimension',
+        category: 'grounding',
+        defaultSeverity: 'high',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'User asked for results grouped by a dimension (e.g. "by department", "per sector") but the response provides a single flat aggregate without the requested breakdown.',
+        suppresses: ['grounding.question_not_answered', 'grounding.data_ignored'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'reasoning.transformational_intent',
+        label: 'Unverified Transformation',
+        category: 'reasoning',
+        defaultSeverity: 'medium',
+        defaultAction: 'observe',
+        status: 'stable',
+        description: 'The user\'s question implies a business-logic transformation (net/gross, after-tax, discount, derived metric) that cannot be verified from raw tool output alone. The response may be using raw values instead of the transformed ones.',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'legal'],
+        tier: 'B',
+    },
+    {
+        type: 'grounding.metric_mismatch',
+        label: 'Metric Type Mismatch',
+        category: 'grounding',
+        defaultSeverity: 'high',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'The user requested a specific aggregation type (e.g. average) but the response contains a different aggregation (e.g. sum) computed from the same data.',
+        suppresses: ['grounding.question_not_answered', 'grounding.math_error'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'reasoning.partial_period_risk',
+        label: 'Partial Period Data',
+        category: 'reasoning',
+        defaultSeverity: 'medium',
+        defaultAction: 'observe',
+        status: 'stable',
+        description: 'The user asked about a period that is currently ongoing (e.g. "this month", "this quarter", YTD). Data for this period is inherently incomplete and aggregations may change by period end.',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'B',
+    },
+    {
+        type: 'orchestration.ai_unavailable',
+        label: 'AI Service Unavailable',
+        category: 'orchestration',
+        defaultSeverity: 'high',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'The AI service was unavailable (timeout, overloaded, rate-limited, insufficient credits) and returned an error instead of a response. The user received a fallback error message rather than an AI-generated answer.',
+        suppresses: ['grounding.empty_fabrication', 'grounding.no_tool_call', 'grounding.incomplete_response', 'grounding.question_not_answered'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'orchestration.answer_refusal',
+        label: 'Answer Refusal',
+        category: 'orchestration',
+        defaultSeverity: 'critical',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'The AI explicitly refused or admitted it cannot answer the user question, despite having tools available. The response contains refusal phrases like "I cannot confirm", "I was unable to", or explicit failure markers.',
+        suppresses: ['grounding.question_not_answered'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'orchestration.tool_selection_error',
+        label: 'Wrong Tool Selection',
+        category: 'orchestration',
+        defaultSeverity: 'high',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'The AI selected inappropriate tools for the task, repeatedly calling the same ineffective tool or ignoring better-suited alternatives. Often co-occurs with tool_budget_exhaustion.',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'orchestration.tool_output_error',
+        label: 'Tool Output Error',
+        category: 'orchestration',
+        defaultSeverity: 'high',
+        defaultAction: 'warn',
+        status: 'stable',
+        description: 'A tool call returned an error (SQL error, runtime exception, API failure) instead of valid data. The AI may have proceeded without acknowledging the error or retrying with corrected parameters.',
+        suppresses: [],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'orchestration.fabricated_tool_input',
+        label: 'Fabricated Tool Input',
+        category: 'orchestration',
+        defaultSeverity: 'critical',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'The AI fabricated tool call parameter values (e.g. entity IDs, person_keys) that do not appear in any prior tool output. The tool returned errors for all fabricated values.',
+        suppresses: ['grounding.hallucinated_entity', 'orchestration.tool_selection_error', 'orchestration.tool_capability_gap'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'support', 'logistics'],
+        tier: 'S',
+    },
+    {
+        type: 'reasoning.percentage_error',
+        label: 'Percentage Calculation Error',
+        category: 'reasoning',
+        defaultSeverity: 'high',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'Agent computed a percentage incorrectly — wrong percentage-of-total, percentage change, or share calculation from tool output values.',
+        suppresses: ['grounding.math_error'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'reasoning.ratio_error',
+        label: 'Ratio / Proportion Error',
+        category: 'reasoning',
+        defaultSeverity: 'high',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'Agent stated a ratio or proportion that does not match the underlying data — e.g. "3:1 ratio" when data shows 2:1, or "3 out of 5" when data shows 2 out of 5.',
+        suppresses: ['grounding.math_error'],
+        industries: ['hr', 'finance', 'healthcare', 'legal', 'logistics'],
+        tier: 'A',
+    },
+    {
+        type: 'reasoning.multiplication_error',
+        label: 'Multiplication / Division Error',
+        category: 'reasoning',
+        defaultSeverity: 'high',
+        defaultAction: 'block',
+        status: 'stable',
+        description: 'Agent computed a product or quotient incorrectly — e.g. unit price × quantity ≠ total, or total / count ≠ per-unit value.',
+        suppresses: ['grounding.math_error'],
+        industries: ['finance', 'accounting', 'hr', 'logistics', 'legal'],
+        tier: 'A',
+    },
+];
+// ---------------------------------------------------------------------------
+// Lookup helpers
+// ---------------------------------------------------------------------------
+/** Map for O(1) lookup by failure type. */
+const registryMap = new Map(exports.FAILURE_REGISTRY.map((entry) => [entry.type, entry]));
+/** Get registry entry for a failure type. */
+function getRegistryEntry(type) {
+    return registryMap.get(type);
+}
+/** Get default severity for a failure type. */
+function getDefaultSeverity(type) {
+    return registryMap.get(type)?.defaultSeverity ?? 'medium';
+}
+/** Get default action for a failure type. */
+function getDefaultAction(type) {
+    return registryMap.get(type)?.defaultAction ?? 'warn';
+}
+/** Get all failure types in a category. */
+function getByCategory(category) {
+    return exports.FAILURE_REGISTRY.filter((e) => e.category === category);
+}
+/**
+ * Compute effective severity based on failure type and detection confidence.
+ * High confidence → default severity. Lower confidence → demoted one level.
+ */
+function computeSeverity(type, confidence) {
+    const base = getDefaultSeverity(type);
+    if (confidence === 'high')
+        return base;
+    // Demote by one level for medium confidence
+    const demotion = {
+        critical: 'high',
+        high: 'medium',
+        medium: 'low',
+        low: 'low',
+    };
+    if (confidence === 'medium')
+        return demotion[base];
+    // Low confidence → demote two levels
+    return demotion[demotion[base]];
+}
+// ---------------------------------------------------------------------------
+// Suppression logic
+// ---------------------------------------------------------------------------
+/** Types that a given primary failure suppresses. */
+function getSuppressedTypes(type) {
+    return registryMap.get(type)?.suppresses ?? [];
+}
+/**
+ * Severity rank for ordering (higher = more severe).
+ */
+const SEVERITY_RANK = {
+    critical: 4,
+    high: 3,
+    medium: 2,
+    low: 1,
+};
+/** Compare two severities. Returns positive if a > b. */
+function compareSeverity(a, b) {
+    return SEVERITY_RANK[a] - SEVERITY_RANK[b];
+}
+// ---------------------------------------------------------------------------
+// Repair ordering
+// ---------------------------------------------------------------------------
+/**
+ * Compute a recommended repair order for a set of active failure types.
+ *
+ * Uses the suppression graph: if A suppresses B then A is a root cause of B,
+ * and fixing A should be attempted first (B may disappear automatically).
+ * Within the same dependency level, higher severity comes first.
+ *
+ * Returns an ordered array of `{ type, reason }` pairs.
+ */
+function getRepairOrder(activeTypes) {
+    const active = new Set(activeTypes);
+    if (active.size === 0)
+        return [];
+    // Build dependency graph: for each active type, find which active types
+    // suppress it (its "blockers"). Those blockers should be fixed first.
+    const blockedBy = new Map();
+    for (const t of active) {
+        blockedBy.set(t, new Set());
+    }
+    for (const entry of exports.FAILURE_REGISTRY) {
+        if (!active.has(entry.type))
+            continue;
+        for (const suppressed of entry.suppresses) {
+            if (active.has(suppressed)) {
+                blockedBy.get(suppressed).add(entry.type);
+            }
+        }
+    }
+    // Kahn's algorithm — topological sort (roots first)
+    const inDegree = new Map();
+    for (const t of active) {
+        inDegree.set(t, blockedBy.get(t).size);
+    }
+    const queue = [];
+    for (const [t, deg] of inDegree) {
+        if (deg === 0)
+            queue.push(t);
+    }
+    // Stable sort within queue by severity descending
+    queue.sort((a, b) => {
+        const sa = SEVERITY_RANK[getDefaultSeverity(a)] ?? 0;
+        const sb = SEVERITY_RANK[getDefaultSeverity(b)] ?? 0;
+        return sb - sa;
+    });
+    const result = [];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (visited.has(current))
+            continue;
+        visited.add(current);
+        const deps = blockedBy.get(current);
+        const reason = deps.size === 0
+            ? 'Root cause — fix this first.'
+            : `Depends on ${[...deps].join(', ')} — fix after those.`;
+        result.push({ type: current, reason });
+        // Decrease in-degree for neighbours
+        for (const entry of exports.FAILURE_REGISTRY) {
+            if (entry.type !== current)
+                continue;
+            for (const suppressed of entry.suppresses) {
+                if (!active.has(suppressed) || visited.has(suppressed))
+                    continue;
+                const newDeg = (inDegree.get(suppressed) ?? 1) - 1;
+                inDegree.set(suppressed, newDeg);
+                if (newDeg === 0) {
+                    // Insert in severity order
+                    const si = SEVERITY_RANK[getDefaultSeverity(suppressed)] ?? 0;
+                    let inserted = false;
+                    for (let i = 0; i < queue.length; i++) {
+                        const sq = SEVERITY_RANK[getDefaultSeverity(queue[i])] ?? 0;
+                        if (si > sq) {
+                            queue.splice(i, 0, suppressed);
+                            inserted = true;
+                            break;
+                        }
+                    }
+                    if (!inserted)
+                        queue.push(suppressed);
+                }
+            }
+        }
+    }
+    // Any remaining (cycle protection) get appended at the end
+    for (const t of active) {
+        if (!visited.has(t)) {
+            result.push({ type: t, reason: 'Circular dependency — review manually.' });
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Tier enforcement
+// ---------------------------------------------------------------------------
+/** Maximum action allowed per tier: S→block, A→block, B→warn, C→observe. */
+const TIER_MAX_ACTION = {
+    S: 'block',
+    A: 'block',
+    B: 'warn',
+    C: 'observe',
+};
+const ACTION_RANK = {
+    observe: 1,
+    warn: 2,
+    block: 3,
+};
+/**
+ * Get the maximum action allowed for a failure type based on its tier.
+ * Policy cannot escalate beyond this ceiling.
+ */
+function getTierMaxAction(type) {
+    const entry = registryMap.get(type);
+    if (!entry)
+        return 'observe';
+    return TIER_MAX_ACTION[entry.tier];
+}
+/**
+ * Cap an action to the tier ceiling.
+ * If the requested action exceeds what the tier allows, returns the tier max.
+ */
+function capActionToTier(type, requestedAction) {
+    const maxAction = getTierMaxAction(type);
+    if (ACTION_RANK[requestedAction] > ACTION_RANK[maxAction]) {
+        return maxAction;
+    }
+    return requestedAction;
+}
+//# sourceMappingURL=index.js.map