// Copyright (c) 2026 Alexander Medvednikov. All rights reserved.
// Use of this source code is governed by an MIT license
// that can be found in the LICENSE file.
module transformer

import v2.ast
import v2.token
import v2.types

// flat_write.v scaffolds the "transformer writes flat directly" multi-session
// port. The wedge `transform_files_to_flat` (transformer.v ~line 1855) today
// composes the legacy per-file transform with a boundary `ast.flatten_files()`
// so callers can adopt the flat-output API now. The peak-memory win documented
// in project_v2_flat_migration.md only materialises when the per-file rewrite
// sites stop materialising legacy `ast.File` / `ast.Stmt` / `ast.Expr` values
// and emit `FlatNode`s into the supplied `ast.FlatBuilder` directly.
//
// The entry point is `transform_file_index_to_flat` below. Its body is the
// staging ground for the port: every session in the plan replaces one rewrite
// site inside `transform_file` with a flat-emitting equivalent, leaving the
// outer signature stable. The differential harness in
// transformer_flat_diff_test.v pins both the wedge invariant (4th row,
// `to_flat_*`) and the per-file invariant (5th row, `per_file_*`) so each
// session's change must keep both signatures bit-equal.
//
// ----- Migration phases -----
//
// The 55-site audit from session 1 is the inventory of work, but the port
// itself decomposes into roughly six phases. Each phase ships one
// architectural seam; the per-rewrite-site ports of phase 4 are then
// mechanical follow-ups that plug into the seams.
//
// Phase 1 (DONE, session 1): scaffolding.
//   `transform_file_index_to_flat` exists. Harness 5th row pins per-file
//   parity against a manual rehydrate+transform+append loop. Body is the
//   identity decomposition: rehydrate + transform_file + append_file.
//
// Phase 2 (DONE, session 2): file-level emission decomposition.
//   `ast.FlatBuilder.append_file_with_stmt_ids` accepts pre-emitted stmt
//   FlatNodeIds for the file's stmt list. `transform_file_index_to_flat`
//   now mirrors `transform_file`'s prologue itself, runs `transform_stmts`
//   for the body, and emits each transformed stmt via the new per-stmt
//   seam (`transform_stmt_to_flat` → `out.emit_stmt(...)`). The post-stmt
//   file root is assembled via `append_file_with_stmt_ids`. The per-stmt
//   seam is where phases 3..5 plug per-variant direct-emit logic.
//
// Phase 3 (DONE, session 3): per-stmt direct-emit dispatch.
//   `transform_file_index_to_flat` now bypasses `transform_stmts` at the
//   file level (top-level stmts never trigger its multi-stmt expansions —
//   all those paths live in function bodies). `transform_stmt_to_flat`
//   carries an 11-variant leaf-arm match for stmt kinds that are identity
//   in `transform_stmt`'s `else { stmt }` case (AsmStmt, Directive,
//   EmptyStmt, EnumDecl, FlowControlStmt, ImportStmt, InterfaceDecl,
//   ModuleStmt, StructDecl, TypeDecl, []Attribute); these direct-emit and
//   skip `transform_stmt` entirely. Non-leaf arms take the legacy
//   round-trip `out.emit_stmt(t.transform_stmt(stmt))`. The dispatch
//   surface is now ready for phase 4 ports.
//
// Phase 4 (IN PROGRESS — per-rewrite-site ports).
//   For each non-leaf Stmt variant (AssignStmt, BlockStmt, ConstDecl,
//   DeferStmt, ExprStmt, FnDecl, ForStmt, ForInStmt, GlobalDecl,
//   ComptimeStmt, LabelStmt, ReturnStmt, AssertStmt) rewrite the rewrite
//   logic inside `transform_X` to emit `FlatNode`s via `out.emit(...)`
//   directly instead of constructing legacy `ast.Stmt` / `ast.Expr`
//   values. The inventory below is the checklist.
//
//   Session 1 (2026-05-26): expression dispatch surface + GlobalDecl port.
//     `transform_expr_to_flat` mirrors `transform_stmt_to_flat`'s shape with
//     9 leaf-arm direct-emit variants (BasicLiteral, EmptyExpr, Keyword,
//     LifetimeExpr, RangeExpr, SelectExpr, StringLiteral, Tuple, Type — all
//     identity in `transform_expr`'s `else { expr }` case); non-leaf arms
//     take the legacy round-trip `out.emit_expr(t.transform_expr(expr))`.
//     The GlobalDecl arm in `transform_stmt_to_flat` direct-emits via
//     `transform_expr_to_flat` for each field's typ/value plus the new
//     `emit_field_decl_by_ids` / `emit_global_decl_by_ids` builder helpers,
//     skipping the `transform_global_decl` round-trip entirely. The
//     `__global init` fixture in the 5th harness row pins it.
//
//   Session 2 (2026-05-26): ConstDecl port + harness fixture.
//     The ConstDecl arm in `transform_stmt_to_flat` direct-emits via
//     `transform_expr_to_flat` for each field's value plus the new
//     `emit_field_init_by_id` / `emit_const_decl_by_ids` builder helpers,
//     skipping the `transform_const_decl` round-trip entirely. Mirrors the
//     GlobalDecl shape but uses FieldInit (name + value only, no typ/attrs)
//     and carries the `is_public` flag. A new `fixture_const_decl` covers
//     leaf (BasicLiteral, StringLiteral) and non-leaf (InfixExpr) const
//     values across all 5 harness rows.
//
//   Session 3 (2026-05-26): FnDecl dispatch arm (shape port).
//     The FnDecl arm in `transform_stmt_to_flat` calls `transform_fn_decl`
//     for the body work (prologue / scope setup / `transform_stmts` /
//     defer lowering — the next port target) but decomposes the resulting
//     `ast.FnDecl` and emits via the new `emit_parameter` / `emit_type` /
//     `emit_fn_decl_by_ids` builder helpers. Body stmts go through
//     `out.emit_stmt(body_stmt)` per stmt and the list is assembled via
//     `emit_aux_list_from_ids`. Bit-equal to the legacy
//     `out.emit_stmt(t.transform_fn_decl(stmt))` round-trip; the value is
//     that the dispatch arm now exists, so the next session can refactor
//     `transform_fn_decl` to emit body stmts straight into the builder
//     without touching this dispatch site. Every existing fixture
//     exercises this arm — all 46 harness tests pin it.
//
//   Session 4 (2026-05-26): FnDecl wrapper-struct elision.
//     Extracts `transform_fn_decl_parts(decl) (attrs, stmts)` in fn.v as
//     the body-work driver — returns the two variable parts of the lowered
//     FnDecl (final attribute list and final transformed + defer-lowered
//     stmts) and leaves the immutable name / typ / receiver / language /
//     is_public / is_method / is_static / pos fields to be re-attached by
//     the caller. Existing `transform_fn_decl` becomes a thin wrapper that
//     calls the helper and assembles the `ast.FnDecl` (no behavioural
//     change for legacy callers). The FnDecl flat-write arm now calls
//     `transform_fn_decl_parts` directly, so the `ast.FnDecl` wrapper
//     struct that session 3 built and then decomposed is never allocated.
//     First real (if modest) memory saving in the flat-write port: one
//     FnDecl struct per fn under flat-output paths.
//
//   Session 5 (2026-05-26): ParenExpr expr direct-emit + harness fixture.
//     The ParenExpr arm in `transform_expr_to_flat` direct-emits via a
//     recursive `transform_expr_to_flat` for the inner expression plus the
//     new `emit_paren_expr_by_id` builder helper, skipping the
//     `ast.ParenExpr` struct allocation per occurrence (the `transform_expr`
//     ParenExpr arm just recurses + rebuilds the wrapper — identity in
//     shape). First non-leaf *expression* port — paves the way for porting
//     larger expression rewrites (PrefixExpr, CastExpr, InfixExpr ...) into
//     the dispatch surface. New `fixture_paren_expr` (file-scope consts
//     wrapping leaf and nested-paren values) covers the arm across all 5
//     harness rows — 46 → 51 transformer-diff tests.
//
//   Session 6 (2026-05-26): PrefixExpr expr direct-emit + harness fixture.
//     The PrefixExpr arm in `transform_expr_to_flat` direct-emits via a
//     recursive `transform_expr_to_flat` for the inner expression plus the
//     new `emit_prefix_expr_by_id` builder helper, skipping the
//     `ast.PrefixExpr` struct allocation for the common case (unary `-`,
//     `~`, `!`). Two legacy fallback guards keep semantics intact:
//     `expr.op == .amp` (transform_prefix_expr removes `&` redundancy with
//     attribute-aware lowering — not bit-equal to a structural rebuild) and
//     `expr.op == .arrow && expr.expr is ast.OrExpr` (channel-recv with
//     or-block is lowered by `expand_chan_recv_or_expr` — full
//     statement-list synthesis). Both stay on the round-trip
//     `out.emit_expr(t.transform_expr(expr))` path. New
//     `fixture_prefix_expr` (file-scope consts with `-`, `~`, `!`) covers
//     the arm across all 5 harness rows — 51 → 56 transformer-diff tests.
//
//   Session 7 (2026-05-26): ModifierExpr expr direct-emit + harness fixture.
//     The ModifierExpr arm in `transform_expr_to_flat` direct-emits via a
//     recursive `transform_expr_to_flat` for the inner expression plus the
//     new `emit_modifier_expr_by_id` builder helper, skipping the
//     `ast.ModifierExpr` struct allocation per occurrence (`mut x`,
//     `shared x`, `atomic x`, `static x`, `volatile x` — all pure wrappers
//     around the inner expression in `transform_expr`'s arm; kind + pos
//     copied verbatim). Structurally identical to the ParenExpr session
//     except the kind token packs into the meta u16 (mirror of
//     `add_expr(ModifierExpr)`'s encoding). New `fixture_modifier_expr`
//     (a `mut`-parameter fn + a caller that passes `mut a`) covers the arm
//     across all 5 harness rows — 56 → 61 transformer-diff tests.
//
//   Session 8 (2026-05-26): LambdaExpr expr direct-emit + harness fixture.
//     The LambdaExpr arm in `transform_expr_to_flat` direct-emits via a
//     recursive `transform_expr_to_flat` for the body expression plus a
//     leaf `out.emit_expr(ast.Expr(arg))` per arg Ident and the new
//     `emit_lambda_expr_by_ids` builder helper. The `transform_expr` arm
//     for LambdaExpr is a pure wrapper — args are an `[]Ident` copied
//     verbatim, only the body `expr.expr` is transformed — so direct-emit
//     mirrors that exactly: leaf args go through the legacy `emit_expr`
//     leaf path (Idents are identity), body goes through the recursive
//     direct-emit. Mirrors `add_expr(LambdaExpr)` encoding exactly:
//     edge[0] = body expr, edge[1..] = args. New `fixture_lambda_expr`
//     (an `apply(f fn (int) int, x int)` higher-order fn + a caller that
//     passes `|y| y + 1`) covers the arm across all 5 harness rows —
//     61 → 66 transformer-diff tests.
//
//   Session 9 (2026-05-26): FnLiteral expr direct-emit + harness fixture.
//     The FnLiteral arm in `transform_expr_to_flat` direct-emits via:
//     `out.emit_type(ast.Type(expr.typ))` for the FnType (verbatim, leaf),
//     `out.emit_expr(cv)` per captured_var (verbatim, leaf), and
//     `transform_stmts(expr.stmts)` + `out.emit_stmt(...)` per result for
//     the body stmts (still allocates a `[]Stmt` — the stmt-list expansion
//     seam is the next big port target), then the new
//     `emit_fn_literal_by_ids` builder helper. Skips the
//     `ast.FnLiteral` wrapper struct allocation per occurrence. Mirrors
//     `add_expr(FnLiteral)` encoding exactly: edge[0] = type,
//     edge[1..1+captured.len] = captured_vars, edge[1+captured.len..] =
//     stmts; `captured_vars.len` is packed into `extra`. New
//     `fixture_fn_literal` (a `make_doubler()` returning `fn (x int) int`
//     + a `use_fn_literal()` that binds a `fn (n int) int` to a local and
//     calls it) covers the arm across all 5 harness rows — 66 → 71
//     transformer-diff tests.
//
//   Session 10 (2026-05-26): PostfixExpr expr direct-emit + harness fixture.
//     The PostfixExpr arm in `transform_expr_to_flat` direct-emits via a
//     recursive `transform_expr_to_flat` for the inner expression plus the
//     new `emit_postfix_expr_by_id` builder helper. Skips the
//     `ast.PostfixExpr` struct allocation for the plain postfix ops (`++`
//     / `--`, i.e. `.inc` / `.dec`). One legacy fallback guard:
//     `expr.op == .not || expr.op == .question` — these ops trigger
//     non-trivial lowering in `transform_expr` (native backends keep
//     postfix; non-native rewrite `expr!` / `expr?` into a CastExpr over
//     the inner Result/Option base type plus string-range rename
//     `substr` → `substr_checked` plus unwrap fallback). These produce
//     different expression shapes, so they stay on the legacy round-trip.
//     New `fixture_postfix_expr` (a fn that mut-binds a local then runs
//     `a++` / `a--`) covers the arm across all 5 harness rows — 71 → 76
//     transformer-diff tests.
//
//   Session 11 (2026-05-26): CastExpr expr direct-emit + harness fixture.
//     The CastExpr arm in `transform_expr_to_flat` direct-emits via the
//     leaf `out.emit_expr(expr.typ)` (type is NOT transformed by
//     `transform_expr` — copied verbatim) plus a recursive
//     `transform_expr_to_flat` for the inner expression, then assembles
//     via the new `emit_cast_expr_by_ids` builder helper. Skips the
//     `ast.CastExpr` struct allocation per occurrence in the common case
//     (primitive casts: `int(x)`, `f64(y)`, `u8(z)`, etc.).
//     One legacy fallback guard: `t.type_expr_name_full(expr.typ)`
//     resolves to a name that `t.is_sum_type(name)` accepts. In that case
//     `transform_expr` may lower the cast into an explicit sum-type
//     initialisation (CallExpr to `<SumType>__from_<Variant>` / InitExpr),
//     which is a *different* expression shape. Both helpers are read-only
//     so the guard is cheap to evaluate. The existing
//     `fixture_sumtype_is_as` already exercises the fallback (it contains
//     `c := Shape(Circle{r: 2.0})`); new `fixture_cast_expr` (primitive
//     casts only) pins the fast path across all 5 harness rows — 76 → 81
//     transformer-diff tests.
//
//   Session 12 (2026-05-26): FieldInit expr direct-emit + harness fixture.
//     The FieldInit arm in `transform_expr_to_flat` direct-emits via a
//     recursive `transform_expr_to_flat` for the inner `value` plus the
//     existing `emit_field_init_by_id` builder helper (the same helper
//     ConstDecl uses for its aux_field_init child node — `add_expr(FieldInit)`
//     and `add_field_init(field)` produce bit-equal encodings so a single
//     emit helper covers both call sites). Skips the `ast.FieldInit` struct
//     allocation per occurrence — `transform_expr`'s FieldInit arm just
//     transforms `value` and copies `name` verbatim. FieldInit reaches the
//     expr dispatch when it appears as a standalone call arg in struct-
//     shorthand / named-arg syntax (`foo(name: value)`). New
//     `fixture_field_init` (struct + a `make(name: 'a', n: 1)` call) covers
//     the arm across all 5 harness rows — 81 → 86 transformer-diff tests.
//
//   Session 13 (2026-05-26): AsCastExpr expr direct-emit + harness fixture.
//     The AsCastExpr arm in `transform_expr_to_flat` direct-emits via the
//     leaf `out.emit_expr(expr.typ)` (type is NOT transformed by
//     `transform_expr` — copied verbatim) plus a recursive
//     `transform_expr_to_flat` for the inner expression, then assembles via
//     the new `emit_as_cast_expr_by_ids` builder helper. First port that
//     mutates Transformer state: to keep the `as` cast intact (a same-
//     expression smartcast would rewrite the operand into a direct sum
//     payload access and hide the original storage type from the backend),
//     the arm clones `smartcast_stack` + `smartcast_expr_counts`, drains
//     matching smartcast entries via a bounded `remove_smartcast_for_expr`
//     loop, transforms the inner expression with the drained state, then
//     restores the snapshot. Direct-emit mirrors the legacy prologue/restore
//     exactly so the snapshot semantics stay identical — the only thing
//     that changes is the inner recursion target (flat vs legacy). Skips
//     the `ast.AsCastExpr` struct allocation per occurrence. New
//     `fixture_as_cast_expr` (sum type Shape + `(s as Circle).r` / `(s as
//     Square).side` arms in a `pick(s Shape, k int) f64` fn) covers the
//     arm across all 5 harness rows — 86 → 91 transformer-diff tests.
//
//   Session 14 (2026-05-26): UnsafeExpr expr direct-emit + harness fixture.
//     The UnsafeExpr arm in `transform_expr_to_flat` has two paths matching
//     `transform_expr`'s arm:
//       1. `unsafe { nil }` normalises to a plain `nil` Ident (detected via
//          `t.is_unsafe_nil_expr(expr)`) — emitted as a leaf Ident through
//          `out.emit_expr(...)`. Identity in `transform_expr`'s else case.
//       2. otherwise transform `expr.stmts` via `transform_stmts` and emit
//          each result via `out.emit_stmt(...)`, then assemble the flat node
//          via the new `emit_unsafe_expr_by_ids` builder helper. Mirrors
//          `add_expr(UnsafeExpr)` encoding exactly (edges are body stmts in
//          order). Skips the `ast.UnsafeExpr` struct allocation per non-nil
//          occurrence.
//     The body stmt-list is still materialised because `transform_stmts`
//     returns one (the stmt-list expansion seam is the next big port
//     target). New `fixture_unsafe_expr` (a `mut p := unsafe { &int(0) }`
//     with a non-trivial body + plain `unsafe { nil }` for the
//     normalisation arm) covers both paths across all 5 harness rows —
//     91 → 96 transformer-diff tests.
//
//   Session 15 (2026-05-26): LockExpr expr direct-emit + harness fixture.
//     The LockExpr arm in `transform_expr_to_flat` rewrites
//     `lock x { body }` / `rlock x { body }` into a sequence of mutex
//     lock/unlock calls wrapped in an UnsafeExpr (compound expression).
//     `expand_lock_expr` produces `[lock_calls..., body..., unlock_calls...]`;
//     the legacy arm duplicates the last body stmt after the unlock calls so
//     that GCC compound-expression value semantics return the body's tail
//     value instead of `void`. Direct-emit mirrors the rewrite exactly —
//     same `expand_lock_expr` call, same duplicate-last fix-up, then emits
//     each stmt via `out.emit_stmt(...)` and assembles via the existing
//     `emit_unsafe_expr_by_ids` builder helper (the same helper UnsafeExpr
//     session 14 uses, since the legacy LockExpr arm produces an UnsafeExpr).
//     Crucial encoding detail: the legacy `ast.UnsafeExpr{stmts: stmts}` is
//     constructed with no `pos` field (defaults to zero), so direct-emit must
//     pass `token.Pos{}` (not `expr.pos`). First port to import `v2.token`
//     in `flat_write.v` — needed for the zero-pos literal. New
//     `fixture_lock_expr` (a `Counter` struct with `mut value int` + a
//     `bump(mut c Counter) int` that uses `lock c { c.value += 1; c.value }`)
//     covers the arm across all 5 harness rows — 96 → 101 transformer-diff
//     tests.
//
//   Session 16 (2026-05-26): OrExpr expr direct-emit + harness fixture.
//     The OrExpr arm in `transform_expr_to_flat` direct-emits the expression-
//     context or-block (the statement-level sites have dedicated handlers and
//     never reach here). `expand_single_or_expr` returns the data-access
//     expression that stands in for the or-block value and appends prefix
//     stmts (typed temp init, optional-state branch). When `prefix_stmts` is
//     non-empty, the legacy arm wraps everything in an `UnsafeExpr` (GCC
//     compound expression) — direct-emit mirrors that exactly via
//     `emit_unsafe_expr_by_ids` (same helper LockExpr session 15 uses),
//     passing `token.Pos{}` since the legacy wrapper has no explicit pos.
//     When empty, the result expression goes through `out.emit_expr(...)`
//     (leaf). Skips the `ast.UnsafeExpr` wrapper allocation per occurrence
//     in the compound-expression case. New `fixture_or_expr` (a fn
//     returning `pair(maybe(n) or { -1 }, 2)` — or-block nested in call
//     args) covers the arm across all 5 harness rows — 101 → 106
//     transformer-diff tests.
//
//   Session 17 (2026-05-26): IfGuardExpr expr direct-emit (degenerate arm).
//     IfGuardExpr only appears in normal usage as an IfExpr condition, where
//     `transform_if_expr` handles it (statement form via
//     `try_expand_if_guard_stmt`, expression form via the expr.v ~line 1371
//     site). The arm in `transform_expr_to_flat` is the degenerate standalone-
//     reach case: legacy `transform_expr` returns
//     `t.transform_expr(expr.stmt.rhs[0])` when `rhs` is non-empty, otherwise
//     returns `expr` unchanged. Direct-emit mirrors that — recursive
//     `transform_expr_to_flat` for the rhs[0] case, leaf `out.emit_expr(...)`
//     for the fallback. No new fixture: IfGuardExpr is unreachable in
//     standalone position in practice, so no diff-harness fixture exercises
//     it; the port is a completeness sweep that keeps the dispatch surface
//     coherent with the legacy `transform_expr` shape. All 106 existing
//     transformer-diff tests continue to pass.
//
//   Session 18 (2026-05-26): SelectorExpr deep helper port + fixture.
//     First "deep helper rewrite" port (per the planning conversation that
//     followed session 17). The full body of `transform_selector_expr`
//     (~130 lines in expr.v) is mirrored as `transform_selector_expr_to_flat`
//     in this file. Special-case branches that rewrite the selector into a
//     non-selector shape — typeof.name/idx (3 sub-branches: KeywordOperator,
//     CallExpr, CallOrCastExpr lhs), sumtype representation fields
//     (`_tag` / `_data` / `_*` chained under `_data`), smartcast match
//     (direct + field-access), `os.args` → `arguments()`, module-qualified
//     enum (`mod.Type.value` → `mod__Type__value` Ident or nested module
//     refs), and same-module enum (`Op.value` → `mod__Op__value` Ident) —
//     all build the legacy `ast.Expr` and emit via `out.emit_expr(...)`
//     (their results are Idents, BasicLiterals, or CallExprs that route
//     through `add_expr`'s normal encoding). Only the default `x.field`
//     path is direct-emit: recurse on lhs via `transform_expr_to_flat`,
//     emit rhs Ident via the leaf `out.emit_expr(...)`, and assemble via
//     the new `emit_selector_expr_by_ids` builder helper, skipping the
//     `ast.SelectorExpr` struct allocation per default-path occurrence.
//
//     Adds `import v2.types` to this file (needed for the `typ is types.Enum`
//     checks in the module-qualified / same-module enum branches). New
//     `fixture_selector_expr` exercises the default path with chained
//     selectors (`b.p.x`, `b.p.y`), non-Ident lhs (`arr[0].y` — IndexExpr),
//     and a selector-LHS assignment (`b.p.y = 42`) — 106 → 111 transformer-
//     diff tests.
//
//     Pattern note: this is the first port where the dispatch arm delegates
//     to a dedicated `transform_*_to_flat` helper instead of inlining the
//     logic in the match arm itself. Established because the legacy helper
//     has too many branches to inline (~130 lines of special-case
//     dispatch + lookup). Subsequent deep-helper ports (CallExpr, IfExpr,
//     InfixExpr, ...) will follow the same shape: one helper per legacy
//     `transform_*` with the same structure, special-case branches routed
//     through `emit_expr` for their non-default Expr results, default-path
//     direct-emit via new `emit_*_by_ids` builder helpers.
//
//   Session 19 (2026-05-26): IndexExpr deep helper port + fixture.
//     Second deep-helper rewrite, same shape as session 18. The body of
//     `transform_index_expr` (~140 lines in expr.v) is mirrored as
//     `transform_index_expr_to_flat`. Two branches produce non-IndexExpr
//     shapes and route through the legacy round-trip:
//     (a) Slice lowering (`expr.expr is ast.RangeExpr`) →
//         `transform_slice_index_expr` produces a CallExpr to
//         `array_slice` / `string_substr`.
//     (b) Map index on a non-eval backend → `map__get` lowering produces
//         an `ast.UnsafeExpr` wrapping prefix temps + cast + deref.
//     Map detection mirrors the legacy sequence exactly: `map_index_lhs_type`
//     → fallback to `lookup_var_type` for Ident lhs → `unwrap_map_type`.
//     All three lookups are immutable `&Transformer` calls so running them
//     up-front to decide dispatch is side-effect-free. Eval-backend map
//     case rebuilds an IndexExpr verbatim — falls through to direct-emit.
//
//     The gated path (`arr#[i]`), eval-backend map path, and default
//     `arr[i]` path all rebuild an IndexExpr with `lhs` and `expr`
//     recursively transformed and `is_gated` copied verbatim — direct-emit
//     via the new `emit_index_expr_by_ids` builder helper (`is_gated` flag
//     packed into the flags byte to match `add_expr(IndexExpr)` encoding
//     exactly). Skips the `ast.IndexExpr` struct allocation on the common
//     path.
//
//     New `fixture_index_expr` exercises all four paths in one fn: default
//     `arr[0] + arr[1]`, gated `arr#[0]`, map index `m['key']`, and slice
//     `arr[1..3].len` — 111 → 116 transformer-diff tests.
//
//   Session 20 (2026-05-26): ComptimeExpr deep helper port + fixture.
//     Third deep-helper rewrite, same shape as sessions 18/19. The body of
//     `transform_comptime_expr` (~50 lines in expr.v) is mirrored as
//     `transform_comptime_expr_to_flat`. Most branches lower the comptime
//     form into a non-ComptimeExpr shape — eval_comptime_if produces an
//     IfExpr result; `$res(...)` (both CallExpr and CallOrCastExpr lhs)
//     becomes a BasicLiteral `false`; `$embed_file(...)` (both forms)
//     becomes an InitExpr or chained CallExpr via
//     `transform_embed_file_comptime_expr`; `@VMODROOT`/`VMODROOT` Ident
//     becomes a StringLiteral via `vmodroot_string_literal`; the
//     `transform_embed_file_comptime_chain` rescue produces a non-comptime
//     shape — all six branches route through `out.emit_expr(...)`. Only
//     the default `ast.ComptimeExpr{expr: transform(inner), pos}` path is
//     direct-emit via the new `emit_comptime_expr_by_id` builder helper.
//     Skips the `ast.ComptimeExpr` struct allocation on the rare
//     default-path occurrence.
//
//     New `fixture_comptime_expr` exercises a `$if linux { return 1 }`
//     stmt body (the IfExpr branch — legacy fallback) — 116 → 121
//     transformer-diff tests.
//
//   Session 21 (2026-05-26): InitExpr deep helper port + fixture.
//     Fourth deep-helper rewrite, same shape as sessions 18-20. The body of
//     `transform_init_expr` (~220 lines in struct.v) is large and complex —
//     the per-field transformation involves sumtype wrapping,
//     ArrayInitExpr special-casing, expected-type resolution, and
//     missing-default fill-in via `add_missing_struct_field_defaults`. Only
//     one branch produces a non-InitExpr shape: the typed empty map
//     `map[K]V{}` lowers to a CallExpr to `new_map` (or `MapInitExpr` on the
//     eval backend) — that branch routes through `out.emit_expr(...)`. The
//     default path delegates the field work to legacy
//     `transform_init_expr` (its result is an `ast.InitExpr` with the same
//     `typ` and a fully-transformed fields list) and then direct-emits via
//     the new `emit_init_expr_by_ids` builder helper together with
//     `emit_field_init_by_id` per field. This skips the outer
//     `ast.InitExpr` wrapper allocation per occurrence; the per-field
//     `ast.FieldInit` wrappers still materialise on the default path (the
//     legacy function builds them). A later session can inline the
//     per-field loop directly to also skip those — that's a much bigger
//     port and not required to close this dispatch arm.
//
//     New `fixture_init_expr` exercises two struct types and a nested
//     struct literal with both fully-specified fields and a field with a
//     declared default (`tag string = "default"`) — the missing-default
//     fill-in path. 121 → 126 transformer-diff tests.
//
//   Session 22 (2026-05-26): ReturnStmt port + fixture.
//     First stmt-level port since session 3 (FnDecl). `transform_return_stmt`
//     (~110 lines in transformer.v) always returns an `ast.ReturnStmt`
//     (never lowers to a different shape). Its body does per-expression
//     sumtype wrapping (`should_wrap_return_sumtype`), enum-shorthand
//     resolution (`resolve_enum_shorthand`), smartcast handling (Ident
//     re-wrap, var-type sumtype shortcut), and native-backend pre-wrap
//     (`wrap_sumtype_value` for sumtype-returning fns). Too much logic to
//     inline for a single session. Wrap-only port: call legacy
//     `transform_return_stmt`, decompose the resulting ReturnStmt, emit
//     each transformed expr via `out.emit_expr(...)` (already transformed)
//     and assemble via the new `emit_return_stmt_by_ids` helper. Skips the
//     outer `ast.ReturnStmt` wrapper allocation per occurrence; the
//     `[]ast.Expr` list still materialises (legacy builds it).
//
//     New `fixture_return_stmt` covers three return shapes: multi-value
//     return (`return 1, 2`), sumtype-wrapping return
//     (`return Circle2{r: r}` in a `Shape2`-returning fn), and smartcast
//     return (`if s is Circle2 { return s }` — Ident re-wrap path).
//     126 → 131 transformer-diff tests.
//
//   Session 23 (2026-05-26): Ident expr direct-emit + fixture.
//     The Ident arm in `transform_expr_to_flat` direct-emits via the leaf
//     `out.emit_expr(ast.Expr(expr))` for the default path (Ident is
//     identity in `transform_expr`'s arm — same shape returned). Two
//     state-dependent rewrite branches fall back to legacy:
//       1. `@VMODROOT` → `vmodroot_string_literal(expr.pos)` produces a
//          StringLiteral (different shape).
//       2. `find_smartcast_for_expr(expr.name)` hit → smartcast lowering
//          via `apply_smartcast_direct_ctx` produces a direct sum payload
//          access (different shape).
//     Both gate checks use the immutable `&Transformer` receiver, safe to
//     probe upfront. Skips the `transform_expr` dispatch call per Ident
//     occurrence reached through a ported ancestor (ParenExpr, PrefixExpr,
//     ModifierExpr, CastExpr, AsCastExpr, FieldInit, LambdaExpr, IndexExpr,
//     SelectorExpr, ComptimeExpr, InitExpr default fields, etc.). No
//     struct allocation savings since the legacy default-path arm also
//     returns the input Ident verbatim — the win is dispatch-skip on the
//     hottest expression variant.
//
//     New `fixture_ident` covers file-scope Ident references nested inside
//     already-ported expr arms: `const neg_base = -base` (Ident inside
//     PrefixExpr arm), `const wrapped_base = (base)` (Ident inside
//     ParenExpr arm), `const inv_base = ~base` (Ident inside PrefixExpr
//     `~` arm), plus mut-param + multiple Ident references in a fn body
//     (Idents in InfixExpr operands — covered by the legacy InfixExpr
//     fallback path). 131 → 136 transformer-diff tests.
//
//     Pattern note: first port where the saving is dispatch-skip rather
//     than struct-allocation skip (since Ident's default `transform_expr`
//     arm is pure identity, no allocation). Future leaf-identity arms
//     (KeywordOperator default, etc.) follow the same pattern: gate
//     state-dependent special branches via immutable lookups, direct-emit
//     the identity path.
//
//   Session 24 (2026-05-26): KeywordOperator expr direct-emit + fixture.
//     KeywordOperator covers the comptime/macro-style call shapes
//     (`typeof(x)`, `sizeof(T)`, `isreftype(T)`, `dump(x)`, `likely(x)` /
//     `unlikely(x)`, `offsetof(T, f)`, `go ...` / `spawn ...`). The arm
//     in `transform_expr_to_flat` follows the session 23 (Ident) pattern:
//     a leaf-identity default path direct-emits via
//     `out.emit_expr(ast.Expr(expr))` and two gated state-dependent
//     special branches fall back to the legacy round-trip:
//       1. `key_typeof` with `exprs.len > 0` → `resolve_typeof_expr`
//          produces a StringLiteral when the name is non-empty.
//       2. `key_go` with `exprs.len > 0` → `lower_go_call(expr)` lowers
//          the spawn into a CallExpr to the generated goroutine wrapper.
//     All other ops (`sizeof`, `isreftype`, `dump`, `likely`, `unlikely`,
//     `offsetof`, `spawn`, also `typeof` when `resolve_typeof_expr`
//     returns empty) fall through to identity. Gate is the cheap
//     immutable `expr.op == ...` check — no side effects, no Transformer
//     state access. Same dispatch-skip win as session 23: skip the
//     `transform_expr` function call + match dispatch per occurrence
//     reached through a ported ancestor or a file-scope const value
//     (e.g. `const sz = sizeof(int)`).
//
//     New `fixture_keyword_operator` covers file-scope KeywordOperators
//     in ConstDecl values: `const sz_int = sizeof(int)`,
//     `const sz_bool = sizeof(bool)`, `const ref_int = isreftype(int)`
//     — all hit the default identity branch since the legacy arm only
//     specially handles `key_typeof` and `key_go`. 136 → 141
//     transformer-diff tests.
//
//   Session 25 (2026-05-26): GenericArgs expr direct-emit (completeness sweep).
//     GenericArgs covers the type-parameter shape `lhs[T]` (`typeof[int]`,
//     `MyGenericFn[string]`, ...). The `transform_expr` arm has three
//     branches: (1) `is_typeof_generic_args(expr)` → identity; (2)
//     `args.len == 1` + non-callable lhs type → `transform_index_expr`
//     lowers into an IndexExpr (different shape); (3) default →
//     `specialize_generic_callable_expr` lowers into an Ident or CallExpr
//     (different shape). The arm in `transform_expr_to_flat` follows the
//     session 23/24 pattern — gate the identity branch via the immutable
//     `is_typeof_generic_args` lookup (a `&Transformer` name check, no
//     state mutation) and direct-emit via leaf
//     `out.emit_expr(ast.Expr(expr))`; all other paths fall back to the
//     legacy round-trip.
//
//     Reachability is limited in practice: GenericArgs typically appears
//     as a CallExpr lhs (`typeof[int]()`, `myfn[T](x)`), and CallExpr is
//     unported — so the arm fires only through ported-ancestor recursion
//     (ParenExpr / SelectorExpr deep helper, etc.). Same shape as the
//     session 17 IfGuardExpr completeness sweep: no new fixture, keeps the
//     dispatch surface coherent with the legacy `transform_expr` shape.
//     All 141 existing transformer-diff tests continue to pass.
//
//   Session 26 (2026-05-26): StringInterLiteral deep helper port + fixture.
//     StringInterLiteral covers V's `'... ${x:d} ...'` interpolation syntax.
//     The legacy `transform_string_inter_literal` always returns a
//     StringInterLiteral (no branch produces a different shape) — it walks
//     each `ast.StringInter`, (a) optionally hoists a smartcasted payload via
//     `transform_expr` + `hoist_expr_to_temp` (mutates `t.pending_stmts`),
//     (b) wraps the inter expression via `transform_sprintf_arg` (type-aware
//     pointer-with-str / string-keeping logic), then (c) fills in the
//     resolved sprintf format via `resolve_sprintf_format`. The legacy body
//     allocates: one `ast.StringInterLiteral` wrapper, one `[]ast.StringInter`
//     list, and one `ast.StringInter` struct per inter.
//
//     `transform_string_inter_literal_to_flat` mirrors the per-inter loop
//     and emits each StringInter via `emit_string_inter_by_ids(format, width,
//     precision, expr_id, format_expr_id, resolved_fmt)` and the outer
//     literal via `emit_string_inter_literal_by_ids(kind, values, inter_ids,
//     token.Pos{})`. The smartcast/hoist mutations still happen identically
//     (we call the same legacy helpers); only the post-build allocations are
//     skipped. Note: legacy omits `pos` on the rebuilt literal (defaults to
//     `token.Pos{}`) — the port passes `token.Pos{}` explicitly for parity.
//     Same deep-port pattern as sessions 18 (SelectorExpr), 19 (IndexExpr),
//     20 (ComptimeExpr), 21 (InitExpr).
//
//     No new fixture in this session — existing fixtures already cover
//     StringInterLiteral nodes reached via ported ancestors (e.g.,
//     `'hi ${name}'` inside a ParenExpr / SelectorExpr / ConstDecl value).
//     All 141 transformer-diff tests continue to pass.
//
//   Session 27 (2026-05-26): ExprStmt port (stmt-level dispatch-skip).
//     First stmt-level identity-shape port. `transform_stmt`'s `ast.ExprStmt`
//     arm is identity-shape: it wraps the transformed inner expression in a
//     new `ast.ExprStmt`, with one state mutation — when `stmt.expr is
//     ast.IfExpr`, the arm flips `t.skip_if_value_lowering = true` around the
//     recursive `transform_expr` call so `transform_if_expr` knows the IfExpr
//     is in statement position (not value position) and skips temp-variable
//     lowering, then restores the prior flag.
//
//     The flat-write port mirrors the flag flip around a recursive
//     `transform_expr_to_flat` call (so any deep-helper-ported expr arm
//     reached inside also benefits from the flat path — Ident, SelectorExpr,
//     IndexExpr, InitExpr, ComptimeExpr, StringInterLiteral, ...), then
//     assembles the stmt_expr node via the new `emit_expr_stmt_by_id` helper.
//     Skips the `ast.ExprStmt` wrapper struct allocation and the legacy
//     `out.emit_stmt(t.transform_stmt(stmt))` round-trip's match dispatch
//     (both on `transform_stmt` and on `add_stmt`) on every expression
//     statement.
//
//     Reachability is excellent: ExprStmt is the most common statement form
//     after AssignStmt — every function body has them, every block has them,
//     every call as a top-level statement is an ExprStmt. No new fixture
//     this session — every existing fixture exercises ExprStmt via fn bodies
//     and asserts. All 141 transformer-diff tests continue to pass.
//
//     Pattern note: first port that recursively enters `transform_expr_to_flat`
//     from the stmt-level dispatch, propagating the flat-port savings into
//     all statement-position expressions (not just nested expressions inside
//     already-ported ConstDecl/GlobalDecl/ReturnStmt values).
//
//   Session 28 (2026-05-26): LabelStmt port (stmt-level recursive descent).
//     Second stmt-level identity-shape port after session 27 (ExprStmt).
//     `transform_stmt`'s LabelStmt arm always returns `LabelStmt{name:
//     stmt.name, stmt: transform_stmt(stmt.stmt)}` — `name` is verbatim,
//     single inner stmt recursively transformed. Direct-emit recurses via
//     `transform_stmt_to_flat` for the inner stmt (so any ported stmt arm
//     reached inside the label — ExprStmt, ReturnStmt, ForStmt, etc. — also
//     stays on the flat path) and assembles via the new
//     `emit_label_stmt_by_id(name, stmt_id)` helper. Mirrors
//     `add_stmt(LabelStmt)` encoding exactly (pos = `token.Pos{}`, interned
//     name, single edge to inner stmt). Skips the `ast.LabelStmt` wrapper
//     struct allocation and the `transform_stmt`/`add_stmt` match-dispatch
//     round-trip per occurrence.
//
//     Reachability is limited to source-level `label: stmt` syntax
//     (typically `outer:` before loops for labelled break/continue), but the
//     port is clean — single child stmt and a verbatim name. No new fixture
//     this session — existing fixtures don't exercise LabelStmt directly,
//     but the port keeps the stmt-dispatch surface coherent. All 141
//     transformer-diff tests continue to pass.
//
//     Pattern note: first stmt port that recursively enters
//     `transform_stmt_to_flat` itself (sibling of session 27's recursion into
//     `transform_expr_to_flat`), establishing the stmt-level recursive descent
//     pattern. Future stmt-level identity-shape ports (BlockStmt, DeferStmt,
//     ComptimeStmt $for branch) follow the same template — recurse via
//     `transform_stmt_to_flat` for child stmts, then emit via a new
//     `emit_*_by_ids` helper mirroring the matching `add_stmt` arm encoding.
//
//   Session 29 (2026-05-26): BlockStmt port (wrap-only stmt port).
//     Third stmt-level identity-shape port after sessions 27 (ExprStmt) and
//     28 (LabelStmt). `transform_stmt`'s BlockStmt arm always returns
//     `BlockStmt{stmts: transform_stmts(stmt.stmts)}` — identity-shape with
//     the body driver `transform_stmts` handling sibling-stmt smartcast
//     state snapshot/restore, pending-stmt hoisting, and one-to-many
//     expansion. Because the driver does extra inter-stmt work (and may
//     expand one input stmt into several outputs), we can't recurse via
//     `transform_stmt_to_flat` per-element without porting the driver
//     itself — that's a separate (bigger) refactor.
//
//     Wrap-only port: call legacy `transform_stmts(stmt.stmts)` to
//     materialise the transformed `[]ast.Stmt`, emit each via the legacy
//     `out.emit_stmt(...)` (the stmts are already transformed), and
//     assemble via the new `emit_block_stmt_by_ids` helper. Mirrors
//     `add_stmt(BlockStmt)` encoding exactly (pos = `token.Pos{}`, edges =
//     inner stmts in order). Skips the outer `ast.BlockStmt` wrapper struct
//     allocation per occurrence; the inner `[]ast.Stmt` from
//     `transform_stmts` still materialises (until the body driver is
//     ported).
//
//     Reachability is good — BlockStmt appears as a free-standing `{ ... }`
//     block in source. Most fn bodies don't directly use them (the FnDecl
//     arm calls `transform_stmts` itself), but `unsafe { ... }` and lambda
//     bodies in some shapes wrap their contents in BlockStmt. No new
//     fixture this session. All 141 transformer-diff tests continue to
//     pass.
//
//     Pattern note: first stmt port that takes the "wrap-only" shape
//     (sessions 9 FnLiteral, 14 UnsafeExpr, 22 ReturnStmt established this
//     pattern at the expr level). The body driver port (which would let
//     BlockStmt / DeferStmt / FnLiteral.stmts / UnsafeExpr.stmts all stream
//     directly into the builder instead of materialising `[]ast.Stmt`) is
//     the next significant target.
//
//   Session 55 (2026-05-27): InitExpr typed-empty-map direct-emit
//     refactor (seventh rewrite-site port — extends the post-routing-
//     pass mini-sweep to the InitExpr arm). `transform_init_expr_to_flat`
//     previously leaf-encoded the typed empty map branch
//     (`map[K]V{}`, `expr.fields.len == 0` + `MapType` typ) via
//     `out.emit_expr(t.transform_expr(ast.Expr(expr)))`. Session 55
//     direct-calls `transform_init_expr` (skipping the outer
//     `transform_expr` dispatch) and dispatches on result shape —
//     `ast.MapInitExpr` (eval backend) direct-emits via session 40's
//     `emit_map_init_expr_by_ids`; `ast.CallExpr` (non-eval, returns
//     a `new_map(sizeof(K), sizeof(V), &hash, &eq, &clone, &free)`
//     call) direct-emits via session 44's `emit_call_expr_by_ids`;
//     anything else falls through to leaf-emit.
//
//     Safety: `transform_init_expr` is the helper `transform_expr`'s
//     InitExpr arm calls. The MapInitExpr branch's children
//     (`typ`/`keys`/`vals`) are leaves built locally by the helper
//     (`MapInitExpr{typ: ast.Expr(ast.Type(expr.typ)), keys: [], vals:
//     [], pos}`); the CallExpr branch's args are also leaves built
//     locally (`KeywordOperator{op: .key_sizeof}` + Ident-wrapped
//     `&hash`/`&eq`/... fns) — no re-transform needed, leaf
//     `out.emit_expr` is correct.
//
//     Reachability: `map[K]V{}` is the canonical empty-map literal
//     and appears in every map-using V module. The dispatch-skip
//     win applies on every typed empty map occurrence; the
//     wrapper-allocation skip applies on every direct-emit path
//     (no longer build an `ast.InitExpr` wrapper before dispatch).
//     No new helper, no new fixture. All 168 transformer-diff tests
//     continue to pass.
//
//   Session 54 (2026-05-27): CastExpr sum-type lowering direct-emit
//     refactor (sixth rewrite-site port — extends the post-routing-
//     pass mini-sweep to the CastExpr arm). `transform_expr_to_flat`'s
//     CastExpr arm previously gated the sum-type lowering branch and
//     leaf-encoded via `out.emit_expr(t.transform_expr(expr))`,
//     re-entering the legacy dispatch only to reach
//     `wrap_sumtype_value`. Session 54 direct-calls
//     `wrap_sumtype_value(expr.expr, sumtype_name)` and leaf-emits
//     the wrapped result when it returns Some; when it returns none
//     (value already is the sum type, declared receiver matches,
//     generic-param guard, etc.), falls through to the existing
//     default direct-emit path (CastExpr rebuild via
//     `emit_cast_expr_by_ids`).
//
//     Safety: `wrap_sumtype_value` is the same helper
//     `transform_expr`'s CastExpr arm calls; calling it directly
//     skips one dispatch hop. The wrapped result (CastExpr/InitExpr/
//     CallExpr depending on variant shape — see `build_sumtype_init`)
//     is leaf-encoded via `out.emit_expr`: the result is already
//     fully-formed by the helper (it transforms the inner value
//     before wrapping at types.v:2145), so re-entering
//     `transform_expr_to_flat` would re-apply transforms — same
//     "do not route through dispatch" hazard as sessions 47-51.
//
//     Reachability: sum-type casts (`MySum(variant_value)`) appear
//     in V code wherever a sum-type variant is materialised from an
//     untyped expression — common in pattern-match arms, ast
//     construction, etc. The dispatch-skip win applies on every
//     sum-type cast occurrence. No new helper, no new fixture. All
//     168 transformer-diff tests continue to pass.
//
//   Session 53 (2026-05-27): GenericArgs branch-2/3 direct-emit
//     refactor (fifth rewrite-site port — extends the
//     post-routing-pass mini-sweep to the GenericArgs arm).
//     `transform_expr_to_flat`'s GenericArgs arm previously gated
//     the identity branch (typeof[T]) and leaf-encoded the other two
//     branches via `out.emit_expr(t.transform_expr(expr))`. Session
//     53 direct-handles each branch: branch 2 (single-arg,
//     non-callable lhs) cross-arm routes to
//     `transform_index_expr_to_flat` (same template as
//     GenericArgOrIndexExpr in session 33), branch 3 direct-calls
//     `specialize_generic_callable_expr` (returns Ident or
//     SelectorExpr — both identity in `transform_expr`) and
//     leaf-emits the result.
//
//     Safety: `is_typeof_generic_args` / `get_expr_type` /
//     `is_callable_type` are immutable lookups. The IndexExpr
//     re-entry mirrors the legacy disambiguation exactly. The
//     branch-3 result (Ident/SelectorExpr) is leaf-encoded — both
//     shapes are identity in `transform_expr`, so re-entering
//     `transform_expr_to_flat` would only add a dispatch hop with
//     no rewrite.
//
//     Reachability is limited (GenericArgs typically appears as a
//     CallExpr lhs which is unported — the arm fires through
//     ported-ancestor recursion: ParenExpr, SelectorExpr deep
//     helper, etc.), but the port removes the last legacy round-trip
//     from the arm. No new helper, no new fixture. All 168
//     transformer-diff tests continue to pass.
//
//   Session 52 (2026-05-27): Ident @VMODROOT / smartcast branch
//     direct-emit refactor (fourth rewrite-site port — extends the
//     post-routing-pass mini-sweep to the Ident arm).
//     `transform_expr_to_flat`'s Ident arm previously leaf-encoded
//     both rewrite branches via `out.emit_expr(t.transform_expr(expr))`,
//     re-entering the legacy dispatch only to reach the two distinct
//     rewrites. Session 52 direct-calls each helper instead:
//     `@VMODROOT` → `vmodroot_string_literal(expr.pos)` (immutable,
//     returns StringLiteral) → leaf-emit; smartcast hit →
//     `apply_smartcast_direct_ctx(expr, ctx)` (the same helper
//     `transform_expr` would call) → leaf-emit.
//
//     Safety: `vmodroot_string_literal` is a pure value-resolution
//     lookup (no expression rewriting). `apply_smartcast_direct_ctx`
//     returns an already-fully-formed expression (selector chain into
//     sum payload, or smartcast-rewritten expr) — leaf-encoding via
//     `out.emit_expr` is the safe escape hatch (routing through
//     `transform_expr_to_flat` would re-enter the helper-result's arm
//     and could re-apply smartcast rewrites).
//
//     Reachability: Ident is by far the most-frequent expr variant
//     in V code (every variable reference is an Ident). The default
//     identity path was already direct-emit since session 23; this
//     session removes the last legacy-round-trip path from the arm.
//     `@VMODROOT` is rare (build-config code only); smartcast hits
//     are common inside `if x is Type { ... }` / `match`-narrowed
//     blocks. No new helper, no new fixture. All 168 transformer-diff
//     tests continue to pass.
//
//   Session 51 (2026-05-27): KeywordOperator typeof/go branch split
//     direct-emit refactor (third rewrite-site port — extends the
//     post-routing-pass mini-sweep to the KeywordOperator arm).
//     `transform_expr_to_flat`'s KeywordOperator arm previously gated
//     both rewrite branches behind a single `(typeof || go) && len > 0`
//     check and leaf-encoded via `out.emit_expr(t.transform_expr(expr))`,
//     re-entering the legacy dispatch only to route to the two distinct
//     rewrites. Session 51 splits the branches: the typeof branch
//     direct-calls `resolve_typeof_expr` (an immutable `&Transformer`
//     lookup) and direct-emits the resulting StringLiteral via leaf
//     `out.emit_expr` (StringLiteral is identity in `transform_expr`);
//     the go branch direct-calls `lower_go_call(expr)` and dispatches
//     on the result shape — `ast.CallExpr` direct-emits via session
//     44's `emit_call_expr_by_ids`, the `KeywordOperator` identity
//     fallback (unresolved fn_name / non-Call inner) falls through to
//     leaf `out.emit_expr(result)`.
//
//     Safety: `resolve_typeof_expr` is a pure name-resolution lookup
//     (no mutation, no expression rewriting). `lower_go_call`
//     internally calls `t.transform_expr` on each arg and on the
//     selector lhs (for method calls) — args/receiver in the returned
//     CallExpr are fully-transformed, so direct-emit encodes them via
//     leaf `out.emit_expr` per arg. Routing through
//     `transform_expr_to_flat`'s CallExpr arm would re-run
//     `transform_call_expr` (fn.v:112 "Do NOT route" hazard) —
//     skipped, same as sessions 47/48/49/50.
//
//     Reachability: `typeof(expr).name` patterns are common in V
//     comptime code (introspection, error messages, generic dispatch
//     hints). `go ...` / `spawn ...` are less common but appear in
//     concurrent code. The dispatch-skip win applies on every
//     KeywordOperator occurrence with these ops; the StringLiteral
//     direct-emit (no wrapper allocation) is a small but pure win on
//     typeof hits. No new helper, no new fixture. All 168
//     transformer-diff tests continue to pass.
//
//   Session 50 (2026-05-27): IndexExpr map-index-lowering direct-emit
//     refactor (second rewrite-site port — completes the IndexExpr
//     non-identity-shape routing sweep started in session 49).
//     `transform_index_expr_to_flat`'s map-index branch (non-eval
//     backend, lhs unwraps to a Map type) was a leaf-encode shape:
//     `out.emit_expr(t.transform_expr(ast.Expr(expr)))` re-entered
//     `transform_expr`'s IndexExpr arm → `transform_index_expr` →
//     produced an UnsafeExpr containing temp-assign stmts plus a
//     deref-of-cast-of-`map__get` call. Session 50 refactor:
//     direct-call `transform_index_expr` (skipping the outer
//     `transform_expr` match dispatch) and direct-emit the resulting
//     UnsafeExpr via `emit_unsafe_expr_by_ids` (already present in
//     `vlib/v2/ast/flat.v`; no new helper needed).
//
//     Safety: `transform_index_expr` returns an `ast.UnsafeExpr` with
//     fully-transformed stmts (the helper calls `t.transform_expr` on
//     every child expr internally — lhs, key, default-zero, etc.).
//     Direct-emit encodes each stmt via leaf `out.emit_stmt` — no
//     re-transform. Routing through `transform_stmt_to_flat` per stmt
//     would re-run the legacy dispatch (some arms call into helpers
//     that re-transform); leaf-encoding is the safe escape hatch.
//     The detection chain (`map_index_lhs_type` / `unwrap_map_type`
//     / `is_eval_backend`) stays upfront so we only direct-call
//     `transform_index_expr` when we already know it will produce the
//     UnsafeExpr lowering — `if result is ast.UnsafeExpr` is a
//     defensive type-narrow that catches an upstream shape drift.
//
//     Reachability: map index reads `m[key]` on non-eval backends are
//     common in compiler-internal code (registries, lookup tables,
//     name resolution). The dispatch-skip win applies on every
//     map-index occurrence on the non-eval path. Same routing
//     template as sessions 47/48/49. No new helper, no new fixture.
//     All 168 transformer-diff tests continue to pass.
//
//   Session 49 (2026-05-27): IndexExpr slice-lowering direct-emit
//     refactor (first rewrite-site port — sibling of routing-pass
//     sessions 46-48). `transform_index_expr_to_flat`'s slice branch
//     (`expr.expr is ast.RangeExpr`) was a leaf-encode shape: it called
//     `out.emit_expr(t.transform_expr(ast.Expr(expr)))` which re-entered
//     `transform_expr`'s IndexExpr arm → `transform_index_expr` →
//     `transform_slice_index_expr`, materialising a CallExpr to
//     `string__substr` / `array__slice` / `array__slice_ni`. With session
//     44's `emit_call_expr_by_ids` in place, the slice branch can
//     direct-call `transform_slice_index_expr` (skipping the dispatch +
//     re-entry round-trip) and direct-emit the resulting CallExpr.
//
//     Safety: `transform_slice_index_expr` returns an `ast.CallExpr`
//     with fully-transformed lhs/args (it calls `t.transform_expr` on
//     range start/end internally and on the lhs upstream of the
//     direct-call). Direct-emit encodes via leaf `out.emit_expr` per
//     arg — no re-transform. Routing through `transform_expr_to_flat`'s
//     CallExpr arm would re-run `transform_call_expr` (the fn.v:112
//     "Do NOT route" hazard) — skipped. Same template as sessions 47
//     (CallOrCastExpr) and 48 (SqlExpr lowered).
//
//     Reachability is good — slice syntax `a[i..j]`, `s[..n]`, `arr[k..]`
//     is common in V code. The map-index lowering branch (lower in the
//     same function, returns UnsafeExpr) stays leaf-encoded for now;
//     porting it would need a new `emit_unsafe_expr_by_id` helper. This
//     is the first rewrite-site port after the routing-pass mini-sweep
//     finished — every dispatch arm in `transform_expr_to_flat` either
//     direct-emits or routes through a helper that does. No new helper,
//     no new fixture. All 168 transformer-diff tests continue to pass.
//
//   Session 48 (2026-05-27): SqlExpr lowered-CallExpr direct-emit
//     refactor (routing pass — completes the routing-pass mini-sweep).
//     Session 36 ported SqlExpr with two outcome shapes:
//     identity-SqlExpr direct-emits via `emit_sql_expr_by_id` (added in
//     same session); lowered branch (is_create + table lookup hit) goes
//     through `lower_sql_create_expr` → `t.transform_expr(call)` on a
//     synthesized CallExpr, leaf-encoded via `out.emit_expr(result)`.
//     With session 44's `emit_call_expr_by_ids` in place, the lowered
//     branch's CallExpr result can be direct-emitted via the helper —
//     same template as session 47.
//
//     Safety: `lower_sql_create_expr`'s `t.transform_expr(call)` enters
//     the CallExpr arm of `transform_expr` which calls
//     `transform_call_expr` once; its result has fully-transformed args.
//     Direct-emit here encodes lhs/args via leaf `out.emit_expr` — no
//     re-transform. Routing through `transform_expr_to_flat` would
//     re-run `transform_call_expr` (the fn.v:112 "Do NOT route" hazard
//     again) — skipped.
//
//     Reachability is limited (sql ... { create ... } blocks with a
//     looked-up table struct), but the routing keeps the SqlExpr arm
//     coherent with the CallOrCastExpr arm (session 47) and finishes
//     the routing-pass mini-sweep that sessions 45-48 ran: every
//     "always-lowers via helper" arm whose downstream shape has a
//     direct-emit helper now uses it (MatchExpr → IfExpr in session 46,
//     CallOrCastExpr → CallExpr in session 47, SqlExpr lowered →
//     CallExpr in session 48). No new helper, no new fixture. All 168
//     transformer-diff tests continue to pass.
//
//   Session 47 (2026-05-27): CallOrCastExpr direct-emit refactor
//     (routing pass — sibling of session 46's MatchExpr refactor).
//     Session 42 ported CallOrCastExpr to call `transform_call_or_cast_expr`
//     once and leaf-encode the result via `out.emit_expr(...)`. Session
//     44 landed `emit_call_expr_by_ids`, unlocking the downstream win:
//     the most common shape `transform_call_or_cast_expr` lowers to is
//     `ast.CallExpr` (every method-resolved call, generic-math inline,
//     filter/map expansion, flag-enum method, smartcast method, all
//     module-prefixed calls, and the unresolved fallback). The CallExpr
//     branch can now be direct-emitted via the helper instead of
//     leaf-encoded.
//
//     Safety: every CallExpr return path in `transform_call_or_cast_expr`
//     populates `lhs` and `args` from already-transformed values
//     (`transform_call_arg_with_sumtype_check`, `transform_expr` calls
//     upstream of each return). Direct-emit encodes lhs/args via leaf
//     `out.emit_expr` — no re-transform. Going through
//     `transform_expr_to_flat`'s CallExpr arm (which would re-run
//     `transform_call_expr` on the already-lowered result) IS unsafe
//     and explicitly flagged by an "// Do NOT route through
//     transform_call_expr because it would..." comment at fn.v:112; the
//     routing skips the dispatch arm and direct-emits instead.
//
//     The non-CallExpr shapes (CastExpr, BasicLiteral '0', and rarer
//     `lower_call_or_cast_expr` results) still route through leaf
//     `out.emit_expr(result)`. Reachability of the direct-emit win is
//     high — CallExpr is the dominant downstream shape for the
//     parser's ambiguous `T(x)`/`f(x)` form. No new helper, no new
//     fixture. All 168 transformer-diff tests continue to pass.
//
//   Session 46 (2026-05-27): MatchExpr direct-emit refactor (routing
//     pass — sibling of session 45's IfExpr port).
//     Session 35 ported MatchExpr to call `transform_match_expr` once
//     and leaf-encode the result via `out.emit_expr(...)`. Session 45
//     landed `emit_if_expr_by_ids` for the IfExpr arm, unlocking
//     MatchExpr's downstream win: `transform_match_expr` always lowers
//     to an `ast.IfExpr` (via `lower_match_expr_to_if`), so the IfExpr
//     can be direct-emitted via the new helper instead of routed
//     through leaf `out.emit_expr` (which still allocates one extra
//     wrapper layer inside `add_expr(IfExpr)`'s `push_expr` /
//     `push_stmt` walk).
//
//     Safety: `transform_match_expr` runs `transform_match_branch_stmts`
//     per branch and `transform_expr(expr.expr)` upstream of
//     `build_match_branch_cond`, so the IfExpr's `cond` / `stmts` /
//     `else_expr` are already transformed. Direct-emit encodes them via
//     leaf `out.emit_expr` / `out.emit_stmt` (no re-transform). Going
//     through `transform_expr_to_flat`'s IfExpr arm would re-run
//     `transform_if_expr` on the already-transformed result — would
//     double-transform body stmts, which is why this routing skips the
//     IfExpr dispatch arm entirely.
//
//     Edge case: `lower_match_expr_to_if` returns `ast.empty_expr` when
//     `branches.len == 0` (no branches → no if). The `is ast.IfExpr`
//     guard keeps that path on the leaf `out.emit_expr(result)` exit.
//
//     Pattern note: routing-pass template — when an "always-lowers via
//     helper" arm produces a result shape that now has a direct-emit
//     helper, switch from leaf-encoding to direct-emit (without
//     re-routing through the dispatch arm, which would double-
//     transform). Same trick applies to CallOrCastExpr (session 42 →
//     `emit_call_expr_by_ids`) and SqlExpr's lowered-CallExpr branch
//     (session 36) — both follow-up sessions. No new helper, no new
//     fixture. All 168 transformer-diff tests continue to pass.
//
//   Session 45 (2026-05-27): IfExpr port (always-lowers via helper, two
//     outcome shapes) — completes phase 4 expression-arm port sweep.
//     `transform_expr`'s IfExpr arm is a thin wrapper around
//     `transform_if_expr` (expr.v:1268), the largest control-flow helper
//     in the transformer. Many outcome shapes:
//       - &&-chain normalisation with embedded `is` checks → recursive
//         `transform_if_expr(outer_if / inner_if)` rebuild (IfExpr).
//       - smartcast hoisting (`if x is T && rest { ... }`) → IfExpr
//         with smartcast applied to the nested then-branch.
//       - sumtype tag/_type_id rewrite for `is`/`!is` cond → IfExpr.
//       - matched smartcast / type-narrowed branches → IfExpr with
//         hoisted decl-assigns + transformed stmts/else.
//       - direct option/result unwrap (`if x is none`) → IfExpr or
//         UnsafeExpr lowering with deref + tag check.
//       - default → `IfExpr{cond: transform(cond), stmts:
//         transform_stmts(stmts), else_expr: transform(else), pos}`
//         identity-shape rebuild.
//       - value-position lowering: `if_expr_is_value(transformed_if)`
//         AND not skipped → `lower_if_expr_value(transformed_if)` hoists
//         a temp decl-assign per branch, returning an Ident (NOT an
//         IfExpr).
//
//     Direct-emit calls `transform_if_expr` once and dispatches on result
//     type. Identity branch → encode `cond` + `else_expr` via leaf
//     `out.emit_expr`, each `stmt` via leaf `out.emit_stmt` (helper
//     already transformed body via `transform_stmts` —
//     `transform_stmt_to_flat` would double-transform and break parity
//     for hoisted smartcast / pending_stmts ordering) + assemble via the
//     new `emit_if_expr_by_ids(cond_id, else_id, stmt_ids, pos)` helper.
//     Lowered branch → route through leaf `out.emit_expr(result)`.
//
//     Pattern note: extends "always-lowers via helper, two outcome
//     shapes" (sessions 36 SqlExpr, 40 MapInitExpr, 41 ArrayInitExpr,
//     43 InfixExpr, 44 CallExpr). Reachability is high — `if` is one of
//     the two main control-flow constructs in V; every `if cond { ... }
//     else { ... }` passes through this arm. The wrapper-allocation skip
//     applies on the identity branch (statement-position ifs and ifs
//     without value lowering — most of them in compiler-style code).
//
//     Completes phase 4's expression-arm port sweep — with this landing,
//     every non-leaf arm in `transform_expr_to_flat` has a dedicated
//     port. The `else { return out.emit_expr(t.transform_expr(expr)) }`
//     fallback at the bottom of the dispatch is dead code (next
//     follow-up: remove it + the `KeywordOperator` / `GenericArgs`
//     intra-arm fallbacks that still route through the legacy round-trip
//     for state-dependent rewrites). MatchExpr's arm (session 35) can
//     now chain through `transform_expr_to_flat` to pick up IfExpr's
//     direct-emit win on the lowered result, instead of routing through
//     leaf `out.emit_expr` — another follow-up routing pass.
//
//     New pub helper: `emit_if_expr_by_ids(cond_id, else_id, stmt_ids,
//     pos)` in `vlib/v2/ast/flat.v` mirrors `add_expr(IfExpr)` encoding
//     (`emit_simple(.expr_if, pos, [cond, else, stmts...])`). No new
//     fixture this session. All 168 transformer-diff tests continue to
//     pass.
//
//   Session 44 (2026-05-27): CallExpr port (always-lowers via helper,
//     two outcome shapes).
//     `transform_expr`'s CallExpr arm is a thin wrapper around
//     `transform_call_expr` (fn.v:1881) — by far the largest single
//     helper in the transformer. It lowers many call shapes into
//     non-CallExpr results: generic-math inline, embed_file lowering,
//     $d resolution, .filter()/.map()/.sort() expansion, flag-enum
//     methods, array contains/index/last_index, smartcast hoisting,
//     BasicLiteral '0' elision (for elided fns), CastExpr for bare-type
//     calls, IfExpr / InitExpr for some intrinsics, etc. The default
//     tail (fn.v:2603-2610) is identity-shape:
//       `CallExpr{lhs: transform(lhs),
//                 args: [transform_call_arg_with_sumtype_check(...)],
//                 pos}` —
//     wrapped by `lower_missing_call_args` (fills omitted optional
//     args) and `lower_variadic_args` (collapses trailing args into a
//     `[]T` ArrayInitExpr).
//
//     Direct-emit calls `transform_call_expr` once and dispatches on
//     result type. Identity branch → encode `lhs` + each `arg` via leaf
//     `out.emit_expr` (helper already transformed — re-routing through
//     `transform_expr_to_flat` would double-transform and break parity
//     for hoisted smartcast temps + variadic lowering) + assemble via
//     the new `emit_call_expr_by_ids(lhs_id, arg_ids, pos)` helper.
//     Lowered branch → route through leaf `out.emit_expr(result)` so
//     the many lowering branches stay single-sourced.
//
//     Pattern note: extends "always-lowers via helper, two outcome
//     shapes" (sessions 36 SqlExpr, 40 MapInitExpr, 41 ArrayInitExpr,
//     43 InfixExpr). CallExpr is the highest-traffic arm of any port in
//     phase 4 — every function call, method call, intrinsic, and
//     lowered-array/map operation passes through it. The dispatch-skip
//     win applies on every occurrence; the wrapper-allocation skip
//     applies on the default-path identity branch (the most common
//     case for ordinary user-code calls).
//
//     With CallExpr ported, the CallOrCastExpr arm (session 42) and
//     the cascade of lowering helpers throughout the transformer that
//     produce CallExpr results could be retargeted to chain through
//     `transform_expr_to_flat` instead of leaf `out.emit_expr` — but
//     that's a follow-up routing pass, not part of this session. No
//     new fixture this session. All 168 transformer-diff tests continue
//     to pass.
//
//     New pub helper: `emit_call_expr_by_ids(lhs_id, arg_ids, pos)` in
//     `vlib/v2/ast/flat.v` mirrors `add_expr(CallExpr)` encoding
//     (emit_simple `.expr_call` with edges = [lhs, args...]).
//
//   Session 43 (2026-05-27): InfixExpr port (always-lowers via helper,
//     two outcome shapes).
//     `transform_expr`'s InfixExpr arm is a thin wrapper around
//     `transform_infix_expr` (expr.v:2124), which has many outcome shapes
//     that collapse into "identity InfixExpr" vs "lowered different
//     shape":
//       - `&&`-chain smartcast: `join_and_terms(terms)` rebuilds an
//         InfixExpr chain — identity shape.
//       - sum-type tag comparison (`is`/`!is`/`==`/`!=` against a
//         variant) → `make_infix_expr_at(...)` over `_tag` / `_type_id`
//         — identity shape (InfixExpr).
//       - string literal concat folding → StringLiteral.
//       - string + string → CallExpr to `string__plus`.
//       - operator overload → CallExpr to the user-defined `<op>`
//         method.
//       - alias arithmetic, smartcast-of-lhs/rhs, fixed-array concat,
//         etc. → various CallExpr / IndexExpr / etc.
//       - default → `InfixExpr{op, lhs: transform(lhs), rhs:
//         transform(rhs), pos}` — identity shape.
//
//     Direct-emit calls `transform_infix_expr` once and dispatches on
//     result type. Identity branches → encode lhs/rhs via leaf
//     `out.emit_expr` (helper already transformed — `transform_expr_to_flat`
//     would double-transform) + assemble via the new
//     `emit_infix_expr_by_ids(op, lhs_id, rhs_id, pos)` helper. Lowered
//     branches → route through leaf `out.emit_expr(result)`.
//
//     Pattern note: extends "always-lowers via helper, two outcome
//     shapes" (sessions 36 SqlExpr, 40 MapInitExpr, 41 ArrayInitExpr).
//     The identity branch is reached by the vast majority of arithmetic
//     / boolean / comparison infix operations in V code — every `a + b`,
//     `i < n`, `flag && x`, `xs == ys`, ... — so the direct-emit win is
//     broad.
//
//     Reachability is extremely high — infix is the workhorse of every
//     function body. The dispatch-skip win applies on every occurrence;
//     the wrapper-allocation skip applies on every identity-branch
//     occurrence. No new fixture this session. All 168 transformer-diff
//     tests continue to pass.
//
//     New pub helper: `emit_infix_expr_by_ids(op, lhs_id, rhs_id, pos)`
//     in `vlib/v2/ast/flat.v` mirrors `add_expr(InfixExpr)` encoding
//     (aux1=-1, aux2=-1, meta=u16(op), edges = [lhs, rhs]).
//
//   Session 42 (2026-05-27): CallOrCastExpr port (always-lowers via helper,
//     never-identity).
//     `transform_expr`'s CallOrCastExpr arm is a thin wrapper around
//     `transform_call_or_cast_expr` (fn.v:3955), which virtually always
//     lowers a CallOrCastExpr (the parser's ambiguity node for `Type(arg)`
//     vs `func(arg)`) into a different shape: CallExpr (most paths —
//     generic-math inline, filter/map expansion, sort lambda, flag-enum
//     methods, array contains/index, smartcast methods, all module-
//     prefixed and method-resolved calls, the "unresolved fallback"
//     CallExpr at the very end), CastExpr (when lhs is a known type
//     expression), BasicLiteral '0' (elided fn or `enum.zero()` for flag
//     enums), or whatever shape `lower_call_or_cast_expr` /
//     `t.transform_expr(t.transform_call_or_cast_expr(...))` recursion
//     produces.
//
//     There is no identity-shape rebuild — every code path produces a
//     non-CallOrCastExpr. The direct-emit win is purely the dispatch
//     skip on the outer `transform_expr` arm; the lowered result still
//     routes through leaf `out.emit_expr(...)` (no re-transform —
//     `transform_call_or_cast_expr` already transformed receivers and
//     args; double-transforming would break parity for smartcast
//     hoisting and similar mutation).
//
//     Pattern note: sibling of AssocExpr (session 34), MatchExpr (35) —
//     "always-lowers via single helper to a DIFFERENT shape".
//     Distinct from SqlExpr / MapInitExpr / ArrayInitExpr (sessions
//     36/40/41) which have an identity branch worth direct-emitting.
//     When CallExpr and InfixExpr get their own flat helpers (sessions
//     43-44), this arm could switch to
//     `t.transform_expr_to_flat(result, mut out)` to chain into those
//     helpers' direct-emit paths — but today they still hit the `else`
//     fallback, so routing through them adds no win.
//
//     Reachability: CallOrCastExpr is the parser's ambiguous
//     `T(x)`/`f(x)` form, common for single-arg calls and casts. By
//     transformer-exit time every CallOrCastExpr becomes one of the
//     shapes above, so the dispatch-skip win applies broadly. No new
//     helper, no new fixture. All 168 transformer-diff tests continue to
//     pass.
//
//   Session 41 (2026-05-27): ArrayInitExpr port (always-lowers via helper,
//     two outcome shapes).
//     `transform_expr`'s ArrayInitExpr arm is a thin wrapper around
//     `transform_array_init_expr` (struct.v:291), which has many outcome
//     shapes that collapse into "identity ArrayInitExpr" vs "lowered
//     CallExpr/UnsafeExpr":
//       (a) invalid data → identity (`return ast.Expr(expr)`).
//       (b) fixed-size array (`[1, 2, 3]!`, `[5]int{}`) → identity-shape
//           rebuild with transformed `exprs`/`init`/`cap`/`len`.
//       (c) eval backend → identity-shape rebuild with transformed
//           typ/init/cap/len/update_expr fields.
//       (d) spread `[...base, e1, e2]` → CallExpr to
//           `new_array_from_array_and_c_array(...)`.
//       (e) empty dynamic array `[]int{}` →
//           `__new_array_with_default_noscan(len, cap, sizeof(elem),
//           init)` CallExpr; or a ForStmt expansion when `init`
//           references `index`.
//       (f) keyed dynamic array `[1, 2, 3]` → `new_array_from_c_array(...)`
//           CallExpr.
//
//     Direct-emit calls `transform_array_init_expr` once and dispatches
//     on result type. Identity branches (a)/(b)/(c) all return an
//     `ast.ArrayInitExpr` — direct-emit via the new
//     `emit_array_init_expr_by_ids` helper, skipping the wrapper
//     allocation. Children are encoded via leaf `out.emit_expr` (the
//     helper already transformed them — `transform_expr_to_flat` would
//     double-transform). Lowering branches (d)/(e)/(f) return a
//     non-ArrayInitExpr shape — route through leaf
//     `out.emit_expr(result)` so the lowering logic stays
//     single-sourced.
//
//     Pattern note: extends "always-lowers via helper, two outcome
//     shapes" (sessions 36 SqlExpr, 40 MapInitExpr). The two-shape
//     template handles multiple identity branches uniformly via
//     post-helper type dispatch. Unlike MapInitExpr (only eval backend
//     keeps the identity shape), ArrayInitExpr keeps identity on every
//     backend for fixed-size literals — so the direct-emit win reaches
//     every backend for that branch, not just eval.
//
//     Reachability is very high — array literals (`[]`, `[1, 2, 3]`,
//     `[]int{}`, `[5]int{init: -1}`, `[1, 2, 3]!`) are ubiquitous in V
//     code. Most call/return-arg array literals on non-eval backends hit
//     branches (d)/(e)/(f), but fixed-size array literals (common in
//     lookup tables and configuration) hit (b) identity-rebuild on every
//     backend. No new fixture this session. All 168 transformer-diff
//     tests continue to pass.
//
//     New pub helper: `emit_array_init_expr_by_ids(typ_id, init_id,
//     cap_id, len_id, update_expr_id, expr_ids, pos)` in
//     `vlib/v2/ast/flat.v` mirrors `add_expr(ArrayInitExpr)` encoding
//     (`emit_simple(.expr_array_init, pos, [typ, init, cap, len,
//     update_expr, exprs...])`).
//
//   Session 40 (2026-05-27): MapInitExpr port (always-lowers via helper,
//     two outcome shapes).
//     `transform_expr`'s MapInitExpr arm is a thin wrapper around
//     `transform_map_init_expr` (struct.v:1010), which has two outcome
//     shapes:
//       (a) eval backend → identity-shape rebuild
//           `MapInitExpr{typ: transform(typ), keys: [transform(k)...],
//            vals: [transform(v)...], pos}`. Each child is already
//           transformed inside the helper.
//       (b) non-eval backend → lowers to a CallExpr:
//           `new_map(sizeof(K), sizeof(V), &hash, &eq, &clone, &free)` for
//           empty literals, `new_map_init(...)` for keyed literals.
//
//     Direct-emit calls `transform_map_init_expr` once and dispatches on
//     result type: `is ast.MapInitExpr` → encode typ/keys/vals via leaf
//     `out.emit_expr` (pure `add_expr` — `transform_expr_to_flat` would
//     double-transform) + assemble via the new
//     `emit_map_init_expr_by_ids(typ_id, key_ids, val_ids, pos)` helper.
//     Otherwise (lowered CallExpr) → route through leaf
//     `out.emit_expr(result)`.
//
//     Pattern note: extends the "always-lowers via helper, two outcome
//     shapes" template established by SqlExpr (session 36) and AssignStmt
//     (37). Identity branch picks up the direct-emit win (skips the
//     `ast.MapInitExpr` wrapper struct allocation + the `transform_expr`
//     match dispatch); lowered branch single-sources the `new_map`
//     construction logic in the legacy helper.
//
//     Reachability: map literals (`{}`, `{'a': 1}`, `map[string]int{}`)
//     are common across the compiler (registries, lookup tables, codegen
//     state). Most v2 backend builds use the non-eval path, so the
//     identity-branch direct-emit win applies only on the eval backend;
//     the dispatch-skip win applies on every backend. No new fixture this
//     session — existing fixtures exercise map literals via for-in maps,
//     tag tables, etc. All 168 transformer-diff tests continue to pass.
//
//     New pub helper: `emit_map_init_expr_by_ids(typ_id, key_ids, val_ids,
//     pos)` in `vlib/v2/ast/flat.v` mirrors `add_expr(MapInitExpr)`
//     encoding exactly (opcode `expr_map_init`, aux1=-1,
//     aux2=keys.len, edges = [typ, keys..., vals...]).
//
//   Session 39 (2026-05-27): ForInStmt port (always-lowers via helper,
//     cross-arm encoding reuse).
//     `transform_stmt`'s ForInStmt arm is a single helper call to
//     `transform_for_in_stmt` (for.v:1115), which wraps the ForInStmt as
//     the `init` of a synthetic ForStmt and delegates to
//     `transform_for_stmt`. The return type is `ast.ForStmt` — a
//     DIFFERENT shape from the input (ForInStmt → ForStmt). All the
//     for-in lowering (RangeExpr → range loop, runes_iterator → array-
//     with-value-type, fixed-array / dynamic-array / string / map /
//     untyped) happens inside `transform_for_stmt` once it sees the
//     ForInStmt in `init`.
//
//     Direct-emit calls `transform_for_in_stmt` once, then encodes the
//     already-transformed ForStmt children via leaf emitters (no
//     re-transform via `transform_*_to_flat` — would double-transform):
//     init/post stmts via `out.emit_stmt`, cond expr via `out.emit_expr`,
//     body stmts via `out.emit_stmt`. Reuses the existing
//     `emit_for_stmt_by_ids(init_id, cond_id, post_id, stmt_ids)` helper
//     from session 38 — no new flat helper needed since the lowered shape
//     is ForStmt.
//
//     Pattern note: stmt-level sibling of AssocExpr (session 34) and
//     MatchExpr (session 35) — the "always-lowers via single helper to a
//     DIFFERENT shape" template. Distinct from session 38 (ForStmt,
//     identity-shape result) because the input arm is ForInStmt but the
//     lowered shape is ForStmt. This is also "cross-arm encoding reuse"
//     — analogous to session 33 (GenericArgOrIndexExpr routes to
//     `transform_index_expr_to_flat` for the next stage) but here we
//     reuse the ENCODING helper rather than re-dispatching through
//     `transform_stmt_to_flat`. We must NOT route through
//     `transform_stmt_to_flat`'s ForStmt arm because that would re-call
//     `transform_for_stmt` on the already-fully-transformed ForStmt —
//     double work and possible smartcast double-application.
//
//     Skips the `ast.ForStmt` wrapper struct allocation for the result
//     and the outer `transform_stmt` match dispatch on every ForInStmt
//     occurrence. Reachability is high: `for x in arr`, `for k, v in
//     map`, `for r in s.runes()` are extremely common (every iterator in
//     the compiler itself uses them).
//
//     No new flat helper this session — reuses `emit_for_stmt_by_ids`
//     from session 38. All 168 transformer-diff tests continue to pass.
//
//   Session 38 (2026-05-27): ForStmt port (always-lowers via helper,
//     identity-shape result).
//     `transform_stmt`'s ForStmt arm is a single helper call to
//     `transform_for_stmt` (for.v:488), which always returns an
//     `ast.ForStmt` regardless of its internal lowering paths. The
//     helper handles for-in loops by dispatching on iterable type
//     (RangeExpr → range lowering; runes_iterator() → array-with-
//     value-type; smartcast array/string variant → array; fixed array
//     → fixed-array; dynamic array/string → array; native backend any
//     → untyped; map/channel/other → ForStmt-wrapped ForInStmt; no
//     type info → untyped) and for plain `for cond { ... }` loops,
//     sets up smartcast contexts from `is` checks in the condition
//     (flattened across `&&` chains), recursively transforms init/
//     cond/post and body via `transform_stmts`, then pops smartcasts
//     and returns the assembled ForStmt. Opens/closes a child scope
//     around the whole transform.
//
//     Direct-emit calls `transform_for_stmt` once, then encodes the
//     already-transformed children via leaf emitters (no re-transform
//     via `transform_*_to_flat` — would double-transform): init/post
//     stmts via `out.emit_stmt`, cond expr via `out.emit_expr`, body
//     stmts via `out.emit_stmt`. Assembles via the new
//     `emit_for_stmt_by_ids(init_id, cond_id, post_id, stmt_ids)`
//     helper, which mirrors `add_stmt(ForStmt)` encoding exactly
//     (pos = `token.Pos{}`, edges = [init, cond, post, body...]).
//
//     Pattern note: stmt-level sibling of SqlExpr branch (b)
//     (session 36) and AssignStmt's main-path (session 37) — the
//     "always-lowers via single helper call, identity-shape result"
//     template. Unlike AssignStmt, there's no pre-arm guard;
//     `transform_for_stmt` handles everything internally. The
//     remaining stmt-side helper-driven arm is ForInStmt (which
//     returns ForStmt — a different shape than its input, so it's a
//     sibling of AssocExpr session 34 / MatchExpr session 35:
//     always-lowers via single helper to a different shape).
//
//     Reachability is high — `for` loops appear in nearly every
//     non-trivial function body. Top-level ForStmts (file scope)
//     are rare, but the arm also fires from any recursive
//     `transform_stmt_to_flat` calls (currently ComptimeStmt's
//     non-$for branch). No new fixture this session. All 168
//     transformer-diff tests continue to pass.
//
//     New pub helper: `emit_for_stmt_by_ids(init_id, cond_id,
//     post_id, stmt_ids)` in `vlib/v2/ast/flat.v` (~line 577).
//
//   Session 37 (2026-05-27): AssignStmt port (pre-arm guard + helper).
//     `transform_stmt`'s AssignStmt arm has a pre-arm dispatch block
//     (transformer.v lines 2958-2966) plus the match-arm call:
//       1. `try_expand_or_expr_assign(stmt)` — stub returning `none`
//          (transformer.v:3804). No-op, skip from direct-emit too.
//       2. `try_transform_map_index_assign(stmt)` — may rewrite map
//          index assigns (`m[key] = v`, `m[k] += v`, `m[k].f = v`, etc.)
//          into an `ExprStmt(map__set(...))` or `BlockStmt` hoisting
//          temp-decl stmts before the call. Returned shape is NOT an
//          AssignStmt — route through leaf `out.emit_stmt(...)`.
//       3. else → `transform_assign_stmt(stmt)` returns an AssignStmt
//          with `lhs`/`rhs` exprs already transformed (string `+=` →
//          `string__plus` call, result/option payload writes, etc.).
//          Direct-emit encodes each lhs/rhs via leaf `out.emit_expr`
//          (pure `add_expr` — `transform_expr_to_flat` would
//          double-transform) and assembles via the new
//          `emit_assign_stmt_by_ids(op, lhs_ids, rhs_ids, pos)` helper.
//
//     Pattern note: stmt-level sibling of SqlExpr (session 36) —
//     "always-lowers via single helper call" with two outcome shapes
//     (rewrite vs identity-rebuild), with an additional pre-arm guard
//     that can short-circuit to a lowered shape. Most assigns reach the
//     identity-rebuild path (only map-index assigns hit the rewrite),
//     so the dispatch-skip win applies broadly. The lowered shapes from
//     `try_transform_map_index_assign` (BlockStmt/ExprStmt) currently
//     route through legacy `emit_stmt`; when a BlockStmt cross-arm
//     router lands they can switch to dispatched routing.
//
//     Mirrors `add_stmt(AssignStmt)` encoding exactly: aux1=-1,
//     aux2=lhs.len (lhs/rhs boundary), meta=u16(op), no flags, edges =
//     lhs in order followed by rhs in order. Skips the `ast.AssignStmt`
//     wrapper struct allocation per occurrence + the `transform_stmt`
//     match dispatch.
//
//     Reachability is very high — assignments appear in nearly every
//     function body. No new fixture this session; existing fixtures
//     exercise AssignStmt extensively (decl-assigns, mutations, compound
//     ops). All 168 transformer-diff tests continue to pass.
//
//     New pub helper: `emit_assign_stmt_by_ids(op, lhs_ids, rhs_ids,
//     pos)` in `vlib/v2/ast/flat.v` (~line 577).
//
//   Session 36 (2026-05-27): SqlExpr port (always-lowers via helper, two
//     outcome shapes).
//     Third sibling at the expr level of the "always-lowers via single
//     helper call" template (after AssocExpr session 34 and MatchExpr
//     session 35). `transform_expr`'s SqlExpr arm is a thin wrapper
//     around `transform_sql_expr` (orm.v), which has two outcome shapes:
//       (a) `is_create` AND `lower_sql_create_expr` finds the table
//           struct → lowers to a CallExpr `expr.create(table_name,
//           table_fields)`, then transforms that CallExpr and returns it
//           — the result is no longer a SqlExpr. Routed through leaf
//           `out.emit_expr(...)` (the lowered CallExpr is already
//           transformed; no re-transform needed).
//       (b) otherwise (read query, count, or create with missing table)
//           → identity-shape rebuild: `SqlExpr{expr:
//           transform_expr(expr.expr), table_name, is_count, is_create,
//           pos}`. Direct-emit encodes `result.expr` via leaf
//           `out.emit_expr` (pure `add_expr` encoder, no re-transform —
//           `transform_expr_to_flat` would double-transform since
//           `transform_sql_expr` already ran `transform_expr` on it) and
//           assembles via the new `emit_sql_expr_by_id(table_name,
//           is_count, is_create, expr_id, pos)` helper. Skips the
//           `ast.SqlExpr` wrapper struct allocation per occurrence.
//
//     Detection: call `transform_sql_expr` once, then dispatch on the
//     result's runtime type — `is ast.SqlExpr` → branch (b), else →
//     branch (a). This keeps the table-lookup logic single-sourced
//     (don't reimplement `lower_sql_create_expr` here just to detect the
//     branch upfront) and preserves the exact "rebuild on lookup miss"
//     semantics.
//
//     Pattern note: extends the "always-lowers via single helper call"
//     template with two outcome shapes. AssocExpr (34) lowers to a leaf
//     Ident; MatchExpr (35) lowers to an IfExpr (awaiting flat helper);
//     SqlExpr (36) either lowers to a CallExpr OR identity-rebuilds.
//     The branch-on-result-type pattern lets identity-shape rebuilds
//     pick up the direct-emit win even when the legacy helper has
//     multiple shapes. Future candidates: arms where a single legacy
//     helper has both a lowering path and an identity-shape rebuild
//     path (some CallExpr/InfixExpr lowering arms fit this).
//
//     Reachability is limited to `sql ... { ... }` blocks (rare in the
//     compiler itself). No new fixture this session — existing fixtures
//     don't exercise SqlExpr. All 168 transformer-diff tests continue
//     to pass.
//
//     New pub helper: `emit_sql_expr_by_id(table_name, is_count,
//     is_create, expr_id, pos)` in `vlib/v2/ast/flat.v` (~line 696).
//     Mirrors `add_expr(SqlExpr)`'s encoding exactly: opcode `expr_sql`,
//     pos, interned table_name (aux1), `flag_is_count | flag_is_create`
//     packed into flags, one edge to inner expr.
//
//   Session 35 (2026-05-27): MatchExpr port (always-lowers via helper).
//     Sibling of AssocExpr (session 34) at the expr level —
//     `transform_expr`'s MatchExpr arm is a single helper call to
//     `t.transform_match_expr(expr)`, which always lowers a `match`
//     construct to an IfExpr:
//       - sum-type match: each branch's smartcast is set up (variant
//         names → tags), then the chain `if x is Variant1 { ... } else
//         if x is Variant2 { ... } ...` is built; the smartcast stack is
//         restored after each branch.
//       - non-sum match: chains `x == c1`/`x in c_list` IfBranches in
//         declaration order, with `else` becoming the final IfBranch.
//     The lowered IfExpr is returned as `ast.Expr` (not pre-transformed
//     through `transform_expr`); the caller's match arm wraps it via
//     legacy `add_expr(transformed_if)` which re-enters `transform_expr`
//     on the IfExpr.
//
//     Direct-emit calls `transform_match_expr` and routes the IfExpr
//     result through the leaf `out.emit_expr(...)` — same as the `else`
//     fallback would, minus the `transform_expr` match dispatch on
//     MatchExpr. No dedicated IfExpr flat helper exists yet, so routing
//     through `transform_expr_to_flat` for the result would only add
//     one dispatch level without benefit. When an IfExpr flat helper
//     lands, change this arm to feed the result back through
//     `transform_expr_to_flat` (cross-arm routing, same pattern as
//     GenericArgOrIndexExpr → transform_index_expr_to_flat in session
//     33).
//
//     Pattern note: same "always-lowers via single helper call" shape
//     as AssocExpr (session 34) — both arms have a single
//     `t.lower_*(expr, ...)` body in legacy `transform_expr`. AssocExpr
//     lowers to a leaf Ident (smartcast context handled via pending
//     stmts); MatchExpr lowers to an IfExpr awaiting its own flat
//     helper. Reachability is high — `match` is one of the most common
//     constructs in the compiler. Win is purely the dispatch skip until
//     IfExpr gets a flat helper.
//
//     No new fixture this session — existing fixtures already exercise
//     MatchExpr extensively (sum-type matches, literal matches, range
//     matches). All 141 transformer-diff tests continue to pass.
//
//   Session 34 (2026-05-26): AssocExpr port (always-lowers via helper).
//     `transform_expr`'s AssocExpr arm is a single helper call —
//     `t.lower_assoc_expr(expr, false)` always lowers the struct-update
//     syntax `{base | field: val}` into a decl-assign of a typed tmp
//     followed by per-field assignments, all hoisted into
//     `t.pending_stmts` (which `transform_stmts` then drains as prefix
//     stmts before the current stmt). The arm returns the tmp Ident
//     (or `&tmp_ident` PrefixExpr in the `take_addr` form, which is
//     only invoked by the PrefixExpr `.amp` rewrite branch — not by
//     this arm).
//
//     Direct-emit calls `lower_assoc_expr` and routes the Ident result
//     through the leaf `out.emit_expr(...)` — same as the `else`
//     fallback minus the `transform_expr` match dispatch on AssocExpr.
//     The win is purely the dispatch skip. Routing through
//     `transform_expr_to_flat` for the result would add a dispatch
//     level without benefit since Idents are leaf direct-emit already.
//
//     Pattern note: establishes the "always-lowers via single helper
//     call" template — sibling of GenericArgOrIndexExpr (session 33)
//     where cross-arm routing applies because the lowered shape has a
//     dedicated flat helper. AssocExpr's result is a leaf Ident, so
//     direct `out.emit_expr` is the right exit. Future siblings:
//     MatchExpr (lowers to IfExpr via `transform_match_expr`) — same
//     shape, route through `out.emit_expr` until an IfExpr flat helper
//     exists; SqlExpr if it has a similar single-helper structure.
//
//     Reachability is moderate — struct-update syntax `{base | f: v}`
//     is used across the compiler for AST node copying. No new fixture
//     this session. All 141 transformer-diff tests continue to pass.
//
//   Session 33 (2026-05-26): GenericArgOrIndexExpr port (cross-arm routing).
//     `transform_expr`'s GenericArgOrIndexExpr arm disambiguates the parser
//     ambiguity for `x[y]` via the lhs type:
//       (a) callable lhs → `specialize_generic_callable_expr(lhs, [expr],
//           pos)` lowers to the generic arg specialization token (Ident or
//           CallExpr) — different shape, route through leaf
//           `out.emit_expr(...)`.
//       (b) otherwise → constructs an `ast.IndexExpr{lhs, expr,
//           is_gated: false, pos}` and runs it through
//           `transform_index_expr`. Direct-emit routes through the
//           existing `transform_index_expr_to_flat` helper so the IndexExpr
//           arm's default-path direct-emit (lhs + expr via
//           `transform_expr_to_flat`, assembled via
//           `emit_index_expr_by_ids`) also applies here.
//
//     Pattern note: first port where one ported `transform_*_to_flat`
//     helper calls another (`GenericArgOrIndexExpr` → `transform_index_
//     expr_to_flat`). Establishes the cross-arm routing template — when
//     an arm always lowers into a shape that already has a flat helper,
//     forward to that helper directly instead of going through legacy
//     `transform_expr` dispatch.
//
//     `is_callable_type` is an immutable lookup (`&Transformer` receiver);
//     `specialize_generic_callable_expr` is `mut`. Gate the mut-call
//     branch via an upfront immutable probe — same shape as the Ident /
//     KeywordOperator / GenericArgs ports (sessions 23-25). Reachability
//     is limited (the parser typically unifies into CallExpr/IndexExpr at
//     parse time), but the port removes one fallback path from the `else`
//     branch. No new fixture this session. All 141 transformer-diff tests
//     continue to pass.
//
//   Session 32 (2026-05-26): AssertStmt port (fallback stmt-level identity).
//     `transform_stmt`'s AssertStmt arm is the rare fallback path — most
//     assert stmts get expanded into `if !cond { panic(...) }` by
//     `transform_stmts` before they reach the per-stmt dispatch. The
//     fallback rebuilds `AssertStmt{expr: t.transform_expr(stmt.expr)}`
//     without setting `extra`, so the result always has `extra =
//     empty_expr` (struct default) and any original `stmt.extra` (the
//     `"assert cond, msg"` text) is DROPPED.
//
//     Direct-emit mirrors that exactly: transform `stmt.expr` via the
//     recursive `transform_expr_to_flat` (so any ported deep-helper expr
//     arm reached inside benefits too) and route through the new
//     `emit_assert_stmt_by_id` helper, which encodes the second edge as
//     `add_expr(empty_expr)` — hits the shared cached `empty_expr_id` so
//     repeat AssertStmts don't duplicate the node. Mirrors
//     `add_stmt(AssertStmt)` encoding exactly (pos = `token.Pos{}`, two
//     edges: expr + empty_expr). Skips the `ast.AssertStmt` wrapper
//     struct allocation per fallback occurrence.
//
//     Reachability is low but the port completes the stmt-level
//     identity-shape coverage planned in session 28's pattern note
//     (BlockStmt → session 29, DeferStmt → session 30, ComptimeStmt →
//     session 31, AssertStmt → this session). No new fixture this
//     session. All 141 transformer-diff tests continue to pass.
//
//   Session 31 (2026-05-26): ComptimeStmt port (two-branch stmt port).
//     `transform_stmt`'s ComptimeStmt arm has two branches:
//       (a) `stmt.stmt is ast.ForStmt` (the `$for field in Type.fields { ... }`
//           form): rebuild ComptimeStmt(ForStmt{init, cond, post, stmts:
//           transform_stmts(for_stmt.stmts)}) — `init`/`cond`/`post` are
//           copied verbatim (NOT transformed by the legacy arm), only the
//           body stmts go through the body driver.
//       (b) otherwise (`$if` as stmt, etc.): legacy returns
//           `transform_stmt(stmt.stmt)` — the ComptimeStmt wrapper is
//           DROPPED entirely; the result is whatever the inner stmt
//           transforms into.
//
//     Direct-emit: branch (a) synthesises a `ForStmt{init, cond, post,
//     transformed_stmts}` and routes it through legacy `out.emit_stmt(...)`
//     for the encoding (ForStmt itself isn't ported yet), then wraps via
//     the new `emit_comptime_stmt_by_id` helper. Branch (b) recurses via
//     `transform_stmt_to_flat(stmt.stmt, ...)` so any ported inner stmt
//     (ExprStmt, ReturnStmt, ...) also stays on the flat path.
//     Mirrors `add_stmt(ComptimeStmt)` encoding exactly (pos =
//     `token.Pos{}`, single edge to inner stmt). Skips the outer
//     `ast.ComptimeStmt` wrapper struct allocation per `$for` occurrence
//     AND the wrapper entirely on the non-`$for` recursive path.
//
//     Reachability is reasonable — compile-time reflection via `$for`
//     shows up in the compiler/runtime helpers. No new fixture this
//     session. All 141 transformer-diff tests continue to pass.
//
//     Pattern note: first stmt port with TWO branches that diverge at
//     emit time (wrap-and-build vs. drop-and-recurse). Establishes the
//     "branch-dispatch" template for future stmt ports where the legacy
//     arm has conditional shape changes (e.g. AssertStmt expand-in-driver
//     vs. fallback, PostfixExpr op-based lowering at the expr level
//     already used this shape on the expr side).
//
//   Session 30 (2026-05-26): DeferStmt port (wrap-only stmt port).
//     Sibling of session 29 (BlockStmt) — same wrap-only shape with a
//     `mode` field. `transform_stmt`'s DeferStmt arm always returns
//     `DeferStmt{mode: stmt.mode, stmts: transform_stmts(stmt.stmts)}` —
//     identity-shape with the body driver `transform_stmts` doing the
//     same inter-stmt work (smartcast snapshot/restore, pending-stmt
//     hoisting, one-to-many expansion). Same driver constraint as the
//     BlockStmt arm.
//
//     Wrap-only port: call legacy `transform_stmts(stmt.stmts)` to
//     materialise the transformed `[]ast.Stmt`, emit each via the legacy
//     `out.emit_stmt(...)` (already transformed), and assemble via the
//     new `emit_defer_stmt_by_ids(mode, stmt_ids)` helper. Mirrors
//     `add_stmt(DeferStmt)` encoding exactly: `pos = token.Pos{}`,
//     `flags |= flag_defer_func` when mode is `.function`, edges = inner
//     stmts in order. Skips the outer `ast.DeferStmt` wrapper struct
//     allocation per occurrence; the inner `[]ast.Stmt` still
//     materialises until the body driver is ported.
//
//     Reachability is limited but clean — `defer { ... }` appears in
//     resource-cleanup paths (file close, mutex unlock, ...) and
//     `defer (func) { ... }` (function-scope variant) in fewer places.
//     No new fixture this session. All 141 transformer-diff tests
//     continue to pass.
//
// Phase 5: post-pass port.
//   The active flat-direct paths run post_pass_to_flat and the post-pass tail
//   without materialising a transformed []ast.File. Compatibility entry points
//   still maintain legacy files for the `.v`/eval backends.
//
// Phase 6: drop compatibility materialisation.
//   `transform_files_to_flat` and `_via_driver` still return []ast.File for
//   legacy consumers. Flat-codegen backends use transform_flat_to_flat_direct
//   or the parallel flat-direct path and keep the transformed program in
//   FlatAst only.
//
// ----- Rewrite Site Inventory (55 sites, audited 2026-05-26) -----
//
// Phase 4's checklist. Categories are coarse — within a category the
// rewrites share most of their helper state (e.g. all or-block expansions
// share `expand_*_or_expr`).
//
// Control-flow lowering (~15 sites):
//   - if.v: if-guard expansion (assign + stmt forms, 2 sites)
//   - for.v: for-in map / array / range / fixed-array / untyped (6 sites)
//   - expr.v: IfGuardExpr in IfExpr, match-expression lowering (~7 sites)
//
// Or-block / Result / Option (~8 sites):
//   - transformer.v: expand_direct_or_expr_assign, expand_single_or_expr,
//     string-range or-block, return-or-block (4 sites)
//   - expr.v: OrExpr in expression context, deref-or, index-or (~4 sites)
//
// Operator / method lowering (~12 sites):
//   - expr.v: operator overload, in-operator, infix coercions, prefix lower,
//     index/slice rewrites, comptime field access (~10 sites)
//   - fn.v: CallExpr method-to-function rewrites, CallOrCastExpr (2 sites)
//
// Structure init (~8 sites):
//   - struct.v: array init, indexed array init, spread, map init, struct
//     init, default-field fill (6 sites)
//   - fn.v: generic specialization synthetic args, FnDecl rewrites (2 sites)
//
// String operations (~3 sites):
//   - transformer.v: string interpolation lowering, embed_file
//   - expr.v: string range / string method dispatch
//
// Defer / lock / go (~4 sites):
//   - transformer.v: defer lowering, lock/rlock expansion, go-wrapper
//   - fn.v: native interface vtable elision
//
// Generic specialization (~2 sites):
//   - fn.v: monomorphize call rewrite
//   - transformer.v: lower_assoc_expr
//
// Misc (~3 sites):
//   - transformer.v: assert message lowering, assign_stmt multi-return,
//     transform_stmt dispatcher special cases
//   - orm.v: SQL expression lowering (1 site)
//
// ----- Per-file flat-write entry point -----

// transform_file_index_to_flat is the per-file entry point for the multi-
// session port. It reads one file from `input_flat` through cursors, mirrors
// `transform_file`'s prologue, and emits each top-level stmt through the
// `transform_stmt_to_flat` seam. Returns the FlatNodeId of the appended file
// root, or `ast.invalid_flat_node_id` for an empty / missing source file.
//
// The file-level loop uses the flat stmt-list driver rather than dispatching
// each stmt directly. Top-level comptime `$if` blocks can expand to multiple
// declarations, and codegen expects those declarations to live directly under
// the file root.
//
// Callers must invoke `pre_pass_from_flat(input_flat)` before the per-file
// loop and `post_pass(mut collected_files)` after, mirroring the wedge. The
// per-file API does not run those passes itself so future phases can
// interleave file emissions with pre/post bookkeeping without re-running it.
pub fn (mut t Transformer) transform_file_index_to_flat(input_flat &ast.FlatAst, fi int, mut out ast.FlatBuilder) ast.FlatNodeId {
    return t.transform_flat_file_index_to_flat(input_flat, fi, []ast.Stmt{}, mut out)
}

// transform_file_index_with_extra_to_flat is the pub entry the parallel
// flat-direct transform uses: it forwards the monomorphize-generated `extra`
// stmts for file `fi` (from prepare_flat_for_transform) into the cursor-native
// per-file transform. The plain `transform_file_index_to_flat` above passes no
// extras (sequential generic-free callers).
pub fn (mut t Transformer) transform_file_index_with_extra_to_flat(input_flat &ast.FlatAst, fi int, extra_stmts []ast.Stmt, mut out ast.FlatBuilder) ast.FlatNodeId {
    return t.transform_flat_file_index_to_flat(input_flat, fi, extra_stmts, mut out)
}

fn (mut t Transformer) transform_flat_file_index_to_flat(input_flat &ast.FlatAst, fi int, extra_stmts []ast.Stmt, mut out ast.FlatBuilder) ast.FlatNodeId {
    if fi < 0 || fi >= input_flat.files.len {
        return ast.invalid_flat_node_id
    }
    fc := input_flat.file_cursor(fi)
    t.cur_file_name = fc.name()
    t.cur_module = fc.mod()
    t.cur_import_aliases = flat_import_aliases_for_generic_collect(input_flat, fi)
    if scope := t.get_module_scope(t.cur_module) {
        t.scope = scope
    } else {
        t.scope = unsafe { nil }
    }
    stmt_ids := t.transform_cursor_stmts_to_flat_direct(fc.stmts(), extra_stmts, mut out)
    attrs_id := copy_cursor_aux_list_to_flat(fc.attrs(), mut out)
    imports_id := copy_cursor_aux_list_to_flat(fc.imports(), mut out)
    return out.append_file_with_flat_lists_and_stmt_ids(fc.name(), fc.mod(), fc.selector_names(),
        attrs_id, imports_id, stmt_ids)
}

// transform_file_to_flat transforms one legacy file and appends the transformed
// tree directly to `out`. It is the AST-input counterpart to
// `transform_file_index_to_flat`, used by flat-output pipelines after
// whole-program generic preparation has produced concrete appended stmts.
pub fn (mut t Transformer) transform_file_to_flat(file ast.File, mut out ast.FlatBuilder) ast.FlatNodeId {
    // Mirror transform_file's per-file prologue. transform_stmt and the
    // rewrite sites read these fields to resolve cross-stmt references.
    t.cur_file_name = file.name
    t.cur_module = file.mod
    t.cur_import_aliases = import_aliases_for_generic_collect(file.imports)
    if scope := t.get_module_scope(file.mod) {
        t.scope = scope
    } else {
        t.scope = unsafe { nil }
    }
    // Top-level comptime `$if` blocks can expand to multiple declarations
    // (for example platform-specific worker structs/functions). Use the same
    // stmt-list driver as function bodies so selected branch stmts are spliced
    // into the file root instead of being hidden inside a top-level BlockStmt.
    stmt_ids := t.transform_stmts_to_flat_direct(file.stmts, mut out)
    return out.append_file_with_stmt_ids(file, stmt_ids)
}

// transform_stmts_to_flat is the consolidated seam for "transform a body
// stmt list, then encode each result into the flat builder" — the pattern
// repeated at every flat-write arm that wraps a body (BlockStmt, DeferStmt,
// ComptimeStmt $for body, UnsafeExpr body, FnLiteral body). Currently a
// literal pass-through over `transform_stmts` + leaf-encode loop, kept as a
// single function so future sessions can replace the body with direct-emit
// ports for `transform_stmts`'s expansion sites (comptime $if assign, or-
// block assign, tuple if-assign, lock/rlock, for-in-map, assert, ...) in
// one place. The FnDecl arm has its own seam (`transform_fn_decl_parts_to_flat`)
// because the FnDecl body driver also runs `lower_defer_stmts` between
// `transform_stmts` and the flat encoding — porting that needs a separate
// thrust.
pub fn (mut t Transformer) transform_stmts_to_flat(stmts []ast.Stmt, mut out ast.FlatBuilder) []ast.FlatNodeId {
    return t.transform_stmts_to_flat_direct(stmts, mut out)
}

// transform_stmts_to_flat_direct is the flat-direct mirror of
// `transform_stmts` (transformer.v:3072). Drives the per-stmt loop emitting
// `FlatNodeId`s straight into `out` instead of materialising a `[]ast.Stmt`
// intermediate. Mirrors every expansion site (comptime $if assign, native
// interface cast/sincos, or-block assign, tuple if-assign, tuple call-assign,
// if-guard assign, if-expr assign, $if expr-stmt, or-expr stmt, if-guard
// stmt, flag-enum set/clear, return-match, or-return, return-if, lock/rlock,
// map-index push/postfix, native selector postfix, for-in-map, assert) and
// the default fall-through via `append_transformed_stmt_to_flat`.
//
// Stmts produced by expansion helpers (legacy `try_expand_*` /
// `expand_*` helpers that still return `ast.Stmt` / `[]ast.Stmt`) are leaf-
// encoded via `out.emit_stmt(...)` — these helpers transform the contained
// exprs internally, so leaf-encoding is bit-equal to the legacy
// `result << expanded_X` push. The `transform_stmt(stmt)` dispatch on the
// default fall-through routes through `transform_stmt_to_flat`'s direct-emit
// arms via the appender, which skips the legacy stmt-wrapper allocation for
// the many already-ported variants.
//
// Saves the outer `[]ast.Stmt` allocation (one per call) and the stmt-
// wrapper allocations on the default path. Expansion sites still materialise
// their inner intermediates — those need per-helper `_to_flat` ports in
// future sessions to fully drop the legacy materialisation.
pub fn (mut t Transformer) transform_stmts_to_flat_direct(stmts []ast.Stmt, mut out ast.FlatBuilder) []ast.FlatNodeId {
    mut ids := []ast.FlatNodeId{cap: stmts.len}
    block_smartcast_depth := t.smartcast_stack.len
    has_smartcast_state := block_smartcast_depth > 0
    block_smartcast_stack := if has_smartcast_state {
        t.smartcast_stack.clone()
    } else {
        []SmartcastContext{}
    }
    block_smartcast_counts := if has_smartcast_state {
        t.smartcast_expr_counts.clone()
    } else {
        map[string]int{}
    }
    for stmt in stmts {
        t.restore_flat_stmt_list_smartcast_context(block_smartcast_depth, block_smartcast_stack,
            block_smartcast_counts)
        t.transform_stmt_list_item_to_flat(stmt, mut ids, mut out)
    }
    t.restore_flat_stmt_list_smartcast_context(block_smartcast_depth, block_smartcast_stack,
        block_smartcast_counts)
    return ids
}

pub fn (mut t Transformer) transform_cursor_stmts_to_flat_direct(stmts ast.CursorList, extra_stmts []ast.Stmt, mut out ast.FlatBuilder) []ast.FlatNodeId {
    mut ids := []ast.FlatNodeId{cap: stmts.len() + extra_stmts.len}
    block_smartcast_depth := t.smartcast_stack.len
    has_smartcast_state := block_smartcast_depth > 0
    block_smartcast_stack := if has_smartcast_state {
        t.smartcast_stack.clone()
    } else {
        []SmartcastContext{}
    }
    block_smartcast_counts := if has_smartcast_state {
        t.smartcast_expr_counts.clone()
    } else {
        map[string]int{}
    }
    for i in 0 .. stmts.len() {
        t.restore_flat_stmt_list_smartcast_context(block_smartcast_depth, block_smartcast_stack,
            block_smartcast_counts)
        t.transform_stmt_list_item_cursor_to_flat(stmts.at(i), mut ids, mut out)
    }
    for stmt in extra_stmts {
        t.restore_flat_stmt_list_smartcast_context(block_smartcast_depth, block_smartcast_stack,
            block_smartcast_counts)
        t.transform_stmt_list_item_to_flat(stmt, mut ids, mut out)
    }
    t.restore_flat_stmt_list_smartcast_context(block_smartcast_depth, block_smartcast_stack,
        block_smartcast_counts)
    return ids
}

fn (mut t Transformer) restore_flat_stmt_list_smartcast_context(block_smartcast_depth int, block_smartcast_stack []SmartcastContext, block_smartcast_counts map[string]int) {
    if t.smartcast_stack.len < block_smartcast_depth {
        t.smartcast_stack = block_smartcast_stack.clone()
        t.smartcast_expr_counts = block_smartcast_counts.clone()
    } else if t.smartcast_stack.len > block_smartcast_depth {
        t.truncate_smartcasts(block_smartcast_depth)
    }
}

fn (mut t Transformer) transform_stmt_list_item_to_flat(stmt ast.Stmt, mut ids []ast.FlatNodeId, mut out ast.FlatBuilder) {
    if stmt is ast.AssignStmt {
        assign_stmt := stmt as ast.AssignStmt
        if t.try_expand_comptime_if_assign_to_flat(assign_stmt, mut ids, mut out) {
            return
        }
        t.track_interface_assign_to_flat(assign_stmt)
        if t.try_expand_interface_cast_assign_to_flat(assign_stmt, mut ids, mut out) {
            return
        }
        if t.try_expand_sincos_assign_to_flat(assign_stmt, mut ids, mut out) {
            return
        }
        if t.try_expand_or_expr_assign_stmts_to_flat(&assign_stmt, mut ids, mut out) {
            return
        }
        if t.try_expand_tuple_if_assign_stmts_to_flat(assign_stmt, mut ids, mut out) {
            return
        }
        if t.try_expand_tuple_call_assign_to_flat(assign_stmt, mut ids, mut out) {
            return
        }
        if t.try_expand_if_guard_assign_stmts_to_flat(assign_stmt, mut ids, mut out) {
            return
        }
        if t.try_expand_if_expr_assign_stmts_to_flat(assign_stmt, mut ids, mut out) {
            return
        }
    }
    if stmt is ast.ExprStmt {
        if t.try_expand_comptime_if_stmt_to_flat(stmt, mut ids, mut out) {
            return
        }
    }
    if stmt is ast.ExprStmt {
        if t.try_expand_or_expr_stmt_to_flat(stmt, mut ids, mut out) {
            return
        }
        if t.try_expand_if_guard_stmt_to_flat(stmt, mut ids, mut out) {
            return
        }
    }
    if stmt is ast.ExprStmt {
        if t.try_emit_flag_enum_set_clear_to_flat(stmt, mut ids, mut out) {
            return
        }
    }
    if stmt is ast.ReturnStmt {
        if t.try_expand_return_match_expr_to_flat(stmt, mut ids, mut out) {
            return
        }
        if t.try_expand_or_expr_return_to_flat(stmt, mut ids, mut out) {
            return
        }
        if t.try_expand_return_if_expr_to_flat(stmt, mut ids, mut out) {
            return
        }
    }
    if stmt is ast.ExprStmt {
        if stmt.expr is ast.LockExpr {
            t.expand_lock_expr_to_flat(stmt.expr, mut ids, mut out)
            return
        }
        if t.try_emit_map_index_push_to_flat(stmt, mut ids, mut out) {
            return
        }
        if t.try_emit_map_index_postfix_to_flat(stmt, mut ids, mut out) {
            return
        }
        if t.try_emit_selector_postfix_to_flat(stmt, mut ids, mut out) {
            return
        }
    }
    if stmt is ast.ForStmt {
        if t.try_expand_for_in_map_to_flat(stmt, mut ids, mut out) {
            return
        }
    }
    if stmt is ast.AssertStmt {
        t.expand_assert_stmt_to_flat(stmt, mut ids, mut out)
        return
    }
    t.append_transformed_stmt_to_flat(mut ids, stmt, mut out)
}

// transform_stmt_list_item_cursor_to_flat is the cursor-input mirror of
// `transform_stmt_list_item_to_flat`. It dispatches on the top-level statement's
// FlatNodeKind so converted arms can be handled without routing through the
// legacy guard chain, and unconverted kinds fall back to the proven decode path
// in one line. This is the seam that lets the transform become cursor-native one
// statement kind at a time (eliminating the whole-subtree `.stmt()` decode at
// the `transform_cursor_stmts_to_flat_direct` loop).
//
// First converted set: true-passthrough top-level kinds that carry no
// `try_expand_*` guard and that `transform_stmt_to_flat` emits verbatim. Those
// copy their flat subtrees directly, so they do not route through `c.stmt()`.

// classify_call_fallback_cursor builds a diagnostic key describing WHY a call
// fell back to the legacy decode path. Instrumentation for V2_FLAT_FB_STATS.
fn (t &Transformer) classify_call_fallback_cursor(c ast.Cursor, prefix string) string {
    lhs := c.edge(0)
    if lhs.kind() != .expr_selector {
        return '${prefix}/lhs=${lhs.kind()}'
    }
    receiver := lhs.edge(0)
    method_name := selector_rhs_name_cursor(lhs)
    if t.has_active_smartcast() {
        return '${prefix}/sel/smartcast'
    }
    if method_name_needs_legacy_selector_pipeline(method_name) {
        return '${prefix}/sel/legacy-list:${method_name}'
    }
    recv_type := t.get_expr_type_cursor(receiver) or { return '${prefix}/sel/no-recv-type' }
    base := t.unwrap_alias_and_pointer_type(recv_type)
    if base is types.Struct {
        if !t.type_has_cached_method(base, method_name) {
            return '${prefix}/sel/no-cached-method'
        }
    } else {
        // Mirror the non-struct receiver gate: only its rejects classify as
        // receiver failures; accepted receivers fall through to late gates.
        if method_name in ['filter', 'map', 'any', 'count', 'wait'] {
            return '${prefix}/sel/expansion-method:${method_name}'
        }
        if base is types.Interface || base is types.SumType {
            return '${prefix}/sel/recv-dispatch=${base.name()}'
        }
        if t.resolve_alias_receiver_method_name(recv_type, method_name) == none
            && !(t.type_is_string(recv_type)
            && t.lookup_method_cached('string', method_name) != none) {
            return '${prefix}/sel/recv=${typeof(base).name}:${base.name()}:m=${method_name}'
        }
    }
    if t.resolve_static_type_method_call_cursor(receiver, method_name) != none {
        return '${prefix}/sel/static-shadow'
    }
    call_name := t.resolve_method_call_name_cursor(receiver, method_name) or {
        return '${prefix}/sel/no-call-name'
    }
    if call_name in t.elided_fns {
        return '${prefix}/sel/elided'
    }
    info := t.generic_aware_call_fn_info_cursor(c.edge(0), call_name) or {
        return '${prefix}/sel/no-fn-info'
    }
    arg_count := if c.kind() == .expr_call_or_cast {
        arg0 := c.edge(1)
        if arg0.is_valid() && arg0.kind() != .expr_empty {
            1
        } else {
            0
        }
    } else {
        c.edge_count() - 1
    }
    if info.param_types.len != arg_count {
        return '${prefix}/sel/arity:${call_name}:${info.param_types.len}vs${arg_count}'
    }
    if info.is_variadic {
        return '${prefix}/sel/variadic'
    }
    if info.generic_params.len > 0 {
        return '${prefix}/sel/generic'
    }
    for i in 0 .. arg_count {
        arg := c.edge(i + 1)
        if arg.kind() == .aux_field_init {
            return '${prefix}/sel/field-init-arg'
        }
        if !t.identity_call_arg_can_transform_direct(arg, info.param_types[i]) {
            param_base := t.unwrap_alias_type(info.param_types[i])
            param_kind := match param_base {
                types.Struct { 'struct' }
                types.Enum { 'enum' }
                types.Array { 'array' }
                types.ArrayFixed { 'array_fixed' }
                types.Map { 'map' }
                types.SumType { 'sumtype' }
                types.Interface { 'interface' }
                types.FnType { 'fn' }
                types.OptionType { 'option' }
                types.ResultType { 'result' }
                types.Pointer { 'pointer' }
                types.String { 'string' }
                else { 'other' }
            }

            return '${prefix}/sel/arg-not-identity/param=${param_kind}'
        }
    }
    return '${prefix}/sel/struct-late-gate-unknown'
}

fn (mut t Transformer) transform_stmt_list_item_cursor_to_flat(c ast.Cursor, mut ids []ast.FlatNodeId, mut out ast.FlatBuilder) {
    match c.kind() {
        .stmt_import, .stmt_module, .stmt_directive, .stmt_empty, .stmt_enum_decl,
        .stmt_interface_decl, .stmt_type_decl, .stmt_asm, .stmt_flow_control, .stmt_attributes {
            id := out.copy_subtree_from(c.flat, c.id)
            t.append_transformed_stmt_id_to_flat(mut ids, id, mut out)
        }
        .stmt_const_decl {
            id := t.transform_const_decl_cursor_to_flat(c, mut out)
            t.append_transformed_stmt_id_to_flat(mut ids, id, mut out)
        }
        .stmt_block {
            id := t.transform_block_stmt_cursor_to_flat(c, mut out)
            t.append_transformed_stmt_id_to_flat(mut ids, id, mut out)
        }
        .stmt_defer {
            id := t.transform_defer_stmt_cursor_to_flat(c, mut out)
            t.append_transformed_stmt_id_to_flat(mut ids, id, mut out)
        }
        .stmt_label {
            id := t.transform_label_stmt_cursor_to_flat(c, mut out)
            t.append_transformed_stmt_id_to_flat(mut ids, id, mut out)
        }
        .stmt_global_decl {
            id := t.transform_global_decl_cursor_to_flat(c, mut out)
            t.append_transformed_stmt_id_to_flat(mut ids, id, mut out)
        }
        .stmt_struct_decl {
            t.count_flat_fallback('stmt_struct_decl')
            id := out.emit_stmt(t.transform_struct_decl(c.struct_decl()))
            t.append_transformed_stmt_id_to_flat(mut ids, id, mut out)
        }
        .stmt_assert {
            t.expand_assert_stmt_cursor_to_flat(c, mut ids, mut out)
        }
        .stmt_assign {
            if id := t.transform_map_index_assign_cursor_to_flat(c, mut out) {
                t.append_transformed_stmt_id_to_flat(mut ids, id, mut out)
                return
            }
            if t.try_expand_if_expr_assign_cursor_to_flat(c, mut ids, mut out) {
                return
            }
            if t.assign_stmt_cursor_needs_legacy_expand(c) {
                t.count_flat_fallback('stmt_assign')
                t.transform_stmt_list_item_to_flat(assign_stmt_from_cursor(c), mut ids, mut out)
            } else {
                id := t.transform_assign_stmt_cursor_to_flat(c, mut out)
                t.append_transformed_stmt_id_to_flat(mut ids, id, mut out)
            }
        }
        .stmt_comptime {
            id := t.transform_comptime_stmt_cursor_to_flat(c, mut out)
            t.append_transformed_stmt_id_to_flat(mut ids, id, mut out)
        }
        .stmt_expr {
            if t.try_expand_comptime_if_stmt_cursor_to_flat(c, mut ids, mut out) {
                return
            }
            if c.edge(0).kind() == .expr_lock {
                t.expand_lock_expr_cursor_to_flat(c.edge(0), mut ids, mut out)
                return
            }
            if id := t.transform_flag_enum_set_clear_cursor_to_flat(c, mut out) {
                t.append_transformed_stmt_id_to_flat(mut ids, id, mut out)
                return
            }
            if t.expr_stmt_cursor_needs_legacy_expand(c) {
                t.count_flat_fallback('stmt_expr')
                t.transform_stmt_list_item_to_flat(expr_stmt_from_cursor(c), mut ids, mut out)
            } else {
                expr := c.edge(0)
                if expr.kind() == .expr_infix
                    && unsafe { token.Token(int(expr.aux())) } == .left_shift {
                    if t.try_emit_map_index_push_to_flat(expr_stmt_from_cursor(c), mut ids, mut out) {
                        return
                    }
                }
                id := t.transform_expr_stmt_cursor_to_flat(c, mut out)
                t.append_transformed_stmt_id_to_flat(mut ids, id, mut out)
            }
        }
        .stmt_return {
            if t.try_expand_return_if_expr_cursor_to_flat(c, mut ids, mut out) {
                return
            }
            if t.return_stmt_cursor_needs_legacy_expand(c) {
                t.count_flat_fallback('stmt_return')
                t.transform_stmt_list_item_to_flat(return_stmt_from_cursor(c), mut ids, mut out)
            } else {
                id := t.transform_return_stmt_cursor_to_flat(c, mut out)
                t.append_transformed_stmt_id_to_flat(mut ids, id, mut out)
            }
        }
        .stmt_for_in {
            t.count_flat_fallback('stmt_for_in')
            t.transform_stmt_list_item_to_flat(for_in_stmt_from_cursor(c), mut ids, mut out)
        }
        .stmt_fn_decl {
            decl := c.fn_decl_signature()
            if t.omit_backend_generic_decl(decl) {
                return
            }
            // Stream the body cursor-native when it has no defers (defer
            // lowering needs the whole body, so those take the legacy
            // whole-decl decode path).
            if flat_body_has_defer(c.list_at(3)) {
                t.count_flat_fallback('stmt_fn_decl_defer')
                decl_with_body := fn_decl_signature_with_body_cursor(c.fn_decl_signature(), c)
                t.transform_stmt_list_item_to_flat(decl_with_body, mut ids, mut out)
            } else {
                id := t.transform_fn_decl_streaming_to_flat(c, mut out)
                t.append_transformed_stmt_id_to_flat(mut ids, id, mut out)
            }
        }
        .stmt_for {
            // Stream plain `for` loops (cond / classic / bare) cursor-native.
            // For-in loops dispatch through cursor-native lowerings for the
            // migrated iterable families, and only unported forms fall back to
            // the legacy whole-loop decode path.
            init_c := c.edge(0)
            if init_c.is_valid() && init_c.kind() == .stmt_for_in {
                if t.try_expand_range_for_in_cursor_to_flat(c, mut ids, mut out) {
                    return
                }
                if t.try_expand_array_for_in_cursor_to_flat(c, mut ids, mut out) {
                    return
                }
                if t.try_expand_fixed_array_for_in_cursor_to_flat(c, mut ids, mut out) {
                    return
                }
                if t.try_expand_for_in_map_cursor_to_flat(c, mut ids, mut out) {
                    return
                }
                if t.try_expand_untyped_for_in_cursor_to_flat(c, mut ids, mut out) {
                    return
                }
                if t.try_expand_passthrough_for_in_cursor_to_flat(c, mut ids, mut out) {
                    return
                }
                panic('unhandled flat for-in lowering')
            } else {
                id := t.transform_for_stmt_streaming_to_flat(c, mut out)
                t.append_transformed_stmt_id_to_flat(mut ids, id, mut out)
            }
        }
        else {
            panic('unexpected flat statement kind: ${c.kind()}')
        }
    }
}

// append_transformed_stmt_to_flat is the flat-builder mirror of
// `append_transformed_stmt` (transformer.v:3061). Runs `transform_stmt_to_flat`
// on the input stmt (direct-emitting via the dispatch seam), then drains any
// `t.pending_stmts` produced by sub-transforms (e.g. or-block side effects
// pushed by `expand_single_or_expr`) by leaf-encoding them into `out` BEFORE
// the just-emitted main stmt — matching the ordering invariant of the legacy
// appender ("pending stmts hoist ahead of the transformed result").
//
// Scaffolding for the `transform_stmts` body driver port (arc #1). Future
// sessions fork the legacy `transform_stmts` body into a direct-emit driver
// that drives the per-stmt loop via this appender, replacing the inner
// `t.append_transformed_stmt(mut result, ast.Stmt(...))` calls with their
// `_to_flat` equivalents. Used today by `transform_file_index_to_flat`'s
// top-level loop (replacing the previous push/pop/restore pattern).
pub fn (mut t Transformer) append_transformed_stmt_to_flat(mut ids []ast.FlatNodeId, stmt ast.Stmt, mut out ast.FlatBuilder) {
    id := t.transform_stmt_to_flat(stmt, mut out)
    t.append_transformed_stmt_id_to_flat(mut ids, id, mut out)
}

// append_transformed_stmt_id_to_flat hoists any `t.pending_stmts` produced
// while building `id` ahead of it (matching the appender's ordering invariant),
// then pushes `id`. Shared by `append_transformed_stmt_to_flat` and the
// cursor-native stmt arms (transform_stmt_list_item_cursor_to_flat) so both
// drain pending side effects identically.
fn (mut t Transformer) append_transformed_stmt_id_to_flat(mut ids []ast.FlatNodeId, id ast.FlatNodeId, mut out ast.FlatBuilder) {
    // Flat-side hoists drain first: arms that push pending_flat_stmt_ids
    // flush the legacy pending_stmts queue into it beforehand, so emitting
    // the flat queue first preserves the legacy chronological order.
    if t.pending_flat_stmt_ids.len > 0 {
        for fid in t.pending_flat_stmt_ids {
            ids << fid
        }
        t.pending_flat_stmt_ids.clear()
    }
    if t.pending_stmts.len > 0 {
        pending := t.pending_stmts.clone()
        t.pending_stmts.clear()
        for ps in pending {
            ids << out.emit_stmt(ps)
        }
    }
    ids << id
}

// transform_const_decl_cursor_to_flat is the cursor-input mirror of the
// `ast.ConstDecl` arm of `transform_stmt_to_flat` (flat_write.v). It reads the
// const decl's is_public flag and field-init list straight from the cursor —
// the ConstDecl wrapper + FieldInit structure are never decoded to legacy — and
// transforms each field value via the existing `transform_expr_to_flat`. Emit
// order matches the flat-output arm exactly (per-field value+field_init, then
// the fields aux_list, then the stmt).
fn (mut t Transformer) transform_const_decl_cursor_to_flat(c ast.Cursor, mut out ast.FlatBuilder) ast.FlatNodeId {
    fields := c.list_at(0)
    mut field_ids := []ast.FlatNodeId{cap: fields.len()}
    for i in 0 .. fields.len() {
        fc := fields.at(i)
        value_id := t.transform_expr_cursor_to_flat(fc.edge(0), mut out)
        field_ids << out.emit_field_init_by_id(fc.name(), value_id)
    }
    fields_list_id := out.emit_aux_list_from_ids(field_ids)
    return out.emit_const_decl_by_ids(c.flag(ast.flag_is_public), fields_list_id)
}

// transform_global_decl_cursor_to_flat is the cursor-input mirror of the
// `ast.GlobalDecl` arm of `transform_stmt_to_flat`. It reads the decl
// attributes, field-decl list, and per-field metadata/flags from the cursor and
// transforms each field's typ + value via `transform_expr_to_flat`. Emit order
// matches the flat-output arm (decl attrs, then per-field typ/value/attrs/
// field_decl, then the fields aux_list, then the stmt).
fn (mut t Transformer) transform_global_decl_cursor_to_flat(c ast.Cursor, mut out ast.FlatBuilder) ast.FlatNodeId {
    decl_attrs_id := copy_cursor_aux_list_to_flat(c.list_at(0), mut out)
    fields := c.list_at(1)
    mut field_ids := []ast.FlatNodeId{cap: fields.len()}
    for i in 0 .. fields.len() {
        fc := fields.at(i)
        typ_id := t.transform_expr_cursor_to_flat(fc.edge(0), mut out)
        value_id := t.transform_expr_cursor_to_flat(fc.edge(1), mut out)
        field_attrs_id := copy_cursor_aux_list_to_flat(fc.list_at(2), mut out)
        field := ast.FieldDecl{
            name:                fc.name()
            is_public:           fc.flag(ast.flag_is_public)
            is_mut:              fc.flag(ast.flag_is_mut)
            is_module_mut:       fc.flag(ast.flag_field_is_module_mut)
            is_interface_method: fc.flag(ast.flag_field_is_interface_method)
        }
        field_ids << out.emit_field_decl_by_ids(field, typ_id, value_id, field_attrs_id)
    }
    fields_list_id := out.emit_aux_list_from_ids(field_ids)
    return out.emit_global_decl_by_ids(c.flag(ast.flag_is_public), decl_attrs_id, fields_list_id)
}

fn assoc_expr_from_cursor(c ast.Cursor) ast.AssocExpr {
    mut fields := []ast.FieldInit{cap: c.edge_count() - 2}
    for i in 2 .. c.edge_count() {
        field := c.edge(i)
        fields << ast.FieldInit{
            name:  field.name()
            value: field.edge(0).expr()
        }
    }
    return ast.AssocExpr{
        typ:    c.edge(0).expr()
        expr:   c.edge(1).expr()
        fields: fields
        pos:    c.pos()
    }
}

fn or_expr_from_cursor(c ast.Cursor) ast.OrExpr {
    mut stmts := []ast.Stmt{cap: c.edge_count() - 1}
    for i in 1 .. c.edge_count() {
        stmts << c.edge(i).stmt()
    }
    return ast.OrExpr{
        expr:  c.edge(0).expr()
        stmts: stmts
        pos:   c.pos()
    }
}

fn infix_expr_from_cursor(c ast.Cursor) ast.InfixExpr {
    return ast.InfixExpr{
        op:  unsafe { token.Token(int(c.aux())) }
        lhs: c.edge(0).expr()
        rhs: c.edge(1).expr()
        pos: c.pos()
    }
}

fn (t &Transformer) cursor_is_string_concat_operand(c ast.Cursor) bool {
    if !c.is_valid() {
        return false
    }
    if t.is_string_expr_cursor(c) {
        return true
    }
    match c.kind() {
        .expr_call {
            if c.edge_count() == 0 {
                return false
            }
            lhs := c.edge(0)
            return lhs.kind() == .expr_ident && lhs.name().starts_with('string__')
        }
        .expr_paren, .expr_modifier {
            return c.edge_count() > 0 && t.cursor_is_string_concat_operand(c.edge(0))
        }
        .expr_infix {
            op := unsafe { token.Token(int(c.aux())) }
            return op == .plus && (t.cursor_is_string_concat_operand(c.edge(0))
                || t.cursor_is_string_concat_operand(c.edge(1)))
        }
        else {
            return false
        }
    }
}

fn (t &Transformer) infix_plus_cursor_can_transform_direct(c ast.Cursor) bool {
    if t.cursor_is_string_concat_operand(c.edge(0)) || t.cursor_is_string_concat_operand(c.edge(1)) {
        return false
    }
    if lhs_type := t.get_expr_type_cursor(c.edge(0)) {
        if lhs_type is types.Struct {
            type_name := t.type_to_c_name(lhs_type)
            if type_name == 'time__Time' {
                return false
            }
        }
    }
    return true
}

fn cursor_is_enum_shorthand_selector(c ast.Cursor) bool {
    if !c.is_valid() || c.kind() != .expr_selector || c.edge_count() == 0 {
        return false
    }
    lhs := c.edge(0)
    return lhs.kind() == .expr_empty || (lhs.kind() == .expr_ident && lhs.name() == '')
}

fn (mut t Transformer) enum_shorthand_cursor_to_flat(c ast.Cursor, enum_type string, mut out ast.FlatBuilder) ?ast.FlatNodeId {
    if enum_type == '' || !cursor_is_enum_shorthand_selector(c) {
        return none
    }
    member := c.edge(1)
    if typ := t.lookup_type(enum_type) {
        t.register_synth_type(c.pos(), typ)
        if typ is types.Enum {
            return out.emit_ident_by_name(t.enum_member_ident_for_lookup(enum_type, typ,
                member.name()), c.pos())
        }
    }
    return out.emit_ident_by_name(enum_member_ident(enum_type, member.name()), c.pos())
}

fn (mut t Transformer) transform_enum_shorthand_compare_cursor_to_flat(c ast.Cursor, op token.Token, mut out ast.FlatBuilder) ?ast.FlatNodeId {
    if op !in [.eq, .ne] || c.edge_count() < 2 {
        return none
    }
    lhs := c.edge(0)
    rhs := c.edge(1)
    if cursor_is_enum_shorthand_selector(rhs) {
        enum_type := t.get_enum_type_name_cursor(lhs)
        rhs_id := t.enum_shorthand_cursor_to_flat(rhs, enum_type, mut out) or { return none }
        lhs_id := t.transform_expr_cursor_to_flat(lhs, mut out)
        return out.emit_infix_expr_by_ids(op, lhs_id, rhs_id, c.pos())
    }
    if cursor_is_enum_shorthand_selector(lhs) {
        enum_type := t.get_enum_type_name_cursor(rhs)
        lhs_id := t.enum_shorthand_cursor_to_flat(lhs, enum_type, mut out) or { return none }
        rhs_id := t.transform_expr_cursor_to_flat(rhs, mut out)
        return out.emit_infix_expr_by_ids(op, lhs_id, rhs_id, c.pos())
    }
    return none
}

fn (t &Transformer) sumtype_check_variant_name_cursor(rhs ast.Cursor) (string, string) {
    if rhs.kind() == .expr_ident {
        return rhs.name(), ''
    }
    if rhs.kind() == .expr_selector {
        mut variant_module := ''
        rhs_lhs := rhs.edge(0)
        if rhs_lhs.kind() == .expr_ident {
            variant_module = rhs_lhs.name()
        }
        return selector_rhs_name_cursor(rhs), variant_module
    }
    return t.type_expr_to_variant_name_cursor(rhs), ''
}

fn (mut t Transformer) transform_interface_self_type_check_cursor_to_flat(lhs ast.Cursor, variant_name string, op token.Token, pos token.Pos, mut out ast.FlatBuilder) ?ast.FlatNodeId {
    lhs_type := t.get_expr_type_cursor(lhs) or { return none }
    lhs_base := t.unwrap_alias_and_pointer_type(lhs_type)
    if lhs_base !is types.Interface {
        return none
    }
    lhs_base_name := lhs_base.name()
    if !lhs_base_name.ends_with(variant_name) && lhs_base_name != variant_name {
        return none
    }
    lhs_id := t.transform_expr_cursor_to_flat(lhs, mut out)
    type_id := t.synth_selector_cursor_to_flat(lhs_id, '_type_id', types.Type(types.int_), mut out)
    zero_id := out.emit_basic_literal_by_value(.number, '0', pos)
    cmp_op := if op in [.key_is, .eq] { token.Token.ne } else { token.Token.eq }
    return out.emit_infix_expr_by_ids(cmp_op, type_id, zero_id, pos)
}

fn (mut t Transformer) transform_sumtype_check_cursor_to_flat(c ast.Cursor, op token.Token, mut out ast.FlatBuilder) ?ast.FlatNodeId {
    if op !in [.key_is, .not_is, .eq, .ne] || c.edge_count() < 2 || t.has_active_smartcast() {
        return none
    }
    lhs := c.edge(0)
    rhs := c.edge(1)
    variant_name, variant_module := t.sumtype_check_variant_name_cursor(rhs)
    if variant_name == '' {
        return none
    }
    variant_lookup_name := sum_type_variant_name_with_module(variant_module, variant_name)
    mut sumtype_name := t.generic_scan_sumtype_name_for_expr_cursor(lhs)
    mut lhs_is_enum := t.get_enum_type_name_cursor(lhs) != ''
    if lhs_type := t.get_expr_type_cursor(lhs) {
        lhs_base := t.unwrap_alias_and_pointer_type(lhs_type)
        lhs_is_enum = lhs_is_enum || lhs_base is types.Enum
    }
    rhs_is_type_like := variant_name.len > 0 && variant_name[0] >= `A` && variant_name[0] <= `Z`
    if sumtype_name == '' && !lhs_is_enum && !cursor_is_enum_shorthand_selector(rhs)
        && (op in [.key_is, .not_is] || rhs_is_type_like) {
        sumtype_name = t.find_sumtype_for_variant(variant_lookup_name)
    }
    if sumtype_name == '' {
        if result_id := t.transform_interface_self_type_check_cursor_to_flat(lhs, variant_name, op,
            c.pos(), mut out)
        {
            return result_id
        }
        return none
    }
    variants := t.get_sum_type_variants(sumtype_name)
    mut tag_value := -1
    for i, variant in variants {
        if sum_type_variant_matches_for_sumtype(sumtype_name, variant, variant_lookup_name) {
            tag_value = i
            break
        }
    }
    if tag_value < 0 {
        return none
    }
    lhs_id := t.transform_expr_cursor_to_flat(lhs, mut out)
    tag_id := t.synth_selector_cursor_to_flat(lhs_id, '_tag', types.Type(types.int_), mut out)
    tag_value_id := out.emit_basic_literal_by_value(.number, tag_value.str(), c.pos())
    cmp_op := if op in [.key_is, .eq] { token.Token.eq } else { token.Token.ne }
    return out.emit_infix_expr_by_ids(cmp_op, tag_id, tag_value_id, c.pos())
}

fn (t &Transformer) scalar_equality_type_can_transform_direct(typ types.Type) bool {
    if t.type_is_string(typ) {
        return false
    }
    base := t.unwrap_alias_type(typ)
    return match base {
        types.Primitive, types.Char, types.ISize, types.Nil, types.Pointer, types.Rune,
        types.USize {
            true
        }
        else {
            false
        }
    }
}

fn (t &Transformer) infix_equality_cursor_can_transform_direct(c ast.Cursor) bool {
    lhs := c.edge(0)
    rhs := c.edge(1)
    if cursor_is_enum_shorthand_selector(lhs) || cursor_is_enum_shorthand_selector(rhs) {
        return false
    }
    lhs_type := t.get_expr_type_cursor(lhs) or { return false }
    rhs_type := t.get_expr_type_cursor(rhs) or { return false }
    return t.scalar_equality_type_can_transform_direct(lhs_type)
        && t.scalar_equality_type_can_transform_direct(rhs_type)
}

fn (t &Transformer) is_nil_expr_cursor(c ast.Cursor) bool {
    return match c.kind() {
        .expr_ident {
            c.name() == 'nil'
        }
        .expr_keyword {
            unsafe { token.Token(int(c.aux())) } == .key_nil
        }
        .typ_nil {
            true
        }
        .expr_basic_literal {
            unsafe { token.Token(int(c.aux())) } == .number && c.name() == '0'
        }
        .expr_paren, .expr_cast, .expr_modifier {
            c.edge_count() > 0 && t.is_nil_expr_cursor(c.edge(0))
        }
        else {
            false
        }
    }
}

fn cursor_is_c_string_literal(c ast.Cursor) bool {
    return match c.kind() {
        .expr_string {
            unsafe { ast.StringLiteralKind(int(c.aux())) } == .c
        }
        .expr_paren, .expr_modifier {
            c.edge_count() > 0 && cursor_is_c_string_literal(c.edge(0))
        }
        else {
            false
        }
    }
}

fn cursor_is_foldable_v_string_literal(c ast.Cursor) bool {
    return match c.kind() {
        .expr_string {
            unsafe { ast.StringLiteralKind(int(c.aux())) } == .v
        }
        .expr_paren {
            c.edge_count() > 0 && cursor_is_foldable_v_string_literal(c.edge(0))
        }
        else {
            false
        }
    }
}

fn (t &Transformer) is_v_string_expr_cursor(c ast.Cursor) bool {
    return !cursor_is_c_string_literal(c) && t.is_string_expr_cursor(c)
}

fn (t &Transformer) infix_string_compare_cursor_can_transform_direct(c ast.Cursor, op token.Token) bool {
    if op !in [.eq, .ne, .lt, .gt, .le, .ge] || c.edge_count() < 2 {
        return false
    }
    lhs := c.edge(0)
    rhs := c.edge(1)
    return !t.is_nil_expr_cursor(lhs) && !t.is_nil_expr_cursor(rhs)
        && t.is_v_string_expr_cursor(lhs) && t.is_v_string_expr_cursor(rhs)
}

fn (mut t Transformer) string_compare_call_cursor_to_flat(name string, first ast.Cursor, second ast.Cursor, pos token.Pos, mut out ast.FlatBuilder) ast.FlatNodeId {
    lhs_id := out.emit_ident_by_name(name, token.Pos{})
    first_id := t.transform_expr_cursor_to_flat(first, mut out)
    second_id := t.transform_expr_cursor_to_flat(second, mut out)
    return out.emit_call_expr_by_ids(lhs_id, [first_id, second_id], pos)
}

fn (mut t Transformer) transform_string_compare_cursor_to_flat(c ast.Cursor, op token.Token, mut out ast.FlatBuilder) ?ast.FlatNodeId {
    if !t.infix_string_compare_cursor_can_transform_direct(c, op) {
        return none
    }
    lhs := c.edge(0)
    rhs := c.edge(1)
    match op {
        .eq {
            return t.string_compare_call_cursor_to_flat('string__eq', lhs, rhs, c.pos(), mut out)
        }
        .ne {
            call_id :=
                t.string_compare_call_cursor_to_flat('string__eq', lhs, rhs, c.pos(), mut out)
            return out.emit_prefix_expr_by_id(.not, call_id, c.pos())
        }
        .lt {
            return t.string_compare_call_cursor_to_flat('string__lt', lhs, rhs, c.pos(), mut out)
        }
        .gt {
            return t.string_compare_call_cursor_to_flat('string__lt', rhs, lhs, c.pos(), mut out)
        }
        .le {
            call_id :=
                t.string_compare_call_cursor_to_flat('string__lt', rhs, lhs, c.pos(), mut out)
            return out.emit_prefix_expr_by_id(.not, call_id, c.pos())
        }
        .ge {
            call_id :=
                t.string_compare_call_cursor_to_flat('string__lt', lhs, rhs, c.pos(), mut out)
            return out.emit_prefix_expr_by_id(.not, call_id, c.pos())
        }
        else {
            return none
        }
    }
}

fn (t &Transformer) infix_string_concat_cursor_can_transform_direct(c ast.Cursor, op token.Token) bool {
    if op != .plus || c.edge_count() < 2 {
        return false
    }
    lhs := c.edge(0)
    rhs := c.edge(1)
    if lhs.kind() == .expr_infix || rhs.kind() == .expr_infix {
        return false
    }
    if cursor_is_foldable_v_string_literal(lhs) && cursor_is_foldable_v_string_literal(rhs) {
        return false
    }
    return t.is_v_string_expr_cursor(lhs) && t.is_v_string_expr_cursor(rhs)
}

fn (mut t Transformer) transform_string_concat_cursor_to_flat(c ast.Cursor, op token.Token, mut out ast.FlatBuilder) ?ast.FlatNodeId {
    if !t.infix_string_concat_cursor_can_transform_direct(c, op) {
        return none
    }
    lhs_id := out.emit_ident_by_name('string__plus', token.Pos{})
    left_id := t.transform_expr_cursor_to_flat(c.edge(0), mut out)
    right_id := t.transform_expr_cursor_to_flat(c.edge(1), mut out)
    return out.emit_call_expr_by_ids(lhs_id, [left_id, right_id], c.pos())
}

fn (mut t Transformer) transform_range_membership_cursor_to_flat(c ast.Cursor, op token.Token, mut out ast.FlatBuilder) ?ast.FlatNodeId {
    if op !in [.key_in, .not_in] || c.edge_count() < 2 {
        return none
    }
    lhs := c.edge(0)
    range := c.edge(1)
    if !range.is_valid() || range.kind() != .expr_range || range.edge_count() < 2 {
        return none
    }
    lhs_id := t.transform_expr_cursor_to_flat(lhs, mut out)
    start_id := t.transform_expr_cursor_to_flat(range.edge(0), mut out)
    lower_id := out.emit_infix_expr_by_ids(.ge, lhs_id, start_id, c.pos())
    mut range_check_id := lower_id
    end := range.edge(1)
    if end.is_valid() && end.kind() != .expr_empty {
        range_op := unsafe { token.Token(int(range.aux())) }
        upper_op := if range_op == .dotdot { token.Token.lt } else { token.Token.le }
        end_id := t.transform_expr_cursor_to_flat(end, mut out)
        upper_id := out.emit_infix_expr_by_ids(upper_op, lhs_id, end_id, c.pos())
        range_check_id = out.emit_infix_expr_by_ids(.and, lower_id, upper_id, c.pos())
    }
    if op == .not_in {
        return out.emit_prefix_expr_by_id(.not, range_check_id, c.pos())
    }
    return range_check_id
}

fn (mut t Transformer) transform_inline_array_membership_elem_cursor_to_flat(elem ast.Cursor, enum_type string, mut out ast.FlatBuilder) ast.FlatNodeId {
    if enum_type != '' {
        if enum_id := t.enum_shorthand_cursor_to_flat(elem, enum_type, mut out) {
            return enum_id
        }
    }
    return t.transform_expr_cursor_to_flat(elem, mut out)
}

fn (mut t Transformer) transform_inline_array_membership_cursor_to_flat(c ast.Cursor, op token.Token, mut out ast.FlatBuilder) ?ast.FlatNodeId {
    if op !in [.key_in, .not_in] || c.edge_count() < 2 {
        return none
    }
    lhs := c.edge(0)
    rhs := c.edge(1)
    if !rhs.is_valid() || rhs.kind() != .expr_array_init || rhs.edge_count() <= 5 {
        return none
    }
    enum_type := t.get_enum_type_name_cursor(lhs)
    lhs_id := t.transform_expr_cursor_to_flat(lhs, mut out)
    first_elem_id := t.transform_inline_array_membership_elem_cursor_to_flat(rhs.edge(5),
        enum_type, mut out)
    mut chain_id := out.emit_infix_expr_by_ids(.eq, lhs_id, first_elem_id, c.pos())
    for i in 6 .. rhs.edge_count() {
        elem_id :=
            t.transform_inline_array_membership_elem_cursor_to_flat(rhs.edge(i), enum_type,