// ============================================================
// BUILD REQUIREMENTS - Self-documenting build dependencies
// ============================================================
// Modules declare their build requirements for backend.zig compilation.
// The frontend collects these during compilation and generates build.zig.
// 
// Usage:
//   ~compiler:requires {
//     exe.linkSystemLibrary("sqlite3");
//   }
// 
// [norun] annotation prevents auto-execution - frontend reads from AST instead.
// This makes build.zig generation metacircular - discovered by parsing, not hardcoded!
~[comptime|norun]pub event requires {
    source: Source
}

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

// ============================================================
// COMPILER COMMANDS - User-definable CLI commands
// ============================================================
// Modules can declare CLI commands that run instead of normal compilation.
// Commands have full AST access and run in the backend compilation phase.
// 
// Usage (in your module, e.g. package.kz):
//   ~import "$std/compiler"
// 
//   ~std.compiler:command.declare {
//     "name": "i",
//     "alias": "install",
//     "description": "Install npm packages from requires.npm declarations"
//   }
// 
//   ~[comptime|command]pub event install {
//       program: *const Program,
//       allocator: std.mem.Allocator,
//       argv: []const []const u8,
//   }
// 
//   ~proc install {
//       // Full AST access - walk program for requires.npm, etc.
//   }
// 
// Invoke: koruc main.kz install [args...]
// Or:     koruc main.kz i [args...]
// 
// Commands appear in --help under "Commands:" section.
// [norun] prevents auto-execution - collected from AST like flags.
~[comptime|norun]pub event command.declare {
    source: Source
}

// Composable pipeline segments - users can mix and match!
// 
// Helper: Create CompilerContext from ast and allocator
~pub event context_create {
    program_ast: *const Program, allocator: std.mem.Allocator
}
| created { ctx: CompilerContext }

// Helper: Format metrics string
~pub event metrics_format {
    passes_completed: u32, allocator: std.mem.Allocator
}
| formatted { metrics: []const u8 }

// 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: "frontend") |> ...
~[comptime]pub event ast_dump {
    ctx: CompilerContext,
    flag: []const u8
}

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

// Zig code emission event - the final step of compilation!
~pub event emit_zig {
    ctx: CompilerContext
}
| ctx { ctx: CompilerContext, code: []const u8 }

// Comptime evaluation pass - executes events with Program/Source parameters
~pub event evaluate_comptime {
    ctx: CompilerContext
}
| ctx CompilerContext

// Structural shape checking - validates events/branches exist, base types match
~pub event check_structure {
    ctx: CompilerContext
}
| ctx CompilerContext
| failed { ctx: CompilerContext, message: []const u8 }

// Flow checking - validates control flow properties (when-clause exhaustiveness, etc.)
~pub event check_flow {
    ctx: CompilerContext
}
| ctx CompilerContext
| failed { ctx: CompilerContext, message: []const u8 }

// Auto-discharge insertion - inserts disposal calls before terminators
// Runs BEFORE check_phantom_semantic so checker validates the inserted calls
~pub event pass_auto_discharge {
    ctx: CompilerContext
}
| ctx CompilerContext
| failed { ctx: CompilerContext, message: []const u8 }

// Semantic phantom type checking - validates type-state compatibility using
// the default Koru semantic checker (module-qualified phantom states)
~pub event check_phantom_semantic {
    ctx: CompilerContext
}
| ctx CompilerContext
| failed { ctx: CompilerContext, message: []const u8 }

// Purity checking - trusts [pure] annotations as developer assertions
~pub event check_purity {
    ctx: CompilerContext
}
| ctx CompilerContext
| failed { ctx: CompilerContext, message: []const u8 }

// Dead strip pass - removes unreachable events/flows from the AST
// Walks from entry points, marks reachable events, prunes the rest
~pub event pass_dead_strip {
    ctx: CompilerContext
}
| ctx 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 event inject_ccp {
    ctx: CompilerContext
}
| ctx CompilerContext

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