/**
 * Pure types of the AI-review approval plugin: the plugin config, the closed
 * reviewer verdict vocabulary, and the three log-only session events. Free of
 * runtime code so type-only consumers load nothing executable.
 *
 * @module @deepseek-ai/dsh-approval-ai-review/types
 */

import type { ToolCallId } from '@deepseek-ai/dsh-llm'

declare module '@deepseek-ai/dsh-session-projection/types' {
  interface SessionProjectionStateMap {
    /**
     * The reviewer's incrementally maintained session knowledge: the enabled
     * switch and the bounded tool-call argument index. Key absence means the
     * plugin's projection unit is not composed.
     */
    'approval-ai-review': ApprovalReviewProjectionState
  }
}

/**
 * The closed verdict one AI review may return. `approve` auto-grants the ask
 * (`'allowed-once'`); `escalate` delegates the ask to the remaining answerers
 * with the review's analysis attached. There is no `reject`: the human is the
 * final authority, so every non-approve outcome escalates.
 */
export type ReviewVerdict = 'approve' | 'escalate'

/** One parsed reviewer response, validated at the model-JSON boundary. */
export interface ReviewVerdictRecord {
  /** The closed verdict. */
  readonly verdict: ReviewVerdict
  /** What the operation will do, in the session's language. */
  readonly explanation: string
  /** Concrete risks of the operation, when the reviewer named any. */
  readonly risks?: string
}

/**
 * The reasoning-effort ids this plugin accepts for the review call. They are
 * the DeepSeek adapter's effort vocabulary; the adapter validates the exact
 * model's advertised efforts before I/O, so an unsupported value fails the
 * review (which escalates) rather than the boot.
 */
export type ReviewReasoningEffort = 'off' | 'low' | 'high' | 'max'

/**
 * The `approval-ai-review` session projection state: the reviewer's answer to
 * "what does this session's log say", maintained incrementally from committed
 * events so the reviewer never reads event history synchronously.
 */
export interface ApprovalReviewProjectionState {
  /** The last `approval/review/enabled` switch, or `null` before one. */
  readonly enabled: boolean | null
  /** Raw `tool/call` arguments JSON by call id, truncated at `maxArgumentsChars`. */
  readonly toolCalls: Readonly<Record<string, string>>
}

declare module '@deepseek-ai/dsh-session/types' {
  interface SessionEventMap {
    /**
     * Log-only pre-dispatch record of one AI review request (like
     * `session/title-llm-request`): the exact route, effort, pending-ask
     * facts, and the verbatim system and user prompts, so the auxiliary model
     * call is reconstructable from the session log. Paired with the
     * `approval/review/verdict` that follows when the review produced one.
     */
    'approval/review/request': {
      /** Exact auxiliary LLM route. */
      route: { provider: string; model: string }
      /** Exact reasoning effort sent for the call. */
      reasoningEffort: ReviewReasoningEffort
      /** The tool the pending ask is about. */
      toolName: string
      /** The exact tool call being decided, when the asker had one. */
      callId?: ToolCallId
      /** The asker's stated reason, verbatim. */
      askerReason?: string
      /** The tool call's raw arguments JSON, when the log supplied one. */
      toolArguments?: string
      /** Exact auxiliary system prompt. */
      system: string
      /** Exact auxiliary user input. */
      input: string
      /** Exact auxiliary output-token cap. */
      maxTokens: number
    }
    /**
     * The parsed outcome of a prior `approval/review/request` — log-only.
     * Appended only when the review produced a validated verdict; a review
     * that failed (transport, deadline, malformed output) leaves the pair
     * unbalanced and the eventual `approval/decided` outcome records the
     * escalation the failure produced.
     */
    'approval/review/verdict': {
      /** The closed reviewer verdict. */
      verdict: ReviewVerdict
      /** What the operation will do, verbatim from the reviewer. */
      explanation: string
      /** Concrete risks, verbatim from the reviewer, when named. */
      risks?: string
    }
    /**
     * The session's AI-review switch was toggled — log-only, durable,
     * replayable, never in the model transcript. The LAST such event is the
     * session's override; its absence means the composition `enabled` default
     * applies.
     */
    'approval/review/enabled': { enabled: boolean }
  }
}