~[comptime|command] pub tor test {
    program: *const Program,
    allocator: __koru_std.mem.Allocator,
    argv: []string
}

// `score` — the OVERRIDABLE runner seam (abstract event, same pattern as
// compiler:coordinate). The default below scores a case by driving `koruc` as a
// subprocess; a user swaps the entire behavior with `~koru/regressions:score = …`
// (e.g. to run pytest/cargo, or to traverse a dependency graph). "Traverses
// stuff" today = one case; the seam is what a future graph-runner plugs into.
//
// Named `score`, not `run` — the expectation marker below owns `run()`, and a
// tor name is unique per module (measured: two `run` tors emitted a duplicate
// `run_event` struct in the backend).
~[comptime|abstract] pub tor score {
    dir: string,
    base: string,
    allocator: __koru_std.mem.Allocator
}
| passed
| failed string

// The `case` marker: a declared test case, collected from the AST by `test`.
// `expr` = the human label; `source` = a JSON object block. Void at runtime.
~[comptime|norun] pub tor case { expr: Expression, source: Source }

// The EXPECTATION markers — a test file's self-description as declared program
// surface, ADJACENT to the //~ comment directives (ruled Lars 2026-07-17).
// Each is collected from the test program's AST — via its program.ast.json —
// by `run-exec`, the same walk that collects `case` from suite.k. The
// compiler parses, resolves, and validates them: a typo is a compile error
// with a location, an unknown marker is impossible, and "can't drift" lives
// in the type system. Both spellings map onto the same vocabulary:
//
//   //~ run                  <-> koru/regressions:run()
//   //~ compile_fail(stage)  <-> koru/regressions:compile-fail(stage: …)
//   //~ error[ID]: msg       <-> koru/regressions:error(id: "ID", msg: "…")
//   //~ expect: text         <-> koru/regressions:expect(text: "…")
//   //~ expect-not: text     <-> koru/regressions:expect-not(text: "…")
//   //~ leaks: allow reason  <-> koru/regressions:leaks-allow(reason: "…")
//
// One vocabulary, one spelling per test — mixing them is rejected. A
// `compile-fail(stage: frontend)` DECLARED marker is contradictory (a file
// that fails at the frontend never materializes its AST, so it cannot declare
// itself); the frontend-negative kind is spelled with the adjacent //~ form,
// which the runner reads from the file text before compiling.
//
// Positive: compiles, runs, exits 0, no leaks.
~[comptime|norun] pub tor run {}

// Negative, pinned to a stage. `frontend` is unscoreable (see above).
~[comptime|norun] pub tor compile-fail { stage: Expression }

// Diagnostic pin: diagnostic ID + message substring.
~[comptime|norun] pub tor error { id: Expression, msg: Expression }

// Produced-program output must contain this substring.
~[comptime|norun] pub tor expect { text: Expression }

// Produced-program output must NOT contain this substring.
~[comptime|norun] pub tor expect-not { text: Expression }

// Reasoned opt-out of the leak gate — a reason is required.
~[comptime|norun] pub tor leaks-allow { reason: Expression }