/**
 * Core interfaces for the GateRunner control plane.
 *
 * GateContext  – snapshot passed into every policy evaluation.
 * GateFinding – a single observation from one policy.
 * GateDecision – the aggregated result of evaluating all policies at a checkpoint.
 */

import type { ActiveRun, KdPhase } from "../types.ts";
import type { GateCheckpoint, GateSeverity } from "./taxonomy.ts";

// ── GateContext ──────────────────────────────────────────────────────────────

/**
 * Snapshot of the runtime state at a gate checkpoint.
 *
 * Only the fields relevant to the current checkpoint are populated.
 * Policies MUST NOT mutate the context; they read it and return findings.
 */
export interface GateContext {
	/** Working directory for the current run. */
	cwd: string;

	/** Which checkpoint triggered this gate evaluation. */
	checkpoint: GateCheckpoint;

	/** The active run object, if one exists. */
	run?: ActiveRun;

	/** Tool name, populated at pre-tool / post-tool checkpoints. */
	toolName?: string;

	/** File path under evaluation, populated at pre-write / post-write / pre-tool. */
	path?: string;

	/** Shell command under evaluation, populated at pre-verify-command. */
	command?: string;

	/** Delegation target role, populated at pre-delegation / post-delegation. */
	delegationRole?: string;

	/** Target phase for a transition, populated at pre-phase-transition. */
	phaseTarget?: KdPhase;

	/** Arbitrary checkpoint-specific payload (tool args, write content, etc.). */
	payload?: unknown;
}

// ── GateFinding ──────────────────────────────────────────────────────────────

/**
 * A single observation produced by one policy during gate evaluation.
 *
 * Every finding must declare its severity, the policy that produced it,
 * a human-readable message, and (for blocking severities) a suggested nextAction.
 */
export interface GateFinding {
	/** Unique finding id, formatted "F-001", "F-002", etc. */
	id: string;

	/** How this finding affects the gate decision. */
	severity: GateSeverity;

	/** Name of the policy that produced this finding. */
	policy: string;

	/** Human-readable description of the issue. */
	message: string;

	/** Suggested next action for the agent or user to resolve the finding. */
	nextAction?: string;

	/** Path to an evidence file supporting this finding. */
	evidencePath?: string;

	/** Source references (file paths, line numbers, URLs) related to this finding. */
	sourceRefs?: string[];
}

// ── GateDecision ─────────────────────────────────────────────────────────────

/**
 * The aggregated result of evaluating all registered policies at a checkpoint.
 *
 * Computation rules (applied by GateRunner):
 *   - Any hard-deny finding  → allowed = false
 *   - Any soft-deny finding  → allowed = false (unless explicitly authorized)
 *   - evidence-required      → blocks phase advance but not necessarily tool calls
 *   - warning                → records only, never blocks
 */
export interface GateDecision {
	/** Whether the action at this checkpoint is permitted to proceed. */
	allowed: boolean;

	/** The checkpoint at which this decision was made. */
	checkpoint: GateCheckpoint;

	/** All findings collected from policy evaluations. */
	findings: GateFinding[];

	/** Trace id for ledger correlation, formatted "gate-{timestamp}-{random_hex_6}". */
	traceId: string;
}