bugc: add code contexts with source ranges to compiler-generated instructions

Add source location info (loc, sourceId) to Ir.Function so EVM
codegen can build code contexts for compiler-generated instructions.

Instructions that map to a source location now use gather contexts
combining both a remark (for debugger tooling) and a code context
(for source highlighting):
- Free memory pointer init → code block / create block range
- Function prologue (param stores, return PC save) → function decl range
- STOP guard → code block range

Deployment wrapper remains remark-only (no corresponding source).
Return value spill already had correct source mapping (call expr).

Author: gnidan

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

@@ -2,6 +2,7 @@
  * Block-level code generation
  */
 
+import type * as Ast from "#ast";
 import type * as Format from "@ethdebug/format";
 import * as Ir from "#ir";
 import type { Stack } from "#evm";
@@ -47,9 +48,13 @@ export function generate<S extends Stack>(
 
       // Initialize memory for first block
       if (isFirstBlock) {
-        // Always initialize the free memory pointer for consistency
-        // This ensures dynamic allocations start after static ones
-        result = result.then(initializeMemory(state.memory.nextStaticOffset));
+        const sourceInfo =
+          func?.sourceId && func?.loc
+            ? { sourceId: func.sourceId, loc: func.loc }
+            : undefined;
+        result = result.then(
+          initializeMemory(state.memory.nextStaticOffset, sourceInfo),
+        );
       }
 
       // Set JUMPDEST for non-first blocks
@@ -215,18 +220,34 @@ function generatePhi<S extends Stack>(
 
 /**
  * Initialize the free memory pointer at runtime
- * Sets the value at 0x40 to the next available memory location after static allocations
+ * Sets the value at 0x40 to the next available memory location
+ * after static allocations
  */
 function initializeMemory<S extends Stack>(
   nextStaticOffset: number,
+  sourceInfo?: { sourceId: string; loc: Ast.SourceLocation },
 ): Transition<S, S> {
   const { PUSHn, MSTORE } = operations;
 
-  const debug = {
-    context: {
-      remark: "initialize free memory pointer",
-    },
-  };
+  const debug = sourceInfo
+    ? {
+        context: {
+          gather: [
+            { remark: "initialize free memory pointer" },
+            {
+              code: {
+                source: { id: sourceInfo.sourceId },
+                range: sourceInfo.loc,
+              },
+            },
+          ],
+        } as Format.Program.Context,
+      }
+    : {
+        context: {
+          remark: "initialize free memory pointer",
+        } as Format.Program.Context,
+      };
 
   return pipe<S>()
     .then(PUSHn(BigInt(nextStaticOffset), { debug }), {

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

@@ -71,11 +71,28 @@ function generatePrologue<S extends Stack>(
     // Return PC is already in memory at 0x60 (stored by caller)
     // Pop and store each arg from argN down to arg0
 
-    const prologueDebug = {
-      context: {
-        remark: `prologue: store ${params.length} parameter(s) to memory`,
-      },
-    };
+    const prologueDebug =
+      func.sourceId && func.loc
+        ? {
+            context: {
+              gather: [
+                {
+                  remark: `prologue: store ${params.length} parameter(s) to memory`,
+                },
+                {
+                  code: {
+                    source: { id: func.sourceId },
+                    range: func.loc,
+                  },
+                },
+              ],
+            } as Format.Program.Context,
+          }
+        : {
+            context: {
+              remark: `prologue: store ${params.length} parameter(s) to memory`,
+            } as Format.Program.Context,
+          };
 
     for (let i = params.length - 1; i >= 0; i--) {
       const param = params[i];
@@ -117,11 +134,28 @@ function generatePrologue<S extends Stack>(
     // so nested function calls don't clobber it.
     const savedPcOffset = currentState.memory.savedReturnPcOffset;
     if (savedPcOffset !== undefined) {
-      const savePcDebug = {
-        context: {
-          remark: `prologue: save return PC to 0x${savedPcOffset.toString(16)}`,
-        },
-      };
+      const savePcDebug =
+        func.sourceId && func.loc
+          ? {
+              context: {
+                gather: [
+                  {
+                    remark: `prologue: save return PC to 0x${savedPcOffset.toString(16)}`,
+                  },
+                  {
+                    code: {
+                      source: { id: func.sourceId },
+                      range: func.loc,
+                    },
+                  },
+                ],
+              } as Format.Program.Context,
+            }
+          : {
+              context: {
+                remark: `prologue: save return PC to 0x${savedPcOffset.toString(16)}`,
+              } as Format.Program.Context,
+            };
       const highByte = (savedPcOffset >> 8) & 0xff;
       const lowByte = savedPcOffset & 0xff;
       currentState = {

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

@@ -105,17 +105,35 @@ export function generate(
   // Insert STOP between main and user functions to prevent
   // fall-through when the main function's last block omits
   // STOP (the isLastBlock optimization).
+  const stopGuardDebug =
+    module.main.sourceId && module.main.loc
+      ? {
+          context: {
+            gather: [
+              {
+                remark: "guard: prevent fall-through into functions",
+              },
+              {
+                code: {
+                  source: { id: module.main.sourceId },
+                  range: module.main.loc,
+                },
+              },
+            ],
+          },
+        }
+      : {
+          context: {
+            remark: "guard: prevent fall-through into functions",
+          },
+        };
   const stopGuard: Evm.Instruction[] =
     patchedFunctions.length > 0
       ? [
           {
             mnemonic: "STOP" as const,
             opcode: 0x00,
-            debug: {
-              context: {
-                remark: "guard: prevent fall-through into functions",
-              },
-            },
+            debug: stopGuardDebug,
           },
         ]
       : [];

packages/bugc/src/ir/spec/function.ts

@@ -17,6 +17,10 @@ export interface Function {
   blocks: Map<string, Block>;
   /** SSA variable metadata mapping temp IDs to original variables */
   ssaVariables?: Map<string, Function.SsaVariable>;
+  /** Source location of the function body */
+  loc?: Ast.SourceLocation;
+  /** Source identifier for debug info */
+  sourceId?: string;
 }
 
 export namespace Function {

packages/bugc/src/irgen/generate/function.ts

@@ -46,12 +46,16 @@ export function* buildFunction(
   // Collect SSA variable metadata
   const ssaVariables = yield* Process.Functions.collectSsaMetadata();
 
+  const module_ = yield* Process.Modules.current();
+
   const function_: Ir.Function = {
     name,
     parameters: params,
     entry: "entry",
     blocks,
     ssaVariables: ssaVariables.size > 0 ? ssaVariables : undefined,
+    loc: body.loc ?? undefined,
+    sourceId: module_.sourceId,
   };
 
   return function_;