/**
 * Delivery & Distribution agent — matrix row.
 *
 * Per Pillar 3 spec §Agent 3: route visualized outputs to designated
 * audiences through approved channels, confirm delivery, and manage
 * cadence. The framework's exit point — once this agent has dispatched
 * an output, control leaves the framework (to humans, or to external
 * systems registered as channel adapters).
 *
 * Silent failure is not allowed: every dispatch attempt is logged and
 * persistent failures escalate (spec §Agent 3 key constraint).
 */

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

export const AGENT_NAME = 'decision.delivery-distribution';
export const AGENT_VERSION = '1.0.0';

export const deliveryDistributionMatrix = {
  '1_objective':
    'Route visualized outputs to designated audiences through approved channels, confirm delivery, and manage cadence. Deliver only — do not re-interpret or re-render.',
  '2_inputs':
    'Visualizations from the Visualization agent + the Rule Library + the channel registry. Each visualization carries audience tier and disclosure-cleared status; rejects anything not cleared.',
  '3_decisionLogic':
    'Every delivery decision (channel choice, cadence enforcement, addressing) traces to a declared delivery rule from the library. Logs the rule + channel + recipient + cadence outcome.',
  '4_rulesConstraints':
    'No delivery outside approved channels (channels must be registered). No delivery exceeding cadence policies. No silent dropping of failed dispatches.',
  '5_methodsTools':
    'Rule Library lookup via find_rules / get_rule (capability: rule-library). Channel-adapter dispatch via registry lookup (capability: channel-dispatch). Cadence enforcement (capability: cadence-control). Acknowledgment tracking (capability: acknowledgment-tracking).',
  '6_processing':
    'Receive visualizations → for each, deterministically find applicable delivery rule(s) via library → resolve precedence → if zero, escalate as delivery-rule-gap → otherwise look up primary channel; if unregistered, try secondary then fallback; if all unregistered, escalate channel-unavailable → enforce cadence and disclosure-policy → channel.dispatch(...) → record outcome. No LLM call in the deterministic path (Std 6 cost-appropriate execution).',
  '7_validation':
    'Validate correct addressing (audience tier carried through), channel availability (channel registered), cadence compliance. Per-dispatch confidence reflecting any fallback channel use.',
  '8_conditionalTriggers':
    'delivery-rule-gap, channel-unavailable, cadence-violation, recipient-verification-failed, acknowledgment-failure, material-impact-finding (carried through).',
  '9_hitlEscalation':
    'Escalates aggressively (Pillar 3 stricter regime). Recommended reviewers: operations-reviewer (delivery failures, channel issues), authorizing-decision-maker (material findings), compliance-reviewer (disclosure-policy gaps).',
  '10_repositoryWriteBack':
    'Dispatch record with channel, recipient, timestamp, content reference, acknowledgment state, outcome. The framework\'s most complete audit trail terminus.',
  '11_handoff':
    'Dispatches object → external systems (humans, downstream platforms). Framework exit point.',
  '12_failureHandling':
    'Retries on bounded schedule (channel adapter responsibility). Falls back to secondary then fallback channel. Escalates persistent failures. Never silently drops a dispatch.',
} as const;

const capabilities: readonly Capability[] = [
  'rule-library',
  'channel-dispatch',
  'cadence-control',
  'acknowledgment-tracking',
  'disclosure-policy-check',
  'audience-tier-routing',
];

const runbook: readonly RunbookStep[] = [
  { n: 1, name: 'receive-visualizations', description: 'Verify Visualizations schema, audience identifier, delivery requirements (Std 2).' },
  { n: 2, name: 'find-rules', description: 'For each visualization, deterministically search the Rule Library for applicable delivery rules (Std 5).' },
  { n: 3, name: 'resolve-precedence', description: 'If multiple rules match, apply precedence (most-specific then newest).' },
  { n: 4, name: 'verify-channel', description: 'Look up primary channel in the registry; fall back to secondary / fallback if missing. Escalate channel-unavailable if all are unregistered (Std 4).' },
  { n: 5, name: 'enforce-cadence-and-disclosure', description: 'Check cadence policy and disclosure policy against the audience tier. Escalate cadence-violation or disclosure-policy-concern (Std 8 + Std 9).' },
  { n: 6, name: 'dispatch', description: 'Call channel.dispatch(payload). Record outcome — channel name, dispatched-at timestamp, acknowledgment state. Never silently drop (Std 12).' },
  { n: 7, name: 'score-confidence', description: 'Per-dispatch confidence reflecting fallback channel use or acknowledgment-pending state.' },
  { n: 8, name: 'package-handoff', description: 'Hand off dispatches + audit log to the orchestrator for repository persistence. Framework exit point (Std 11).' },
];

const triggers: readonly TriggerCategory[] = [
  'rule-gap',
  'delivery-failure',
  'cadence-violation',
  'recipient-verification-failed',
  'acknowledgment-failure',
  'disclosure-policy-concern',
  'material-impact-finding',
];

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

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

export const deliveryDistributionContract: AgentStandardsContract = {
  agentName: AGENT_NAME,
  agentVersion: AGENT_VERSION,
  pillar: 'decision',
  objective: {
    does: deliveryDistributionMatrix['1_objective'],
    produces: 'A typed Dispatches object — each dispatch with channel, recipient, timestamp, content reference, acknowledgment state, outcome.',
    doesNot: [
      're-interpret findings',
      're-render visualizations',
      'deliver outside approved channels',
      'exceed declared cadence policies',
      'silently drop failed dispatches',
    ],
    downstreamPurpose: 'Framework exit — dispatches reach humans or external systems registered as channel adapters. Confirmations return to the repository.',
  },
  rules,
  capabilities,
  runbook,
  triggers,
  writeBack,
};