~[comptime|norun] pub tor flag.declare { source: Source }

~[comptime|norun] pub tor paths { source: Source }

~[comptime|norun] pub tor command.declare { source: Source }

// COMPILER COORDINATION - User-overridable compilation pipeline
//
// The compiler coordinator (user-overridable)
// Abstract: Users can override with std/compiler:coordinate = ...
~[comptime|abstract] pub tor coordinate {
    program_ast: *const Program,
    allocator: std.mem.Allocator
}
| coordinated { ast: *const Program, code: string, metrics: string }
| error string

// Composable pipeline segments - users can mix and match!
//
// Helper: Create CompilerContext from ast and allocator
~pub tor context-create {
    program_ast: *const Program,
    allocator: std.mem.Allocator
} -> CompilerContext

// Comptime interpreter fold: partial evaluation of [comptime] flows whose
// head tor has a pure-Koru bare-return impl. The interpreter (comptime_eval)
// evaluates the head at Stage C and rewrites the flow to its runtime residue
// with the folded value spliced in. Failure is LOUD: an unfoldable foldable
// flow is a compile error carrying the evaluator's diagnostic, never a silent
// pass-through. See docs/comptime_core_ast_inventory.md.
~pub tor fold-comptime { ctx: CompilerContext } -> CompilerContext

// Elaboration segment: resolve names, expand templates, fold comptime — the AST
// arrives as written and leaves in the core form the later segments validate and
// emit. Abstract, can be overridden.
//
// NOT the frontend: `koruc` (src/main.zig) is the frontend, and it parses and
// validates before any of this runs. This segment is the first phase of the
// BACKEND compiler, which is why it can see resolved names at all.
~[comptime|abstract] pub tor elaborate { ctx: CompilerContext } -> CompilerContext

// Analysis segment: Validation passes (abstract, can be overridden)
~[comptime|abstract] pub tor analysis { ctx: CompilerContext }
| ctx CompilerContext
| failed { ctx: CompilerContext, message: string }

// Tap transformation segment: Insert tap invocations into AST
// This converts taps from emission-time code injection to AST nodes,
// enabling the optimizer to see and optimize them (zero-cost abstraction!)
// (abstract, can be overridden)
~[comptime|abstract] pub tor transform-taps { ctx: CompilerContext } -> CompilerContext

// Test generation segment: Generates Zig test blocks from test declarations
// Runs AFTER analysis (purity is propagated) but BEFORE optimization
// This uses the SAME emitter as emission - no hand-rolled code generation!
~[comptime|abstract] pub tor test-generation { ctx: CompilerContext } -> CompilerContext

// Emission segment: Final code generation (abstract, can be overridden)
// The default impl routes on the compile target: target-of selects which
// emit-* tor produces the artifact — per-target emission is a pipeline
// decision, overridable like any other step, not an if-chain inside one proc.
~[comptime|abstract] pub tor emission { ctx: CompilerContext } -> { ctx: CompilerContext, code: string }

// Parser service - makes the Koru parser available at backend comptime
// This enables dynamic module loading during compilation passes
~pub tor parse { source: string, module_name: string }
| parsed []Item
| failed string

// Zig code emission tor - the final step of compilation!
~pub tor emit-zig { ctx: CompilerContext } -> { ctx: CompilerContext, code: string }

// Comptime evaluation pass - executes tors with Program/Source parameters
~pub tor evaluate-comptime { ctx: CompilerContext } -> CompilerContext

// Structural shape checking - validates tors/branches exist, base types match
// Release gate - rejects [prototype] modules under --release (runs first in analysis)
~pub tor check-release-gate { ctx: CompilerContext }
| ctx CompilerContext
| failed { ctx: CompilerContext, message: string }

~pub tor check-structure { ctx: CompilerContext }
| ctx CompilerContext
| failed { ctx: CompilerContext, message: string }

// Flow checking - validates control flow properties (when-clause exhaustiveness, etc.)
~pub tor check-flow { ctx: CompilerContext }
| ctx CompilerContext
| failed { ctx: CompilerContext, message: string }

// Phantom SIGNATURE validation - declaration-shape checks on tor signatures
// (phantom syntax, obligation polarity: KORU033, unknown phantom modules: KORU040).
// Runs BEFORE pass-auto-discharge: an illegal polarity on an tor's own
// declaration must be rejected before any obligation-FLOW analysis reasons
// about programs using that tor (otherwise auto-discharge halts first with
// a spurious KORU030 leak and the declaration error stays dormant).
~pub tor check-phantom-signatures { ctx: CompilerContext }
| ctx CompilerContext
| failed { ctx: CompilerContext, message: string }

// Phantom ARGUMENT validation - the argument-located call-site checks (state
// threading, per-argument "Phantom state mismatch", use-after-discharge).
// Runs BEFORE pass-auto-discharge: a call-site mismatch the user can point at
// must surface with its precise, argument-located diagnostic — not be
// preempted by the inserter's generic "was not discharged" wall, which never
// acknowledges the explicit discharge already present in the source. The
// flow-EXIT obligation-balance walls stay in check-phantom-semantic, after
// insertion, where the inserted disposal calls exist to be credited.
~pub tor check-phantom-args { ctx: CompilerContext }
| ctx CompilerContext
| failed { ctx: CompilerContext, message: string }

// Auto-discharge insertion - inserts disposal calls before terminators
// Runs BEFORE check-phantom-semantic so checker validates the inserted calls
~pub tor pass-auto-discharge { ctx: CompilerContext }
| ctx CompilerContext
| failed { ctx: CompilerContext, message: string }

// Semantic phantom type checking - validates type-state compatibility using
// the default Koru semantic checker (module-qualified phantom states)
~pub tor check-phantom-semantic { ctx: CompilerContext }
| ctx CompilerContext
| failed { ctx: CompilerContext, message: string }

// Purity checking - trusts [pure] annotations as developer assertions
~pub tor check-purity { ctx: CompilerContext }
| ctx CompilerContext
| failed { ctx: CompilerContext, message: string }

// Dead strip pass - removes unreachable tors/flows from the AST
// Walks from entry points, marks reachable tors, prunes the rest
~pub tor pass-dead-strip { ctx: CompilerContext } -> CompilerContext

// CCP observability pass - injects universal observability taps into user AST
// When enabled, this makes every compiled program self-observing by adding:
// - emit_json tor/proc for JSON output
// - Universal tap (* -> *) that emits transition events
~pub tor inject-ccp { ctx: CompilerContext } -> CompilerContext

// Compiler flags
~[comptime] pub tor has-flag { flag: string } -> bool

// Compiler pipeline control flow.
//
// [template] constructs (std/control:if, cond, for) splice host source text
// and only expand where the per-call template pass reaches. Compiler pipeline
// definitions — coordinate overrides and other impl-of-comptime flows — are
// rebuilt downstream of that pass, so templates never expand there; the
// fallback (calling the unreachable stub handler) always fails. Branch here
// on VALUES instead: a plain proc returning a branch union lowers in every
// position — pipeline overrides, walked flows, and plain runtime code.
~[comptime] pub tor branch { cond: bool }
| yes
| no

// Helper: Format metrics string
~pub tor metrics-format {
    passes_completed: u32,
    allocator: std.mem.Allocator
} -> string

// Koru Standard Library: the `dump` part of compiler.kz.
// Joined via `~part dump` in compiler.kz; merged into the compiler
// module at load.
//
// Helper: Dump AST as JSON for introspection
// Usage: Insert at key points in pipeline to inspect AST state
// Void tor - just prints and continues
// Example: ast-dump(ctx: c, flag: "elaborate") |> ...
~[comptime] pub tor ast-dump { ctx: CompilerContext, flag: string }

// Koru Standard Library: the `directives` part of compiler.kz — frontend-read
// compiler directives. Joined via `~part directives` in compiler.kz; merged
// into the compiler module at load.
//
// These tors are never dispatched: [norun] prevents auto-execution and the
// FRONTEND reads the invocation from the AST — discovered by parsing, not
// hardcoded. `requires` declares backend build requirements (build.zig
// generation is metacircular this way); `use` pins the backend itself to a
// minted compiler — it is consumed and stripped before backend emission, so
// the mint name never reaches the closure it selects.
~[comptime|norun] pub tor requires { source: Source }

// Pin the backend to a minted compiler: `std/compiler:use(my-compiler)`.
// `expr` resolves in the mint store; `hash` pins binary identity.
~[comptime|norun] pub tor use { expr: Expression, hash: ?string }

// Koru Standard Library: the `stages` part of compiler.kz.
// Joined via `~part stages` in compiler.kz; merged into the compiler module at load.
//
// The pre-emission AST stage procs: the per-call template pass and the
// `.pre` transform stage that must run before it. They live apart from the
// pass-runner body because they are a named family — graft-aware ordering
// is their whole contract.
//
// Template processor: walks AST, renders any proc whose variant chain
// starts with `template|...` through Liquid, then strips the `template`
// tag so downstream emission sees a plain host-language proc. See
// memory project_proc_variant_pipeline / docs/EFFECT_BRANCHES for the
// `host[:processor]` story this implements.
~pub tor process-template-procs { ctx: CompilerContext } -> CompilerContext

// Koru Standard Library: the `prelate` part of compiler.kz.
// Joined via `~part prelate` in compiler.kz; merged into the compiler module at load.
//
// The pre-template transform sprinkle: runs the `.pre` stage (producers —
// component, store, channel) then `.pre_late` (consumers — std/ctx reads
// synthesized decls) BEFORE the per-call template pass, so consumer output
// is ordinary AST that expands normally. `.main`/`.post` still run at
// Phase 2.4 (evaluate-comptime); `.pre*` transforms carry @pass_ran so the
// later all-stages run re-visits them as no-ops.
~pub tor run-pre-transforms { ctx: CompilerContext } -> CompilerContext

// Compiler target routing + artifact materialization
//
// target-of reads the compile target (--lang / CompilerEnv.lang) and
// selects the matching emission arm; emit-js / emit-cs are the non-zig
// target emitters; the emit-*-artifact chains spell what emission does
// with the code string once it exists — write the artifact, validate
// it, invoke the host toolchain. Ordinary tors in the pipeline: a user
// emission override can drop, reorder, or interpose on any of them.
// Emit-only pipelines and custom Stage-D verbs are user-space
// decisions, not driver privileges.
// ARTIFACT MATERIALIZATION - what emission does with the code
// string once it exists. These are ordinary tors: write the
// artifact, validate it, invoke the host toolchain. A user
// emission override can drop, reorder, or interpose on any of
// them — emit-only pipelines and custom Stage-D verbs are
// user-space decisions, not driver privileges.
//
// Per-target composed artifact chains — one entry per target-of arm.
// `output` names the produced binary (defaults to the -o argv name);
// `dir` stages the emitted artifact under a directory instead of cwd.
~pub tor emit-zig-artifact {
    ctx: CompilerContext,
    output: ?string,
    dir: ?string
} -> { ctx: CompilerContext, code: string }

~pub tor emit-js-artifact {
    ctx: CompilerContext,
    dir: ?string
} -> { ctx: CompilerContext, code: string }

~pub tor emit-cs-artifact {
    ctx: CompilerContext,
    output: ?string,
    dir: ?string
} -> { ctx: CompilerContext, code: string }

// Write the emitted code to its artifact file — `dir` relocates the
// artifact under a directory (created if absent); unset means cwd.
~pub tor write-artifact {
    ctx: CompilerContext,
    code: string,
    name: string,
    dir: ?string
} -> { ctx: CompilerContext, code: string }

// --deep-check: the emitted text must be a parseable program, not just text.
// Replaces the Stage-D build with a zig.Ast witness — fuzz splices land
// Koru-shaped lines inside `proc|zig` bodies and record fields, and both
// paste verbatim into the Zig — a green verdict on emission `zig ast-check`
// refuses. "Emitted" is not the verdict; "emitted valid" is.
~pub tor validate-emitted {
    ctx: CompilerContext,
    code: string
} -> { ctx: CompilerContext, code: string }

// Target routing
//
// Target router: reads the compile target (--lang / CompilerEnv.lang) and
// selects the matching emission arm. `other` is not a fallback — KORU126
// refuses undeclared targets upstream, so the only names that land here
// are declared proc-variant tags (|mlir, |gpu, ...): the tag selects which
// proc bodies emit, and the host artifact stays Zig.
~[comptime] pub tor target-of { ctx: CompilerContext }
| zig
| js
| cs
| other

// JS code emission tor - selected by target-of under --lang=js
~pub tor emit-js { ctx: CompilerContext } -> { ctx: CompilerContext, code: string }

// C# code emission tor - selected by target-of under --lang=cs
~pub tor emit-cs { ctx: CompilerContext } -> { ctx: CompilerContext, code: string }

// Compiler host-build drivers — Stage D of artifact materialization
//
// host-build-zig and host-build-cs are the pipeline-visible toolchain
// verbs: zig build / build-exe / dotnet build, the csproj driver, the
// overlay + optimize-mode + cross-target reads. Ordinary tors like the
// rest of materialization — a user emission override can swap them,
// interpose around them, or drop them for an emit-only pipeline.
// `output` names the produced binary (overrides the -o argv name);
// `dir` is where write-artifact staged the emitted source.
//
// Stage D for the Zig target: zig build (via build_output.zig when the
// program declared build:requires) or a direct build-exe, then place the
// artifact at the -o name. Failures exit non-zero — the compile's verdict
// IS the build's verdict. `output` overrides the -o argv name; `dir` is
// where write-artifact staged output_emitted.zig.
~pub tor host-build-zig {
    ctx: CompilerContext,
    code: string,
    output: ?string,
    dir: ?string
} -> { ctx: CompilerContext, code: string }

// C# Stage D — the dotnet driver of artifact materialization. A minimal
// csproj IS the driver (dotnet has no file-based run): OutputType flips
// with koruc lib (Exe apphost vs callable .dll), AssemblyName lands the
// artifact at the -o path. Ordinary pipeline tor — swappable by a user
// emission override like every other materialization step.
//
// Stage D for the C# target: a minimal csproj IS the driver — dotnet has no
// file-based run, so the apphost lands at exactly the path koruc was asked
// for via AssemblyName. `koruc lib` flips OutputType to Library — the
// artifact is a callable .dll (ASP.NET-loadable), not an apphost.
~pub tor host-build-cs {
    ctx: CompilerContext,
    code: string,
    output: ?string,
    dir: ?string
} -> { ctx: CompilerContext, code: string }

// Koru Standard Library: the `with` part of compiler.kz.
// Joined via `~part with` in compiler.kz; merged into the compiler
// module at load.
//
// resolve-with-scopes: the [with] vocabulary pass and its helpers.
//
// [with] scoped-vocabulary resolution (641_010; concept
// frag-with-declares-the-flows-vocabulary). Stage-A canonicalize stamps the
// MAIN module onto every bare name with no import lookup, so a bare `match`
// inside a grammar region arrives here as `<main>:match` and would die as an
// unknown tor. `[with]` colors its whole flow — position is meaningless, the
// gather runs over the entire subtree before any restamp — and the open set
// is the union of every opener it finds: bare `[with]` derives the annotated
// invocation's own module, `[with(a, b)]` names modules explicitly
// (import-spelled, and each must be imported — KORU142). A bare name stamped
// to its flow's home module that is NOT a real tor there but IS a real tor of
// an opened module is re-qualified to it; matching is on the full dotted
// event name, so `say.hi` and `log.hi` never collide on `hi`. Unresolved-only
// — a name that genuinely resolves at home is never shadowed. Runs BEFORE
// run-pre-transforms so the grammar transform (parser.kz `isVerb` keys off
// the qualifier being present) sees the resolved `std.parser:match`. Mirrors
// canonicalize_names' own flow/continuation/node recursion, so it visits
// exactly the paths it does.
~pub tor resolve-with-scopes { ctx: CompilerContext } -> CompilerContext

// Koru Standard Library: the `desugars` part of compiler.kz.
// Joined via `~part desugars` in compiler.kz; merged into the compiler module at load.
//
// The chain-desugar stage tor: point-free pyramid, bind pun + type thread,
// flow return terminus, and the dead-produce audit — the pass that must run
// after resolve-with-scopes, where every callee name is finally visible.
//
// The AST desugars: the point-free pyramid, the bind pun + type thread, and the
// flow return terminus.
//
// They live HERE, and not in koruc, because each one looks a declaration up BY
// PATH. Stage-A canonicalize stamps `<main>:` onto every bare name, so a
// `[with]`-scoped name is not resolvable until `resolve-with-scopes` has run.
// A desugar running before that found no declaration, silently did nothing, and
// left the failure to surface passes later wearing a different name — an
// undischarged obligation, or a KORU100 for a binding whose only use the pun
// never filled. Ordering, not a lookup bug.
//
// Order among the three is load-bearing: the pyramid first, so the canonical
// explicit-continuation shape exists; then the pun and thread, so every step's
// args are in place; then the terminus, which needs the last step final.
~pub tor desugar-chains { ctx: CompilerContext } -> CompilerContext

// CCP Command Processing Pass
// Reads and processes incoming AI commands from stdin when --ccp is enabled
~pub tor process-ccp-commands { ctx: CompilerContext } -> CompilerContext