/**
 * Normalization agent — matrix row.
 *
 * Combines canonical 12-standard contracts (src/standards.ts) with the
 * per-agent fill-ins from the spec matrix. The matrix is the source of
 * truth; the typed `normalizationContract` is derived from it for the
 * orchestrator's consumption.
 */

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

export const AGENT_NAME = 'baseline.normalization';
export const AGENT_VERSION = '1.0.0';

export const normalizationMatrix = {
  '1_objective':
    'Standardize extracted source records into comparable analytical structures.',
  '2_inputs':
    'Structured raw dataset, metadata, validation status, confidence scores, lineage references, taxonomy rules.',
  '3_decisionLogic':
    'Determine entity mapping, period standardization, terminology mapping, duplicate handling, escalation needs.',
  '4_rulesConstraints':
    'Preserve raw values, preserve lineage, avoid forced mappings, maintain comparability.',
  '5_methodsTools':
    'Taxonomy mapping, ontology rules, entity resolution, semantic mapping, duplicate resolution.',
  '6_processing':
    'Normalize entities, periods, source types, terminology, metadata, and duplicate records.',
  '7_validation':
    'Check mapping consistency, detect contradictions, validate normalized fields, assign confidence scores.',
  '8_conditionalTriggers':
    'Unmapped term, duplicate entity, contradictory mapping, low confidence, ontology conflict.',
  '9_hitlEscalation':
    'Unresolved mapping, ontology conflict, low confidence normalization, critical inconsistency.',
  '10_repositoryWriteBack':
    'Normalized records, mapping rules, learned mappings, validation status, confidence scores.',
  '11_handoff':
    'Analytics-ready dataset for the Intelligence Pillar.',
  '12_failureHandling':
    'Stop unresolved normalization loops, preserve unresolved mappings, escalate critical conflicts.',
} as const;

const capabilities: readonly Capability[] = [
  'taxonomy-mapping', 'ontology-rules', 'entity-resolution', 'semantic-mapping', 'duplicate-resolution',
];

const runbook: readonly RunbookStep[] = [
  { n: 1, name: 'validate-input', description: 'Validate the Structured Payload from Source/Extraction (Std 2).' },
  { n: 2, name: 'normalize-entities', description: 'Resolve raw entity labels to canonical ids using JobRequest.entities + learned mappings (Std 5).' },
  { n: 3, name: 'normalize-terminology', description: 'Map raw labels to canonical metric keys via learned mappings; LLM judgment for novel labels (Std 3 + Std 5).' },
  { n: 4, name: 'normalize-units-and-periods', description: 'Standardize units and periods; flag ontology conflicts (Std 8).' },
  { n: 5, name: 'resolve-duplicates', description: 'Detect duplicates and contradictions; preserve raw values (Std 4).' },
  { n: 6, name: 'validate-output', description: 'Check mapping consistency, contradictions, confidence per record (Std 7).' },
  { n: 7, name: 'handoff', description: 'Package analytics-ready dataset for the Resolution agent / Intelligence pillar (Std 11).' },
];

const triggers: readonly TriggerCategory[] = [
  'unmapped-term', 'duplicate-entity', 'contradictory-mapping', 'low-confidence', 'ontology-conflict',
];

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

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

export const normalizationContract: AgentStandardsContract = {
  agentName: AGENT_NAME,
  agentVersion: AGENT_VERSION,
  pillar: 'baseline',
  objective: {
    does: normalizationMatrix['1_objective'],
    produces: 'A canonical, comparable, duplicate-resolved dataset.',
    doesNot: [
      'invent values for missing fields',
      'destructively overwrite raw values (raw values are preserved alongside)',
      'derive strategic insight, benchmarks, or recommendations',
    ],
    downstreamPurpose: 'Analytics-ready dataset for the Resolution agent / Intelligence pillar.',
  },
  rules,
  capabilities,
  runbook,
  triggers,
  writeBack,
};