Add transform context for annotating compiler optimizations (#216)

* format: add the transform context for compiler optimizations

Introduce the `transform` context: a flat sibling key on an instruction
listing the optimization passes (fold, coalesce, tailcall, inline) the
compiler applied to it, so a debugger can distinguish
compiler-synthesized code from the source the user wrote.

Adds the schema, the format TypeScript type, and the spec page, and
registers the context page in the docs schema index.

* tailcall: emit, render, and document the tail-call transform

Emit `transform: ["tailcall"]` on the TCO back-edge JUMP, alongside the
invoke/return pair it already carries, so a debugger sees the pair as a
tail-call-optimized back-edge rather than a real frame push/pop and does
not invent a spurious frame.

Render it in the tracer drawer — an optimizer-level (O0-O3) selector and a
tail-call-aware call stack — and document it with a tracing example and a
walkthrough homed in the trace playground.

Introduces the shared `Ir.Utils.addTransform` helper — the fold, coalesce,
and inline emitters all route through it — and the transform-emission test
file (`transform-contexts.test.ts`, with the `countTransform` helper),
covering the tailcall marker: absent at O0/O1, present at O2/O3.

* bugc: emit the fold transform on constant folding

Mark constant-folded values with `transform: ["fold"]` through a shared
`addTransform` helper, so the tracer can show a value as a
compile-time-evaluated constant rather than source. The marker composes
with later passes into a multiset (e.g. `["fold", "coalesce"]`).

* bugc: emit the coalesce transform on read-write merging

Mark the SHL/OR field-packing sequence produced by read-write merging
with `transform: ["coalesce"]`, so a packed-storage write reads as
compiler-synthesized rather than source the user wrote. Composes with a
folded value into `["fold", "coalesce"]`.

* inline: spec, compiler pass, tracer reconstruction, and examples

Add the function-inlining transform end to end:

- spec the inlined-call virtual-activation contract — push/pop pairing
  via the virtual invoke/return versus the per-instruction `inline`
  membership marker;
- add the bugc inlining pass (level 2): splice eligible leaf callees into
  their call sites, emit `transform: ["inline"]` on the spliced body, and
  bracket it with a virtual invoke/return; bracket those boundary ops in
  evmgen so the activation nests correctly;
- reconstruct the inline virtual activations in the tracer's call stack;
- add the inlining showcase examples and the trace-playground section.

* format: correlate activations with an activation identifier

Correlate activations with an `activation` identifier on invoke, return,
and revert: the invoke that opens an activation and the return or revert
that closes it carry the same value, so a debugger pairs a call with its
return independent of trace order. It lives inside the
invoke/return/revert object, keeping a tail call's two facts flat without
a `gather`.

* web: surface optimizer transforms in the tracer instruction list

Show the tailcall and inline transform annotations inline in the tracer's
instruction list, so the optimizer passes applied to each instruction are
visible as you step through the trace.

Author: gnidan

packages/bugc/src/evmgen/generation/block.ts

@@ -14,6 +14,7 @@ import { Memory } from "#evmgen/analysis";
 import { calculateSize } from "#evmgen/serialize";
 
 import * as Instruction from "./instruction.js";
+import { bracketActivation, carriesActivation } from "./bracket-activation.js";
 import { loadValue } from "./values/index.js";
 import {
   generateTerminator,
@@ -161,9 +162,31 @@ export function generate<S extends Stack>(
       // the runtime predecessor differs from the layout-order
       // predecessor.
 
-      // Process regular instructions
+      // Process regular instructions. Invoke/return activation
+      // discriminators must be bracketed to the first/last emitted op
+      // of the instruction (see bracket-activation.ts); everything else
+      // (source mapping, variables, transform markers) rides all ops.
       for (const inst of block.instructions) {
-        result = result.then(Instruction.generate(inst));
+        const gen = Instruction.generate(inst);
+        const operationCtx = inst.operationDebug?.context;
+        if (
+          !carriesActivation(operationCtx, "invoke") &&
+          !carriesActivation(operationCtx, "return")
+        ) {
+          result = result.then(gen);
+          continue;
+        }
+        result = result.peek((state, builder) => {
+          const start = state.instructions.length;
+          return builder.then(gen).then((s) => ({
+            ...s,
+            instructions: bracketActivation(
+              s.instructions,
+              start,
+              operationCtx,
+            ),
+          }));
+        });
       }
 
       // Emit phi copies for successor blocks before the

packages/bugc/src/evmgen/generation/bracket-activation.ts

@@ -0,0 +1,164 @@
+/**
+ * Bracket invoke/return activation discriminators onto the boundary
+ * ops of an IR instruction's emitted op-run.
+ *
+ * A single IR instruction lowers to N EVM micro-ops, and the generic
+ * lowering attaches that instruction's whole `operationDebug` (source
+ * mapping, variables, transform markers, AND any invoke/return
+ * discriminators) to every one of those ops. That is correct for
+ * source/variable/transform context — a debugger wants all N ops
+ * mapped to the instruction — but WRONG for invoke/return: those are
+ * positional activation boundaries. An `invoke` marks a single push
+ * point; a `return` a single pop point. Broadcasting them across the
+ * whole op-run makes a push/pop reconstruction see every op as both a
+ * push and a pop.
+ *
+ * This module de-smears: for the ops emitted by one instruction, the
+ * `invoke` discriminator is kept on only the FIRST op, `return` on only
+ * the LAST op, and stripped from the interior. The `transform`
+ * membership markers (and source/variables) stay on every op.
+ *
+ * It is a general evmgen invariant, not inline-specific: it is a no-op
+ * for real calls (whose invoke/return already ride single-op JUMP /
+ * JUMPDEST terminators) and fires only when invoke/return happen to
+ * ride a multi-op instruction — which today is inlined virtual
+ * activations.
+ */
+import type * as Format from "@ethdebug/format";
+import type * as Evm from "#evm";
+
+type Ctx = Format.Program.Context;
+type Activation = "invoke" | "return";
+
+function isPick(ctx: Ctx): ctx is Ctx & { pick: Ctx[] } {
+  return (
+    typeof ctx === "object" &&
+    ctx !== null &&
+    "pick" in ctx &&
+    Array.isArray((ctx as { pick: unknown }).pick)
+  );
+}
+
+function isGather(ctx: Ctx): ctx is Ctx & { gather: Ctx[] } {
+  return (
+    typeof ctx === "object" &&
+    ctx !== null &&
+    "gather" in ctx &&
+    Array.isArray((ctx as { gather: unknown }).gather)
+  );
+}
+
+/** Whether ctx carries the given activation key anywhere, reaching
+ * into pick/gather composites. */
+export function carriesActivation(
+  ctx: Ctx | undefined,
+  key: Activation,
+): boolean {
+  if (!ctx || typeof ctx !== "object") return false;
+  if (isPick(ctx)) return ctx.pick.some((c) => carriesActivation(c, key));
+  if (isGather(ctx)) return ctx.gather.some((c) => carriesActivation(c, key));
+  return key in ctx;
+}
+
+/** The first activation value found for the given key, reaching into
+ * pick/gather composites. */
+function findActivation(ctx: Ctx | undefined, key: Activation): unknown {
+  if (!ctx || typeof ctx !== "object") return undefined;
+  if (isPick(ctx)) {
+    for (const c of ctx.pick) {
+      const v = findActivation(c, key);
+      if (v !== undefined) return v;
+    }
+    return undefined;
+  }
+  if (isGather(ctx)) {
+    for (const c of ctx.gather) {
+      const v = findActivation(c, key);
+      if (v !== undefined) return v;
+    }
+    return undefined;
+  }
+  return (ctx as Record<string, unknown>)[key];
+}
+
+/** Remove invoke and return discriminators anywhere in ctx, reaching
+ * into pick/gather composites. Returns undefined if nothing remains. */
+export function stripActivation(ctx: Ctx | undefined): Ctx | undefined {
+  if (!ctx || typeof ctx !== "object") return ctx;
+  if (isPick(ctx)) {
+    const kids = ctx.pick
+      .map(stripActivation)
+      .filter((c): c is Ctx => c !== undefined);
+    if (kids.length === 0) return undefined;
+    if (kids.length === 1) return kids[0];
+    return { pick: kids } as Ctx;
+  }
+  if (isGather(ctx)) {
+    const kids = ctx.gather
+      .map(stripActivation)
+      .filter((c): c is Ctx => c !== undefined);
+    if (kids.length === 0) return undefined;
+    if (kids.length === 1) return kids[0];
+    return { gather: kids } as Ctx;
+  }
+  const rest = { ...(ctx as Record<string, unknown>) };
+  delete rest.invoke;
+  delete rest.return;
+  return Object.keys(rest).length > 0 ? (rest as Ctx) : undefined;
+}
+
+/** Attach an activation discriminator, composing it as a flat sibling
+ * key on a leaf context (per the flat-composition convention), or
+ * appending it to a pick/gather composite. */
+function attachActivation(
+  ctx: Ctx | undefined,
+  key: Activation,
+  value: unknown,
+): Ctx {
+  const marker = { [key]: value } as Ctx;
+  if (!ctx || typeof ctx !== "object") return marker;
+  if (isPick(ctx)) return { pick: [...ctx.pick, marker] } as Ctx;
+  if (isGather(ctx)) return { gather: [...ctx.gather, marker] } as Ctx;
+  return { ...(ctx as Record<string, unknown>), [key]: value } as Ctx;
+}
+
+/**
+ * Rewrite the ops emitted by one IR instruction (the tail slice
+ * `instructions[start..]`) so invoke rides only the first op and
+ * return only the last op, using the discriminators found on the
+ * instruction's `operationDebug` context. No-op unless that context
+ * carries invoke and/or return, so it never touches ordinary code.
+ */
+export function bracketActivation(
+  instructions: Evm.Instruction[],
+  start: number,
+  operationCtx: Ctx | undefined,
+): Evm.Instruction[] {
+  const end = instructions.length; // exclusive
+  if (end <= start) return instructions;
+
+  const hasInvoke = carriesActivation(operationCtx, "invoke");
+  const hasReturn = carriesActivation(operationCtx, "return");
+  if (!hasInvoke && !hasReturn) return instructions;
+
+  const invokeValue = hasInvoke
+    ? findActivation(operationCtx, "invoke")
+    : undefined;
+  const returnValue = hasReturn
+    ? findActivation(operationCtx, "return")
+    : undefined;
+
+  const out = instructions.slice();
+  for (let i = start; i < end; i++) {
+    const op = out[i];
+    let ctx = stripActivation(op.debug?.context);
+    if (hasInvoke && i === start) {
+      ctx = attachActivation(ctx, "invoke", invokeValue);
+    }
+    if (hasReturn && i === end - 1) {
+      ctx = attachActivation(ctx, "return", returnValue);
+    }
+    out[i] = { ...op, debug: { ...op.debug, context: ctx } };
+  }
+  return out;
+}

packages/bugc/src/evmgen/generation/control-flow/terminator.ts

@@ -1,5 +1,6 @@
 import type * as Format from "@ethdebug/format";
 import type * as Ir from "#ir";
+import { Utils as IrUtils } from "#ir";
 import type * as Evm from "#evm";
 import type { Stack } from "#evm";
 import type { State } from "#evmgen/state";
@@ -411,17 +412,25 @@ function generateReturnEpilogue<S extends Stack>(
 /**
  * Build JUMP instruction options for a TCO-replaced tail call.
  *
- * The JUMP carries BOTH discriminators on a single flat
- * context object:
+ * The JUMP carries three keys on a single flat context
+ * object:
  *   - return: the previous iteration's return
  *   - invoke: the new iteration's call
+ *   - transform: ["tailcall"]
  *
  * Semantically the debugger sees frame depth stay constant
  * across the back-edge JUMP: the previous frame pops, the
  * new one pushes, on the same instruction. The function's
  * terminal RETURN (elsewhere) emits a return context
  * normally, popping the final iteration's frame.
  *
+ * The `transform: ["tailcall"]` key is an additive
+ * annotation: it does not replace the invoke/return pair
+ * (which state the source-level facts) but tells debuggers
+ * the pair was realized as a TCO back-edge rather than a
+ * real frame push/pop, so they can avoid inventing a
+ * spurious frame.
+ *
  * The invoke mirrors the normal caller-JUMP invoke
  * (identity + declaration + code target, no argument
  * pointers). The return omits `data` because TCO does not
@@ -432,7 +441,7 @@ function generateReturnEpilogue<S extends Stack>(
  * resolved later by patchInvokeTarget.
  */
 function buildTailCallJumpOptions(tailCall: Ir.Block.TailCall): {
-  debug: { context: Format.Program.Context };
+  debug: Ir.Instruction.Debug;
 } {
   const declaration =
     tailCall.declarationLoc && tailCall.declarationSourceId
@@ -462,7 +471,16 @@ function buildTailCallJumpOptions(tailCall: Ir.Block.TailCall): {
     },
   };
 
-  return { debug: { context: combined as Format.Program.Context } };
+  // Route through the shared helper so all transform emission
+  // (fold/tailcall/coalesce/...) composes consistently: the
+  // `transform` marker becomes a flat sibling key appended to
+  // any existing transform array.
+  return {
+    debug: IrUtils.addTransform(
+      { context: combined as Format.Program.Context },
+      "tailcall",
+    ),
+  };
 }
 
 /** PUSH an integer as the smallest PUSHn. */