/**
 * Insight Synthesis agent — matrix row.
 *
 * Produce business-relevant insights grounded in comparisons + metrics,
 * using SME-encoded narrative frameworks. Per Pillar 2 spec §Agent 4:
 * every narrative claim cites its supporting data point, comparison,
 * or methodology — no unsupported claims.
 */

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

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

export const insightSynthesisMatrix = {
  '1_objective':
    'Produce business-relevant insights grounded in the comparisons and metrics, using SME-encoded narrative frameworks. Insights from existing comparisons/metrics only — do not introduce new data or run new computations.',
  '2_inputs':
    'Comparisons object from Agent 3 plus business context from the JobRequest. Validate each comparison carries comparability annotations.',
  '3_decisionLogic':
    'Log which insight framework was applied and what observations it surfaced. Every framework choice explainable.',
  '4_rulesConstraints':
    'Every narrative claim must cite at least one supporting metric, comparison, or methodology. Unsupported claims are removed or clearly marked as inference.',
  '5_methodsTools':
    'Methodology library lookup for insight_framework entries (driver analysis, trend interpretation, peer positioning).',
  '6_processing':
    'Receive comparisons → select insight framework(s) → for each candidate insight: identify support → verify sufficiency → drop or mark inference if unsupported. Validate narrative-data fidelity. Confidence per insight. Package.',
  '7_validation':
    'Validate every narrative claim against its data citation. Confidence per insight.',
  '8_conditionalTriggers':
    'Unsupported claims, contradictory interpretations, methodology gaps, narrative ambiguity.',
  '9_hitlEscalation':
    'Escalate for unsupported-claim handling, framework selection, narrative-validity questions. Recommended reviewer: domain-expert (SME).',
  '10_repositoryWriteBack':
    'Insights with supporting evidence, framework used, per-insight confidence, full reasoning lineage.',
  '11_handoff':
    'Insights object → next layer (SME review, eventually Pillar 3 Decision).',
  '12_failureHandling':
    'Fail per-insight when a claim cannot be supported. Other insights in the same run continue.',
} as const;

const capabilities: readonly Capability[] = [
  'methodology-library',
  'insight-synthesis',
  'narrative-fidelity',
];

const runbook: readonly RunbookStep[] = [
  { n: 1, name: 'receive-comparisons', description: 'Verify Comparisons schema + business context from the JobRequest.' },
  { n: 2, name: 'select-framework', description: 'Pick applicable insight framework(s) from the library based on JobRequest + data shape.' },
  { n: 3, name: 'identify-support', description: 'For each candidate insight, identify which comparisons/metrics support the claim.' },
  { n: 4, name: 'verify-sufficiency', description: 'Verify the supporting evidence is sufficient; drop or mark inference if not (Std 4).' },
  { n: 5, name: 'attach-evidence', description: 'Stamp every retained claim with its supporting evidence ids and reasoning lineage.' },
  { n: 6, name: 'validate-fidelity', description: 'Validate narrative-data fidelity: every claim cites its support (Std 7).' },
  { n: 7, name: 'score-confidence', description: 'Per-insight confidence with rationale.' },
  { n: 8, name: 'package-handoff', description: 'Hand off to next layer / SME review / Pillar 3 (Std 11).' },
];

const triggers: readonly TriggerCategory[] = [
  'unsupported-claim',
  'narrative-ambiguity',
  '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 insightSynthesisContract: AgentStandardsContract = {
  agentName: AGENT_NAME,
  agentVersion: AGENT_VERSION,
  pillar: 'intelligence',
  objective: {
    does: insightSynthesisMatrix['1_objective'],
    produces: 'A typed Insights object — claims + supporting evidence + reasoning lineage.',
    doesNot: [
      'introduce new data',
      'run new computations',
      'make claims without citation',
      'produce partner-facing recommendations (that is Pillar 3\'s job)',
    ],
    downstreamPurpose: 'Hand off to SME review or Pillar 3 (Decision) when that pillar exists.',
  },
  rules,
  capabilities,
  runbook,
  triggers,
  writeBack,
};