bugc: preserve invoke/return contexts through optimizer

[gnidan]

Adds packages/bugc/src/evmgen/optimizer-contexts.test.ts — a suite that compiles the same source at levels 0, 1, 2, 3 and asserts:

• The bytecode still runs correctly end-to-end.
• Invoke contexts (caller JUMP + callee JUMPDEST) and return contexts (continuation JUMPDEST) are present with the expected identifiers.

Also updates bugc's tail call optimization pass to preserve invoke/return debug contexts, which the original test suite identified as a gap.

Coverage

Every pass that could touch call sites or returns:

• Level 1: constant folding, constant propagation, DCE
• Level 2: CSE, tail call optimization, jump optimization
• Level 3: block merging, return merging, read/write merging

Scenarios: simple call, constant-foldable args, multiple call sites, non-tail recursion, mutual recursion, nested calls, multiple returns of the same value (return-merging candidate), and tail-recursive call.

TCO debug context preservation

The TCO pass used to drop both invoke and return contexts on the recursive call — a deeply recursive program looked like one giant loop to the debugger and the logical call stack was lost.

Now the TCO back-edge JUMP carries a gather context with BOTH:

• return: the previous iteration's return
• invoke: the new iteration's call

Depth stays constant across the JUMP — one frame pops, one pushes, on the same instruction. The function's terminal RETURN pops the final iteration's frame normally. This models source-level semantics rather than the optimized control flow.

A future transform: tailcall marker will annotate these JUMPs as TCO-produced, letting debuggers optionally render the optimization-aware view.

Implementation:

• Adds Block.TailCall metadata to the jump terminator IR, populated by TCO when replacing a call terminator with a jump to the loop header.
• Jump codegen attaches a gather context (return + invoke) to the JUMP when tailCall metadata is present.
• patchInvokeTarget now walks gather contexts so the invoke leaf's placeholder code offset gets resolved from the function registry.

Findings from the optimizer survey

• All other passes preserve contexts. Return-merging and block-merging do not drop return contexts because those contexts are emitted at continuation JUMPDESTs (whose presence is driven by the IR call terminator, which these passes don't touch).
• No function inlining pass exists in bugc today, so no "inlined call loses its context" concern for the upcoming transform context design.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-04-16 07:48 UTC

[gnidan]

Review from architect (schema/format side).

gather-of-return-and-invoke: yes, semantically right

The "all contexts apply simultaneously" claim holds. Under
"following execution" semantics, after the back-edge JUMP both
facts are true: iteration N has returned, iteration N+1 has been
invoked. That's a conjunction, which is what gather means.

One subtlety worth noting in the commit message (not blocking):
there's an implicit ordering (return happens before invoke), but
gather expresses only conjunction, not sequence. That's fine —
the order is recoverable from the surrounding trace (prior
iteration's body preceded, new iteration's body follows) and the
future transform: tailcall marker will disambiguate further.
The gather construct itself doesn't need to encode order.

The shared machine state between the two contexts also works out:
the invoke has no argument pointers, and the stack layout at the
JUMP trace step is already the layout a normal callee-entry
JUMPDEST would see (return address + new args, destination
already popped). So the invoke's identity + target is accurate
for that state. No conflict.

stack slot 0 placeholder for return data: not OK, schema needs to change

This is the real issue. Per return.schema.yaml, data is
required:

required:
  - data

And per the TS types, data: Function.PointerRef is non-optional.
The PR satisfies the constraint by pointing at stack slot 0, but
at a TCO back-edge JUMP slot 0 is the new iteration's first
argument (or the return address, depending on the setup) — not
the intermediate return value, which doesn't materialize. A
debugger that follows this pointer gets a wrong answer labeled as
the return value.

The right fix is making return.data optional, not working
around it at the bytecode level. Rationale:

1. TCO is a legitimate case where a return semantically happens
   but no value is observable at that point. The schema should
   admit this rather than force compilers to lie.
2. Precedent: revert.schema.yaml already makes reason and
   panic optional on the same grounds — "a bare revert: {} is
   permitted when the compiler knows a revert occurred but has
   no further detail."
3. Other legitimate use cases will emerge:
   • void functions (no return value to point at)
   • compiler-lost precision (return happened but tracking
     dropped)
   • optimized returns where the value lives in a register
     already consumed by the subsequent instruction

The change is small:

• schemas/program/context/function/return.schema.yaml: remove
  data from required.
• packages/format/src/types/program/context.ts: change
  data: Function.PointerRef to data?: Function.PointerRef
  and adjust the guard.
• Add a worked example to the schema for a no-data return.
• Update revert.mdx-style docs if applicable (probably the
  return doc page needs a mirror of revert's "Field optionality"
  section).

Once that lands, this PR can drop the stack-slot-0 placeholder
and emit just:

const returnCtx: Format.Program.Context.Return = {
  return: {
    identifier: tailCall.function,
    ...(declaration ? { declaration } : {}),
  },
};

Happy to open that schema change as a separate PR ahead of this
one landing, or bundle it in here — your call.

Other observations

Not blocking, but worth noting:

• The gather context's order is [returnCtx, invoke] in the
  code. Since gather is an unordered conjunction per its schema,
  this works either way, but putting return before invoke reads
  naturally ("pop, then push"). Good choice.
• A future transform: tailcall marker sitting alongside these
  two in the gather would be the ideal final shape. Design
  already leaves room for that.
• The patchInvokeTarget walking into gather contexts to resolve
  the invoke leaf is a good generalization — it means any
  composed context shape will work without special-casing TCO.

Approving the design direction. The data-optional schema fix is
the only substantive change needed before this should merge — the
current placeholder produces a subtly wrong debug trace.