package com.correx.core.events.events

import com.correx.core.events.types.SessionId
import com.correx.core.events.types.StageId
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable

/**
 * The known-good workspace invariant (design 2026-07-15 §"Known-good workspace invariant", seam 2).
 * After a code/config-writing stage runs its deterministic build/test gate, the orchestrator records
 * ONE verification observation binding the [passed] result to the [stateKey] of the workspace that was
 * actually verified. The next implementation stage may treat the workspace as `known-good` only when
 * a passing observation's [stateKey] still equals the current recorded state key — a later write
 * changes the key, so a dirty workspace can never be mistaken for the state that passed.
 *
 * The [stateKey] is derived purely from the recorded FileWritten manifest (path → latest post-image
 * hash), so it is replay-safe: replay reads this event and the key back, never re-running [command]
 * or rescanning the filesystem (invariants #8/#9). [changedPaths] are the write-declaring stage's
 * paths at verification time; [expectation] is the deterministic build vocabulary (MODULE/PROJECT/
 * TESTS) that selected [command] — the model never chooses the truth test.
 */
@Serializable
@SerialName("WorkspaceVerificationObserved")
data class WorkspaceVerificationObservedEvent(
    val sessionId: SessionId,
    val stageId: StageId,
    val stateKey: String,
    val expectation: String,
    val command: String,
    val passed: Boolean,
    val changedPaths: List<String> = emptyList(),
) : EventPayload
