~[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

// 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

// 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)
~[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