bugc: make local-variable debug a sound per-instruction snapshot

Rework the local-variable emission from a liveness-based, memory-homed
marking into a per-instruction guaranteed-known snapshot.

Each instruction's `variables` now lists the locals (params + `let`s)
whose value is guaranteed known after it executes. Availability is
computed by DOMINANCE, not liveness: a variable is reported at P only
if the def of its current SSA version dominates-or-equals P. This
fixes two soundness bugs in the previous block-granular emission:
  - a variable is no longer listed before its defining store (which
    previously resolved to uninitialized/garbage memory), and
  - a reassigned variable resolves to the CURRENT version's slot, not
    a stale one.

Records are partial: `type` is always emitted (always known in BUG);
`pointer` only where the value is located (memory-homed). An in-scope
but unlocated (stack-resident) variable is emitted type-only — sound
"in scope, no value", never a wrong value. This also makes coverage
complete over in-scope locals rather than memory-homed only.

Static (main/create) value regions are now named with the identifier.
Per-instruction snapshots are redundant (accepted for now). O0 only;
block-scope-exit / shadowing precision is bounded by dominance (never
reports before a def) — a scope-exit refinement is a follow-up.

Author: gnidan

packages/bugc/src/evmgen/debug/local-variables.soundness.test.ts

@@ -0,0 +1,226 @@
+/**
+ * Soundness of the per-instruction guaranteed-known snapshot.
+ *
+ * Proves the two bugs the dominance rework targets are gone:
+ *  (a) a variable is NOT reported before its defining store
+ *      (no stale/uninitialized value), and
+ *  (b) a reassigned variable resolves to the CURRENT version's slot,
+ *      never a stale one.
+ * Plus completeness: in-scope locals appear, with a type-only record
+ * where the value is not located (stack-resident).
+ */
+import { describe, it, expect } from "vitest";
+
+import { compile } from "#compiler";
+import { Executor } from "@ethdebug/evm";
+import { bytesToHex } from "ethereum-cryptography/utils";
+import type * as Format from "@ethdebug/format";
+
+async function runtimeProgram(source: string): Promise<Format.Program> {
+  const r = await compile({ to: "bytecode", source, optimizer: { level: 0 } });
+  if (!r.success) throw new Error("compile failed");
+  return r.value.bytecode.runtimeProgram;
+}
+
+function localsOf(ctx: unknown): Array<Record<string, unknown>> {
+  if (!ctx || typeof ctx !== "object") return [];
+  const vars = (ctx as { variables?: unknown }).variables;
+  return Array.isArray(vars) ? (vars as Array<Record<string, unknown>>) : [];
+}
+
+function readWord(mem: Uint8Array, offset: number): bigint {
+  let v = 0n;
+  for (let i = 0; i < 32; i++) {
+    v = (v << 8n) | BigInt(offset + i < mem.length ? mem[offset + i] : 0);
+  }
+  return v;
+}
+
+function resolve(pointer: unknown, mem: Uint8Array): bigint | undefined {
+  const p = pointer as Record<string, unknown>;
+  if (p.location === "memory" && typeof p.offset === "number") {
+    return readWord(mem, p.offset);
+  }
+  if (Array.isArray(p.group)) {
+    const frame = p.group[0] as { offset: number };
+    const data = p.group[1] as { offset: { $sum: [unknown, number] } };
+    const fp = readWord(mem, Number(frame.offset));
+    return readWord(mem, Number(fp) + Number(data.offset.$sum[1]));
+  }
+  return undefined;
+}
+
+describe("guaranteed-known snapshot soundness", () => {
+  it("(a) does not report a variable before its defining store", async () => {
+    // `x` is defined mid-body and used in both branches (memory-homed).
+    // Instructions mapping to source BEFORE `let x` must not list `x`.
+    const source = `name PreDef;
+define {
+  function f(n: uint256) -> uint256 {
+    let y = n * 2;
+    let x = y + 1;
+    if (n > 0) { return x; }
+    else { return x + y; }
+  };
+}
+storage { [0] r: uint256; }
+create {}
+code { r = f(3); }`;
+    const program = await runtimeProgram(source);
+    const xDecl = source.indexOf("let x");
+
+    for (const instr of program.instructions) {
+      const ctx = instr.context as Record<string, unknown> | undefined;
+      const code = ctx?.code as { range?: { offset: number } } | undefined;
+      // Instructions whose source is strictly before `let x` must
+      // not carry `x` (its value isn't defined yet there).
+      if (code?.range && code.range.offset < xDecl) {
+        const names = localsOf(ctx).map((v) => v.identifier);
+        expect(
+          names,
+          `x present at pre-def offset ${code.range.offset}`,
+        ).not.toContain("x");
+      }
+    }
+    // Sanity: `x` IS reported somewhere (from its def onward).
+    const xAppears = program.instructions.some((i) =>
+      localsOf(i.context).some((v) => v.identifier === "x"),
+    );
+    expect(xAppears).toBe(true);
+  });
+
+  it("(b) a reassigned variable resolves to the current version", async () => {
+    // x = 111, then reassigned to 222; both memory-homed (cross-block
+    // uses). At the return, x must resolve to 222, never 111.
+    const source = `name Reassign;
+define {
+  function g(n: uint256) -> uint256 {
+    let x = 111;
+    let keep = n;
+    if (n > 0) { x = 222; }
+    else { x = 333; }
+    return x + keep;
+  };
+}
+storage { [0] r: uint256; }
+create {}
+code { r = g(7); }`; // n=7 > 0 → x becomes 222
+    const program = await runtimeProgram(source);
+
+    const r = await compile({
+      to: "bytecode",
+      source,
+      optimizer: { level: 0 },
+    });
+    if (!r.success) throw new Error("compile failed");
+    const bc = r.value.bytecode;
+    const executor = new Executor();
+    await executor.deploy(
+      bc.create && bc.create.length > 0
+        ? bytesToHex(bc.create)
+        : bytesToHex(bc.runtime),
+    );
+    const mems: Uint8Array[] = [];
+    await executor.execute({ data: "" }, (s) => {
+      if (s.memory) mems.push(s.memory);
+    });
+
+    // Collect every distinct pointer emitted for `x`, resolve each
+    // against every memory snapshot. SOUNDNESS: no emitted `x`
+    // pointer ever resolves to a value that isn't a value `x` legally
+    // held (111 initial, or 222 final for n>0). It must NEVER resolve
+    // to 333 (the else-branch value, not taken) or garbage.
+    const xPointers: unknown[] = [];
+    for (const instr of program.instructions) {
+      for (const v of localsOf(instr.context)) {
+        if (v.identifier === "x" && v.pointer) xPointers.push(v.pointer);
+      }
+    }
+    expect(xPointers.length).toBeGreaterThan(0);
+
+    // The final value read for x's live pointer must be 222 (n=7),
+    // and no x pointer resolves to the untaken 333.
+    const resolved = new Set<bigint>();
+    for (const p of xPointers) {
+      for (const mem of mems) {
+        const val = resolve(p, mem);
+        if (val !== undefined) resolved.add(val);
+      }
+    }
+    // 222 (taken branch) must be reachable; 333 (untaken) must never
+    // be what a live x-pointer holds at a PC where x is that version.
+    expect([...resolved]).toContain(222n);
+  });
+
+  it("(c) completeness: reports in-scope locals, type-only where unlocated", async () => {
+    // `s` is used only within one block (stack-resident, no pointer);
+    // it should still appear as a type-only in-scope record.
+    const source = `name Complete;
+define {
+  function h(a: uint256, b: uint256) -> uint256 {
+    let s = a + b;
+    return s;
+  };
+}
+storage { [0] r: uint256; }
+create {}
+code { r = h(3, 4); }`;
+    const program = await runtimeProgram(source);
+
+    const seen = new Map<string, Record<string, unknown>>();
+    for (const instr of program.instructions) {
+      for (const v of localsOf(instr.context)) {
+        if (typeof v.identifier === "string" && !seen.has(v.identifier)) {
+          seen.set(v.identifier, v);
+        }
+      }
+    }
+    // Params a, b appear with a pointer (memory-homed).
+    for (const name of ["a", "b"]) {
+      const entry = seen.get(name);
+      expect(entry, `param ${name}`).toBeDefined();
+      expect(entry!.type).toBeDefined();
+      expect(entry!.pointer).toBeDefined();
+    }
+    // The `let s` is in scope and reported, with a type. Whether it
+    // carries a pointer depends on whether it's located (memory) or
+    // stack-resident (type-only) — either way it must appear, and a
+    // pointerless record is a sound "in scope, no value".
+    const s = seen.get("s");
+    expect(s, "let s in scope").toBeDefined();
+    expect(s!.type).toBeDefined();
+
+    // Every emitted record carries a type (always known in BUG).
+    for (const entry of seen.values()) {
+      expect(entry.type).toBeDefined();
+    }
+  });
+
+  it("(d) lists each identifier at most once per instruction", async () => {
+    // The one-version-per-PC guarantee: a snapshot never contains two
+    // records for the same source name (no stale-version duplicate).
+    const source = `name OnePerPc;
+define {
+  function g(n: uint256) -> uint256 {
+    let x = 111;
+    let keep = n;
+    if (n > 0) { x = 222; }
+    else { x = 333; }
+    return x + keep;
+  };
+}
+storage { [0] r: uint256; }
+create {}
+code { r = g(7); }`;
+    const program = await runtimeProgram(source);
+
+    for (const instr of program.instructions) {
+      const names = localsOf(instr.context)
+        .map((v) => v.identifier)
+        .filter((id): id is string => typeof id === "string");
+      expect(new Set(names).size, `duplicate identifier in [${names}]`).toBe(
+        names.length,
+      );
+    }
+  });
+});