Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

311 KB
Raw Blame
/*
 * py_lsp.c — Python type-aware call resolution.
 *
 * Implements the Python LSP-style binder + type evaluator + call resolver.
 * Mirrors go_lsp.c / c_lsp.c:
 *   - py_lsp_bind_imports     (Phase 3) — imports → root scope
 *   - py_eval_expr_type       (Phase 5) — single-expression type
 *   - py_process_statement    (Phase 4) — assignment / for / with binding
 *   - py_lookup_attribute     (Phase 6) — attribute walk with MRO
 *   - py_resolve_calls_in     (Phase 4-6) — recursive AST walker emitting
 *                                          resolved_calls entries
 */
#include "py_lsp.h"
#include "../cbm.h"
#include "../helpers.h"
#include "../../../src/foundation/hash_table.h" /* module-scope suffix index (re-exports) */
#include "lsp_node_iter.h"
#include "tree_sitter/api.h"
#include <ctype.h>
#include <limits.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

/* Minimal Python builtins as real graph nodes (py_builtins_inject_defs).
 * #included here (CGo amalgamation pattern, see lsp_all.c) — referenced
 * only from py_lsp.c, never compiled standalone. */
#include "py_builtins.c"

/* Stack guard for py_eval_expr_type (#720; same limit as C_EVAL_DEPTH_LIMIT).
 * It counts expression NESTING (call arguments, container elements, operands
 * outside a chain); the links of a left-associative chain do not count, see
 * py_eval_chain_operands.
 * There is deliberately NO per-file work budget (#1527): the step cap that
 * used to sit here stopped resolution after 10000 evaluations and left the
 * rest of a large file silently unresolved while the file still reported
 * status `indexed`. Memoized evaluation (#710), hashed scope frames, and
 * cursor-based child access reduce the repeated work. Memo failure is reported
 * explicitly; the existing depth bound now reports an incomplete walk too. */
#define PY_LSP_MAX_EVAL_DEPTH 256
#include "lsp_work.h"

#ifdef CBM_ENABLE_TEST_SEAMS
_Atomic uint64_t cbm_py_submodule_probes = 0;
_Atomic uint64_t cbm_py_submodule_probe_visits = 0;
_Atomic uint64_t cbm_py_module_class_binds = 0;
_Atomic uint64_t cbm_py_module_class_bind_visits = 0;
_Atomic uint64_t cbm_py_wildcard_invalidations = 0;
_Atomic uint64_t cbm_py_wildcard_invalidation_visits = 0;
static _Thread_local int py_module_scratch_allocations_left = -1;
static _Thread_local int py_module_prefix_allocations_left = -1;
void cbm_py_test_module_scratch_fail_after(int successful_allocations) {
    py_module_scratch_allocations_left = successful_allocations;
}
void cbm_py_test_module_prefix_fail_after(int successful_allocations) {
    py_module_prefix_allocations_left = successful_allocations;
}
#endif

#ifdef CBM_ENABLE_TEST_SEAMS
static _Thread_local int py_test_memo_allocations_left = -1;
static _Thread_local bool py_test_depth_failure;
static _Thread_local int py_test_scope_allocations_left = -1;
static _Thread_local int py_test_class_frames_left = -1;
void cbm_py_lsp_test_class_frame_fail_after(int successful_allocations) {
    py_test_class_frames_left = successful_allocations;
}
void cbm_py_lsp_test_scope_fail_after(int successful_allocations) {
    py_test_scope_allocations_left = successful_allocations;
}
void cbm_py_lsp_test_depth_fail(bool enabled) {
    py_test_depth_failure = enabled;
}
void cbm_py_lsp_test_memo_fail_after(int successful_allocations) {
    py_test_memo_allocations_left = successful_allocations;
}
#endif

static void py_memo_test_stage(PyLSPContext *ctx, const char *stage) {
#ifdef CBM_ENABLE_TEST_SEAMS
    const char *depth_stage = getenv("CBM_TEST_PY_LSP_DEPTH_FAIL_STAGE");
    if (depth_stage && strcmp(depth_stage, stage) == 0)
        ctx->eval_depth = 256;
    const char *fail_stage = getenv("CBM_TEST_PY_LSP_MEMO_FAIL_STAGE");
    if (fail_stage && strcmp(fail_stage, stage) == 0)
        ctx->test_memo_allocations_left = 0;
#else
    (void)ctx;
    (void)stage;
#endif
}

void cbm_py_lsp_record_failure(CBMFileResult *result, CBMLSPStatus status) {
    result->has_error = true;
    result->lsp_skipped = true;
    /* Static lifetime also works when the result arena cannot allocate. */
    result->error_msg = status == CBM_LSP_SCOPE_FAILED     ? CBM_PY_LSP_SCOPE_ERROR
                        : status == CBM_LSP_DEPTH_EXCEEDED ? CBM_PY_LSP_DEPTH_ERROR
                                                           : CBM_PY_LSP_MEMO_ERROR;
}

// Forward decls
static void py_resolve_calls_in_inner(PyLSPContext *ctx, TSNode node);

/* Named children of one node for an index loop (#1527). ts_node_named_child(n, i)
 * restarts tree-sitter's child iterator at the first child, so indexing every
 * child of a wide node is O(n^2) -- a module of thousands of classes, or a body
 * of thousands of statements, spent most of its resolve time re-walking its
 * own children. Wide nodes are collected once (lsp_node_iter.h); narrow nodes
 * keep plain indexed access, which is cheaper than an allocation. */
enum { PY_KIDS_COLLECT_MIN = 64 };
typedef struct {
    TSNode node;
    TSNode *kids; /* NULL = index the node directly */
    uint32_t n;
} PyKids;

static PyKids py_kids(CBMArena *arena, TSNode node) {
    PyKids k = {node, NULL, ts_node_named_child_count(node)};
    if (k.n >= PY_KIDS_COLLECT_MIN) {
        uint32_t got = 0;
        TSNode *kids = cbm_lsp_collect_named_children(arena, node, &got);
        if (kids && got == k.n)
            k.kids = kids;
    }
    return k;
}

static TSNode py_kid(const PyKids *k, uint32_t i) {
    return k->kids ? k->kids[i] : ts_node_named_child(k->node, i);
}

/* Decorators are extracted as raw syntax (`@property`, `@pkg.cache(...)`),
 * not resolved qualified names.  Preserve the raw array for sound callable-
 * value admission, while parsing only enough of the spelling to retain the
 * existing descriptive flags used by Python type inference. */
static bool py_decorator_short_name_is(const char *raw, const char *expected) {
    if (!raw || !expected)
        return false;
    while (*raw && (isspace((unsigned char)*raw) || *raw == '@'))
        raw++;
    const char *end = raw;
    const char *leaf = raw;
    while (*end && *end != '(' && !isspace((unsigned char)*end)) {
        if (*end == '.')
            leaf = end + 1;
        end++;
    }
    size_t expected_len = strlen(expected);
    return (size_t)(end - leaf) == expected_len && strncmp(leaf, expected, expected_len) == 0;
}

static void py_register_func_decorators(CBMRegisteredFunc *func, const char **decorators) {
    if (!func)
        return;
    func->decorator_qns = decorators;
    if (!decorators)
        return;
    for (int i = 0; decorators[i]; i++) {
        const char *decorator = decorators[i];
        if (py_decorator_short_name_is(decorator, "property"))
            func->flags |= CBM_FUNC_FLAG_PROPERTY;
        else if (py_decorator_short_name_is(decorator, "classmethod"))
            func->flags |= CBM_FUNC_FLAG_CLASSMETHOD;
        else if (py_decorator_short_name_is(decorator, "staticmethod"))
            func->flags |= CBM_FUNC_FLAG_STATICMETHOD;
        else if (py_decorator_short_name_is(decorator, "abstractmethod"))
            func->flags |= CBM_FUNC_FLAG_ABSTRACTMETHOD;
        else if (py_decorator_short_name_is(decorator, "overload"))
            func->flags |= CBM_FUNC_FLAG_OVERLOAD;
        else if (py_decorator_short_name_is(decorator, "final"))
            func->flags |= CBM_FUNC_FLAG_FINAL;
    }
}

/* Python defines `@decorator def f` as rebinding `f = decorator(f)`.  Until
 * decorator identity and composition are semantically resolved, the raw
 * decorated definition cannot prove that a value occurrence denotes the
 * exact underlying function.  Fail closed to ordinary USAGE. */
static bool py_func_is_exact_callable_value(const CBMRegisteredFunc *func) {
    return func && func->qualified_name &&
           !(func->flags &
             (CBM_FUNC_FLAG_PROPERTY | CBM_FUNC_FLAG_OVERLOAD | CBM_FUNC_FLAG_AMBIGUOUS_BINDING)) &&
           (!func->decorator_qns || !func->decorator_qns[0]);
}

/* Reuse the QN snapshot for duplicate marks and later submodule probes.
 * The graph cannot identify one exact callable value for a duplicate QN;
 * ordinary exact lookups retain their original registration-order policy. */
static void py_mark_ambiguous_callable_bindings(CBMTypeRegistry *registry, CBMArena *idx_arena) {
    if (!registry)
        return;
    cbm_registry_build_func_qn_order(registry, idx_arena);
    if (registry->func_count <= 1)
        return;
    const CBMRegistryQNEntry *sorted = registry->func_qn_sorted;
    if (!sorted || registry->func_qn_sorted_upto != registry->func_count) {
        for (int i = 0; i < registry->func_count; i++)
            registry->funcs[i].flags |= CBM_FUNC_FLAG_AMBIGUOUS_BINDING;
        return;
    }
    int count = registry->func_qn_sorted_count;
    for (int first = 0; first < count;) {
        int end = first + 1;
        while (end < count && strcmp(sorted[first].qualified_name, sorted[end].qualified_name) == 0)
            end++;
        if (end - first > 1) {
            for (int i = first; i < end; i++)
                registry->funcs[sorted[i].func_index].flags |= CBM_FUNC_FLAG_AMBIGUOUS_BINDING;
        }
        first = end;
    }
}

/* Depth-guarded entry for the AST call-resolution walk. The walk recurses once
 * per nesting level; a deeply-nested or cyclic file can overflow the native
 * stack (SIGSEGV) and take down the whole index. Past the cap the subtree is
 * skipped — its calls stay unresolved, which is graceful degradation, not a
 * crash. The cap is CBM_LSP_MAX_WALK_DEPTH, env-overridable via the same name.
 * The walk_depth-- runs after the inner returns, so early returns in the body
 * never leak the counter. */
static void py_resolve_calls_in(PyLSPContext *ctx, TSNode node) {
    if (!ctx || ctx->eval_failure || ctx->walk_depth >= cbm_lsp_max_walk_depth())
        return;
    ctx->walk_depth++;
    py_resolve_calls_in_inner(ctx, node);
    ctx->walk_depth--;
}
static const CBMType *py_eval_expr_type(PyLSPContext *ctx, TSNode node);
static const CBMType *py_eval_expr_type_uncached(PyLSPContext *ctx, TSNode node);
static void py_process_statement(PyLSPContext *ctx, TSNode node);
static void py_exec_class_definition(PyLSPContext *ctx, TSNode class_node);
static void py_invalidate_possible_bindings(PyLSPContext *ctx, TSNode node, int depth);
static const CBMRegisteredFunc *py_lookup_attribute(PyLSPContext *ctx, const char *type_qn,
                                                    const char *member_name);
static void py_emit_resolved_call(PyLSPContext *ctx, const char *callee_qn, const char *strategy,
                                  float confidence, TSNode site);
static const CBMType *py_resolve_annotation(PyLSPContext *ctx, const char *ann);
static const CBMType *py_iterable_element_type(PyLSPContext *ctx, const CBMType *iter_type);
static const CBMType *py_lookup_field(PyLSPContext *ctx, const char *type_qn,
                                      const char *field_name);
static void py_register_instance_field(PyLSPContext *ctx, const char *class_qn,
                                       const char *field_name, const CBMType *field_type);
static void py_bind_for_target(PyLSPContext *ctx, TSNode left, const CBMType *elem_type);
static void py_register_lambda(PyLSPContext *ctx, const char *name, TSNode lambda_node);
static void py_register_dict_literal(PyLSPContext *ctx, const char *name, TSNode dict_node);
static int py_lookup_lambda(PyLSPContext *ctx, const char *name);
static const char *py_lookup_dict_dispatch(PyLSPContext *ctx, const char *var, const char *key);
static void py_process_function(PyLSPContext *ctx, TSNode func_node, const char *container_qn);
static void py_process_class(PyLSPContext *ctx, TSNode class_node);
static void py_process_class_in(PyLSPContext *ctx, TSNode class_node, const char *container_qn);
typedef enum { PY_LOCAL_DEFS_BIND, PY_LOCAL_DEFS_PROCESS } PyLocalDefsMode;
static void py_visit_local_defs(PyLSPContext *ctx, TSNode block, PyLocalDefsMode mode, int depth);

/* A name looked up in a module namespace: the module's own function or
 * class, or the definition the module re-exports under that name. At most
 * one of func/type is set. */
typedef struct {
    const CBMRegisteredFunc *func;
    const CBMRegisteredType *type;
} PyModuleMember;
static PyModuleMember py_module_member(PyLSPContext *ctx, const char *module_qn, const char *name);

/* ── Scope mutation wrappers ─────────────────────────────────────────────
 *
 * py_eval_expr_type memoizes per-node results (see the cache block above
 * py_eval_expr_type). A cached result is only valid as long as name lookup
 * resolves exactly as it did when the entry was computed, so every mutation
 * of the scope chain must invalidate the cache. Bumping the generation
 * counter is an O(1) whole-cache flush: entries from older generations
 * never match again. All binds/restores in this file MUST go through these
 * wrappers — never call cbm_scope_bind(ctx->current_scope, ...) or assign
 * ctx->current_scope directly (scope pushes are exempt: an empty child
 * scope delegates every lookup to its parent, changing nothing).
 *
 * This is what makes memoization behavior-preserving even when the same
 * node is legitimately re-evaluated under different bindings — e.g. a
 * lambda body re-walked per call site with per-call argument types, or
 * isinstance-narrowed branches. */
static void py_disable_callable_value_proof(PyLSPContext *ctx) {
    if (ctx)
        ctx->callable_value_proof_disabled = true;
}

static void py_scope_bind(PyLSPContext *ctx, const char *name, const CBMType *type) {
    ctx->type_cache_gen++;
    if (!cbm_scope_bind_checked(ctx->current_scope, name, type))
        py_disable_callable_value_proof(ctx);
}

static void py_scope_bind_callable(PyLSPContext *ctx, const char *name, const CBMType *type,
                                   const char *callable_qn) {
    ctx->type_cache_gen++;
    if (!cbm_scope_bind_callable_checked(ctx->current_scope, name, type, callable_qn))
        py_disable_callable_value_proof(ctx);
}

static CBMScope *py_scope_push_checked(PyLSPContext *ctx) {
    if (!ctx)
        return NULL;
    CBMScope *parent = ctx->current_scope;
    CBMScope *child = cbm_scope_push(ctx->arena, parent);
    if (!child || child == parent)
        py_disable_callable_value_proof(ctx);
    return child;
}

/* New class execution frames must never fall back to their parent: body
 * bindings would escape and subsequent calls could use those stale bindings. */
static CBMScope *py_class_frame_push(PyLSPContext *ctx, CBMScope *parent) {
#ifdef CBM_ENABLE_TEST_SEAMS
    if (py_test_class_frames_left == 0) {
        ctx->eval_failure = CBM_LSP_SCOPE_FAILED;
        return NULL;
    }
    if (py_test_class_frames_left > 0)
        py_test_class_frames_left--;
#endif
    CBMScope *frame = cbm_scope_push(ctx->arena, parent);
    if (!frame || frame == parent) {
        ctx->eval_failure = CBM_LSP_SCOPE_FAILED;
        return NULL;
    }
    return frame;
}

static void py_scope_clear_callable(PyLSPContext *ctx, const char *name) {
    if (cbm_scope_update_callable(ctx->current_scope, name, NULL)) {
        ctx->type_cache_gen++;
    }
}

static void py_scope_restore(PyLSPContext *ctx, CBMScope *saved) {
    ctx->type_cache_gen++;
    ctx->current_scope = saved;
}

/* Only a changed Python scope needs storage. Failure is explicit: never
 * register or walk a package using the raw file scope as an OOM fallback. */
static bool py_symbol_scope(CBMArena *arena, const char *module_qn, const char *stage,
                            const char **out) {
    *out = module_qn;
    size_t len = cbm_fqn_symbol_scope_len(module_qn);
    if (!module_qn || module_qn[len] == '\0')
        return true;
#ifdef CBM_ENABLE_TEST_SEAMS
    const char *fail_stage = getenv("CBM_TEST_PY_LSP_SCOPE_FAIL_STAGE");
    if ((fail_stage && strcmp(fail_stage, stage) == 0) || py_test_scope_allocations_left == 0)
        return false;
    if (py_test_scope_allocations_left > 0)
        py_test_scope_allocations_left--;
#else
    (void)stage;
#endif
    char *scope = cbm_arena_strndup(arena, module_qn, len);
    if (!scope)
        return false;
    *out = scope;
    return true;
}

static void py_lsp_init_for_stage(PyLSPContext *ctx, CBMArena *arena, const char *source,
                                  int source_len, const CBMTypeRegistry *registry,
                                  const char *module_qn, CBMResolvedCallArray *out,
                                  const char *stage) {
    if (!ctx)
        return;
    memset(ctx, 0, sizeof(PyLSPContext));
#ifdef CBM_ENABLE_TEST_SEAMS
    ctx->test_memo_allocations_left = py_test_memo_allocations_left;
    if (py_test_depth_failure)
        ctx->eval_depth = 256;
#endif
    ctx->arena = arena;
    ctx->source = source;
    ctx->source_len = source_len;
    ctx->registry = registry;
    ctx->registry_head = (CBMTypeRegistry *)registry;
    ctx->file_module_qn = module_qn;
    ctx->resolved_calls = out;
    if (!py_symbol_scope(arena, module_qn, stage, &ctx->module_qn)) {
        ctx->eval_failure = CBM_LSP_SCOPE_FAILED;
        return;
    }
    ctx->current_scope = py_scope_push_checked(ctx);
    const char *dbg = getenv("CBM_LSP_DEBUG");
    ctx->debug = dbg && dbg[0] && dbg[0] != '0';
}

void py_lsp_init(PyLSPContext *ctx, CBMArena *arena, const char *source, int source_len,
                 const CBMTypeRegistry *registry, const char *module_qn,
                 CBMResolvedCallArray *out) {
    py_lsp_init_for_stage(ctx, arena, source, source_len, registry, module_qn, out, "context");
}

void py_lsp_add_import(PyLSPContext *ctx, const char *local_name, const char *module_qn) {
    if (!ctx || !local_name || !module_qn)
        return;

    int new_count = ctx->import_count + 1;
    const char **names =
        (const char **)cbm_arena_alloc(ctx->arena, (size_t)(new_count + 1) * sizeof(const char *));
    const char **qns =
        (const char **)cbm_arena_alloc(ctx->arena, (size_t)(new_count + 1) * sizeof(const char *));
    unsigned char *kinds =
        (unsigned char *)cbm_arena_alloc(ctx->arena, (size_t)new_count * sizeof(unsigned char));
    if (!names || !qns || !kinds)
        return;

    for (int i = 0; i < ctx->import_count; i++) {
        names[i] = ctx->import_local_names[i];
        qns[i] = ctx->import_module_qns[i];
        kinds[i] = ctx->import_kinds ? ctx->import_kinds[i] : 0;
    }
    names[ctx->import_count] = cbm_arena_strdup(ctx->arena, local_name);
    qns[ctx->import_count] = cbm_arena_strdup(ctx->arena, module_qn);
    kinds[ctx->import_count] = 0;
    names[new_count] = NULL;
    qns[new_count] = NULL;

    ctx->import_local_names = names;
    ctx->import_module_qns = qns;
    ctx->import_kinds = kinds;
    ctx->import_count = new_count;
}

/* Determine whether this import is an `import X` style binding (binds the
 * module itself) or a `from X import Y` style binding (binds Y, an
 * attribute of module X). Heuristic: if module_qn ends in `.<local_name>`
 * and has at least two components, it's a from-import; otherwise it's a
 * straight module import. Matches the shape produced by extract_imports.c.
 */
static bool import_is_from_style(const char *local_name, const char *module_qn) {
    if (!local_name || !module_qn)
        return false;
    size_t local_len = strlen(local_name);
    size_t mod_len = strlen(module_qn);
    if (mod_len <= local_len)
        return false;
    if (module_qn[mod_len - local_len - 1] != '.')
        return false;
    if (strcmp(module_qn + mod_len - local_len, local_name) != 0)
        return false;
    return true;
}

typedef enum {
    PY_DIRECT_IMPORT_UNKNOWN = 0,
    PY_DIRECT_IMPORT_UNALIASED,
    PY_DIRECT_IMPORT_ALIASED,
    PY_FROM_IMPORT,
    PY_IMPORT_AMBIGUOUS,
    PY_IMPORT_UNCLASSIFIED,
} PyDirectImportKind;

typedef struct {
    int count;
    PyDirectImportKind kind;
    const char *canonical_qn;
} PyImportSyntaxMatch;

static bool py_import_node_text_equals(const PyLSPContext *ctx, TSNode node, const char *expected) {
    if (!ctx || !expected || ts_node_is_null(node))
        return false;
    uint32_t start = ts_node_start_byte(node);
    uint32_t end = ts_node_end_byte(node);
    size_t expected_len = strlen(expected);
    return end >= start && (int)end <= ctx->source_len && (size_t)(end - start) == expected_len &&
           memcmp(ctx->source + start, expected, expected_len) == 0;
}

static bool py_qn_has_boundary_suffix(const char *qualified_name, const char *suffix) {
    if (!qualified_name || !suffix)
        return false;
    while (*suffix == '.')
        suffix++;
    size_t qn_len = strlen(qualified_name);
    size_t suffix_len = strlen(suffix);
    if (suffix_len == 0 || qn_len < suffix_len)
        return false;
    size_t start = qn_len - suffix_len;
    return (start == 0 || qualified_name[start - 1] == '.') &&
           strcmp(qualified_name + start, suffix) == 0;
}

static char *py_import_node_text_dup(PyLSPContext *ctx, TSNode node) {
    if (!ctx || ts_node_is_null(node))
        return NULL;
    uint32_t start = ts_node_start_byte(node);
    uint32_t end = ts_node_end_byte(node);
    if (end < start || (int)end > ctx->source_len)
        return NULL;
    return cbm_arena_strndup(ctx->arena, ctx->source + start, (size_t)(end - start));
}

static TSNode py_from_import_module_node(TSNode statement) {
    TSNode module = ts_node_child_by_field_name(statement, "module_name", 11);
    if (!ts_node_is_null(module))
        return module;
    uint32_t count = ts_node_named_child_count(statement);
    for (uint32_t i = 0; i < count; i++) {
        TSNode child = ts_node_named_child(statement, i);
        const char *kind = ts_node_type(child);
        if (strcmp(kind, "dotted_name") == 0 || strcmp(kind, "relative_import") == 0)
            return child;
    }
    return (TSNode){0};
}

static bool py_import_node_root_equals(PyLSPContext *ctx, TSNode node, const char *expected_root) {
    char *text = py_import_node_text_dup(ctx, node);
    if (!text || !expected_root)
        return false;
    size_t root_len = strlen(expected_root);
    size_t text_len = strlen(text);
    if (root_len > text_len)
        return false;
    return strncmp(text, expected_root, root_len) == 0 &&
           (text[root_len] == '\0' || text[root_len] == '.');
}

static void py_import_syntax_match_add(PyImportSyntaxMatch *match, PyDirectImportKind kind,
                                       const char *canonical_qn) {
    if (!match)
        return;
    match->count++;
    if (match->count == 1) {
        match->kind = kind;
        match->canonical_qn = canonical_qn;
    }
}

/* The graph import map can only name the imported module. Python extraction
 * intentionally records the same metadata for
 *
 *   from target import handler as callback
 *   import target.handler as callback
 *
 * so only the parsed statement can decide whether `handler` is a member or
 * part of a module path. Canonicalize a proven from-import once, before scope
 * binding: `<project>.target` becomes `<project>.target.handler`. The sealed
 * registry then retains responsibility for proving that the exact target is
 * an undecorated, unambiguous callable. */
static const char *py_canonical_from_import_qn(PyLSPContext *ctx, TSNode statement,
                                               TSNode imported_name, const char *incoming_qn) {
    if (!ctx || !incoming_qn || ts_node_is_null(statement) || ts_node_is_null(imported_name))
        return NULL;
    TSNode module = py_from_import_module_node(statement);

    char *member = py_import_node_text_dup(ctx, imported_name);
    char *module_text = py_import_node_text_dup(ctx, module);
    if (!member || !member[0])
        return NULL;
    const char *module_suffix = module_text;
    while (module_suffix && *module_suffix == '.')
        module_suffix++;

    const char *full_suffix = module_suffix && module_suffix[0]
                                  ? cbm_arena_sprintf(ctx->arena, "%s.%s", module_suffix, member)
                                  : member;
    if (!full_suffix)
        return NULL;
    if (py_qn_has_boundary_suffix(incoming_qn, full_suffix))
        return incoming_qn;
    if (module_suffix && module_suffix[0] &&
        !py_qn_has_boundary_suffix(incoming_qn, module_suffix)) {
        return NULL;
    }
    return cbm_arena_sprintf(ctx->arena, "%s.%s", incoming_qn, member);
}

/* CBMImport intentionally stores only the local spelling and module path.
 * Recover the binding form from the AST, but require exactly one top-level
 * binding for the local name. Python permits later imports to rebind the same
 * local; selecting the first would turn conflicting runtime identities into
 * false semantic proof. */
static void py_import_match_statement(PyLSPContext *ctx, TSNode stmt, const char *local,
                                      const char *qn, PyImportSyntaxMatch *match) {
    if (!ctx || ts_node_is_null(stmt) || !local || !qn || !match)
        return;
    const char *stmt_kind = ts_node_type(stmt);
    if (strcmp(stmt_kind, "import_from_statement") == 0) {
        TSNode module = py_from_import_module_node(stmt);
        uint32_t import_count = ts_node_named_child_count(stmt);
        for (uint32_t j = 0; j < import_count; j++) {
            TSNode item = ts_node_named_child(stmt, j);
            if (!ts_node_is_null(module) && ts_node_eq(item, module))
                continue;
            const char *kind = ts_node_type(item);
            if (strcmp(kind, "aliased_import") == 0) {
                TSNode name = ts_node_child_by_field_name(item, "name", 4);
                TSNode alias = ts_node_child_by_field_name(item, "alias", 5);
                if (py_import_node_text_equals(ctx, alias, local)) {
                    const char *canonical = py_canonical_from_import_qn(ctx, stmt, name, qn);
                    py_import_syntax_match_add(match,
                                               canonical ? PY_FROM_IMPORT : PY_IMPORT_UNCLASSIFIED,
                                               canonical ? canonical : qn);
                }
            } else if ((strcmp(kind, "identifier") == 0 || strcmp(kind, "dotted_name") == 0) &&
                       py_import_node_text_equals(ctx, item, local)) {
                const char *canonical = py_canonical_from_import_qn(ctx, stmt, item, qn);
                py_import_syntax_match_add(match,
                                           canonical ? PY_FROM_IMPORT : PY_IMPORT_UNCLASSIFIED,
                                           canonical ? canonical : qn);
            }
        }
        return;
    }
    if (strcmp(stmt_kind, "import_statement") != 0)
        return;
    uint32_t import_count = ts_node_named_child_count(stmt);
    for (uint32_t j = 0; j < import_count; j++) {
        TSNode item = ts_node_named_child(stmt, j);
        const char *kind = ts_node_type(item);
        if (strcmp(kind, "aliased_import") == 0) {
            TSNode name = ts_node_child_by_field_name(item, "name", 4);
            TSNode alias = ts_node_child_by_field_name(item, "alias", 5);
            if (py_import_node_text_equals(ctx, alias, local)) {
                char *imported_path = py_import_node_text_dup(ctx, name);
                PyDirectImportKind matched_kind =
                    imported_path && py_qn_has_boundary_suffix(qn, imported_path)
                        ? PY_DIRECT_IMPORT_ALIASED
                        : PY_IMPORT_UNCLASSIFIED;
                py_import_syntax_match_add(match, matched_kind, qn);
            }
        } else if ((strcmp(kind, "dotted_name") == 0 || strcmp(kind, "identifier") == 0) &&
                   py_import_node_root_equals(ctx, item, local)) {
            char *imported_path = py_import_node_text_dup(ctx, item);
            PyDirectImportKind matched_kind =
                imported_path && py_qn_has_boundary_suffix(qn, imported_path)
                    ? PY_DIRECT_IMPORT_UNALIASED
                    : PY_IMPORT_UNCLASSIFIED;
            py_import_syntax_match_add(match, matched_kind, qn);
        }
    }
}

static PyDirectImportKind py_import_match_result(PyImportSyntaxMatch *match, const char **qn_io) {
    if (!match || !qn_io)
        return PY_DIRECT_IMPORT_UNKNOWN;
    if (match->count == 0)
        return PY_IMPORT_UNCLASSIFIED;
    if (match->count > 1)
        return PY_IMPORT_AMBIGUOUS;
    if (match->kind == PY_FROM_IMPORT && match->canonical_qn)
        *qn_io = match->canonical_qn;
    return match->kind;
}

static PyDirectImportKind py_import_kind_from_statement(PyLSPContext *ctx, TSNode stmt,
                                                        const char *local, const char **qn_io) {
    const char *qn = qn_io ? *qn_io : NULL;
    if (!ctx || !local || !qn || !qn_io || ts_node_is_null(stmt))
        return PY_DIRECT_IMPORT_UNKNOWN;
    PyImportSyntaxMatch match = {0};
    py_import_match_statement(ctx, stmt, local, qn, &match);
    return py_import_match_result(&match, qn_io);
}

/* stmts: the root's import statements, collected once per root by the caller
 * (#1527) -- only they can match, and rescanning every top-level statement
 * once per import made classification O(imports x module size). */
static PyDirectImportKind py_import_kind_from_ast(PyLSPContext *ctx, bool have_root,
                                                  const TSNode *stmts, uint32_t stmt_count,
                                                  const char *local, const char **qn_io) {
    const char *qn = qn_io ? *qn_io : NULL;
    if (!ctx || !local || !qn || !qn_io || !have_root)
        return PY_DIRECT_IMPORT_UNKNOWN;

    PyImportSyntaxMatch match = {0};
    for (uint32_t i = 0; i < stmt_count; i++) {
        py_import_match_statement(ctx, stmts[i], local, qn, &match);
    }
    return py_import_match_result(&match, qn_io);
}

static bool py_import_index_is_from_binding(const PyLSPContext *ctx, int index) {
    if (!ctx || index < 0 || index >= ctx->import_count)
        return false;
    if (ctx->import_kinds && ctx->import_kinds[index] == PY_FROM_IMPORT)
        return true;
    return (!ctx->import_kinds || ctx->import_kinds[index] == PY_DIRECT_IMPORT_UNKNOWN) &&
           import_is_from_style(ctx->import_local_names[index], ctx->import_module_qns[index]);
}

/* For an unaliased `import a.b.c`, also bind every dotted prefix as MODULE so
 * that `a.b.c.fn()` style chained access walks correctly: `a` -> MODULE(a),
 * `a.b` -> MODULE(a.b), `a.b.c` -> MODULE(a.b.c). */
static void py_bind_dotted_prefixes(PyLSPContext *ctx, const char *qn) {
    if (!ctx || !qn)
        return;
    const char *p = qn;
    for (;;) {
        const char *dot = strchr(p, '.');
        if (!dot)
            break;
        size_t prefix_len = (size_t)(dot - qn);
        char *prefix = (char *)cbm_arena_alloc(ctx->arena, prefix_len + 1);
        if (!prefix)
            return;
        memcpy(prefix, qn, prefix_len);
        prefix[prefix_len] = '\0';
        // Also bind the *short top-level name* — for `import a.b.c`,
        // the source typically writes `a.b.c.fn()` and `a` must be in
        // scope as MODULE("a") (not the full QN, since attribute access
        // walks one segment at a time).
        const char *short_name = strrchr(prefix, '.');
        const char *bind_short = short_name ? short_name + 1 : prefix;
        if (cbm_type_is_unknown(cbm_scope_lookup(ctx->current_scope, bind_short))) {
            py_scope_bind(ctx, bind_short, cbm_type_module(ctx->arena, prefix));
        }
        p = dot + 1;
    }
}

static void py_classify_imports_for_root(PyLSPContext *ctx, TSNode root) {
    if (!ctx)
        return;
    /* A null root classifies every import UNKNOWN, as it always has; so does
     * a root whose statement list cannot be allocated (no proof either way). */
    bool have_root = !ts_node_is_null(root);
    TSNode *stmts = NULL;
    uint32_t stmt_count = 0;
    if (have_root && ctx->import_count > 0) {
        PyKids rk = py_kids(ctx->arena, root);
        if (rk.n > 0) {
            stmts = (TSNode *)cbm_arena_alloc(ctx->arena, (size_t)rk.n * sizeof(TSNode));
            if (!stmts)
                have_root = false;
        }
        for (uint32_t i = 0; stmts && i < rk.n; i++) {
            TSNode c = py_kid(&rk, i);
            const char *ck = ts_node_type(c);
            if (strcmp(ck, "import_statement") == 0 || strcmp(ck, "import_from_statement") == 0)
                stmts[stmt_count++] = c;
        }
    }
    for (int i = 0; i < ctx->import_count; i++) {
        const char *local = ctx->import_local_names[i];
        const char *qn = ctx->import_module_qns[i];
        if (!local || !qn)
            continue;
        PyDirectImportKind direct_kind =
            py_import_kind_from_ast(ctx, have_root, stmts, stmt_count, local, &qn);
        ctx->import_module_qns[i] = qn;
        if (ctx->import_kinds)
            ctx->import_kinds[i] = (unsigned char)direct_kind;
    }
}

/* `from X import Y` names X.Y, which need not be a definition:
 *  - X re-exports Y (`from .fields import *` in X/__init__.py): bind the
 *    definition Y resolves to, and record that canonical QN for the import
 *    so every later consumer of the import metadata agrees;
 *  - Y is a submodule (`from django.db import models`): bind the MODULE, so
 *    `models.CharField` is a module-namespace lookup, not a class attribute.
 * A registered X.Y (the ordinary case) keeps its NAMED binding. */
static const CBMType *py_canonical_named_import(PyLSPContext *ctx, int index, const char **qn_io,
                                                const CBMType *named) {
    const char *qn = *qn_io;
    const CBMTypeRegistry *reg = ctx->registry;
    if (!reg || cbm_registry_lookup_type(reg, qn) || cbm_registry_lookup_func(reg, qn))
        return named;
    const char *dot = strrchr(qn, '.');
    if (dot && dot > qn) {
        /* the export table is keyed by symbol scope: a package import value
         * may still carry the package file identity (P.pkg.__init__.Y) */
        char *module = cbm_arena_strndup(ctx->arena, qn, (size_t)(dot - qn));
        if (module)
            module[cbm_fqn_symbol_scope_len(module)] = '\0';
        const char *target = module ? cbm_registry_lookup_export(reg, module, dot + 1) : NULL;
        if (target) {
            *qn_io = target;
            ctx->import_module_qns[index] = target;
            return cbm_type_named(ctx->arena, target);
        }
    }
    if (cbm_registry_is_module(reg, qn))
        return cbm_type_module(ctx->arena, qn);
    return named;
}

static void py_bind_import_index(PyLSPContext *ctx, int index, bool synthetic_fallback) {
    if (!ctx || !ctx->current_scope || index < 0 || index >= ctx->import_count)
        return;
    const char *local = ctx->import_local_names[index];
    const char *qn = ctx->import_module_qns[index];
    if (!local || !qn || strcmp(local, "*") == 0)
        return;

    PyDirectImportKind direct_kind =
        ctx->import_kinds ? (PyDirectImportKind)ctx->import_kinds[index] : PY_DIRECT_IMPORT_UNKNOWN;
    bool from_style = direct_kind == PY_FROM_IMPORT ||
                      (direct_kind == PY_DIRECT_IMPORT_UNKNOWN && import_is_from_style(local, qn));
    const CBMType *t;
    if (direct_kind == PY_DIRECT_IMPORT_UNALIASED) {
        // Python binds only the root of an unaliased dotted import.
        t = cbm_type_module(ctx->arena, local);
    } else if (direct_kind == PY_DIRECT_IMPORT_ALIASED) {
        t = cbm_type_module(ctx->arena, qn);
    } else if (from_style) {
        // `from X import Y` — bind Y to NAMED(X.Y). Phase 6 attribute
        // resolution checks the registry to upgrade to MODULE / class
        // / function as appropriate.
        t = cbm_type_named(ctx->arena, qn);
    } else if (strchr(qn, '.') != NULL) {
        // Dotted path whose tail does NOT match the local name: an
        // ALIASED binding — `from X import Y as Z` (Z names function/
        // class X.Y) or `import a.b as z` (z names module a.b). The
        // CBMImport shape cannot distinguish the two, but NAMED(qn)
        // covers both: phase 6 upgrades it to the registered function/
        // class for the from-import and to MODULE for the module alias.
        // Binding MODULE here made `g()` calls on `from m import f as g`
        // resolve as calls on a module — lsp=MISS, and the whole CALLS
        // edge was lost (#988).
        t = cbm_type_named(ctx->arena, qn);
    } else {
        // `import X` / `import X as Y` (single segment) — MODULE(X).
        t = cbm_type_module(ctx->arena, qn);
    }
    if (t->kind == CBM_TYPE_NAMED)
        t = py_canonical_named_import(ctx, index, &qn, t);
    const CBMRegisteredFunc *imported =
        from_style && ctx->registry ? cbm_registry_lookup_func(ctx->registry, qn) : NULL;
    if (py_func_is_exact_callable_value(imported)) {
        py_scope_bind_callable(ctx, local, t, imported->qualified_name);
    } else {
        py_scope_bind(ctx, local, t);
    }
    if (direct_kind == PY_DIRECT_IMPORT_UNALIASED || synthetic_fallback)
        py_bind_dotted_prefixes(ctx, qn);
}

static void py_lsp_bind_imports_for_root(PyLSPContext *ctx, TSNode root) {
    if (!ctx || !ctx->current_scope)
        return;
    py_classify_imports_for_root(ctx, root);
    for (int i = 0; i < ctx->import_count; i++) {
        py_bind_import_index(ctx, i, ts_node_is_null(root));
    }
}

void py_lsp_bind_imports(PyLSPContext *ctx) {
    py_lsp_bind_imports_for_root(ctx, (TSNode){0});
}

const CBMType *py_lsp_lookup_in_scope(const PyLSPContext *ctx, const char *name) {
    if (!ctx)
        return cbm_type_unknown();
    return cbm_scope_lookup(ctx->current_scope, name);
}

/* ── helpers: text + emit ─────────────────────────────────────── */

static char *py_node_text(PyLSPContext *ctx, TSNode node) {
    if (!ctx || ts_node_is_null(node))
        return NULL;
    uint32_t start = ts_node_start_byte(node);
    uint32_t end = ts_node_end_byte(node);
    if (end <= start || (int)end > ctx->source_len)
        return NULL;
    size_t len = (size_t)(end - start);
    char *out = (char *)cbm_arena_alloc(ctx->arena, len + 1);
    if (!out)
        return NULL;
    memcpy(out, ctx->source + start, len);
    out[len] = '\0';
    return out;
}

/* ── lambda + dict-literal-dispatch registries ────────────────── */

static void py_register_lambda(PyLSPContext *ctx, const char *name, TSNode lambda_node) {
    if (!ctx || !name)
        return;
    if (ctx->lambda_count >= ctx->lambda_cap) {
        int new_cap = ctx->lambda_cap == 0 ? 8 : ctx->lambda_cap * 2;
        CBMLambdaEntry *grown =
            (CBMLambdaEntry *)cbm_arena_alloc(ctx->arena, (size_t)new_cap * sizeof(CBMLambdaEntry));
        if (!grown)
            return;
        if (ctx->lambdas && ctx->lambda_count > 0) {
            memcpy(grown, ctx->lambdas, (size_t)ctx->lambda_count * sizeof(CBMLambdaEntry));
        }
        ctx->lambdas = grown;
        ctx->lambda_cap = new_cap;
    }
    // Overwrite if name already registered.
    for (int i = 0; i < ctx->lambda_count; i++) {
        if (ctx->lambdas[i].name && strcmp(ctx->lambdas[i].name, name) == 0) {
            ctx->lambdas[i].lambda_node = lambda_node;
            return;
        }
    }
    ctx->lambdas[ctx->lambda_count].name = cbm_arena_strdup(ctx->arena, name);
    ctx->lambdas[ctx->lambda_count].lambda_node = lambda_node;
    ctx->lambdas[ctx->lambda_count].expanding = false;
    ctx->lambda_count++;
}

/* Registry index of the lambda bound to `name`, or -1. An index, not a
 * pointer: the registry array is replaced when it grows. */
static int py_lookup_lambda(PyLSPContext *ctx, const char *name) {
    if (!ctx || !name)
        return -1;
    for (int i = 0; i < ctx->lambda_count; i++) {
        if (ctx->lambdas[i].name && strcmp(ctx->lambdas[i].name, name) == 0) {
            return i;
        }
    }
    return -1;
}

/* Helper for stripping quotes from a tree-sitter `string` node text. */
static char *py_string_literal_value(PyLSPContext *ctx, TSNode str_node) {
    if (ts_node_is_null(str_node))
        return NULL;
    char *lit = py_node_text(ctx, str_node);
    if (!lit)
        return NULL;
    size_t len = strlen(lit);
    if (len >= 2 && (lit[0] == '"' || lit[0] == '\'') && lit[len - 1] == lit[0]) {
        char *out = (char *)cbm_arena_alloc(ctx->arena, len - 1);
        if (!out)
            return NULL;
        memcpy(out, lit + 1, len - 2);
        out[len - 2] = '\0';
        return out;
    }
    return lit;
}

static void py_register_dict_literal(PyLSPContext *ctx, const char *var, TSNode dict_node) {
    if (!ctx || !var || ts_node_is_null(dict_node))
        return;
    uint32_t nc = ts_node_named_child_count(dict_node);
    for (uint32_t i = 0; i < nc; i++) {
        TSNode pair = ts_node_named_child(dict_node, i);
        if (strcmp(ts_node_type(pair), "pair") != 0)
            continue;
        TSNode key = ts_node_child_by_field_name(pair, "key", 3);
        TSNode value = ts_node_child_by_field_name(pair, "value", 5);
        if (ts_node_is_null(key) || ts_node_is_null(value))
            continue;
        if (strcmp(ts_node_type(key), "string") != 0)
            continue;
        if (strcmp(ts_node_type(value), "identifier") != 0)
            continue;
        char *key_text = py_string_literal_value(ctx, key);
        char *val_text = py_node_text(ctx, value);
        if (!key_text || !val_text)
            continue;
        // Resolve val_text to a registered function QN.
        const CBMRegisteredFunc *f =
            cbm_registry_lookup_symbol(ctx->registry, ctx->module_qn, val_text);
        if (!f) {
            f = cbm_registry_lookup_symbol(ctx->registry, "builtins", val_text);
        }
        if (!f)
            continue;

        if (ctx->dict_literal_count >= ctx->dict_literal_cap) {
            int new_cap = ctx->dict_literal_cap == 0 ? 16 : ctx->dict_literal_cap * 2;
            CBMDictLiteralEntry *grown = (CBMDictLiteralEntry *)cbm_arena_alloc(
                ctx->arena, (size_t)new_cap * sizeof(CBMDictLiteralEntry));
            if (!grown)
                return;
            if (ctx->dict_literals && ctx->dict_literal_count > 0) {
                memcpy(grown, ctx->dict_literals,
                       (size_t)ctx->dict_literal_count * sizeof(CBMDictLiteralEntry));
            }
            ctx->dict_literals = grown;
            ctx->dict_literal_cap = new_cap;
        }
        ctx->dict_literals[ctx->dict_literal_count].var_name = cbm_arena_strdup(ctx->arena, var);
        ctx->dict_literals[ctx->dict_literal_count].literal_key =
            cbm_arena_strdup(ctx->arena, key_text);
        ctx->dict_literals[ctx->dict_literal_count].target_qn =
            cbm_arena_strdup(ctx->arena, f->qualified_name);
        ctx->dict_literal_count++;
    }
}

static const char *py_lookup_dict_dispatch(PyLSPContext *ctx, const char *var, const char *key) {
    if (!ctx || !var || !key)
        return NULL;
    for (int i = 0; i < ctx->dict_literal_count; i++) {
        const CBMDictLiteralEntry *e = &ctx->dict_literals[i];
        if (e->var_name && e->literal_key && strcmp(e->var_name, var) == 0 &&
            strcmp(e->literal_key, key) == 0) {
            return e->target_qn;
        }
    }
    return NULL;
}

enum { PY_RESOLVED_DEDUP_WINDOW = 256 };

static void py_emit_resolved_call_reason(PyLSPContext *ctx, const char *callee_qn,
                                         const char *strategy, float confidence, const char *reason,
                                         TSNode site) {
    if (!ctx || !ctx->resolved_calls || !callee_qn || !ctx->enclosing_func_qn)
        return;
    uint32_t site_start = ts_node_is_null(site) ? 0 : ts_node_start_byte(site);
    uint32_t site_end = ts_node_is_null(site) ? 0 : ts_node_end_byte(site);
    // Dedupe by exact invocation identity. Bounded-window scan: most duplicate
    // emissions are nearby in time (same expression evaluated by both
    // resolver and emitter passes), so checking only the last DEDUP_WINDOW
    // entries catches the common case while keeping per-emission O(1).
    // Without this cap the dedup is O(N) per emission -> O(N^2) per file
    // and dominates above ~1k call sites.
    int n = ctx->resolved_calls->count;
    int start = n > PY_RESOLVED_DEDUP_WINDOW ? n - PY_RESOLVED_DEDUP_WINDOW : 0;
    for (int i = start; i < n; i++) {
        CBMResolvedCall *rc = &ctx->resolved_calls->items[i];
        if (rc->kind == CBM_RESOLVED_INVOCATION && rc->site_start_byte == site_start &&
            rc->site_end_byte == site_end && rc->caller_qn && rc->callee_qn &&
            strcmp(rc->caller_qn, ctx->enclosing_func_qn) == 0 &&
            strcmp(rc->callee_qn, callee_qn) == 0) {
            if (confidence > rc->confidence) {
                rc->confidence = confidence;
                rc->strategy = strategy;
                rc->reason = reason ? cbm_arena_strdup(ctx->arena, reason) : NULL;
            }
            return;
        }
    }
    CBMResolvedCall rc = {0};
    rc.caller_qn = ctx->enclosing_func_qn;
    rc.callee_qn = cbm_arena_strdup(ctx->arena, callee_qn);
    rc.strategy = strategy;
    rc.confidence = confidence;
    rc.reason = reason ? cbm_arena_strdup(ctx->arena, reason) : NULL;
    rc.kind = CBM_RESOLVED_INVOCATION;
    rc.site_start_byte = site_start;
    rc.site_end_byte = site_end;
    cbm_resolvedcall_push(ctx->resolved_calls, ctx->arena, rc);
}

static void py_emit_resolved_call(PyLSPContext *ctx, const char *callee_qn, const char *strategy,
                                  float confidence, TSNode site) {
    py_emit_resolved_call_reason(ctx, callee_qn, strategy, confidence, NULL, site);
}

static void py_emit_resolved_reference(PyLSPContext *ctx, const char *callee_qn,
                                       const char *source_name, TSNode site, const char *strategy) {
    if (!ctx || !ctx->resolved_calls || !callee_qn || !ctx->enclosing_func_qn ||
        ts_node_is_null(site)) {
        return;
    }
    uint32_t start = ts_node_start_byte(site);
    uint32_t end = ts_node_end_byte(site);
    for (int i = ctx->resolved_calls->count - 1; i >= 0; i--) {
        CBMResolvedCall *existing = &ctx->resolved_calls->items[i];
        if (existing->kind == CBM_RESOLVED_CALL_REFERENCE && existing->site_start_byte == start &&
            existing->site_end_byte == end && existing->caller_qn && existing->callee_qn &&
            strcmp(existing->caller_qn, ctx->enclosing_func_qn) == 0 &&
            strcmp(existing->callee_qn, callee_qn) == 0) {
            return;
        }
    }
    CBMResolvedCall rc = {0};
    rc.caller_qn = ctx->enclosing_func_qn;
    rc.callee_qn = cbm_arena_strdup(ctx->arena, callee_qn);
    rc.strategy = strategy ? strategy : "lsp_callable_value_reference";
    rc.confidence = 0.97f;
    const char *leaf = strrchr(callee_qn, '.');
    leaf = leaf ? leaf + 1 : callee_qn;
    rc.reason = source_name && strcmp(source_name, leaf) != 0
                    ? cbm_arena_strdup(ctx->arena, source_name)
                    : NULL;
    rc.kind = CBM_RESOLVED_CALL_REFERENCE;
    rc.site_start_byte = start;
    rc.site_end_byte = end;
    cbm_resolvedcall_push(ctx->resolved_calls, ctx->arena, rc);
}

static void py_emit_unresolved_reference(PyLSPContext *ctx, const char *candidate_qn, TSNode site) {
    if (!ctx || !ctx->resolved_calls || !candidate_qn || !ctx->enclosing_func_qn ||
        ts_node_is_null(site)) {
        return;
    }
    CBMResolvedCall rc = {0};
    rc.caller_qn = ctx->enclosing_func_qn;
    rc.callee_qn = cbm_arena_strdup(ctx->arena, candidate_qn);
    rc.strategy = "lsp_unresolved";
    rc.confidence = 0.0f;
    rc.reason = "callable_value_not_in_registry";
    rc.kind = CBM_RESOLVED_CALL_REFERENCE;
    rc.site_start_byte = ts_node_start_byte(site);
    rc.site_end_byte = ts_node_end_byte(site);
    cbm_resolvedcall_push(ctx->resolved_calls, ctx->arena, rc);
}

/* Return a project-pass candidate only when the import metadata itself names
 * one exact from-import target. Module imports and ambiguous duplicate local
 * bindings deliberately return NULL. */
static const char *py_exact_imported_reference_candidate(PyLSPContext *ctx,
                                                         const char *local_name) {
    if (!ctx || !local_name)
        return NULL;
    const char *candidate = NULL;
    for (int i = 0; i < ctx->import_count; i++) {
        const char *local = ctx->import_local_names[i];
        const char *qn = ctx->import_module_qns[i];
        if (!local || !qn || strcmp(local, local_name) != 0 ||
            !py_import_index_is_from_binding(ctx, i)) {
            continue;
        }
        if (candidate && strcmp(candidate, qn) != 0)
            return NULL;
        candidate = qn;
    }
    return candidate;
}

/* Return one graph target only for an expression whose callable identity is
 * statically exact. Complex containers/conditionals deliberately return NULL
 * so their constituent function names stay ordinary USAGE. */
/* `occurrence_out` receives the node the callable name actually occupies after
 * parentheses are stripped, so a caller can record the reference at the same
 * occurrence the usage carrier uses. `lexical_alias_out` reports that the name
 * was proven through a lexical binding rather than a module symbol -- see
 * py_resolve_value_references_at for why that distinction decides a strategy.
 * Both are optional. */
static const char *py_exact_callable_target_ex(PyLSPContext *ctx, TSNode node,
                                               TSNode *occurrence_out, bool *lexical_alias_out) {
    if (lexical_alias_out)
        *lexical_alias_out = false;
    if (!ctx || ctx->callable_value_proof_disabled || ts_node_is_null(node))
        return NULL;

    /* Parentheses do not change callable identity. Unwrap them iteratively:
     * an assignment such as `fn = (((target)))` reaches this helper after
     * expression-type inference, and adversarial nesting must not consume one
     * native stack frame per parenthesized_expression. */
    const char *kind = ts_node_type(node);
    while (strcmp(kind, "parenthesized_expression") == 0 && ts_node_named_child_count(node) == 1) {
        node = ts_node_named_child(node, 0);
        kind = ts_node_type(node);
    }
    if (occurrence_out)
        *occurrence_out = node;
    if (strcmp(kind, "identifier") == 0) {
        char *name = py_node_text(ctx, node);
        if (!name)
            return NULL;
        const CBMVarBinding *binding = cbm_scope_lookup_binding(ctx->current_scope, name);
        if (binding) {
            const char *bound = binding->callable_qn;
            if (bound && lexical_alias_out) {
                /* A lexical binding that does NOT simply name the module symbol
                 * of the same spelling is an alias introduced in this body. Only
                 * that case may claim the alias strategy; a module function
                 * referenced by its own name keeps the plain value-reference
                 * strategy it has always had. */
                const CBMRegisteredFunc *module_symbol =
                    cbm_registry_lookup_symbol(ctx->registry, ctx->module_qn, name);
                *lexical_alias_out = !module_symbol || !module_symbol->qualified_name ||
                                     strcmp(module_symbol->qualified_name, bound) != 0;
            }
            return bound;
        }
        const CBMRegisteredFunc *f =
            cbm_registry_lookup_symbol(ctx->registry, ctx->module_qn, name);
        return py_func_is_exact_callable_value(f) ? f->qualified_name : NULL;
    }
    if (strcmp(kind, "attribute") == 0) {
        TSNode object = ts_node_child_by_field_name(node, "object", 6);
        TSNode attribute = ts_node_child_by_field_name(node, "attribute", 9);
        if (ts_node_is_null(object) || ts_node_is_null(attribute))
            return NULL;
        char *member = py_node_text(ctx, attribute);
        const CBMType *receiver = py_eval_expr_type(ctx, object);
        if (!member || !receiver)
            return NULL;
        receiver = cbm_type_resolve_alias(receiver);
        if (receiver->kind == CBM_TYPE_MODULE) {
            const CBMRegisteredFunc *f =
                py_module_member(ctx, receiver->data.module.module_qn, member).func;
            return py_func_is_exact_callable_value(f) ? f->qualified_name : NULL;
        }
        if (receiver->kind == CBM_TYPE_NAMED) {
            /* Instance fields shadow class methods. Without an exact callable
             * identity for the field value, promoting the same-named method
             * would fabricate a callable target. */
            if (py_lookup_field(ctx, receiver->data.named.qualified_name, member))
                return NULL;
            const CBMRegisteredFunc *f =
                py_lookup_attribute(ctx, receiver->data.named.qualified_name, member);
            return py_func_is_exact_callable_value(f) ? f->qualified_name : NULL;
        }
    }
    return NULL;
}

static void py_resolve_value_references_at(PyLSPContext *ctx, TSNode call) {
    if (!ctx || ctx->callable_value_proof_disabled)
        return;
    TSNode args = ts_node_child_by_field_name(call, "arguments", 9);
    if (ts_node_is_null(args))
        return;
    uint32_t count = ts_node_named_child_count(args);
    for (uint32_t i = 0; i < count; i++) {
        TSNode arg = ts_node_named_child(args, i);
        if (strcmp(ts_node_type(arg), "keyword_argument") == 0) {
            arg = ts_node_child_by_field_name(arg, "value", 5);
            if (ts_node_is_null(arg))
                continue;
        }
        const char *kind = ts_node_type(arg);
        if (strcmp(kind, "identifier") != 0 && strcmp(kind, "attribute") != 0 &&
            strcmp(kind, "parenthesized_expression") != 0)
            continue;
        bool lexical_alias = false;
        const char *target = py_exact_callable_target_ex(ctx, arg, NULL, &lexical_alias);
        char *source_name = py_node_text(ctx, arg);
        if (target) {
            /* `arg` is the outermost direct-argument node, parentheses included,
             * which is the occurrence the usage carrier also reports. */
            py_emit_resolved_reference(ctx, target, source_name, arg,
                                       lexical_alias ? "lsp_callable_alias"
                                                     : "lsp_callable_value_reference");
            continue;
        }
        const char *candidate = strcmp(kind, "identifier") == 0
                                    ? py_exact_imported_reference_candidate(ctx, source_name)
                                    : NULL;
        const CBMVarBinding *scope_binding =
            candidate ? cbm_scope_lookup_binding(ctx->current_scope, source_name) : NULL;
        if (scope_binding) {
            const CBMType *type = cbm_type_resolve_alias(scope_binding->type);
            if (type && type->kind == CBM_TYPE_NAMED && type->data.named.qualified_name &&
                strcmp(type->data.named.qualified_name, candidate) == 0) {
                py_emit_unresolved_reference(ctx, candidate, arg);
            }
        }
    }
}

/* ── helpers: registry-driven attribute lookup with depth cap ──── */

static const CBMRegisteredFunc *py_lookup_attribute_depth(PyLSPContext *ctx, const char *type_qn,
                                                          const char *member_name, int depth) {
    if (!ctx || !type_qn || !member_name)
        return NULL;
    if (depth > CBM_LSP_MAX_LOOKUP_DEPTH)
        return NULL;

    const CBMRegisteredFunc *f = cbm_registry_lookup_method(ctx->registry, type_qn, member_name);
    if (f)
        return f;

    const CBMRegisteredType *rt = cbm_registry_lookup_type(ctx->registry, type_qn);
    if (rt) {
        if (rt->alias_of) {
            f = py_lookup_attribute_depth(ctx, rt->alias_of, member_name, depth + 1);
            if (f)
                return f;
        }
        if (rt->embedded_types) {
            for (int i = 0; rt->embedded_types[i]; i++) {
                f = py_lookup_attribute_depth(ctx, rt->embedded_types[i], member_name, depth + 1);
                if (f)
                    return f;
            }
        }
    }
    return NULL;
}

static PyModuleMember py_module_member_exact(PyLSPContext *ctx, const char *module_qn,
                                             const char *name) {
    PyModuleMember m = {0};
    m.func = cbm_registry_lookup_symbol(ctx->registry, module_qn, name);
    if (m.func)
        return m;
    const char *qn = cbm_arena_sprintf(ctx->arena, "%s.%s", module_qn, name);
    m.type = qn ? cbm_registry_lookup_type(ctx->registry, qn) : NULL;
    if (m.type)
        return m;
    /* Re-export: `module.name` is bound by the module's imports (the export
     * table the cross registry materialized once, before its seal), keyed by
     * the module symbol scope (a package without its `.__init__`). */
    size_t scope_len = cbm_fqn_symbol_scope_len(module_qn);
    const char *scope =
        module_qn[scope_len] ? cbm_arena_strndup(ctx->arena, module_qn, scope_len) : module_qn;
    const char *target = scope ? cbm_registry_lookup_export(ctx->registry, scope, name) : NULL;
    if (target) {
        m.func = cbm_registry_lookup_func(ctx->registry, target);
        if (!m.func)
            m.type = cbm_registry_lookup_type(ctx->registry, target);
    }
    return m;
}

/* `prefix.module_qn`, or NULL when module_qn already starts with prefix. */
static const char *py_qualify_module(PyLSPContext *ctx, const char *prefix, size_t prefix_len,
                                     const char *module_qn) {
    if (prefix_len == 0 ||
        (strncmp(module_qn, prefix, prefix_len) == 0 && module_qn[prefix_len] == '.'))
        return NULL;
    return cbm_arena_sprintf(ctx->arena, "%.*s.%s", (int)prefix_len, prefix, module_qn);
}

/* An in-project `import sibling` / `import pkg` binds the module by its
 * source spelling ("pkg"), while its defs are registered project-qualified.
 * Try the spelling as written, then qualified by the importing file's
 * package, then by the project root (the file module's first segment). */
static PyModuleMember py_module_member(PyLSPContext *ctx, const char *module_qn, const char *name) {
    PyModuleMember none = {0};
    if (!ctx || !ctx->registry || !module_qn || !name)
        return none;
    PyModuleMember m = py_module_member_exact(ctx, module_qn, name);
    if (m.func || m.type || !ctx->file_module_qn)
        return m;
    const char *file_mod = ctx->file_module_qn;
    const char *last_dot = strrchr(file_mod, '.');
    const char *first_dot = strchr(file_mod, '.');
    if (last_dot && last_dot > file_mod) {
        const char *qual =
            py_qualify_module(ctx, file_mod, (size_t)(last_dot - file_mod), module_qn);
        m = qual ? py_module_member_exact(ctx, qual, name) : none;
        if (m.func || m.type)
            return m;
    }
    if (first_dot && first_dot != last_dot) {
        const char *qual =
            py_qualify_module(ctx, file_mod, (size_t)(first_dot - file_mod), module_qn);
        m = qual ? py_module_member_exact(ctx, qual, name) : none;
    }
    return m;
}

/* Emit a call resolved through a module namespace. A re-export may bind the
 * definition under another name (`from .x import Orig as Renamed`): that is
 * an import alias, whose join reads the written name from `reason`. */
static void py_emit_module_member_call(PyLSPContext *ctx, const char *callee_qn,
                                       const char *strategy, float confidence,
                                       const char *written_name, TSNode site) {
    const char *dot = strrchr(callee_qn, '.');
    const char *short_name = dot ? dot + 1 : callee_qn;
    if (strcmp(short_name, written_name) != 0) {
        py_emit_resolved_call_reason(ctx, callee_qn, "lsp_import_alias", confidence, written_name,
                                     site);
    } else {
        py_emit_resolved_call(ctx, callee_qn, strategy, confidence, site);
    }
}

/* ── The C3 method resolution order ──────────────────────────────── */

/* Longest linearization followed. A longer one (or more bases than this) keeps
 * the depth-first walk above. */
#define PY_C3_MAX 64

enum { PY_MRO_CACHE_INITIAL_CAP = 64 };  /* power of two (index masking) */
enum { PY_MRO_CACHE_MAX_CAP = 1 << 20 }; /* hard stop for adversarial files */

static uint32_t py_mro_hash(const char *qn) {
    uint32_t h = 2166136261u; /* FNV-1a */
    for (const unsigned char *p = (const unsigned char *)qn; *p; p++) {
        h = (h ^ *p) * 16777619u;
    }
    return h;
}

static const CBMPyMroCacheEntry *py_mro_cache_find(const PyLSPContext *ctx, const char *qn,
                                                   uint32_t h) {
    if (!ctx->mro_cache || ctx->mro_cache_cap == 0)
        return NULL;
    uint32_t mask = (uint32_t)ctx->mro_cache_cap - 1;
    uint32_t idx = h & mask;
    for (int probed = 0; probed < ctx->mro_cache_cap; probed++) {
        const CBMPyMroCacheEntry *e = &ctx->mro_cache[idx];
        if (!e->qn)
            return NULL;
        if (e->hash == h && strcmp(e->qn, qn) == 0)
            return e;
        idx = (idx + 1) & mask;
    }
    return NULL;
}

/* Doubles the table (arena allocation: the old table is freed with the
 * per-file arena). */
static bool py_mro_cache_grow(PyLSPContext *ctx) {
    if (ctx->mro_cache_cap >= PY_MRO_CACHE_MAX_CAP)
        return false;
    int new_cap = ctx->mro_cache_cap ? ctx->mro_cache_cap * 2 : PY_MRO_CACHE_INITIAL_CAP;
    CBMPyMroCacheEntry *entries = (CBMPyMroCacheEntry *)cbm_arena_alloc(
        ctx->arena, (size_t)new_cap * sizeof(CBMPyMroCacheEntry));
    if (!entries)
        return false;
    memset(entries, 0, (size_t)new_cap * sizeof(CBMPyMroCacheEntry));
    uint32_t mask = (uint32_t)new_cap - 1;
    for (int i = 0; i < ctx->mro_cache_cap; i++) {
        const CBMPyMroCacheEntry *e = &ctx->mro_cache[i];
        if (!e->qn)
            continue;
        uint32_t idx = e->hash & mask;
        while (entries[idx].qn)
            idx = (idx + 1) & mask;
        entries[idx] = *e;
    }
    ctx->mro_cache = entries;
    ctx->mro_cache_cap = new_cap;
    return true;
}

/* Records the order of `qn` (len -1: none). A table that cannot grow only
 * costs a recomputation later. */
static void py_mro_cache_put(PyLSPContext *ctx, const char *qn, uint32_t h, const char **mro,
                             int len) {
    if ((ctx->mro_cache_count + 1) * 4 > ctx->mro_cache_cap * 3 && !py_mro_cache_grow(ctx))
        return;
    const char *key = cbm_arena_strdup(ctx->arena, qn);
    if (!key)
        return;
    uint32_t mask = (uint32_t)ctx->mro_cache_cap - 1;
    uint32_t idx = h & mask;
    while (ctx->mro_cache[idx].qn)
        idx = (idx + 1) & mask;
    ctx->mro_cache[idx].qn = key;
    ctx->mro_cache[idx].hash = h;
    ctx->mro_cache[idx].len = len;
    ctx->mro_cache[idx].mro = mro;
    ctx->mro_cache_count++;
}

static bool py_c3_in_tail(const char *qn, const char *const *seq, int head, int len) {
    for (int k = head + 1; k < len; k++) {
        if (strcmp(seq[k], qn) == 0)
            return true;
    }
    return false;
}

/* The C3 head to take next: the first sequence head that is in no sequence's
 * tail. NULL when every head is blocked (Python rejects such a class). */
static const char *py_c3_pick(const char **const *seqs, const int *lens, const int *heads,
                              int nseq) {
    for (int s = 0; s < nseq; s++) {
        if (heads[s] >= lens[s])
            continue;
        const char *cand = seqs[s][heads[s]];
        bool blocked = false;
        for (int t = 0; t < nseq && !blocked; t++) {
            blocked = heads[t] < lens[t] && py_c3_in_tail(cand, seqs[t], heads[t], lens[t]);
        }
        if (!blocked)
            return cand;
    }
    return NULL;
}

/* The C3 merge of `nseq` sequences into mro[1..]: returns the order's length,
 * or -1 when there is none or it is longer than PY_C3_MAX. */
static int py_c3_merge(const char **const *seqs, const int *lens, int *heads, int nseq,
                       const char **mro) {
    int n = 1;
    for (;;) {
        bool pending = false;
        for (int s = 0; s < nseq && !pending; s++) {
            pending = heads[s] < lens[s];
        }
        if (!pending)
            return n;
        const char *pick = py_c3_pick(seqs, lens, heads, nseq);
        if (!pick || n >= PY_C3_MAX)
            return -1;
        mro[n++] = pick;
        for (int s = 0; s < nseq; s++) {
            if (heads[s] < lens[s] && strcmp(seqs[s][heads[s]], pick) == 0)
                heads[s]++;
        }
    }
}

/* Python's method resolution order of `type_qn`: the class, then the C3 merge
 * of its bases' linearizations and of the base list. A common base therefore
 * follows every class deriving from it. Computed once per class and file
 * (ctx->mro_cache). Sets *out to an arena array and returns its length, or -1
 * when there is no C3 order, the hierarchy is deeper than
 * CBM_LSP_MAX_LOOKUP_DEPTH, or the order is longer than PY_C3_MAX. A base the
 * registry does not know (external, unresolved) linearizes to itself. Only an
 * order computed from the top (depth 0) is cached as missing: below it, the
 * depth cap may have cut a hierarchy that is fine on its own. */
static int py_c3_linearize(PyLSPContext *ctx, const char *type_qn, const char ***out, int depth) {
    uint32_t h = py_mro_hash(type_qn);
    const CBMPyMroCacheEntry *hit = py_mro_cache_find(ctx, type_qn, h);
    if (hit) {
        *out = hit->mro;
        return hit->len;
    }
    int n = -1;
    const char **mro = NULL;
    const CBMRegisteredType *rt =
        depth <= CBM_LSP_MAX_LOOKUP_DEPTH ? cbm_registry_lookup_type(ctx->registry, type_qn) : NULL;
    const char **bases = rt ? rt->embedded_types : NULL;
    int nb = 0;
    while (bases && bases[nb])
        nb++;
    if (depth > CBM_LSP_MAX_LOOKUP_DEPTH || nb >= PY_C3_MAX) {
        n = -1;
    } else if (rt && rt->alias_of) {
        n = py_c3_linearize(ctx, rt->alias_of, &mro, depth + 1);
    } else {
        const char ***seqs =
            (const char ***)cbm_arena_alloc(ctx->arena, (size_t)(nb + 1) * sizeof(const char **));
        int *lens = (int *)cbm_arena_alloc(ctx->arena, (size_t)(nb + 1) * 2 * sizeof(int));
        mro = (const char **)cbm_arena_alloc(ctx->arena, PY_C3_MAX * sizeof(const char *));
        bool ok = seqs && lens && mro;
        int *heads = lens ? lens + nb + 1 : NULL;
        for (int b = 0; ok && b < nb; b++) {
            lens[b] = py_c3_linearize(ctx, bases[b], &seqs[b], depth + 1);
            heads[b] = 0;
            ok = lens[b] >= 0;
        }
        if (ok) {
            seqs[nb] = bases;
            lens[nb] = nb;
            heads[nb] = 0;
            mro[0] = cbm_arena_strdup(ctx->arena, type_qn);
            n = mro[0] ? py_c3_merge((const char **const *)seqs, lens, heads, nb + 1, mro) : -1;
        }
    }
    if (n >= 0 || depth == 0)
        py_mro_cache_put(ctx, type_qn, h, n >= 0 ? mro : NULL, n);
    *out = n >= 0 ? mro : NULL;
    return n;
}

/* Attribute lookup along the class's C3 order: the class itself, then each
 * class of its order that declares the member. A hierarchy without a C3 order
 * keeps the depth-first walk. */
static const CBMRegisteredFunc *py_lookup_attribute(PyLSPContext *ctx, const char *type_qn,
                                                    const char *member_name) {
    if (!ctx || !type_qn || !member_name)
        return NULL;
    const CBMRegisteredFunc *f = cbm_registry_lookup_method(ctx->registry, type_qn, member_name);
    if (f)
        return f;
    const char **mro = NULL;
    int n = py_c3_linearize(ctx, type_qn, &mro, 0);
    if (n < 0)
        return py_lookup_attribute_depth(ctx, type_qn, member_name, 0);
    /* mro[0] is the class itself, already asked, or an alias's target. */
    for (int i = strcmp(mro[0], type_qn) == 0 ? 1 : 0; i < n; i++) {
        f = cbm_registry_lookup_method(ctx->registry, mro[i], member_name);
        if (f)
            return f;
    }
    return NULL;
}

/* The method super() reaches from inside `class_qn`: the first class AFTER it in
 * its C3 order that declares `member` itself. *have_mro is false when the
 * hierarchy has no C3 order; the caller then keeps its base-by-base walk. */
static const CBMRegisteredFunc *py_lookup_super_attribute(PyLSPContext *ctx, const char *class_qn,
                                                          const char *member, bool *have_mro) {
    *have_mro = false;
    if (!ctx || !class_qn || !member)
        return NULL;
    const char **mro = NULL;
    int n = py_c3_linearize(ctx, class_qn, &mro, 0);
    if (n < 0)
        return NULL;
    *have_mro = true;
    for (int i = 1; i < n; i++) {
        const CBMRegisteredFunc *f = cbm_registry_lookup_method(ctx->registry, mro[i], member);
        if (f)
            return f;
    }
    return NULL;
}

/* Per-file field overlay: look up a (class_qn, field_name) recorded during resolve
 * against the sealed shared registry. Linear scan — the overlay only holds fields
 * discovered in THIS file's own classes, so it is small. */
static const CBMType *py_overlay_lookup_field(const PyLSPContext *ctx, const char *class_qn,
                                              const char *field_name) {
    for (int i = 0; i < ctx->field_overlay_count; i++) {
        if (strcmp(ctx->field_overlay[i].class_qn, class_qn) == 0 &&
            strcmp(ctx->field_overlay[i].field_name, field_name) == 0)
            return ctx->field_overlay[i].field_type;
    }
    return NULL;
}

/* Record a (class_qn, field_name) -> field_type in the per-file overlay. Overwrites
 * an existing entry (mirrors the direct-mutation overwrite semantics). Arena-backed;
 * grows by copy. class_qn/field_name are arena-dup'd so the entry never borrows a
 * transient node-text buffer. */
static void py_overlay_register_field(PyLSPContext *ctx, const char *class_qn,
                                      const char *field_name, const CBMType *field_type) {
    for (int i = 0; i < ctx->field_overlay_count; i++) {
        if (strcmp(ctx->field_overlay[i].class_qn, class_qn) == 0 &&
            strcmp(ctx->field_overlay[i].field_name, field_name) == 0) {
            ctx->field_overlay[i].field_type = field_type;
            return;
        }
    }
    if (ctx->field_overlay_count >= ctx->field_overlay_cap) {
        int new_cap = ctx->field_overlay_cap == 0 ? 16 : ctx->field_overlay_cap * 2;
        void *na = cbm_arena_alloc(ctx->arena, (size_t)new_cap * sizeof(*ctx->field_overlay));
        if (!na) {
            py_disable_callable_value_proof(ctx);
            return;
        }
        if (ctx->field_overlay && ctx->field_overlay_count > 0)
            memcpy(na, ctx->field_overlay,
                   (size_t)ctx->field_overlay_count * sizeof(*ctx->field_overlay));
        ctx->field_overlay = na;
        ctx->field_overlay_cap = new_cap;
    }
    const char *stored_class = cbm_arena_strdup(ctx->arena, class_qn);
    const char *stored_field = cbm_arena_strdup(ctx->arena, field_name);
    if (!stored_class || !stored_field) {
        py_disable_callable_value_proof(ctx);
        return;
    }
    ctx->field_overlay[ctx->field_overlay_count].class_qn = stored_class;
    ctx->field_overlay[ctx->field_overlay_count].field_name = stored_field;
    ctx->field_overlay[ctx->field_overlay_count].field_type = field_type;
    ctx->field_overlay_count++;
}

/* Look up a field on a registered type. Walks alias / embedded chain
 * with the same depth cap as method lookup. Returns the field's type
 * or NULL if no match. */
static const CBMType *py_lookup_field_depth(PyLSPContext *ctx, const char *type_qn,
                                            const char *field_name, int depth) {
    if (!ctx || !ctx->registry || !type_qn || !field_name)
        return NULL;
    if (depth > CBM_LSP_MAX_LOOKUP_DEPTH)
        return NULL;

    const CBMRegisteredType *rt = cbm_registry_lookup_type(ctx->registry, type_qn);
    if (!rt)
        return NULL;
    if (rt->field_names && rt->field_types) {
        for (int i = 0; rt->field_names[i]; i++) {
            if (strcmp(rt->field_names[i], field_name) == 0) {
                return rt->field_types[i];
            }
        }
    }
    /* Per-file overlay: `self.x = ...` fields discovered during resolve against the
     * sealed shared registry live here (not on rt). Checked at the same point the
     * direct field scan would have found them in the mutable path — preserving the
     * derived-shadows-base precedence before recursing into alias/base classes. */
    {
        const CBMType *ov = py_overlay_lookup_field(ctx, type_qn, field_name);
        if (ov)
            return ov;
    }
    if (rt->alias_of) {
        const CBMType *a = py_lookup_field_depth(ctx, rt->alias_of, field_name, depth + 1);
        if (a)
            return a;
    }
    if (rt->embedded_types) {
        for (int i = 0; rt->embedded_types[i]; i++) {
            const CBMType *e =
                py_lookup_field_depth(ctx, rt->embedded_types[i], field_name, depth + 1);
            if (e)
                return e;
        }
    }
    return NULL;
}

static const CBMType *py_lookup_field(PyLSPContext *ctx, const char *type_qn,
                                      const char *field_name) {
    return py_lookup_field_depth(ctx, type_qn, field_name, 0);
}

/* Append a (name, type) entry to a registered class's field arrays.
 * Idempotent — re-registering the same name overwrites the existing
 * entry. Mutates the array in place by allocating a new (slightly
 * larger) array on each call; not a hot path so the cost is acceptable. */
static void py_register_instance_field(PyLSPContext *ctx, const char *class_qn,
                                       const char *field_name, const CBMType *field_type) {
    if (!ctx || !ctx->registry || !class_qn || !field_name || !field_type)
        return;

    /* Shared Tier-2 registry is finalized + sealed (read_only) and read concurrently
     * by all resolve workers. Writing its type entries directly below would bypass the
     * add_* seal, race the other workers, and leave the shared entry pointing into
     * this file's resolve arena (freed when the file completes). Route the discovery
     * to the per-file overlay instead; py_lookup_field consults it alongside the
     * shared base, so same-file `self.x`/PEP-526 resolution is preserved with zero
     * shared mutation. Mutable per-file registries (read_only == false) keep the
     * byte-identical direct write below. */
    if (ctx->registry->read_only) {
        py_overlay_register_field(ctx, class_qn, field_name, field_type);
        return;
    }

    // The writable entry for the class: the head's own, or a copy of the
    // base entry made in the head (copy-on-write). The shared base is never
    // written -- it used to be, from every parallel resolve worker.
    CBMRegisteredType *rt = cbm_registry_type_for_update(ctx->registry_head, class_qn);
    if (!rt)
        return;

    // Overwrite if name already registered.
    if (rt->field_names && rt->field_types) {
        for (int i = 0; rt->field_names[i]; i++) {
            if (strcmp(rt->field_names[i], field_name) == 0) {
                ((const CBMType **)rt->field_types)[i] = field_type;
                return;
            }
        }
    }

    int existing = 0;
    if (rt->field_names) {
        while (rt->field_names[existing])
            existing++;
    }
    int new_count = existing + 1;
    const char **new_names =
        (const char **)cbm_arena_alloc(ctx->arena, (size_t)(new_count + 1) * sizeof(const char *));
    const CBMType **new_types = (const CBMType **)cbm_arena_alloc(
        ctx->arena, (size_t)(new_count + 1) * sizeof(const CBMType *));
    if (!new_names || !new_types)
        return;
    for (int i = 0; i < existing; i++) {
        new_names[i] = rt->field_names[i];
        new_types[i] = rt->field_types[i];
    }
    new_names[existing] = cbm_arena_strdup(ctx->arena, field_name);
    new_types[existing] = field_type;
    new_names[new_count] = NULL;
    new_types[new_count] = NULL;
    rt->field_names = new_names;
    rt->field_types = new_types;
}

/* ── expression typing ────────────────────────────────────────── */

/* Map a tree-sitter Python literal node to a BUILTIN type. Returns NULL if
 * the node isn't a simple literal. */
static const CBMType *py_literal_type(PyLSPContext *ctx, TSNode node) {
    const char *k = ts_node_type(node);
    if (strcmp(k, "integer") == 0)
        return cbm_type_builtin(ctx->arena, "int");
    if (strcmp(k, "float") == 0)
        return cbm_type_builtin(ctx->arena, "float");
    if (strcmp(k, "string") == 0)
        return cbm_type_builtin(ctx->arena, "str");
    if (strcmp(k, "concatenated_string") == 0)
        return cbm_type_builtin(ctx->arena, "str");
    if (strcmp(k, "true") == 0 || strcmp(k, "false") == 0)
        return cbm_type_builtin(ctx->arena, "bool");
    if (strcmp(k, "none") == 0)
        return cbm_type_builtin(ctx->arena, "None");
    // tuple / list / set / dict are handled separately by py_eval_expr_type
    // so it can build structured TUPLE / TEMPLATE types from element
    // types. Only fall through to BUILTIN here for empty literals.
    if (strcmp(k, "list_comprehension") == 0)
        return cbm_type_builtin(ctx->arena, "list");
    if (strcmp(k, "dictionary_comprehension") == 0)
        return cbm_type_builtin(ctx->arena, "dict");
    if (strcmp(k, "set_comprehension") == 0)
        return cbm_type_builtin(ctx->arena, "set");
    if (strcmp(k, "generator_expression") == 0)
        return cbm_type_builtin(ctx->arena, "generator");
    return NULL;
}

/* Substitute "Self" / "typing.Self" return types with the receiver type.
 * Walks the type recursively so `Optional[Self]` becomes `Optional[R]`. */
static const CBMType *py_substitute_self(PyLSPContext *ctx, const CBMType *t,
                                         const char *receiver_qn) {
    if (!t || !receiver_qn)
        return t;
    if (t->kind == CBM_TYPE_NAMED && t->data.named.qualified_name) {
        const char *qn = t->data.named.qualified_name;
        if (strcmp(qn, "Self") == 0 || strcmp(qn, "typing.Self") == 0 ||
            strcmp(qn, "typing_extensions.Self") == 0) {
            return cbm_type_named(ctx->arena, receiver_qn);
        }
    }
    if (t->kind == CBM_TYPE_UNION) {
        int n = t->data.union_type.count;
        const CBMType **members = (const CBMType **)cbm_arena_alloc(
            ctx->arena, (size_t)(n + 1) * sizeof(const CBMType *));
        if (!members)
            return t;
        for (int i = 0; i < n; i++) {
            members[i] = py_substitute_self(ctx, t->data.union_type.members[i], receiver_qn);
        }
        return cbm_type_union(ctx->arena, members, n);
    }
    return t;
}

/* If `func_qn` is a registered function, return its return type. When
 * called on a receiver, pass receiver_qn to substitute Self return
 * types; pass NULL otherwise. */
static const CBMType *py_func_return_type_recv(PyLSPContext *ctx, const char *func_qn,
                                               const char *receiver_qn) {
    if (!ctx || !func_qn)
        return cbm_type_unknown();
    const CBMRegisteredFunc *f = cbm_registry_lookup_func(ctx->registry, func_qn);
    if (!f || !f->signature)
        return cbm_type_unknown();
    if (f->signature->kind != CBM_TYPE_FUNC)
        return cbm_type_unknown();
    const CBMType **rets = f->signature->data.func.return_types;
    if (!rets || !rets[0])
        return cbm_type_unknown();
    const CBMType *base;
    if (!rets[1]) {
        base = rets[0];
    } else {
        int count = 0;
        while (rets[count])
            count++;
        base = cbm_type_tuple(ctx->arena, rets, count);
    }
    if (receiver_qn) {
        return py_substitute_self(ctx, base, receiver_qn);
    }
    return base;
}

/* Convenience wrapper: no receiver substitution. */
static const CBMType *py_func_return_type(PyLSPContext *ctx, const char *func_qn) {
    return py_func_return_type_recv(ctx, func_qn, NULL);
}

/* Element type of an iterable. For TEMPLATE("list"|"set"|"Iterable"|...,
 * [T]), return T. For TEMPLATE("dict", [K, V]) — `for x in d` iterates
 * keys, return K. For TEMPLATE("tuple", [A, B, ...]) return UNION(A, B,
 * ...) since `for x in (a, b)` yields heterogeneous types. dict_items /
 * ItemsView return tuple[K, V] so unpacking works. NAMED("list") with
 * no template args -> UNKNOWN. */
/* Bind a `for X in ...` target. Supports identifier (single binding) and
 * pattern_list / tuple_pattern (destructure tuple element type). */
static void py_bind_for_target(PyLSPContext *ctx, TSNode left, const CBMType *elem_type) {
    if (ts_node_is_null(left) || !ctx)
        return;
    const char *lk = ts_node_type(left);
    if (strcmp(lk, "identifier") == 0) {
        char *name = py_node_text(ctx, left);
        if (name)
            py_scope_bind(ctx, name, elem_type);
        return;
    }
    if (strcmp(lk, "pattern_list") == 0 || strcmp(lk, "tuple_pattern") == 0 ||
        strcmp(lk, "list_pattern") == 0) {
        // Destructure tuple element type element-by-element.
        const CBMType *const *elems = NULL;
        int count = 0;
        if (elem_type) {
            if (elem_type->kind == CBM_TYPE_TUPLE) {
                elems = elem_type->data.tuple.elems;
                count = elem_type->data.tuple.count;
            } else if (elem_type->kind == CBM_TYPE_TEMPLATE &&
                       elem_type->data.template_type.template_name &&
                       strcmp(elem_type->data.template_type.template_name, "tuple") == 0) {
                elems = elem_type->data.template_type.template_args;
                count = elem_type->data.template_type.arg_count;
            }
        }
        uint32_t lc = ts_node_named_child_count(left);
        for (uint32_t i = 0; i < lc; i++) {
            TSNode tgt = ts_node_named_child(left, i);
            if (ts_node_is_null(tgt))
                continue;
            const char *tk = ts_node_type(tgt);
            if (strcmp(tk, "identifier") == 0) {
                char *nm = py_node_text(ctx, tgt);
                if (!nm)
                    continue;
                const CBMType *bind_type;
                if (elems && (int)i < count && elems[i])
                    bind_type = elems[i];
                else
                    bind_type = cbm_type_unknown();
                py_scope_bind(ctx, nm, bind_type);
            }
        }
    }
}

static const CBMType *py_iterable_element_type(PyLSPContext *ctx, const CBMType *iter_type) {
    if (!iter_type)
        return cbm_type_unknown();
    if (iter_type->kind == CBM_TYPE_TEMPLATE) {
        const char *name = iter_type->data.template_type.template_name;
        const CBMType **args = iter_type->data.template_type.template_args;
        int n = iter_type->data.template_type.arg_count;
        if (!name || n <= 0 || !args)
            return cbm_type_unknown();
        if (strcmp(name, "list") == 0 || strcmp(name, "set") == 0 ||
            strcmp(name, "frozenset") == 0 || strcmp(name, "Iterable") == 0 ||
            strcmp(name, "Iterator") == 0 || strcmp(name, "Sequence") == 0 ||
            strcmp(name, "MutableSequence") == 0 || strcmp(name, "AsyncIterable") == 0 ||
            strcmp(name, "AsyncIterator") == 0 || strcmp(name, "Generator") == 0 ||
            strcmp(name, "AsyncGenerator") == 0 || strcmp(name, "Reversible") == 0 ||
            strcmp(name, "Collection") == 0 || strcmp(name, "Container") == 0 ||
            strcmp(name, "deque") == 0 || strcmp(name, "KeysView") == 0 ||
            strcmp(name, "ValuesView") == 0 || strcmp(name, "dict_keys") == 0 ||
            strcmp(name, "dict_values") == 0) {
            return args[0];
        }
        if (strcmp(name, "ItemsView") == 0 || strcmp(name, "dict_items") == 0) {
            // Iterating ItemsView[K, V] yields tuple[K, V].
            if (n >= 2) {
                const CBMType *elems[3] = {args[0], args[1], NULL};
                return cbm_type_tuple(ctx->arena, elems, 2);
            }
            return cbm_type_unknown();
        }
        if (strcmp(name, "dict") == 0 || strcmp(name, "Mapping") == 0 ||
            strcmp(name, "MutableMapping") == 0 || strcmp(name, "defaultdict") == 0 ||
            strcmp(name, "OrderedDict") == 0) {
            // `for k in d` iterates keys.
            return args[0];
        }
        if (strcmp(name, "tuple") == 0) {
            if (n == 1)
                return args[0];
            return cbm_type_union(ctx->arena, args, n);
        }
        // Other generics: best-effort take first arg.
        return args[0];
    }
    return cbm_type_unknown();
}

/* The real recursive-descent evaluator. Never call directly — go through
 * the memoizing, depth-guarded py_eval_expr_type wrapper below
 * (every recursive call inside this body already does). */
/* Existing function-only submodule predicate, after exact symbol/type misses. */
static bool py_names_submodule(PyLSPContext *ctx, const char *qn) {
    const char *prefix = qn ? cbm_arena_sprintf(ctx->arena, "%s.", qn) : NULL;
    if (!prefix)
        return false;
#ifdef CBM_ENABLE_TEST_SEAMS
    uint64_t visits = 0;
    bool found = cbm_registry_has_func_qn_prefix(ctx->registry, prefix, &visits);
    atomic_fetch_add_explicit(&cbm_py_submodule_probes, 1, memory_order_relaxed);
    atomic_fetch_add_explicit(&cbm_py_submodule_probe_visits, visits, memory_order_relaxed);
    return found;
#else
    return cbm_registry_has_func_qn_prefix(ctx->registry, prefix, NULL);
#endif
}

static const CBMType *py_eval_expr_type_uncached(PyLSPContext *ctx, TSNode node) {
    if (!ctx || ts_node_is_null(node))
        return cbm_type_unknown();

    const CBMType *lit = py_literal_type(ctx, node);
    if (lit)
        return lit;

    const char *k = ts_node_type(node);

    // Tuple / list / set / dict literals: build structured types from
    // element types so unpacking and indexing work without losing
    // precision. py_literal_type returns BUILTIN — we override here.
    if (strcmp(k, "tuple") == 0) {
        uint32_t cn = ts_node_named_child_count(node);
        if (cn == 0)
            return cbm_type_builtin(ctx->arena, "tuple");
        const CBMType **elems = (const CBMType **)cbm_arena_alloc(
            ctx->arena, (size_t)(cn + 1) * sizeof(const CBMType *));
        if (!elems)
            return cbm_type_builtin(ctx->arena, "tuple");
        for (uint32_t i = 0; i < cn; i++) {
            elems[i] = py_eval_expr_type(ctx, ts_node_named_child(node, i));
        }
        elems[cn] = NULL;
        return cbm_type_tuple(ctx->arena, elems, (int)cn);
    }
    if (strcmp(k, "list") == 0) {
        uint32_t cn = ts_node_named_child_count(node);
        if (cn == 0)
            return cbm_type_builtin(ctx->arena, "list");
        const CBMType *first = py_eval_expr_type(ctx, ts_node_named_child(node, 0));
        if (!first || cbm_type_is_unknown(first))
            return cbm_type_builtin(ctx->arena, "list");
        return cbm_type_template(ctx->arena, "list", &first, 1);
    }
    if (strcmp(k, "set") == 0) {
        uint32_t cn = ts_node_named_child_count(node);
        if (cn == 0)
            return cbm_type_builtin(ctx->arena, "set");
        const CBMType *first = py_eval_expr_type(ctx, ts_node_named_child(node, 0));
        if (!first || cbm_type_is_unknown(first))
            return cbm_type_builtin(ctx->arena, "set");
        return cbm_type_template(ctx->arena, "set", &first, 1);
    }
    if (strcmp(k, "dictionary") == 0) {
        uint32_t cn = ts_node_named_child_count(node);
        if (cn == 0)
            return cbm_type_builtin(ctx->arena, "dict");
        for (uint32_t i = 0; i < cn; i++) {
            TSNode pair = ts_node_named_child(node, i);
            if (strcmp(ts_node_type(pair), "pair") != 0)
                continue;
            TSNode key = ts_node_child_by_field_name(pair, "key", 3);
            TSNode value = ts_node_child_by_field_name(pair, "value", 5);
            if (ts_node_is_null(key) || ts_node_is_null(value))
                continue;
            const CBMType *kt = py_eval_expr_type(ctx, key);
            const CBMType *vt = py_eval_expr_type(ctx, value);
            if (!kt || !vt)
                break;
            const CBMType *args[3] = {kt, vt, NULL};
            return cbm_type_template(ctx->arena, "dict", args, 2);
        }
        return cbm_type_builtin(ctx->arena, "dict");
    }

    if (strcmp(k, "identifier") == 0) {
        char *name = py_node_text(ctx, node);
        if (!name)
            return cbm_type_unknown();
        const CBMVarBinding *binding = cbm_scope_lookup_binding(ctx->current_scope, name);
        if (binding)
            return binding->type ? binding->type : cbm_type_unknown();
        // Builtin globals: True / False / None at top level.
        if (strcmp(name, "True") == 0 || strcmp(name, "False") == 0)
            return cbm_type_builtin(ctx->arena, "bool");
        if (strcmp(name, "None") == 0)
            return cbm_type_builtin(ctx->arena, "None");
        // Module/package-local function.
        const CBMRegisteredFunc *f =
            cbm_registry_lookup_symbol(ctx->registry, ctx->module_qn, name);
        if (f)
            return py_func_return_type(ctx, f->qualified_name);
        // Builtins fallback (range / len / list / str / int / etc.). For
        // builtin classes, this returns the class as NAMED so subsequent
        // attribute access works.
        f = cbm_registry_lookup_symbol(ctx->registry, "builtins", name);
        if (f)
            return py_func_return_type(ctx, f->qualified_name);
        const CBMRegisteredType *rt = cbm_registry_lookup_type(
            ctx->registry, cbm_arena_sprintf(ctx->arena, "builtins.%s", name));
        if (rt)
            return cbm_type_builtin(ctx->arena, name);
        return cbm_type_unknown();
    }

    if (strcmp(k, "attribute") == 0) {
        TSNode obj = ts_node_child_by_field_name(node, "object", 6);
        TSNode attr = ts_node_child_by_field_name(node, "attribute", 9);
        if (ts_node_is_null(obj) || ts_node_is_null(attr))
            return cbm_type_unknown();
        const CBMType *obj_type = py_eval_expr_type(ctx, obj);
        if (obj_type)
            obj_type = cbm_type_resolve_alias(obj_type);
        char *attr_name = py_node_text(ctx, attr);
        if (!attr_name || !obj_type)
            return cbm_type_unknown();

        if (obj_type->kind == CBM_TYPE_MODULE) {
            // module.attr — its own function or class, or what it re-exports
            // under the name.
            const char *mod = obj_type->data.module.module_qn;
            PyModuleMember mm = py_module_member(ctx, mod, attr_name);
            if (mm.func)
                return py_func_return_type(ctx, mm.func->qualified_name);
            if (mm.type)
                return cbm_type_named(ctx->arena, mm.type->qualified_name);
            const char *qn = cbm_arena_sprintf(ctx->arena, "%s.%s", mod, attr_name);
            if (qn && cbm_registry_is_module(ctx->registry, qn))
                return cbm_type_module(ctx->arena, qn);
            if (py_names_submodule(ctx, qn))
                return cbm_type_module(ctx->arena, qn);
            return cbm_type_unknown();
        }
        if (obj_type->kind == CBM_TYPE_NAMED) {
            const CBMRegisteredFunc *f =
                py_lookup_attribute(ctx, obj_type->data.named.qualified_name, attr_name);
            if (f)
                return py_func_return_type_recv(ctx, f->qualified_name,
                                                obj_type->data.named.qualified_name);
            // Field fallback: instance attributes from __init__'s self.x = expr.
            const CBMType *field =
                py_lookup_field(ctx, obj_type->data.named.qualified_name, attr_name);
            if (field)
                return field;
        }
        if (obj_type->kind == CBM_TYPE_BUILTIN && obj_type->data.builtin.name) {
            // Builtins map to typeshed stdlib via "builtins.<typename>".
            const char *recv_qn =
                cbm_arena_sprintf(ctx->arena, "builtins.%s", obj_type->data.builtin.name);
            const CBMRegisteredFunc *f = py_lookup_attribute(ctx, recv_qn, attr_name);
            if (f)
                return py_func_return_type_recv(ctx, f->qualified_name, recv_qn);
        }
        if (obj_type->kind == CBM_TYPE_TEMPLATE && obj_type->data.template_type.template_name) {
            // dict[K, V].get / list[T].append etc — receiver is the
            // unparameterized container in typeshed: builtins.dict /
            // builtins.list / collections.abc.Mapping etc.
            const char *tname = obj_type->data.template_type.template_name;
            // Try builtins.<tname> first, then bare tname.
            const char *recv_qn = cbm_arena_sprintf(ctx->arena, "builtins.%s", tname);
            const CBMRegisteredFunc *f = py_lookup_attribute(ctx, recv_qn, attr_name);
            if (!f) {
                f = py_lookup_attribute(ctx, tname, attr_name);
            }
            if (f)
                return py_func_return_type_recv(ctx, f->qualified_name, recv_qn);
        }
        if (obj_type->kind == CBM_TYPE_UNION) {
            int matches = 0;
            const CBMRegisteredFunc *hit = NULL;
            const char *hit_recv = NULL;
            for (int i = 0; i < obj_type->data.union_type.count; i++) {
                const CBMType *m = obj_type->data.union_type.members[i];
                if (!m || m->kind != CBM_TYPE_NAMED)
                    continue;
                const CBMRegisteredFunc *f =
                    py_lookup_attribute(ctx, m->data.named.qualified_name, attr_name);
                if (f) {
                    matches++;
                    hit = f;
                    hit_recv = m->data.named.qualified_name;
                }
            }
            if (matches == 1 && hit) {
                return py_func_return_type_recv(ctx, hit->qualified_name, hit_recv);
            }
            // Field fallback for UNION: same single-match heuristic.
            int field_matches = 0;
            const CBMType *field_hit = NULL;
            for (int i = 0; i < obj_type->data.union_type.count; i++) {
                const CBMType *m = obj_type->data.union_type.members[i];
                if (!m || m->kind != CBM_TYPE_NAMED)
                    continue;
                const CBMType *fld = py_lookup_field(ctx, m->data.named.qualified_name, attr_name);
                if (fld) {
                    field_matches++;
                    field_hit = fld;
                }
            }
            if (field_matches == 1 && field_hit)
                return field_hit;
        }
        return cbm_type_unknown();
    }

    if (strcmp(k, "call") == 0) {
        TSNode fn = ts_node_child_by_field_name(node, "function", 8);
        if (ts_node_is_null(fn))
            return cbm_type_unknown();
        const char *fk = ts_node_type(fn);

        // Container method special-cases: dict.items() / .keys() / .values(),
        // list.copy(), set.copy() etc. Without a constraint solver we can't
        // substitute K, V into the registered method's return type, so we
        // hand-roll the most-impactful container methods.
        if (strcmp(fk, "attribute") == 0) {
            TSNode obj = ts_node_child_by_field_name(fn, "object", 6);
            TSNode attr = ts_node_child_by_field_name(fn, "attribute", 9);
            if (!ts_node_is_null(obj) && !ts_node_is_null(attr)) {
                const CBMType *obj_type = py_eval_expr_type(ctx, obj);
                char *mname = py_node_text(ctx, attr);
                if (mname && obj_type && obj_type->kind == CBM_TYPE_TEMPLATE) {
                    const char *tname = obj_type->data.template_type.template_name;
                    const CBMType **args = obj_type->data.template_type.template_args;
                    int n = obj_type->data.template_type.arg_count;
                    bool is_dict_like =
                        tname &&
                        (strcmp(tname, "dict") == 0 || strcmp(tname, "Mapping") == 0 ||
                         strcmp(tname, "MutableMapping") == 0 ||
                         strcmp(tname, "defaultdict") == 0 || strcmp(tname, "OrderedDict") == 0);
                    bool is_list_like =
                        tname && (strcmp(tname, "list") == 0 || strcmp(tname, "set") == 0 ||
                                  strcmp(tname, "frozenset") == 0 || strcmp(tname, "deque") == 0);
                    if (is_dict_like && args && n >= 2) {
                        if (strcmp(mname, "items") == 0) {
                            const CBMType *pair[3] = {args[0], args[1], NULL};
                            return cbm_type_template(ctx->arena, "ItemsView", pair, 2);
                        }
                        if (strcmp(mname, "keys") == 0) {
                            const CBMType *k1[2] = {args[0], NULL};
                            return cbm_type_template(ctx->arena, "KeysView", k1, 1);
                        }
                        if (strcmp(mname, "values") == 0) {
                            const CBMType *v1[2] = {args[1], NULL};
                            return cbm_type_template(ctx->arena, "ValuesView", v1, 1);
                        }
                        if (strcmp(mname, "get") == 0) {
                            // dict.get(k) -> Optional[V]
                            return cbm_type_optional(ctx->arena, args[1]);
                        }
                        if (strcmp(mname, "pop") == 0) {
                            return args[1];
                        }
                        if (strcmp(mname, "copy") == 0) {
                            return obj_type; // dict[K, V]
                        }
                    }
                    if (is_list_like && args && n >= 1) {
                        if (strcmp(mname, "copy") == 0 || strcmp(mname, "__iter__") == 0) {
                            return obj_type;
                        }
                        if (strcmp(mname, "pop") == 0) {
                            return args[0];
                        }
                    }
                }
            }
        }

        // typing.cast(T, x) -> NAMED(T). typing.assert_type(x, T) -> type-of(x).
        // Detect by the call's function expression: matches either bare `cast` /
        // `assert_type` (when imported from typing) or `typing.cast` style.
        bool is_cast = false;
        bool is_assert_type = false;
        if (strcmp(fk, "identifier") == 0) {
            char *nm = py_node_text(ctx, fn);
            if (nm) {
                is_cast = strcmp(nm, "cast") == 0;
                is_assert_type = strcmp(nm, "assert_type") == 0;
            }
        } else if (strcmp(fk, "attribute") == 0) {
            TSNode aobj = ts_node_child_by_field_name(fn, "object", 6);
            TSNode aattr = ts_node_child_by_field_name(fn, "attribute", 9);
            if (!ts_node_is_null(aobj) && !ts_node_is_null(aattr) &&
                strcmp(ts_node_type(aobj), "identifier") == 0) {
                char *mod = py_node_text(ctx, aobj);
                char *nm = py_node_text(ctx, aattr);
                if (mod && nm && strcmp(mod, "typing") == 0) {
                    is_cast = strcmp(nm, "cast") == 0;
                    is_assert_type = strcmp(nm, "assert_type") == 0;
                }
            }
        }
        if (is_cast || is_assert_type) {
            TSNode args = ts_node_child_by_field_name(node, "arguments", 9);
            if (!ts_node_is_null(args) && ts_node_named_child_count(args) >= 2) {
                if (is_cast) {
                    TSNode type_arg = ts_node_named_child(args, 0);
                    char *type_text = py_node_text(ctx, type_arg);
                    if (type_text)
                        return py_resolve_annotation(ctx, type_text);
                } else {
                    // assert_type(x, T) returns x's type unchanged (it's a no-op).
                    TSNode val_arg = ts_node_named_child(args, 0);
                    return py_eval_expr_type(ctx, val_arg);
                }
            }
        }

        if (strcmp(fk, "identifier") == 0) {
            char *fname = py_node_text(ctx, fn);
            if (!fname)
                return cbm_type_unknown();
            // next(iter) — returns the iterable's element type.
            if (strcmp(fname, "next") == 0) {
                TSNode args = ts_node_child_by_field_name(node, "arguments", 9);
                if (!ts_node_is_null(args) && ts_node_named_child_count(args) >= 1) {
                    const CBMType *iter_type = py_eval_expr_type(ctx, ts_node_named_child(args, 0));
                    const CBMType *elem = py_iterable_element_type(ctx, iter_type);
                    if (elem && !cbm_type_is_unknown(elem))
                        return elem;
                }
            }
            // iter(x) -> Iterator[element_of(x)] (best-effort: same as x).
            if (strcmp(fname, "iter") == 0) {
                TSNode args = ts_node_child_by_field_name(node, "arguments", 9);
                if (!ts_node_is_null(args) && ts_node_named_child_count(args) >= 1) {
                    return py_eval_expr_type(ctx, ts_node_named_child(args, 0));
                }
            }
            // Constructor call: ClassName() returns NAMED(ClassName).
            const CBMVarBinding *binding = cbm_scope_lookup_binding(ctx->current_scope, fname);
            const CBMType *in_scope = binding && binding->type ? binding->type : cbm_type_unknown();
            const char *callable_qn = binding ? binding->callable_qn : NULL;
            if (callable_qn) {
                return py_func_return_type(ctx, callable_qn);
            }
            if (!cbm_type_is_unknown(in_scope)) {
                if (in_scope->kind == CBM_TYPE_NAMED) {
                    const CBMRegisteredType *rt = cbm_registry_lookup_type(
                        ctx->registry, in_scope->data.named.qualified_name);
                    if (rt)
                        return in_scope; // NAMED(ClassName) = instance type
                }
                // CALLABLE in scope -> calling it returns its return type.
                if (in_scope->kind == CBM_TYPE_CALLABLE) {
                    return in_scope->data.callable.return_type ? in_scope->data.callable.return_type
                                                               : cbm_type_unknown();
                }
                // TEMPLATE("Callable", [..., R]) — last template arg is the
                // return type; calling such a value yields R.
                if (in_scope->kind == CBM_TYPE_TEMPLATE &&
                    in_scope->data.template_type.template_name &&
                    strcmp(in_scope->data.template_type.template_name, "Callable") == 0 &&
                    in_scope->data.template_type.arg_count >= 1) {
                    int n = in_scope->data.template_type.arg_count;
                    return in_scope->data.template_type.template_args[n - 1];
                }
            }
            /* Even an UNKNOWN local/parameter is a real lexical shadow. Do
             * not borrow the return type of a same-named module function. */
            if (binding)
                return cbm_type_unknown();
            // Module-local function call.
            const CBMRegisteredFunc *f =
                cbm_registry_lookup_symbol(ctx->registry, ctx->module_qn, fname);
            if (f)
                return py_func_return_type(ctx, f->qualified_name);
            // Builtins fallback: range / len / list / str / int / etc.
            f = cbm_registry_lookup_symbol(ctx->registry, "builtins", fname);
            if (f)
                return py_func_return_type(ctx, f->qualified_name);
            // Builtin class constructor: list() / dict() / set() / str() / ...
            const CBMRegisteredType *rt = cbm_registry_lookup_type(
                ctx->registry, cbm_arena_sprintf(ctx->arena, "builtins.%s", fname));
            if (rt)
                return cbm_type_builtin(ctx->arena, fname);
        }

        // factory()() / (lambda x: x)(...) / etc — evaluate the function
        // expression's type, and if it's a callable, return its return.
        if (strcmp(fk, "call") == 0 || strcmp(fk, "parenthesized_expression") == 0 ||
            strcmp(fk, "lambda") == 0) {
            const CBMType *fn_type = py_eval_expr_type(ctx, fn);
            if (fn_type && fn_type->kind == CBM_TYPE_CALLABLE) {
                return fn_type->data.callable.return_type ? fn_type->data.callable.return_type
                                                          : cbm_type_unknown();
            }
            if (fn_type && fn_type->kind == CBM_TYPE_TEMPLATE &&
                fn_type->data.template_type.template_name &&
                strcmp(fn_type->data.template_type.template_name, "Callable") == 0 &&
                fn_type->data.template_type.arg_count >= 1) {
                int n = fn_type->data.template_type.arg_count;
                return fn_type->data.template_type.template_args[n - 1];
            }
        }

        if (strcmp(fk, "attribute") == 0) {
            TSNode obj = ts_node_child_by_field_name(fn, "object", 6);
            TSNode attr = ts_node_child_by_field_name(fn, "attribute", 9);
            if (ts_node_is_null(obj) || ts_node_is_null(attr))
                return cbm_type_unknown();
            const CBMType *obj_type = py_eval_expr_type(ctx, obj);
            char *attr_name = py_node_text(ctx, attr);
            if (!attr_name || !obj_type)
                return cbm_type_unknown();

            if (obj_type->kind == CBM_TYPE_MODULE) {
                const char *mod = obj_type->data.module.module_qn;
                PyModuleMember mm = py_module_member(ctx, mod, attr_name);
                if (mm.func)
                    return py_func_return_type(ctx, mm.func->qualified_name);
                if (mm.type) // `mod.Class()` constructs an instance
                    return cbm_type_named(ctx->arena, mm.type->qualified_name);
            }
            if (obj_type->kind == CBM_TYPE_NAMED) {
                const CBMRegisteredFunc *f =
                    py_lookup_attribute(ctx, obj_type->data.named.qualified_name, attr_name);
                if (f)
                    return py_func_return_type_recv(ctx, f->qualified_name,
                                                    obj_type->data.named.qualified_name);
            }
        }
        return cbm_type_unknown();
    }

    if (strcmp(k, "binary_operator") == 0) {
        TSNode left = ts_node_child_by_field_name(node, "left", 4);
        TSNode op = ts_node_child_by_field_name(node, "operator", 8);
        const CBMType *lt = py_eval_expr_type(ctx, left);
        // Try the operator's dunder method on left's type. Falls back to
        // left-operand type when registry has no info (most common: int+int,
        // str+str, list+list — typing-by-left is correct in those cases).
        if (lt && lt->kind == CBM_TYPE_NAMED && !ts_node_is_null(op)) {
            char *op_text = py_node_text(ctx, op);
            const char *dunder = NULL;
            if (op_text) {
                if (strcmp(op_text, "+") == 0)
                    dunder = "__add__";
                else if (strcmp(op_text, "-") == 0)
                    dunder = "__sub__";
                else if (strcmp(op_text, "*") == 0)
                    dunder = "__mul__";
                else if (strcmp(op_text, "/") == 0)
                    dunder = "__truediv__";
                else if (strcmp(op_text, "//") == 0)
                    dunder = "__floordiv__";
                else if (strcmp(op_text, "%") == 0)
                    dunder = "__mod__";
                else if (strcmp(op_text, "**") == 0)
                    dunder = "__pow__";
                else if (strcmp(op_text, "<<") == 0)
                    dunder = "__lshift__";
                else if (strcmp(op_text, ">>") == 0)
                    dunder = "__rshift__";
                else if (strcmp(op_text, "&") == 0)
                    dunder = "__and__";
                else if (strcmp(op_text, "|") == 0)
                    dunder = "__or__";
                else if (strcmp(op_text, "^") == 0)
                    dunder = "__xor__";
                else if (strcmp(op_text, "@") == 0)
                    dunder = "__matmul__";
            }
            if (dunder) {
                const CBMRegisteredFunc *f =
                    py_lookup_attribute(ctx, lt->data.named.qualified_name, dunder);
                if (f) {
                    return py_func_return_type_recv(ctx, f->qualified_name,
                                                    lt->data.named.qualified_name);
                }
            }
        }
        return lt ? lt : cbm_type_unknown();
    }

    if (strcmp(k, "comparison_operator") == 0 || strcmp(k, "boolean_operator") == 0 ||
        strcmp(k, "not_operator") == 0) {
        return cbm_type_builtin(ctx->arena, "bool");
    }

    if (strcmp(k, "conditional_expression") == 0) {
        // a if cond else b — return union of a, b types
        uint32_t nc = ts_node_named_child_count(node);
        if (nc >= 2) {
            const CBMType *a = py_eval_expr_type(ctx, ts_node_named_child(node, 0));
            const CBMType *b = py_eval_expr_type(ctx, ts_node_named_child(node, 2));
            const CBMType *members[2] = {a, b};
            return cbm_type_union(ctx->arena, members, 2);
        }
    }

    if (strcmp(k, "parenthesized_expression") == 0) {
        if (ts_node_named_child_count(node) > 0) {
            return py_eval_expr_type(ctx, ts_node_named_child(node, 0));
        }
    }

    // `await expr` — for resolution purposes we treat as identity. async
    // functions register their declared return type as the registered
    // return; callers use it directly without modeling Coroutine[A, A, T].
    if (strcmp(k, "await") == 0 || strcmp(k, "await_expression") == 0) {
        if (ts_node_named_child_count(node) > 0) {
            return py_eval_expr_type(ctx, ts_node_named_child(node, 0));
        }
    }

    // Subscript: container[index]. For TEMPLATE("dict", [K, V])[K] -> V;
    // TEMPLATE("list"|"set"|...)[int] -> elem; TEMPLATE("tuple", [A, B,
    // ...])[int] -> A (union when index isn't a literal int). NAMED that
    // resolves to a TypedDict-tagged registered type with a literal-string
    // key returns the field's type.
    if (strcmp(k, "subscript") == 0) {
        TSNode value = ts_node_child_by_field_name(node, "value", 5);
        if (ts_node_is_null(value))
            return cbm_type_unknown();
        const CBMType *container = py_eval_expr_type(ctx, value);

        // TypedDict literal-key subscript: d["foo"] where d: TD and TD has
        // class-body annotation `foo: Foo`. Field is registered via
        // py_register_instance_field.
        if (container && container->kind == CBM_TYPE_NAMED) {
            TSNode sub = ts_node_child_by_field_name(node, "subscript", 9);
            if (!ts_node_is_null(sub)) {
                const char *sk = ts_node_type(sub);
                if (strcmp(sk, "string") == 0) {
                    char *lit = py_node_text(ctx, sub);
                    if (lit) {
                        // Strip surrounding quotes.
                        size_t llen = strlen(lit);
                        if (llen >= 2 && (lit[0] == '"' || lit[0] == '\'') &&
                            lit[llen - 1] == lit[0]) {
                            lit[llen - 1] = '\0';
                            lit++;
                        }
                        const CBMType *field =
                            py_lookup_field(ctx, container->data.named.qualified_name, lit);
                        if (field)
                            return field;
                    }
                }
            }
            return cbm_type_unknown();
        }

        if (!container || container->kind != CBM_TYPE_TEMPLATE) {
            return cbm_type_unknown();
        }
        const char *tname = container->data.template_type.template_name;
        const CBMType **args = container->data.template_type.template_args;
        int n = container->data.template_type.arg_count;
        if (!tname || !args || n <= 0)
            return cbm_type_unknown();

        // Slice subscript returns the same container type:
        // list[T][1:3] -> list[T]; str[1:3] -> str (handled via BUILTIN
        // path elsewhere).
        TSNode sub = ts_node_child_by_field_name(node, "subscript", 9);
        if (!ts_node_is_null(sub) && strcmp(ts_node_type(sub), "slice") == 0) {
            return container;
        }

        if (strcmp(tname, "dict") == 0 || strcmp(tname, "Mapping") == 0 ||
            strcmp(tname, "MutableMapping") == 0 || strcmp(tname, "defaultdict") == 0 ||
            strcmp(tname, "OrderedDict") == 0 || strcmp(tname, "ChainMap") == 0) {
            // Value type is the second template arg.
            if (n >= 2 && args[1])
                return args[1];
            return cbm_type_unknown();
        }
        if (strcmp(tname, "list") == 0 || strcmp(tname, "set") == 0 ||
            strcmp(tname, "frozenset") == 0 || strcmp(tname, "Sequence") == 0 ||
            strcmp(tname, "MutableSequence") == 0 || strcmp(tname, "deque") == 0 ||
            strcmp(tname, "Iterable") == 0 || strcmp(tname, "Iterator") == 0) {
            return args[0];
        }
        if (strcmp(tname, "tuple") == 0) {
            if (!ts_node_is_null(sub) && strcmp(ts_node_type(sub), "integer") == 0) {
                char *idx_text = py_node_text(ctx, sub);
                if (idx_text) {
                    int idx = atoi(idx_text);
                    if (idx >= 0 && idx < n)
                        return args[idx];
                }
            }
            if (n == 1)
                return args[0];
            return cbm_type_union(ctx->arena, args, n);
        }
        // Other generics: best-effort first arg.
        return args[0];
    }

    return cbm_type_unknown();
}

/* ── py_eval_expr_type memoization + guards (issues #710, #720) ──────────
 *
 * py_eval_expr_type_uncached re-evaluates a call node's attribute receiver
 * twice — once in the container special-case and again in the general
 * attribute path — so an N-link chained call (`Builder().add(x)...add(z)`)
 * cost O(2^N) evaluations: the #710 indexing hang (~65-link real chains).
 * Memoizing per node makes each distinct node evaluate at most once per
 * scope generation, and py_emit_call_for's per-call-node receiver
 * re-evaluation becomes an O(1) cache hit.
 *
 * Key: the tree-sitter node identity pointer (TSNode.id — unique per node
 * within one parse tree). NOT the node's start byte: in a chained call
 * every leftmost descendant (the whole chain, each receiver, down to the
 * root identifier) shares the same start byte, so byte-keyed entries alias
 * distinct nodes and silently return the wrong type (missing/incorrect
 * CALLS edges).
 *
 * Entries carry the scope generation (see py_scope_bind); stale
 * generations never match, which keeps caching invisible to resolution
 * behavior. The table is open-addressing/linear-probe, arena-allocated on
 * the per-file arena (freed with it; ctx is memset per file so each file
 * starts cold). */

enum { PY_TYPE_CACHE_INITIAL_CAP = 256 }; /* power of two (index masking) */
enum { PY_TYPE_CACHE_MAX_CAP = 1 << 26 }; /* hard stop for adversarial files */

static uint32_t py_type_cache_hash(const void *id) {
    uintptr_t v = (uintptr_t)id >> 3; /* node structs are >=8-byte aligned */
    return (uint32_t)((v ^ (v >> 29)) * 2654435761u);
}

/* Returns the cached full-fidelity result for this node, or NULL when the
 * node has no entry from the current scope generation. Live entries never
 * store NULL (the wrapper normalizes to cbm_type_unknown() first), so NULL
 * unambiguously means "miss". */
static const CBMType *py_type_cache_lookup(const PyLSPContext *ctx, const void *id) {
    if (!ctx->type_cache || ctx->type_cache_cap == 0 || !id)
        return NULL;
    uint32_t mask = (uint32_t)ctx->type_cache_cap - 1;
    uint32_t idx = py_type_cache_hash(id) & mask;
    for (int probed = 0; probed < ctx->type_cache_cap; probed++) {
        const CBMPyTypeCacheEntry *e = &ctx->type_cache[idx];
        if (!e->node_id)
            return NULL; /* empty slot: this id was never inserted */
        if (e->node_id == id)
            return e->gen == ctx->type_cache_gen ? e->result : NULL;
        idx = (idx + 1) & mask;
    }
    return NULL; /* probe bound: unreachable below the 75% load ceiling */
}

/* Doubles the table (arena allocation: the old table is abandoned and
 * freed with the per-file arena). Entries from stale generations are
 * dropped during the rehash — they can never match again. */
static bool py_type_cache_grow(PyLSPContext *ctx) {
    if (ctx->type_cache_cap >= PY_TYPE_CACHE_MAX_CAP)
        return false;
    int new_cap = ctx->type_cache_cap ? ctx->type_cache_cap * 2 : PY_TYPE_CACHE_INITIAL_CAP;
    if ((size_t)new_cap > SIZE_MAX / sizeof(CBMPyTypeCacheEntry))
        return false;
#ifdef CBM_ENABLE_TEST_SEAMS
    if (ctx->test_memo_allocations_left == 0)
        return false;
    if (ctx->test_memo_allocations_left > 0)
        ctx->test_memo_allocations_left--;
#endif
    CBMPyTypeCacheEntry *new_entries = (CBMPyTypeCacheEntry *)cbm_arena_alloc(
        ctx->arena, (size_t)new_cap * sizeof(CBMPyTypeCacheEntry));
    if (!new_entries)
        return false;
    memset(new_entries, 0, (size_t)new_cap * sizeof(CBMPyTypeCacheEntry));

    CBMPyTypeCacheEntry *old_entries = ctx->type_cache;
    int old_cap = ctx->type_cache_cap;
    ctx->type_cache = new_entries;
    ctx->type_cache_cap = new_cap;
    ctx->type_cache_count = 0;

    uint32_t mask = (uint32_t)new_cap - 1;
    for (int i = 0; i < old_cap; i++) {
        if (!old_entries[i].node_id || old_entries[i].gen != ctx->type_cache_gen)
            continue;
        uint32_t idx = py_type_cache_hash(old_entries[i].node_id) & mask;
        while (new_entries[idx].node_id)
            idx = (idx + 1) & mask;
        new_entries[idx] = old_entries[i];
        ctx->type_cache_count++;
    }
    return true;
}

static bool py_type_cache_insert(PyLSPContext *ctx, const void *id, const CBMType *result) {
    if (!id || !result)
        return true;
    /* Keep load strictly below 75% so probe chains stay short. If growth
     * fails (OOM / max cap), REJECT the insert rather than filling up: a
     * full table would turn every probe loop into a full-table scan, and
     * an unbounded insert loop on a full table would spin forever. */
    if (!ctx->type_cache || (ctx->type_cache_count + 1) * 4 > ctx->type_cache_cap * 3) {
        if (!py_type_cache_grow(ctx) &&
            (!ctx->type_cache || (ctx->type_cache_count + 1) * 4 > ctx->type_cache_cap * 3))
            return false;
    }
    uint32_t mask = (uint32_t)ctx->type_cache_cap - 1;
    uint32_t idx = py_type_cache_hash(id) & mask;
    for (int probed = 0; probed < ctx->type_cache_cap; probed++) {
        CBMPyTypeCacheEntry *e = &ctx->type_cache[idx];
        if (!e->node_id) {
            e->node_id = id;
            e->gen = ctx->type_cache_gen;
            e->result = result;
            ctx->type_cache_count++;
            return true;
        }
        if (e->node_id == id) {
            e->gen = ctx->type_cache_gen; /* refresh a stale-generation entry in place */
            e->result = result;
            return true;
        }
        idx = (idx + 1) & mask;
    }
    /* Probe bound exhausted — only reachable with a corrupt count; drop the
     * insert instead of spinning. */
    return false;
}

/* ── Left-associative chains are evaluated iteratively ───────────────────
 *
 * A chain's length is not nesting. `a + b + ... + z`, `x.a().b()...`,
 * `x.f.g.h`, `m[i][j]`, `a if p else b if q else ...` and runs of
 * parentheses are trees in which every link derives its type from ONE chain
 * operand. Recursing through them spent native stack and a
 * PY_LSP_MAX_EVAL_DEPTH unit per link, so a 300-term sum exceeded the guard
 * and rolled back the whole file.
 *
 * py_eval_expr_type therefore first walks down the chain operands below the
 * node, then evaluates them innermost first, each at the caller's depth. When
 * a link is evaluated, its chain operand is already cached, so the
 * evaluator's own recursive call into it is a cache hit one frame deep. The
 * types are exactly the recursive ones: every node is still evaluated by
 * py_eval_expr_type_uncached, the cache is generation-checked (evaluation
 * never binds or restores scope, and if it did a stale entry would simply
 * miss and recurse), and only an operand the uncached evaluator always
 * evaluates is pre-evaluated, so no node is evaluated that the recursion
 * would not have evaluated. Operands in any other position (call arguments,
 * container elements, dictionary keys and values, await operands, ...) are
 * genuine nesting and still count depth. */

/* The chain operand of a link: an operand py_eval_expr_type_uncached always
 * evaluates and derives the link's type from. A null node when `node` is not
 * a chain link. */
static TSNode py_chain_operand(TSNode node) {
    const TSNode none = {0};
    const char *k = ts_node_type(node);
    if (strcmp(k, "attribute") == 0) {
        if (ts_node_is_null(ts_node_child_by_field_name(node, "attribute", 9)))
            return none;
        return ts_node_child_by_field_name(node, "object", 6);
    }
    if (strcmp(k, "call") == 0) {
        TSNode fn = ts_node_child_by_field_name(node, "function", 8);
        if (ts_node_is_null(fn))
            return none;
        const char *fk = ts_node_type(fn);
        /* `obj.m(...)` evaluates obj, never the attribute node itself. */
        if (strcmp(fk, "attribute") == 0) {
            if (ts_node_is_null(ts_node_child_by_field_name(fn, "attribute", 9)))
                return none;
            return ts_node_child_by_field_name(fn, "object", 6);
        }
        /* `f()()` / `(expr)()`: the callee expression is evaluated. */
        if (strcmp(fk, "call") == 0 || strcmp(fk, "parenthesized_expression") == 0)
            return fn;
        return none;
    }
    if (strcmp(k, "subscript") == 0)
        return ts_node_child_by_field_name(node, "value", 5);
    if (strcmp(k, "binary_operator") == 0)
        return ts_node_child_by_field_name(node, "left", 4);
    if (strcmp(k, "conditional_expression") == 0) {
        /* Both branches are evaluated; a conditional chain continues in the
         * else branch: `a if p else (b if q else ...)`. */
        return ts_node_named_child_count(node) >= 3 ? ts_node_named_child(node, 2) : none;
    }
    if (strcmp(k, "parenthesized_expression") == 0)
        return ts_node_named_child_count(node) > 0 ? ts_node_named_child(node, 0) : none;
    return none;
}

/* Push a pending link. On allocation failure the caller stops collecting:
 * the rest of the chain is then evaluated recursively, under the depth
 * guard, exactly as before -- slower to fail, never a wrong type. */
static bool py_eval_chain_push(PyLSPContext *ctx, TSNode link) {
    if (ctx->eval_chain_len == ctx->eval_chain_cap) {
        if (ctx->eval_chain_cap > INT_MAX / 2)
            return false;
        int new_cap = ctx->eval_chain_cap ? ctx->eval_chain_cap * 2 : 64;
        if ((size_t)new_cap > SIZE_MAX / sizeof(TSNode))
            return false;
        TSNode *grown = (TSNode *)cbm_arena_alloc(ctx->arena, (size_t)new_cap * sizeof(TSNode));
        if (!grown)
            return false;
        if (ctx->eval_chain_len > 0)
            memcpy(grown, ctx->eval_chain, (size_t)ctx->eval_chain_len * sizeof(TSNode));
        ctx->eval_chain = grown;
        ctx->eval_chain_cap = new_cap;
    }
    ctx->eval_chain[ctx->eval_chain_len++] = link;
    return true;
}

/* One real evaluation of a node that has no live cache entry. */
static const CBMType *py_eval_expr_type_node(PyLSPContext *ctx, TSNode node) {
    /* One real (non-memoized) evaluation: the work the complexity tests count
     * to prove evaluation stays linear without a budget. */
    CBM_LSP_WORK(1);

    uint32_t trunc_before = ctx->eval_truncations;
    ctx->eval_depth++;
    const CBMType *result = py_eval_expr_type_uncached(ctx, node);
    ctx->eval_depth--;
    if (!result)
        result = cbm_type_unknown();

    /* Only cache full-fidelity results: if any descendant evaluation was
     * cut off by the depth cap, this result may be a truncated `unknown`.
     * The sticky failure stops this walk instead of repeating uncached branches;
     * a fresh walk starts with a fresh cache. */
    if (!ctx->eval_failure && ctx->eval_truncations == trunc_before &&
        !py_type_cache_insert(ctx, node.id, result))
        ctx->eval_failure = CBM_LSP_MEMO_FAILED;
    return ctx->eval_failure ? cbm_type_unknown() : result;
}

/* Evaluate the uncached chain operands below `node`, innermost first.
 * Nested evaluations push above the links still pending, so the stack is
 * shared; a link's index is re-read after each evaluation (it may grow). */
static void py_eval_chain_operands(PyLSPContext *ctx, TSNode node) {
    int base = ctx->eval_chain_len;
    for (TSNode op = py_chain_operand(node); !ts_node_is_null(op); op = py_chain_operand(op)) {
        if (py_type_cache_lookup(ctx, op.id) || !py_eval_chain_push(ctx, op))
            break;
    }
    for (int i = ctx->eval_chain_len - 1; i >= base && !ctx->eval_failure; i--) {
        TSNode link = ctx->eval_chain[i];
        ctx->eval_chain_len = i;
        if (!py_type_cache_lookup(ctx, link.id))
            (void)py_eval_expr_type_node(ctx, link);
    }
    ctx->eval_chain_len = base;
}

/* Memoizing, depth-guarded wrapper — the function every call site in this
 * file goes through. */
static const CBMType *py_eval_expr_type(PyLSPContext *ctx, TSNode node) {
    if (!ctx || ctx->eval_failure || ts_node_is_null(node))
        return cbm_type_unknown();

    /* Depth cap (issue #720): the evaluator recurses once per expression
     * nesting level, so a pathologically deep expression (tens of
     * thousands of nested brackets) overflowed the native stack. At the
     * existing bound, stop this walk explicitly; never memoize a truncated
     * result as complete. Chain links do not nest (see above). */
    if (ctx->eval_depth >= PY_LSP_MAX_EVAL_DEPTH) {
        ctx->eval_truncations++;
        ctx->eval_failure = CBM_LSP_DEPTH_EXCEEDED;
        return cbm_type_unknown();
    }

    const CBMType *cached = py_type_cache_lookup(ctx, node.id);
    if (cached)
        return cached;

    py_eval_chain_operands(ctx, node);
    if (ctx->eval_failure)
        return cbm_type_unknown();
    return py_eval_expr_type_node(ctx, node);
}

#ifdef CBM_ENABLE_TEST_SEAMS
const CBMType *cbm_py_lsp_test_eval(PyLSPContext *ctx, TSNode node) {
    return py_eval_expr_type(ctx, node);
}
#endif

/* ── statement processing: bind from assignments, for-loops, with-as ──── */

static void py_process_statement(PyLSPContext *ctx, TSNode node) {
    if (!ctx || ctx->eval_failure || ts_node_is_null(node))
        return;
    const char *k = ts_node_type(node);

    if (strcmp(k, "assignment") == 0) {
        TSNode left = ts_node_child_by_field_name(node, "left", 4);
        TSNode right = ts_node_child_by_field_name(node, "right", 5);
        TSNode ann = ts_node_child_by_field_name(node, "type", 4);

        const CBMType *rhs_type =
            ts_node_is_null(right) ? cbm_type_unknown() : py_eval_expr_type(ctx, right);
        bool rhs_lexical_alias = false;
        const char *rhs_callable =
            ts_node_is_null(right)
                ? NULL
                : py_exact_callable_target_ex(ctx, right, NULL, &rhs_lexical_alias);
        /* A proven callable value on the right of an assignment is a reference
         * to that callable, exactly as it would be as a call argument -- the
         * policy is proven exact value => CALL_REFERENCE, and `cb = handler`
         * proves it or the alias binding below could not be created. Bare
         * identifier RHS only, in lockstep with the usage-carrier rule in
         * extract_usages.c; the strategy distinction mirrors the argument path
         * so a shadowed source name still satisfies the local-shadow guard. */
        if (rhs_callable && strcmp(ts_node_type(right), "identifier") == 0) {
            char *rhs_name = py_node_text(ctx, right);
            py_emit_resolved_reference(ctx, rhs_callable, rhs_name, right,
                                       rhs_lexical_alias ? "lsp_callable_alias"
                                                         : "lsp_callable_value_reference");
        }

        // Annotated assignment: x: T = expr — annotation wins.
        bool has_annotation = !ts_node_is_null(ann);
        if (has_annotation) {
            char *ann_text = py_node_text(ctx, ann);
            if (ann_text && ann_text[0]) {
                rhs_type = py_resolve_annotation(ctx, ann_text);
            }
        }

        if (ts_node_is_null(left))
            return;
        const char *lk = ts_node_type(left);
        // Tuple/list pattern unpacking: a, b = f()  /  [a, b] = f()  /
        // (a, b) = f(). Each LHS element binds to the corresponding
        // element of the RHS tuple. *rest binds the remaining elements
        // as a list (best-effort: list of element type).
        if (strcmp(lk, "pattern_list") == 0 || strcmp(lk, "tuple_pattern") == 0 ||
            strcmp(lk, "list_pattern") == 0 || strcmp(lk, "expression_list") == 0) {
            uint32_t lc = ts_node_named_child_count(left);
            // Collect RHS element types.
            const CBMType *const *rhs_elems = NULL;
            int rhs_count = 0;
            if (rhs_type) {
                if (rhs_type->kind == CBM_TYPE_TUPLE) {
                    rhs_elems = rhs_type->data.tuple.elems;
                    rhs_count = rhs_type->data.tuple.count;
                } else if (rhs_type->kind == CBM_TYPE_TEMPLATE &&
                           rhs_type->data.template_type.template_name) {
                    const char *tn = rhs_type->data.template_type.template_name;
                    if (strcmp(tn, "tuple") == 0) {
                        rhs_elems = rhs_type->data.template_type.template_args;
                        rhs_count = rhs_type->data.template_type.arg_count;
                    }
                }
            }
            // Element type for star-rest binding (best-effort element of
            // the iterable; for a pure tuple use UNKNOWN since the rest
            // is heterogeneous).
            const CBMType *elem_type = py_iterable_element_type(ctx, rhs_type);

            for (uint32_t i = 0; i < lc; i++) {
                TSNode tgt = ts_node_named_child(left, i);
                if (ts_node_is_null(tgt))
                    continue;
                const char *tk = ts_node_type(tgt);
                bool is_rest = false;
                TSNode bind_target = tgt;
                if (strcmp(tk, "list_splat_pattern") == 0 || strcmp(tk, "list_splat") == 0) {
                    is_rest = true;
                    if (ts_node_named_child_count(tgt) > 0) {
                        bind_target = ts_node_named_child(tgt, 0);
                    }
                }
                if (strcmp(ts_node_type(bind_target), "identifier") != 0)
                    continue;
                char *nm = py_node_text(ctx, bind_target);
                if (!nm)
                    continue;
                const CBMType *bind_type;
                if (is_rest) {
                    bind_type = elem_type ? cbm_type_template(ctx->arena, "list", &elem_type, 1)
                                          : cbm_type_unknown();
                } else if (rhs_elems && (int)i < rhs_count && rhs_elems[i]) {
                    bind_type = rhs_elems[i];
                } else {
                    bind_type = elem_type ? elem_type : cbm_type_unknown();
                }
                py_scope_bind(ctx, nm, bind_type);
            }
            return;
        }
        if (strcmp(lk, "identifier") == 0) {
            char *name = py_node_text(ctx, left);
            if (name) {
                if (rhs_callable) {
                    py_scope_bind_callable(ctx, name, rhs_type, rhs_callable);
                } else {
                    py_scope_bind(ctx, name, rhs_type);
                }
                // Class attributes must not replace file-wide dispatch entries.
                // Lambda registry: `fn = lambda x: ...`.
                if (!ctx->class_body_outer_scope && !ts_node_is_null(right) &&
                    strcmp(ts_node_type(right), "lambda") == 0) {
                    py_register_lambda(ctx, name, right);
                }
                // Dict literal dispatch table: `funcs = {"a": foo, "b": bar}`
                // with all values being known function QNs.
                if (!ctx->class_body_outer_scope && !ts_node_is_null(right) &&
                    strcmp(ts_node_type(right), "dictionary") == 0) {
                    py_register_dict_literal(ctx, name, right);
                }
            }
        } else if (strcmp(lk, "attribute") == 0) {
            // self.x = expr — record as instance field on the enclosing
            // class. Effective inside any method that resolves obj.x where
            // obj is an instance of the class.
            TSNode obj = ts_node_child_by_field_name(left, "object", 6);
            TSNode attr = ts_node_child_by_field_name(left, "attribute", 9);
            if (!ts_node_is_null(obj) && !ts_node_is_null(attr) &&
                strcmp(ts_node_type(obj), "identifier") == 0 && ctx->enclosing_class_qn) {
                char *obj_name = py_node_text(ctx, obj);
                char *attr_name = py_node_text(ctx, attr);
                if (obj_name && attr_name &&
                    (strcmp(obj_name, "self") == 0 || strcmp(obj_name, "cls") == 0)) {
                    py_register_instance_field(ctx, ctx->enclosing_class_qn, attr_name, rhs_type);
                }
            }
        }
        return;
    }

    if (strcmp(k, "for_statement") == 0) {
        TSNode left = ts_node_child_by_field_name(node, "left", 4);
        TSNode right = ts_node_child_by_field_name(node, "right", 5);
        const CBMType *elem_type = cbm_type_unknown();
        if (!ts_node_is_null(right)) {
            const CBMType *iter_type = py_eval_expr_type(ctx, right);
            elem_type = py_iterable_element_type(ctx, iter_type);
            // For async for: try unwrapping AsyncIterator[T] / AsyncIterable[T]
            // / AsyncGenerator[T, S] — already handled in py_iterable_element_type.
            // If the iterable came from an explicit __aiter__ / __anext__
            // call, look up __anext__'s return type.
            if (cbm_type_is_unknown(elem_type) && iter_type && iter_type->kind == CBM_TYPE_NAMED) {
                const CBMRegisteredFunc *anext =
                    py_lookup_attribute(ctx, iter_type->data.named.qualified_name, "__anext__");
                if (anext) {
                    const CBMType *ret = py_func_return_type_recv(
                        ctx, anext->qualified_name, iter_type->data.named.qualified_name);
                    if (ret && !cbm_type_is_unknown(ret))
                        elem_type = ret;
                }
            }
        }
        py_bind_for_target(ctx, left, elem_type);
        return;
    }

    // async_with_statement (with_statement preceded by `async`) — same
    // shape as with_statement; tree-sitter Python uses with_statement
    // for both, with an `async` token. async with binds via __aenter__.
    if (strcmp(k, "with_statement") == 0) {
        // with X as y:  bind y to X.__enter__() return type. Tree-sitter
        // Python wraps `X as y` in an `as_pattern` whose first named child
        // is X (value) and second is the target identifier `y` (alias).
        // The with_item may either contain the as_pattern as its child, or
        // directly expose value/alias as field children — we handle both.
        uint32_t nc = ts_node_named_child_count(node);
        for (uint32_t i = 0; i < nc; i++) {
            TSNode child = ts_node_named_child(node, i);
            if (strcmp(ts_node_type(child), "with_clause") != 0)
                continue;
            uint32_t cn = ts_node_named_child_count(child);
            for (uint32_t j = 0; j < cn; j++) {
                TSNode item = ts_node_named_child(child, j);
                if (strcmp(ts_node_type(item), "with_item") != 0)
                    continue;

                // Try field lookup first; fall back to as_pattern walk.
                TSNode value = ts_node_child_by_field_name(item, "value", 5);
                TSNode alias = ts_node_child_by_field_name(item, "alias", 5);

                if (ts_node_is_null(value) || ts_node_is_null(alias)) {
                    // Look for an as_pattern child.
                    uint32_t ic = ts_node_named_child_count(item);
                    for (uint32_t k2 = 0; k2 < ic; k2++) {
                        TSNode c = ts_node_named_child(item, k2);
                        if (strcmp(ts_node_type(c), "as_pattern") == 0) {
                            uint32_t ac = ts_node_named_child_count(c);
                            if (ac >= 1)
                                value = ts_node_named_child(c, 0);
                            if (ac >= 2)
                                alias = ts_node_named_child(c, 1);
                            // Field-based lookup as another option.
                            if (ts_node_is_null(alias)) {
                                alias = ts_node_child_by_field_name(c, "alias", 5);
                            }
                            break;
                        }
                    }
                }

                if (ts_node_is_null(alias) || strcmp(ts_node_type(alias), "identifier") != 0) {
                    // alias may itself be an as_pattern_target wrapping an
                    // identifier; walk through it.
                    if (!ts_node_is_null(alias) && ts_node_named_child_count(alias) > 0) {
                        TSNode inner = ts_node_named_child(alias, 0);
                        if (strcmp(ts_node_type(inner), "identifier") == 0) {
                            alias = inner;
                        }
                    }
                }
                if (ts_node_is_null(alias) || strcmp(ts_node_type(alias), "identifier") != 0)
                    continue;
                char *name = py_node_text(ctx, alias);
                if (!name)
                    continue;
                const CBMType *cm_type =
                    ts_node_is_null(value) ? cbm_type_unknown() : py_eval_expr_type(ctx, value);
                const CBMType *bind_type = cm_type;
                if (cm_type && cm_type->kind == CBM_TYPE_NAMED) {
                    // Try __aenter__ first (async with), fall back to
                    // __enter__ (sync with). __aenter__ is a coroutine
                    // returning T; we treat the return as T directly.
                    const CBMRegisteredFunc *enter =
                        py_lookup_attribute(ctx, cm_type->data.named.qualified_name, "__aenter__");
                    if (!enter) {
                        enter = py_lookup_attribute(ctx, cm_type->data.named.qualified_name,
                                                    "__enter__");
                    }
                    if (enter) {
                        const CBMType *ret = py_func_return_type_recv(
                            ctx, enter->qualified_name, cm_type->data.named.qualified_name);
                        if (ret && !cbm_type_is_unknown(ret)) {
                            bind_type = ret;
                        }
                    }
                }
                py_scope_bind(ctx, name, bind_type);
            }
        }
        return;
    }

    if (strcmp(k, "try_statement") == 0) {
        // except E as e: bind e to NAMED(E). Tree-sitter Python wraps
        // `E as e` either as an as_pattern child of the except_clause,
        // or as flat children. Handle both shapes.
        uint32_t nc = ts_node_named_child_count(node);
        for (uint32_t i = 0; i < nc; i++) {
            TSNode clause = ts_node_named_child(node, i);
            if (strcmp(ts_node_type(clause), "except_clause") != 0)
                continue;

            TSNode exc_type = {0};
            TSNode exc_name = {0};
            uint32_t ccn = ts_node_named_child_count(clause);
            for (uint32_t j = 0; j < ccn; j++) {
                TSNode c = ts_node_named_child(clause, j);
                const char *ck = ts_node_type(c);
                if (strcmp(ck, "block") == 0)
                    continue;
                if (strcmp(ck, "as_pattern") == 0) {
                    uint32_t ac = ts_node_named_child_count(c);
                    if (ac >= 1)
                        exc_type = ts_node_named_child(c, 0);
                    if (ac >= 2)
                        exc_name = ts_node_named_child(c, 1);
                    // alias may be wrapped in as_pattern_target
                    if (!ts_node_is_null(exc_name)) {
                        const char *nk = ts_node_type(exc_name);
                        if (strcmp(nk, "as_pattern_target") == 0 &&
                            ts_node_named_child_count(exc_name) > 0) {
                            exc_name = ts_node_named_child(exc_name, 0);
                        }
                    }
                    continue;
                }
                if (ts_node_is_null(exc_type))
                    exc_type = c;
                else if (ts_node_is_null(exc_name) && strcmp(ck, "identifier") == 0) {
                    exc_name = c;
                }
            }
            if (!ts_node_is_null(exc_name) && !ts_node_is_null(exc_type) &&
                strcmp(ts_node_type(exc_name), "identifier") == 0) {
                char *nm = py_node_text(ctx, exc_name);
                char *tn = py_node_text(ctx, exc_type);
                if (nm && tn) {
                    py_scope_bind(ctx, nm, py_resolve_annotation(ctx, tn));
                }
            }
        }
        return;
    }
}

/* ── Recursive walker: process statements + emit resolved_calls ── */

static void py_emit_call_for(PyLSPContext *ctx, TSNode call_node) {
    if (!ctx || ctx->eval_failure)
        return;
    if (!ctx || ctx->callable_value_proof_disabled)
        return;
    TSNode fn = ts_node_child_by_field_name(call_node, "function", 8);
    if (ts_node_is_null(fn))
        return;
    const char *fk = ts_node_type(fn);

    if (strcmp(fk, "identifier") == 0) {
        char *fname = py_node_text(ctx, fn);
        if (!fname)
            return;
        // Lambda invocation: `fn(args)` where fn was assigned a lambda.
        // Walk the lambda body for any nested call sites with the params
        // bound to the call's arg types. Resolved calls get caller_qn
        // set to a synthetic <lambda> child of the enclosing function.
        /* These legacy entries have no lexical frame identity. During class
         * execution, leave lambda replay unresolved instead of bypassing a
         * local shadow or running the lambda against class locals. */
        int lambda_idx = ctx->class_body_outer_scope ? -1 : py_lookup_lambda(ctx, fname);
        if (lambda_idx >= 0) {
            TSNode lambda_node = ctx->lambdas[lambda_idx].lambda_node;
            TSNode params = ts_node_child_by_field_name(lambda_node, "parameters", 10);
            TSNode body = ts_node_child_by_field_name(lambda_node, "body", 4);
            TSNode args = ts_node_child_by_field_name(call_node, "arguments", 9);
            // A lambda that reaches itself again (directly or through another
            // lambda) would re-walk its body once per nesting level up to the
            // walk-depth cap, and two such calls in one body double the work
            // per level. Walk each body at most once per chain.
            if (ctx->lambdas[lambda_idx].expanding)
                return;
            CBMScope *saved = ctx->current_scope;
            ctx->current_scope = py_scope_push_checked(ctx);
            // Bind each lambda param to the call-site arg's type.
            if (!ts_node_is_null(params) && !ts_node_is_null(args)) {
                uint32_t pn = ts_node_named_child_count(params);
                uint32_t an = ts_node_named_child_count(args);
                for (uint32_t pi = 0; pi < pn && pi < an; pi++) {
                    TSNode p = ts_node_named_child(params, pi);
                    TSNode a = ts_node_named_child(args, pi);
                    const char *pname = NULL;
                    if (strcmp(ts_node_type(p), "identifier") == 0) {
                        pname = py_node_text(ctx, p);
                    } else if (strcmp(ts_node_type(p), "default_parameter") == 0 ||
                               strcmp(ts_node_type(p), "typed_parameter") == 0) {
                        TSNode pi_n = ts_node_child_by_field_name(p, "name", 4);
                        if (!ts_node_is_null(pi_n) &&
                            strcmp(ts_node_type(pi_n), "identifier") == 0) {
                            pname = py_node_text(ctx, pi_n);
                        }
                    }
                    if (pname) {
                        const CBMType *arg_type = py_eval_expr_type(ctx, a);
                        py_scope_bind(ctx, pname, arg_type);
                    }
                }
            }
            // Set enclosing func to a synthetic <lambda> so emissions
            // attribute correctly (find_resolved by "<lambda>" works).
            const char *prev_func = ctx->enclosing_func_qn;
            ctx->enclosing_func_qn = cbm_arena_sprintf(ctx->arena, "%s.<lambda>",
                                                       prev_func ? prev_func : ctx->module_qn);
            if (!ts_node_is_null(body)) {
                ctx->lambdas[lambda_idx].expanding = true;
                py_resolve_calls_in(ctx, body);
                ctx->lambdas[lambda_idx].expanding = false;
            }
            ctx->enclosing_func_qn = prev_func;
            py_scope_restore(ctx, saved);
            return;
        }
        /* Lexical identity takes precedence over same-named module symbols.
         * An ordinary local binding is also a hard shadow: if it is not a
         * proven callable alias, do not fall through and fabricate a direct
         * call to a module-level function with the same spelling. */
        const CBMVarBinding *binding = cbm_scope_lookup_binding(ctx->current_scope, fname);
        if (binding) {
            const char *alias_target = binding->callable_qn;
            if (alias_target) {
                py_emit_resolved_call_reason(ctx, alias_target, "lsp_callable_alias", 0.97f, fname,
                                             call_node);
                return;
            }
            const CBMType *in_scope = binding->type ? binding->type : cbm_type_unknown();
            if (!cbm_type_is_unknown(in_scope) && in_scope->kind == CBM_TYPE_NAMED) {
                const char *qn = in_scope->data.named.qualified_name;
                const char *tail = qn ? strrchr(qn, '.') : NULL;
                const char *qn_short = tail ? tail + 1 : qn;
                bool imported_alias = false;

                /* #988 is specifically an import binding. Gate the
                 * reason-based alias join by import metadata so an unrelated
                 * local NAMED value cannot masquerade as an imported callable. */
                if (qn && qn_short && strcmp(qn_short, fname) != 0) {
                    for (int i = 0; i < ctx->import_count; i++) {
                        const char *local = ctx->import_local_names[i];
                        const char *import_qn = ctx->import_module_qns[i];
                        if (local && import_qn && strcmp(local, fname) == 0 &&
                            strcmp(import_qn, qn) == 0 && py_import_index_is_from_binding(ctx, i)) {
                            imported_alias = true;
                            break;
                        }
                    }
                }

                if (imported_alias) {
                    py_emit_resolved_call_reason(ctx, qn, "lsp_import_alias", 0.85f, fname,
                                                 call_node);
                } else if (qn && cbm_registry_lookup_type(ctx->registry, qn)) {
                    /* ClassName() binds to the __init__ the class declares
                     * itself. An inherited __init__ is not followed: B(A)
                     * without its own __init__ keeps the call on B, so a base
                     * constructor does not collect every subclass
                     * construction as its caller. Retarget only when this
                     * binding IS the class being called. An instance
                     * (`f = Foo(); f()`) keeps the class row: that call
                     * dispatches to __call__, and a reason-join would invent
                     * a Foo.__init__ edge. A builtins.* __init__ is not a
                     * project constructor, so the class target stays. */
                    const CBMRegisteredFunc *fi = NULL;
                    if (qn_short && strcmp(qn_short, fname) == 0) {
                        fi = cbm_registry_lookup_method(ctx->registry, qn, "__init__");
                    }
                    if (fi && fi->qualified_name &&
                        strncmp(fi->qualified_name, "builtins.", sizeof("builtins.") - 1) != 0) {
                        py_emit_resolved_call_reason(ctx, fi->qualified_name,
                                                     "lsp_constructor_init", 0.85f, fname,
                                                     call_node);
                    } else {
                        py_emit_resolved_call(ctx, qn, "lsp_constructor", 0.85f, call_node);
                    }
                }
            }
            return;
        }
        // Module-local function
        const CBMRegisteredFunc *f =
            cbm_registry_lookup_symbol(ctx->registry, ctx->module_qn, fname);
        if (f) {
            py_emit_resolved_call(ctx, f->qualified_name, "lsp_direct", 0.95f, call_node);
            return;
        }
        // Builtins (range / len / list / dict / str / int / print / ...).
        f = cbm_registry_lookup_symbol(ctx->registry, "builtins", fname);
        if (f) {
            py_emit_resolved_call(ctx, f->qualified_name, "lsp_builtin", 0.92f, call_node);
            return;
        }
        const CBMRegisteredType *rt = cbm_registry_lookup_type(
            ctx->registry, cbm_arena_sprintf(ctx->arena, "builtins.%s", fname));
        if (rt) {
            py_emit_resolved_call(ctx, rt->qualified_name, "lsp_builtin_constructor", 0.88f,
                                  call_node);
            return;
        }
        return;
    }

    // Subscript-as-call: `funcs["a"]()` where funcs is a registered
    // dict-literal dispatch table.
    if (!ctx->class_body_outer_scope && strcmp(fk, "subscript") == 0) {
        TSNode container = ts_node_child_by_field_name(fn, "value", 5);
        TSNode key = ts_node_child_by_field_name(fn, "subscript", 9);
        if (!ts_node_is_null(container) && !ts_node_is_null(key) &&
            strcmp(ts_node_type(container), "identifier") == 0 &&
            strcmp(ts_node_type(key), "string") == 0) {
            char *var_name = py_node_text(ctx, container);
            char *k_text = py_string_literal_value(ctx, key);
            if (var_name && k_text) {
                const char *tgt = py_lookup_dict_dispatch(ctx, var_name, k_text);
                if (tgt) {
                    /* The textual callee of `funcs["a"](v)` is the subscript base
                     * identifier ("funcs"), not the resolved target ("foo"), so
                     * stash it in `reason` for the join (see lsp_resolve.h). */
                    py_emit_resolved_call_reason(ctx, tgt, "lsp_dict_dispatch", 0.86f, var_name,
                                                 call_node);
                    return;
                }
            }
        }
    }

    if (strcmp(fk, "attribute") == 0) {
        TSNode obj = ts_node_child_by_field_name(fn, "object", 6);
        TSNode attr = ts_node_child_by_field_name(fn, "attribute", 9);
        if (ts_node_is_null(obj) || ts_node_is_null(attr))
            return;
        char *attr_name = py_node_text(ctx, attr);
        if (!attr_name)
            return;

        // super().method() — Python 3 super() returns a proxy bound to the
        // enclosing class's MRO. Resolve attr against the first base class
        // of the enclosing class (single-inheritance practical case).
        if (strcmp(ts_node_type(obj), "call") == 0) {
            TSNode super_fn = ts_node_child_by_field_name(obj, "function", 8);
            if (!ts_node_is_null(super_fn) && strcmp(ts_node_type(super_fn), "identifier") == 0) {
                char *super_name = py_node_text(ctx, super_fn);
                if (super_name && strcmp(super_name, "super") == 0 && ctx->enclosing_class_qn) {
                    const CBMRegisteredType *enclosing =
                        cbm_registry_lookup_type(ctx->registry, ctx->enclosing_class_qn);
                    if (enclosing && enclosing->embedded_types) {
                        // The proxy walks the enclosing class's C3 order, in which a
                        // diamond's shared base follows every class deriving from it:
                        // RadarrCalendarEntity(RadarrEntity, CalendarEntity) reaches
                        // CalendarEntity before Entity, which the first base reaches
                        // through its own ancestry. The base-by-base walk below stays for
                        // a hierarchy without a C3 order and for an undeclared __init__.
                        bool have_mro = false;
                        const CBMRegisteredFunc *sf = py_lookup_super_attribute(
                            ctx, ctx->enclosing_class_qn, attr_name, &have_mro);
                        if (sf) {
                            bool is_init = strcmp(attr_name, "__init__") == 0;
                            py_emit_resolved_call(ctx, sf->qualified_name,
                                                  is_init ? "lsp_super_init" : "lsp_super",
                                                  is_init ? 0.90f : 0.88f, call_node);
                            return;
                        }
                        for (int i = 0; enclosing->embedded_types[i]; i++) {
                            // super().__init__() is a constructor delegation:
                            // lsp_super_init is the MORE SPECIFIC, more accurate
                            // strategy than the generic lsp_super. Resolve __init__
                            // first and emit lsp_super_init — when the base both
                            // registers __init__ (py_lookup_attribute hits) and the
                            // generic super() proxy resolution applies, the generic
                            // lsp_super used to also be emitted at 0.88, outranking
                            // lsp_super_init (0.85) in the highest-confidence join so
                            // the specific strategy never landed on the edge. Handle
                            // __init__ BEFORE the generic lsp_super and rank it at
                            // least as high (0.90) so the constructor-delegation
                            // strategy wins. The plain super().method() form below is
                            // unchanged — it still emits lsp_super.
                            if (strcmp(attr_name, "__init__") == 0) {
                                const CBMRegisteredFunc *fi = py_lookup_attribute(
                                    ctx, enclosing->embedded_types[i], attr_name);
                                const char *init_qn =
                                    fi ? fi->qualified_name
                                       : cbm_arena_sprintf(ctx->arena, "%s.__init__",
                                                           enclosing->embedded_types[i]);
                                py_emit_resolved_call(ctx, init_qn, "lsp_super_init", 0.90f,
                                                      call_node);
                                return;
                            }
                            const CBMRegisteredFunc *f =
                                py_lookup_attribute(ctx, enclosing->embedded_types[i], attr_name);
                            if (f) {
                                py_emit_resolved_call(ctx, f->qualified_name, "lsp_super", 0.88f,
                                                      call_node);
                                return;
                            }
                        }
                    }
                }
            }
        }

        const CBMType *obj_type = py_eval_expr_type(ctx, obj);
        if (!obj_type)
            return;

        if (obj_type->kind == CBM_TYPE_MODULE) {
            const char *mod = obj_type->data.module.module_qn;
            // py_module_member also retries an in-project module written in its
            // short source form ("helpers") project-qualified; a genuinely
            // external module (requests, os) has no project def, so it stays
            // lsp_module_attr_unresolved below. It also answers a name the
            // module re-exports (`models.CharField`).
            PyModuleMember mm = py_module_member(ctx, mod, attr_name);
            if (mm.func) {
                py_emit_module_member_call(ctx, mm.func->qualified_name, "lsp_module_attr", 0.92f,
                                           attr_name, call_node);
                return;
            }
            if (mm.type) {
                py_emit_module_member_call(ctx, mm.type->qualified_name, "lsp_constructor", 0.88f,
                                           attr_name, call_node);
                return;
            }
            // Best-effort: emit "module.attr" QN — Phase 9 cross-file may fix up.
            const char *qn = cbm_arena_sprintf(ctx->arena, "%s.%s", mod, attr_name);
            py_emit_resolved_call(ctx, qn, "lsp_module_attr_unresolved", 0.55f, call_node);
            return;
        }
        if (obj_type->kind == CBM_TYPE_NAMED) {
            const CBMRegisteredFunc *f =
                py_lookup_attribute(ctx, obj_type->data.named.qualified_name, attr_name);
            if (f) {
                py_emit_resolved_call(ctx, f->qualified_name, "lsp_method", 0.9f, call_node);
                return;
            }
        }
        if (obj_type->kind == CBM_TYPE_BUILTIN && obj_type->data.builtin.name) {
            // Builtins -> "builtins.<typename>" in typeshed.
            const char *recv_qn =
                cbm_arena_sprintf(ctx->arena, "builtins.%s", obj_type->data.builtin.name);
            const CBMRegisteredFunc *f = py_lookup_attribute(ctx, recv_qn, attr_name);
            if (f) {
                py_emit_resolved_call(ctx, f->qualified_name, "lsp_builtin_method", 0.9f,
                                      call_node);
                return;
            }
        }
        if (obj_type->kind == CBM_TYPE_TEMPLATE && obj_type->data.template_type.template_name) {
            const char *tname = obj_type->data.template_type.template_name;
            const char *recv_qn = cbm_arena_sprintf(ctx->arena, "builtins.%s", tname);
            const CBMRegisteredFunc *f = py_lookup_attribute(ctx, recv_qn, attr_name);
            if (!f) {
                f = py_lookup_attribute(ctx, tname, attr_name);
            }
            if (f) {
                py_emit_resolved_call(ctx, f->qualified_name, "lsp_generic_method", 0.88f,
                                      call_node);
                return;
            }
        }
        if (obj_type->kind == CBM_TYPE_UNION) {
            // Try each non-None member; if exactly one matches, emit.
            int matches = 0;
            const CBMRegisteredFunc *hit = NULL;
            for (int i = 0; i < obj_type->data.union_type.count; i++) {
                const CBMType *m = obj_type->data.union_type.members[i];
                if (!m)
                    continue;
                if (m->kind == CBM_TYPE_BUILTIN && m->data.builtin.name &&
                    strcmp(m->data.builtin.name, "None") == 0)
                    continue;
                if (m->kind != CBM_TYPE_NAMED)
                    continue;
                const CBMRegisteredFunc *f =
                    py_lookup_attribute(ctx, m->data.named.qualified_name, attr_name);
                if (f) {
                    matches++;
                    hit = f;
                }
            }
            if (matches == 1 && hit) {
                py_emit_resolved_call(ctx, hit->qualified_name, "lsp_method_union", 0.85f,
                                      call_node);
                return;
            }
        }
        return;
    }
}

/* Detect `isinstance(x, T)` / `isinstance(x, (T1, T2))` and return
 * (var_name, narrowed_type). Returns true on match. */
static bool py_match_isinstance(PyLSPContext *ctx, TSNode call_node, char **out_name,
                                const CBMType **out_type) {
    if (ts_node_is_null(call_node))
        return false;
    if (strcmp(ts_node_type(call_node), "call") != 0)
        return false;
    TSNode fn = ts_node_child_by_field_name(call_node, "function", 8);
    if (ts_node_is_null(fn) || strcmp(ts_node_type(fn), "identifier") != 0)
        return false;
    char *fname = py_node_text(ctx, fn);
    if (!fname || strcmp(fname, "isinstance") != 0)
        return false;
    TSNode args = ts_node_child_by_field_name(call_node, "arguments", 9);
    if (ts_node_is_null(args) || ts_node_named_child_count(args) < 2)
        return false;
    TSNode var_node = ts_node_named_child(args, 0);
    TSNode type_node = ts_node_named_child(args, 1);
    if (ts_node_is_null(var_node) || strcmp(ts_node_type(var_node), "identifier") != 0)
        return false;
    char *name = py_node_text(ctx, var_node);
    if (!name)
        return false;
    char *tname = py_node_text(ctx, type_node);
    if (!tname)
        return false;
    *out_name = name;
    *out_type = py_resolve_annotation(ctx, tname);
    return true;
}

/* Walk through parenthesized expressions and walrus expressions to find
 * the underlying identifier of an `is None` operand. Returns the
 * identifier's text or NULL. */
static char *py_underlying_ident(PyLSPContext *ctx, TSNode node) {
    if (ts_node_is_null(node))
        return NULL;
    const char *k = ts_node_type(node);
    if (strcmp(k, "identifier") == 0) {
        return py_node_text(ctx, node);
    }
    if (strcmp(k, "parenthesized_expression") == 0) {
        if (ts_node_named_child_count(node) > 0) {
            return py_underlying_ident(ctx, ts_node_named_child(node, 0));
        }
    }
    if (strcmp(k, "named_expression") == 0 || strcmp(k, "assignment_expression") == 0) {
        TSNode left = ts_node_child_by_field_name(node, "name", 4);
        if (ts_node_is_null(left)) {
            left = ts_node_child_by_field_name(node, "left", 4);
        }
        if (!ts_node_is_null(left) && strcmp(ts_node_type(left), "identifier") == 0) {
            return py_node_text(ctx, left);
        }
    }
    return NULL;
}

/* Detect `x is None` / `x is not None` / `None is x` / etc. Walks
 * through parens and walrus to find the underlying identifier.
 * Returns 1 for "x is not None" (positive narrow), -1 for "x is None"
 * (negative), 0 otherwise. */
static int py_match_is_none(PyLSPContext *ctx, TSNode test_node, char **out_name) {
    if (ts_node_is_null(test_node))
        return 0;
    const char *k = ts_node_type(test_node);
    if (strcmp(k, "comparison_operator") == 0) {
        uint32_t cn = ts_node_child_count(test_node);
        TSNode left = {0}, right = {0};
        bool is_not = false;
        bool is_is = false;
        bool first_named = true;
        for (uint32_t i = 0; i < cn; i++) {
            TSNode c = ts_node_child(test_node, i);
            if (ts_node_is_null(c))
                continue;
            if (ts_node_is_named(c)) {
                if (first_named) {
                    left = c;
                    first_named = false;
                } else {
                    right = c;
                }
                continue;
            }
            // Anonymous operator token. Tree-sitter Python emits "is" or
            // "is not" as a single token via the sym__is_not literal.
            char *tok = py_node_text(ctx, c);
            if (!tok)
                continue;
            if (strcmp(tok, "is") == 0)
                is_is = true;
            else if (strcmp(tok, "is not") == 0) {
                is_is = true;
                is_not = true;
            }
        }
        if (!is_is || ts_node_is_null(left) || ts_node_is_null(right))
            return 0;
        char *l_text = py_node_text(ctx, left);
        char *r_text = py_node_text(ctx, right);
        if (!l_text || !r_text)
            return 0;
        char *var_name = NULL;
        if (strcmp(r_text, "None") == 0) {
            var_name = py_underlying_ident(ctx, left);
        } else if (strcmp(l_text, "None") == 0) {
            var_name = py_underlying_ident(ctx, right);
        }
        if (!var_name)
            return 0;
        *out_name = var_name;
        return is_not ? 1 : -1;
    }
    return 0;
}

/* Compute the non-None component of a UNION type. If t is Optional[X]
 * (= Union[X, None]), return X; otherwise return t unchanged. */
static const CBMType *py_strip_none(PyLSPContext *ctx, const CBMType *t) {
    if (!t || t->kind != CBM_TYPE_UNION)
        return t;
    int n = t->data.union_type.count;
    int retained = 0;
    const CBMType **kept =
        (const CBMType **)cbm_arena_alloc(ctx->arena, (size_t)(n + 1) * sizeof(const CBMType *));
    if (!kept)
        return t;
    for (int i = 0; i < n; i++) {
        const CBMType *m = t->data.union_type.members[i];
        if (m && m->kind == CBM_TYPE_BUILTIN && m->data.builtin.name &&
            strcmp(m->data.builtin.name, "None") == 0)
            continue;
        kept[retained++] = m;
    }
    if (retained == 0)
        return cbm_type_unknown();
    if (retained == 1)
        return kept[0];
    return cbm_type_union(ctx->arena, kept, retained);
}

/* Walk a node's subtree looking for walrus expressions and bind their
 * targets in the enclosing function scope (PEP 572 semantics). */
static void py_bind_walrus_in(PyLSPContext *ctx, TSNode node) {
    if (ts_node_is_null(node))
        return;
    const char *k = ts_node_type(node);
    if (strcmp(k, "named_expression") == 0 || strcmp(k, "assignment_expression") == 0) {
        TSNode left = ts_node_child_by_field_name(node, "name", 4);
        if (ts_node_is_null(left)) {
            left = ts_node_child_by_field_name(node, "left", 4);
        }
        TSNode right = ts_node_child_by_field_name(node, "value", 5);
        if (ts_node_is_null(right)) {
            right = ts_node_child_by_field_name(node, "right", 5);
        }
        if (!ts_node_is_null(left) && !ts_node_is_null(right) &&
            strcmp(ts_node_type(left), "identifier") == 0) {
            char *name = py_node_text(ctx, left);
            if (name) {
                const CBMType *t = py_eval_expr_type(ctx, right);
                py_scope_bind(ctx, name, t);
            }
        }
    }
    uint32_t nc = ts_node_named_child_count(node);
    for (uint32_t i = 0; i < nc; i++) {
        py_bind_walrus_in(ctx, ts_node_named_child(node, i));
    }
}

/* Detect whether a block ends with `return`, `raise`, `break`, or
 * `continue` — meaning execution doesn't fall through past the if-block.
 * Used for early-return narrowing of the negated condition. */
static bool py_block_terminates(TSNode block) {
    if (ts_node_is_null(block))
        return false;
    uint32_t bnc = ts_node_named_child_count(block);
    if (bnc == 0)
        return false;
    TSNode last = ts_node_named_child(block, bnc - 1);
    const char *k = ts_node_type(last);
    return strcmp(k, "return_statement") == 0 || strcmp(k, "raise_statement") == 0 ||
           strcmp(k, "break_statement") == 0 || strcmp(k, "continue_statement") == 0;
}

/* Walk if_statement: push scope for consequence body when narrowing
 * applies, then recurse. If the consequence terminates (return/raise),
 * apply the negated narrow to the *enclosing* scope so subsequent
 * statements see the narrowed type. */
static void py_walk_if_statement(PyLSPContext *ctx, TSNode if_node) {
    TSNode cond = ts_node_child_by_field_name(if_node, "condition", 9);
    TSNode body = ts_node_child_by_field_name(if_node, "consequence", 11);
    TSNode alt = ts_node_child_by_field_name(if_node, "alternative", 11);

    py_invalidate_possible_bindings(ctx, body, 0);
    py_invalidate_possible_bindings(ctx, alt, 0);

    // Walrus bindings in the condition leak into the enclosing scope.
    py_bind_walrus_in(ctx, cond);

    // Always evaluate the condition (may bind via walrus, currently a no-op).
    py_resolve_calls_in(ctx, cond);

    // Recognize negated isinstance / is-None patterns for early-return
    // narrowing.
    bool neg_isinstance = false;
    char *neg_name = NULL;
    const CBMType *neg_type = NULL;
    int neg_none_kind = 0;
    char *neg_none_var = NULL;
    if (!ts_node_is_null(cond) && strcmp(ts_node_type(cond), "not_operator") == 0 &&
        ts_node_named_child_count(cond) > 0) {
        TSNode inner = ts_node_named_child(cond, 0);
        if (strcmp(ts_node_type(inner), "call") == 0) {
            char *nm = NULL;
            const CBMType *ty = NULL;
            if (py_match_isinstance(ctx, inner, &nm, &ty)) {
                neg_isinstance = true;
                neg_name = nm;
                neg_type = ty;
            }
        }
        // `if not (x is None):` -> equivalent to `if x is not None`
        // (rare, the next branch handles `is not None` directly).
    }
    // `if x is None: return` — after the if block, x is non-None.
    {
        char *nv = NULL;
        int nk = py_match_is_none(ctx, cond, &nv);
        if (nk == -1) { // x is None
            neg_none_kind = -1;
            neg_none_var = nv;
        }
    }

    // Consequence: maybe narrow.
    if (!ts_node_is_null(body)) {
        CBMScope *saved = ctx->current_scope;
        ctx->current_scope = py_scope_push_checked(ctx);

        // Try isinstance narrowing.
        if (!ts_node_is_null(cond) && strcmp(ts_node_type(cond), "call") == 0) {
            char *name = NULL;
            const CBMType *narrowed = NULL;
            if (py_match_isinstance(ctx, cond, &name, &narrowed) && name && narrowed) {
                py_scope_bind(ctx, name, narrowed);
            }
        }
        // Try `x is not None` narrowing.
        char *none_var = NULL;
        int none_kind = py_match_is_none(ctx, cond, &none_var);
        if (none_kind == 1 && none_var) {
            const CBMType *current = cbm_scope_lookup(ctx->current_scope, none_var);
            if (current && !cbm_type_is_unknown(current)) {
                const CBMType *narrowed = py_strip_none(ctx, current);
                py_scope_bind(ctx, none_var, narrowed);
            }
        }

        py_resolve_calls_in(ctx, body);
        py_scope_restore(ctx, saved);
    }

    // Alternative branch: include else / elif. Recurse without narrowing —
    // the else branch's narrowing is the negation, which we don't model in v1.
    if (!ts_node_is_null(alt)) {
        py_resolve_calls_in(ctx, alt);
    }

    // Early-return narrowing: if the consequence block terminates and the
    // condition negates a type guard, apply the *positive* narrow to the
    // enclosing scope so subsequent statements see the narrowed type.
    if (!ts_node_is_null(body) && py_block_terminates(body)) {
        if (neg_isinstance && neg_name && neg_type) {
            py_scope_bind(ctx, neg_name, neg_type);
        }
        if (neg_none_kind == -1 && neg_none_var) {
            // `if x is None: return` -> narrow x to non-None afterwards.
            const CBMType *current = cbm_scope_lookup(ctx->current_scope, neg_none_var);
            if (current && !cbm_type_is_unknown(current)) {
                const CBMType *narrowed = py_strip_none(ctx, current);
                py_scope_bind(ctx, neg_none_var, narrowed);
            }
        }
    }
}

/* Map a Python infix operator token to its dunder method name. */
static const char *py_binop_dunder(const char *op_text) {
    if (!op_text)
        return NULL;
    if (strcmp(op_text, "+") == 0)
        return "__add__";
    if (strcmp(op_text, "-") == 0)
        return "__sub__";
    if (strcmp(op_text, "*") == 0)
        return "__mul__";
    if (strcmp(op_text, "/") == 0)
        return "__truediv__";
    if (strcmp(op_text, "//") == 0)
        return "__floordiv__";
    if (strcmp(op_text, "%") == 0)
        return "__mod__";
    if (strcmp(op_text, "**") == 0)
        return "__pow__";
    if (strcmp(op_text, "<<") == 0)
        return "__lshift__";
    if (strcmp(op_text, ">>") == 0)
        return "__rshift__";
    if (strcmp(op_text, "&") == 0)
        return "__and__";
    if (strcmp(op_text, "|") == 0)
        return "__or__";
    if (strcmp(op_text, "^") == 0)
        return "__xor__";
    if (strcmp(op_text, "@") == 0)
        return "__matmul__";
    return NULL;
}

/* If `recv` is a user-defined NAMED type that defines `dunder`, emit a CALLS
 * edge to that dunder method (operator-overload / subscript desugaring).  This
 * models `a + b` → T.__add__ and `s[k]` → T.__getitem__ as calls.
 *
 * Requires a typed receiver.  An UNTYPED receiver (e.g. the unannotated
 * parameter in `def run(s): return s[0]`) is intentionally left unresolved:
 * guessing the sole class that declares the dunder would mis-resolve ordinary
 * built-in subscripts/operators (`some_list[0]`, `a + b` on ints) onto an
 * unrelated user class, so we only resolve when the receiver type is known. */
static void py_emit_dunder_call(PyLSPContext *ctx, const CBMType *recv, const char *dunder,
                                TSNode site) {
    if (!recv || recv->kind != CBM_TYPE_NAMED || !dunder)
        return;
    const CBMRegisteredFunc *f = py_lookup_attribute(ctx, recv->data.named.qualified_name, dunder);
    if (f && f->qualified_name) {
        py_emit_resolved_call(ctx, f->qualified_name, "lsp_operator_dunder", 0.85f, site);
        /* A subscript (`s[k]`) / binary_operator (`a + b`) is not a syntactic
         * `call` node, so the extractor produced no CBMCall for it and the
         * resolved_call above would never be matched into a CALLS edge. Inject
         * a synthetic CBMCall keyed on (enclosing_func_qn, short dunder name)
         * so resolve_file_calls can pair it with the resolved entry. The
         * resolved callee QN ends in the dunder, so its short name == dunder.
         * Mirrors rust_inject_syn_call. */
        if (ctx->syn_calls && ctx->arena && ctx->enclosing_func_qn) {
            uint32_t site_start = ts_node_start_byte(site);
            uint32_t site_end = ts_node_end_byte(site);
            for (int i = 0; i < ctx->syn_calls->count; i++) {
                const CBMCall *existing = &ctx->syn_calls->items[i];
                if (existing->requires_lsp_resolution && existing->callee_name &&
                    existing->enclosing_func_qn && strcmp(existing->callee_name, dunder) == 0 &&
                    strcmp(existing->enclosing_func_qn, ctx->enclosing_func_qn) == 0 &&
                    existing->site_start_byte == site_start &&
                    existing->site_end_byte == site_end) {
                    return;
                }
            }
            CBMCall call;
            memset(&call, 0, sizeof(call));
            call.callee_name = cbm_arena_strdup(ctx->arena, dunder);
            call.enclosing_func_qn = ctx->enclosing_func_qn;
            call.start_line = (int)ts_node_start_point(site).row + 1;
            call.site_start_byte = site_start;
            call.site_end_byte = site_end;
            call.requires_lsp_resolution = true;
            cbm_calls_push(ctx->syn_calls, ctx->arena, call);
        }
    } else if (recv->data.named.qualified_name) {
        /* The per-file registry cannot see an imported class's dunder method.
         * Preserve this source-exact semantic candidate so the fused parallel
         * pipeline knows a cross-file pass is still required. No carrier is
         * injected until the project registry proves the target. */
        const char *candidate =
            cbm_arena_sprintf(ctx->arena, "%s.%s", recv->data.named.qualified_name, dunder);
        py_emit_resolved_call_reason(ctx, candidate, "lsp_unresolved", 0.0f,
                                     "operator_method_not_in_registry", site);
    }
}

/* A class comprehension evaluates its leftmost iterable in the class frame,
 * but the implicit body scope skips class locals. Nested comprehensions keep
 * the surrounding comprehension frame. Keep class execution marked active so
 * legacy bare-name dispatch cannot bypass either frame's lexical bindings. */
static void py_resolve_class_comprehension(PyLSPContext *ctx, TSNode node) {
    if (ctx->eval_failure)
        return;
    PyKids kids = py_kids(ctx->arena, node);
    uint32_t first_for = kids.n;
    TSNode first_right = {0};
    for (uint32_t i = 0; i < kids.n && !ctx->eval_failure; i++) {
        TSNode child = py_kid(&kids, i);
        if (strcmp(ts_node_type(child), "for_in_clause") == 0) {
            first_for = i;
            first_right = ts_node_child_by_field_name(child, "right", 5);
            break;
        }
    }
    if (first_for == kids.n)
        return;
    const CBMType *first_type = py_eval_expr_type(ctx, first_right);
    py_resolve_calls_in(ctx, first_right);
    if (ctx->eval_failure)
        return;
    const CBMType *first_elem = py_iterable_element_type(ctx, first_type);
    CBMScope *saved_scope = ctx->current_scope;
    bool saved_comprehension = ctx->class_body_in_comprehension;
    CBMScope *parent = saved_comprehension ? saved_scope : ctx->class_body_outer_scope;
    CBMScope *frame = py_class_frame_push(ctx, parent);
    if (!frame)
        return;
    py_scope_restore(ctx, frame);
    ctx->class_body_in_comprehension = true;
    /* Clauses precede the body at evaluation time, although tree-sitter stores
     * the body first. Walk each iterable/filter only once, before later binds. */
    for (uint32_t i = first_for; i < kids.n && !ctx->eval_failure; i++) {
        TSNode child = py_kid(&kids, i);
        if (strcmp(ts_node_type(child), "for_in_clause") == 0) {
            TSNode left = ts_node_child_by_field_name(child, "left", 4);
            const CBMType *elem = first_elem;
            if (i != first_for) {
                TSNode right = ts_node_child_by_field_name(child, "right", 5);
                const CBMType *iter = py_eval_expr_type(ctx, right);
                py_resolve_calls_in(ctx, right);
                if (ctx->eval_failure)
                    break;
                elem = py_iterable_element_type(ctx, iter);
            }
            py_bind_for_target(ctx, left, elem);
        } else {
            py_resolve_calls_in(ctx, child);
        }
    }
    for (uint32_t i = 0; i < first_for && !ctx->eval_failure; i++)
        py_resolve_calls_in(ctx, py_kid(&kids, i));
    ctx->class_body_in_comprehension = saved_comprehension;
    py_scope_restore(ctx, saved_scope);
}

static void py_resolve_calls_in_inner(PyLSPContext *ctx, TSNode node) {
    if (!ctx || ts_node_is_null(node))
        return;
    const char *k = ts_node_type(node);

    // Statement-level binding effects.
    py_process_statement(ctx, node);

    // Emit call entry if applicable.
    if (strcmp(k, "call") == 0) {
        py_resolve_value_references_at(ctx, node);
        py_emit_call_for(ctx, node);
    }

    // Operator-overload desugaring: `a + b` calls type(a).__add__,
    // `s[k]` calls type(s).__getitem__.  Only emit when the receiver is a
    // user-defined type that actually declares the dunder (built-ins resolve
    // to typeshed and would create noisy edges).
    if (strcmp(k, "binary_operator") == 0) {
        TSNode left = ts_node_child_by_field_name(node, "left", 4);
        TSNode op = ts_node_child_by_field_name(node, "operator", 8);
        if (!ts_node_is_null(left) && !ts_node_is_null(op)) {
            const char *dunder = py_binop_dunder(py_node_text(ctx, op));
            if (dunder) {
                py_emit_dunder_call(ctx, py_eval_expr_type(ctx, left), dunder, node);
            }
        }
    } else if (strcmp(k, "subscript") == 0) {
        TSNode value = ts_node_child_by_field_name(node, "value", 5);
        if (!ts_node_is_null(value)) {
            py_emit_dunder_call(ctx, py_eval_expr_type(ctx, value), "__getitem__", node);
        }
    }

    // if_statement gets special-case narrowing.
    if (strcmp(k, "if_statement") == 0) {
        py_walk_if_statement(ctx, node);
        return;
    }

    // match/case (PEP 634): subject narrows per case-pattern.
    if (strcmp(k, "match_statement") == 0) {
        TSNode subject = ts_node_child_by_field_name(node, "subject", 7);
        TSNode body = ts_node_child_by_field_name(node, "body", 4);
        // Subject identifier (best-effort — only narrow when the subject
        // is a single identifier).
        char *subject_name = NULL;
        if (!ts_node_is_null(subject) && strcmp(ts_node_type(subject), "identifier") == 0) {
            subject_name = py_node_text(ctx, subject);
        }
        py_resolve_calls_in(ctx, subject);
        if (!ts_node_is_null(body)) {
            uint32_t bcc = ts_node_named_child_count(body);
            for (uint32_t i = 0; i < bcc; i++) {
                TSNode case_clause = ts_node_named_child(body, i);
                if (strcmp(ts_node_type(case_clause), "case_clause") != 0)
                    continue;
                CBMScope *saved = ctx->current_scope;
                ctx->current_scope = py_scope_push_checked(ctx);

                // Pattern is the first non-block named child; consequence
                // is the block.
                TSNode pattern = {0}, conseq = {0};
                uint32_t cnc = ts_node_named_child_count(case_clause);
                for (uint32_t j = 0; j < cnc; j++) {
                    TSNode c = ts_node_named_child(case_clause, j);
                    const char *ck = ts_node_type(c);
                    if (strcmp(ck, "block") == 0) {
                        conseq = c;
                        break;
                    }
                    if (ts_node_is_null(pattern))
                        pattern = c;
                }

                // The pattern field is a `case_pattern` wrapper around the
                // actual pattern type (class_pattern, sequence_pattern, etc).
                // Some grammar versions wrap further in `pattern`. Walk
                // through both wrappers.
                TSNode actual_pattern = pattern;
                for (int unwrap = 0; unwrap < 3; unwrap++) {
                    if (ts_node_is_null(actual_pattern))
                        break;
                    const char *apk = ts_node_type(actual_pattern);
                    if ((strcmp(apk, "case_pattern") == 0 || strcmp(apk, "pattern") == 0 ||
                         strcmp(apk, "_simple_pattern") == 0) &&
                        ts_node_named_child_count(actual_pattern) > 0) {
                        actual_pattern = ts_node_named_child(actual_pattern, 0);
                        continue;
                    }
                    break;
                }
                // Class pattern: case Foo(a, b): -> bind subject to NAMED(Foo),
                // bind a / b to UNKNOWN (field-type extraction is a v1.1 task).
                if (subject_name && !ts_node_is_null(actual_pattern) &&
                    strcmp(ts_node_type(actual_pattern), "class_pattern") == 0) {
                    if (ts_node_named_child_count(actual_pattern) > 0) {
                        TSNode cls = ts_node_named_child(actual_pattern, 0);
                        char *cls_text = py_node_text(ctx, cls);
                        if (cls_text) {
                            const CBMType *narrowed = py_resolve_annotation(ctx, cls_text);
                            py_scope_bind(ctx, subject_name, narrowed);
                        }
                    }
                    // Bind capture sub-patterns to UNKNOWN.
                    for (uint32_t j = 1; j < ts_node_named_child_count(actual_pattern); j++) {
                        TSNode sub = ts_node_named_child(actual_pattern, j);
                        if (strcmp(ts_node_type(sub), "capture_pattern") == 0) {
                            if (ts_node_named_child_count(sub) > 0) {
                                TSNode id = ts_node_named_child(sub, 0);
                                char *nm = py_node_text(ctx, id);
                                if (nm)
                                    py_scope_bind(ctx, nm, cbm_type_unknown());
                            }
                        }
                    }
                }
                // Sequence pattern: `case [head, *tail]:` / `case (a, b):`
                // — for each capture pattern element, bind to the
                // subject's iterable element type. Star-rest binds to
                // list[elem]. Tree-sitter wraps each list_pattern child
                // in another case_pattern; a capture appears as a
                // dotted_name -> identifier; a splat as splat_pattern.
                if (subject_name && !ts_node_is_null(actual_pattern) &&
                    (strcmp(ts_node_type(actual_pattern), "list_pattern") == 0 ||
                     strcmp(ts_node_type(actual_pattern), "tuple_pattern") == 0)) {
                    const CBMType *subj_t = cbm_scope_lookup(ctx->current_scope, subject_name);
                    const CBMType *elem_t = py_iterable_element_type(ctx, subj_t);
                    uint32_t pn = ts_node_named_child_count(actual_pattern);
                    for (uint32_t j = 0; j < pn; j++) {
                        TSNode elem = ts_node_named_child(actual_pattern, j);
                        // Unwrap inner case_pattern.
                        if (!ts_node_is_null(elem) &&
                            strcmp(ts_node_type(elem), "case_pattern") == 0 &&
                            ts_node_named_child_count(elem) > 0) {
                            elem = ts_node_named_child(elem, 0);
                        }
                        if (ts_node_is_null(elem))
                            continue;
                        const char *ek = ts_node_type(elem);
                        // Capture pattern: dotted_name wrapping identifier.
                        if (strcmp(ek, "dotted_name") == 0 && ts_node_named_child_count(elem) > 0) {
                            TSNode id = ts_node_named_child(elem, 0);
                            if (strcmp(ts_node_type(id), "identifier") == 0) {
                                char *nm = py_node_text(ctx, id);
                                if (nm && elem_t) {
                                    py_scope_bind(ctx, nm, elem_t);
                                }
                            }
                            continue;
                        }
                        if (strcmp(ek, "identifier") == 0) {
                            char *nm = py_node_text(ctx, elem);
                            if (nm && elem_t) {
                                py_scope_bind(ctx, nm, elem_t);
                            }
                            continue;
                        }
                        if (strcmp(ek, "splat_pattern") == 0 ||
                            strcmp(ek, "list_splat_pattern") == 0 ||
                            strcmp(ek, "star_pattern") == 0) {
                            // splat_pattern's first named child is the
                            // identifier (or another wrapper).
                            TSNode id = {0};
                            uint32_t snc = ts_node_named_child_count(elem);
                            for (uint32_t s = 0; s < snc; s++) {
                                TSNode c = ts_node_named_child(elem, s);
                                if (strcmp(ts_node_type(c), "identifier") == 0) {
                                    id = c;
                                    break;
                                }
                                if (strcmp(ts_node_type(c), "dotted_name") == 0 &&
                                    ts_node_named_child_count(c) > 0) {
                                    id = ts_node_named_child(c, 0);
                                    break;
                                }
                            }
                            if (!ts_node_is_null(id)) {
                                char *nm = py_node_text(ctx, id);
                                if (nm && elem_t) {
                                    const CBMType *lst =
                                        cbm_type_template(ctx->arena, "list", &elem_t, 1);
                                    py_scope_bind(ctx, nm, lst);
                                }
                            }
                        }
                    }
                }

                if (!ts_node_is_null(conseq)) {
                    py_resolve_calls_in(ctx, conseq);
                }
                py_scope_restore(ctx, saved);
            }
        }
        return;
    }

    // Comprehensions push a scope and bind for_in_clause loop vars to the
    // iterable's element type, then walk inner expressions.
    if (strcmp(k, "list_comprehension") == 0 || strcmp(k, "dictionary_comprehension") == 0 ||
        strcmp(k, "set_comprehension") == 0 || strcmp(k, "generator_expression") == 0) {
        if (ctx->class_body_outer_scope) {
            py_resolve_class_comprehension(ctx, node);
            return;
        }
        CBMScope *saved = ctx->current_scope;
        ctx->current_scope = py_scope_push_checked(ctx);
        uint32_t cnc = ts_node_named_child_count(node);
        // First pass: bind for-clause vars (process in source order so
        // chained comprehensions like `for x in xs for y in x.ys` see
        // x bound by the time we evaluate x.ys).
        for (uint32_t i = 0; i < cnc; i++) {
            TSNode child = ts_node_named_child(node, i);
            const char *ck = ts_node_type(child);
            if (strcmp(ck, "for_in_clause") == 0) {
                TSNode left = ts_node_child_by_field_name(child, "left", 4);
                TSNode right = ts_node_child_by_field_name(child, "right", 5);
                const CBMType *elem_type = cbm_type_unknown();
                if (!ts_node_is_null(right)) {
                    const CBMType *iter_type = py_eval_expr_type(ctx, right);
                    elem_type = py_iterable_element_type(ctx, iter_type);
                }
                py_bind_for_target(ctx, left, elem_type);
            }
        }
        // Second pass: recurse into all children (body + filter clauses
        // benefit from the bound vars).
        for (uint32_t i = 0; i < cnc; i++) {
            py_resolve_calls_in(ctx, ts_node_named_child(node, i));
        }
        py_scope_restore(ctx, saved);
        return;
    }

    // Recurse: children. We don't push scope for control-flow blocks
    // here (Python scoping is function-level apart from comprehension /
    // lambda / class), but we do for nested function / class / lambda.
    if (strcmp(k, "function_definition") == 0 || strcmp(k, "lambda") == 0) {
        // These are processed by the top-level pass; skip recursion to
        // avoid double-walking their bodies.
        return;
    }

    if (strcmp(k, "class_definition") == 0) {
        py_exec_class_definition(ctx, node);
        return;
    }

    PyKids nk = py_kids(ctx->arena, node);
    for (uint32_t i = 0; i < nk.n && !ctx->eval_failure; i++) {
        py_resolve_calls_in(ctx, py_kid(&nk, i));
    }
}

/* ── function / class processing ───────────────────────────────── */

/* Parse a type-annotation TEXT into a CBMType without requiring a
 * PyLSPContext. Handles `Optional[T]`, `Union[A, B]`, `X | Y`, generic
 * containers (`list[T]` -> TEMPLATE), forward-reference quotes, and
 * builtin scalar names. Used by py_register_def, which runs before any
 * context is available. When module_qn is non-NULL, bare class names
 * are qualified as "<module_qn>.<name>" so registry lookups match. */
static const CBMType *py_parse_type_text(CBMArena *arena, const char *ann);
static const CBMType *py_parse_type_text_qn(CBMArena *arena, const char *ann,
                                            const char *module_qn);

/* Trim ASCII whitespace from both ends of an arena-allocated copy. */
static char *py_trim_ws(CBMArena *arena, const char *start, size_t len) {
    while (len > 0 && (start[0] == ' ' || start[0] == '\t')) {
        start++;
        len--;
    }
    while (len > 0 && (start[len - 1] == ' ' || start[len - 1] == '\t'))
        len--;
    char *out = (char *)cbm_arena_alloc(arena, len + 1);
    if (!out)
        return NULL;
    memcpy(out, start, len);
    out[len] = '\0';
    return out;
}

/* Split a comma-separated argument string at depth 0 (ignoring commas
 * inside [], (), {}). Returns NULL-terminated arena array of trimmed
 * substring copies. Caller passes the inside of `[...]`. */
static const char **py_split_subscript_args(CBMArena *arena, const char *s, int *out_n) {
    if (!s) {
        *out_n = 0;
        return NULL;
    }
    int cap = 8;
    const char **out =
        (const char **)cbm_arena_alloc(arena, (size_t)(cap + 1) * sizeof(const char *));
    if (!out) {
        *out_n = 0;
        return NULL;
    }
    int n = 0;
    int depth = 0;
    size_t len = strlen(s);
    size_t start = 0;
    for (size_t i = 0; i <= len; i++) {
        char c = (i < len) ? s[i] : ',';
        if (c == '[' || c == '(' || c == '{')
            depth++;
        else if (c == ']' || c == ')' || c == '}')
            depth--;
        else if (c == ',' && depth == 0) {
            char *part = py_trim_ws(arena, s + start, i - start);
            if (part && part[0]) {
                if (n >= cap) {
                    int new_cap = cap * 2;
                    const char **grown = (const char **)cbm_arena_alloc(
                        arena, (size_t)(new_cap + 1) * sizeof(const char *));
                    if (grown) {
                        for (int q = 0; q < n; q++)
                            grown[q] = out[q];
                        out = grown;
                        cap = new_cap;
                    }
                }
                if (n < cap)
                    out[n++] = part;
            }
            start = i + 1;
        }
    }
    out[n] = NULL;
    *out_n = n;
    return out;
}

static const CBMType *py_parse_type_text_qn(CBMArena *arena, const char *ann,
                                            const char *module_qn) {
    if (!ann || !ann[0])
        return cbm_type_unknown();
    size_t len = strlen(ann);

    if (len >= 2 && (ann[0] == '"' || ann[0] == '\'') && ann[len - 1] == ann[0]) {
        char *unquoted = (char *)cbm_arena_alloc(arena, len - 1);
        if (unquoted) {
            memcpy(unquoted, ann + 1, len - 2);
            unquoted[len - 2] = '\0';
            return py_parse_type_text_qn(arena, unquoted, module_qn);
        }
    }

    const char *lb = strchr(ann, '[');
    if (lb && len > 0 && ann[len - 1] == ']') {
        size_t base_len = (size_t)(lb - ann);
        char *base = (char *)cbm_arena_alloc(arena, base_len + 1);
        if (base) {
            memcpy(base, ann, base_len);
            base[base_len] = '\0';
            char *btrim = base;
            while (*btrim == ' ')
                btrim++;
            size_t blen = strlen(btrim);
            while (blen > 0 && btrim[blen - 1] == ' ') {
                btrim[blen - 1] = '\0';
                blen--;
            }
            size_t inner_start = (size_t)(lb - ann) + 1;
            size_t inner_len = len - inner_start - 1;
            char *args_text = (char *)cbm_arena_alloc(arena, inner_len + 1);
            if (args_text) {
                memcpy(args_text, ann + inner_start, inner_len);
                args_text[inner_len] = '\0';
                int arg_n = 0;
                const char **arg_strs = py_split_subscript_args(arena, args_text, &arg_n);
                const CBMType **arg_types = NULL;
                if (arg_n > 0 && arg_strs) {
                    arg_types = (const CBMType **)cbm_arena_alloc(
                        arena, (size_t)(arg_n + 1) * sizeof(const CBMType *));
                    if (arg_types) {
                        for (int i = 0; i < arg_n; i++) {
                            arg_types[i] = py_parse_type_text_qn(arena, arg_strs[i], module_qn);
                        }
                        arg_types[arg_n] = NULL;
                    }
                }
                if (strcmp(btrim, "Optional") == 0 || strcmp(btrim, "typing.Optional") == 0) {
                    if (arg_types && arg_n >= 1 && arg_types[0]) {
                        return cbm_type_optional(arena, arg_types[0]);
                    }
                }
                if (strcmp(btrim, "Union") == 0 || strcmp(btrim, "typing.Union") == 0) {
                    if (arg_types && arg_n > 0) {
                        return cbm_type_union(arena, arg_types, arg_n);
                    }
                }
                // Type-wrapper annotations that don't change the underlying
                // type for resolution: ClassVar[T], Final[T], InitVar[T],
                // ReadOnly[T], Required[T], NotRequired[T], Annotated[T, ...]
                // (drop metadata), Mapped[T] (SQLAlchemy 2.0), and
                // typing_extensions/typing variants of all these. Returns
                // the wrapped type T.
                static const char *wrapper_names[] = {"ClassVar",
                                                      "Final",
                                                      "InitVar",
                                                      "ReadOnly",
                                                      "Required",
                                                      "NotRequired",
                                                      "Annotated",
                                                      "Mapped",
                                                      "WriteOnlyMapped",
                                                      "DynamicMapped", // SQLAlchemy
                                                      "typing.ClassVar",
                                                      "typing.Final",
                                                      "typing.Annotated",
                                                      "typing.Required",
                                                      "typing.NotRequired",
                                                      "typing.ReadOnly",
                                                      "typing_extensions.ClassVar",
                                                      "typing_extensions.Final",
                                                      "typing_extensions.Annotated",
                                                      "typing_extensions.Required",
                                                      "typing_extensions.NotRequired",
                                                      "typing_extensions.ReadOnly",
                                                      "dataclasses.InitVar",
                                                      NULL};
                for (int wi = 0; wrapper_names[wi]; wi++) {
                    if (strcmp(btrim, wrapper_names[wi]) == 0) {
                        if (arg_types && arg_n >= 1 && arg_types[0]) {
                            return arg_types[0];
                        }
                    }
                }
                // Type[T] / type[T] -> instance of T's metaclass... for
                // resolution purposes, treat as the class itself.
                if (strcmp(btrim, "Type") == 0 || strcmp(btrim, "type") == 0 ||
                    strcmp(btrim, "typing.Type") == 0) {
                    if (arg_types && arg_n >= 1 && arg_types[0]) {
                        return arg_types[0];
                    }
                }
                if (arg_types && arg_n > 0) {
                    return cbm_type_template(arena, btrim, arg_types, arg_n);
                }
                return py_parse_type_text_qn(arena, btrim, module_qn);
            }
        }
    }

    {
        int cap = 4;
        const char **out =
            (const char **)cbm_arena_alloc(arena, (size_t)(cap + 1) * sizeof(const char *));
        if (out) {
            int onum = 0;
            int d2 = 0;
            size_t start = 0;
            bool seen_pipe = false;
            for (size_t j = 0; j <= len; j++) {
                char cc = (j < len) ? ann[j] : '|';
                if (cc == '[' || cc == '(' || cc == '{')
                    d2++;
                else if (cc == ']' || cc == ')' || cc == '}')
                    d2--;
                else if (cc == '|' && d2 == 0) {
                    seen_pipe = (j < len);
                    char *p = py_trim_ws(arena, ann + start, j - start);
                    if (p && p[0] && onum < cap)
                        out[onum++] = p;
                    start = j + 1;
                }
            }
            if (seen_pipe && onum >= 2) {
                const CBMType **members = (const CBMType **)cbm_arena_alloc(
                    arena, (size_t)(onum + 1) * sizeof(const CBMType *));
                if (members) {
                    for (int j = 0; j < onum; j++) {
                        members[j] = py_parse_type_text_qn(arena, out[j], module_qn);
                    }
                    return cbm_type_union(arena, members, onum);
                }
            }
        }
    }

    static const char *builtins[] = {"int",     "str",       "bool",   "float", "bytes", "None",
                                     "complex", "bytearray", "object", "type",  NULL};
    for (int i = 0; builtins[i]; i++) {
        if (strcmp(ann, builtins[i]) == 0) {
            return cbm_type_builtin(arena, ann);
        }
    }
    // Bare unqualified name: qualify with module_qn if it doesn't already
    // contain a dot. Skips obvious typing-module names so `Optional` /
    // `Self` / etc. don't end up qualified to the consumer's module.
    if (module_qn && !strchr(ann, '.')) {
        static const char *typing_names[] = {"Self",
                                             "Any",
                                             "None",
                                             "True",
                                             "False",
                                             "Iterator",
                                             "Iterable",
                                             "Generator",
                                             "AsyncIterator",
                                             "AsyncIterable",
                                             "Sequence",
                                             "MutableSequence",
                                             "Mapping",
                                             "MutableMapping",
                                             "Collection",
                                             "Container",
                                             "Reversible",
                                             "Optional",
                                             "Union",
                                             "Callable",
                                             "Awaitable",
                                             "Coroutine",
                                             "TypeVar",
                                             "ParamSpec",
                                             NULL};
        bool is_typing = false;
        for (int i = 0; typing_names[i]; i++) {
            if (strcmp(ann, typing_names[i]) == 0) {
                is_typing = true;
                break;
            }
        }
        if (!is_typing) {
            const char *qn = cbm_arena_sprintf(arena, "%s.%s", module_qn, ann);
            return cbm_type_named(arena, qn);
        }
    }
    return cbm_type_named(arena, ann);
}

typedef struct {
    const char *module_qn;
} PySignatureParamParserContext;

static const CBMType *py_signature_param_type_adapter(CBMArena *arena, const char *text,
                                                      void *parser_ctx) {
    const PySignatureParamParserContext *ctx = (const PySignatureParamParserContext *)parser_ctx;
    return py_parse_type_text_qn(arena, text, ctx ? ctx->module_qn : NULL);
}

static const CBMType *py_parse_type_text(CBMArena *arena, const char *ann) {
    return py_parse_type_text_qn(arena, ann, NULL);
}

/* Resolve a type-annotation text into a CBMType. Tries: scope lookup
 * (for imports / type aliases), module-qualified lookup in the registry,
 * then falls back to a bare NAMED. Strips quoted forward-reference
 * wrappers like `"Foo"` and converts subscripted forms `list[Foo]` /
 * `Optional[Foo]` / `Union[A, B]` into TEMPLATE / UNION shapes so
 * subsequent code can reach into element types for comprehensions
 * etc. */
static const CBMType *py_resolve_annotation(PyLSPContext *ctx, const char *ann) {
    if (!ann || !ann[0])
        return cbm_type_unknown();

    // Strip outer quotes for forward references: `"Foo"` -> `Foo`.
    size_t len = strlen(ann);
    if (len >= 2 && (ann[0] == '"' || ann[0] == '\'') && ann[len - 1] == ann[0]) {
        char *unquoted = (char *)cbm_arena_alloc(ctx->arena, len - 1);
        if (unquoted) {
            memcpy(unquoted, ann + 1, len - 2);
            unquoted[len - 2] = '\0';
            return py_resolve_annotation(ctx, unquoted);
        }
    }

    // Generic subscript: `list[Foo]` / `Optional[Foo]` / `Union[A, B]` /
    // `dict[K, V]`. Parse the base name + comma-split args at depth 0.
    const char *lb = strchr(ann, '[');
    if (lb && len > 0 && ann[len - 1] == ']') {
        size_t base_len = (size_t)(lb - ann);
        char *base = (char *)cbm_arena_alloc(ctx->arena, base_len + 1);
        if (base) {
            memcpy(base, ann, base_len);
            base[base_len] = '\0';
            // Trim leading/trailing whitespace from base.
            char *btrim = base;
            while (*btrim == ' ')
                btrim++;
            size_t blen = strlen(btrim);
            while (blen > 0 && btrim[blen - 1] == ' ') {
                btrim[blen - 1] = '\0';
                blen--;
            }
            // Args text: between [ and ]
            size_t inner_start = (size_t)(lb - ann) + 1;
            size_t inner_len = len - inner_start - 1;
            char *args_text = (char *)cbm_arena_alloc(ctx->arena, inner_len + 1);
            if (args_text) {
                memcpy(args_text, ann + inner_start, inner_len);
                args_text[inner_len] = '\0';
                int arg_n = 0;
                const char **arg_strs = py_split_subscript_args(ctx->arena, args_text, &arg_n);
                // Recursively resolve each arg to a CBMType.
                const CBMType **arg_types = NULL;
                if (arg_n > 0 && arg_strs) {
                    arg_types = (const CBMType **)cbm_arena_alloc(
                        ctx->arena, (size_t)(arg_n + 1) * sizeof(const CBMType *));
                    if (arg_types) {
                        for (int i = 0; i < arg_n; i++) {
                            arg_types[i] = py_resolve_annotation(ctx, arg_strs[i]);
                        }
                        arg_types[arg_n] = NULL;
                    }
                }

                // Optional[X] -> UNION(X, None)
                if (strcmp(btrim, "Optional") == 0 || strcmp(btrim, "typing.Optional") == 0) {
                    if (arg_types && arg_n >= 1 && arg_types[0]) {
                        return cbm_type_optional(ctx->arena, arg_types[0]);
                    }
                }
                // Union[A, B, ...] -> UNION
                if (strcmp(btrim, "Union") == 0 || strcmp(btrim, "typing.Union") == 0) {
                    if (arg_types && arg_n > 0) {
                        return cbm_type_union(ctx->arena, arg_types, arg_n);
                    }
                }
                // Type wrappers that don't change the underlying type:
                // ClassVar / Final / InitVar / ReadOnly / Required /
                // NotRequired / Annotated / Mapped (SQLAlchemy) / Type[T].
                // Returns the wrapped type T directly.
                static const char *wrapper_names[] = {"ClassVar",
                                                      "Final",
                                                      "InitVar",
                                                      "ReadOnly",
                                                      "Required",
                                                      "NotRequired",
                                                      "Annotated",
                                                      "Mapped",
                                                      "WriteOnlyMapped",
                                                      "DynamicMapped",
                                                      "Type",
                                                      "type",
                                                      "typing.ClassVar",
                                                      "typing.Final",
                                                      "typing.Annotated",
                                                      "typing.Required",
                                                      "typing.NotRequired",
                                                      "typing.ReadOnly",
                                                      "typing.Type",
                                                      "typing_extensions.ClassVar",
                                                      "typing_extensions.Final",
                                                      "typing_extensions.Annotated",
                                                      "typing_extensions.Required",
                                                      "typing_extensions.NotRequired",
                                                      "typing_extensions.ReadOnly",
                                                      "dataclasses.InitVar",
                                                      NULL};
                for (int wi = 0; wrapper_names[wi]; wi++) {
                    if (strcmp(btrim, wrapper_names[wi]) == 0) {
                        if (arg_types && arg_n >= 1 && arg_types[0]) {
                            return arg_types[0];
                        }
                    }
                }
                // Generic containers -> TEMPLATE
                if (arg_types && arg_n > 0) {
                    return cbm_type_template(ctx->arena, btrim, arg_types, arg_n);
                }
                return py_resolve_annotation(ctx, btrim);
            }
        }
    }

    // X | Y top-level union (PEP 604).
    {
        int depth = 0;
        for (size_t i = 0; i < len; i++) {
            char c = ann[i];
            if (c == '[' || c == '(' || c == '{')
                depth++;
            else if (c == ']' || c == ')' || c == '}')
                depth--;
            else if (c == '|' && depth == 0) {
                int n = 0;
                const char **parts = py_split_subscript_args(ctx->arena, ann, &n);
                // py_split splits on commas — manually split on '|' at depth 0
                (void)parts;
                (void)n;
                // Simpler: walk again splitting on '|'.
                int cap = 4;
                const char **out = (const char **)cbm_arena_alloc(
                    ctx->arena, (size_t)(cap + 1) * sizeof(const char *));
                if (!out)
                    break;
                int onum = 0;
                int d2 = 0;
                size_t start = 0;
                for (size_t j = 0; j <= len; j++) {
                    char cc = (j < len) ? ann[j] : '|';
                    if (cc == '[' || cc == '(' || cc == '{')
                        d2++;
                    else if (cc == ']' || cc == ')' || cc == '}')
                        d2--;
                    else if (cc == '|' && d2 == 0) {
                        char *p = py_trim_ws(ctx->arena, ann + start, j - start);
                        if (p && p[0] && onum < cap)
                            out[onum++] = p;
                        start = j + 1;
                    }
                }
                if (onum >= 2) {
                    const CBMType **members = (const CBMType **)cbm_arena_alloc(
                        ctx->arena, (size_t)(onum + 1) * sizeof(const CBMType *));
                    if (!members)
                        break;
                    for (int j = 0; j < onum; j++) {
                        members[j] = py_resolve_annotation(ctx, out[j]);
                    }
                    return cbm_type_union(ctx->arena, members, onum);
                }
                break;
            }
        }
    }

    const CBMType *t = cbm_scope_lookup(ctx->current_scope, ann);
    if (!cbm_type_is_unknown(t))
        return t;
    if (ctx->annotation_scope) {
        t = cbm_scope_lookup(ctx->annotation_scope, ann);
        if (!cbm_type_is_unknown(t))
            return t;
    }
    if (ctx->module_qn) {
        const char *qn = cbm_arena_sprintf(ctx->arena, "%s.%s", ctx->module_qn, ann);
        const CBMRegisteredType *rt = cbm_registry_lookup_type(ctx->registry, qn);
        if (rt)
            return cbm_type_named(ctx->arena, qn);
    }
    // Common builtin names go to BUILTIN.
    static const char *builtins[] = {"int",     "str",       "bool",   "float", "bytes", "None",
                                     "complex", "bytearray", "object", "type",  NULL};
    for (int i = 0; builtins[i]; i++) {
        if (strcmp(ann, builtins[i]) == 0) {
            return cbm_type_builtin(ctx->arena, ann);
        }
    }
    return cbm_type_named(ctx->arena, ann);
}

static void py_bind_parameters(PyLSPContext *ctx, TSNode params) {
    if (ts_node_is_null(params))
        return;
    uint32_t nc = ts_node_named_child_count(params);
    for (uint32_t i = 0; i < nc; i++) {
        TSNode p = ts_node_named_child(params, i);
        const char *pk = ts_node_type(p);

        TSNode ident_node = {0};
        TSNode type_node = {0};
        if (strcmp(pk, "identifier") == 0) {
            ident_node = p;
        } else if (strcmp(pk, "typed_parameter") == 0 ||
                   strcmp(pk, "typed_default_parameter") == 0) {
            if (ts_node_named_child_count(p) > 0)
                ident_node = ts_node_named_child(p, 0);
            type_node = ts_node_child_by_field_name(p, "type", 4);
        } else if (strcmp(pk, "default_parameter") == 0) {
            ident_node = ts_node_child_by_field_name(p, "name", 4);
        } else if (strcmp(pk, "list_splat_pattern") == 0 ||
                   strcmp(pk, "dictionary_splat_pattern") == 0) {
            if (ts_node_named_child_count(p) > 0)
                ident_node = ts_node_named_child(p, 0);
        } else if (strcmp(pk, "typed_default_parameter") == 0) {
            // already covered above by typed_parameter branch
        }
        // Splat-typed parameter: `*args: int` -> args is tuple[int, ...]
        // `**kwargs: V` -> kwargs is dict[str, V]. Tree-sitter Python
        // wraps these in typed_parameter where the inner is
        // list_splat_pattern / dictionary_splat_pattern. Handle here.
        bool is_splat = false;
        bool is_kwargs = false;
        if (strcmp(pk, "typed_parameter") == 0 && ts_node_named_child_count(p) > 0) {
            TSNode first = ts_node_named_child(p, 0);
            const char *fk = ts_node_type(first);
            if (strcmp(fk, "list_splat_pattern") == 0) {
                is_splat = true;
                if (ts_node_named_child_count(first) > 0)
                    ident_node = ts_node_named_child(first, 0);
            } else if (strcmp(fk, "dictionary_splat_pattern") == 0) {
                is_kwargs = true;
                if (ts_node_named_child_count(first) > 0)
                    ident_node = ts_node_named_child(first, 0);
            }
        }
        if (ts_node_is_null(ident_node))
            continue;

        char *name = py_node_text(ctx, ident_node);
        if (!name)
            continue;

        const CBMType *t = cbm_type_unknown();
        if (!ts_node_is_null(type_node)) {
            char *ann = py_node_text(ctx, type_node);
            t = py_resolve_annotation(ctx, ann);
        }
        // Splat parameter wrapping: *args: T -> tuple[T, ...]; **kwargs: T
        // -> dict[str, T]. The annotation gives the element type T; we
        // wrap it in the appropriate container.
        if (is_splat && t && !cbm_type_is_unknown(t)) {
            t = cbm_type_template(ctx->arena, "tuple", &t, 1);
        }
        if (is_kwargs && t && !cbm_type_is_unknown(t)) {
            const CBMType *str_t = cbm_type_builtin(ctx->arena, "str");
            const CBMType *args[3] = {str_t, t, NULL};
            t = cbm_type_template(ctx->arena, "dict", args, 2);
        }
        py_scope_bind(ctx, name, t);
    }
}

/* Bind a def or class statement of the current function body as a local of
 * that function (#1548): its graph QN extends the function's
 * (enclosing_func_qn.name), the QN extraction gives it. An undecorated def
 * registered with that QN becomes an exact callable alias; anything else
 * (decorated, overloaded, not registered) is a hard local shadow, so no call
 * falls through to a same-named module symbol. A class is bound by its type
 * when registered, else shadowed. A parameter of the same name is already a
 * local and keeps its own binding. */
static void py_bind_local_def(PyLSPContext *ctx, TSNode def, bool is_class) {
    TSNode name_node = ts_node_child_by_field_name(def, "name", 4);
    char *name = ts_node_is_null(name_node) ? NULL : py_node_text(ctx, name_node);
    if (!name || !name[0] || !ctx->enclosing_func_qn) {
        py_disable_callable_value_proof(ctx);
        return;
    }
    if (cbm_scope_lookup_local(ctx->current_scope, name))
        return;
    const char *qn = cbm_arena_sprintf(ctx->arena, "%s.%s", ctx->enclosing_func_qn, name);
    if (!qn) {
        py_disable_callable_value_proof(ctx);
        py_scope_bind(ctx, name, cbm_type_unknown());
        return;
    }
    if (is_class) {
        py_scope_bind(ctx, name,
                      cbm_registry_lookup_type(ctx->registry, qn) ? cbm_type_named(ctx->arena, qn)
                                                                  : cbm_type_unknown());
        return;
    }
    const CBMRegisteredFunc *func = cbm_registry_lookup_func(ctx->registry, qn);
    if (py_func_is_exact_callable_value(func)) {
        py_scope_bind_callable(ctx, name, cbm_type_unknown(), func->qualified_name);
    } else {
        py_scope_bind(ctx, name, cbm_type_unknown());
    }
}

/* Statements a function body nests further statements in. A def inside any of
 * them is still a local of the function; a nested def, class or lambda body
 * is a scope of its own and is never entered. */
static bool py_is_statement_block(const char *kind) {
    static const char *const kinds[] = {"block",
                                        "if_statement",
                                        "elif_clause",
                                        "else_clause",
                                        "for_statement",
                                        "while_statement",
                                        "try_statement",
                                        "except_clause",
                                        "except_group_clause",
                                        "finally_clause",
                                        "with_statement",
                                        "match_statement",
                                        "case_clause",
                                        NULL};
    for (int i = 0; kinds[i]; i++) {
        if (strcmp(kind, kinds[i]) == 0)
            return true;
    }
    return false;
}

/* Visit the def/class statements of a function body, including those inside
 * its compound statements: BIND binds each as a local (py_bind_local_def),
 * PROCESS walks each nested def's own body (py_process_function). */
static void py_visit_local_defs(PyLSPContext *ctx, TSNode block, PyLocalDefsMode mode, int depth) {
    if (!ctx || ctx->eval_failure || ts_node_is_null(block) || depth >= cbm_lsp_max_walk_depth())
        return;
    PyKids kids = py_kids(ctx->arena, block);
    for (uint32_t i = 0; i < kids.n && !ctx->eval_failure; i++) {
        TSNode c = py_kid(&kids, i);
        const char *ck = ts_node_type(c);
        TSNode def = c;
        if (strcmp(ck, "decorated_definition") == 0) {
            def = ts_node_child_by_field_name(c, "definition", 10);
            if (ts_node_is_null(def))
                continue;
            ck = ts_node_type(def);
        }
        if (strcmp(ck, "function_definition") == 0) {
            if (mode == PY_LOCAL_DEFS_BIND)
                py_bind_local_def(ctx, def, false);
            else
                py_process_function(ctx, def, ctx->enclosing_func_qn);
        } else if (strcmp(ck, "class_definition") == 0) {
            if (mode == PY_LOCAL_DEFS_BIND)
                py_bind_local_def(ctx, def, true);
            else
                py_process_class_in(ctx, def, ctx->enclosing_func_qn);
        } else if (py_is_statement_block(ck)) {
            py_visit_local_defs(ctx, c, mode, depth + 1);
        }
    }
}

static void py_process_function(PyLSPContext *ctx, TSNode func_node, const char *container_qn) {
    if (!ctx || ctx->eval_failure)
        return;
    TSNode name_node = ts_node_child_by_field_name(func_node, "name", 4);
    if (ts_node_is_null(name_node))
        return;
    char *fname = py_node_text(ctx, name_node);
    if (!fname || !fname[0])
        return;

    const char *prev_func = ctx->enclosing_func_qn;
    const char *base_qn = container_qn ? container_qn : ctx->module_qn;
    ctx->enclosing_func_qn = cbm_arena_sprintf(ctx->arena, "%s.%s", base_qn, fname);

    CBMScope *saved = ctx->current_scope;
    ctx->current_scope = py_scope_push_checked(ctx);

    TSNode params = ts_node_child_by_field_name(func_node, "parameters", 10);
    py_bind_parameters(ctx, params);

    // For methods, bind `self`/`cls` AFTER param walk so the receiver type
    // wins over the unannotated `self` / `cls` parameter declaration.
    if (ctx->enclosing_class_qn) {
        py_scope_bind(ctx, "self", cbm_type_named(ctx->arena, ctx->enclosing_class_qn));
        py_scope_bind(ctx, "cls", cbm_type_named(ctx->arena, ctx->enclosing_class_qn));
    }

    TSNode body = ts_node_child_by_field_name(func_node, "body", 4);
    if (!ts_node_is_null(body)) {
        /* Python resolves a bare name in the function's own scope first: every
         * def/class statement of the body binds a local for the whole body
         * (LEGB), whatever a module-level symbol of the same spelling says. */
        py_visit_local_defs(ctx, body, PY_LOCAL_DEFS_BIND, 0);
        py_resolve_calls_in(ctx, body);
        // Also descend into nested function definitions in the body.
        py_visit_local_defs(ctx, body, PY_LOCAL_DEFS_PROCESS, 0);
    }

    py_scope_restore(ctx, saved);
    ctx->enclosing_func_qn = prev_func;
}

/* Return true iff func_node's name is __init__ or __post_init__. */
static bool py_is_init_method(PyLSPContext *ctx, TSNode func_node) {
    TSNode name = ts_node_child_by_field_name(func_node, "name", 4);
    if (ts_node_is_null(name))
        return false;
    char *nm = py_node_text(ctx, name);
    return nm && (strcmp(nm, "__init__") == 0 || strcmp(nm, "__post_init__") == 0);
}

/* Decorator expressions of a decorated definition, in source order. They
 * evaluate in the scope enclosing the definition, before it is bound. A bare
 * `@name` is no call and emits nothing; `@name(args)` is one. */
static void py_resolve_decorators(PyLSPContext *ctx, TSNode decorated) {
    if (!ctx || ctx->eval_failure)
        return;
    PyKids kids = py_kids(ctx->arena, decorated);
    for (uint32_t i = 0; i < kids.n && !ctx->eval_failure; i++) {
        TSNode child = py_kid(&kids, i);
        if (strcmp(ts_node_type(child), "decorator") == 0)
            py_resolve_calls_in(ctx, child);
    }
}

/* Bind the name a class-body `def`/`class` statement defines in the class
 * frame, so later class-body statements see it (and never the same-named
 * module symbol). Its value is exact only for an undecorated function or a
 * registered class whose QN is known; anything else is an UNKNOWN shadow. */
static void py_bind_class_body_def(PyLSPContext *ctx, TSNode stmt) {
    if (ctx->eval_failure)
        return;
    TSNode def = stmt;
    bool decorated = strcmp(ts_node_type(stmt), "decorated_definition") == 0;
    if (decorated) {
        def = ts_node_child_by_field_name(stmt, "definition", 10);
        if (ts_node_is_null(def))
            return;
    }
    const char *kind = ts_node_type(def);
    bool is_class = strcmp(kind, "class_definition") == 0;
    if (!is_class && strcmp(kind, "function_definition") != 0)
        return;
    char *name = py_node_text(ctx, ts_node_child_by_field_name(def, "name", 4));
    if (!name || !name[0]) {
        py_disable_callable_value_proof(ctx);
        return;
    }
    const char *qn = ctx->class_body_qn
                         ? cbm_arena_sprintf(ctx->arena, "%s.%s", ctx->class_body_qn, name)
                         : NULL;
    if (is_class) {
        const CBMRegisteredType *type = qn ? cbm_registry_lookup_type(ctx->registry, qn) : NULL;
        py_scope_bind(ctx, name,
                      type ? cbm_type_named(ctx->arena, type->qualified_name) : cbm_type_unknown());
        return;
    }
    const CBMRegisteredFunc *func = qn ? cbm_registry_lookup_func(ctx->registry, qn) : NULL;
    if (!decorated && py_func_is_exact_callable_value(func)) {
        py_scope_bind_callable(ctx, name, cbm_type_unknown(), func->qualified_name);
    } else {
        py_scope_bind(ctx, name, cbm_type_unknown());
    }
}

/* Execute a class definition where it stands: its bases in the enclosing
 * scope, then its body statements in source order in a class frame. Calls
 * keep the caller the extraction gives them: the enclosing function, or the
 * module QN at module level (enclosing_func_qn is left unchanged).
 *
 * Scoping follows Python: a name bound earlier in the body is visible to
 * later body statements (and to decorators of methods), but the class frame
 * is not an enclosing scope for anything nested in it. Method bodies are
 * resolved later by py_process_class against the module scope, and a nested
 * class body chains to the nearest enclosing non-class scope. Each body
 * statement is walked exactly once. */
static void py_exec_class_definition(PyLSPContext *ctx, TSNode class_node) {
    if (!ctx || ctx->eval_failure || ts_node_is_null(class_node))
        return;
    TSNode supers = ts_node_child_by_field_name(class_node, "superclasses", 12);
    if (!ts_node_is_null(supers))
        py_resolve_calls_in(ctx, supers);
    TSNode body = ts_node_child_by_field_name(class_node, "body", 4);
    if (ctx->eval_failure || ts_node_is_null(body))
        return;

    char *cname = py_node_text(ctx, ts_node_child_by_field_name(class_node, "name", 4));
    const char *class_qn = NULL;
    if (cname && cname[0]) {
        if (ctx->class_body_outer_scope) {
            class_qn = ctx->class_body_qn
                           ? cbm_arena_sprintf(ctx->arena, "%s.%s", ctx->class_body_qn, cname)
                           : NULL;
        } else if (ctx->module_qn && ctx->enclosing_func_qn && ctx->file_module_qn &&
                   strcmp(ctx->enclosing_func_qn, ctx->file_module_qn) == 0) {
            class_qn = cbm_arena_sprintf(ctx->arena, "%s.%s", ctx->module_qn, cname);
        }
    }

    CBMScope *saved_scope = ctx->current_scope;
    CBMScope *saved_outer = ctx->class_body_outer_scope;
    const char *saved_qn = ctx->class_body_qn;
    bool saved_comprehension = ctx->class_body_in_comprehension;
    CBMScope *outer = saved_outer ? saved_outer : saved_scope;
    CBMScope *frame = py_class_frame_push(ctx, outer);
    if (!frame)
        return;
    py_scope_restore(ctx, frame);
    ctx->class_body_outer_scope = outer;
    ctx->class_body_qn = class_qn;
    ctx->class_body_in_comprehension = false;

    PyKids bk = py_kids(ctx->arena, body);
    for (uint32_t i = 0; i < bk.n && !ctx->eval_failure; i++) {
        TSNode stmt = py_kid(&bk, i);
        py_resolve_calls_in(ctx, stmt);
        py_bind_class_body_def(ctx, stmt);
    }

    ctx->class_body_outer_scope = saved_outer;
    ctx->class_body_qn = saved_qn;
    ctx->class_body_in_comprehension = saved_comprehension;
    py_scope_restore(ctx, saved_scope);
}

/* Walk a class's methods with the class qualified under `container_qn`: the
 * module for a module-level class, the enclosing def for a class declared in
 * a function body (#1548: extraction gives it the def's QN as prefix). */
static void py_process_class_in(PyLSPContext *ctx, TSNode class_node, const char *container_qn) {
    if (!ctx || ctx->eval_failure)
        return;
    TSNode name_node = ts_node_child_by_field_name(class_node, "name", 4);
    if (ts_node_is_null(name_node))
        return;
    char *cname = py_node_text(ctx, name_node);
    if (!cname || !cname[0])
        return;

    const char *prev_class = ctx->enclosing_class_qn;
    ctx->enclosing_class_qn =
        cbm_arena_sprintf(ctx->arena, "%s.%s", container_qn ? container_qn : ctx->module_qn, cname);

    TSNode body = ts_node_child_by_field_name(class_node, "body", 4);
    if (!ts_node_is_null(body)) {
        PyKids bk = py_kids(ctx->arena, body);
        uint32_t bnc = bk.n;
        // First pass: process class-level annotated assignments (PEP 526
        // class-body field annotations like `x: int`) and dunder __init__
        // methods so fields are registered before sibling methods that
        // reference them.
        for (uint32_t i = 0; i < bnc; i++) {
            TSNode c = py_kid(&bk, i);
            const char *ck = ts_node_type(c);
            if (strcmp(ck, "expression_statement") == 0 && ts_node_named_child_count(c) > 0) {
                TSNode inner = ts_node_named_child(c, 0);
                const char *ik = ts_node_type(inner);
                // class C: x: int = 1   → bind x as field
                if (strcmp(ik, "assignment") == 0) {
                    TSNode left = ts_node_child_by_field_name(inner, "left", 4);
                    TSNode ann = ts_node_child_by_field_name(inner, "type", 4);
                    if (!ts_node_is_null(left) && !ts_node_is_null(ann) &&
                        strcmp(ts_node_type(left), "identifier") == 0) {
                        char *fname = py_node_text(ctx, left);
                        char *atext = py_node_text(ctx, ann);
                        if (fname && atext) {
                            const CBMType *ft = py_resolve_annotation(ctx, atext);
                            py_register_instance_field(ctx, ctx->enclosing_class_qn, fname, ft);
                        }
                    }
                }
            }
        }
        // Second pass: __init__ (so self.x assignments populate fields).
        for (uint32_t i = 0; i < bnc; i++) {
            TSNode c = py_kid(&bk, i);
            const char *ck = ts_node_type(c);
            TSNode fn_node = c;
            bool is_decorated = strcmp(ck, "decorated_definition") == 0;
            if (is_decorated) {
                fn_node = ts_node_child_by_field_name(c, "definition", 10);
                if (ts_node_is_null(fn_node) ||
                    strcmp(ts_node_type(fn_node), "function_definition") != 0)
                    continue;
            } else if (strcmp(ck, "function_definition") != 0) {
                continue;
            }
            if (py_is_init_method(ctx, fn_node)) {
                py_process_function(ctx, fn_node, ctx->enclosing_class_qn);
            }
        }
        // Third pass: every other method (and nested classes).
        for (uint32_t i = 0; i < bnc; i++) {
            TSNode c = py_kid(&bk, i);
            const char *ck = ts_node_type(c);
            if (strcmp(ck, "function_definition") == 0) {
                if (!py_is_init_method(ctx, c)) {
                    py_process_function(ctx, c, ctx->enclosing_class_qn);
                }
            } else if (strcmp(ck, "decorated_definition") == 0) {
                TSNode def = ts_node_child_by_field_name(c, "definition", 10);
                if (!ts_node_is_null(def) &&
                    strcmp(ts_node_type(def), "function_definition") == 0 &&
                    !py_is_init_method(ctx, def)) {
                    py_process_function(ctx, def, ctx->enclosing_class_qn);
                } else if (!ts_node_is_null(def) &&
                           strcmp(ts_node_type(def), "class_definition") == 0) {
                    py_process_class_in(ctx, def, ctx->enclosing_class_qn);
                }
            } else if (strcmp(ck, "class_definition") == 0) {
                /* A class nested in a class is qualified by its outer class
                 * (proj.m.Outer.Inner), the QN extraction gives it; under the
                 * module its methods' calls never joined their callers. */
                py_process_class_in(ctx, c, ctx->enclosing_class_qn);
            }
        }
    }

    ctx->enclosing_class_qn = prev_class;
}

static void py_process_class(PyLSPContext *ctx, TSNode class_node) {
    py_process_class_in(ctx, class_node, NULL);
}

/* Module bindings are replayed in source order before deferred function bodies
 * are analyzed. Class definitions always replace an earlier callable identity;
 * the registry decides whether the resulting class type is known precisely. */
/* The names of the classes this source defines at module level, as a name set
 * (a detached, hash-indexed CBMScope frame). Built in one pass over the root:
 * asking "does the root define a class named X?" by rescanning the root once
 * per registry type made module assembly O(types x top-level statements).
 * Returns NULL if a class name or set entry cannot be collected completely. */
static CBMScope *py_root_class_names(PyLSPContext *ctx, const PyKids *rk) {
    CBMScope *names = cbm_scope_push(ctx->arena, NULL);
    if (!names)
        return NULL;
    for (uint32_t i = 0; i < rk->n; i++) {
        TSNode node = py_kid(rk, i);
        const char *kind = ts_node_type(node);
        if (strcmp(kind, "decorated_definition") == 0) {
            node = ts_node_child_by_field_name(node, "definition", 10);
            kind = ts_node_is_null(node) ? "" : ts_node_type(node);
        }
        if (strcmp(kind, "class_definition") != 0)
            continue;
        char *name = py_node_text(ctx, ts_node_child_by_field_name(node, "name", 4));
#ifdef CBM_ENABLE_TEST_SEAMS
        if (ctx->test_root_name_failure == 1)
            name = NULL;
        else if (ctx->test_root_name_failure == 2)
            name = "";
#endif
        if (!name || !name[0] || !cbm_scope_bind_checked(names, name, cbm_type_unknown()))
            return NULL;
    }
    return names;
}

/* The temporary query owner never supplies a retained binding/name/type.
 * A disabled/failed optimization leaves the original module-aware scan usable. */
static bool py_module_scratch_open(CBMArena *scratch) {
#ifdef CBM_ENABLE_TEST_SEAMS
    if (py_module_scratch_allocations_left == 0)
        return false;
    if (py_module_scratch_allocations_left > 0)
        py_module_scratch_allocations_left--;
#endif
    cbm_arena_init_lazy(scratch, 4096);
    return true;
}

static char *py_module_prefix(CBMArena *scratch, const char *module_qn, size_t length) {
    /* The arena rounds up by seven bytes after this addition. */
    if (length > SIZE_MAX - 9)
        return NULL;
#ifdef CBM_ENABLE_TEST_SEAMS
    if (py_module_prefix_allocations_left == 0)
        return NULL;
    if (py_module_prefix_allocations_left > 0)
        py_module_prefix_allocations_left--;
#endif
    char *prefix = cbm_arena_alloc(scratch, length + 2);
    if (!prefix)
        return NULL;
    memcpy(prefix, module_qn, length);
    prefix[length] = '.';
    prefix[length + 1] = '\0';
    return prefix;
}

/* A class declared inside a def -- django's per-test `class MyModelAdmin`, an
 * app factory's local class, and anything nested in one -- is a local of that
 * def, not a global of the module: bound here by its short name, every
 * same-named local class of the file collapsed onto whichever registered last.
 * Its QN extends a registered function's (proj.mod.Tests.test_x.MyModelAdmin),
 * which tells it apart from a class nested in a class (proj.mod.Outer.Inner).
 * Only prefixes longer than the module are probed. */
static bool py_type_is_function_local(const PyLSPContext *ctx, const char *qn, size_t module_len) {
    char scope[512];
    size_t len = strlen(qn);
    if (len >= sizeof(scope))
        return false;
    memcpy(scope, qn, len + 1);
    for (char *dot = strrchr(scope, '.'); dot && (size_t)(dot - scope) > module_len;
         dot = strrchr(scope, '.')) {
        *dot = '\0';
        if (cbm_registry_lookup_func(ctx->registry, scope))
            return true;
    }
    return false;
}

/* A project registry can contain another file's class in the same logical
 * Python module. Keep those cross-file globals available, but do not prebind
 * classes declared by this source: their binding epoch belongs in the ordered
 * replay below. */
static void py_bind_external_module_classes(PyLSPContext *ctx, const PyKids *rk) {
    if (!ctx || !ctx->registry || !ctx->module_qn)
        return;
    CBMScope *defined = py_root_class_names(ctx, rk);
    if (!defined) {
        /* Without the set no external class can be proven undeclared here;
         * binding none is the fail-closed direction. */
        py_disable_callable_value_proof(ctx);
        return;
    }
    size_t prefix_len = strlen(ctx->module_qn);
    bool package_scope = ctx->file_module_qn && strcmp(ctx->file_module_qn, ctx->module_qn) != 0;
    CBMArena scratch = {0};
    char *prefix = py_module_scratch_open(&scratch)
                       ? py_module_prefix(&scratch, ctx->module_qn, prefix_len)
                       : NULL;
    uint64_t visits = 0;
    for (const CBMTypeRegistry *link = ctx->registry; link; link = link->fallback) {
        CBMQNPrefixIter it;
        if (prefix)
            cbm_registry_types_with_qn_prefix(link, prefix, package_scope, &scratch, &it);
        int linear = 0;
        for (;;) {
            int i;
            if (prefix) {
                i = cbm_qn_prefix_iter_next(&it);
            } else {
                i = linear < link->type_count ? linear++ : -1;
                if (i >= 0)
                    visits++;
            }
            if (i < 0)
                break;
            if (cbm_registry_type_shadowed(ctx->registry, link, i))
                continue;
            const CBMRegisteredType *type = &link->types[i];
            const char *qn = type->qualified_name;
            const char *name = type->short_name;
            if (!qn || !name || strncmp(qn, ctx->module_qn, prefix_len) != 0 ||
                qn[prefix_len] != '.' || cbm_scope_lookup_local(defined, name))
                continue;
            if (package_scope && strchr(qn + prefix_len + 1, '.'))
                continue; /* submodule/nested classes are not package globals */
            if (py_type_is_function_local(ctx, qn, prefix_len))
                continue; /* a def-local class is no module global (#1548) */
            py_scope_bind(ctx, name, cbm_type_named(ctx->arena, qn));
        }
        if (prefix)
            visits += it.visits;
    }
    cbm_arena_destroy(&scratch);
#ifdef CBM_ENABLE_TEST_SEAMS
    atomic_fetch_add_explicit(&cbm_py_module_class_binds, 1, memory_order_relaxed);
    atomic_fetch_add_explicit(&cbm_py_module_class_bind_visits, visits, memory_order_relaxed);
#else
    (void)visits;
#endif
}

#ifdef CBM_ENABLE_TEST_SEAMS
void cbm_py_lsp_test_bind_external_classes(PyLSPContext *ctx, TSNode root) {
    PyKids rk = py_kids(ctx->arena, root);
    py_bind_external_module_classes(ctx, &rk);
}
#endif

static void py_bind_module_class(PyLSPContext *ctx, TSNode class_node) {
    if (!ctx || ts_node_is_null(class_node) || !ctx->module_qn)
        return;
    TSNode name_node = ts_node_child_by_field_name(class_node, "name", 4);
    char *name = py_node_text(ctx, name_node);
    if (!name || !name[0]) {
        py_disable_callable_value_proof(ctx);
        return;
    }
    const char *qn = cbm_arena_sprintf(ctx->arena, "%s.%s", ctx->module_qn, name);
    if (!qn) {
        py_disable_callable_value_proof(ctx);
        py_scope_bind(ctx, name, cbm_type_unknown());
        return;
    }
    const CBMRegisteredType *type = cbm_registry_lookup_type(ctx->registry, qn);
    py_scope_bind(ctx, name,
                  type ? cbm_type_named(ctx->arena, type->qualified_name) : cbm_type_unknown());
}

/* Preserve the historical registry fallback for an unshadowed function: it
 * keeps ordinary direct-call resolution stable. When a definition actually
 * replaces a prior binding (import, wildcard uncertainty, class, assignment),
 * record the new exact callable value or clear the stale identity. */
static void py_bind_module_function(PyLSPContext *ctx, TSNode func_node) {
    if (!ctx || ts_node_is_null(func_node) || !ctx->module_qn)
        return;
    TSNode name_node = ts_node_child_by_field_name(func_node, "name", 4);
    char *name = py_node_text(ctx, name_node);
    if (!name || !name[0]) {
        py_disable_callable_value_proof(ctx);
        return;
    }
    if (!cbm_scope_contains(ctx->current_scope, name))
        return;

    const char *qn = cbm_arena_sprintf(ctx->arena, "%s.%s", ctx->module_qn, name);
    if (!qn) {
        py_disable_callable_value_proof(ctx);
        py_scope_bind(ctx, name, cbm_type_unknown());
        return;
    }
    const CBMRegisteredFunc *func = cbm_registry_lookup_func(ctx->registry, qn);
    if (py_func_is_exact_callable_value(func)) {
        py_scope_bind_callable(ctx, name, cbm_type_unknown(), func->qualified_name);
    } else {
        py_scope_bind(ctx, name, cbm_type_unknown());
    }
}

static bool py_import_statement_is_wildcard(TSNode stmt) {
    uint32_t count = ts_node_named_child_count(stmt);
    for (uint32_t i = 0; i < count; i++) {
        if (strcmp(ts_node_type(ts_node_named_child(stmt, i)), "wildcard_import") == 0)
            return true;
    }
    return false;
}

static void py_invalidate_registry_module_functions(PyLSPContext *ctx,
                                                    const CBMTypeRegistry *registry) {
    if (!ctx || !registry || !ctx->module_qn)
        return;
    size_t prefix_len = strlen(ctx->module_qn);
    CBMArena scratch = {0};
    char *prefix = py_module_scratch_open(&scratch)
                       ? py_module_prefix(&scratch, ctx->module_qn, prefix_len)
                       : NULL;
    uint64_t visits = 0;
    for (const CBMTypeRegistry *link = registry; link; link = link->fallback) {
        CBMQNPrefixIter it;
        if (prefix)
            cbm_registry_funcs_with_qn_prefix(link, prefix, true, &scratch, &it);
        int linear = 0;
        for (;;) {
            int i;
            if (prefix) {
                i = cbm_qn_prefix_iter_next(&it);
            } else {
                i = linear < link->func_count ? linear++ : -1;
                if (i >= 0)
                    visits++;
            }
            if (i < 0)
                break;
            const CBMRegisteredFunc *func = &link->funcs[i];
            const char *qn = func->qualified_name;
            if (!qn || func->receiver_type || strncmp(qn, ctx->module_qn, prefix_len) != 0 ||
                qn[prefix_len] != '.')
                continue;
            const char *suffix = qn + prefix_len + 1;
            if (!suffix[0] || strchr(suffix, '.'))
                continue;
            py_scope_bind(ctx, func->short_name ? func->short_name : suffix, cbm_type_unknown());
        }
        if (prefix)
            visits += it.visits;
    }
    cbm_arena_destroy(&scratch);
#ifdef CBM_ENABLE_TEST_SEAMS
    atomic_fetch_add_explicit(&cbm_py_wildcard_invalidations, 1, memory_order_relaxed);
    atomic_fetch_add_explicit(&cbm_py_wildcard_invalidation_visits, visits, memory_order_relaxed);
#else
    (void)visits;
#endif
}

/* `from module import *` may overwrite any module global through `__all__`.
 * Without the imported module's export set, retaining any callable identity is
 * unsound. Clear current bindings and install UNKNOWN shadows for registry-only
 * local functions so exact lookup cannot fall through around the wildcard. */
static void py_invalidate_module_bindings_for_wildcard(PyLSPContext *ctx) {
    if (!ctx || !ctx->current_scope)
        return;
    for (CBMScopeChunk *chunk = ctx->current_scope->chunks; chunk; chunk = chunk->next) {
        for (int i = 0; i < chunk->used; i++) {
            const char *name = chunk->bindings[i].name;
            if (name)
                py_scope_bind(ctx, name, cbm_type_unknown());
        }
    }
    py_invalidate_registry_module_functions(ctx, ctx->registry);
}

static char *py_import_item_local_name(PyLSPContext *ctx, TSNode item, bool from_import) {
    const char *kind = ts_node_type(item);
    if (strcmp(kind, "aliased_import") == 0) {
        TSNode alias = ts_node_child_by_field_name(item, "alias", 5);
        return py_import_node_text_dup(ctx, alias);
    }
    if (strcmp(kind, "identifier") != 0 && strcmp(kind, "dotted_name") != 0)
        return NULL;
    char *name = py_import_node_text_dup(ctx, item);
    if (!name || from_import)
        return name;
    char *dot = strchr(name, '.');
    if (dot)
        *dot = '\0';
    return name;
}

/* Invalidate one syntactic binding target without treating attribute or
 * subscript writes as rebinding the same-spelled module global. Pattern
 * containers are walked recursively; a one-component dotted_name is the
 * tree-sitter shape used by Python capture patterns. */
static void py_invalidate_binding_target(PyLSPContext *ctx, TSNode target, int depth) {
    if (!ctx || ts_node_is_null(target))
        return;
    if (depth > 64) {
        py_disable_callable_value_proof(ctx);
        return;
    }
    const char *kind = ts_node_type(target);
    if (strcmp(kind, "identifier") == 0) {
        char *name = py_node_text(ctx, target);
        if (!name) {
            py_disable_callable_value_proof(ctx);
            return;
        }
        py_scope_bind(ctx, name, cbm_type_unknown());
        return;
    }
    if (strcmp(kind, "attribute") == 0 || strcmp(kind, "subscript") == 0)
        return;
    uint32_t count = ts_node_named_child_count(target);
    if (strcmp(kind, "dotted_name") == 0 && count != 1)
        return;
    for (uint32_t i = 0; i < count; i++)
        py_invalidate_binding_target(ctx, ts_node_named_child(target, i), depth + 1);
}

/* An assignment expression binds in the CONTAINING scope (PEP 572), which is
 * what separates it from every other binder a comprehension can hold: the
 * iteration variables are private to the comprehension, the walrus is not.
 *
 * This exists because a module-level expression statement is resolved for calls
 * rather than scanned for bindings, so `(callback := 0)` and
 * `[(callback := 0) for _ in (0,)]` reached no binder at all and left an
 * imported name looking exactly bound after Python had already rebound it --
 * proof fabricated from a name that no longer refers to the callable.
 *
 * A lambda, function or class body owns its own walrus targets, so those are
 * not walked. The value side is, because a walrus can nest inside one. */
static void py_invalidate_walrus_bindings(PyLSPContext *ctx, TSNode node, int depth) {
    if (!ctx || ts_node_is_null(node))
        return;
    if (depth > 64) {
        py_disable_callable_value_proof(ctx);
        return;
    }
    const char *kind = ts_node_type(node);
    if (strcmp(kind, "lambda") == 0 || strcmp(kind, "function_definition") == 0 ||
        strcmp(kind, "class_definition") == 0) {
        return;
    }
    if (strcmp(kind, "named_expression") == 0 || strcmp(kind, "assignment_expression") == 0) {
        TSNode name = ts_node_child_by_field_name(node, "name", 4);
        if (ts_node_is_null(name))
            name = ts_node_child_by_field_name(node, "left", 4);
        if (ts_node_is_null(name))
            py_disable_callable_value_proof(ctx);
        else
            py_invalidate_binding_target(ctx, name, depth + 1);
    }
    uint32_t count = ts_node_named_child_count(node);
    for (uint32_t i = 0; i < count; i++)
        py_invalidate_walrus_bindings(ctx, ts_node_named_child(node, i), depth + 1);
}

/* Match patterns mix value expressions and capture targets. Skip the class
 * expression in `case Type(...)` and keyword labels, while invalidating every
 * nested capture/as/star target that may replace a module binding. */
static void py_invalidate_match_pattern(PyLSPContext *ctx, TSNode pattern, int depth) {
    if (!ctx || ts_node_is_null(pattern))
        return;
    if (depth > 64) {
        py_disable_callable_value_proof(ctx);
        return;
    }
    const char *kind = ts_node_type(pattern);
    uint32_t count = ts_node_named_child_count(pattern);
    if (strcmp(kind, "class_pattern") == 0) {
        for (uint32_t i = 1; i < count; i++)
            py_invalidate_match_pattern(ctx, ts_node_named_child(pattern, i), depth + 1);
        return;
    }
    if (strcmp(kind, "keyword_pattern") == 0) {
        if (count > 0)
            py_invalidate_match_pattern(ctx, ts_node_named_child(pattern, count - 1), depth + 1);
        return;
    }
    if (strcmp(kind, "attribute") == 0)
        return;
    if (strcmp(kind, "dotted_name") == 0) {
        if (count == 1)
            py_invalidate_binding_target(ctx, ts_node_named_child(pattern, 0), depth + 1);
        return;
    }
    if (strcmp(kind, "identifier") == 0) {
        py_invalidate_binding_target(ctx, pattern, depth + 1);
        return;
    }
    for (uint32_t i = 0; i < count; i++)
        py_invalidate_match_pattern(ctx, ts_node_named_child(pattern, i), depth + 1);
}

static void py_invalidate_import_bindings(PyLSPContext *ctx, TSNode stmt) {
    if (py_import_statement_is_wildcard(stmt)) {
        py_invalidate_module_bindings_for_wildcard(ctx);
        return;
    }
    bool from_import = strcmp(ts_node_type(stmt), "import_from_statement") == 0;
    TSNode module = from_import ? py_from_import_module_node(stmt) : (TSNode){0};
    uint32_t count = ts_node_named_child_count(stmt);
    for (uint32_t i = 0; i < count; i++) {
        TSNode item = ts_node_named_child(stmt, i);
        if (from_import && !ts_node_is_null(module) && ts_node_eq(item, module))
            continue;
        const char *kind = ts_node_type(item);
        char *local = py_import_item_local_name(ctx, item, from_import);
        if (local) {
            py_scope_bind(ctx, local, cbm_type_unknown());
        } else if (strcmp(kind, "aliased_import") == 0 || strcmp(kind, "identifier") == 0 ||
                   strcmp(kind, "dotted_name") == 0) {
            py_disable_callable_value_proof(ctx);
        }
    }
}

/* Conservatively join possible binding effects from module/function compound
 * statements. Only names that occur in a binding position lose exact callable
 * identity. Nested lexical bodies are not walked after their definition name,
 * and annotation-only assignments do not replace a runtime value. */
static void py_invalidate_possible_bindings(PyLSPContext *ctx, TSNode node, int depth) {
    if (!ctx || ts_node_is_null(node))
        return;
    if (depth > 64) {
        py_disable_callable_value_proof(ctx);
        return;
    }
    const char *kind = ts_node_type(node);
    if (strcmp(kind, "lambda") == 0) {
        return;
    }
    /* A comprehension's iteration variables are private to it, so it is not
     * scanned as an ordinary binder -- but a walrus inside one still binds out
     * here, and skipping the whole node missed that. */
    if (strcmp(kind, "list_comprehension") == 0 || strcmp(kind, "set_comprehension") == 0 ||
        strcmp(kind, "dictionary_comprehension") == 0 ||
        strcmp(kind, "generator_expression") == 0) {
        py_invalidate_walrus_bindings(ctx, node, depth + 1);
        return;
    }
    /* PEP 695 `type X = ...` binds X in the enclosing scope. Only the left side
     * is a target; the right is a type expression. */
    if (strcmp(kind, "type_alias_statement") == 0) {
        TSNode left = ts_node_child_by_field_name(node, "left", 4);
        if (ts_node_is_null(left) && ts_node_named_child_count(node) > 0)
            left = ts_node_named_child(node, 0);
        if (ts_node_is_null(left))
            py_disable_callable_value_proof(ctx);
        else
            py_invalidate_binding_target(ctx, left, depth + 1);
        return;
    }
    if (strcmp(kind, "function_definition") == 0 || strcmp(kind, "class_definition") == 0) {
        TSNode name = ts_node_child_by_field_name(node, "name", 4);
        if (ts_node_is_null(name))
            py_disable_callable_value_proof(ctx);
        else
            py_invalidate_binding_target(ctx, name, depth + 1);
        return;
    }
    if (strcmp(kind, "decorated_definition") == 0) {
        TSNode definition = ts_node_child_by_field_name(node, "definition", 10);
        if (ts_node_is_null(definition))
            py_disable_callable_value_proof(ctx);
        else
            py_invalidate_possible_bindings(ctx, definition, depth + 1);
        return;
    }
    if (strcmp(kind, "import_statement") == 0 || strcmp(kind, "import_from_statement") == 0) {
        py_invalidate_import_bindings(ctx, node);
        return;
    }
    if (strcmp(kind, "assignment") == 0) {
        TSNode right = ts_node_child_by_field_name(node, "right", 5);
        if (ts_node_is_null(right))
            return;
        py_invalidate_binding_target(ctx, ts_node_child_by_field_name(node, "left", 4), depth + 1);
        py_invalidate_possible_bindings(ctx, right, depth + 1);
        return;
    }
    if (strcmp(kind, "augmented_assignment") == 0) {
        TSNode left = ts_node_child_by_field_name(node, "left", 4);
        TSNode right = ts_node_child_by_field_name(node, "right", 5);
        py_invalidate_binding_target(ctx, left, depth + 1);
        py_invalidate_possible_bindings(ctx, right, depth + 1);
        return;
    }
    if (strcmp(kind, "named_expression") == 0 || strcmp(kind, "assignment_expression") == 0) {
        TSNode name = ts_node_child_by_field_name(node, "name", 4);
        if (ts_node_is_null(name))
            name = ts_node_child_by_field_name(node, "left", 4);
        TSNode value = ts_node_child_by_field_name(node, "value", 5);
        if (ts_node_is_null(value))
            value = ts_node_child_by_field_name(node, "right", 5);
        py_invalidate_binding_target(ctx, name, depth + 1);
        py_invalidate_possible_bindings(ctx, value, depth + 1);
        return;
    }
    if (strcmp(kind, "delete_statement") == 0) {
        uint32_t count = ts_node_named_child_count(node);
        for (uint32_t i = 0; i < count; i++)
            py_invalidate_binding_target(ctx, ts_node_named_child(node, i), depth + 1);
        return;
    }
    if (strcmp(kind, "for_statement") == 0) {
        TSNode left = ts_node_child_by_field_name(node, "left", 4);
        py_invalidate_binding_target(ctx, left, depth + 1);
        uint32_t count = ts_node_named_child_count(node);
        for (uint32_t i = 0; i < count; i++) {
            TSNode child = ts_node_named_child(node, i);
            if (!ts_node_eq(child, left))
                py_invalidate_possible_bindings(ctx, child, depth + 1);
        }
        return;
    }
    if (strcmp(kind, "as_pattern") == 0) {
        TSNode alias = ts_node_child_by_field_name(node, "alias", 5);
        uint32_t count = ts_node_named_child_count(node);
        if (ts_node_is_null(alias) && count > 1)
            alias = ts_node_named_child(node, count - 1);
        py_invalidate_binding_target(ctx, alias, depth + 1);
        for (uint32_t i = 0; i < count; i++) {
            TSNode child = ts_node_named_child(node, i);
            if (!ts_node_eq(child, alias))
                py_invalidate_possible_bindings(ctx, child, depth + 1);
        }
        return;
    }
    if (strcmp(kind, "match_statement") == 0) {
        TSNode subject = ts_node_child_by_field_name(node, "subject", 7);
        TSNode body = ts_node_child_by_field_name(node, "body", 4);
        py_invalidate_possible_bindings(ctx, subject, depth + 1);
        uint32_t cases = ts_node_named_child_count(body);
        for (uint32_t i = 0; i < cases; i++) {
            TSNode clause = ts_node_named_child(body, i);
            if (strcmp(ts_node_type(clause), "case_clause") != 0)
                continue;
            TSNode pattern = {0};
            uint32_t count = ts_node_named_child_count(clause);
            for (uint32_t j = 0; j < count; j++) {
                TSNode child = ts_node_named_child(clause, j);
                if (ts_node_is_null(pattern) && strcmp(ts_node_type(child), "block") != 0) {
                    pattern = child;
                    py_invalidate_match_pattern(ctx, pattern, depth + 1);
                } else if (!ts_node_eq(child, pattern)) {
                    py_invalidate_possible_bindings(ctx, child, depth + 1);
                }
            }
        }
        return;
    }
    PyKids nk = py_kids(ctx->arena, node);
    for (uint32_t i = 0; i < nk.n; i++)
        py_invalidate_possible_bindings(ctx, py_kid(&nk, i), depth + 1);
}

static bool py_replayable_import_kind(PyDirectImportKind kind) {
    return kind == PY_DIRECT_IMPORT_UNALIASED || kind == PY_DIRECT_IMPORT_ALIASED ||
           kind == PY_FROM_IMPORT;
}

/* Replay one syntactic local-binding occurrence. UNKNOWN is installed first,
 * so missing, conflicting, or project-prefix-ambiguous metadata fails closed.
 * Exactly one canonical target may then upgrade that occurrence. */
static void py_replay_import_local(PyLSPContext *ctx, TSNode stmt, const char *local,
                                   unsigned char *consumed) {
    if (!ctx || !local || !local[0])
        return;
    py_scope_bind(ctx, local, cbm_type_unknown());
    if (ctx->import_count > 0 && !consumed)
        return;

    int chosen = -1;
    PyDirectImportKind chosen_kind = PY_IMPORT_UNCLASSIFIED;
    const char *chosen_qn = NULL;
    bool conflicting_target = false;
    for (int i = 0; i < ctx->import_count; i++) {
        if ((consumed && consumed[i]) || !ctx->import_local_names[i] ||
            !ctx->import_module_qns[i] || strcmp(ctx->import_local_names[i], local) != 0) {
            continue;
        }
        const char *candidate_qn = ctx->import_module_qns[i];
        PyDirectImportKind kind = py_import_kind_from_statement(ctx, stmt, local, &candidate_qn);
        if (!py_replayable_import_kind(kind))
            continue;
        if (!chosen_qn) {
            chosen = i;
            chosen_kind = kind;
            chosen_qn = candidate_qn;
        } else if (strcmp(chosen_qn, candidate_qn) != 0 || chosen_kind != kind) {
            conflicting_target = true;
        }
    }
    if (chosen < 0 || conflicting_target)
        return;

    ctx->import_module_qns[chosen] = chosen_qn;
    if (ctx->import_kinds)
        ctx->import_kinds[chosen] = (unsigned char)chosen_kind;
    if (consumed)
        consumed[chosen] = 1;
    py_bind_import_index(ctx, chosen, false);
}

static void py_replay_import_statement(PyLSPContext *ctx, TSNode stmt, unsigned char *consumed) {
    if (py_import_statement_is_wildcard(stmt)) {
        py_invalidate_module_bindings_for_wildcard(ctx);
        return;
    }
    bool from_import = strcmp(ts_node_type(stmt), "import_from_statement") == 0;
    TSNode module = from_import ? py_from_import_module_node(stmt) : (TSNode){0};
    uint32_t count = ts_node_named_child_count(stmt);
    for (uint32_t i = 0; i < count; i++) {
        TSNode item = ts_node_named_child(stmt, i);
        if (from_import && !ts_node_is_null(module) && ts_node_eq(item, module))
            continue;
        char *local = py_import_item_local_name(ctx, item, from_import);
        if (local) {
            py_replay_import_local(ctx, stmt, local, consumed);
        } else {
            const char *kind = ts_node_type(item);
            if (strcmp(kind, "aliased_import") == 0 || strcmp(kind, "identifier") == 0 ||
                strcmp(kind, "dotted_name") == 0) {
                py_disable_callable_value_proof(ctx);
            }
        }
    }
}

/* The consequence block of a module-level `if TYPE_CHECKING:` /
 * `if <module>.TYPE_CHECKING:` statement, else a null node. Mirrors the
 * extraction's py_is_type_checking_condition (extract_imports.c). */
static TSNode py_type_checking_body(PyLSPContext *ctx, TSNode stmt) {
    TSNode none = {0};
    if (strcmp(ts_node_type(stmt), "if_statement") != 0)
        return none;
    TSNode cond = ts_node_child_by_field_name(stmt, "condition", 9);
    if (ts_node_is_null(cond))
        return none;
    TSNode name = cond;
    if (strcmp(ts_node_type(cond), "attribute") == 0)
        name = ts_node_child_by_field_name(cond, "attribute", 9);
    if (ts_node_is_null(name) || strcmp(ts_node_type(name), "identifier") != 0)
        return none;
    char *text = py_node_text(ctx, name);
    if (!text || strcmp(text, "TYPE_CHECKING") != 0)
        return none;
    return ts_node_child_by_field_name(stmt, "consequence", 11);
}

static bool py_expression_is_annotation_only_assignment(TSNode statement) {
    if (ts_node_named_child_count(statement) != 1)
        return false;
    TSNode expression = ts_node_named_child(statement, 0);
    if (strcmp(ts_node_type(expression), "assignment") != 0)
        return false;
    TSNode annotation = ts_node_child_by_field_name(expression, "type", 4);
    TSNode value = ts_node_child_by_field_name(expression, "right", 5);
    return !ts_node_is_null(annotation) && ts_node_is_null(value);
}

void py_lsp_process_file(PyLSPContext *ctx, TSNode root) {
    if (!ctx || ctx->eval_failure || ts_node_is_null(root))
        return;
    int resolved_start = ctx->resolved_calls ? ctx->resolved_calls->count : 0;
    int synthetic_start = ctx->syn_calls ? ctx->syn_calls->count : 0;
    /* Only invocation dedup mutates prior rows, within this fixed tail.
     * Snapshot once per walk: no full-output copy or fallible rollback allocation. */
    int tail_count =
        resolved_start < PY_RESOLVED_DEDUP_WINDOW ? resolved_start : PY_RESOLVED_DEDUP_WINDOW;
    int tail_start = resolved_start - tail_count;
    CBMResolvedCall saved_tail[PY_RESOLVED_DEDUP_WINDOW];
    CBMResolvedCall *original_tail = tail_count ? ctx->resolved_calls->items + tail_start : NULL;
    if (tail_count)
        memcpy(saved_tail, original_tail, (size_t)tail_count * sizeof(*saved_tail));
    PyKids rk = py_kids(ctx->arena, root);
    py_classify_imports_for_root(ctx, root);
    py_bind_external_module_classes(ctx, &rk);
    unsigned char *consumed_imports = NULL;
    if (ctx->import_count > 0) {
        consumed_imports = (unsigned char *)cbm_arena_alloc(ctx->arena, (size_t)ctx->import_count);
        if (consumed_imports)
            memset(consumed_imports, 0, (size_t)ctx->import_count);
    }

    uint32_t nc = rk.n;
    const char *prev_func = ctx->enclosing_func_qn;
    /* Extraction uses the file's Module QN at top level. Keep the caller
     * arena-owned for cross-file APIs whose module_qn input may be temporary. */
    ctx->enclosing_func_qn = cbm_arena_sprintf(ctx->arena, "%s", ctx->file_module_qn);
    // Pass 1: execute top-level binding effects in source order. Function
    // bodies remain deferred until the final module scope has been assembled.
    for (uint32_t i = 0; i < nc && !ctx->eval_failure; i++) {
        TSNode c = py_kid(&rk, i);
        const char *ck = ts_node_type(c);
        if (strcmp(ck, "import_statement") == 0 || strcmp(ck, "import_from_statement") == 0) {
            py_replay_import_statement(ctx, c, consumed_imports);
        } else if (strcmp(ck, "function_definition") == 0) {
            py_bind_module_function(ctx, c);
        } else if (strcmp(ck, "class_definition") == 0) {
            py_exec_class_definition(ctx, c);
            if (!ctx->eval_failure)
                py_bind_module_class(ctx, c);
        } else if (strcmp(ck, "decorated_definition") == 0) {
            py_resolve_decorators(ctx, c);
            TSNode def = ts_node_child_by_field_name(c, "definition", 10);
            if (!ctx->eval_failure && !ts_node_is_null(def)) {
                const char *dk = ts_node_type(def);
                if (strcmp(dk, "function_definition") == 0) {
                    py_bind_module_function(ctx, def);
                } else if (strcmp(dk, "class_definition") == 0) {
                    py_exec_class_definition(ctx, def);
                    if (!ctx->eval_failure)
                        py_bind_module_class(ctx, def);
                }
            }
        } else if (strcmp(ck, "expression_statement") == 0) {
            /* An expression statement is resolved for calls, not scanned as a
             * binder -- but an assignment expression anywhere inside it does
             * rebind a module name, so take those targets first. Doing it
             * before resolution fails closed for the rest of the statement,
             * which is the safe direction. */
            py_invalidate_walrus_bindings(ctx, c, 0);
            /* The recursive walker reaches a wrapped assignment and applies
             * its binding exactly once here, at module execution time. It also
             * preserves top-level call edges without replaying the assignment
             * later against the final module scope. */
            if (!py_expression_is_annotation_only_assignment(c))
                py_resolve_calls_in(ctx, c);
        } else {
            /* A compound statement can leave several possible module values.
             * Invalidate only syntactic binding targets at the control-flow
             * join; a later unconditional statement may restore exact proof. */
            py_invalidate_possible_bindings(ctx, c, 0);
            /* `if TYPE_CHECKING:` holds the imports annotations are written
             * against (#1277). Bind them into the annotation-only frame: an
             * annotation resolves through them, a runtime call never does (the
             * interpreter never runs the block). Extraction recorded them
             * flagged type_checking_only, so they reach this walk through the
             * LSP import map only, never a CALLS import map. */
            TSNode tc_body = py_type_checking_body(ctx, c);
            if (!ts_node_is_null(tc_body)) {
                if (!ctx->annotation_scope)
                    ctx->annotation_scope = cbm_scope_push(ctx->arena, NULL);
                CBMScope *runtime_scope = ctx->current_scope;
                PyKids tk = py_kids(ctx->arena, tc_body);
                for (uint32_t t = 0; ctx->annotation_scope && t < tk.n && !ctx->eval_failure; t++) {
                    TSNode stmt = py_kid(&tk, t);
                    const char *sk = ts_node_type(stmt);
                    if (strcmp(sk, "import_statement") == 0 ||
                        strcmp(sk, "import_from_statement") == 0) {
                        ctx->current_scope = ctx->annotation_scope;
                        py_replay_import_statement(ctx, stmt, consumed_imports);
                        ctx->current_scope = runtime_scope;
                    }
                }
            }
        }
    }
    // Pass 2: top-level calls (rare) and nested definitions.
    for (uint32_t i = 0; i < nc && !ctx->eval_failure; i++) {
        TSNode c = py_kid(&rk, i);
        const char *ck = ts_node_type(c);
        if (strcmp(ck, "function_definition") == 0) {
            py_process_function(ctx, c, NULL);
        } else if (strcmp(ck, "class_definition") == 0) {
            py_process_class(ctx, c);
        } else if (strcmp(ck, "decorated_definition") == 0) {
            TSNode def = ts_node_child_by_field_name(c, "definition", 10);
            if (ts_node_is_null(def))
                continue;
            const char *dk = ts_node_type(def);
            if (strcmp(dk, "function_definition") == 0) {
                py_process_function(ctx, def, NULL);
            } else if (strcmp(dk, "class_definition") == 0) {
                py_process_class(ctx, def);
            }
        }
    }
    ctx->enclosing_func_qn = prev_func;
    if (ctx->eval_failure) {
        if (tail_count) {
            memcpy(original_tail, saved_tail, (size_t)tail_count * sizeof(*saved_tail));
            memcpy(ctx->resolved_calls->items + tail_start, saved_tail,
                   (size_t)tail_count * sizeof(*saved_tail));
        }
        if (ctx->resolved_calls)
            ctx->resolved_calls->count = resolved_start;
        if (ctx->syn_calls)
            ctx->syn_calls->count = synthetic_start;
    }
}

/* Register one definition into the registry. Returns true if recognized. */
static bool py_register_def(CBMArena *arena, CBMTypeRegistry *reg, CBMDefinition *d,
                            const char *module_qn) {
    if (!d || !d->qualified_name || !d->name || !d->label)
        return false;

    if (strcmp(d->label, "Class") == 0 || strcmp(d->label, "Type") == 0) {
        CBMRegisteredType rt;
        memset(&rt, 0, sizeof(rt));
        rt.qualified_name = d->qualified_name;
        rt.short_name = d->name;
        rt.is_interface = false;
        if (d->base_classes) {
            // Python's extract_defs records the entire `(Base, Other)` argument
            // list as a single base_classes[0] entry. Split commas and strip
            // parens / whitespace / generic subscripts to recover usable QNs.
            int cap = 8;
            const char **embedded =
                (const char **)cbm_arena_alloc(arena, (size_t)(cap + 1) * sizeof(const char *));
            int n = 0;
            for (int j = 0; d->base_classes[j]; j++) {
                const char *raw = d->base_classes[j];
                size_t raw_len = strlen(raw);
                // Trim outer parens if present.
                size_t lo = 0;
                size_t hi = raw_len;
                while (lo < hi && (raw[lo] == '(' || raw[lo] == ' '))
                    lo++;
                while (hi > lo && (raw[hi - 1] == ')' || raw[hi - 1] == ' '))
                    hi--;
                // Split on commas at depth 0 (ignore commas inside [], ()).
                size_t start = lo;
                int depth = 0;
                for (size_t k = lo; k <= hi; k++) {
                    char c = (k < hi) ? raw[k] : ',';
                    if (c == '[' || c == '(')
                        depth++;
                    else if (c == ']' || c == ')')
                        depth--;
                    else if (c == ',' && depth == 0) {
                        size_t s = start;
                        size_t e = k;
                        while (s < e && raw[s] == ' ')
                            s++;
                        while (e > s && raw[e - 1] == ' ')
                            e--;
                        // Strip generic subscript: "Foo[T]" -> "Foo"
                        size_t lb = s;
                        while (lb < e && raw[lb] != '[')
                            lb++;
                        size_t name_end = lb;
                        // Skip keyword args like "metaclass=Meta" (contains '=')
                        size_t eq = s;
                        while (eq < name_end && raw[eq] != '=')
                            eq++;
                        if (eq >= name_end && name_end > s) {
                            size_t blen = name_end - s;
                            char *bname = (char *)cbm_arena_alloc(arena, blen + 1);
                            if (bname) {
                                memcpy(bname, raw + s, blen);
                                bname[blen] = '\0';
                                if (n >= cap) {
                                    int new_cap = cap * 2;
                                    const char **grown = (const char **)cbm_arena_alloc(
                                        arena, (size_t)(new_cap + 1) * sizeof(const char *));
                                    if (grown) {
                                        for (int q = 0; q < n; q++)
                                            grown[q] = embedded[q];
                                        embedded = grown;
                                        cap = new_cap;
                                    }
                                }
                                if (n < cap) {
                                    embedded[n++] =
                                        strchr(bname, '.')
                                            ? bname
                                            : cbm_arena_sprintf(arena, "%s.%s", module_qn, bname);
                                }
                            }
                        }
                        start = k + 1;
                    }
                }
            }
            embedded[n] = NULL;
            if (n > 0)
                rt.embedded_types = embedded;
        }
        cbm_registry_add_type(reg, rt);
        return true;
    }

    if (strcmp(d->label, "Function") == 0 || strcmp(d->label, "Method") == 0) {
        CBMRegisteredFunc rf;
        memset(&rf, 0, sizeof(rf));
        rf.qualified_name = d->qualified_name;
        rf.short_name = d->name;
        py_register_func_decorators(&rf, d->decorators);

        const CBMType **ret_types = NULL;
        // Prefer d->return_type (full text) when it has subscript brackets
        // — extract_defs.c::extract_return_types strips them in its array
        // form, which loses subscript args like Optional[Foo]. d->return_type
        // is the cbm_node_text of the whole annotation node, which is the
        // form py_parse_type_text_qn expects.
        bool prefer_full = d->return_type && d->return_type[0] && strchr(d->return_type, '[');
        if (prefer_full) {
            ret_types = (const CBMType **)cbm_arena_alloc(arena, 2 * sizeof(const CBMType *));
            ret_types[0] = py_parse_type_text_qn(arena, d->return_type, module_qn);
            ret_types[1] = NULL;
        } else if (d->return_types && d->return_types[0]) {
            int count = 0;
            while (d->return_types[count])
                count++;
            ret_types = (const CBMType **)cbm_arena_alloc(arena, (size_t)(count + 1) *
                                                                     sizeof(const CBMType *));
            for (int j = 0; j < count; j++) {
                ret_types[j] = py_parse_type_text_qn(arena, d->return_types[j], module_qn);
            }
            ret_types[count] = NULL;
        } else if (d->return_type && d->return_type[0]) {
            ret_types = (const CBMType **)cbm_arena_alloc(arena, 2 * sizeof(const CBMType *));
            ret_types[0] = py_parse_type_text_qn(arena, d->return_type, module_qn);
            ret_types[1] = NULL;
        }
        const CBMType **param_types = NULL;
        const char **param_names = d->param_names;
        if (d->signature_param_types || d->signature_param_count > 0) {
            PySignatureParamParserContext parser_ctx = {.module_qn = module_qn};
            param_types = cbm_type_materialize_signature_params(
                arena, d->signature_param_types, d->signature_param_count,
                py_signature_param_type_adapter, &parser_ctx);
            param_names = NULL;
        }
        rf.signature = cbm_type_func(arena, param_names, param_types, ret_types);

        if (strcmp(d->label, "Method") == 0) {
            // Receiver type: the enclosing class. Python def metadata may
            // record the class name in `receiver` or via the QN itself.
            const char *qn = d->qualified_name;
            const char *last_dot = strrchr(qn, '.');
            if (last_dot && last_dot != qn) {
                size_t prefix_len = (size_t)(last_dot - qn);
                rf.receiver_type = cbm_arena_strndup(arena, qn, prefix_len);
            }
        }
        cbm_registry_add_func(reg, rf);
        return true;
    }
    return false;
}

/* ── cbm_run_py_lsp: single-file entry point ──────────────────── */

void cbm_run_py_lsp(CBMArena *arena, CBMFileResult *result, const char *source, int source_len,
                    TSNode root) {
    if (!arena || !result || result->lsp_skipped)
        return;

    CBMTypeRegistry reg;
    cbm_registry_init(&reg, arena);
    PyLSPContext ctx;
    py_lsp_init_for_stage(&ctx, arena, source, source_len, &reg, result->module_qn,
                          &result->resolved_calls, "raw");
    if (ctx.eval_failure) {
        cbm_py_lsp_record_failure(result, ctx.eval_failure);
        return;
    }

    /* Inject minimal builtin definitions as real graph nodes (builtins.len,
     * builtins.str, builtins.str.upper, ...). The typeshed registry already
     * RESOLVES builtin calls (emitting the strategy + a "builtins.*" callee_qn),
     * but pass_calls.c only writes the CALLS edge when that callee_qn maps to a
     * graph node. We run inside cbm_extract_file, before the pipeline mints
     * def nodes from result->defs, so these become the target nodes the
     * builtin/constructor/method edges point at. Upsert dedups by QN. */
    py_builtins_inject_defs(result, arena);

    cbm_python_stdlib_register(&reg, arena);

    const char *module_qn = ctx.module_qn;

    // Register the file's own definitions so calls inside this file can
    // resolve via the registry.
    for (int i = 0; i < result->defs.count; i++) {
        py_register_def(arena, &reg, &result->defs.items[i], module_qn);
    }

    /* Hash-index the registry before the walk (#1527). Unfinalized, every
     * lookup scanned the stdlib plus all of this file's definitions, which
     * made resolving a large module O(calls x defs). The index answers each
     * duplicated name with its first registration, as the scan did, so the
     * resolution result is unchanged; post-walk additions (instance fields)
     * stay visible through the registry's tail scan. The index lives in a
     * scratch arena that dies with this call, not in the result arena. */
    CBMArena idx_arena;
    cbm_arena_init(&idx_arena);
    py_mark_ambiguous_callable_bindings(&reg, &idx_arena);
    reg.index_first_registered = true;
    cbm_registry_finalize_into(&reg, &idx_arena);

    /* Let the resolver inject synthetic syntactic calls for operator/subscript
     * dunder desugaring so those recovered calls reach the CALLS-edge pipeline. */
    ctx.syn_calls = &result->calls;

    for (int i = 0; i < result->imports.count; i++) {
        CBMImport *imp = &result->imports.items[i];
        if (imp->local_name && imp->module_path) {
            py_lsp_add_import(&ctx, imp->local_name, imp->module_path);
        }
    }

    py_memo_test_stage(&ctx, "raw");
    py_lsp_process_file(&ctx, root);
    if (ctx.eval_failure)
        cbm_py_lsp_record_failure(result, ctx.eval_failure);
    cbm_arena_destroy(&idx_arena);
}

/* ── Cross-file + batch ───────────────────────────────────────── */

extern const TSLanguage *tree_sitter_python(void);

/* Split a "|"-separated list into a NULL-terminated array of arena copies. */
static const char **py_split_pipe(CBMArena *arena, const char *text) {
    if (!text || !text[0])
        return NULL;
    int count = 1;
    for (const char *p = text; *p; p++)
        if (*p == '|')
            count++;
    const char **out =
        (const char **)cbm_arena_alloc(arena, (size_t)(count + 1) * sizeof(const char *));
    if (!out)
        return NULL;
    int idx = 0;
    const char *start = text;
    for (const char *p = text;; p++) {
        if (*p == '|' || *p == '\0') {
            size_t n = (size_t)(p - start);
            char *s = (char *)cbm_arena_alloc(arena, n + 1);
            if (!s)
                return NULL;
            memcpy(s, start, n);
            s[n] = '\0';
            out[idx++] = s;
            if (*p == '\0')
                break;
            start = p + 1;
        }
    }
    out[idx] = NULL;
    return out;
}

/* Split a class def's field_defs ("name:QN|name:QN", built by the Python
 * field fold in pass_lsp_cross.c) into the parallel NULL-terminated arrays a
 * CBMRegisteredType carries. The types are already project QNs, so each one
 * becomes a NAMED type verbatim. Without this, `obj.field.method()` on a class
 * from another file lost the field's type (#1277); same-file classes get their
 * fields from the per-file walk instead. Pure string work: no registry lookup
 * happens here, so it is safe inside the type-registration pass. */
static void py_split_field_defs(CBMArena *arena, const char *field_defs, const char ***names_out,
                                const CBMType ***types_out) {
    *names_out = NULL;
    *types_out = NULL;
    const char **pairs = py_split_pipe(arena, field_defs);
    if (!pairs)
        return;
    int n = 0;
    while (pairs[n])
        n++;
    const char **names =
        (const char **)cbm_arena_alloc(arena, (size_t)(n + 1) * sizeof(const char *));
    const CBMType **types =
        (const CBMType **)cbm_arena_alloc(arena, (size_t)(n + 1) * sizeof(const CBMType *));
    if (!names || !types)
        return;
    int kept = 0;
    for (int i = 0; i < n; i++) {
        char *colon = strchr(pairs[i], ':');
        if (!colon || colon == pairs[i] || !colon[1])
            continue;
        *colon = '\0'; /* pairs[i] is this call's own arena copy */
        names[kept] = pairs[i];
        types[kept] = cbm_type_named(arena, colon + 1);
        kept++;
    }
    if (kept == 0)
        return;
    names[kept] = NULL;
    types[kept] = NULL;
    *names_out = names;
    *types_out = types;
}

/* Qualified names of reg->types[0..noted), for a caller that registers into a
 * registry it does not finalize until the end (cbm_py_build_cross_registry):
 * that registry's own lookup scans every type. qns == NULL probes the
 * registry instead. */
typedef struct {
    CBMHashTable *qns;
    int noted;
} PyKnownTypes;

/* Note the types added since the last call. Run after every add_type, so an
 * add that failed silently cannot desync set and registry. If the set cannot
 * grow it is dropped and probes fall back to the registry. */
static void py_note_known_types(PyKnownTypes *known, const CBMTypeRegistry *reg) {
    for (; known && known->qns && known->noted < reg->type_count; known->noted++) {
        const char *qn = reg->types[known->noted].qualified_name;
        if (!qn || cbm_ht_has(known->qns, qn))
            continue;
        cbm_ht_set(known->qns, qn, (void *)(uintptr_t)(known->noted + 1));
        if (!cbm_ht_has(known->qns, qn)) {
            cbm_ht_free(known->qns);
            known->qns = NULL;
        }
    }
}

/* Build a registry from CBMLSPDef[] supplied by the caller — covers both
 * the source file's own defs and cross-file referenced defs. known is NULL
 * except for the shared Tier-2 build. */
static bool py_register_lsp_defs(CBMArena *arena, CBMArena *idx_arena, CBMTypeRegistry *reg,
                                 CBMLSPDef *defs, int def_count, PyKnownTypes *known) {
    /* Pass 1: types only — the method pass probes the registry per Method def
     * (receiver auto-registration), which is a LINEAR scan pre-finalize:
     * O(methods x types) per file (same quadratic as php_register_lsp_defs;
     * see that function's comment). Types first, finalize, then methods. */
    for (int i = 0; i < def_count; i++) {
        CBMLSPDef *d = &defs[i];
        if (!d->qualified_name || !d->short_name || !d->label)
            continue;

        if (strcmp(d->label, "Type") == 0 || strcmp(d->label, "Class") == 0 ||
            strcmp(d->label, "Interface") == 0 || strcmp(d->label, "Protocol") == 0) {
            CBMRegisteredType rt;
            memset(&rt, 0, sizeof(rt));
            rt.qualified_name = d->qualified_name; /* borrowed — d outlives this call */
            rt.short_name = d->short_name;
            rt.is_interface = d->is_interface || strcmp(d->label, "Interface") == 0 ||
                              strcmp(d->label, "Protocol") == 0;
            rt.embedded_types = py_split_pipe(arena, d->embedded_types);
            if (d->method_names_str && d->method_names_str[0]) {
                rt.method_names = py_split_pipe(arena, d->method_names_str);
            }
            py_split_field_defs(arena, d->field_defs, &rt.field_names, &rt.field_types);
            cbm_registry_add_type(reg, rt);
            py_note_known_types(known, reg);
        }
    }
    /* idx_arena == NULL skips the mid-build finalize: the tier-2 builder
     * registers one def per call — finalizing per def would rebuild the
     * buckets def_count times and leak each generation into the shared
     * registry arena. */
    if (idx_arena) {
        cbm_registry_finalize_into(reg, idx_arena);
    }

    /* Pass 2: functions and methods. */
    for (int i = 0; i < def_count; i++) {
        CBMLSPDef *d = &defs[i];
        if (!d->qualified_name || !d->short_name || !d->label)
            continue;

        if (strcmp(d->label, "Function") == 0 || strcmp(d->label, "Method") == 0) {
            CBMRegisteredFunc rf;
            memset(&rf, 0, sizeof(rf));
            rf.qualified_name = d->qualified_name; /* borrowed */
            rf.short_name = d->short_name;
            py_register_func_decorators(&rf, d->decorators);

            // Build FUNC type from "|"-separated return types.
            const char **ret_strs = py_split_pipe(arena, d->return_types);
            const CBMType **ret_types = NULL;
            if (ret_strs) {
                int n = 0;
                while (ret_strs[n])
                    n++;
                if (n > 0) {
                    ret_types = (const CBMType **)cbm_arena_alloc(
                        arena, (size_t)(n + 1) * sizeof(const CBMType *));
                    for (int j = 0; j < n; j++) {
                        ret_types[j] = cbm_type_named(arena, ret_strs[j]);
                    }
                    ret_types[n] = NULL;
                }
            }
            const char *symbol_scope = d->def_module_qn;
            /* Fallback definitions can be mixed-language. Only authoritative
             * Python metadata opts into package scope normalization. */
            if (d->lang == CBM_LANG_PYTHON &&
                !py_symbol_scope(arena, d->def_module_qn, "register", &symbol_scope))
                return false;
            PySignatureParamParserContext parser_ctx = {.module_qn = symbol_scope};
            const CBMType **param_types = cbm_type_materialize_signature_params(
                arena, d->signature_param_types, d->signature_param_count,
                py_signature_param_type_adapter, &parser_ctx);
            rf.signature = cbm_type_func(arena, NULL, param_types, ret_types);

            if (strcmp(d->label, "Method") == 0 && d->receiver_type && d->receiver_type[0]) {
                rf.receiver_type = d->receiver_type; /* borrowed */
                bool recv_known = known && known->qns
                                      ? cbm_ht_has(known->qns, rf.receiver_type)
                                      : cbm_registry_lookup_type(reg, rf.receiver_type) != NULL;
                if (!recv_known) {
                    CBMRegisteredType auto_t;
                    memset(&auto_t, 0, sizeof(auto_t));
                    auto_t.qualified_name = rf.receiver_type;
                    const char *dot = strrchr(d->receiver_type, '.');
                    auto_t.short_name = dot ? dot + 1 : rf.receiver_type; /* borrowed substring */
                    cbm_registry_add_type(reg, auto_t);
                    py_note_known_types(known, reg);
                }
            }
            cbm_registry_add_func(reg, rf);
        }
    }
    return true;
}

#ifdef CBM_ENABLE_TEST_SEAMS
bool cbm_py_lsp_test_register_defs(CBMArena *arena, CBMTypeRegistry *reg, CBMLSPDef *defs,
                                   int def_count) {
    return py_register_lsp_defs(arena, NULL, reg, defs, def_count, NULL);
}
#endif

/* ── Module namespaces: package re-exports ────────────────────────────────
 *
 * cbm_pxc_collect_all_defs carries each Python module's namespace records
 * (PyReexport / PyStarImport / PyAll, built from its ordered namespace facts)
 * next to its definitions. py_build_module_namespaces folds them into the
 * registry's export table ONCE, after the func/type indexes are finalized
 * (every probe below is a hashed lookup or a binary search) and before the
 * seal. Per module it computes the namespace its imports bind: a re-export
 * resolves its target through further re-exports (chains); a star copies the
 * source module's namespace, restricted to its literal `__all__` when it has
 * one and otherwise to names without a leading `_`; the module's own
 * definitions are never replaced. Modules are visited in sorted order and
 * records in source order; a module reached again while its own namespace is
 * being computed (an import cycle) contributes what it has so far, so every
 * cycle ends with the same answer on every run. PY_NS_MAX_DEPTH bounds only
 * the native recursion (no project re-exports through 64 modules in a row). */
enum { PY_NS_MAX_DEPTH = 64, PY_NS_MAP_MIN_CAP = 8 };

typedef struct {
    const char *name;   /* short name (borrowed); NULL = empty slot */
    const char *target; /* definition QN, registry-owned */
    bool own;           /* the module's own definition: imports never replace it */
} PyNsSlot;

typedef struct {
    PyNsSlot *slots;
    int cap; /* power of two */
    int count;
} PyNsMap;

typedef struct {
    const char *scope;
    int *records; /* def indices of PyReexport / PyStarImport, source order */
    int record_count;
    const char **all_names; /* NULL-terminated when has_all */
    bool has_all;
    bool star_source;
    int state; /* 0 = pending, 1 = computing, 2 = done */
    PyNsMap ns;
} PyNsModule;

typedef struct {
    CBMArena *scratch;
    const CBMTypeRegistry *reg;
    const CBMLSPDef *defs;
    PyNsModule *mods;
    const char **scopes; /* sorted, parallel to mods */
    int mod_count;
    CBMHashTable *by_suffix; /* dot-boundary scope tail -> module index + 1, or PY_NS_AMBIGUOUS */
} PyNsBuild;

#define PY_NS_AMBIGUOUS ((void *)(uintptr_t)UINTPTR_MAX)

static bool py_ns_is_record(const CBMLSPDef *d) {
    return strcmp(d->label, "PyReexport") == 0 || strcmp(d->label, "PyStarImport") == 0 ||
           strcmp(d->label, "PyAll") == 0;
}

static uint32_t py_ns_hash(const char *s) {
    uint32_t h = 2166136261u;
    for (; *s; s++)
        h = (h ^ (unsigned char)*s) * 16777619u;
    return h;
}

static PyNsSlot *py_ns_find(const PyNsMap *map, const char *name) {
    if (!map->slots)
        return NULL;
    uint32_t mask = (uint32_t)map->cap - 1;
    for (uint32_t i = py_ns_hash(name) & mask;; i = (i + 1) & mask) {
        PyNsSlot *s = &map->slots[i];
        if (!s->name || strcmp(s->name, name) == 0)
            return s;
    }
}

static bool py_ns_grow(CBMArena *scratch, PyNsMap *map) {
    int cap = map->cap ? map->cap * 2 : PY_NS_MAP_MIN_CAP;
    PyNsSlot *slots = (PyNsSlot *)cbm_arena_alloc(scratch, (size_t)cap * sizeof(PyNsSlot));
    if (!slots)
        return false;
    memset(slots, 0, (size_t)cap * sizeof(PyNsSlot));
    PyNsMap grown = {slots, cap, 0};
    for (int i = 0; i < map->cap; i++) {
        if (map->slots[i].name) {
            *py_ns_find(&grown, map->slots[i].name) = map->slots[i];
            grown.count++;
        }
    }
    *map = grown;
    return true;
}

/* Bind name -> target. A later import rebinds an earlier one (Python's
 * semantics); nothing rebinds the module's own definition. */
static void py_ns_put(CBMArena *scratch, PyNsMap *map, const char *name, const char *target,
                      bool own) {
    if ((map->count + 1) * 2 > map->cap && !py_ns_grow(scratch, map))
        return;
    PyNsSlot *s = py_ns_find(map, name);
    if (s->name && s->own)
        return;
    if (!s->name)
        map->count++;
    s->name = name;
    s->target = target;
    s->own = own;
}

static int py_ns_module_index(const PyNsBuild *b, const char *scope) {
    int lo = 0;
    int hi = b->mod_count - 1;
    while (lo <= hi) {
        int mid = lo + (hi - lo) / 2;
        int cmp = strcmp(b->scopes[mid], scope);
        if (cmp == 0)
            return mid;
        if (cmp < 0)
            lo = mid + 1;
        else
            hi = mid - 1;
    }
    return -1;
}

static void py_ns_compute(PyNsBuild *b, int m, int depth);

/* The definition `qn` names: itself when registered, else the name its
 * module's namespace binds (a chained re-export), else NULL. */
static const char *py_ns_resolve(PyNsBuild *b, const char *qn, int depth) {
    const CBMRegisteredFunc *f = cbm_registry_lookup_func(b->reg, qn);
    if (f)
        return f->qualified_name;
    const CBMRegisteredType *t = cbm_registry_lookup_type(b->reg, qn);
    if (t)
        return t->qualified_name;
    const char *dot = strrchr(qn, '.');
    if (!dot || dot == qn || depth > PY_NS_MAX_DEPTH)
        return NULL;
    char *scope = cbm_arena_strndup(b->scratch, qn, (size_t)(dot - qn));
    int m = scope ? py_ns_module_index(b, scope) : -1;
    if (m < 0)
        return NULL;
    py_ns_compute(b, m, depth + 1);
    const PyNsSlot *s = py_ns_find(&b->mods[m].ns, dot + 1);
    return s && s->name ? s->target : NULL; /* NULL target = tombstone */
}

/* The parent of a dotted scope ("a.b.c" -> "a.b"), or NULL at the root. */
static char *py_ns_parent(CBMArena *scratch, const char *scope) {
    const char *dot = strrchr(scope, '.');
    return dot && dot > scope ? cbm_arena_strndup(scratch, scope, (size_t)(dot - scope)) : NULL;
}

/* Module index a record raw module spec names, seen from the module that
 * wrote it (importer_qn: its raw module QN, `.__init__` kept), or -1.
 * Relative (`..pkg.mod`): the importer package -- the importer itself for a
 * package `__init__`, else its parent -- ascended once per further dot, then
 * the dotted rest; exact. Absolute (`app.db.models`): the one project module
 * scope whose dot-boundary tail spells it; none or several = unknown (a
 * vendored copy, an external module), never a guess between candidates. */
static int py_ns_resolve_spec(PyNsBuild *b, const char *spec, const char *importer_qn) {
    if (!spec || !importer_qn)
        return -1;
    size_t level = 0;
    while (spec[level] == '.')
        level++;
    const char *rest = spec + level;
    if (level == 0) {
        void *v = b->by_suffix ? cbm_ht_get(b->by_suffix, rest) : NULL;
        if (!v || v == PY_NS_AMBIGUOUS)
            return -1;
        return (int)((uintptr_t)v - 1);
    }
    size_t scope_len = cbm_fqn_symbol_scope_len(importer_qn);
    char *pkg = cbm_arena_strndup(b->scratch, importer_qn, scope_len);
    bool is_package = importer_qn[scope_len] != '\0';
    if (pkg && !is_package)
        pkg = py_ns_parent(b->scratch, pkg);
    for (size_t up = 1; pkg && up < level; up++)
        pkg = py_ns_parent(b->scratch, pkg);
    if (!pkg)
        return -1;
    const char *module = rest[0] ? cbm_arena_sprintf(b->scratch, "%s.%s", pkg, rest) : pkg;
    return module ? py_ns_module_index(b, module) : -1;
}

/* Index every dot-boundary tail of every module scope ("p.app.db" -> "app.db",
 * "db"); a tail two modules share is ambiguous. */
static bool py_ns_build_suffix_index(PyNsBuild *b) {
    b->by_suffix = cbm_ht_create((uint32_t)(b->mod_count * 4 + 16));
    if (!b->by_suffix)
        return false;
    for (int m = 0; m < b->mod_count; m++) {
        const char *s = b->scopes[m];
        for (const char *tail = s; tail; tail = strchr(tail, '.') ? strchr(tail, '.') + 1 : NULL) {
            void *prev = cbm_ht_get(b->by_suffix, tail);
            cbm_ht_set(b->by_suffix, tail, prev ? PY_NS_AMBIGUOUS : (void *)(uintptr_t)(m + 1));
        }
    }
    return true;
}

/* An unresolvable star is a whole-namespace barrier: every name the
 * module's imports bound so far becomes unknown (a tombstone, so the
 * open-addressing chains stay intact); own definitions stay. */
static void py_ns_barrier(PyNsModule *mod) {
    for (int i = 0; i < mod->ns.cap; i++) {
        if (mod->ns.slots[i].name && !mod->ns.slots[i].own)
            mod->ns.slots[i].target = NULL;
    }
}

/* `from src import *` into dst. */
static void py_ns_star_merge(PyNsBuild *b, PyNsModule *dst, const PyNsModule *src) {
    if (src->has_all) {
        for (int i = 0; src->all_names && src->all_names[i]; i++) {
            const PyNsSlot *s = py_ns_find(&src->ns, src->all_names[i]);
            if (s && s->name && s->target)
                py_ns_put(b->scratch, &dst->ns, s->name, s->target, false);
        }
        return;
    }
    for (int i = 0; i < src->ns.cap; i++) {
        const PyNsSlot *s = &src->ns.slots[i];
        if (s->name && s->target && s->name[0] != '_')
            py_ns_put(b->scratch, &dst->ns, s->name, s->target, false);
    }
}

static void py_ns_compute(PyNsBuild *b, int m, int depth) {
    PyNsModule *mod = &b->mods[m];
    if (mod->state != 0 || depth > PY_NS_MAX_DEPTH)
        return;
    mod->state = 1;
    for (int r = 0; r < mod->record_count; r++) {
        const CBMLSPDef *d = &b->defs[mod->records[r]];
        if (!d->receiver_type)
            continue;
        int src = py_ns_resolve_spec(b, d->receiver_type, d->def_module_qn);
        if (strcmp(d->label, "PyReexport") == 0) {
            const char *qn =
                src >= 0 && d->method_names_str
                    ? cbm_arena_sprintf(b->scratch, "%s.%s", b->scopes[src], d->method_names_str)
                    : NULL;
            const char *target = qn ? py_ns_resolve(b, qn, depth + 1) : NULL;
            /* unresolved: the name is still rebound, to something unknown */
            py_ns_put(b->scratch, &mod->ns, d->short_name, target, false);
            continue;
        }
        if (src < 0) {
            py_ns_barrier(mod);
            continue;
        }
        if (src == m)
            continue;
        py_ns_compute(b, src, depth + 1);
        py_ns_star_merge(b, mod, &b->mods[src]);
    }
    mod->state = 2;
}

static int py_ns_cmp_str(const void *a, const void *b) {
    return strcmp(*(const char *const *)a, *(const char *const *)b);
}

typedef struct {
    const char *key;
    const char *target;
} PyNsExport;

static int py_ns_cmp_export(const void *a, const void *b) {
    return strcmp(((const PyNsExport *)a)->key, ((const PyNsExport *)b)->key);
}

/* The symbol scope of a module QN (a package's `.__init__` dropped). */
static const char *py_ns_scope(CBMArena *scratch, const char *module_qn) {
    return cbm_arena_strndup(scratch, module_qn, cbm_fqn_symbol_scope_len(module_qn));
}

/* Sorted, de-duplicated module scopes of every Python def and record (and
 * every star source). Returns the count; def_scope[i] is def i's scope
 * (NULL when def i is skipped). */
static int py_ns_collect_scopes(PyNsBuild *b, int def_count, bool check_lang,
                                const char **def_scope) {
    const char **all =
        (const char **)cbm_arena_alloc(b->scratch, (size_t)(def_count * 2 + 1) * sizeof(char *));
    if (!all)
        return -1;
    int n = 0;
    for (int i = 0; i < def_count; i++) {
        const CBMLSPDef *d = &b->defs[i];
        def_scope[i] = NULL;
        if ((check_lang && d->lang != CBM_LANG_PYTHON) || !d->label || !d->qualified_name ||
            !d->def_module_qn)
            continue;
        def_scope[i] = py_ns_scope(b->scratch, d->def_module_qn);
        if (!def_scope[i])
            continue;
        all[n++] = def_scope[i];
    }
    qsort(all, (size_t)n, sizeof(char *), py_ns_cmp_str);
    int u = 0;
    for (int i = 0; i < n; i++) {
        if (u == 0 || strcmp(all[u - 1], all[i]) != 0)
            all[u++] = all[i];
    }
    b->scopes = all;
    return u;
}

/* Attach records, __all__ lists and (for star sources) own top-level
 * definitions to their modules. */
static bool py_ns_attach(PyNsBuild *b, int def_count, const char **def_scope) {
    int *def_mod = (int *)cbm_arena_alloc(b->scratch, (size_t)(def_count + 1) * sizeof(int));
    if (!def_mod)
        return false;
    for (int i = 0; i < def_count; i++) {
        const CBMLSPDef *d = &b->defs[i];
        def_mod[i] = def_scope[i] ? py_ns_module_index(b, def_scope[i]) : -1;
        if (def_mod[i] < 0 || !py_ns_is_record(d))
            continue;
        PyNsModule *mod = &b->mods[def_mod[i]];
        if (strcmp(d->label, "PyAll") == 0) {
            mod->has_all = true;
            mod->all_names = py_split_pipe(b->scratch, d->method_names_str);
            continue;
        }
        mod->record_count++;
        if (strcmp(d->label, "PyStarImport") == 0 && d->receiver_type) {
            int src = py_ns_resolve_spec(b, d->receiver_type, d->def_module_qn);
            if (src >= 0)
                b->mods[src].star_source = true;
        }
    }
    for (int m = 0; m < b->mod_count; m++) {
        PyNsModule *mod = &b->mods[m];
        if (mod->record_count > 0) {
            mod->records =
                (int *)cbm_arena_alloc(b->scratch, (size_t)mod->record_count * sizeof(int));
            if (!mod->records)
                return false;
            mod->record_count = 0;
        }
    }
    for (int i = 0; i < def_count; i++) {
        if (def_mod[i] < 0)
            continue;
        const CBMLSPDef *d = &b->defs[i];
        PyNsModule *mod = &b->mods[def_mod[i]];
        if (py_ns_is_record(d)) {
            if (strcmp(d->label, "PyAll") != 0)
                mod->records[mod->record_count++] = i;
            continue;
        }
        /* A star source exports its own top-level classes and functions
         * (direct children of the module scope, never methods). */
        size_t scope_len = strlen(def_scope[i]);
        if (!mod->star_source || !d->short_name || d->receiver_type ||
            strncmp(d->qualified_name, def_scope[i], scope_len) != 0 ||
            d->qualified_name[scope_len] != '.' ||
            strcmp(d->qualified_name + scope_len + 1, d->short_name) != 0)
            continue;
        const CBMRegisteredFunc *f = cbm_registry_lookup_func(b->reg, d->qualified_name);
        const CBMRegisteredType *t = f ? NULL : cbm_registry_lookup_type(b->reg, d->qualified_name);
        const char *target = f ? f->qualified_name : t ? t->qualified_name : NULL;
        if (target)
            py_ns_put(b->scratch, &mod->ns, d->short_name, target, true);
    }
    return true;
}

/* Copy the computed namespaces (import-bound names only) and the module set
 * into the registry's arena, sorted for binary search. */
static void py_ns_publish(PyNsBuild *b, CBMTypeRegistry *reg) {
    int total = 0;
    for (int m = 0; m < b->mod_count; m++) {
        for (int i = 0; i < b->mods[m].ns.cap; i++)
            total += b->mods[m].ns.slots[i].name && !b->mods[m].ns.slots[i].own &&
                     b->mods[m].ns.slots[i].target;
    }
    const char **module_qns =
        (const char **)cbm_arena_alloc(reg->arena, (size_t)(b->mod_count + 1) * sizeof(char *));
    PyNsExport *exports =
        (PyNsExport *)cbm_arena_alloc(b->scratch, (size_t)(total + 1) * sizeof(PyNsExport));
    const char **keys =
        (const char **)cbm_arena_alloc(reg->arena, (size_t)(total + 1) * sizeof(char *));
    const char **targets =
        (const char **)cbm_arena_alloc(reg->arena, (size_t)(total + 1) * sizeof(char *));
    if (!module_qns || !exports || !keys || !targets)
        return;
    int n = 0;
    for (int m = 0; m < b->mod_count; m++) {
        module_qns[m] = cbm_arena_strdup(reg->arena, b->scopes[m]);
        const PyNsMap *ns = &b->mods[m].ns;
        for (int i = 0; i < ns->cap; i++) {
            const PyNsSlot *s = &ns->slots[i];
            if (!s->name || s->own || !s->target)
                continue;
            exports[n].key = cbm_arena_sprintf(reg->arena, "%s.%s", b->scopes[m], s->name);
            exports[n].target = s->target;
            if (exports[n].key)
                n++;
        }
    }
    qsort(exports, (size_t)n, sizeof(PyNsExport), py_ns_cmp_export);
    for (int i = 0; i < n; i++) {
        keys[i] = exports[i].key;
        targets[i] = exports[i].target;
    }
    reg->module_qns = module_qns;
    reg->module_count = b->mod_count;
    reg->export_keys = keys;
    reg->export_targets = targets;
    reg->export_count = n;
}

/* Build reg's module set and export table from defs[]. reg must be
 * finalized and not yet sealed. check_lang: defs[] is mixed-language. */
static void py_build_module_namespaces(CBMTypeRegistry *reg, CBMLSPDef *defs, int def_count,
                                       bool check_lang) {
    if (!reg || !defs || def_count <= 0 || reg->read_only)
        return;
    CBMArena scratch;
    cbm_arena_init(&scratch);
    PyNsBuild b = {.scratch = &scratch, .reg = reg, .defs = defs};
    const char **def_scope =
        (const char **)cbm_arena_alloc(&scratch, (size_t)def_count * sizeof(char *));
    int mod_count = def_scope ? py_ns_collect_scopes(&b, def_count, check_lang, def_scope) : -1;
    if (mod_count > 0) {
        b.mod_count = mod_count;
        b.mods = (PyNsModule *)cbm_arena_alloc(&scratch, (size_t)mod_count * sizeof(PyNsModule));
    }
    if (b.mods) {
        memset(b.mods, 0, (size_t)mod_count * sizeof(PyNsModule));
        for (int m = 0; m < mod_count; m++)
            b.mods[m].scope = b.scopes[m];
        if (py_ns_build_suffix_index(&b) && py_ns_attach(&b, def_count, def_scope)) {
            for (int m = 0; m < mod_count; m++)
                py_ns_compute(&b, m, 0);
            py_ns_publish(&b, reg);
        }
    }
    cbm_ht_free(b.by_suffix);
    cbm_arena_destroy(&scratch);
}

bool cbm_run_py_lsp_cross(CBMArena *arena, const char *source, int source_len,
                          const char *module_qn, CBMLSPDef *defs, int def_count,
                          const char **import_names, const char **import_qns, int import_count,
                          TSTree *cached_tree, CBMResolvedCallArray *out,
                          CBMCallArray *synthetic_calls) {
    return cbm_run_py_lsp_cross_status(arena, source, source_len, module_qn, defs, def_count,
                                       import_names, import_qns, import_count, cached_tree, out,
                                       synthetic_calls) == CBM_LSP_COMPLETE;
}

CBMLSPStatus cbm_run_py_lsp_cross_status(CBMArena *arena, const char *source, int source_len,
                                         const char *module_qn, CBMLSPDef *defs, int def_count,
                                         const char **import_names, const char **import_qns,
                                         int import_count, TSTree *cached_tree,
                                         CBMResolvedCallArray *out, CBMCallArray *synthetic_calls) {
    if (!arena || !source || source_len <= 0 || !out)
        return CBM_LSP_COMPLETE;

    TSParser *parser = NULL;
    TSTree *tree = cached_tree;
    bool owns_tree = false;
    if (!tree) {
        parser = ts_parser_new();
        if (!parser)
            return CBM_LSP_COMPLETE;
        ts_parser_set_language(parser, tree_sitter_python());
        tree = cbm_parse_source(parser, source, (uint32_t)source_len, (TSParseOptions){0});
        owns_tree = true;
        if (!tree) {
            ts_parser_delete(parser);
            return CBM_LSP_COMPLETE;
        }
    }
    TSNode root = ts_tree_root_node(tree);

    CBMTypeRegistry reg;
    cbm_registry_init(&reg, arena);
    cbm_python_stdlib_register(&reg, arena);
    /* per-file path: defs[] already filtered by caller, no lang-check needed */
    /* Index allocations go to a per-call scratch arena (see php_lsp_cross). */
    CBMArena idx_arena;
    cbm_arena_init(&idx_arena);
    PyLSPContext ctx;
    py_lsp_init_for_stage(&ctx, arena, source, source_len, &reg, module_qn, out, "cross");
    if (ctx.eval_failure)
        goto cross_cleanup;
    if (!py_register_lsp_defs(arena, &idx_arena, &reg, defs, def_count, NULL)) {
        ctx.eval_failure = CBM_LSP_SCOPE_FAILED;
        goto cross_cleanup;
    }
    py_mark_ambiguous_callable_bindings(&reg, &idx_arena);

    /* Finalize registry — O(1) lookups. See go_lsp.c "3c. Finalize"
     * comment for the rationale. */
    cbm_registry_finalize_into(&reg, &idx_arena);
    py_build_module_namespaces(&reg, defs, def_count, false);

    ctx.syn_calls = synthetic_calls;
    for (int i = 0; i < import_count; i++) {
        if (import_names && import_qns && import_names[i] && import_qns[i]) {
            py_lsp_add_import(&ctx, import_names[i], import_qns[i]);
        }
    }
    py_memo_test_stage(&ctx, "cross");
    py_lsp_process_file(&ctx, root);
cross_cleanup:
    cbm_arena_destroy(&idx_arena);

    if (owns_tree && tree)
        ts_tree_delete(tree);
    if (parser)
        ts_parser_delete(parser);
    return ctx.eval_failure;
}

/* ── Tier 2: pre-built per-language registry (mirrors Go pilot) ── */
CBMTypeRegistry *cbm_py_build_cross_registry(CBMArena *arena, CBMLSPDef *defs, int def_count) {
    if (!arena)
        return NULL;
    CBMTypeRegistry *reg = (CBMTypeRegistry *)cbm_arena_alloc(arena, sizeof(*reg));
    if (!reg)
        return NULL;
    cbm_registry_init(reg, arena);
    cbm_python_stdlib_register(reg, arena);

    /* The registry is not finalized until the end, so probing it for each
     * Method's receiver scanned every type: O(methods x types), single-threaded
     * (~54 s of lsp_cross_prepare on a large Python tree). Probe a set of
     * the registered type QNs instead; registration order is unchanged. Sized
     * for the stdlib seed, not def_count (the mixed all-language count). NULL
     * on allocation failure: the registry probe runs as before. */
    PyKnownTypes known = {cbm_ht_create((uint32_t)reg->type_count), 0};
    py_note_known_types(&known, reg);

    /* Filter to Python defs only — defs[] is mixed-language all_defs. */
    for (int i = 0; i < def_count; i++) {
        CBMLSPDef *d = &defs[i];
        if (d->lang != CBM_LANG_PYTHON)
            continue;
        /* Reuse the existing register fn on a single-def slice (n=1 inline). */
        if (!py_register_lsp_defs(arena, NULL, reg, d, 1, &known)) {
            cbm_ht_free(known.qns);
            return NULL; /* caller owns the shared arena and other registries */
        }
    }
    cbm_ht_free(known.qns);

    py_mark_ambiguous_callable_bindings(reg, arena);
    cbm_registry_build_type_qn_order(reg, arena);
    cbm_registry_finalize(reg);
    /* Export table: after finalize (hashed probes), before the seal. */
    py_build_module_namespaces(reg, defs, def_count, true);
    reg->read_only = true; /* seal: shared Tier-2 registry is read-only during resolve */
    return reg;
}

bool cbm_run_py_lsp_cross_with_registry(CBMArena *arena, const char *source, int source_len,
                                        const char *module_qn, CBMTypeRegistry *reg,
                                        const char **import_names, const char **import_qns,
                                        int import_count, TSTree *cached_tree,
                                        CBMResolvedCallArray *out, CBMCallArray *synthetic_calls) {
    return cbm_run_py_lsp_cross_with_registry_status(
               arena, source, source_len, module_qn, reg, import_names, import_qns, import_count,
               cached_tree, out, synthetic_calls) == CBM_LSP_COMPLETE;
}

CBMLSPStatus cbm_run_py_lsp_cross_with_registry_status(
    CBMArena *arena, const char *source, int source_len, const char *module_qn,
    CBMTypeRegistry *reg, const char **import_names, const char **import_qns, int import_count,
    TSTree *cached_tree, CBMResolvedCallArray *out, CBMCallArray *synthetic_calls) {
    if (!arena || !source || source_len <= 0 || !out || !reg)
        return CBM_LSP_COMPLETE;

    TSParser *parser = NULL;
    TSTree *tree = cached_tree;
    bool owns_tree = false;
    if (!tree) {
        parser = ts_parser_new();
        if (!parser)
            return CBM_LSP_COMPLETE;
        ts_parser_set_language(parser, tree_sitter_python());
        tree = cbm_parse_source(parser, source, (uint32_t)source_len, (TSParseOptions){0});
        owns_tree = true;
        if (!tree) {
            ts_parser_delete(parser);
            return CBM_LSP_COMPLETE;
        }
    }
    TSNode root = ts_tree_root_node(tree);

    PyLSPContext ctx;
    py_lsp_init_for_stage(&ctx, arena, source, source_len, reg, module_qn, out, "cross");
    if (ctx.eval_failure)
        goto prebuilt_cleanup;
    ctx.syn_calls = synthetic_calls;
    for (int i = 0; i < import_count; i++) {
        if (import_names && import_qns && import_names[i] && import_qns[i]) {
            py_lsp_add_import(&ctx, import_names[i], import_qns[i]);
        }
    }
    py_memo_test_stage(&ctx, "cross");
    py_lsp_process_file(&ctx, root);
prebuilt_cleanup:
    if (owns_tree && tree)
        ts_tree_delete(tree);
    if (parser)
        ts_parser_delete(parser);
    return ctx.eval_failure;
}

bool cbm_batch_py_lsp_cross(CBMArena *arena, CBMBatchPyLSPFile *files, int file_count,
                            CBMResolvedCallArray *out) {
    if (!arena || !files || file_count <= 0 || !out)
        return true;

    bool complete = true;
    for (int f = 0; f < file_count; f++) {
        CBMBatchPyLSPFile *file = &files[f];
        memset(&out[f], 0, sizeof(CBMResolvedCallArray));
        if (!file->source || file->source_len <= 0)
            continue;

        CBMArena file_arena;
        cbm_arena_init(&file_arena);

        CBMResolvedCallArray file_out;
        memset(&file_out, 0, sizeof(file_out));

        if (!cbm_run_py_lsp_cross(&file_arena, file->source, file->source_len, file->module_qn,
                                  file->defs, file->def_count, file->import_names, file->import_qns,
                                  file->import_count, file->cached_tree, &file_out, NULL))
            complete = false;

        if (file_out.count > 0) {
            out[f].count = file_out.count;
            out[f].items = (CBMResolvedCall *)cbm_arena_alloc(arena, (size_t)file_out.count *
                                                                         sizeof(CBMResolvedCall));
            if (out[f].items) {
                for (int j = 0; j < file_out.count; j++) {
                    CBMResolvedCall *src = &file_out.items[j];
                    CBMResolvedCall *dst = &out[f].items[j];
                    memset(dst, 0, sizeof(*dst));
                    dst->caller_qn =
                        src->caller_qn ? cbm_arena_strdup(arena, src->caller_qn) : NULL;
                    dst->callee_qn =
                        src->callee_qn ? cbm_arena_strdup(arena, src->callee_qn) : NULL;
                    dst->strategy = src->strategy ? cbm_arena_strdup(arena, src->strategy) : NULL;
                    dst->confidence = src->confidence;
                    dst->reason = src->reason ? cbm_arena_strdup(arena, src->reason) : NULL;
                    dst->kind = src->kind;
                    dst->site_start_byte = src->site_start_byte;
                    dst->site_end_byte = src->site_end_byte;
                }
            } else {
                out[f].count = 0;
            }
        }

        cbm_arena_destroy(&file_arena);
    }
    return complete;
}

/* ── Stdlib stub — Phase 10 replaces with auto-generated body ─── */

#ifndef CBM_PYTHON_STDLIB_GENERATED
void cbm_python_stdlib_register(CBMTypeRegistry *reg, CBMArena *arena) {
    (void)reg;
    (void)arena;
}
#endif