package com.correx.core.inference

/**
 * Cancellation contract for inference calls.
 *
 * ## Coroutine contract
 * Implementations of [InferenceProvider.infer] MUST honour cancellation cooperatively.
 * Checkpoints are mandatory at:
 *   - before the HTTP/socket write
 *   - after each streamed chunk (if streaming)
 *   - before parsing the final response
 *
 * Use `kotlinx.coroutines.ensureActive()` at each checkpoint.
 * Blocking calls must be wrapped with `withContext(Dispatchers.IO)` and must
 * not suppress `CancellationException`.
 *
 * ## Timeout / token interaction
 * Direction is one-way: when a deadline fires, the harness cancels this token (calling
 * [cancel] with [CancellationReason.StageTimeout]). The reverse is NOT true — calling
 * [cancel] on this token for any other reason MUST NOT retroactively record or signal a
 * timeout. Only a fired [InferenceTimeout] deadline triggers [CancellationReason.StageTimeout].
 *
 * ## Event contract
 * On cancellation, the provider MUST emit [com.correx.core.events.events.InferenceTimeoutEvent] (for deadline
 * exceeded) or allow the harness to emit [com.correx.core.events.events.InferenceFailedEvent] with
 * [CancellationReason] attached. The provider MUST NOT swallow the cancellation.
 */
interface InferenceCancellationToken {
    val isCancelled: Boolean
    fun cancel(reason: CancellationReason)
}
