package com.correx.core.kernel.orchestration

import com.correx.core.events.types.SessionId

/**
 * Deterministic, kernel-driven task claiming for the execution loop: the kernel — not the LLM —
 * picks and claims the next ready task, so the loop terminates by event-recorded fact rather than by
 * agent compliance (the failure mode the read-before-write logs exposed). Implemented in apps/server
 * over the task projection; core:kernel stays decoupled from core:tasks (mirrors [ReadyTaskCounter]).
 * Null injection ⇒ no claiming and unrestricted task scope.
 */
interface TaskClaimCoordinator {
    /**
     * Ensure the session has a claimed task and return that task's context bundle as L0 text. If the
     * session already has one claimed (e.g. a review bounced it back), re-injects its context without
     * re-claiming; otherwise claims the next ready task. Null when nothing is ready to work.
     */
    suspend fun claimNext(sessionId: SessionId): String?

    /** Write-scope (affected paths) of the task the session currently has claimed; empty when none. */
    fun activeScope(sessionId: SessionId): List<String>

    /**
     * Block the session's currently-claimed task — used when the operator rejects a scope-amendment
     * proposal: the task can't proceed within scope, so it leaves the active/ready set and the loop
     * advances to the next task instead of the implementer retrying the blocked write. No-op when
     * nothing is claimed.
     */
    suspend fun blockActiveTask(sessionId: SessionId, reason: String)
}
