//! `CompileContext` — the per-module wasm assembly state shared across

//! every codegen path.

//!

//! Split across topic-focused submodules so each file stays under the

//! ~500-line CLAUDE.md guideline:

//! - [`host_fn`] — host-fn import registration + lookup.

//! - [`types`] — concrete + abstract heap-type accessors

//!   (`ratio_ref`, `commodity_ref`, `pair_ref`, `anyref`, ...).

//! - [`registry`] — section-level registration: types, imports,

//!   functions, exports, data segments, and the local-pool

//!   allocator.

//! - [`pair`] — `$pair`/`$i8_array` setup + entity allocators +

//!   string-eq helper.

//! - [`commodity`] — commodity-arithmetic helpers

//!   (`commodity_new`, `commodity_add`/sub/neg/scale/cmp/...).

//! - [`ratio`] — ratio-arithmetic helpers (`ratio_new`, `gcd`,

//!   binops, comparisons).

//!

//! Construction lives here in `mod.rs`: every entry point assembles

//! the engine by calling submodule helpers in order.

pub(crate) mod closure;

mod commodity;

mod commodity_compound;

mod entity_registry;

mod exception;

mod host_fn;

mod ids;

pub(in crate::compiler) mod monomorph;

mod pair;

mod ratio;

mod registry;

mod snapshot;

mod types;

mod unit_term;

#[cfg(test)]

mod tests;

#[cfg(test)]

mod snapshot_tests;

use std::collections::{HashMap, HashSet};

use tracing::debug;

use wasm_encoder::{

    CodeSection, DataCountSection, DataSection, ElementSection, Elements, ExportKind,

    ExportSection, Function, FunctionSection, ImportSection, Instruction, MemorySection,

    MemoryType, Module, TagSection, TypeSection, ValType,

};

use super::layout::OutputSerializer;

use crate::ast::{Expr, WasmType};

use crate::error::Result;

use crate::host_fn::HostFnSpec;

pub(crate) use closure::CLOSURE_LITERAL_LEN;

#[derive(Debug, Clone)]

pub(crate) struct HostFnEntry {

    pub func_idx: u32,

    pub params: Vec<WasmType>,

    pub result: Option<WasmType>,

}

/// Base index for user-allocatable locals (after pre-allocated slots)

pub const LOCAL_POOL_BASE: u32 = 6;

pub struct CompileContext {

    pub(in crate::compiler::context) types: TypeSection,

    pub(in crate::compiler::context) imports: ImportSection,

    pub(in crate::compiler::context) functions: FunctionSection,

    pub(in crate::compiler::context) memories: MemorySection,

    pub(in crate::compiler::context) tags: TagSection,

    pub(in crate::compiler::context) exports: ExportSection,

    pub(in crate::compiler::context) data: DataSection,

    pub(in crate::compiler::context) codes: CodeSection,

    pub(in crate::compiler::context) data_count: u32,

    pub(in crate::compiler::context) type_count: u32,

    pub(in crate::compiler::context) tag_count: u32,

    pub(in crate::compiler::context) import_func_count: u32,

    pub(in crate::compiler::context) local_func_count: u32,

    pub(in crate::compiler::context) type_cache: HashMap<Vec<ValType>, HashMap<Vec<ValType>, u32>>,

    /// Maps a declared helper-function / import NAME to its wasm function index.

    /// Written during the declare phase; read once by [`Self::resolve_ids`] to

    /// populate the typed `WasmIds`, and by `export_func` /

    /// `declared_func_index`. Emit code never touches it — it reads `self.ids`.

    pub(in crate::compiler::context) func_names: HashMap<String, u32>,

    pub(in crate::compiler::context) host_fns: HashMap<String, HostFnEntry>,

    pub(in crate::compiler::context) pending_helpers: Vec<Function>,

    pub(in crate::compiler::context) next_local: u32,

    pub(in crate::compiler::context) local_types: Vec<(WasmType, u32)>,

    pub(in crate::compiler::context) serializer: OutputSerializer,

    pub(in crate::compiler::context) closures: closure::ClosureRegistry,

    /// Source `(params, body)` of each value-position lambda, keyed by the wasm

    /// local index its closure value was bound to. A let-bound closure is

    /// emitted with FIXED (param-usage-inferred / default-Ratio) param types, so

    /// applying it via `call_ref` over a list whose element type differs is a

    /// type mismatch. A higher-order native (FOLD/MAP/FILTER) recovers the body

    /// here and INLINES it per element instead — binding the iteration param to

    /// the actual element type — so the closure works over String/I32/Entity

    /// lists, not just Ratio. Keyed by local index (unique per binding); the

    /// closure SIG is shared across structurally-identical lambdas and can't

    /// distinguish bodies.

    pub(in crate::compiler::context) closure_bodies: HashMap<u32, (crate::ast::LambdaParams, Expr)>,

    pub(in crate::compiler::context) declared_funcs: Vec<u32>,

    pub(in crate::compiler::context) monomorphs: monomorph::MonomorphCache,

    pub(in crate::compiler::context) nomi_error_tag: Option<u32>,

    /// Resolved wasm fn/type indices for emit. Seeded poison

    /// ([`ids::WasmIds::UNRESOLVED`]) in `new_skeleton`, overwritten with the

    /// real indices by `resolve_ids` at the end of each public constructor —

    /// before any emit can read it. See `context/ids.rs`.

    pub(in crate::compiler) ids: ids::WasmIds,

    inlining_stack: Vec<String>,

    inlining_set: HashSet<String>,

    block_labels: Vec<BlockLabel>,

    tag_frames: Vec<TagFrame>,

    unwind_frames: Vec<UnwindFrame>,

}

/// One active `(unwind-protect)` frame, live while its protected body

/// compiles. A non-local lexical exit — `(return-from)` / `(go)` whose

/// target lies *outside* this unwind-protect — must run this cleanup before

/// branching (Common-Lisp semantics), so the exit-site codegen walks the

/// frame stack and emits the cleanup of every crossed frame inline, then

/// `br`s. `threshold` is the `block_depth()` the unwind-protect sat at

/// (`parent_depth`); an exit whose target wasm-depth is `<= threshold`

/// leaves this frame and so triggers its cleanup. `cleanup` is the cleanup

/// forms' AST, recompiled for effect at each crossing exit (the normal /

/// exceptional convergence path emits its own copy independently).

#[derive(Debug, Clone)]

pub(in crate::compiler) struct UnwindFrame {

    pub threshold: u32,

    pub cleanup: Vec<Expr>,

}

/// One frame on the lexical BLOCK stack. `wasm_depth` is the

/// `FunctionEmitter::block_depth()` reading captured *after* the

/// matching `block` instruction was emitted, so a `(return-from name v)`

/// sees a stable br target across nested IF / DOLIST / DO frames inside

/// the body. The frame is popped when control leaves the BLOCK form.

///

/// The block's result type is discovered at emit time: each reachable

/// `(return-from name v)` compiled inside the body records `v`'s

/// `WasmType` in `recorded_exits`. Because only *compiled* (reachable)

/// exits record — code stored as a value (quote / lambda / labels bodies,

/// discarded macro args) is never compiled in value position — the set is

/// exactly the live exits, with no syntactic pre-scan.

#[derive(Debug, Clone)]

pub(in crate::compiler) struct BlockLabel {

    pub name: String,

    pub wasm_depth: u32,

    pub recorded_exits: Vec<WasmType>,

}

/// One TAGBODY frame. Each tag in the body has a stable ordinal `pc` (its

/// position in the source order, base-zero) and a wasm-block depth captured

/// when emit reaches its segment. `(go tag)` resolves the named tag,

/// stores the next `pc` into `pc_local`, and branches to the dispatcher

/// `loop` so `br_table` re-enters at the right segment.

#[derive(Debug, Clone)]

pub(in crate::compiler) struct TagFrame {

    pub tags: Vec<TagEntry>,

    pub pc_local: u32,

    pub loop_depth: u32,

}

#[derive(Debug, Clone)]

pub(in crate::compiler) struct TagEntry {

    pub name: String,

    pub pc: u32,

}

impl CompileContext {

    /// Builds an eval-mode compile context: same types and ratio helpers as

    /// script mode, but exports `nomi-eval` (returning `(ref null any)`)

    /// instead of `should_apply`/`process`. Each entry in `host_fns`

    /// gets a wasm import declared up-front (so the function index is

    /// stable for codegen) plus an entry in the lookup table the native

    /// dispatcher consults when emitting calls. The host decodes the

    /// nomi-eval return via `scripting::runtime::decode_eval_result`.

        // `env.log` is the output channel for PRINT / DISPLAY / NEWLINE / DEBUG.

        // It was script-mode-only; without it those natives' `ctx.func("log")`

        // had no func index in eval mode. Declared before the local `nomi-eval`

        // fn so the import index space stays contiguous. Host side: the rpc

        // Session linker wires `env.log` (mirrors `scripting::host`).

        }

        // Two-phase (declare → resolve → build): declare every helper signature

        // so all indices exist, snapshot them into `ids`, then emit the bodies

        // reading `ids`. Declare order fixes the function-index space; build

        // order fixes `pending_helpers` + data-segment indices — both preserved

        // exactly as the pre-split single-pass layout, so the wasm is identical.

            "eval compile context initialized"

        );

    /// Declares the `(error 'code "msg")` lowering target up-front so

    /// the function index is stable before any user host fn is wired.

    /// The native is declared as `(string-ref, string-ref) -> ()` —

    /// it never returns normally; the host always produces

    /// `Err(__nomi_raise:CODE:MSG)` which the classifier parses before

    /// the unreachable-trap branch (ADR-0014). See

    /// `rpc::natives::raise` for the host side.

    /// Declares the `(catch-each items var body)` lowering target up-front.

    /// The body is compiled to a real wasm fn (Tier 1.5 closure machinery)

    /// whose funcref + env are extracted at the call site and passed to

    /// `__nomi_catch_each` along with the items list. The host walks the

    /// chain in Rust, calls the funcref per item recovering per-call

    /// `wasmtime::Error`, and returns a heterogeneous `pair<anyref>`

    /// chain of `(ok . v)` / `(err . (code . msg))` cells. Engine-bound

    /// `OutOfFuel` / `EpochInterrupt` traps re-throw straight through —

    /// they never appear as `err` cells (ADR-0025).

        // Items + result go on the wire as abstract `(ref null struct)`.

        // The host registers the fn with `Rooted<StructRef>` whose

        // `WasmTy::valtype()` is the abstract heap type — declaring the

        // concrete `$pair` here would fail the import-type check at

        // instantiation. Compiler emits a `ref.cast` after the call to

        // recover the concrete `$pair` for the downstream pipeline; the

        // items-arg side accepts a `(ref null $pair)` because the struct

        // subtype relationship is one-way (concrete <: abstract).

        // Type indices are captured into `ids.ty_*` AS each type registers, so

        // the type-ref accessors (`ratio_ref`, `pair_ref`, …) read `ids` even

        // mid-skeleton — before the helper-fn `resolve_ids` runs. The struct

        // layouts + registration order are unchanged, so the wasm is identical.

        // Commodity unit-term (ADR-0028): a flat `(array (mut i64))` of sorted

        // canonical `(hi, lo, exp)` triples. Registered before `commodity` so

        // the struct's 5th field can reference it. A NULL term means ATOMIC

        // `[(atom, 1)]`, so atomic money leaves the field unset and round-trips

        // exactly as before this widening.

        // Commodity = (i64 numer, i64 denom, i64 commodity_hi, i64 commodity_lo,

        // (ref null $unit_term) term). commodity_hi/lo carry the two halves of

        // the UUID, stored as i64 to match wasmtime host-fn primitive types

        // (reassembled to Uuid at the host boundary via `Uuid::from_u128`).

        // Fields 0-3 are byte-identical to the pre-ADR-0028 layout.

        // Server-entity wasm struct types. Field layouts read from

        // the single-source-of-truth `ENTITY_SPECS` table in

        // `entity_registry.rs` — both this site and

        // `register_entity_allocators` walk the same const so the

        // struct layout and the allocator signature can't drift.

        // Adding a new entity kind: extend `EntityKind` in =ast.rs= +

        // add one row to `ENTITY_SPECS`. The recursive `ReportNode`

        // case is no longer special-cased here — its `PairRef` field

        // resolves to `(ref null $pair)` which `$pair` (registered

        // earlier in this skeleton) already supplies.

        }

        // `$nomi_condition` struct + `$nomi_error` exception tag (Tier 3,

        // ADR-0026). Registered here so the type/tag indices are stable

        // before any body emits a `throw` / `try_table`. The tag's payload

        // is a single `(ref null $nomi_condition)` so a catch hands the

        // handler the condition ref directly.

        // Tier 3: the boundary wrapper around `process` / `should_apply`

        // bridges an uncaught `$nomi_error` to `__nomi_raise`, so script

        // mode must declare the import too (it was eval-mode-only). Must

        // precede the first `register_function` so the import index space

        // stays contiguous. Host side: `scripting::host::define_host_functions`.

        // Two-phase (declare → resolve → build); see `new_eval_with_host_fns`.

        // `should_apply` / `process` keep their function-index slots (declared

        // around the helper declarations exactly as before); helper BODIES land

        // on `pending_helpers` in build order, which the `should_apply`

        // split-drain (bootstrap count) consumes unchanged.

    /// Declares the `env.log` import — the host output channel shared by

    /// PRINT / DISPLAY / NEWLINE / DEBUG (`(i32 level, i32 ptr, i32 len) -> ()`).

    /// Used by both module modes so the `log` func index always exists wherever

    /// those natives can be emitted.

    /// Emits `should_apply`, then drains the first `bootstrap_count`

    /// queued helpers so their code-section slots line up with the

    /// function-section slots reserved between `should_apply` and

    /// `process` during context bootstrap. Helpers the user's `process`

    /// body queued (e.g. a real wasm fn for a `(lambda ...)` value) stay

    /// in the queue until [`add_process`] drains them after the

    /// `process` body lands. Pass `usize::MAX` (or any value `>=` the

    /// pending count) to drain everything — the helper bootstrap path

    /// in tests goes that route.

            bootstrap_count,

            "emitting should_apply with split-drain helpers"

        );

        // User code in `process` may register lambda / defun helpers

        // whose function-section indices land *after* `process`. Their

        // bodies have to appear in the code section in the matching

        // order, so drain after the `process` body — `add_should_apply`

        // earlier already drained the bootstrap-time helpers

        // (ratio/commodity/pair) that were registered before `process`.

    /// Tracks active defun / lambda inlining frames so a body that

    /// re-enters itself can be flagged before the compiler stack

    /// overflows. The inline-call path is load-bearing const-fold (see

    /// ADR-0027 / Tier 1.5 reframe): recursion terminates only because

    /// each walk reduces args toward a base case via constant folding.

    /// With a runtime arg the walk re-enters the same body without

    /// progress; the runtime-call path that would terminate the

    /// recursion at one level is the next-tier follow-up.

    /// Push an inlining frame, erroring past [`MAX_INLINE_DEPTH`]. The codegen

    /// inline path (`compile_lambda_call`) walks a defun body recursively;

    /// const recursion with no foldable base case (or simply very deep

    /// const-folded recursion) would otherwise recurse the compiler's native

    /// stack until it overflows. This turns that into a structured compile

    /// error — the codegen-path analogue of `SymbolTable::enter_inline`.

    /// Records `func_idx` as ref-able via `ref.func`. Wasm requires every

    /// `ref.func` operand to appear in either an import/export, a global

    /// initializer, or a declared element segment — lambda helpers are

    /// none of those, so we collect their indices and emit a single

    /// declared-funcref segment in [`Self::finish`].

    /// Push a lexical BLOCK frame so a `(return-from name v)` walking

    /// the stack from innermost to outermost can resolve the wasm-block

    /// it refers to. `wasm_depth` is the emitter's depth the body is

    /// compiled at (the depth the `block` frame will occupy once spliced).

    /// Pop the named BLOCK frame, returning the exit types its reachable

    /// `(return-from)`s recorded during body emit. The caller unifies them

    /// (with the fall-through tail, if any) into the block's result type.

        }

    /// Record a reachable `(return-from name v)` exit's value type into the

    /// innermost matching BLOCK frame, so emit-time discovery can unify the

    /// block's result type from exactly the exits that compile.

    /// Push an `(unwind-protect)` frame so a non-local exit crossing it runs

    /// its cleanup. `threshold` is the unwind-protect's `parent_depth`; an

    /// exit to a wasm-depth `<= threshold` leaves the frame.

        }

    /// REMOVE and return every active unwind-protect frame an exit to

    /// `target_depth` crosses, innermost-first. A frame is crossed when the

    /// exit lands at or above (shallower than) its `threshold`. Removing them

    /// (rather than cloning) MASKS them for the duration of cleanup emission:

    /// a `(return-from)` / `(go)` *inside* one of these cleanups then only

    /// sees the OUTER frames, so a cleanup can't re-schedule itself (which

    /// would recurse forever / double-run). The caller MUST call

    /// [`Self::restore_unwind_frames`] with the returned frames afterward, so

    /// sibling branches of the protected body (compiled later on the same

    /// frame stack) still see them.

    ///

    /// Because the frame stack is monotonic in `threshold` (a deeper-nested

    /// unwind-protect pushes a higher `parent_depth`), the crossed frames are

    /// exactly the contiguous top run with `threshold >= target_depth`.

    /// Restore frames removed by [`Self::take_unwind_frames_crossing`], in

    /// their original (bottom-to-top) order.

    /// The cleanup ASTs of `frames`, innermost-first (the order they must run).

    /// Push a TAGBODY frame so `(go tag)` walking the stack from innermost

    /// outward can resolve the wasm-loop it has to jump back to. Returned

    /// after the matching `loop` instruction is emitted (so `loop_depth`

    /// records the emitter's depth at that moment).

        }

        }

        // Tag section (ID 13) sits after Memory and before Export in the

        // exception-handling proposal's section order.

}