Types

import type {
  ContractResult,
  ContractAttempt,
  ContractError,
  AttemptDetail,
  FailureCategory,
  Rule,
  RunFn,
  Message,
  ContractConfig,
  DefinedContract,
  RetryOptions,
  ContractLogger,
} from "@boundary/contract";

type ContractResult<T> =
  | {
      ok: true
      data: T              // typed, validated, all rules passed
      attempts: number     // total attempts made
      raw: string          // the raw LLM output that was accepted
      durationMS: number   // total wall-clock time
    }
  | {
      ok: false
      error: ContractError
    }

type ContractAttempt = {
  attempt: number          // 1-indexed attempt number
  maxAttempts: number      // from retry config
  instructions: string     // auto-generated prompt from schema
  repairs: Message[]       // repair messages from prior failure (empty on first)
  previousError?: ContractError
  previousCategory?: FailureCategory
}

type ContractError = {
  message: string          // human-readable summary
  attempts: AttemptDetail[] // one entry per failed attempt
}

type AttemptDetail = {
  raw: string              // raw LLM output
  cleaned: unknown         // parsed/cleaned output
  issues: string[]         // list of violations
  category: FailureCategory
}

type FailureCategory =
  | "EMPTY_RESPONSE"     // model returned nothing
  | "REFUSAL"            // model refused the task
  | "NO_JSON"            // response contained no JSON
  | "TRUNCATED"          // JSON was cut off
  | "PARSE_ERROR"        // malformed JSON
  | "VALIDATION_ERROR"   // valid JSON, failed schema
  | "INVARIANT_ERROR"    // passed schema, failed rules
  | "RUN_ERROR"          // RunFn threw an error

type Rule<T> = (data: T) => true | string

type RunFn = (attempt: ContractAttempt) => Promise<string | null>

type Message = {
  role: string
  content: string
}

type ContractConfig<T> = {
  schema: ZodType<T>
  rules?: Rule<T>[]
  retry?: RetryOptions
  repairs?: RepairOverrides
  instructions?: { suffix?: string }
  onAttempt?: AttemptHook
  logger?: ContractLogger<T>
  debug?: boolean
}

type RetryOptions = {
  maxAttempts?: number     // default: 3
  backoff?: "none" | "linear" | "exponential"
  baseMs?: number          // default: 200
}

type RepairOverrides = Partial<Record<FailureCategory, RepairFn | false>>
type RepairFn = (detail: AttemptDetail) => Message[]

type ContractLogger<T> = {
  onRunStart?: (ctx: {
    maxAttempts: number
    hasRules: boolean
    retry: RetryPolicy
  }) => void

  onAttemptStart?: (ctx: {
    attempt: number
    maxAttempts: number
    instructions: string
    repairs: Message[]
  }) => void

  onRawOutput?: (ctx: {
    attempt: number
    raw: string
  }) => void

  onCleanedOutput?: (ctx: {
    attempt: number
    cleaned: unknown
  }) => void

  onVerifySuccess?: (ctx: {
    attempt: number
    data: T
    durationMs: number
  }) => void

  onVerifyFailure?: (ctx: {
    attempt: number
    category: FailureCategory
    issues: string[]
    durationMs: number
  }) => void

  onRepairGenerated?: (ctx: {
    attempt: number
    category: FailureCategory
    repairMessage: string
  }) => void

  onRetryScheduled?: (ctx: {
    attempt: number
    nextAttempt: number
    category: FailureCategory
    delayMs: number
  }) => void

  onRunSuccess?: (ctx: {
    attempts: number
    data: T
    totalDurationMs: number
  }) => void

  onRunFailure?: (ctx: {
    attempts: number
    category?: FailureCategory
    message: string
    totalDurationMs: number
  }) => void
}