bynk_check/checker/

calls.rs

//! Call / application dispatch.
//!
//! Split out of `checker.rs` (v0.29.10) verbatim; the parent module
//! re-exports these via `use calls::*`.

use super::*;

/// v0.39 (ADR 0072): record a parameter-name inlay hint for one call argument,
/// unless it would be noise — the `_`/`self` placeholders, or an argument that
/// is already the identically-named identifier (`f(count)` for parameter
/// `count`, matching rust-analyzer's suppression).
fn record_param_hint(hints: &mut HintSink, param_name: &str, arg: &Expr) {
    if param_name == "_" || param_name == "self" {
        return;
    }
    if let ExprKind::Ident(id) = &arg.kind
        && id.name == param_name
    {
        return;
    }
    hints.record_param(arg.span, format!("{param_name}:"));
}

#[allow(clippy::too_many_arguments)]
pub(crate) fn check_fn(
    f: &FnDecl,
    input: &ResolvedCommons,
    expr_types: &mut HashMap<ExprId, TypedExpr>,
    callees: &mut HashMap<ExprId, Callee>,
    errors: &mut Vec<CompileError>,
    refs: &mut RefSink,
    hints: &mut HintSink,
    locals: &mut LocalsSink,
    requirements: &mut RequirementSink,
    tys: &Types,
) {
    // v0.20a: the fn's type parameters are *rigid* type variables while
    // checking its own body. A type param shadowing a declared type is
    // confusing — diagnose the collision.
    let mut vars: HashSet<String> = f
        .type_params
        .iter()
        .map(|tp| tp.name.name.clone())
        .collect();
    for tp in &f.type_params {
        if input.types.contains_key(&tp.name.name) {
            errors.push(
                CompileError::new(
                    "bynk.generics.type_arg_mismatch",
                    tp.span,
                    format!(
                        "type parameter `{}` shadows the declared type of the same name",
                        tp.name.name
                    ),
                )
                .with_note("rename the type parameter"),
            );
        }
    }
    // #594: an instance method on a generic type inherits the receiver type's
    // parameters as additional rigid vars, so its signature and body may name
    // them (`self: Box[A]`, `f: A -> U`). The receiver's parameters are the
    // type's own — they never shadow a declared type — so they bypass the guard
    // above.
    if let FnName::Method { type_name, .. } = &f.name
        && let Some(decl) = input.types.get(&type_name.name)
    {
        for tp in &decl.type_params {
            vars.insert(tp.name.name.clone());
        }
    }
    let return_ty = match resolve_type_ref_in(&f.return_type, &input.types, &vars, tys) {
        Some(t) => t,
        None => return,
    };
    record_type_refs(&f.return_type, &input.types, &vars, refs);
    let mut param_scope: HashMap<String, TyId> = HashMap::new();
    // For methods, the implicit `self` parameter has the attached type. #594: on
    // a generic receiver, `self` is the type applied to its own parameters as
    // rigid vars (`Box[A]`), so field access substitutes them and the body's
    // uses of `A` line up with the signature.
    if let FnName::Method { type_name, .. } = &f.name
        && f.has_self
        && let Some(decl) = input.types.get(&type_name.name)
    {
        let self_args = decl
            .type_params
            .iter()
            .map(|tp| tys.intern(Ty::Var(tp.name.name.clone())))
            .collect();
        param_scope.insert("self".to_string(), named_ty_with_args(decl, self_args, tys));
    }
    for p in &f.params {
        if let Some(ty) = resolve_type_ref_in(&p.type_ref, &input.types, &vars, tys) {
            record_type_refs(&p.type_ref, &input.types, &vars, refs);
            // v0.31: a fn parameter is in scope over the whole body.
            if p.name.name != "_" {
                locals.record(
                    p.name.name.clone(),
                    p.name.span,
                    crate::locals::LocalKind::Param,
                    ty.display(tys),
                    f.body.span,
                );
            }
            param_scope.insert(p.name.name.clone(), ty);
        }
    }
    // v0.115: check the function's contract clauses (`requires`/`ensures`) in
    // the parameter scope before the body — a contract is the invariant
    // predicate attached to a function (ADR 0144). `result` in an `ensures` is
    // the return value, awaited for an `Effect`.
    if !f.requires.is_empty() || !f.ensures.is_empty() {
        let result_ty = match &*tys.get(return_ty) {
            Ty::Effect(inner) => *inner,
            _ => return_ty,
        };
        let has_result_param = f.params.iter().any(|p| p.name.name == "result");
        let fn_label = format!("function `{}`", f.name.display());
        check_contracts(
            &f.requires,
            &f.ensures,
            &param_scope,
            result_ty,
            has_result_param,
            &fn_label,
            input,
            expr_types,
            errors,
            refs,
            hints,
            locals,
            requirements,
            callees,
            &vars,
            tys,
        );
    }
    let effectful = return_ty.is_effect(tys);
    let mut ctx = Ctx {
        input,
        tys,
        expr_types,
        errors,
        refs,
        hints,
        locals,
        requirements,
        callees,
        scopes: vec![param_scope],
        is_binding_cache: HashMap::new(),
        pattern_binding_types: HashMap::new(),
        return_ty,
        return_ty_span: f.return_type.span(),
        effectful,
        agent_state_ty: None,
        commit_seen: false,
        caps: CapabilityCtx::default(),
        in_test_body: false,
        test_services: HashMap::new(),
        test_actors: HashMap::new(),
        type_vars: vars.clone(),
        store_fields: HashMap::new(),
    };
    let Some(body_ty) = type_of_block(&f.body, Some(return_ty), &mut ctx) else {
        return;
    };
    // #718: run the held-resource linearity pass over `fn`/method bodies too, not
    // just handlers. The caller side treats passing a held value into a function
    // as a transfer (disposal), so the callee *owns* any held parameter and must
    // dispose it (close, store, or transfer) before returning — otherwise a
    // `swallow(c)` leaks and a double `c.close()` goes undiagnosed. No parameter
    // is borrowed here (the borrowed case is a handler's firing connection), so
    // the borrowed set is empty; every held param is seeded owned.
    linearity::check(
        &f.body,
        &f.params,
        &input.types,
        ctx.expr_types,
        &ctx.pattern_binding_types,
        &HashSet::new(),
        ctx.errors,
        tys,
    );
    if !compatible(body_ty, return_ty, tys) {
        ctx.errors.push(
            CompileError::new(
                "bynk.types.return_mismatch",
                f.body.tail.span,
                format!(
                    "function body has type `{}`, but the declared return type is `{}`",
                    body_ty.display(tys),
                    return_ty.display(tys)
                ),
            )
            .with_label(f.return_type.span(), "declared return type"),
        );
    }
}

/// The shared discipline behind both `check_state_initialiser` (agent `store`
/// fields) and `check_event_field_default` (Events slice 3a, #972, event
/// record fields): the initialiser must be a *static* value of the field
/// type — checked in an empty, pure scope (so `self`, parameters,
/// capabilities, and effects are all out of reach) with the field type as
/// the expected type, so refined literals admit (v0.9.4) and sum variants
/// resolve. The init's expression types are recorded into `expr_types` for
/// emission, and its `Callee` classification (a `.of`/`.unsafe`/variant-
/// constructor call, at most) into `callees` (P6.7, #1163) — every
/// `Callee`-driven reader of a call-shaped expression reads `program.callees`
/// unconditionally (ADR 0334), so a call-shaped static initialiser with no
/// entry there would panic on a certified program the checker legitimately
/// accepted, not a recoverable state. (The IR-side `Cell`-init lowering that
/// first motivated this was deleted by Slice D1 of #1542; the invariant
/// outlives it because `bynk-emit`'s own emitter reads the same table.)
/// `code`/`subject`
/// name the caller's own diagnostic and the noun used in its message ("state
/// field initialiser" / "event field default").
#[allow(clippy::too_many_arguments)]
fn check_static_initialiser(
    init: &Expr,
    field_type: &TypeRef,
    input: &ResolvedCommons,
    expr_types: &mut HashMap<ExprId, TypedExpr>,
    callees: &mut HashMap<ExprId, Callee>,
    errors: &mut Vec<CompileError>,
    refs: &mut RefSink,
    hints: &mut HintSink,
    locals: &mut LocalsSink,
    code: &'static str,
    subject: &str,
    tys: &Types,
) {
    let Some(field_ty) = resolve_type_ref(field_type, &input.types, tys) else {
        return; // an unresolved field type is reported elsewhere
    };
    let mut local_errors: Vec<CompileError> = Vec::new();
    // A static initialiser is a pure value — no capability calls reach here —
    // so requirements are discarded into a throwaway sink.
    let mut init_requirements = RequirementSink::new();
    let result = {
        let mut ctx = Ctx {
            input,
            tys,
            expr_types,
            errors: &mut local_errors,
            refs,
            hints,
            locals,
            requirements: &mut init_requirements,
            callees,
            scopes: vec![HashMap::new()],
            is_binding_cache: HashMap::new(),
            pattern_binding_types: HashMap::new(),
            return_ty: field_ty,
            return_ty_span: init.span,
            effectful: false,
            agent_state_ty: None,
            commit_seen: false,
            caps: CapabilityCtx::default(),
            in_test_body: false,
            test_services: HashMap::new(),
            test_actors: HashMap::new(),
            type_vars: HashSet::new(),
            store_fields: HashMap::new(),
        };
        type_of(init, Some(field_ty), &mut ctx)
    };
    let compatible_result = matches!(&result, Some(t) if compatible(*t, field_ty, tys));
    if !compatible_result || !local_errors.is_empty() {
        let got = result
            .map(|t| t.display(tys))
            .unwrap_or_else(|| "an invalid expression".to_string());
        errors.push(
            CompileError::new(
                code,
                init.span,
                format!(
                    "{subject} must be a static value of type `{}` (got `{got}`)",
                    field_ty.display(tys),
                ),
            )
            .with_note(
                "an initialiser is a compile-time value — a literal (including one admitted to a \
                 refined type), a sum variant, `Some`/`None`/`Ok`/`Err`, a record, or — for an \
                 opaque type — `T.unsafe(lit)` — with no reference to `self`, parameters, or \
                 capabilities",
            ),
        );
    }
}

/// v0.11: type-check an agent state-field initialiser (`field: T = init`).
/// See `check_static_initialiser`. Pushes `bynk.agents.bad_state_initialiser`.
#[allow(clippy::too_many_arguments)]
pub fn check_state_initialiser(
    init: &Expr,
    field_type: &TypeRef,
    input: &ResolvedCommons,
    tys: &Types,
    expr_types: &mut HashMap<ExprId, TypedExpr>,
    callees: &mut HashMap<ExprId, Callee>,
    errors: &mut Vec<CompileError>,
    refs: &mut RefSink,
    hints: &mut HintSink,
    locals: &mut LocalsSink,
) {
    check_static_initialiser(
        init,
        field_type,
        input,
        expr_types,
        callees,
        errors,
        refs,
        hints,
        locals,
        "bynk.agents.bad_state_initialiser",
        "state field initialiser",
        tys,
    );
}

/// Events slice 3a (#972): type-check an event field's default expression
/// (`field: T = init`), reusing `check_static_initialiser`'s empty-pure-scope
/// discipline. Pushes `bynk.event.bad_field_default`.
///
/// One admission `check_static_initialiser` doesn't cover on its own: an
/// opaque type's `T.unsafe(lit)` is, by design (ADR 0182), a bypass of its
/// own refinement — `type_of`'s ordinary `ConstructorCall` handling only
/// checks `lit`'s *base* type, not the refinement, since that's the whole
/// point of `unsafe`. An event field default is different: it becomes part
/// of the wire codec (slice 3a lowers it to its *wire* JSON form and splices
/// it into `deserialise_<Event>`, which validates a defaulted value exactly
/// like a real one), so a default that bypasses its own refinement would
/// compile cleanly and then fail at runtime the first time an old event
/// actually triggers it — a deferred, surprising failure this check closes
/// statically instead. Only `T.unsafe(lit)` on a *literal* argument is
/// checked here (anything else already fails the static-value requirement
/// above); a violated refinement pushes the same `bynk.event.bad_field_default`.
#[allow(clippy::too_many_arguments)]
pub fn check_event_field_default(
    init: &Expr,
    field_type: &TypeRef,
    input: &ResolvedCommons,
    tys: &Types,
    expr_types: &mut HashMap<ExprId, TypedExpr>,
    callees: &mut HashMap<ExprId, Callee>,
    errors: &mut Vec<CompileError>,
    refs: &mut RefSink,
    hints: &mut HintSink,
    locals: &mut LocalsSink,
) {
    check_static_initialiser(
        init,
        field_type,
        input,
        expr_types,
        callees,
        errors,
        refs,
        hints,
        locals,
        "bynk.event.bad_field_default",
        "event field default",
        tys,
    );
    // `T.unsafe(lit)` parses as `ExprKind::MethodCall { receiver: Ident(T),
    // method: "unsafe", .. }` — confirmed by direct AST inspection; the
    // parser never distinguishes a type-qualified call from an ordinary
    // instance method call (that's a resolver-time decision), so
    // `ExprKind::ConstructorCall` is not what this actually produces.
    if let ExprKind::MethodCall {
        receiver,
        method,
        args,
        ..
    } = &init.kind
        && let ExprKind::Ident(type_name) = &receiver.kind
        && method.name == "unsafe"
        && let [lit_expr] = args.as_slice()
        && let Some(decl) = input.types.get(&type_name.name)
        && matches!(decl.body, TypeBody::Opaque { .. })
        && let Some(refinement) = refinements::type_decl_refinement(decl)
        && let Some(lit) = refinements::const_literal(lit_expr)
        && let Some(failed) = refinements::first_failed_predicate(refinement, &lit)
    {
        errors.push(
            CompileError::new(
                "bynk.event.bad_field_default",
                lit_expr.span,
                format!(
                    "`{}.unsafe(...)` bypasses its own refinement, but an event field default \
                     must be a value the wire could actually carry — this literal fails `{}`",
                    type_name.name,
                    failed.name(),
                ),
            )
            .with_note(
                "a default is spliced into the same codec that validates a real wire value on \
                 receipt, so a refinement-violating `.unsafe(lit)` default would compile cleanly \
                 and then fail at runtime the first time an old event actually triggers it",
            ),
        );
    }
}

/// v0.91 (ADR 0116 D6): the `bynk.list` free functions whose method forms
/// shipped with slice 1 are **deprecated** in favour of the method-chain
/// vocabulary. `reverse`/`traverse` stay (no method form yet). Emits a
/// non-failing warning (ADR 0117) with a machine-applicable rewrite to the
/// method form — `map(xs, f)` → `xs.map(f)`, `find(xs, p)` → `xs.filter(p).first()`.
fn warn_bynk_list_deprecation(name: &Ident, args: &[Expr], call_span: Span, ctx: &mut Ctx) {
    if ctx.input.imported_from.get(&name.name).map(String::as_str) != Some("bynk.list") {
        return;
    }
    // The method-form spelling each free function rewrites to.
    let method_form: &str = match name.name.as_str() {
        "map" => "xs.map(f)",
        "filter" => "xs.filter(p)",
        "any" => "xs.any(p)",
        "all" => "xs.all(p)",
        "find" => "xs.filter(p).first()",
        _ => return, // reverse / traverse keep their free-function form for now
    };
    let mut err = CompileError::new(
        "bynk.list.deprecated_function",
        name.span,
        format!(
            "`bynk.list.{}` is deprecated — use the `List` method form `{method_form}`",
            name.name
        ),
    )
    .with_note(
        "the `bynk.list.*` free functions are superseded by the method-chain vocabulary (ADR 0116); the method form reads left-to-right and chains",
    );
    // The auto-fix needs the (list, fn) shape — a wrong-arity call is reported
    // elsewhere; only offer the rewrite when it is well-formed.
    if args.len() == 2 {
        let mut edits = vec![
            // delete `name(` — the receiver becomes the first argument.
            (
                Span::new(name.span.start, args[0].span.start),
                String::new(),
            ),
            // the `, ` between the two args becomes `.<method>(`.
            (
                Span::new(args[0].span.end, args[1].span.start),
                format!(
                    ".{}(",
                    if name.name == "find" {
                        "filter"
                    } else {
                        &name.name
                    }
                ),
            ),
        ];
        if name.name == "find" {
            // `filter(p)` then `.first()` after the closing `)`.
            edits.push((
                Span::new(call_span.end, call_span.end),
                ".first()".to_string(),
            ));
        }
        err = err.with_suggestion(
            format!("rewrite to the `List` method form `{method_form}`"),
            edits,
            Applicability::MachineApplicable,
        );
    }
    ctx.errors.push(err);
}

pub(crate) fn check_call(
    name: &Ident,
    type_args: &[TypeRef],
    args: &[Expr],
    span: Span,
    // #593: the binding's expected type grounds a generic variant constructor
    // whose payload cannot determine every parameter (`let o: Opt[Int] = Nil`).
    expected: Option<TyId>,
    // P6.0 (#1139): the outer `Call` expression's own identity — keys the
    // `Callee` classification recorded at whichever branch below dispatches.
    expr_id: ExprId,
    ctx: &mut Ctx,
) -> Option<TyId> {
    let tys = ctx.tys;
    if let Some(fn_decl) = ctx.input.fns.get(&name.name) {
        ctx.refs.record(name.span, SymbolKind::Fn, &name.name);
        ctx.callees.insert(expr_id, Callee::Fn(Arc::clone(fn_decl)));
        warn_bynk_list_deprecation(name, args, span, ctx);
        return check_call_against_fn(name, fn_decl, type_args, args, ctx);
    }
    // v0.20a: explicit type arguments only apply to (generic) functions.
    if !type_args.is_empty() {
        ctx.errors.push(CompileError::new(
            "bynk.generics.type_arg_mismatch",
            span,
            format!(
                "`{}` is not a generic function — it takes no type arguments",
                name.name
            ),
        ));
        for a in args {
            let _ = type_of(a, None, ctx);
        }
        return None;
    }
    // Could be a bare variant constructor with payload. Borrow the matching
    // sum decls' own `Arc`s (a pointer bump each, no full-body clones); the
    // ambiguity check below reuses the same list.
    let owners: Vec<&Arc<TypeDecl>> = ctx
        .input
        .types
        .values()
        .filter(|t| matches!(&t.body, TypeBody::Sum(s) if s.variants.iter().any(|v| v.name.name == name.name)))
        .collect();
    if owners.len() == 1 {
        ctx.callees.insert(
            expr_id,
            Callee::Ctor {
                sum: Arc::clone(owners[0]),
                tag: name.name.clone(),
            },
        );
        return check_variant_construction(owners[0], &name.name, args, span, expected, ctx);
    }
    // Agent instantiation: `AgentName(key)` constructs an instance keyed by
    // `key`. The result type carries the agent's name so subsequent
    // `agent_instance.method(args)` lookups can find the agent's handler set.
    if let Some(agent) = ctx.input.agents.get(&name.name).cloned() {
        ctx.refs.record(name.span, SymbolKind::Agent, &name.name);
        ctx.callees
            .insert(expr_id, Callee::AgentInit(name.name.clone()));
        let key_ty = resolve_type_ref(&agent.key_type, &ctx.input.types, tys);
        if args.len() != 1 {
            ctx.errors.push(CompileError::new(
                "bynk.agent.construction_arity",
                span,
                format!(
                    "agent `{}` is constructed with one key argument, but {} were given",
                    name.name,
                    args.len()
                ),
            ));
            for a in args {
                let _ = type_of(a, None, ctx);
            }
            return None;
        }
        let arg_ty = type_of(&args[0], key_ty, ctx);
        if let (Some(a), Some(k)) = (arg_ty, key_ty)
            && !compatible(a, k, tys)
        {
            ctx.errors.push(CompileError::new(
                "bynk.agent.key_mismatch",
                args[0].span,
                format!(
                    "agent `{}` key is `{}`, but a value of type `{}` was given",
                    name.name,
                    k.display(tys),
                    a.display(tys)
                ),
            ));
        }
        return Some(tys.intern(Ty::Named {
            name: name.name.clone(),
            kind: NamedKind::Record,
            args: Vec::new(),
        }));
    }
    // v0.20a: value application — calling a scope binding (param/local) of
    // function type. Placed AFTER fns/variants/agents: putting scope first
    // would change the meaning of currently-passing programs (the additive
    // guard); the resulting ident/call precedence asymmetry is pre-existing
    // and documented in §5.
    if let Some(ty) = ctx.lookup(&name.name) {
        return match &*tys.get(ty) {
            Ty::Fn { params, ret } => {
                ctx.callees
                    .insert(expr_id, Callee::Value(name.name.clone()));
                check_value_application(name, params, *ret, args, span, ctx)
            }
            _ => {
                // Relocated from the resolver (which has no type info): a
                // non-function-typed value called as a function.
                ctx.errors.push(
                    CompileError::new(
                        "bynk.resolve.param_as_function",
                        span,
                        format!(
                            "`{}` has type `{}` and is not callable",
                            name.name,
                            ty.display(tys)
                        ),
                    )
                    .with_note("only values of function type can be applied"),
                );
                for a in args {
                    let _ = type_of(a, None, ctx);
                }
                None
            }
        };
    }
    // Nothing owns the call. The resolver's reference walk reports these in
    // `fn`/method bodies, but handler/service/agent bodies and test bodies
    // never pass through that walk — the checker is their only backstop, and
    // a silent `None` here admitted any unknown call and emitted it verbatim.
    // Mirror the resolver's ladder. #1708: test bodies were exempt, for the
    // same since-repaired reason as `check_ident`'s twin gate; dropped with it.
    for a in args {
        let _ = type_of(a, None, ctx);
    }
    if owners.len() > 1 {
        ctx.errors.push(CompileError::new(
            "bynk.resolve.ambiguous_variant",
            name.span,
            format!(
                "the variant name `{}` is declared on multiple sum types — qualify it as `TypeName.{}(...)`",
                name.name, name.name
            ),
        ));
        return None;
    }
    if ctx.input.types.contains_key(&name.name) {
        ctx.errors.push(CompileError::new(
            "bynk.resolve.type_as_function",
            span,
            format!(
                "`{}` is a type, not a function — use `{}.of(value)` or `{} {{ ... }}` instead",
                name.name, name.name, name.name
            ),
        ));
        return None;
    }
    ctx.errors.push(
        CompileError::new(
            "bynk.resolve.unknown_function",
            span,
            format!("unknown function `{}`", name.name),
        )
        .with_note("only functions declared in this commons are callable"),
    );
    None
}

fn check_value_application(
    name: &Ident,
    params: &[TyId],
    ret: TyId,
    args: &[Expr],
    span: Span,
    ctx: &mut Ctx,
) -> Option<TyId> {
    let tys = ctx.tys;
    if ret.is_effect(tys) && !ctx.effectful {
        ctx.errors.push(
            CompileError::new(
                "bynk.effect.fn_value_in_pure_context",
                span,
                format!(
                    "`{}` is an effectful function (`{}`) and cannot be called in a pure context",
                    name.name,
                    Ty::Fn {
                        params: params.to_vec(),
                        ret,
                    }
                    .display(tys)
                ),
            )
            .with_note(
                "effectful function values may only be called where the enclosing body is effectful (its return type is an Effect)",
            ),
        );
    }
    if params.len() != args.len() {
        ctx.errors.push(CompileError::new(
            "bynk.types.call_arity",
            span,
            format!(
                "`{}` takes {} argument(s), but {} were given",
                name.name,
                params.len(),
                args.len()
            ),
        ));
        for a in args {
            let _ = type_of(a, None, ctx);
        }
        return None;
    }
    for (arg, param_ty) in args.iter().zip(params) {
        let arg_ty = type_of(arg, Some(*param_ty), ctx);
        if let Some(a) = arg_ty
            && !compatible(a, *param_ty, tys)
        {
            ctx.errors.push(CompileError::new(
                "bynk.types.argument_mismatch",
                arg.span,
                format!(
                    "argument has type `{}`, but `{}` expects `{}`",
                    a.display(tys),
                    name.name,
                    param_ty.display(tys)
                ),
            ));
        }
    }
    Some(ret)
}

/// v0.20a: instantiate and check a call to a generic function. Two-pass
/// argument-directed inference: pass 1 types every **non-lambda** argument
/// left-to-right against the (possibly still Var-bearing) expected — safe
/// because every expected-driven feature in `type_of` matches concrete
/// variants, so a Var falls through benignly (pinned by a unit test) — and
/// unifies; pass 2 types **lambda** arguments against the now-substituted
/// expecteds (a lambda whose expected params are still Var-bearing is
/// uninferable) and unifies the result, capturing return-position variables.
/// Conflicts demand exact equality (`bynk.generics.type_arg_mismatch`); the
/// explicit `name[T](…)` form builds the substitution directly.
fn check_generic_call(
    name: &Ident,
    fn_decl: &FnDecl,
    type_args: &[TypeRef],
    args: &[Expr],
    ctx: &mut Ctx,
) -> Option<TyId> {
    let tys = ctx.tys;
    let vars: HashSet<String> = fn_decl
        .type_params
        .iter()
        .map(|tp| tp.name.name.clone())
        .collect();
    if fn_decl.params.len() != args.len() {
        // Same backstop as the non-generic path: the resolver only covers
        // `fn`/method bodies, so the checker must report for handler bodies.
        ctx.errors.push(
            CompileError::new(
                "bynk.resolve.arity_mismatch",
                name.span,
                format!(
                    "function `{}` expects {} argument(s), but {} were given",
                    name.name,
                    fn_decl.params.len(),
                    args.len()
                ),
            )
            .with_label(fn_decl.name.ident().span, "function declared here"),
        );
        for a in args {
            let _ = type_of(a, None, ctx);
        }
        return None;
    }
    let var_params: Vec<Option<TyId>> = fn_decl
        .params
        .iter()
        .map(|p| resolve_type_ref_in(&p.type_ref, &ctx.input.types, &vars, tys))
        .collect();
    let ret_pattern = resolve_type_ref_in(&fn_decl.return_type, &ctx.input.types, &vars, tys)?;

    let mut subst: HashMap<String, TyId> = HashMap::new();
    if !type_args.is_empty() {
        if type_args.len() != fn_decl.type_params.len() {
            ctx.errors.push(CompileError::new(
                "bynk.generics.type_arg_mismatch",
                name.span,
                format!(
                    "`{}` takes {} type argument(s), but {} were given",
                    name.name,
                    fn_decl.type_params.len(),
                    type_args.len()
                ),
            ));
            return None;
        }
        for (tp, ta) in fn_decl.type_params.iter().zip(type_args) {
            // Resolve explicit type args with the *enclosing* fn's type
            // params in scope, so `identity[A](x)` inside a generic body
            // works. #712: report (not silently drop) an unknown type arg —
            // the resolver never validates `Call::type_args` (it destructures
            // `Call { name, args, .. }`), so this is the only guard.
            let ty = resolve_expr_type_ref(ta, ctx)?;
            subst.insert(tp.name.name.clone(), ty);
        }
    }

    let mut arg_tys: Vec<Option<TyId>> = vec![None; args.len()];
    // Pass 1 — non-lambda arguments.
    for (i, arg) in args.iter().enumerate() {
        if matches!(arg.kind, ExprKind::Lambda(_)) {
            continue;
        }
        let expected = var_params[i].map(|p| substitute(p, &subst, tys));
        let ty = type_of(arg, expected, ctx);
        if let (Some(pattern), Some(actual)) = (var_params[i], ty)
            && !unify(pattern, actual, &mut subst, tys)
        {
            ctx.errors.push(CompileError::new(
                "bynk.generics.type_arg_mismatch",
                arg.span,
                format!(
                    "argument {} infers a type for `{}`'s type parameter that conflicts with an earlier argument — annotate with `{}[T](…)`",
                    i + 1,
                    name.name,
                    name.name
                ),
            ));
            return None;
        }
        arg_tys[i] = ty;
    }
    // Pass 2 — lambda arguments, against substituted expecteds.
    for (i, arg) in args.iter().enumerate() {
        if !matches!(arg.kind, ExprKind::Lambda(_)) {
            continue;
        }
        let expected = var_params[i].map(|p| substitute(p, &subst, tys));
        let params_unconstrained = expected.is_some_and(|e| {
            matches!(&*tys.get(e), Ty::Fn { params, .. }
                if params.iter().any(|p| contains_var(*p, tys)))
        });
        let fully_annotated = matches!(
            &arg.kind,
            ExprKind::Lambda(l) if l.params.iter().all(|p| p.type_ref.is_some())
        );
        if params_unconstrained && !fully_annotated {
            ctx.errors.push(
                CompileError::new(
                    "bynk.generics.uninferable_type_arg",
                    arg.span,
                    format!(
                        "the lambda's parameter types depend on `{}`'s type parameters, which the other arguments do not determine",
                        name.name
                    ),
                )
                .with_note("annotate the lambda's parameters, or give explicit type arguments: `name[T](…)`"),
            );
            return None;
        }
        // A fully-annotated lambda grounds the variables itself: type it
        // bottom-up and let unify capture them.
        let ty = if params_unconstrained {
            type_of(arg, None, ctx)
        } else {
            type_of(arg, expected, ctx)
        };
        if let (Some(pattern), Some(actual)) = (var_params[i], ty)
            && !unify(pattern, actual, &mut subst, tys)
        {
            ctx.errors.push(CompileError::new(
                "bynk.generics.type_arg_mismatch",
                arg.span,
                format!(
                    "the lambda's type conflicts with `{}`'s inferred type arguments",
                    name.name
                ),
            ));
            return None;
        }
        arg_tys[i] = ty;
    }
    // Every type parameter must now be determined.
    for tp in &fn_decl.type_params {
        if !subst.contains_key(&tp.name.name) {
            ctx.errors.push(
                CompileError::new(
                    "bynk.generics.uninferable_type_arg",
                    name.span,
                    format!(
                        "type parameter `{}` of `{}` is neither inferable from the arguments nor given explicitly",
                        tp.name.name, name.name
                    ),
                )
                .with_label(tp.span, "declared here")
                .with_note("give explicit type arguments: `name[T](…)`"),
            );
            return None;
        }
    }
    // Final compatibility over the fully-ground parameter types.
    let mut ok = true;
    for (i, (pattern, arg)) in var_params.iter().zip(args).enumerate() {
        record_param_hint(ctx.hints, &fn_decl.params[i].name.name, arg);
        let (Some(pattern), Some(arg_ty)) = (pattern, arg_tys[i].as_ref()) else {
            continue;
        };
        let ground = substitute(*pattern, &subst, tys);
        if !compatible(*arg_ty, ground, tys) {
            ctx.errors.push(CompileError::new(
                "bynk.types.argument_mismatch",
                arg.span,
                format!(
                    "argument {} to `{}` has type `{}`, but `{}` is expected",
                    i + 1,
                    name.name,
                    arg_ty.display(tys),
                    ground.display(tys)
                ),
            ));
            ok = false;
        }
    }
    if !ok {
        return None;
    }
    // #1688: a type parameter the callee compares (`==` on it, directly or
    // through another generic call) must be instantiated with an
    // equality-supporting type.
    let compared = match ctx.input.fns.get(&name.name) {
        Some(decl) if std::ptr::eq(decl.as_ref(), fn_decl) => {
            super::equality::compared_type_params(decl, ctx)
        }
        _ => Default::default(),
    };
    let params: Vec<(String, Option<Span>)> = fn_decl
        .type_params
        .iter()
        .map(|tp| (tp.name.name.clone(), Some(tp.span)))
        .collect();
    if !super::equality::check_compared_args(&name.name, name.span, &params, &compared, &subst, ctx)
    {
        return None;
    }
    // v0.39 (ADR 0072): when the user omitted the type arguments, show the
    // inferred ones as a `Type`-kind hint after the function name —
    // `identity` ⟨`[Int]`⟩ `(5)`. Declaration order; skipped if any var stayed
    // unresolved (defensive — the arg loop above already grounds them).
    if type_args.is_empty() && !fn_decl.type_params.is_empty() {
        let rendered: Option<Vec<String>> = fn_decl
            .type_params
            .iter()
            .map(|tp| subst.get(&tp.name.name).map(|t| t.display(tys)))
            .collect();
        if let Some(parts) = rendered {
            ctx.hints
                .record(name.span, format!("[{}]", parts.join(", ")));
        }
    }
    let ret = substitute(ret_pattern, &subst, tys);
    // v0.20b: the return is ground *up to the caller's rigid type
    // parameters* — a generic fn calling another generic fn (bynk.list's
    // `map` calling `reverse`) legitimately instantiates the callee at its
    // own rigid vars, which flow through `compatible` by name-equality.
    Some(ret)
}

fn check_call_against_fn(
    name: &Ident,
    fn_decl: &FnDecl,
    type_args: &[TypeRef],
    args: &[Expr],
    ctx: &mut Ctx,
) -> Option<TyId> {
    let tys = ctx.tys;
    // v0.20a: generic functions take the instantiation path; the
    // non-generic path below runs byte-identically to v0.19 (the additive
    // guard). Explicit type args on a non-generic fn are rejected.
    if !fn_decl.type_params.is_empty() {
        return check_generic_call(name, fn_decl, type_args, args, ctx);
    }
    if !type_args.is_empty() {
        ctx.errors.push(CompileError::new(
            "bynk.generics.type_arg_mismatch",
            name.span,
            format!(
                "`{}` is not a generic function — it takes no type arguments",
                name.name
            ),
        ));
        for a in args {
            let _ = type_of(a, None, ctx);
        }
        return None;
    }
    if fn_decl.params.len() != args.len() {
        // The resolver reports this in `fn`/method bodies; handler/service/
        // agent/test bodies only reach the checker, so report here too (a
        // resolve error stops the pipeline first, so this cannot double up).
        ctx.errors.push(
            CompileError::new(
                "bynk.resolve.arity_mismatch",
                name.span,
                format!(
                    "function `{}` expects {} argument(s), but {} were given",
                    name.name,
                    fn_decl.params.len(),
                    args.len()
                ),
            )
            .with_label(fn_decl.name.ident().span, "function declared here"),
        );
        for a in args {
            let _ = type_of(a, None, ctx);
        }
        return None;
    }
    let resolved_params: Vec<(Option<TyId>, &Param)> = fn_decl
        .params
        .iter()
        .map(|p| (resolve_type_ref(&p.type_ref, &ctx.input.types, tys), p))
        .collect();
    let mut ok = true;
    for (i, ((param_ty, param), arg)) in resolved_params.iter().zip(args.iter()).enumerate() {
        record_param_hint(ctx.hints, &param.name.name, arg);
        let arg_ty = type_of(arg, *param_ty, ctx);
        let (Some(arg_ty), Some(param_ty)) = (arg_ty, *param_ty) else {
            ok = false;
            continue;
        };
        if !compatible(arg_ty, param_ty, tys) {
            ctx.errors.push(
                CompileError::new(
                    "bynk.types.argument_mismatch",
                    arg.span,
                    format!(
                        "argument {} to `{}` has type `{}`, but parameter `{}` expects `{}`",
                        i + 1,
                        name.name,
                        arg_ty.display(tys),
                        param.name.name,
                        param_ty.display(tys)
                    ),
                )
                .with_label(param.span, "parameter declared here"),
            );
            ok = false;
        }
    }
    if !ok {
        return None;
    }
    resolve_type_ref(&fn_decl.return_type, &ctx.input.types, tys)
}

/// Type-check a kernel-method argument against its expected type, with the
/// expected type propagated in (so lambdas and literals type contextually).
pub(crate) fn check_arg(arg: &Expr, expected: TyId, what: &str, ctx: &mut Ctx) {
    let tys = ctx.tys;
    let Some(actual) = type_of(arg, Some(expected), ctx) else {
        return;
    };
    if !compatible(actual, expected, tys) {
        ctx.errors.push(CompileError::new(
            "bynk.types.type_mismatch",
            arg.span,
            format!(
                "{what} has type `{}`, but `{}` is required",
                actual.display(tys),
                expected.display(tys)
            ),
        ));
    }
}

/// Record a capability reference's binding edge, qualifying flattened bare
/// names (`consumes U { Cap }`) to their providing unit (v0.25). A bare
/// non-flattened name is the consuming unit's own declaration — qualified
/// at assembly.
fn record_capability_ref(span: Span, name: &str, ctx: &mut Ctx) {
    if let Some(unit) = ctx.input.cross_context.flattened_caps.get(name) {
        ctx.refs
            .record_in_unit(span, SymbolKind::Capability, name, unit);
    } else {
        ctx.refs.record(span, SymbolKind::Capability, name);
    }
}

#[allow(clippy::too_many_arguments)]
pub(crate) fn check_static_call(
    type_name: &Ident,
    method: &Ident,
    // #926: explicit type arguments for a generic capability operation
    // (`Cap.op[T](…)`). Consumed only by the capability-dispatch branch below
    // — the user-declared-static branch never receives a non-empty slice,
    // since `check_method_call`'s gate only lets type args through for a
    // capability (or the `Json` codec, handled separately) receiver.
    type_args: &[TypeRef],
    args: &[Expr],
    span: Span,
    // #593: threaded to `check_variant_construction` so a qualified generic
    // variant (`Opt.Nil`) can ground its arguments from the binding's type.
    expected: Option<TyId>,
    // P6.0 (#1139): the outer expression's identity — the `ConstructorCall`/
    // `MethodCall` node this dispatch is checking on behalf of (this
    // function is also reached from inside `check_method_call`, not only
    // from `type_of` directly).
    expr_id: ExprId,
    ctx: &mut Ctx,
) -> Option<TyId> {
    let tys = ctx.tys;
    // Capability dispatch (v0.5): if `type_name` names a capability declared
    // in the context, dispatch via the capability table. If the capability is
    // declared but not in `given`, error specifically.
    if ctx.caps.declared_capabilities.contains_key(&type_name.name)
        && !ctx.caps.capabilities.contains_key(&type_name.name)
    {
        record_capability_ref(type_name.span, &type_name.name, ctx);
        ctx.callees.insert(
            expr_id,
            Callee::Capability {
                cap: type_name.name.clone(),
                op: method.name.clone(),
            },
        );
        let mut err = CompileError::new(
            "bynk.given.undeclared_capability",
            type_name.span,
            format!(
                "capability `{}` is used but not listed in the handler's `given` clause",
                type_name.name
            ),
        )
        .with_note(format!(
            "add `{}` to the handler's `given` clause so the dependency surface is visible at the declaration site",
            type_name.name
        ));
        // v0.26 (ADR 0054): the one-click counterpart of the note.
        if let Some((span, insert)) = given_insertion_edit(
            &ctx.caps.given_entries,
            ctx.caps.given_anchor,
            &type_name.name,
        ) {
            err = err.with_suggestion(
                format!("add `{}` to the `given` clause", type_name.name),
                vec![(span, insert)],
                Applicability::MachineApplicable,
            );
        }
        ctx.errors.push(err);
        // v0.99: an uncovered direct capability call — record it so the ghost
        // `given` inlay hint can offer the same clause at the declaration site
        // (DECISION D/E). `span` is the call site (the inner `given_insertion_edit`
        // binding shadowed it only within the `if let` above).
        record_requirement(
            ctx,
            &type_name.name,
            span,
            RequirementSource::DirectCall {
                op: method.name.clone(),
            },
            false,
        );
        for a in args {
            let _ = type_of(a, None, ctx);
        }
        return None;
    }
    if let Some(cap) = ctx.caps.capabilities.get(&type_name.name).cloned() {
        record_capability_ref(type_name.span, &type_name.name, ctx);
        ctx.callees.insert(
            expr_id,
            Callee::Capability {
                cap: type_name.name.clone(),
                op: method.name.clone(),
            },
        );
        if !ctx.effectful {
            ctx.errors.push(
                CompileError::new(
                    "bynk.effect.capability_in_pure_context",
                    span,
                    format!(
                        "capability `{}` can only be called inside an effectful body (one returning `Effect[T]`)",
                        type_name.name
                    ),
                ),
            );
        }
        ctx.caps.given_used.insert(type_name.name.clone());
        // v0.99: a covered direct capability call — the call site *is* the
        // reason (DECISION C). Recorded so hover can explain what a declared
        // `given Cap` is for; no inlay hint (already covered).
        record_requirement(
            ctx,
            &type_name.name,
            span,
            RequirementSource::DirectCall {
                op: method.name.clone(),
            },
            true,
        );
        let Some(op) = cap.ops.iter().find(|o| o.name == method.name) else {
            ctx.errors.push(CompileError::new(
                "bynk.capability.unknown_operation",
                method.span,
                format!(
                    "capability `{}` has no operation named `{}`",
                    type_name.name, method.name
                ),
            ));
            for a in args {
                let _ = type_of(a, None, ctx);
            }
            return None;
        };
        // v0.36 (ADR 0069, slice 2): the op is an index symbol keyed by the
        // compound `"Cap.op"` name; this local call is a reference.
        ctx.refs.record(
            method.span,
            SymbolKind::CapabilityOp,
            &format!("{}.{}", type_name.name, method.name),
        );
        if op.params.len() != args.len() {
            ctx.errors.push(CompileError::new(
                "bynk.capability.op_arity",
                span,
                format!(
                    "capability operation `{}.{}` expects {} argument(s), but {} were given",
                    type_name.name,
                    method.name,
                    op.params.len(),
                    args.len()
                ),
            ));
            for a in args {
                let _ = type_of(a, None, ctx);
            }
            return None;
        }
        let op_clone = op.clone();
        // #926: resolve the op's own type parameter(s) from an explicit
        // call-site type argument — explicit only, never inferred (mirrors
        // `Json.decode[T]`, not `#594`'s inference). `check_generic_call`
        // (this file) is the model; only its arity-check + substitution-build
        // half applies here, since a capability op has no argument-driven
        // inference pass.
        let mut subst: HashMap<String, TyId> = HashMap::new();
        if !op_clone.type_params.is_empty() || !type_args.is_empty() {
            if type_args.is_empty() {
                ctx.errors.push(
                    CompileError::new(
                        "bynk.generics.uninferable_type_arg",
                        span,
                        format!(
                            "capability operation `{}.{}` takes a type parameter, but none of its arguments determine it",
                            type_name.name, method.name
                        ),
                    )
                    .with_note(format!(
                        "give it explicitly: `{}.{}[T](…)`",
                        type_name.name, method.name
                    )),
                );
                for a in args {
                    let _ = type_of(a, None, ctx);
                }
                return None;
            }
            if type_args.len() != op_clone.type_params.len() {
                ctx.errors.push(CompileError::new(
                    "bynk.generics.type_arg_mismatch",
                    span,
                    format!(
                        "capability operation `{}.{}` takes {} type argument(s), but {} were given",
                        type_name.name,
                        method.name,
                        op_clone.type_params.len(),
                        type_args.len()
                    ),
                ));
                for a in args {
                    let _ = type_of(a, None, ctx);
                }
                return None;
            }
            for (tp, ta) in op_clone.type_params.iter().zip(type_args) {
                let ty = resolve_expr_type_ref(ta, ctx)?;
                // Events track, slice 0 (spine #936): owner-only emission —
                // `Events.emit[E]` may only name an event `E` declared in
                // *this* context, even though a `consumes`-visible foreign
                // event resolves here just as validly for every other
                // purpose. `is_local_type` already distinguishes "declared
                // here" from "visible via uses/consumes" (the same table
                // ADR 0256's locale-types-split gap analysis used), so this
                // is a check over existing data, not new provenance
                // plumbing — the primary boundary guarantee the threat
                // model (events.md §6) names.
                //
                // First-party-gated like every other Events-special-cased
                // site (mirrors #934's Idempotency precedent): a bare
                // `type_name.name == "Events"` string match would also fire
                // for a third-party capability that happens to declare its
                // own `Events` with an `emit` method — only bynk's own
                // capability (declared here, in `bynk` itself, or flattened
                // in via `consumes bynk { Events }`) gets this check.
                let is_first_party_events = type_name.name == "Events"
                    && method.name == "emit"
                    && (ctx.input.commons.name.joined() == crate::firstparty::BYNK_UNIT
                        || ctx
                            .input
                            .cross_context
                            .flattened_caps
                            .get("Events")
                            .map(String::as_str)
                            == Some(crate::firstparty::BYNK_UNIT));
                if is_first_party_events && let Ty::Named { name: ename, .. } = &*tys.get(ty) {
                    if ctx.input.is_local_event(ename) {
                        // Locally-declared event — the owner. Fine.
                    } else if ctx.input.is_local_type(ename) {
                        // Events track, slice 0: `UnitTable`/`ResolvedCommons`
                        // record which local names are specifically events
                        // (as opposed to any other locally-declared type) —
                        // `Events.emit[SomeLocalRecord]` compiled clean before
                        // this check existed, silently buffering an emission
                        // no `from Events(...)` subscriber could ever match
                        // (`discover_event_subscribers` finds no owner for a
                        // non-event name and just drops it).
                        ctx.errors.push(
                            CompileError::new(
                                "bynk.event.emit_not_an_event",
                                ta.span(),
                                format!(
                                    "`{ename}` is not a declared `event` — `Events.emit` may only name an event type"
                                ),
                            )
                            .with_note(
                                "declare it with `event Name = { ... }`, or check that the type argument names the event you meant",
                            ),
                        );
                    } else {
                        ctx.errors.push(
                            CompileError::new(
                                "bynk.event.emit_outside_owner",
                                ta.span(),
                                format!(
                                    "`{ename}` is not declared in this context — only the context that declares an event may emit it"
                                ),
                            )
                            .with_note(
                                "a foreign event is visible via `consumes` for subscription (`from Events(...)`), but only its owning context may `Events.emit` it",
                            ),
                        );
                    }
                }
                subst.insert(tp.clone(), ty);
            }
        }
        for (i, (param_ty, arg)) in op_clone.params.iter().zip(args.iter()).enumerate() {
            let param_ty = substitute(*param_ty, &subst, tys);
            let arg_ty = type_of(arg, Some(param_ty), ctx);
            if let Some(actual) = arg_ty
                && !compatible(actual, param_ty, tys)
            {
                ctx.errors.push(CompileError::new(
                    "bynk.types.argument_mismatch",
                    arg.span,
                    format!(
                        "argument {} to capability `{}.{}` has type `{}`, but parameter expects `{}`",
                        i + 1,
                        type_name.name,
                        method.name,
                        actual.display(tys),
                        param_ty.display(tys)
                    ),
                ));
            }
        }
        return Some(substitute(op_clone.return_ty, &subst, tys));
    }
    let decl = ctx.input.types.get(&type_name.name)?;
    ctx.refs
        .record(type_name.span, SymbolKind::Type, &type_name.name);

    // 1) User-declared static method. Borrow the method table and decl
    // straight out of the (immutable) input rather than cloning the whole
    // `MethodTable`/`FnDecl` on every static-shaped call.
    if let Some(method_decl) = ctx
        .input
        .methods
        .get(&type_name.name)
        .and_then(|table| table.statics.get(&method.name))
    {
        ctx.callees
            .insert(expr_id, Callee::Static(Arc::clone(method_decl)));
        return check_method_args(method_decl, args, ctx, type_name, method);
    }

    // 2) Built-in `of` constructor on refined or opaque types.
    if method.name == OF
        && let Some(base) = type_decl_base(decl)
    {
        ctx.callees
            .insert(expr_id, Callee::Refine(Arc::clone(decl)));
        if args.len() != 1 {
            ctx.errors.push(CompileError::new(
                "bynk.types.constructor_arity",
                span,
                format!(
                    "constructor `{}.of` expects 1 argument, but {} were given",
                    type_name.name,
                    args.len()
                ),
            ));
            return None;
        }
        let arg = &args[0];
        let expected = tys.intern(Ty::Base(base));
        let arg_ty = type_of(arg, Some(expected), ctx)?;
        if !compatible(arg_ty, expected, tys) {
            ctx.errors.push(CompileError::new(
                "bynk.types.constructor_base_mismatch",
                arg.span,
                format!(
                    "constructor `{}.of` expects a `{}` argument, but got `{}`",
                    type_name.name,
                    base.name(),
                    arg_ty.display(tys)
                ),
            ));
            return None;
        }
        // `.of` is always the runtime constructor: it returns
        // `Result[T, ValidationError]`. Compile-time literal admission (v0.9.4)
        // happens instead wherever an expected refined type is known — see
        // `admit_refined_literal`, used by `type_of` — so `.of`'s type never
        // depends on the form of its argument.
        return Some(tys.intern(Ty::Result(
            named_ty(decl, tys),
            tys.intern(Ty::ValidationError),
        )));
    }

    // 2b) Built-in `unsafe` constructor on opaque types — only available
    // inside the defining commons.
    if method.name == UNSAFE
        && let TypeBody::Opaque { base, .. } = &decl.body
    {
        ctx.callees
            .insert(expr_id, Callee::Unsafe(Arc::clone(decl)));
        if !ctx.input.is_local_type(&decl.name.name) {
            ctx.errors.push(
                CompileError::new(
                    "bynk.types.opaque_unsafe_outside",
                    method.span,
                    format!(
                        "`{}.unsafe(...)` is only available within the commons that defines the opaque type `{}`",
                        type_name.name, type_name.name
                    ),
                )
                .with_note(
                    "outside the defining commons, opaque values are constructed via `T.of(value)`",
                ),
            );
            return None;
        }
        if args.len() != 1 {
            ctx.errors.push(CompileError::new(
                "bynk.types.constructor_arity",
                span,
                format!(
                    "`{}.unsafe` expects 1 argument, but {} were given",
                    type_name.name,
                    args.len()
                ),
            ));
            return None;
        }
        let arg = &args[0];
        let expected = tys.intern(Ty::Base(*base));
        let arg_ty = type_of(arg, Some(expected), ctx)?;
        if !compatible(arg_ty, expected, tys) {
            ctx.errors.push(CompileError::new(
                "bynk.types.constructor_base_mismatch",
                arg.span,
                format!(
                    "`{}.unsafe` expects a `{}` argument, but got `{}`",
                    type_name.name,
                    base.name(),
                    arg_ty.display(tys)
                ),
            ));
            return None;
        }
        return Some(named_ty(decl, tys));
    }

    // 3) Qualified variant construction `TypeName.Variant(args)`.
    if let TypeBody::Sum(_) = &decl.body {
        ctx.callees.insert(
            expr_id,
            Callee::Ctor {
                sum: Arc::clone(decl),
                tag: method.name.clone(),
            },
        );
        return check_variant_construction(decl, &method.name, args, span, expected, ctx);
    }

    ctx.errors.push(
        CompileError::new(
            "bynk.types.unknown_static_member",
            method.span,
            format!(
                "type `{}` has no static method or variant named `{}`",
                type_name.name, method.name
            ),
        )
        // Finding #46: `decl` comes from the combined cross-file symbol
        // table — see resolver.rs:1029 for the full rationale.
        .with_note("type declared here"),
    );
    None
}

fn check_method_args(
    method_decl: &FnDecl,
    args: &[Expr],
    ctx: &mut Ctx,
    type_name: &Ident,
    method: &Ident,
) -> Option<TyId> {
    let tys = ctx.tys;
    if method_decl.params.len() != args.len() {
        ctx.errors.push(
            CompileError::new(
                "bynk.types.method_arity",
                method.span,
                format!(
                    "static method `{}.{}` expects {} argument(s), but {} were given",
                    type_name.name,
                    method.name,
                    method_decl.params.len(),
                    args.len()
                ),
            )
            .with_label(method_decl.name.ident().span, "method declared here"),
        );
        for a in args {
            let _ = type_of(a, None, ctx);
        }
        return None;
    }
    let mut ok = true;
    for (i, (param, arg)) in method_decl.params.iter().zip(args.iter()).enumerate() {
        record_param_hint(ctx.hints, &param.name.name, arg);
        let expected = resolve_type_ref(&param.type_ref, &ctx.input.types, tys);
        let actual = type_of(arg, expected, ctx);
        let (Some(actual), Some(expected)) = (actual, expected) else {
            ok = false;
            continue;
        };
        if !compatible(actual, expected, tys) {
            ctx.errors.push(CompileError::new(
                "bynk.types.argument_mismatch",
                arg.span,
                format!(
                    "argument {} to `{}.{}` has type `{}`, but parameter `{}` expects `{}`",
                    i + 1,
                    type_name.name,
                    method.name,
                    actual.display(tys),
                    param.name.name,
                    expected.display(tys)
                ),
            ));
            ok = false;
        }
    }
    if !ok {
        return None;
    }
    resolve_type_ref(&method_decl.return_type, &ctx.input.types, tys)
}

/// v0.82 (ADR 0110): resolve a storage-map operation `<map>.<op>(args)` on a
/// `store Map[K, V]` field. The ops are effect-typed (storage I/O, awaited with
/// `<-`): `put`/`update`/`upsert`/`remove` → `Effect[()]`, `get` →
/// `Effect[Option[V]]`, `contains` → `Effect[Bool]`, `size` → `Effect[Int]`.
/// `update` on an absent key is a runtime fault; `upsert` is the default-if-absent
/// form. Dispatched by receiver provenance, so it never shadows the immutable
/// value `Map`'s pure methods.
pub(crate) fn check_store_map_op(
    method: &Ident,
    args: &[Expr],
    k: TyId,
    v: TyId,
    span: Span,
    ctx: &mut Ctx,
) -> Option<TyId> {
    let tys = ctx.tys;
    let vfn = || Ty::Fn {
        params: vec![v],
        ret: v,
    };
    // v0.105 (slice 3b-ii): a held `Map[K, Connection]` stores connection ids and
    // resolves them by identity; `update`/`upsert` transform the value through a
    // `(V) -> V` function, which has no meaning for a held resource — you cannot
    // derive a new connection from an old one. Reject them (the other entry ops —
    // `put`/`get`/`remove`/`contains`/`size` — are admitted) so the program is a
    // clean compile error rather than a silent miscompile.
    if v.is_held(tys) && matches!(method.name.as_str(), "update" | "upsert") {
        ctx.errors.push(
            CompileError::new(
                "bynk.held.unsupported_map_op",
                method.span,
                format!(
                    "a held `Map[K, Connection]` has no `{}` operation — a held resource cannot be transformed by a `(Connection) -> Connection` function",
                    method.name
                ),
            )
            .with_note(
                "held connections are stored and resolved by identity; use `put`/`get`/`remove`",
            ),
        );
        for a in args {
            type_of(a, None, ctx);
        }
        return None;
    }
    let (expected, result): (Vec<TyId>, TyId) = match method.name.as_str() {
        "put" => (vec![k, v], tys.intern(Ty::Unit)),
        "get" => (vec![k], tys.intern(Ty::Option(v))),
        "remove" => (vec![k], tys.intern(Ty::Unit)),
        "contains" => (vec![k], tys.intern(Ty::Base(BaseType::Bool))),
        "size" => (vec![], tys.intern(Ty::Base(BaseType::Int))),
        "update" => (vec![k, tys.intern(vfn())], tys.intern(Ty::Unit)),
        "upsert" => (vec![k, v, tys.intern(vfn())], tys.intern(Ty::Unit)),
        other => {
            ctx.errors.push(
                CompileError::new(
                    "bynk.store.unknown_op",
                    method.span,
                    format!(
                        "a `Map` store field has no operation `{other}` — expected `put`, `get`, \
                         `update`, `upsert`, `remove`, `contains`, or `size`"
                    ),
                )
                .with_note("storage-map ops are entry-level and effectful (await with `<-`)"),
            );
            for a in args {
                type_of(a, None, ctx);
            }
            return None;
        }
    };
    let effect = Ty::Effect(result);
    if args.len() != expected.len() {
        ctx.errors.push(CompileError::new(
            "bynk.types.call_arity",
            span,
            format!(
                "`Map.{}` takes {} argument(s), found {}",
                method.name,
                expected.len(),
                args.len()
            ),
        ));
        for a in args {
            type_of(a, None, ctx);
        }
        return Some(tys.intern(effect));
    }
    for (a, exp) in args.iter().zip(expected.iter()) {
        if let Some(at) = type_of(a, Some(*exp), ctx)
            && !compatible(at, *exp, tys)
        {
            ctx.errors.push(CompileError::new(
                "bynk.types.argument_mismatch",
                a.span,
                format!(
                    "expected `{}`, found `{}`",
                    exp.display(tys),
                    at.display(tys)
                ),
            ));
        }
    }
    Some(tys.intern(effect))
}

/// v0.99: record a capability requirement at `site` into the ledger, and — when
/// the enclosing handler's `given` does not cover it — push the diagnostic. The
/// single producer behind both the bare diagnostic and the editor surfaces
/// (DECISION D): every requirement is *recorded*, covered or not; only an
/// uncovered one errors. The `code`/`message` are the consuming feature's, so a
/// store op keeps its precise diagnostic; the ledger's *reason* renders from
/// `source` alone (DECISION C), never from `code`.
fn require_capability(
    site: Span,
    capability: &str,
    source: RequirementSource,
    ctx: &mut Ctx,
    code: &'static str,
    message: &str,
) {
    let covered = ctx.caps.capabilities.contains_key(capability);
    if covered {
        ctx.caps.given_used.insert(capability.to_string());
    } else {
        ctx.errors
            .push(CompileError::new(code, site, message).with_note(format!(
                "add `{capability}` to the handler's `given` clause"
            )));
    }
    record_requirement(ctx, capability, site, source, covered);
}

/// Push a [`Requirement`] into the ledger. For an uncovered requirement it also
/// computes the materialization edit (the ghost `given` inlay hint's one-click
/// apply) from the handler's existing `given` entries and anchor — the same
/// `given_insertion_edit` the undeclared-capability quick-fix uses.
fn record_requirement(
    ctx: &mut Ctx,
    capability: &str,
    site: Span,
    source: RequirementSource,
    covered: bool,
) {
    let materialize = if covered {
        None
    } else {
        given_insertion_edit(&ctx.caps.given_entries, ctx.caps.given_anchor, capability).map(
            |(edit_span, edit_text)| Materialize {
                anchor: ctx.caps.given_anchor.unwrap_or(ctx.return_ty_span),
                edit_span,
                edit_text,
            },
        )
    };
    ctx.requirements.record(Requirement {
        capability: capability.to_string(),
        site,
        source,
        covered,
        materialize,
    });
}

/// v0.87 (ADR 0113): resolve a storage-`Cache` operation `<cache>.<op>(args)` on
/// a `store Cache[K, V]` field. The op set is the storage `Map`'s
/// (`put`/`get`/`update`/`upsert`/`remove`/`contains`/`size`); every op but
/// `remove` additionally requires `given Clock` (eviction reads the clock).
pub(crate) fn check_store_cache_op(
    method: &Ident,
    args: &[Expr],
    k: TyId,
    v: TyId,
    span: Span,
    ctx: &mut Ctx,
) -> Option<TyId> {
    let tys = ctx.tys;
    let vfn = || Ty::Fn {
        params: vec![v],
        ret: v,
    };
    let (expected, result): (Vec<TyId>, TyId) = match method.name.as_str() {
        "put" => (vec![k, v], tys.intern(Ty::Unit)),
        "get" => (vec![k], tys.intern(Ty::Option(v))),
        "remove" => (vec![k], tys.intern(Ty::Unit)),
        "contains" => (vec![k], tys.intern(Ty::Base(BaseType::Bool))),
        "size" => (vec![], tys.intern(Ty::Base(BaseType::Int))),
        "update" => (vec![k, tys.intern(vfn())], tys.intern(Ty::Unit)),
        "upsert" => (vec![k, v, tys.intern(vfn())], tys.intern(Ty::Unit)),
        other => {
            ctx.errors.push(
                CompileError::new(
                    "bynk.store.unknown_op",
                    method.span,
                    format!(
                        "a `Cache` store field has no operation `{other}` — expected `put`, \
                         `get`, `update`, `upsert`, `remove`, `contains`, or `size`"
                    ),
                )
                .with_note("storage-cache ops are entry-level and effectful (await with `<-`)"),
            );
            for a in args {
                type_of(a, None, ctx);
            }
            return None;
        }
    };
    // D4: every op but `remove` reads the clock for TTL expiry.
    if method.name != "remove" {
        require_capability(
            method.span,
            "Clock",
            RequirementSource::StoreOp {
                kind: StoreKind::Cache,
                op: method.name.clone(),
            },
            ctx,
            "bynk.store.cache_needs_clock",
            "a `Cache` operation applies TTL expiry, which reads the clock — the handler must declare `given Clock`",
        );
    }
    let effect = Ty::Effect(result);
    if args.len() != expected.len() {
        ctx.errors.push(CompileError::new(
            "bynk.types.call_arity",
            span,
            format!(
                "`Cache.{}` takes {} argument(s), found {}",
                method.name,
                expected.len(),
                args.len()
            ),
        ));
        for a in args {
            type_of(a, None, ctx);
        }
        return Some(tys.intern(effect));
    }
    for (a, exp) in args.iter().zip(expected.iter()) {
        if let Some(at) = type_of(a, Some(*exp), ctx)
            && !compatible(at, *exp, tys)
        {
            ctx.errors.push(CompileError::new(
                "bynk.types.argument_mismatch",
                a.span,
                format!(
                    "expected `{}`, found `{}`",
                    exp.display(tys),
                    at.display(tys)
                ),
            ));
        }
    }
    Some(tys.intern(effect))
}

/// v0.95 (ADR 0121): resolve a storage-`Log` operation `<log>.<op>(args)` on a
/// `store Log[T]` field. `append(e)` is the effectful, **non-idempotent** write
/// (`Effect[()]`) and the one clock-consuming op — it stamps `Clock.now()`, so it
/// requires `given Clock`. The time-window roots — `since(Instant)`/
/// `before(Instant)` / `between(Instant, Instant)` / `recent(Int)` / `reversed()`
/// — and the general query vocabulary lift the log into a lazy `Query[T]` over its
/// entry values; these need no clock (window bounds are explicit `Instant`s).
pub(crate) fn check_store_log_op(
    method: &Ident,
    args: &[Expr],
    elem: TyId,
    span: Span,
    ctx: &mut Ctx,
) -> Option<TyId> {
    let tys = ctx.tys;
    let query = || Ty::Query(elem);
    let arity = |n: usize, ctx: &mut Ctx| {
        if args.len() != n {
            ctx.errors.push(CompileError::new(
                "bynk.types.call_arity",
                span,
                format!(
                    "`Log.{}` takes {n} argument(s), found {}",
                    method.name,
                    args.len()
                ),
            ));
            for a in args {
                type_of(a, None, ctx);
            }
            return false;
        }
        true
    };
    let window_arg = |a: &Expr, what: &str, ctx: &mut Ctx| {
        if let Some(at) = type_of(a, Some(tys.intern(Ty::Base(BaseType::Instant))), ctx)
            && !compatible(at, tys.intern(Ty::Base(BaseType::Instant)), tys)
        {
            ctx.errors.push(CompileError::new(
                "bynk.types.argument_mismatch",
                a.span,
                format!("{what} expects `Instant`, found `{}`", at.display(tys)),
            ));
        }
    };
    match method.name.as_str() {
        // The one effectful write — non-idempotent; stamps the clock.
        "append" => {
            require_capability(
                method.span,
                "Clock",
                RequirementSource::StoreOp {
                    kind: StoreKind::Log,
                    op: method.name.clone(),
                },
                ctx,
                "bynk.store.log_needs_clock",
                "`Log.append` stamps the current time, which reads the clock — the handler must declare `given Clock`",
            );
            if !arity(1, ctx) {
                return Some(tys.intern(Ty::Effect(tys.intern(Ty::Unit))));
            }
            if let Some(at) = type_of(&args[0], Some(elem), ctx)
                && !compatible(at, elem, tys)
            {
                ctx.errors.push(CompileError::new(
                    "bynk.types.argument_mismatch",
                    args[0].span,
                    format!(
                        "expected `{}`, found `{}`",
                        elem.display(tys),
                        at.display(tys)
                    ),
                ));
            }
            Some(tys.intern(Ty::Effect(tys.intern(Ty::Unit))))
        }
        // Time-window query roots → `Query[T]` (lazy; no clock).
        "since" | "before" => {
            if !arity(1, ctx) {
                return Some(tys.intern(query()));
            }
            window_arg(&args[0], &format!("`Log.{}`", method.name), ctx);
            Some(tys.intern(query()))
        }
        "between" => {
            if !arity(2, ctx) {
                return Some(tys.intern(query()));
            }
            window_arg(&args[0], "`Log.between` start", ctx);
            window_arg(&args[1], "`Log.between` end", ctx);
            Some(tys.intern(query()))
        }
        "recent" => {
            if !arity(1, ctx) {
                return Some(tys.intern(query()));
            }
            check_arg(
                &args[0],
                tys.intern(Ty::Base(BaseType::Int)),
                "the `Log.recent` count",
                ctx,
            );
            Some(tys.intern(query()))
        }
        "reversed" => {
            if !arity(0, ctx) {
                return Some(tys.intern(query()));
            }
            Some(tys.intern(query()))
        }
        // The general query vocabulary over the entry values.
        name if is_query_op(name) => check_query_kernel_method(method, args, elem, span, ctx),
        other => {
            ctx.errors.push(
                CompileError::new(
                    "bynk.store.unknown_op",
                    method.span,
                    format!(
                        "a `Log` store field has no operation `{other}` — `append`, the \
                         time-window roots (`since`/`before`/`between`/`recent`/`reversed`), \
                         and the query builders/terminals"
                    ),
                )
                .with_note(
                    "`Log` reads are lazy `Query[T]`; only `append` is effectful and writes",
                ),
            );
            for a in args {
                type_of(a, None, ctx);
            }
            None
        }
    }
}

/// v0.83: resolve a storage-set operation `<set>.<op>(args)` on a `store Set[T]`
/// field. Effect-typed entry ops: `add(t)`/`remove(t)` → `Effect[()]` (both
/// idempotent), `contains(t)` → `Effect[Bool]`, `size()` → `Effect[Int]`. Set
/// algebra (`union`/`intersection`/`difference`) is deferred (it needs a value
/// `Set` return type). Dispatched by receiver provenance.
pub(crate) fn check_store_set_op(
    method: &Ident,
    args: &[Expr],
    t: TyId,
    span: Span,
    ctx: &mut Ctx,
) -> Option<TyId> {
    let tys = ctx.tys;
    let (expected, result): (Vec<TyId>, TyId) = match method.name.as_str() {
        "add" => (vec![t], tys.intern(Ty::Unit)),
        "remove" => (vec![t], tys.intern(Ty::Unit)),
        "contains" => (vec![t], tys.intern(Ty::Base(BaseType::Bool))),
        "size" => (vec![], tys.intern(Ty::Base(BaseType::Int))),
        other => {
            ctx.errors.push(
                CompileError::new(
                    "bynk.store.unknown_op",
                    method.span,
                    format!(
                        "a `Set` store field has no operation `{other}` — expected `add`, \
                         `remove`, `contains`, or `size`"
                    ),
                )
                .with_note(
                    "set algebra (`union`/`intersection`/`difference`) is not in this slice",
                ),
            );
            for a in args {
                type_of(a, None, ctx);
            }
            return None;
        }
    };
    let effect = Ty::Effect(result);
    if args.len() != expected.len() {
        ctx.errors.push(CompileError::new(
            "bynk.types.call_arity",
            span,
            format!(
                "`Set.{}` takes {} argument(s), found {}",
                method.name,
                expected.len(),
                args.len()
            ),
        ));
        for a in args {
            type_of(a, None, ctx);
        }
        return Some(tys.intern(effect));
    }
    for (a, exp) in args.iter().zip(expected.iter()) {
        if let Some(at) = type_of(a, Some(*exp), ctx)
            && !compatible(at, *exp, tys)
        {
            ctx.errors.push(CompileError::new(
                "bynk.types.argument_mismatch",
                a.span,
                format!(
                    "expected `{}`, found `{}`",
                    exp.display(tys),
                    at.display(tys)
                ),
            ));
        }
    }
    Some(tys.intern(effect))
}

/// v0.98 (ADR 0125): resolve a storage-`Cell` operation `<cell>.<op>(args)` on a
/// `store Cell[T]` field. The single method-shaped cell op is `update(f)` —
/// `f: (T) -> T` — a read-modify-write typed `Effect[()]`. Reading a cell is the
/// bare-name sugar and writing it is `:=`, so `read`/`write` are not callable
/// methods (DECISION B). The combiner is a non-effectful `Ty::Fn`, so an
/// effectful body (including a bare read of another cell) fails the existing
/// function-type check (DECISION E). Dispatched by receiver provenance.
pub(crate) fn check_store_cell_op(
    method: &Ident,
    args: &[Expr],
    t: TyId,
    span: Span,
    ctx: &mut Ctx,
) -> Option<TyId> {
    let tys = ctx.tys;
    let tfn = || Ty::Fn {
        params: vec![t],
        ret: t,
    };
    let (expected, result): (Vec<TyId>, TyId) = match method.name.as_str() {
        "update" => (vec![tys.intern(tfn())], tys.intern(Ty::Unit)),
        other => {
            ctx.errors.push(
                CompileError::new(
                    "bynk.store.unknown_op",
                    method.span,
                    format!("a `Cell` store field has no operation `{other}` — expected `update`"),
                )
                .with_note(
                    "a cell is read by its bare name and written with `:=`; `update` is the only \
                     method-shaped op",
                ),
            );
            for a in args {
                type_of(a, None, ctx);
            }
            return None;
        }
    };
    let effect = Ty::Effect(result);
    if args.len() != expected.len() {
        ctx.errors.push(CompileError::new(
            "bynk.types.call_arity",
            span,
            format!(
                "`Cell.{}` takes {} argument(s), found {}",
                method.name,
                expected.len(),
                args.len()
            ),
        ));
        for a in args {
            type_of(a, None, ctx);
        }
        return Some(tys.intern(effect));
    }
    for (a, exp) in args.iter().zip(expected.iter()) {
        if let Some(at) = type_of(a, Some(*exp), ctx)
            && !compatible(at, *exp, tys)
        {
            ctx.errors.push(CompileError::new(
                "bynk.types.argument_mismatch",
                a.span,
                format!(
                    "expected `{}`, found `{}`",
                    exp.display(tys),
                    at.display(tys)
                ),
            ));
        }
    }
    Some(tys.intern(effect))
}

#[allow(clippy::too_many_arguments)]
pub(crate) fn check_method_call(
    receiver: &Expr,
    method: &Ident,
    type_args: &[TypeRef],
    args: &[Expr],
    span: Span,
    expected: Option<TyId>,
    // P6.0 (#1139): the outer `MethodCall` expression's own identity.
    expr_id: ExprId,
    ctx: &mut Ctx,
) -> Option<TyId> {
    let tys = ctx.tys;
    // v0.22b: explicit type arguments apply only to the `Json.decode[T]`
    // static — every other method/static takes none (the 0039/0045 rule). A
    // user-declared type named `Json` shadows the codec module and takes no type
    // arguments. #594: a generic *user* instance method infers its type
    // arguments from the receiver and the argument types — the explicit
    // `x.map[U](…)` form is deferred, so explicit type args are rejected here.
    // #926: a capability operation may declare its own type parameter(s),
    // resolved only from an explicit call-site type argument (never
    // inferred) — the same explicit-only discipline as `Json.decode[T]`, so
    // it joins that carve-out rather than `#594`'s inference. Covers a bare
    // local/declared capability receiver and a cross-context one (flattened
    // `Cap.op[T](…)` or qualified `B.Cap.op[T](…)`); arity/substitution
    // happens downstream in `check_static_call` /
    // `check_cross_context_capability_call`.
    let receiver_is_capability = matches!(&receiver.kind, ExprKind::Ident(id)
            if ctx.caps.capabilities.contains_key(&id.name)
                || ctx.caps.declared_capabilities.contains_key(&id.name))
        || flatten_ident_chain(receiver).is_some_and(|chain| {
            ctx.input
                .cross_context
                .resolve_cross_capability(&chain)
                .is_some()
        });
    if !type_args.is_empty()
        && !matches!(&receiver.kind, ExprKind::Ident(id) if id.name == JSON
            && !ctx.input.types.contains_key(JSON))
        && !receiver_is_capability
    {
        ctx.errors.push(CompileError::new(
            "bynk.generics.type_arg_mismatch",
            span,
            format!(
                "`{}` does not take explicit type arguments — a generic method infers them from the receiver and arguments",
                method.name
            ),
        ));
        for a in args {
            let _ = type_of(a, None, ctx);
        }
        return None;
    }
    // v0.25 / v0.178: a test body invokes the target's service as
    // `svc.call(args)`. The emitter wires the call from the same service set;
    // the checker resolves the service's `on call` handler and verifies the
    // call's arity and argument types (v0.178, #662 — before this, the branch
    // matched the literal method name `call` without checking the handler
    // exists, so `api.call(…)` on a `from http` service passed `check` and
    // crashed at runtime, #654). The outcome type stays loose — the runner
    // recovers `Result`/`Effect` shapes at runtime — but the binding edge is
    // real, so it is recorded for test-file references. Returns here: the
    // resolution must not fall through to the receiver walk, which would
    // report the service name as unknown (#504 backstop).
    if let ExprKind::Ident(id) = &receiver.kind
        && ctx.lookup(id.name.as_str()).is_none()
        && let Some(sig) = ctx.test_services.get(&id.name).cloned()
    {
        if let Some(unit) = ctx.input.cross_context.self_context.clone() {
            ctx.refs
                .record_in_unit(id.span, SymbolKind::Service, &id.name, &unit);
        }
        return check_test_service_address(&sig, id, method, args, expr_id, ctx);
    }
    // v0.6: cross-context service call. Two shapes:
    //   - `Alias.service(args)`           where Alias is from `consumes X as Alias`
    //   - `prefix.tail.service(args)`     where `prefix.tail` is a consumed context's
    //                                     qualified name (parsed as nested FieldAccess).
    // The full-qualified-name form must be checked before the bare-ident form
    // (the prefix's first segment doesn't resolve as anything local).
    if ctx.lookup_root_ident(receiver).is_none() && !ctx.root_ident_is_store_field(receiver) {
        // v0.15: cross-context capability call — `B.Cap.op(args)` /
        // `Alias.Cap.op(args)`. Checked before the service-call shape because
        // the receiver carries an extra (capability) segment.
        if let Some(chain) = flatten_ident_chain(receiver)
            && let Some((consumed, cap)) = ctx.input.cross_context.resolve_cross_capability(&chain)
        {
            // v0.25: the capability name-segment (`Cap` in `B.Cap` /
            // `Alias.Cap`) is the outermost field of the receiver chain.
            if let ExprKind::FieldAccess { field, .. } = &receiver.kind {
                ctx.refs
                    .record_in_unit(field.span, SymbolKind::Capability, &cap, &consumed);
            }
            return check_cross_context_capability_call(
                receiver, &consumed, &cap, method, type_args, args, span, expr_id, ctx,
            );
        }
        if let Some(consumed) = cross_context_prefix(receiver, ctx) {
            return check_cross_context_call(receiver, &consumed, method, args, span, expr_id, ctx);
        }
        // Looks like a dotted prefix (no local binding for the root). If the
        // chain matches the shape of a consumed-context call but the prefix
        // isn't actually consumed, surface an explicit diagnostic so the user
        // can fix the missing `consumes` clause rather than seeing a silent
        // "no methods" error later.
        if let ExprKind::FieldAccess { .. } = &receiver.kind
            && let Some(chain) = flatten_ident_chain(receiver)
            && chain.contains('.')
        {
            let info = &ctx.input.cross_context;
            let in_context = info.self_context.is_some();
            if in_context && info.resolve_prefix(&chain).is_none() {
                ctx.errors.push(
                    CompileError::new(
                        "bynk.resolve.unconsumed_context",
                        receiver.span,
                        format!(
                            "`{chain}.{}` looks like a cross-context service call, but `{chain}` is not in this context's `consumes` clauses",
                            method.name
                        ),
                    )
                    .with_note(
                        "add a `consumes {chain}` clause at the top of the context, or use an alias and call it through the alias",
                    ),
                );
                for a in args {
                    let _ = type_of(a, None, ctx);
                }
                return None;
            }
        }
    }
    // Detect capability call (v0.5): receiver is a bare Ident naming a
    // capability declared in the context (in scope via `given`, or declared
    // but undeclared in `given` — the static-call path emits the error).
    if let ExprKind::Ident(id) = &receiver.kind
        && ctx.lookup(id.name.as_str()).is_none()
        && (ctx.caps.capabilities.contains_key(&id.name)
            || ctx.caps.declared_capabilities.contains_key(&id.name))
    {
        return check_static_call(id, method, type_args, args, span, expected, expr_id, ctx);
    }
    // Detect static-call shape: receiver is a bare Ident naming a declared
    // type (not a local/param). Dispatch to check_static_call. `type_args` is
    // always empty here — `check_method_call`'s gate above only admits a
    // non-empty slice for a capability (handled just above) or the `Json`
    // codec (handled separately, `check_json_static`).
    if let ExprKind::Ident(id) = &receiver.kind
        && ctx.lookup(id.name.as_str()).is_none()
        && ctx.input.types.contains_key(&id.name)
    {
        return check_static_call(id, method, type_args, args, span, expected, expr_id, ctx);
    }
    // v0.20b: qualified statics on the built-in collection types —
    // `List.empty()` / `Map.empty()`. Like an empty `[]`, they need an
    // expected type to pin their element/key/value types.
    if let ExprKind::Ident(id) = &receiver.kind
        && ctx.lookup(id.name.as_str()).is_none()
        && !ctx.input.types.contains_key(&id.name)
        && (id.name == LIST || id.name == MAP)
    {
        let ns = if id.name == LIST { LIST } else { MAP };
        ctx.callees.insert(
            expr_id,
            Callee::Intrinsic {
                ns,
                op: method.name.clone(),
            },
        );
        return check_collection_static(id, method, args, span, expected, ctx);
    }
    // v0.22a: the numeric parse statics — `Int.parse(s)` / `Float.parse(s)`.
    // The parser only admits these keywords in receiver position when
    // followed by `.`, so the Ident shape here is exactly the static form.
    if let ExprKind::Ident(id) = &receiver.kind
        && (id.name == INT || id.name == FLOAT)
    {
        let ns = if id.name == INT { INT } else { FLOAT };
        ctx.callees.insert(
            expr_id,
            Callee::Intrinsic {
                ns,
                op: method.name.clone(),
            },
        );
        return check_numeric_parse_static(id, method, args, span, ctx);
    }
    // v0.86 (ADR 0112): the `Duration.millis(n)` static constructor — the way to
    // build a `Duration` from a runtime `Int` (the literal covers constants).
    if let ExprKind::Ident(id) = &receiver.kind
        && id.name == DURATION
        && ctx.lookup(DURATION).is_none()
        && !ctx.input.types.contains_key(DURATION)
    {
        ctx.callees.insert(
            expr_id,
            Callee::Intrinsic {
                ns: DURATION,
                op: method.name.clone(),
            },
        );
        return check_duration_static(method, args, span, ctx);
    }
    // v0.90 (ADR 0114 D6): the `Instant.fromEpochMillis(n)` static constructor.
    if let ExprKind::Ident(id) = &receiver.kind
        && id.name == INSTANT
        && ctx.lookup(INSTANT).is_none()
        && !ctx.input.types.contains_key(INSTANT)
    {
        ctx.callees.insert(
            expr_id,
            Callee::Intrinsic {
                ns: INSTANT,
                op: method.name.clone(),
            },
        );
        return check_instant_static(method, args, span, ctx);
    }
    // v0.110 (ADR 0142 D2): the `Bytes` static constructors —
    // `Bytes.fromUtf8(s)` / `Bytes.fromBase64(s)` / `Bytes.empty()`.
    if let ExprKind::Ident(id) = &receiver.kind
        && id.name == BYTES
        && ctx.lookup(BYTES).is_none()
        && !ctx.input.types.contains_key(BYTES)
    {
        ctx.callees.insert(
            expr_id,
            Callee::Intrinsic {
                ns: BYTES,
                op: method.name.clone(),
            },
        );
        return check_bytes_static(method, args, span, ctx);
    }
    // v0.22b: the typed JSON codec statics (ADR 0045).
    if let ExprKind::Ident(id) = &receiver.kind
        && id.name == JSON
        && ctx.lookup(JSON).is_none()
        && !ctx.input.types.contains_key(JSON)
    {
        ctx.callees.insert(
            expr_id,
            Callee::Intrinsic {
                ns: JSON,
                op: method.name.clone(),
            },
        );
        return check_json_static(method, type_args, args, span, expected, ctx);
    }
    // v0.100: the `Stream.of(xs)` static constructor (real-time track slice 0).
    if let ExprKind::Ident(id) = &receiver.kind
        && id.name == STREAM
        && ctx.lookup(STREAM).is_none()
        && !ctx.input.types.contains_key(STREAM)
    {
        ctx.callees.insert(
            expr_id,
            Callee::Intrinsic {
                ns: STREAM,
                op: method.name.clone(),
            },
        );
        return check_stream_static(method, args, span, ctx);
    }
    // v0.20b: `insert`/`prepend` return their receiver's collection type —
    // propagate an expected collection type down the chain so
    // `let m: Map[String, Int] = Map.empty().insert("a", 1)` infers.
    let recv_expected = match (expected, method.name.as_str()) {
        (Some(t), "insert") => peel_to_map(t, tys).map(|(k, v)| tys.intern(Ty::Map(k, v))),
        (Some(t), "prepend") => peel_to_list(t, tys).map(|e| tys.intern(Ty::List(e))),
        _ => None,
    };
    let recv_ty = type_of(receiver, recv_expected, ctx)?;
    // v0.20b: built-in kernel methods on the collection types. These are
    // compiler-known special forms typed directly here — generic in their
    // accumulator without the (deferred) declared-generic-methods feature;
    // the deferral bites only on declared methods (ADR 0037).
    match &*tys.get(recv_ty) {
        Ty::List(elem) => {
            ctx.callees.insert(
                expr_id,
                Callee::Kernel {
                    recv: recv_ty,
                    op: method.name.clone(),
                },
            );
            return check_list_kernel_method(method, args, *elem, span, ctx);
        }
        // v0.91 (ADR 0115): a chained builder/terminal on a lazy `Query[T]`.
        Ty::Query(elem) => {
            ctx.callees.insert(
                expr_id,
                Callee::Kernel {
                    recv: recv_ty,
                    op: method.name.clone(),
                },
            );
            return check_query_kernel_method(method, args, *elem, span, ctx);
        }
        // v0.100: a chained builder/terminal on a `Stream[T]`.
        Ty::Stream(elem) => {
            ctx.callees.insert(
                expr_id,
                Callee::Kernel {
                    recv: recv_ty,
                    op: method.name.clone(),
                },
            );
            return check_stream_kernel_method(method, args, *elem, span, ctx);
        }
        // v0.102: the held-resource operations on a `Connection[F]` — `send(f)`
        // (non-consuming) and `close()` (consuming). The linearity pass tracks
        // the ownership transitions; this types the operations.
        Ty::Connection(frame) => {
            ctx.callees.insert(
                expr_id,
                Callee::Kernel {
                    recv: recv_ty,
                    op: method.name.clone(),
                },
            );
            return check_connection_method(method, args, *frame, span, ctx);
        }
        Ty::Map(key, val) => {
            ctx.callees.insert(
                expr_id,
                Callee::Kernel {
                    recv: recv_ty,
                    op: method.name.clone(),
                },
            );
            return check_map_kernel_method(method, args, *key, *val, span, ctx);
        }
        // v0.21: the numeric kernel — conversions as value methods on the
        // bare base types. A refined value reaches these too, but via the
        // refined-receiver fallback below (after its own declared methods),
        // not via any `.raw` surface — a refined type's only source-level
        // constructors are `.of` and literal admission (ADR 0182); unlike an
        // opaque type it exposes no `.unsafe` (that is opaque-only, confined
        // to the defining commons).
        Ty::Base(base @ (BaseType::Int | BaseType::Float)) => {
            ctx.callees.insert(
                expr_id,
                Callee::Kernel {
                    recv: recv_ty,
                    op: method.name.clone(),
                },
            );
            return check_numeric_kernel_method(method, args, *base, span, ctx);
        }
        // v0.86 (ADR 0112): the `Duration` kernel — `toMillis`/`toString`.
        Ty::Base(BaseType::Duration) => {
            ctx.callees.insert(
                expr_id,
                Callee::Kernel {
                    recv: recv_ty,
                    op: method.name.clone(),
                },
            );
            return check_duration_kernel_method(method, args, span, ctx);
        }
        // v0.90 (ADR 0114): the `Instant` kernel — `toEpochMillis`/`toString`.
        Ty::Base(BaseType::Instant) => {
            ctx.callees.insert(
                expr_id,
                Callee::Kernel {
                    recv: recv_ty,
                    op: method.name.clone(),
                },
            );
            return check_instant_kernel_method(method, args, span, ctx);
        }
        // v0.110 (ADR 0142): the `Bytes` kernel — `length`/`toBase64`/`decodeUtf8`.
        Ty::Base(BaseType::Bytes) => {
            ctx.callees.insert(
                expr_id,
                Callee::Kernel {
                    recv: recv_ty,
                    op: method.name.clone(),
                },
            );
            return check_bytes_kernel_method(method, args, span, ctx);
        }
        // v0.22a: the string kernel (ADR 0046).
        Ty::Base(BaseType::String) => {
            ctx.callees.insert(
                expr_id,
                Callee::Kernel {
                    recv: recv_ty,
                    op: method.name.clone(),
                },
            );
            return check_string_kernel_method(method, args, span, ctx);
        }
        // v0.22a: the Option/Result combinators as kernel methods (ADR 0048).
        Ty::Option(inner) => {
            ctx.callees.insert(
                expr_id,
                Callee::Kernel {
                    recv: recv_ty,
                    op: method.name.clone(),
                },
            );
            return check_option_kernel_method(method, args, *inner, span, ctx);
        }
        Ty::Result(ok, err) => {
            ctx.callees.insert(
                expr_id,
                Callee::Kernel {
                    recv: recv_ty,
                    op: method.name.clone(),
                },
            );
            return check_result_kernel_method(method, args, *ok, *err, span, ctx);
        }
        // The `Effect[Result[T, E]]` combinators (§2.8.3): `mapOk`/`mapErr`/
        // `flatMapOk`/`flatMapErr` on the universal cross-context shape. Only an
        // `Effect` wrapping a `Result` has methods; any other `Effect[_]` falls
        // through to the "no methods" error below.
        Ty::Effect(inner) => {
            if let Ty::Result(ok, err) = &*tys.get(*inner) {
                ctx.callees.insert(
                    expr_id,
                    Callee::Kernel {
                        recv: recv_ty,
                        op: method.name.clone(),
                    },
                );
                return check_effect_result_kernel_method(method, args, *ok, *err, span, ctx);
            }
        }
        _ => {}
    }
    // Find a named type for the receiver, then look up its instance methods.
    let type_name = match &*tys.get(recv_ty) {
        Ty::Named { name, .. } => name.clone(),
        _ => {
            ctx.errors.push(CompileError::new(
                "bynk.types.method_on_non_named_type",
                method.span,
                format!(
                    "type `{}` has no methods — only user-declared types support method calls",
                    recv_ty.display(tys)
                ),
            ));
            return None;
        }
    };
    // Agent handler dispatch: when the receiver is an agent instance, look
    // up the method against the agent's declared `on call` handlers and
    // resolve to the handler's return type.
    if let Some(agent) = ctx.input.agents.get(&type_name).cloned() {
        let Some(handler) = agent.handlers.iter().find(|h| {
            h.method_name
                .as_ref()
                .is_some_and(|n| n.name == method.name)
        }) else {
            ctx.errors.push(CompileError::new(
                "bynk.agent.handler_not_found",
                method.span,
                format!(
                    "agent `{}` has no handler named `{}`",
                    type_name, method.name
                ),
            ));
            for a in args {
                let _ = type_of(a, None, ctx);
            }
            return None;
        };
        ctx.callees.insert(
            expr_id,
            Callee::Agent {
                agent: type_name.clone(),
                handler: method.name.clone(),
            },
        );
        // #304: the handler is a first-class index symbol, keyed by the
        // compound `"Agent.handler"` name — same convention and same
        // recorded-regardless-of-downstream-errors placement as the
        // ordinary instance-method call below.
        ctx.refs.record(
            method.span,
            SymbolKind::Handler,
            &format!("{type_name}.{}", method.name),
        );
        if handler.params.len() != args.len() {
            ctx.errors.push(CompileError::new(
                "bynk.agent.handler_arity",
                method.span,
                format!(
                    "agent handler `{}.{}` expects {} argument(s), but {} were given",
                    type_name,
                    method.name,
                    handler.params.len(),
                    args.len()
                ),
            ));
            for a in args {
                let _ = type_of(a, None, ctx);
            }
            return None;
        }
        for (p, arg) in handler.params.iter().zip(args.iter()) {
            let pty = resolve_type_ref(&p.type_ref, &ctx.input.types, tys);
            let arg_ty = type_of(arg, pty, ctx);
            if let (Some(a), Some(p_ty)) = (arg_ty, pty.as_ref())
                && !compatible(a, *p_ty, tys)
            {
                ctx.errors.push(CompileError::new(
                    "bynk.types.argument_mismatch",
                    arg.span,
                    format!(
                        "argument has type `{}`, but `{}.{}` expects `{}`",
                        a.display(tys),
                        type_name,
                        method.name,
                        p_ty.display(tys)
                    ),
                ));
            }
        }
        return resolve_type_ref(&handler.return_type, &ctx.input.types, tys);
    }
    let table = ctx
        .input
        .methods
        .get(&type_name)
        .cloned()
        .unwrap_or_default();
    let Some(method_decl) = table.instance.get(&method.name).cloned() else {
        // #561: a refined receiver inherits its base type's read-only kernel
        // methods as a fallback *after* its own declared methods (DECISION D).
        // A refined value erases to its base at runtime, so the base methods
        // already apply bit-for-bit; only the checker had to be taught to look.
        // Results are base-typed (DECISION B) and refined arguments widen via
        // `compatible`, so the base kernel checkers need no change. The match
        // is `Refined` only — opaque types deliberately do not widen, so they
        // keep reporting `method_not_found`. `Bool` (and any base without a
        // kernel) inherits nothing and falls through to the same error.
        if let Ty::Named {
            kind: NamedKind::Refined(base),
            ..
        } = &*tys.get(recv_ty)
        {
            if !matches!(base, BaseType::Bool) {
                ctx.callees.insert(
                    expr_id,
                    Callee::Kernel {
                        recv: recv_ty,
                        op: method.name.clone(),
                    },
                );
            }
            match base {
                BaseType::Int | BaseType::Float => {
                    return check_numeric_kernel_method(method, args, *base, span, ctx);
                }
                BaseType::String => return check_string_kernel_method(method, args, span, ctx),
                BaseType::Duration => return check_duration_kernel_method(method, args, span, ctx),
                BaseType::Instant => return check_instant_kernel_method(method, args, span, ctx),
                BaseType::Bytes => return check_bytes_kernel_method(method, args, span, ctx),
                BaseType::Bool => {}
            }
        }
        ctx.errors.push(CompileError::new(
            "bynk.types.method_not_found",
            method.span,
            format!(
                "type `{}` has no instance method named `{}`",
                type_name, method.name
            ),
        ));
        return None;
    };
    // v0.36 (ADR 0069): the method is a first-class index symbol, keyed by the
    // compound `"Type.method"` name. Recorded already-spelled from the resolved
    // receiver type; the bare edge resolves through the same `uses`/`consumes`
    // qualification as cross-file type references.
    ctx.refs.record(
        method.span,
        SymbolKind::Method,
        &format!("{type_name}.{}", method.name),
    );
    ctx.callees
        .insert(expr_id, Callee::Method(Arc::clone(&method_decl)));
    // #594: a generic instance method — one on a generic receiver, or one
    // carrying its own type parameters — resolves its parameter and return
    // types against a substitution seeded from the receiver's type arguments,
    // then infers the method's own parameters from the argument types
    // (argument-directed unification, ADR 0029). A method on a non-generic
    // receiver with no own type parameters takes the plain path below,
    // byte-identically to before.
    let recv_type_params: Vec<String> = ctx
        .input
        .types
        .get(&type_name)
        .map(|d| d.type_params.iter().map(|p| p.name.name.clone()).collect())
        .unwrap_or_default();
    if !recv_type_params.is_empty() || !method_decl.type_params.is_empty() {
        return check_generic_method_call(
            &type_name,
            &recv_type_params,
            recv_ty,
            &method_decl,
            method,
            args,
            ctx,
        );
    }
    // Param count excludes the implicit `self`.
    if method_decl.params.len() != args.len() {
        ctx.errors.push(
            CompileError::new(
                "bynk.types.method_arity",
                method.span,
                format!(
                    "method `{}.{}` expects {} argument(s), but {} were given",
                    type_name,
                    method.name,
                    method_decl.params.len(),
                    args.len()
                ),
            )
            .with_label(method_decl.name.ident().span, "method declared here"),
        );
        for a in args {
            let _ = type_of(a, None, ctx);
        }
        return None;
    }
    let mut ok = true;
    for (i, (param, arg)) in method_decl.params.iter().zip(args.iter()).enumerate() {
        record_param_hint(ctx.hints, &param.name.name, arg);
        let expected = resolve_type_ref(&param.type_ref, &ctx.input.types, tys);
        let actual = type_of(arg, expected, ctx);
        let (Some(actual), Some(expected)) = (actual, expected) else {
            ok = false;
            continue;
        };
        if !compatible(actual, expected, tys) {
            ctx.errors.push(CompileError::new(
                "bynk.types.argument_mismatch",
                arg.span,
                format!(
                    "argument {} to `{}.{}` has type `{}`, but parameter `{}` expects `{}`",
                    i + 1,
                    type_name,
                    method.name,
                    actual.display(tys),
                    param.name.name,
                    expected.display(tys)
                ),
            ));
            ok = false;
        }
    }
    let _ = span;
    if !ok {
        return None;
    }
    resolve_type_ref(&method_decl.return_type, &ctx.input.types, tys)
}

/// #594: type-check a call to a generic instance method — one attached to a
/// generic type (so `self` carries the type's parameters) and/or carrying its
/// own `[U]` parameters. Mirrors [`check_generic_call`] (the free-function
/// path, ADR 0029): resolve the method's parameter/return patterns with the
/// rigid vars in scope, seed the substitution from the receiver's concrete type
/// arguments, then drive argument-directed inference over the method's own
/// parameters. The receiver's parameters are already ground (from the receiver
/// type), so only the method's own parameters need inferring.
fn check_generic_method_call(
    type_name: &str,
    recv_type_params: &[String],
    recv_ty: TyId,
    method_decl: &FnDecl,
    method: &Ident,
    args: &[Expr],
    ctx: &mut Ctx,
) -> Option<TyId> {
    let tys = ctx.tys;
    // Rigid vars: the receiver type's parameters plus the method's own.
    let mut vars: HashSet<String> = recv_type_params.iter().cloned().collect();
    for tp in &method_decl.type_params {
        vars.insert(tp.name.name.clone());
    }
    // Param count excludes the implicit `self`.
    if method_decl.params.len() != args.len() {
        ctx.errors.push(
            CompileError::new(
                "bynk.types.method_arity",
                method.span,
                format!(
                    "method `{}.{}` expects {} argument(s), but {} were given",
                    type_name,
                    method.name,
                    method_decl.params.len(),
                    args.len()
                ),
            )
            .with_label(method_decl.name.ident().span, "method declared here"),
        );
        for a in args {
            let _ = type_of(a, None, ctx);
        }
        return None;
    }
    // Seed the substitution from the receiver's concrete type arguments: the
    // type's parameters are ground the moment the receiver's type is known
    // (`self.map(g)` on a `Box[User]` binds the type's `A` to `User`; on `self`
    // it binds `A` to its own rigid var). An arity mismatch here means the
    // receiver was under-applied — reported where the receiver was typed — so we
    // leave those parameters unseeded and fail below as uninferable.
    let mut subst: HashMap<String, TyId> = HashMap::new();
    if let Ty::Named {
        args: recv_args, ..
    } = &*tys.get(recv_ty)
        && recv_args.len() == recv_type_params.len()
    {
        for (name, arg) in recv_type_params.iter().zip(recv_args.iter()) {
            subst.insert(name.clone(), *arg);
        }
    }
    // Resolve the method's parameter and return patterns with every rigid var in
    // scope (a name matching one resolves to `Ty::Var`, not an unknown type).
    let var_params: Vec<Option<TyId>> = method_decl
        .params
        .iter()
        .map(|p| resolve_type_ref_in(&p.type_ref, &ctx.input.types, &vars, tys))
        .collect();
    let ret_pattern = resolve_type_ref_in(&method_decl.return_type, &ctx.input.types, &vars, tys)?;

    let mut arg_tys: Vec<Option<TyId>> = vec![None; args.len()];
    // Pass 1 — non-lambda arguments (mirrors `check_generic_call`).
    for (i, arg) in args.iter().enumerate() {
        if matches!(arg.kind, ExprKind::Lambda(_)) {
            continue;
        }
        let expected = var_params[i].map(|p| substitute(p, &subst, tys));
        let ty = type_of(arg, expected, ctx);
        if let (Some(pattern), Some(actual)) = (var_params[i], ty)
            && !unify(pattern, actual, &mut subst, tys)
        {
            ctx.errors.push(CompileError::new(
                "bynk.generics.type_arg_mismatch",
                arg.span,
                format!(
                    "argument {} infers a type for `{}.{}`'s type parameter that conflicts with an earlier argument or the receiver",
                    i + 1,
                    type_name,
                    method.name
                ),
            ));
            return None;
        }
        arg_tys[i] = ty;
    }
    // Pass 2 — lambda arguments, against the now-substituted expecteds.
    for (i, arg) in args.iter().enumerate() {
        if !matches!(arg.kind, ExprKind::Lambda(_)) {
            continue;
        }
        let expected = var_params[i].map(|p| substitute(p, &subst, tys));
        let params_unconstrained = expected.is_some_and(|e| {
            matches!(&*tys.get(e), Ty::Fn { params, .. }
                if params.iter().any(|p| contains_var(*p, tys)))
        });
        let fully_annotated = matches!(
            &arg.kind,
            ExprKind::Lambda(l) if l.params.iter().all(|p| p.type_ref.is_some())
        );
        if params_unconstrained && !fully_annotated {
            ctx.errors.push(
                CompileError::new(
                    "bynk.generics.uninferable_type_arg",
                    arg.span,
                    format!(
                        "the lambda's parameter types depend on `{}.{}`'s type parameters, which the receiver and other arguments do not determine",
                        type_name, method.name
                    ),
                )
                .with_note("annotate the lambda's parameters"),
            );
            return None;
        }
        let ty = if params_unconstrained {
            type_of(arg, None, ctx)
        } else {
            type_of(arg, expected, ctx)
        };
        if let (Some(pattern), Some(actual)) = (var_params[i], ty)
            && !unify(pattern, actual, &mut subst, tys)
        {
            ctx.errors.push(CompileError::new(
                "bynk.generics.type_arg_mismatch",
                arg.span,
                format!(
                    "the lambda's type conflicts with `{}.{}`'s inferred type arguments",
                    type_name, method.name
                ),
            ));
            return None;
        }
        arg_tys[i] = ty;
    }
    // Every one of the method's own type parameters must now be determined (the
    // receiver's parameters were seeded above).
    for tp in &method_decl.type_params {
        if !subst.contains_key(&tp.name.name) {
            ctx.errors.push(
                CompileError::new(
                    "bynk.generics.uninferable_type_arg",
                    method.span,
                    format!(
                        "type parameter `{}` of `{}.{}` is not inferable from the receiver or the arguments",
                        tp.name.name, type_name, method.name
                    ),
                )
                .with_label(tp.span, "declared here"),
            );
            return None;
        }
    }
    // Final compatibility over the fully-ground parameter types.
    let mut ok = true;
    for (i, (pattern, arg)) in var_params.iter().zip(args).enumerate() {
        record_param_hint(ctx.hints, &method_decl.params[i].name.name, arg);
        let (Some(pattern), Some(arg_ty)) = (pattern, arg_tys[i].as_ref()) else {
            continue;
        };
        let ground = substitute(*pattern, &subst, tys);
        if !compatible(*arg_ty, ground, tys) {
            ctx.errors.push(CompileError::new(
                "bynk.types.argument_mismatch",
                arg.span,
                format!(
                    "argument {} to `{}.{}` has type `{}`, but `{}` is expected",
                    i + 1,
                    type_name,
                    method.name,
                    arg_ty.display(tys),
                    ground.display(tys)
                ),
            ));
            ok = false;
        }
    }
    if !ok {
        return None;
    }
    // #1702 review: the same call-site bound as a generic function's, over the
    // receiver type's parameters and the method's own.
    let decl = ctx.input.methods.get(type_name).and_then(|t| {
        t.instance
            .get(&method.name)
            .or_else(|| t.statics.get(&method.name))
            .cloned()
    });
    let compared = match &decl {
        Some(decl) if std::ptr::eq(decl.as_ref(), method_decl) => {
            super::equality::compared_type_params(decl, ctx)
        }
        _ => Default::default(),
    };
    let mut params: Vec<(String, Option<Span>)> = method_decl
        .type_params
        .iter()
        .map(|tp| (tp.name.name.clone(), Some(tp.span)))
        .collect();
    params.extend(recv_type_params.iter().map(|p| (p.clone(), None)));
    let callee = format!("{type_name}.{}", method.name);
    if !super::equality::check_compared_args(&callee, method.span, &params, &compared, &subst, ctx)
    {
        return None;
    }
    // v0.39 (ADR 0072)-style hint: show the inferred method type arguments after
    // the method name (`box.map` [Int] `(f)`). Only the method's own
    // parameters — the receiver's are visible in the receiver's type.
    if !method_decl.type_params.is_empty() {
        let rendered: Option<Vec<String>> = method_decl
            .type_params
            .iter()
            .map(|tp| subst.get(&tp.name.name).map(|t| t.display(tys)))
            .collect();
        if let Some(parts) = rendered {
            ctx.hints
                .record(method.span, format!("[{}]", parts.join(", ")));
        }
    }
    Some(substitute(ret_pattern, &subst, tys))
}

/// v0.178 (#662) / v0.182 (#664): resolve a test-body service invocation against
/// the target's declared handlers and check its arity and argument types. The
/// address form depends on the method name:
///
/// - `svc.call(args)` — the `on call` handler (#662);
/// - `svc.<VERB>("/path", …)` — an http route (`GET`/`POST`/`PUT`/`PATCH`/`DELETE`);
/// - `svc.schedule("<expr>", …)` — a cron handler by its schedule string;
/// - `svc.message(msg)` — the queue message handler.
///
/// The outcome type stays loose (the runner recovers `Result`/`Effect` at
/// runtime); the call-site principal (`by <Actor>`) is checked separately at the
/// statement level. Returns `None` (the loose outcome) in every arm.
fn check_test_service_address(
    sig: &TestServiceSig,
    id: &Ident,
    method: &Ident,
    args: &[Expr],
    // P6.0 (#1139): the outer `MethodCall` expression's own identity.
    expr_id: ExprId,
    ctx: &mut Ctx,
) -> Option<TyId> {
    use bynk_syntax::ast::{ExprKind as EK, HandlerKind};

    // `svc.call(...)` — the `on call` handler (Slice 0).
    if method.name == "call" {
        ctx.callees.insert(
            expr_id,
            Callee::TestService {
                service: id.name.clone(),
                address: "call".to_string(),
            },
        );
        let Some(handler) = sig.call_handler() else {
            let message = match &sig.protocol {
                Some(protocol) => format!(
                    "`{}` is a `from {protocol}` service and has no `on call` handler to invoke",
                    id.name
                ),
                None => format!("service `{}` has no `on call` handler to invoke", id.name),
            };
            ctx.errors.push(
                CompileError::new("bynk.test.service_no_call_handler", method.span, message)
                    .with_note(
                        "call an `on call` service with `svc.call(...)`, an http route with `svc.GET(\"/path\")`, cron with `svc.schedule(\"…\")`, or a queue with `svc.message(m)`",
                    ),
            );
            for a in args {
                let _ = type_of(a, None, ctx);
            }
            return None;
        };
        let params = handler.params.clone();
        check_address_args(&id.name, "call", &params, args, method.span, ctx);
        return None;
    }

    // `svc.<VERB>("/path", …)` — an http route. The first argument is the route
    // *pattern* (a compile-time-resolved name), the rest are positional path
    // params then the body, matched against the handler's declared params.
    // `HttpMethod::from_ident` is the single source of truth the emitter shares.
    if bynk_syntax::ast::HttpMethod::from_ident(&method.name).is_some() {
        ctx.callees.insert(
            expr_id,
            Callee::TestService {
                service: id.name.clone(),
                address: method.name.clone(),
            },
        );
        let Some(EK::StrLit(path)) = args.first().map(|a| &a.kind) else {
            ctx.errors.push(
                CompileError::new(
                    "bynk.test.service_bad_address",
                    method.span,
                    format!(
                        "`{}.{}` addresses an http route, so its first argument must be the route pattern string (e.g. `\"/todos\"`)",
                        id.name, method.name
                    ),
                ),
            );
            for a in args {
                let _ = type_of(a, None, ctx);
            }
            return None;
        };
        // The classification recorded above (verb only) is enriched here,
        // now that the route pattern — the thing `sig.handlers` is actually
        // matched against below — is known; a later go-to-definition
        // consumer needs the path, not just the verb, to resolve a handler.
        ctx.callees.insert(
            expr_id,
            Callee::TestService {
                service: id.name.clone(),
                address: format!("{} {path}", method.name),
            },
        );
        let matched = sig.handlers.iter().find(|h| {
            matches!(&h.kind, HandlerKind::Http { method: m, path: p } if m.as_str() == method.name && p == path)
        });
        let Some(handler) = matched else {
            // #707: the method has no handler at this path. If the *path* is
            // declared (for some other method), this is a **wrong-method** call —
            // the `405` fall-through test. Allow it: it drives the router with a
            // method the path has no handler for and observes `Rejected(
            // MethodNotAllowed)`. There is no handler, so no args are matched (a
            // `405` is synthesised before the body is read); the outcome is loose.
            let path_declared = sig
                .handlers
                .iter()
                .any(|h| matches!(&h.kind, HandlerKind::Http { path: p, .. } if p == path));
            if path_declared {
                let _ = type_of(&args[0], None, ctx);
                // A wrong-method call has no handler, so it takes only the path;
                // diagnose extra args rather than silently dropping them (the
                // lowering forwards only method+path to the generic driver).
                if args.len() > 1 {
                    ctx.errors.push(
                        CompileError::new(
                            "bynk.test.service_call_arity",
                            method.span,
                            format!(
                                "`{}.{}(\"{}\")` is a wrong-method `405` test and takes only the route path, but {} argument(s) were given",
                                id.name,
                                method.name,
                                path,
                                args.len() - 1
                            ),
                        )
                        .with_note("a wrong-method call reaches no handler, so it passes no body or params"),
                    );
                    for a in &args[1..] {
                        let _ = type_of(a, None, ctx);
                    }
                }
                return None;
            }
            ctx.errors.push(
                CompileError::new(
                    "bynk.test.service_unknown_route",
                    method.span,
                    format!(
                        "`{}` declares no route at `\"{}\"` (no handler for any method)",
                        id.name, path
                    ),
                )
                .with_note("the path must match a declared route; drive a wrong method against an existing path to test the `405` fall-through"),
            );
            for a in args {
                let _ = type_of(a, None, ctx);
            }
            return None;
        };
        let params = handler.params.clone();
        // Type the route-pattern string as an ordinary string; check the rest.
        let _ = type_of(&args[0], None, ctx);
        check_address_args(
            &id.name,
            &method.name,
            &params,
            &args[1..],
            method.span,
            ctx,
        );
        return None;
    }

    // `svc.schedule("<expr>", …)` — a cron handler, matched by its schedule.
    if method.name == "schedule" {
        ctx.callees.insert(
            expr_id,
            Callee::TestService {
                service: id.name.clone(),
                address: "schedule".to_string(),
            },
        );
        let Some(EK::StrLit(expr)) = args.first().map(|a| &a.kind) else {
            ctx.errors.push(CompileError::new(
                "bynk.test.service_bad_address",
                method.span,
                format!(
                    "`{}.schedule` addresses a cron handler, so its first argument must be the schedule string",
                    id.name
                ),
            ));
            for a in args {
                let _ = type_of(a, None, ctx);
            }
            return None;
        };
        // Enrich with the schedule expression `sig.handlers` is matched
        // against below — same reasoning as the http-verb branch above.
        ctx.callees.insert(
            expr_id,
            Callee::TestService {
                service: id.name.clone(),
                address: format!("schedule {expr}"),
            },
        );
        let matched = sig
            .handlers
            .iter()
            .find(|h| matches!(&h.kind, HandlerKind::Cron { expr: e } if e == expr));
        let Some(handler) = matched else {
            ctx.errors.push(CompileError::new(
                "bynk.test.service_unknown_route",
                method.span,
                format!(
                    "`{}` declares no `on schedule(\"{}\")` handler",
                    id.name, expr
                ),
            ));
            for a in args {
                let _ = type_of(a, None, ctx);
            }
            return None;
        };
        let params = handler.params.clone();
        let _ = type_of(&args[0], None, ctx);
        check_address_args(&id.name, "schedule", &params, &args[1..], method.span, ctx);
        return None;
    }

    // `svc.message(msg)` — the queue message handler.
    if method.name == "message" {
        ctx.callees.insert(
            expr_id,
            Callee::TestService {
                service: id.name.clone(),
                address: "message".to_string(),
            },
        );
        let matched = sig
            .handlers
            .iter()
            .find(|h| matches!(&h.kind, HandlerKind::Message));
        let Some(handler) = matched else {
            ctx.errors.push(CompileError::new(
                "bynk.test.service_unknown_route",
                method.span,
                format!("`{}` declares no `on message(...)` handler", id.name),
            ));
            for a in args {
                let _ = type_of(a, None, ctx);
            }
            return None;
        };
        let params = handler.params.clone();
        check_address_args(&id.name, "message", &params, args, method.span, ctx);
        return None;
    }

    // Not a recognised address form for this service.
    let proto = sig.protocol.as_deref().unwrap_or("call");
    ctx.errors.push(CompileError::new(
        "bynk.test.service_bad_address",
        method.span,
        format!(
            "`{}.{}` is not a way to address a `from {proto}` service in a test body",
            id.name, method.name
        ),
    ));
    for a in args {
        let _ = type_of(a, None, ctx);
    }
    None
}

/// What identity, if any, a resolved actor expects (v0.182).
enum ActorIdentity {
    Typed(TyId),
    CallerString,
    Unit,
    Unknown,
}

/// Resolve an actor name to the identity it carries (v0.182).
fn resolve_actor_identity(name: &str, ctx: &Ctx) -> ActorIdentity {
    let tys = ctx.tys;
    use crate::actors::{Identity, prelude_actor};
    if let Some(decl) = ctx.test_actors.get(name) {
        return match &decl.identity {
            Some(t) => match resolve_type_ref(t, &ctx.input.types, tys) {
                Some(ty) => ActorIdentity::Typed(ty),
                None => ActorIdentity::Unit,
            },
            None => ActorIdentity::Unit,
        };
    }
    match prelude_actor(name) {
        Some(c) => match c.identity {
            Identity::Unit => ActorIdentity::Unit,
            Identity::CallerId => ActorIdentity::CallerString,
            Identity::Declared(_) => ActorIdentity::Unit,
        },
        None => ActorIdentity::Unknown,
    }
}

/// The actor a handler runs as: its declared `by <Actor>`, or the protocol
/// default (`Call`->`Caller`, `Cron`->`Scheduler`, `Queue`->`Producer`; http
/// has no default, so an http handler always declares one) (v0.182).
fn handler_actor_name(handler: &TestHandler, protocol: Option<&str>) -> Option<String> {
    if let Some(by) = &handler.by_clause {
        return Some(by.primary().name.clone());
    }
    match protocol {
        None => Some("Caller".to_string()),
        Some("cron") => Some("Scheduler".to_string()),
        Some("queue") => Some("Producer".to_string()),
        _ => None,
    }
}

/// v0.182 (#664): resolve the handler a test-body address invocation targets,
/// without side effects. Shared by the argument check and the principal check.
fn resolve_test_address<'a>(
    sig: &'a TestServiceSig,
    method: &str,
    args: &[Expr],
) -> Option<&'a TestHandler> {
    use bynk_syntax::ast::{ExprKind as EK, HandlerKind, HttpMethod};
    if method == "call" {
        return sig.call_handler();
    }
    if HttpMethod::from_ident(method).is_some() {
        let EK::StrLit(path) = &args.first()?.kind else {
            return None;
        };
        return sig.handlers.iter().find(|h| {
            matches!(&h.kind, HandlerKind::Http { method: m, path: p } if m.as_str() == method && p == path)
        });
    }
    if method == "schedule" {
        let EK::StrLit(expr) = &args.first()?.kind else {
            return None;
        };
        return sig
            .handlers
            .iter()
            .find(|h| matches!(&h.kind, HandlerKind::Cron { expr: e } if e == expr));
    }
    if method == "message" {
        return sig
            .handlers
            .iter()
            .find(|h| matches!(&h.kind, HandlerKind::Message));
    }
    None
}

/// v0.182 (#664): validate the call-site principal of a test `effect_let`
/// against the ADDRESSED HANDLER. This is where per-case identity isolation is
/// enforced: an identity-carrying handler driven with a unit principal (`by
/// Visitor`) or no `by` at all would otherwise emit a call with
/// `deps.identity === undefined`. The identity value is typed against the
/// handler's required identity type, not the principal actor's.
pub(crate) fn check_effect_let_principal(
    value: &Expr,
    principal: Option<&bynk_syntax::ast::CallSiteActor>,
    ctx: &mut Ctx,
) {
    let tys = ctx.tys;
    let ExprKind::MethodCall {
        receiver,
        method,
        args,
        ..
    } = &value.kind
    else {
        if let Some(p) = principal {
            report_principal_actor(p, ctx);
        }
        return;
    };
    let ExprKind::Ident(id) = &receiver.kind else {
        if let Some(p) = principal {
            report_principal_actor(p, ctx);
        }
        return;
    };
    let Some(sig) = ctx.test_services.get(&id.name).cloned() else {
        if let Some(p) = principal {
            report_principal_actor(p, ctx);
        }
        return;
    };
    let Some(handler) = resolve_test_address(&sig, &method.name, args).cloned() else {
        if let Some(p) = principal {
            // #707: a wrong-method `405` test (an http method whose path is
            // declared for *another* method) reaches no handler, so a `by` clause
            // is meaningless — reject it clearly. (An unresolvable address of any
            // other shape already errors in `check_test_service_address`; only the
            // now-allowed wrong-method call would otherwise drop the `by`.)
            let wrong_method = bynk_syntax::ast::HttpMethod::from_ident(&method.name).is_some()
                && matches!(args.first().map(|a| &a.kind), Some(bynk_syntax::ast::ExprKind::StrLit(path))
                    if sig.handlers.iter().any(|h| matches!(&h.kind, bynk_syntax::ast::HandlerKind::Http { path: p, .. } if p == path)));
            if wrong_method {
                ctx.errors.push(
                    CompileError::new(
                        "bynk.test.principal_on_wrong_method",
                        p.span,
                        format!(
                            "a wrong-method `405` test reaches no handler, so `by {}` is meaningless",
                            p.actor.name
                        ),
                    )
                    .with_note("drop the `by` clause on a wrong-method call"),
                );
                if let Some(id) = &p.identity {
                    let _ = type_of(id, None, ctx);
                }
            } else {
                report_principal_actor(p, ctx);
            }
        }
        return;
    };

    // #706: `by Nobody` is the reserved "no credential" principal. It drives the
    // route with no `Authorization` header so the real auth seam rejects it
    // (`401` → `Rejected(Unauthorized)`), so it is valid on any http handler
    // regardless of the required identity — the whole point is that *no* valid
    // credential is presented. It carries no identity (`by Nobody(...)` is
    // meaningless). The `system`-only tier rule is enforced at emit time, like
    // `Wire`'s (the checker has no tier).
    if let Some(p) = principal
        && p.actor.name == "Nobody"
    {
        // #710-style: `by Nobody` is only *implemented* for a Bearer-secured
        // route — the no-auth driver leaves out the `Authorization` header the
        // Bearer seam checks. On an unsecured (`Visitor`/`None`) or
        // `Signature`/`Oidc` route there is no such seam to reject a missing
        // credential, so reject it here rather than emit a call to a driver that
        // was never generated.
        let secured = handler
            .by_clause
            .as_ref()
            .is_some_and(|by| crate::actors::by_clause_is_bearer(by, &ctx.test_actors));
        if !secured {
            ctx.errors.push(
                CompileError::new(
                    "bynk.test.nobody_needs_secured_route",
                    p.span,
                    "`by Nobody` drives the Bearer auth seam to a `401`, but this handler's route is not Bearer-secured — there is no credential check to reject",
                )
                .with_note(
                    "use `by Nobody` only on a route guarded by a `Bearer` actor; a public (`Visitor`) route has no seam to test",
                ),
            );
        }
        if let Some(idv) = &p.identity {
            ctx.errors.push(CompileError::new(
                "bynk.test.actor_no_identity",
                p.span,
                "`Nobody` presents no credential, so it takes no identity — write `by Nobody`",
            ));
            let _ = type_of(idv, None, ctx);
        }
        return;
    }

    let required = handler_actor_name(&handler, sig.protocol.as_deref())
        .map(|actor| resolve_actor_identity(&actor, ctx));

    match (required, principal) {
        (Some(ActorIdentity::Typed(ty)), principal) => match principal {
            Some(p) => match resolve_actor_identity(&p.actor.name, ctx) {
                ActorIdentity::Unknown => report_principal_actor(p, ctx),
                ActorIdentity::Unit | ActorIdentity::CallerString => {
                    ctx.errors.push(CompileError::new(
                        "bynk.test.principal_identity_mismatch",
                        p.span,
                        format!(
                            "this handler runs as an actor carrying `{}`, but `by {}` supplies no matching identity",
                            ty.display(tys),
                            p.actor.name
                        ),
                    ));
                    if let Some(idv) = &p.identity {
                        let _ = type_of(idv, None, ctx);
                    }
                }
                ActorIdentity::Typed(_) => match &p.identity {
                    Some(idv) => {
                        let got = type_of(idv, Some(ty), ctx);
                        if let Some(g) = got
                            && !compatible(g, ty, tys)
                        {
                            ctx.errors.push(CompileError::new(
                                "bynk.types.argument_mismatch",
                                idv.span,
                                format!(
                                    "identity has type `{}`, but the handler expects `{}`",
                                    g.display(tys),
                                    ty.display(tys)
                                ),
                            ));
                        }
                    }
                    None => ctx.errors.push(CompileError::new(
                        "bynk.test.actor_identity_required",
                        p.span,
                        format!(
                            "actor `{}` carries an identity, so write `by {}(...)`",
                            p.actor.name, p.actor.name
                        ),
                    )),
                },
            },
            None => ctx.errors.push(
                CompileError::new(
                    "bynk.test.principal_required",
                    value.span,
                    format!(
                        "this handler runs as a verified actor carrying `{}`; the case must act as it with `by <Actor>(<identity>)`",
                        ty.display(tys)
                    ),
                )
                .with_note("append a call-site actor, e.g. `... by User(\"alice\")`"),
            ),
        },
        (_, Some(p)) => report_principal_actor(p, ctx),
        (_, None) => {}
    }
}

/// Resolve a call-site principal actor for its own diagnostics (v0.182).
fn report_principal_actor(p: &bynk_syntax::ast::CallSiteActor, ctx: &mut Ctx) {
    let tys = ctx.tys;
    let name = &p.actor.name;
    match resolve_actor_identity(name, ctx) {
        ActorIdentity::Unknown => {
            ctx.errors.push(
                CompileError::new(
                    "bynk.test.unknown_actor",
                    p.actor.span,
                    format!("`{name}` is not an actor of the target context or a prelude actor"),
                )
                .with_note("name an `actor` the target declares, or a prelude actor (`Visitor`, `Caller`, …)"),
            );
            if let Some(id) = &p.identity {
                let _ = type_of(id, None, ctx);
            }
        }
        ActorIdentity::Typed(ty) => match &p.identity {
            Some(id) => {
                let got = type_of(id, Some(ty), ctx);
                if let Some(g) = got
                    && !compatible(g, ty, tys)
                {
                    ctx.errors.push(CompileError::new(
                        "bynk.types.argument_mismatch",
                        id.span,
                        format!(
                            "identity has type `{}`, but actor `{name}` expects `{}`",
                            g.display(tys),
                            ty.display(tys)
                        ),
                    ));
                }
            }
            None => ctx.errors.push(CompileError::new(
                "bynk.test.actor_identity_required",
                p.span,
                format!("actor `{name}` carries an identity, so `by {name}(...)` needs an identity value"),
            )),
        },
        ActorIdentity::CallerString => {
            if let Some(id) = &p.identity {
                let _ = type_of(id, None, ctx);
            }
        }
        ActorIdentity::Unit => {
            if let Some(id) = &p.identity {
                let _ = type_of(id, None, ctx);
                ctx.errors.push(CompileError::new(
                    "bynk.test.actor_no_identity",
                    p.span,
                    format!("actor `{name}` has no identity, so write `by {name}` with no argument"),
                ));
            }
        }
    }
}

/// Shared arity + argument-type check for a resolved test-body service address.
/// `positional` are the arguments that map to the handler's declared params (for
/// http/cron the leading pattern string has already been split off).
fn check_address_args(
    svc: &str,
    addr: &str,
    params: &[bynk_syntax::ast::Param],
    positional: &[Expr],
    err_span: Span,
    ctx: &mut Ctx,
) {
    let tys = ctx.tys;
    if params.len() != positional.len() {
        ctx.errors.push(
            CompileError::new(
                "bynk.test.service_call_arity",
                err_span,
                format!(
                    "`{svc}.{addr}` expects {} argument(s), but {} were given",
                    params.len(),
                    positional.len()
                ),
            )
            // Finding #46: `handler_span` is the target unit's handler — a
            // test file and the unit it tests are normally different files.
            .with_note("handler declared here"),
        );
        for a in positional {
            let _ = type_of(a, None, ctx);
        }
        return;
    }
    for (i, (param, arg)) in params.iter().zip(positional.iter()).enumerate() {
        record_param_hint(ctx.hints, &param.name.name, arg);
        // Slice C: a `Wire(<String>)` argument is *raw* — it deliberately bypasses
        // the param's type so a case can drive the boundary with input the type
        // forbids. Validate only that the inner is a `String` (the wire form); the
        // `system`-only tier rule is enforced at emit time (where the tier is
        // known), alongside `system_needs_wire`. Intercept before the generic
        // `type_of`, which would otherwise report the address-arg `Wire` as
        // misplaced.
        if let bynk_syntax::ast::ExprKind::Wire(inner) = &arg.kind {
            let _ = type_of(inner, Some(tys.intern(Ty::Base(BaseType::String))), ctx);
            continue;
        }
        let expected = resolve_type_ref(&param.type_ref, &ctx.input.types, tys);
        let arg_ty = type_of(arg, expected, ctx);
        if let (Some(a), Some(p)) = (arg_ty, expected)
            && !compatible(a, p, tys)
        {
            ctx.errors.push(CompileError::new(
                "bynk.types.argument_mismatch",
                arg.span,
                format!(
                    "argument {} has type `{}`, but `{svc}.{addr}` expects `{}` for `{}`",
                    i + 1,
                    a.display(tys),
                    p.display(tys),
                    param.name.name
                ),
            ));
        }
    }
}

/// If `receiver` resolves to a consumed-context prefix (an alias or a
/// dotted qualified name appearing in `consumes`), return the consumed
/// context's qualified name. Otherwise None. Local bindings, types, and
/// capabilities take precedence — those are checked at the call site.
fn cross_context_prefix(receiver: &Expr, ctx: &Ctx) -> Option<String> {
    let info = &ctx.input.cross_context;
    if info.consumed_contexts.is_empty() && info.aliases.is_empty() {
        return None;
    }
    // Walk the receiver to assemble a candidate dotted name. Supports:
    //   Ident(X)                                 -> "X"
    //   FieldAccess { Ident(A), B }              -> "A.B"
    //   FieldAccess { FieldAccess { Ident(A), B }, C } -> "A.B.C"
    let candidate = flatten_ident_chain(receiver)?;
    let head = candidate.split('.').next().unwrap_or("");
    // The head must not shadow a local binding / capability / declared type.
    if ctx.lookup(head).is_some() {
        return None;
    }
    if ctx.caps.capabilities.contains_key(head) || ctx.caps.declared_capabilities.contains_key(head)
    {
        return None;
    }
    // If the head is a known local type, only an alias whose name happens to
    // collide could redirect this; aliases conflicting with types are an
    // error in project.rs, so a clash here is impossible at this point.
    info.resolve_prefix(candidate.as_str())
}

/// Flatten an `Ident`/`FieldAccess` chain into its dotted name, or None if
/// any segment isn't a bare identifier.
fn flatten_ident_chain(expr: &Expr) -> Option<String> {
    match &expr.kind {
        ExprKind::Ident(id) => Some(id.name.clone()),
        ExprKind::FieldAccess { receiver, field } => {
            let head = flatten_ident_chain(receiver)?;
            Some(format!("{head}.{}", field.name))
        }
        _ => None,
    }
}

/// Type-check a cross-context service call (v0.6 §4.2). `receiver` carries
/// the prefix's source span for diagnostics. `consumed` is the resolved
/// qualified name of the consumed context.
/// v0.15: type-check a cross-context capability call `B.Cap.op(args)` /
/// `Alias.Cap.op(args)`. The capability operation signatures are carried in
/// `consumed_capabilities` (in the providing context's namespace); the
/// capability must be listed in the handler/provider's `given` clause.
#[allow(clippy::too_many_arguments)]
fn check_cross_context_capability_call(
    receiver: &Expr,
    consumed: &str,
    cap: &str,
    method: &Ident,
    // #926 (Decision G): explicit type arguments for a generic capability
    // operation, qualified form (`B.Cap.op[T](…)` / `Alias.Cap.op[T](…)`).
    type_args: &[TypeRef],
    args: &[Expr],
    _span: Span,
    // P6.0 (#1139): the outer `MethodCall` expression's own identity.
    expr_id: ExprId,
    ctx: &mut Ctx,
) -> Option<TyId> {
    let tys = ctx.tys;
    ctx.callees.insert(
        expr_id,
        Callee::CrossCap {
            unit: consumed.to_string(),
            cap: cap.to_string(),
            op: method.name.clone(),
        },
    );
    // Capability calls require an effectful body (same rule as local ones).
    if !ctx.effectful {
        ctx.errors.push(CompileError::new(
            "bynk.effect.capability_in_pure_context",
            method.span,
            format!(
                "capability `{consumed}.{cap}` can only be called inside an effectful body (one returning `Effect[T]`)"
            ),
        ));
    }
    // The capability must be declared in this handler/provider's `given`.
    // The local deps key is the capability's simple name.
    if !ctx.caps.given_remaining.contains(cap) {
        let mut err = CompileError::new(
            "bynk.given.undeclared_capability",
            receiver.span,
            format!("capability `{consumed}.{cap}` is used but not listed in the `given` clause"),
        )
        .with_note(format!(
            "add `{consumed}.{cap}` to the handler's `given` clause so the dependency surface is visible at the declaration site"
        ));
        // v0.26 (ADR 0054): the one-click counterpart of the note — the
        // clause entry is the qualified form the user writes (`B.Cap`).
        if let Some((span, insert)) = given_insertion_edit(
            &ctx.caps.given_entries,
            ctx.caps.given_anchor,
            &format!("{consumed}.{cap}"),
        ) {
            err = err.with_suggestion(
                format!("add `{consumed}.{cap}` to the `given` clause"),
                vec![(span, insert)],
                Applicability::MachineApplicable,
            );
        }
        ctx.errors.push(err);
        for a in args {
            let _ = type_of(a, None, ctx);
        }
        return None;
    }
    ctx.caps.given_used.insert(cap.to_string());

    let info = &ctx.input.cross_context;
    let op = info
        .consumed_capabilities
        .get(consumed)
        .and_then(|caps| caps.get(cap))
        .and_then(|c| c.ops.iter().find(|o| o.name == method.name))
        .cloned();
    let Some(op) = op else {
        ctx.errors.push(CompileError::new(
            "bynk.capability.unknown_operation",
            method.span,
            format!(
                "capability `{consumed}.{cap}` has no operation named `{}`",
                method.name
            ),
        ));
        for a in args {
            let _ = type_of(a, None, ctx);
        }
        return None;
    };
    // v0.36 (ADR 0069, slice 2): a cross-context op call references the op,
    // recorded already-qualified into the providing unit (where the op is
    // declared), mirroring the cross-context capability reference.
    ctx.refs.record_in_unit(
        method.span,
        SymbolKind::CapabilityOp,
        &format!("{cap}.{}", method.name),
        consumed,
    );
    if op.params.len() != args.len() {
        ctx.errors.push(CompileError::new(
            "bynk.capability.op_arity",
            method.span,
            format!(
                "capability operation `{consumed}.{cap}.{}` expects {} argument(s), but {} were given",
                method.name,
                op.params.len(),
                args.len()
            ),
        ));
        for a in args {
            let _ = type_of(a, None, ctx);
        }
        return None;
    }

    // Resolve parameter / return types in the consumed context's namespace.
    let consumed_types = info
        .consumed_types
        .get(consumed)
        .cloned()
        .unwrap_or_default();
    // #926: resolve the op's own type parameter(s) — declared in the
    // *consumed* context's namespace but instantiated from an explicit type
    // argument named in the *calling* context's own namespace (same split
    // `resolve_type_ref`/`resolve_expr_type_ref` already draw for
    // params/return vs. call-site type args in the local-capability path,
    // `check_static_call`). Explicit only, never inferred.
    let vars: HashSet<String> = op.type_params.iter().cloned().collect();
    let mut subst: HashMap<String, TyId> = HashMap::new();
    if !op.type_params.is_empty() || !type_args.is_empty() {
        if type_args.is_empty() {
            ctx.errors.push(
                CompileError::new(
                    "bynk.generics.uninferable_type_arg",
                    method.span,
                    format!(
                        "capability operation `{consumed}.{cap}.{}` takes a type parameter, but none of its arguments determine it",
                        method.name
                    ),
                )
                .with_note(format!(
                    "give it explicitly: `{consumed}.{cap}.{}[T](…)`",
                    method.name
                )),
            );
            for a in args {
                let _ = type_of(a, None, ctx);
            }
            return None;
        }
        if type_args.len() != op.type_params.len() {
            ctx.errors.push(CompileError::new(
                "bynk.generics.type_arg_mismatch",
                method.span,
                format!(
                    "capability operation `{consumed}.{cap}.{}` takes {} type argument(s), but {} were given",
                    method.name,
                    op.type_params.len(),
                    type_args.len()
                ),
            ));
            for a in args {
                let _ = type_of(a, None, ctx);
            }
            return None;
        }
        for (tp, ta) in op.type_params.iter().zip(type_args) {
            let ty = resolve_expr_type_ref(ta, ctx)?;
            subst.insert(tp.clone(), ty);
        }
    }
    let mut all_ok = true;
    for (i, ((pname, ptype_ref), arg)) in op.params.iter().zip(args.iter()).enumerate() {
        record_param_hint(ctx.hints, pname, arg);
        let param_ty = resolve_type_ref_in(ptype_ref, &consumed_types, &vars, tys)
            .unwrap_or(tys.intern(Ty::Unit));
        let param_ty = substitute(param_ty, &subst, tys);
        let Some(arg_ty) = type_of(arg, None, ctx) else {
            all_ok = false;
            continue;
        };
        if !structurally_compatible(arg_ty, param_ty, &ctx.input.types, &consumed_types, tys) {
            ctx.errors.push(CompileError::new(
                "bynk.boundary.structural_mismatch",
                arg.span,
                format!(
                    "cross-context argument {} to `{consumed}.{cap}.{}` has type `{}`, but parameter `{pname}` expects `{}`",
                    i + 1,
                    method.name,
                    arg_ty.display(tys),
                    param_ty.display(tys),
                ),
            ));
            all_ok = false;
        }
    }
    if !all_ok {
        return None;
    }
    let raw_ret = resolve_type_ref_in(&op.return_type, &consumed_types, &vars, tys)
        .unwrap_or(tys.intern(Ty::Unit));
    let raw_ret = substitute(raw_ret, &subst, tys);
    Some(rebrand_return_type(raw_ret, &ctx.input.types, tys))
}

fn check_cross_context_call(
    receiver: &Expr,
    consumed: &str,
    method: &Ident,
    args: &[Expr],
    _span: Span,
    // P6.0 (#1139): the outer `MethodCall` expression's own identity.
    expr_id: ExprId,
    ctx: &mut Ctx,
) -> Option<TyId> {
    let tys = ctx.tys;
    ctx.callees.insert(
        expr_id,
        Callee::Cross {
            unit: consumed.to_string(),
            service: method.name.clone(),
        },
    );
    // The consuming context must be effectful at this call site (services
    // and agent handlers are; pure free fns are not).
    if !ctx.effectful {
        ctx.errors.push(
            CompileError::new(
                "bynk.effect.cross_context_in_pure_context",
                method.span,
                format!(
                    "cross-context service call `{}.{}` can only be made inside an effectful body (one returning `Effect[T]`)",
                    consumed, method.name
                ),
            )
            .with_label(receiver.span, "consumed context prefix"),
        );
    }
    let info = &ctx.input.cross_context;
    let Some(svcs) = info.consumed_services.get(consumed) else {
        ctx.errors.push(
            CompileError::new(
                "bynk.consumes.unknown_context",
                receiver.span,
                format!("context `{consumed}` is not in scope here"),
            )
            .with_note(
                "add a `consumes` clause for the target context at the top of the consuming context",
            ),
        );
        for a in args {
            let _ = type_of(a, None, ctx);
        }
        return None;
    };
    let Some(service) = svcs.get(&method.name).cloned() else {
        ctx.errors.push(
            CompileError::new(
                "bynk.consumes.unknown_service",
                method.span,
                format!(
                    "context `{consumed}` has no service named `{}`",
                    method.name
                ),
            )
            .with_note(
                "cross-context calls require an `on call` service handler in the consumed context",
            ),
        );
        for a in args {
            let _ = type_of(a, None, ctx);
        }
        return None;
    };
    ctx.refs
        .record_in_unit(method.span, SymbolKind::Service, &method.name, consumed);

    if service.params.len() != args.len() {
        ctx.errors.push(
            CompileError::new(
                "bynk.consumes.service_arity",
                method.span,
                format!(
                    "cross-context service `{consumed}.{}` expects {} argument(s), but {} were given",
                    method.name,
                    service.params.len(),
                    args.len()
                ),
            )
            // Finding #46: `service` belongs to the *consumed*
            // context — a different unit/file than this call, almost
            // always. A label would risk underlining unrelated text
            // there; a note carries the information safely (per-label
            // file identity is a Wave 8 follow-up).
            .with_note("service declared here"),
        );
        for a in args {
            let _ = type_of(a, None, ctx);
        }
        return None;
    }

    // Resolve the consumed-context types so we can describe parameter shapes.
    let consumed_types = info
        .consumed_types
        .get(consumed)
        .cloned()
        .unwrap_or_default();

    // Walk each argument, checking structural compatibility (Phase 4).
    let mut all_ok = true;
    for (i, ((pname, ptype_ref), arg)) in service.params.iter().zip(args.iter()).enumerate() {
        record_param_hint(ctx.hints, pname, arg);
        let param_ty =
            resolve_type_ref(ptype_ref, &consumed_types, tys).unwrap_or(tys.intern(Ty::Unit));
        // Type-check the argument in the caller's context.
        let arg_ty = type_of(arg, None, ctx);
        let Some(arg_ty) = arg_ty else {
            all_ok = false;
            continue;
        };
        if !structurally_compatible(arg_ty, param_ty, &ctx.input.types, &consumed_types, tys) {
            ctx.errors.push(
                CompileError::new(
                    "bynk.boundary.structural_mismatch",
                    arg.span,
                    format!(
                        "cross-context argument {} to `{consumed}.{}` has type `{}` in `{}`, but parameter `{pname}` expects `{}` in `{}`",
                        i + 1,
                        method.name,
                        arg_ty.display(tys),
                        ctx.input
                            .cross_context
                            .self_context
                            .as_deref()
                            .unwrap_or("?"),
                        param_ty.display(tys),
                        consumed,
                    ),
                )
                // Finding #46: same cross-unit provenance as above.
                .with_note("service declared here")
                .with_note(
                    "values crossing a context boundary must have structurally compatible types (same commons-derived type, or identical record/sum shape)",
                ),
            );
            all_ok = false;
        }
    }
    if !all_ok {
        return None;
    }

    // Return type rebrand: project the consumed context's return type into
    // the calling context's namespace by renaming named types whose unqualified
    // name appears in the caller's type table (v0.6 §4.5).
    let raw_ret = resolve_type_ref(&service.return_type, &consumed_types, tys)
        .unwrap_or(tys.intern(Ty::Unit));
    let rebranded = rebrand_return_type(raw_ret, &ctx.input.types, tys);
    Some(rebranded)
}