/**
 * Comparisons & Synthesis agent — matrix row.
 *
 * Produce defensible comparisons (period-over-period, peer benchmark,
 * ratio, etc.) using computed metrics. Per Pillar 2 spec §Agent 3 +
 * §Std 1: comparisons only — no business narratives.
 */

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

export const AGENT_NAME = 'intelligence.comparisons-synthesis';
export const AGENT_VERSION = '1.0.0';

export const comparisonsSynthesisMatrix = {
  '1_objective':
    'Produce defensible comparisons across entities, time periods, segments, or peer groups using computed metrics. Comparisons only — no business narratives, no recommendations.',
  '2_inputs':
    'ComputedMetrics from Agent 2 plus the JobRequest comparison requests (inferred from question if not explicit). Validate the metrics being compared are present for all entities being compared.',
  '3_decisionLogic':
    'Log which comparison method was chosen and why (period-over-period vs peer benchmark vs ratio, etc.).',
  '4_rulesConstraints':
    'No comparisons across incompatible bases. Mismatches get refused or explicitly annotated. No invented comparisons.',
  '5_methodsTools':
    'Methodology library lookup for comparison_method entries; comparability rules from the methodology entries themselves.',
  '6_processing':
    'Receive metrics → for each comparison: determine method → lookup methodology → comparability check → compute → stamp lineage → add statistical context → validate → confidence → package.',
  '7_validation':
    'Validate comparability before comparison; flag or refuse if mismatched. Confidence per comparison.',
  '8_conditionalTriggers':
    'Comparability failure, statistically insignificant differences flagged as significant, peer-set construction failures.',
  '9_hitlEscalation':
    'Escalate for comparability failures, peer set selection ambiguity, comparison-method selection. Recommended reviewer: domain-expert (SME).',
  '10_repositoryWriteBack':
    'Comparison records (method, inputs, comparability status, statistical context), per-comparison confidence.',
  '11_handoff':
    'Comparisons object → Insight Synthesis agent.',
  '12_failureHandling':
    'Fail per-comparison when comparability cannot be established. Other comparisons in the same run continue.',
} as const;

const capabilities: readonly Capability[] = [
  'methodology-library',
  'comparison-analysis',
  'statistical-context',
];

const runbook: readonly RunbookStep[] = [
  { n: 1, name: 'receive-metrics', description: 'Verify ComputedMetrics schema + comparison requests from the JobRequest.' },
  { n: 2, name: 'select-method', description: 'For each comparison: determine the comparison method (period-over-period, peer benchmark, ratio, …).' },
  { n: 3, name: 'lookup-methodology', description: 'Query the methodology library for a matching comparison_method entry.' },
  { n: 4, name: 'comparability-check', description: 'Run the methodology\'s comparability_check on the inputs (Std 8 trigger fires on failure).' },
  { n: 5, name: 'compute', description: 'Compute the comparison; stamp method, inputs, and lineage.' },
  { n: 6, name: 'statistical-context', description: 'Add significance, dispersion, ranking where applicable.' },
  { n: 7, name: 'validate', description: 'Sanity checks, plausibility (Std 7).' },
  { n: 8, name: 'score-confidence', description: 'Per-comparison confidence.' },
  { n: 9, name: 'package-handoff', description: 'Hand off to Insight Synthesis (Std 11).' },
];

const triggers: readonly TriggerCategory[] = [
  'comparability-failure',
  'methodology-gap',
  'insufficient-data',
  'statistical-anomaly',
  'peer-set-failure',
];

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: INTELLIGENCE_FORBIDDEN,
};

export const comparisonsSynthesisContract: AgentStandardsContract = {
  agentName: AGENT_NAME,
  agentVersion: AGENT_VERSION,
  pillar: 'intelligence',
  objective: {
    does: comparisonsSynthesisMatrix['1_objective'],
    produces: 'A typed Comparisons object — validated comparisons with comparability annotations, statistical context, and lineage.',
    doesNot: [
      'produce business narratives',
      'generate recommendations',
      'compute fresh metrics outside what was supplied',
      'compare incompatible bases',
    ],
    downstreamPurpose: 'Feed the Insight Synthesis agent with comparisons it can reason narratively over.',
  },
  rules,
  capabilities,
  runbook,
  triggers,
  writeBack,
};