aver-lang 0.27.0

//! `MirProgram` + `MirFn` — the top-level shape of Core MIR.
//!
//! Phase 2a of #252. The data model is structured (not flat /
//! basic-block), expression-based (every `MirExpr` is a value), and
//! identity-typed (declaration refs go through `FnId` / `TypeId` /
//! `CtorId`). See [`super::RFC.md`] for the full rationale.

use std::collections::HashMap;

use crate::ir::{FnId, ModuleId};

use crate::ast::Spanned;

use super::expr::{MirEffectAnnotation, MirExpr};
use super::stats::LowerStats;

/// A whole compiled program in Core MIR. Keyed by `FnId` (stable
/// across compilation units; same identity layer the rest of the
/// pipeline consumes). Phase 2a builds an empty `MirProgram`
/// directly; Phase 3 grows the lowering that populates it from
/// `ResolvedProgramView`.
#[derive(Debug, Clone, Default)]
pub struct MirProgram {
    /// All compiled functions, keyed by their `FnId`.
    pub fns: HashMap<FnId, MirFn>,
    /// Optional module identity for tooling that wants to walk
    /// `MirProgram` per source module (LSP outline, future
    /// per-module IR dump). Empty when the program was assembled
    /// from a single entry file with no `depends [...]`.
    pub modules: Vec<ModuleId>,
    /// Coverage telemetry for the lowering that produced this
    /// program. `lowered + skipped.values().sum()` equals the
    /// number of `ResolvedFnDef` items the lowerer saw — see
    /// [`super::stats::LowerStats`] for the coverage gate that
    /// Phase 4 (VM slice) consumes.
    pub stats: LowerStats,
    /// Phase 6 wave 11 — interned built-in fn names. Indexed by
    /// `BuiltinId`. Lowering grows this lazily as it encounters
    /// each unique `ResolvedCallee::Builtin(name)` shape; MIR
    /// consumers (VM walker, Rust walker, optimize passes) look
    /// up the canonical string via `program.builtin_name(id)`
    /// instead of carrying the string inline on every
    /// `MirCallee::Builtin`.
    pub builtins: Vec<String>,
    /// `true` when this program is a *fragment* of a larger build whose
    /// other parts are compiled separately — specifically a dependency
    /// module under the VM's per-module compile (the VM lowers each
    /// `depends [...]` module to its own `MirProgram`). Such a fragment
    /// does NOT see the entry/sibling call sites, so whole-program
    /// analyses that rely on "every caller is visible" (notably
    /// `own_param_refine`) must bail. `false` for a whole-program compile
    /// (single entry, or the flattened wasm-gc / Rust builds), where all
    /// callers are present and graduation is sound.
    pub external_callers_possible: bool,
}

impl MirProgram {
    /// Construct an empty program. Phase 3 lowering will populate
    /// `fns` and `modules` as it walks `ResolvedProgramView`.
    pub fn empty() -> Self {
        Self::default()
    }

    /// Lookup a function by its `FnId`. Returns `None` if the id
    /// wasn't part of this compilation (e.g. a stale id surviving
    /// from a previous program view).
    pub fn fn_by_id(&self, id: FnId) -> Option<&MirFn> {
        self.fns.get(&id)
    }

    /// All functions in arbitrary (`HashMap`) order. Callers that
    /// need a stable walk (snapshot tests, dump output) should sort
    /// by `FnId` themselves.
    pub fn iter(&self) -> impl Iterator<Item = (&FnId, &MirFn)> {
        self.fns.iter()
    }

    /// Phase 6 wave 11 — look up the canonical name behind a
    /// `BuiltinId` minted by this program's lowering. Returns
    /// `""` (empty slice) if the id is out of range — a defensive
    /// fallback for diagnostic paths; consumers in the hot path
    /// should hold valid ids by construction.
    pub fn builtin_name(&self, id: crate::ir::BuiltinId) -> &str {
        self.builtins
            .get(id.0 as usize)
            .map(String::as_str)
            .unwrap_or("")
    }

    /// Phase 6 wave 11 — intern a built-in fn name into this
    /// program's table. Returns the stable `BuiltinId`, reusing
    /// the existing slot when the name has already been
    /// registered. Lowering calls this; downstream optimizer
    /// passes inherit the existing ids when they construct new
    /// `MirCallee::Builtin` instances (e.g. from inlining).
    pub fn intern_builtin(&mut self, name: &str) -> crate::ir::BuiltinId {
        for (idx, existing) in self.builtins.iter().enumerate() {
            if existing == name {
                return crate::ir::BuiltinId(idx as u32);
            }
        }
        let id = crate::ir::BuiltinId(self.builtins.len() as u32);
        self.builtins.push(name.to_string());
        id
    }
}

/// One function in Core MIR. Body is a single `MirExpr` — MIR is
/// expression-based, so the function's body is the expression that
/// produces its return value. `Let` chains within the body bind
/// intermediate results; there's no separate "block" or
/// "terminator" concept at this phase.
#[derive(Debug, Clone)]
pub struct MirFn {
    /// Stable identity for this function. Matches the `FnId` issued
    /// by `SymbolTable` during the existing pipeline; downstream
    /// consumers can cross-reference `ProofIR` / `ProgramShape` by
    /// the same id.
    pub fn_id: FnId,
    /// Source-level name. Carried for dumps + diagnostics; backends
    /// must not key off this string for identity — that's what
    /// `fn_id` is for.
    pub name: String,
    /// Parameters in declaration order. Each gets a fresh `LocalId`
    /// at lowering time so the body can refer to it.
    pub params: Vec<MirParam>,
    /// Source-level return type annotation as it appears on the fn
    /// signature. Phase 4 backends consume this for VM stack-slot
    /// layout; later phases may replace it with a richer type
    /// representation when the typechecker's `Type` enum becomes
    /// the universal vocabulary.
    pub return_type: String,
    /// Declared effects (`! [Namespace.method, ...]`). Function-
    /// level only — per-call-site effect annotation is deferred to
    /// the Phase 6 optimizer track per the RFC.
    pub effects: Vec<MirEffectAnnotation>,
    /// The single expression that, when evaluated, produces the
    /// function's return value. Wrapped in `Spanned` so the body's
    /// own source location stays available to dumps / diagnostics
    /// (the surrounding `MirFn` has its own identity layer via
    /// `fn_id`, but the body span is needed for sub-expression
    /// errors that don't carry a closer one).
    pub body: Spanned<MirExpr>,
    /// Number of frame slots the lowered body needs: the resolver's
    /// `local_count` plus any synthetic slots minted for opaque-let
    /// temps during stmt-chain lowering. The VM walker reserves this
    /// many slots; using the resolver's count alone underruns the
    /// frame when the body stores into a synthetic slot.
    pub local_count: u32,
    /// Per-slot alias-proneness, indexed by `LocalId`/slot: `true`
    /// when the resolver's alias analysis flagged the slot as possibly
    /// sharing its backing engine array/struct with another binding.
    /// Backends combine it with a node's `last_use` to gate the
    /// owned-mutate fast path (`owned = last_use && !aliased`) — the
    /// VM's owned-mask and the wasm-gc clone-on-write skip. Carried on
    /// the MIR fn so MIR consumers read this ownership fact off MIR
    /// instead of reaching back into the AST `FnResolution`
    /// side-channel. Cloned from the resolver at lowering today; a
    /// later phase recomputes it as a MIR analysis pass. An
    /// out-of-range slot reads `false` (not aliased → fast path sound),
    /// matching the resolver tables.
    pub aliased_slots: std::sync::Arc<Vec<bool>>,
    /// **Int-representation tags (ETAP-2).** Populated ONLY by the
    /// `bare_i64::rewrite_for_rust` MIR->MIR pass on the per-target clone
    /// the Rust backend codegens from; default-empty everywhere else (so
    /// the VM / wasm-gc / proof MIR keep all-`Int` representation). When a
    /// slot is in [`MirFnRepr::bare_slots`] it is a raw machine `i64` for
    /// its whole lifetime (its reads render native `i64`, arithmetic over
    /// raw slots stays raw); every crossing into an `Int` context is an
    /// explicit [`super::expr::MirExpr::Box`] node the rewrite inserted.
    /// This is the per-value representation tag made explicit ON the IR --
    /// backends read it off the rewritten `MirFn` instead of re-deriving
    /// from the `BareI64Facts` side table.
    pub repr: MirFnRepr,
}

/// Per-fn Int-representation summary made explicit on the rewritten MIR
/// (ETAP-2 SLICE 1). Default-empty ⇒ everything is the arbitrary-precision
/// `Int` (`aver_rt::AverInt`), the fail-closed baseline. Populated only by
/// `bare_i64::rewrite_for_rust`.
#[derive(Debug, Clone, Default)]
pub struct MirFnRepr {
    /// Locals (params + let bindings + match aliases) the rewrite tagged as
    /// raw machine `i64`. A read of such a slot renders as a native `i64`
    /// ident; arithmetic over raw slots stays raw. A missing slot is `Int`
    /// (boxed) -- fail-closed.
    pub bare_slots: std::collections::HashSet<LocalId>,
    /// Per-param representation, indexed by declaration order (same indexing
    /// `aliased_slots` / `own_param` use): `true` ⟺ the param's Rust
    /// signature type is bare `i64` (and every caller `Box`/`Unbox`es at the
    /// boundary).
    pub bare_params: Vec<bool>,
    /// `true` ⟺ the fn's Rust return type is bare `i64`.
    pub bare_return: bool,
    /// ETAP-2 carrier-`i64` (wasm-gc only): slots holding a BARE carrier value
    /// — an eligible refinement-via-opaque carrier whose wasm storage IS a
    /// native `i64`. A `Project(Local(slot), "value")` over such a slot reads
    /// the i64 DIRECTLY (the codegen skips the `$AverInt` project bridge), so
    /// the `.value` read is a raw-i64 leaf for the native arithmetic the
    /// rewrite left raw. Empty on the Rust backend (carriers stay structs) and
    /// whenever no eligible carrier is in scope — the byte-identical default.
    pub carrier_slots: std::collections::HashSet<LocalId>,
}

impl MirFnRepr {
    /// Is the value bound to `slot` represented as a raw machine `i64`?
    pub fn slot_is_bare(&self, slot: LocalId) -> bool {
        self.bare_slots.contains(&slot)
    }

    /// ETAP-2 carrier-`i64`: does `slot` hold a bare carrier whose `.value`
    /// read renders as a raw native `i64` (no project bridge)?
    pub fn slot_is_bare_carrier(&self, slot: LocalId) -> bool {
        self.carrier_slots.contains(&slot)
    }

    /// Is param index `i` bare in the Rust signature?
    pub fn param_is_bare(&self, i: usize) -> bool {
        self.bare_params.get(i).copied().unwrap_or(false)
    }
}

/// One formal parameter. The `LocalId` is assigned at lowering
/// time and is the binding the function body refers to.
#[derive(Debug, Clone)]
pub struct MirParam {
    /// Local binding introduced for this parameter. The function
    /// body refers to it via `MirExpr::Local(LocalId)`.
    pub local: LocalId,
    /// Source-level parameter name. For dumps + diagnostics only.
    pub name: String,
    /// Source-level type annotation. Same caveat as `MirFn::return_type`.
    pub ty: String,
}

/// Local binding identifier. Unique per function body (not per
/// program) — backends look up the binding by walking the body's
/// `Let` chain, so collision across functions isn't a concern.
///
/// Phase 2 picks "assign at MIR construction time" over "carry the
/// HIR slot index" (the latter was the strawman alternative listed
/// in the RFC). The carry-from-HIR option would have meant MIR's
/// local space matches whatever the resolver chose — fine for the
/// VM consumer, but the future inliner / monomorphizer needs the
/// freedom to introduce fresh locals during optimization passes,
/// and inheriting HIR's numbering would silently overlap with
/// those.
///
/// **Seed during Phase 3 (waves 1-3b):** the lowerer seeds new
/// `LocalId`s from the resolver's slot indices
/// (`ResolvedExpr::Resolved { slot, .. }`, `FnResolution.local_slots`,
/// `ResolvedMatchArm.binding_slots`) and grows synthetic locals
/// from `local_count` upward for `Stmt::Expr` intermediates the
/// resolver didn't see. The slot space is unique per function so
/// reuse is safe. Later optimizer passes are still free to
/// renumber — `LocalId` is just an opaque identity per body, not
/// a promise about resolver lineage.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct LocalId(pub u32);

impl std::fmt::Display for LocalId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "%{}", self.0)
    }
}