package com.correx.core.kernel.orchestration

import com.correx.core.events.events.ReviewFinding
import com.correx.core.events.events.ReviewVerdict
import com.correx.core.events.types.SessionId
import com.correx.core.events.types.StageId
import java.nio.file.Path

/** Result of a semantic review over a stage's produced files. */
data class ReviewOutcome(
    val verdict: ReviewVerdict,
    val findings: List<ReviewFinding>,
)

/**
 * Seam for the Gate 3 semantic (LLM) reviewer. Like the other gate seams
 * ([ContractAssertionEvaluator], [StaticAnalysisRunner], [PlanCompilationCheck]), the
 * inference-and-filesystem-touching implementation lives in apps/infrastructure and is injected, so
 * the deterministic core never runs inference or reads files itself and the gate stays
 * unit-testable with a fake.
 *
 * The implementation reads the actual produced [files] from [workspaceRoot] (the FileWritten
 * manifest — never blind context), reviews them against [objective], and returns PR-comment-style
 * findings. Runs last, after the deterministic funnel (contract/static/execution) has passed, so its
 * input is static-clean and its findings exclude anything the cheap gates already catch.
 */
fun interface SemanticReviewer {
    suspend fun review(
        sessionId: SessionId,
        stageId: StageId,
        workspaceRoot: Path,
        files: List<String>,
        objective: String,
    ): ReviewOutcome
}
