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

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

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

// Helper: Dump AST as JSON for introspection
// Usage: Insert at key points in pipeline to inspect AST state
// Void event - just prints and continues
// Example: ast-dump(ctx: c, flag: "elaborate") |> ...
~[comptime] pub tor ast-dump { ctx: CompilerContext, flag: string }

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

// Pre-stage transforms: run the transform runner's `.pre` stage BEFORE the
// template pass. A transform that GRAFTS templated code — e.g. std/constructor
// dissolving into a comptime list plus a `for` over the var it just defined —
// must dissolve FIRST, so the template pass then processes the graft as ordinary
// code. Only `.pre`-tagged transforms fire here; `.main`/`.post` still run at
// Phase 2.4 (evaluate-comptime). `.pre` transforms carry @pass_ran, so that later
// all-stages run re-visits them as no-ops. This is the named-stage design: the
// pipeline sprinkles transform stages where they belong, deliberately.
~pub tor run-pre-transforms { ctx: CompilerContext } -> CompilerContext

// [with] scoped-vocabulary resolution (641_010; concept
// frag-parser-library-peg-on-two-glyphs). 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
// event. A flow annotated `[with]` opens the annotated invocation's OWN module
// for otherwise-unresolved names in its lexical subtree: a name stamped to the
// main module that is NOT a real main-module event but IS a real event of that
// module is re-qualified to it. Unresolved-only — a name that genuinely resolves
// in the main module 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

// 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 event 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: []const u8 }

// 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 event - the final step of compilation!
~pub tor emit-zig { ctx: CompilerContext } -> { ctx: CompilerContext, code: []const u8 }

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

// Structural shape checking - validates events/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 event signatures
// (phantom syntax, obligation polarity: KORU033, unknown phantom modules: KORU040).
// Runs BEFORE pass-auto-discharge: an illegal polarity on an event's own
// declaration must be rejected before any obligation-FLOW analysis reasons
// about programs using that event (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 events/flows from the AST
// Walks from entry points, marks reachable events, 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 event/proc for JSON output
// - Universal tap (* -> *) that emits transition events
~pub tor inject-ccp { 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