/**
 * Output Ingestion & Interpretation agent — matrix row.
 *
 * Per Pillar 3 spec §Agent 1: apply pre-determined rules from the
 * Rule Library to Pillar 2's analytical findings to produce
 * policy-driven recommendations with structured confidence scoring.
 *
 * Never improvises interpretation. Every recommendation traces to a
 * declared rule. If no rule matches, escalates per Std 9 — Pillar 3's
 * "stricter" escalation regime applies (spec §Std 9).
 */

import {
  type AgentRules,
  type AgentStandardsContract,
  type Capability,
  DECISION_FORBIDDEN,
  type RunbookStep,
  type TriggerCategory,
  type WriteBackDeclaration,
} from '../../../standards.js';

export const AGENT_NAME = 'decision.output-ingestion';
export const AGENT_VERSION = '1.0.0';

export const outputIngestionMatrix = {
  '1_objective':
    'Apply pre-determined rules from the SME Rule Library to Pillar 2 findings, producing policy-driven recommendations with structured confidence scoring. Interpret only — do not visualize or deliver.',
  '2_inputs':
    'Pillar 2 output (insights + comparisons + metrics with reasoning lineage), JobRequest.audience for tier context, and the Rule Library. Validates schema, lineage completeness, and per-insight confidence at the boundary.',
  '3_decisionLogic':
    'Every interpretation traces to a declared rule. Logs which rule was selected, which conditions matched, and what recommendation was produced. No improvised logic (Std 3 + Decision §Std 3).',
  '4_rulesConstraints':
    'No recommendation beyond what a matched rule supports. No recommendations for findings whose interpretation rules are absent from the library (those escalate per Std 9). No causal claims beyond the rule\'s declared language constraints.',
  '5_methodsTools':
    'Rule Library lookup via find_rules / get_rule (capability: rule-library). Confidence framework taken from the matched rule\'s confidence_framework block. No fresh data retrieval (DECISION_FORBIDDEN).',
  '6_processing':
    'Receive Pillar 2 output → for each finding, find applicable interpretation rule(s) via library → if multiple, resolve precedence → if zero, escalate as rule-gap → otherwise apply rule conditions to the finding via LLM judgment → score confidence per the rule\'s framework → cross-check → package. Cost-appropriate execution (Std 6): rule discovery is deterministic; rule application via LLM only when the rule\'s conditions are natural-language predicates.',
  '7_validation':
    'Validate each recommendation against its rule\'s conditions and confidence threshold. Reject recommendations that fall below the action threshold (escalate per Std 9). Per-recommendation confidence.',
  '8_conditionalTriggers':
    'rule-gap, rule-conflict, low confidence, material-impact-finding, audience-policy concerns, threshold-breach.',
  '9_hitlEscalation':
    'Escalates aggressively (Pillar 3 stricter regime). Recommended reviewers: domain-expert (SME) for rule gaps; authorizing-decision-maker for material-impact findings; compliance-reviewer for disclosure concerns.',
  '10_repositoryWriteBack':
    'Recommendations with rule_applied, confidence, source-finding lineage, interpretive reasoning. Full chain from upstream insights back to source URLs preserved.',
  '11_handoff':
    'Recommendations object → Visualization agent.',
  '12_failureHandling':
    'Fails per-recommendation when rules do not apply or confidence is below the action threshold; other recommendations in the same run continue. Persistent failures across all findings produce a structured FailureObject with category=interpretation-blocked.',
} as const;

const capabilities: readonly Capability[] = [
  'rule-library',
  'interpretation',
  'disclosure-policy-check',
  'audience-tier-routing',
];

const runbook: readonly RunbookStep[] = [
  { n: 1, name: 'receive-pillar2-output', description: 'Verify Pillar 2 schema, lineage, confidence scores, completeness (Std 2).' },
  { n: 2, name: 'find-rules', description: 'For each finding, deterministically search the Rule Library for applicable interpretation rules (Std 5).' },
  { n: 3, name: 'resolve-precedence', description: 'If multiple rules match, apply precedence (most-specific then newest) before evaluation.' },
  { n: 4, name: 'apply-rule', description: 'Evaluate the rule\'s conditions against the finding\'s data; generate the recommendation per the rule\'s action (Std 3). LLM judgment only when conditions are natural-language predicates.' },
  { n: 5, name: 'score-confidence', description: 'Apply the rule\'s confidence framework, inheriting upstream confidence and applying declared adjustments (Std 7).' },
  { n: 6, name: 'cross-check', description: 'Validate every recommendation references a real rule_id, a real upstream insight/comparison/metric, and meets the action threshold (Std 4 + Std 7).' },
  { n: 7, name: 'escalate-gaps', description: 'For findings with no matching rule, conflicting rules, or sub-threshold confidence, emit a structured HITL escalation (Std 9).' },
  { n: 8, name: 'package-handoff', description: 'Hand off to Visualization agent (Std 11).' },
];

const triggers: readonly TriggerCategory[] = [
  'rule-gap',
  'rule-conflict',
  'low-confidence',
  'material-impact-finding',
  'audience-policy-violation',
  'threshold-breach',
];

const writeBack: WriteBackDeclaration = {
  structuredOutputs: true,
  metadata: true,
  lineage: true,
  validation: true,
  confidence: true,
  exceptionLogs: true,
  learnedRules: false,
  humanOverrides: false,
};

const rules: AgentRules = {
  preserveRawSource: true,
  preserveLineage: true,
  preserveAuditability: true,
  forbidFabrication: true,
  forbidDestructiveOverwrite: true,
  approvedToolsOnly: true,
  pillarSpecificForbidden: DECISION_FORBIDDEN,
};

export const outputIngestionContract: AgentStandardsContract = {
  agentName: AGENT_NAME,
  agentVersion: AGENT_VERSION,
  pillar: 'decision',
  objective: {
    does: outputIngestionMatrix['1_objective'],
    produces: 'A typed Recommendations object — each recommendation with rule_applied, confidence, source-finding lineage, suggested action category.',
    doesNot: [
      'visualize or render',
      'deliver or dispatch',
      'improvise interpretation',
      're-derive analytical findings',
      'invent rules outside the library',
    ],
    downstreamPurpose: 'Hand off to the Visualization agent for audience-appropriate rendering.',
  },
  rules,
  capabilities,
  runbook,
  triggers,
  writeBack,
};