/**
 * AirCoding Runtime Contracts
 *
 * Implements AgentType, AgentRuntimeContext, ContextPack, and PromptLayer types
 * per interface-contracts-v1.md and system-detailed-design.md §3.
 */

// Re-export IDs needed for these types (imported from ids which has no runtime deps)
// Using type-only re-export to avoid circular issues
import type { SessionID, ProjectID, AgentID, TaskID, ArtifactID } from './ids'
export type { SessionID, ProjectID, AgentID, TaskID, ArtifactID }

/**
 * Worker agent types - the 5 worker roles that run as child processes.
 * Runtime-resident roles (main, architecture_designer, scheduler) are NOT members.
 */
export type AgentType = 'executor' | 'reviewer' | 'debugger' | 'compactor' | 'experience_miner'

/**
 * Runtime context passed to worker agents.
 * Provides the execution environment and permission boundaries.
 */
export interface AgentRuntimeContext {
  session_id: SessionID
  project_id: ProjectID
  agent_id: AgentID
  worktree_path?: string
  permission_template: 'main_direct' | 'executor' | 'reviewer' | 'debugger' | 'system'
}

/**
 * Context pack assembled by ContextAssembler and sent to workers.
 * Contains references to artifacts, plans, and assembled context.
 */
export interface ContextPack {
  refs: {
    plan_ref?: string
    arc_ref?: string
    task_refs?: TaskID[]
    artifact_refs?: ArtifactID[]
    rule_refs?: string[]
  }
  assembled_context_ref?: ArtifactID
  notes?: string[]
}

/**
 * Prompt layer levels following prompt-layering-v1 §2.
 * Ordered L0-L9 for hierarchical context assembly.
 */
export type PromptLayerLevel =
  | 'runtime_invariant' // L0
  | 'role' // L1
  | 'safety' // L2
  | 'project_rules' // L3
  | 'architecture' // L4
  | 'task_spec' // L5
  | 'evidence' // L6
  | 'conversation' // L7
  | 'tool_output' // L8
  | 'user_override' // L9
  | 'system_debug' // applied within L9 when present

/**
 * A single prompt layer with level, priority, and content.
 * Used by ContextAssembler to build the full context.
 */
export interface PromptLayer {
  level: PromptLayerLevel
  priority: number
  content: unknown
  token_estimate?: number
  source_ref?: string
  immutable?: boolean
}

/**
 * Result of fitting prompt layers into a token budget.
 */
export interface BudgetFitResult {
  fitted: PromptLayer[]
  omitted: PromptLayer[]
  omissions: string[]
  total_tokens: number
}

/**
 * Interface for loading prompt layers from external resources.
 * Implemented by ContextAssembler or separate loader.
 */
export interface PromptLayerLoader {
  load_runtime_invariant(): PromptLayer
  load_role(role: AgentType): PromptLayer
  load_project_rules(project: { project_id: string; project_root: string }): PromptLayer[]
  load_task_context(
    spec: {
      id: string
      type: string
      title: string
      description: string
      acceptance_criteria: string[]
    },
    context_refs: { plan_ref?: string; arc_ref?: string; artifacts?: string[] }
  ): PromptLayer[]
}