/**
 * Performance Metrics agent — matrix row.
 *
 * Compute defined metrics from the Analytical Table according to
 * declared analytical methodologies. Per Pillar 2 spec §Agent 2 +
 * §Std 1: compute only — no interpretation, no comparisons, no
 * insights.
 */

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

export const AGENT_NAME = 'intelligence.performance-metrics';
export const AGENT_VERSION = '1.0.0';

export const performanceMetricsMatrix = {
  '1_objective':
    'Compute defined metrics from the analytical table according to declared analytical methodologies. Compute only — do not interpret meaning, do not compare.',
  '2_inputs':
    'AnalyticalTable from Agent 1 plus the JobRequest metric requests. Validate the table has all rows/columns each requested metric needs before computing.',
  '3_decisionLogic':
    'Log which methodology was selected and why (JobRequest match, domain match, only one available, etc.). No opaque selection.',
  '4_rulesConstraints':
    'No metrics computed from incomplete inputs. If required data is not present, the metric is omitted or escalated. No invented values.',
  '5_methodsTools':
    'Methodology library lookup for metric_definition entries; declared formulas only. No ad-hoc formulas.',
  '6_processing':
    'Receive table → for each requested metric: lookup methodology → validate inputs → apply formula → stamp lineage. Validate computed values. Score per-metric confidence. Package.',
  '7_validation':
    'Validate the metric formula was applied correctly to the right inputs. Per-metric confidence with rationale.',
  '8_conditionalTriggers':
    'Missing methodology, incomplete inputs, statistical anomaly, unusual values.',
  '9_hitlEscalation':
    'Escalate for methodology gaps, novel metric requests, ambiguous formula choices. Recommended reviewer: domain-expert (SME).',
  '10_repositoryWriteBack':
    'Computed metric values with methodology references, input lineage, per-metric confidence, conditional triggers.',
  '11_handoff':
    'ComputedMetrics object → Comparisons & Synthesis agent.',
  '12_failureHandling':
    'Fail per-metric when methodology unavailable or inputs insufficient. Other metrics in the same run continue.',
} as const;

const capabilities: readonly Capability[] = [
  'methodology-library',
  'metric-computation',
];

const runbook: readonly RunbookStep[] = [
  { n: 1, name: 'receive-table', description: 'Verify AnalyticalTable schema + JobRequest metric requests.' },
  { n: 2, name: 'lookup-methodologies', description: 'For each requested metric, query the library for an applicable methodology.' },
  { n: 3, name: 'validate-inputs', description: 'Per metric, verify the table has every input cell the methodology needs.' },
  { n: 4, name: 'compute', description: 'Apply the methodology formula. Stamp methodology reference and input lineage.' },
  { n: 5, name: 'validate-outputs', description: 'Sanity checks, plausibility, statistical anomaly detection (Std 7 + Std 8).' },
  { n: 6, name: 'score-confidence', description: 'Per-metric confidence with rationale.' },
  { n: 7, name: 'package-handoff', description: 'Hand off to Comparisons & Synthesis (Std 11).' },
];

const triggers: readonly TriggerCategory[] = [
  'methodology-gap',
  'insufficient-data',
  'statistical-anomaly',
  'missing-data',
];

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 performanceMetricsContract: AgentStandardsContract = {
  agentName: AGENT_NAME,
  agentVersion: AGENT_VERSION,
  pillar: 'intelligence',
  objective: {
    does: performanceMetricsMatrix['1_objective'],
    produces: 'A typed ComputedMetrics object — computed metric values with the methodology applied, input lineage, and per-metric confidence.',
    doesNot: [
      'interpret metric meaning',
      'run comparisons',
      'generate insights',
      'invent formulas not in the methodology library',
    ],
    downstreamPurpose: 'Feed the Comparisons & Synthesis agent with computed metric values keyed by methodology.',
  },
  rules,
  capabilities,
  runbook,
  triggers,
  writeBack,
};