/**
 * Analytical Table agent — matrix row.
 *
 * The 12 per-agent fill-ins for the universal standards. The exported
 * `analyticalTableContract` is what the orchestrator reads (Std 1 / 4
 * / 5 / 6 / 8 / 10) and what the prompt builder folds into the agent's
 * system prompt. Per Pillar 2 spec, this agent only structures data
 * — it does not compute metrics, run comparisons, or produce insights.
 */

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

export const AGENT_NAME = 'intelligence.analytical-table';
export const AGENT_VERSION = '1.0.0';

/** The 12 matrix rows, verbatim per the Pillar 2 spec. */
export const analyticalTableMatrix = {
  '1_objective':
    'Convert Pillar 1 output into a normalized analytical structure (entities × metrics × periods) ready for computation. Structure only — no metric computation, no comparisons, no insights.',
  '2_inputs':
    "Pillar 1 resolved-record output (records with full lineage + confidence) plus the JobRequest. Validate entity completeness, period coverage, unit consistency. Refuse inputs lacking Pillar-1 lineage.",
  '3_decisionLogic':
    'Log why each entity was grouped, why each period was selected, why each unit normalization was applied. No opaque structuring.',
  '4_rulesConstraints':
    'No values invented to fill gaps. Missing data stays missing and gets flagged. Lineage chain back to Pillar 1 preserved on every cell.',
  '5_methodsTools':
    'Methodology library lookup for normalization rules (unit conventions, period alignment, entity normalization). Apply only declared methodologies.',
  '6_processing':
    'Receive → determine structure → unit-normalize → period-align → entity-normalize → completeness check → cell lineage → validate → confidence → package.',
  '7_validation':
    'Validate table completeness, period alignment, unit consistency. Confidence per cell and per table.',
  '8_conditionalTriggers':
    'Missing entities, missing periods, incompatible source units, methodology gap for normalization, insufficient data.',
  '9_hitlEscalation':
    'Escalate for entity-resolution gaps, missing-period decisions, scope clarifications. Recommended reviewer: domain-expert (SME).',
  '10_repositoryWriteBack':
    'Analytical table, cell lineage, validation, confidence, conditional triggers fired.',
  '11_handoff':
    'AnalyticalTable object (entities × metrics × periods + cell-level lineage) → Performance Metrics agent.',
  '12_failureHandling':
    'Fail structurally when required inputs are absent or incompatible. No partial tables silently passed forward.',
} as const;

const capabilities: readonly Capability[] = [
  'methodology-library',
  'table-construction',
  'unit-normalization',
  'period-alignment',
  'entity-resolution',
];

const runbook: readonly RunbookStep[] = [
  { n: 1, name: 'receive-pillar1-output', description: 'Verify schema, lineage, completeness of Pillar 1 records.' },
  { n: 2, name: 'determine-table-structure', description: 'Choose rows (entities) × cols (metrics) × periods from the JobRequest.' },
  { n: 3, name: 'apply-unit-normalization', description: 'Convert all values to consistent units via declared normalization methodologies.' },
  { n: 4, name: 'apply-period-alignment', description: 'Map values to consistent period definitions (FY-YYYY, Q1-YYYY).' },
  { n: 5, name: 'apply-entity-normalization', description: 'Ensure entity identifiers match across rows.' },
  { n: 6, name: 'cross-check-completeness', description: 'Flag missing cells with structured notes (Std 8).' },
  { n: 7, name: 'stamp-cell-lineage', description: 'Each cell references its source Pillar 1 record.' },
  { n: 8, name: 'validate-table', description: 'Schema check, lineage check, completeness check (Std 7).' },
  { n: 9, name: 'score-confidence', description: 'Table-level confidence + per-cell confidence.' },
  { n: 10, name: 'package-handoff', description: 'Hand off to Performance Metrics (Std 11).' },
];

const triggers: readonly TriggerCategory[] = [
  'missing-data',
  'missing-metadata',
  'ontology-conflict',
  'methodology-gap',
  'insufficient-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 analyticalTableContract: AgentStandardsContract = {
  agentName: AGENT_NAME,
  agentVersion: AGENT_VERSION,
  pillar: 'intelligence',
  objective: {
    does: analyticalTableMatrix['1_objective'],
    produces: 'A typed AnalyticalTable: entities × metrics × periods, with cell-level lineage to Pillar 1 records.',
    doesNot: [
      'compute metrics',
      'run comparisons',
      'generate insights',
      'invent values to fill missing cells',
    ],
    downstreamPurpose: 'Feed the Performance Metrics agent with a clean, comparable analytical grid.',
  },
  rules,
  capabilities,
  runbook,
  triggers,
  writeBack,
};