format: add transform context for compiler optimizations

[gnidan]

Summary

Adds a new context type, transform, annotating instructions
with the compiler transformations that produced them. The value
is an array of short identifiers; the list may repeat the same
identifier when the transformation has been applied multiple
times (e.g., ["inline", "inline"] for doubly-inlined code).

Design

Role: additional annotation. A transform context does not
replace semantic contexts. When the compiler inlines a function,
the caller's debug info still carries invoke/return contexts
naming the inlined callee at the call boundary — so the
debugger's logical call stack reflects the source-level
structure. The transform context is additional information
telling the debugger how the call was realized.

Consumers that ignore transform contexts get a sound
source-level view from the invoke/return contexts alone.
Consumers that understand them can offer optimization-aware
presentations (collapsible inlined blocks, TCO-aware call
stacks, collapsed coalesce sequences, etc.).

v1 identifiers (based on bugc optimizer's audit):

• "inline" — marked instruction is part of an inlined function
  body; surrounding invoke/return contexts name the inlined
  callee.
• "tailcall" — marked instruction is a tail-call-optimized
  back-edge JUMP or continuation, where the call was realized
  without pushing/popping a full activation.
• "fold" — marked instruction carries the result of a
  compile-time constant fold (typically a PUSH replacing a
  compute sequence from source).
• "coalesce" — marked instruction is part of a read-write
  merging sequence (e.g., SHL/OR packing narrower fields into a
  wider word) the user did not explicitly write.

propagate was considered for v1 and deferred as borderline.

The identifier set is extensible. Debuggers unfamiliar with a
given identifier should preserve it as an opaque label. Order
in the array is not semantically significant — the multiset is
what matters.

Composing with other contexts

For instructions carrying transform alongside other contexts,
use gather. A TCO back-edge JUMP typically combines three
facts:

gather:
  - return: { identifier: "fact", declaration: { ... } }
  - invoke: { jump: true, identifier: "fact", target: { ... } }
  - transform: ["tailcall"]

The return and invoke state the source-level facts; the
transform explains how the compiler realized that pair as a
single JUMP.

Changes

• schemas/program/context/transform.schema.yaml — new schema.
• schemas/program/context.schema.yaml — wire into the if/$ref
  union.
• packages/format/src/types/program/context.ts —
  Context.Transform interface, isTransform guard, and
  Transform.Identifier union ("inline" | "tailcall" | "fold" | "coalesce" | (string & {})) preserving autocomplete
  for known values while allowing compiler-emitted extensions.
• packages/format/src/types/program/context.test.ts — register
  Context.isTransform in the schema guard test harness.
• packages/web/spec/program/context/transform.mdx — spec page
  covering role, v1 identifiers (with EVM-level examples for
  each), repetition/composition, and interaction with gather.

Test plan

• yarn build passes
• yarn test passes (new: transform guard test + schema
  validity/examples suites auto-pick up the new schema)
• yarn lint clean (only pre-existing warnings)
• Schema guard test exercises all 8 examples in
  transform.schema.yaml covering single identifiers and
  mixed combinations

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://ethdebug.github.io/format/pr-preview/pr-212/
Built to branch gh-pages at 2026-04-16 09:10 UTC. Preview will be ready when the GitHub Pages deployment is complete.