AirCoding/packages/contracts/src/worker-result.ts

/**
 * AirCoding Worker Result Contracts
 *
 * Implements WorkerStatus, WorkerResult, ExecutorResult, ReviewerResult,
 * DebuggerResult, CompactorResult, ExperienceMinerResult, BlockerReport,
 * Risk, FollowUpTask per interface-contracts-v1.md §11 and system-detailed-design.md §3.
 */

// Import types needed for these interfaces
import type {
  TaskID,
  AgentID,
  ArtifactID,
  EvidenceRefID,
  SummaryID,
  MessageID,
  UUID,
} from './ids.js'
import type { AgentType } from './runtime.js'
import type { ArtifactRef } from './artifact.js'
import type { EvidenceRef } from './evidence.js'

// Re-export for external consumers
export type {
  TaskID,
  AgentID,
  ArtifactID,
  EvidenceRefID,
  SummaryID,
  MessageID,
  UUID,
}
export type { AgentType }
export type { ArtifactRef }
export type { EvidenceRef }

/**
 * Status values for worker results.
 * Per DD §22.1: status ∈ {completed, failed, blocked, cancelled}
 */
export type WorkerStatus = 'completed' | 'failed' | 'blocked' | 'cancelled'

/**
 * Result of a verification check performed by a worker.
 */
export interface VerificationResult {
  name: string
  status: 'passed' | 'failed' | 'skipped' | 'unknown'
  evidence_ref_ids?: EvidenceRefID[]
  notes?: string
}

/**
 * Risk identified during worker execution.
 */
export interface Risk {
  severity: 'low' | 'medium' | 'high'
  summary: string
}

/**
 * Follow-up task created as a result of worker execution.
 */
export interface FollowUpTask {
  title: string
  description: string
  type?: 'execute' | 'review' | 'debug' | 'compact' | 'mine_experience' | 'docs'
}

/**
 * Generic worker result container.
 * Per DD §22.1: status ∈ {completed, failed, blocked, cancelled}
 */
export interface WorkerResult<TResult = unknown> {
  task_id: TaskID
  agent_id: AgentID
  agent_type: AgentType
  status: WorkerStatus
  summary: string
  changed_files: string[]
  diff_ref?: ArtifactID
  artifacts: ArtifactRef[]
  verification: VerificationResult[]
  risks: Risk[]
  follow_up_tasks: FollowUpTask[]
  evidence_refs: EvidenceRef[]
  result: TResult
}

/**
 * Result from an Executor worker.
 */
export interface ExecutorResult {
  implementation_summary: string
  changed_files: string[]
  verification_commands: string[]
}

/**
 * A single finding from a reviewer.
 */
export interface ReviewFinding {
  severity: 'low' | 'medium' | 'high'
  category: 'correctness' | 'security' | 'scope' | 'architecture' | 'test' | 'maintainability'
  message: string
  file?: string
  line?: number
  evidence_ref_ids?: EvidenceRefID[]
}

/**
 * Result from a Reviewer worker.
 */
export interface ReviewerResult {
  verdict: 'approved' | 'changes_requested' | 'blocked'
  findings: ReviewFinding[]
}

/**
 * Report documenting a blocker that prevented task completion.
 */
export interface BlockerReport {
  impact_level: 'implementation' | 'interface' | 'architecture' | 'product' | 'permission' | 'environment' | 'policy'
  reason: string
  required_decision: string
  options?: Array<{ label: string; tradeoff: string }>
  evidence_ref_ids?: EvidenceRefID[]
  suggested_default?: string
}

/**
 * Result from a Debugger worker.
 */
export interface DebuggerResult {
  diagnosis: string
  root_cause?: string
  fixed: boolean
  blocker?: BlockerReport
}

/**
 * Result from a Compactor worker.
 */
export interface CompactorResult {
  summary_id: SummaryID
  range_start_message_id?: MessageID
  range_end_message_id?: MessageID
  token_estimate_before?: number
  token_estimate_after?: number
}

/**
 * A candidate memory extracted by the experience miner.
 */
export interface MemoryCandidate {
  candidate_id: UUID
  memory_type: 'project_rule' | 'toolchain_rule' | 'skill_update' | 'debug_experience'
  summary: string
  evidence_ref_ids?: EvidenceRefID[]
}

/**
 * Result from an ExperienceMiner worker.
 */
export interface ExperienceMinerResult {
  candidates: MemoryCandidate[]
}