bugc: add debug contexts to all remaining unmapped bytecodes

Thread remark/code contexts through all compiler-generated
instructions that previously lacked debug info:

- Free memory pointer initialization (remark)
- Return value spill after call continuation (call expr source range)
- STOP guard between main and user functions (remark)
- Function prologue MSTORE for param storage (thread existing remark)
- Function prologue return PC save sequence (thread existing remark)
- Deployment wrapper CODECOPY+RETURN (remark)

All 82 instructions across runtime and create programs now
carry debug contexts (previously 22 were unmapped).

Author: gnidan

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

@@ -104,6 +104,7 @@ export function generate<S extends Stack>(
             predBlock.terminator.dest
           ) {
             const destId = predBlock.terminator.dest;
+            const spillDebug = predBlock.terminator.operationDebug;
             result = result.then(annotateTop(destId)).then((s) => {
               const allocation = s.memory.allocations[destId];
               if (!allocation) return s;
@@ -112,16 +113,25 @@ export function generate<S extends Stack>(
                 ...s,
                 instructions: [
                   ...s.instructions,
-                  { mnemonic: "DUP1" as const, opcode: 0x80 },
+                  {
+                    mnemonic: "DUP1" as const,
+                    opcode: 0x80,
+                    debug: spillDebug,
+                  },
                   {
                     mnemonic: "PUSH2" as const,
                     opcode: 0x61,
                     immediates: [
                       (allocation.offset >> 8) & 0xff,
                       allocation.offset & 0xff,
                     ],
+                    debug: spillDebug,
+                  },
+                  {
+                    mnemonic: "MSTORE" as const,
+                    opcode: 0x52,
+                    debug: spillDebug,
                   },
-                  { mnemonic: "MSTORE" as const, opcode: 0x52 },
                 ],
               };
             });
@@ -212,14 +222,22 @@ function initializeMemory<S extends Stack>(
 ): Transition<S, S> {
   const { PUSHn, MSTORE } = operations;
 
-  return (
-    pipe<S>()
-      // Push the static offset value (the value to store)
-      .then(PUSHn(BigInt(nextStaticOffset)), { as: "value" })
-      // Push the free memory pointer location (0x40) (the offset)
-      .then(PUSHn(BigInt(Memory.regions.FREE_MEMORY_POINTER)), { as: "offset" })
-      // Store the initial free pointer (expects [value, offset] on stack)
-      .then(MSTORE())
-      .done()
-  );
+  const debug = {
+    context: {
+      remark: "initialize free memory pointer",
+    },
+  };
+
+  return pipe<S>()
+    .then(PUSHn(BigInt(nextStaticOffset), { debug }), {
+      as: "value",
+    })
+    .then(
+      PUSHn(BigInt(Memory.regions.FREE_MEMORY_POINTER), {
+        debug,
+      }),
+      { as: "offset" },
+    )
+    .then(MSTORE({ debug }))
+    .done();
 }

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

@@ -104,7 +104,11 @@ function generatePrologue<S extends Stack>(
         ...currentState,
         instructions: [
           ...currentState.instructions,
-          { mnemonic: "MSTORE", opcode: 0x52 },
+          {
+            mnemonic: "MSTORE",
+            opcode: 0x52,
+            debug: prologueDebug,
+          },
         ],
       };
     }
@@ -130,13 +134,22 @@ function generatePrologue<S extends Stack>(
             immediates: [0x60],
             debug: savePcDebug,
           },
-          { mnemonic: "MLOAD", opcode: 0x51 },
+          {
+            mnemonic: "MLOAD",
+            opcode: 0x51,
+            debug: savePcDebug,
+          },
           {
             mnemonic: "PUSH2",
             opcode: 0x61,
             immediates: [highByte, lowByte],
+            debug: savePcDebug,
+          },
+          {
+            mnemonic: "MSTORE",
+            opcode: 0x52,
+            debug: savePcDebug,
           },
-          { mnemonic: "MSTORE", opcode: 0x52 },
         ],
       };
     }

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

@@ -107,7 +107,17 @@ export function generate(
   // STOP (the isLastBlock optimization).
   const stopGuard: Evm.Instruction[] =
     patchedFunctions.length > 0
-      ? [{ mnemonic: "STOP" as const, opcode: 0x00 }]
+      ? [
+          {
+            mnemonic: "STOP" as const,
+            opcode: 0x00,
+            debug: {
+              context: {
+                remark: "guard: prevent fall-through into functions",
+              },
+            },
+          },
+        ]
       : [];
   const stopGuardBytes: number[] = patchedFunctions.length > 0 ? [0x00] : [];
 
@@ -243,13 +253,19 @@ function buildDeploymentInstructions(
 function deploymentTransition(runtimeOffset: bigint, runtimeLength: bigint) {
   const { PUSHn, CODECOPY, RETURN } = operations;
 
+  const debug = {
+    context: {
+      remark: "deployment: copy runtime bytecode and return",
+    },
+  };
+
   return pipe()
-    .then(PUSHn(runtimeLength), { as: "size" })
-    .then(PUSHn(runtimeOffset), { as: "offset" })
-    .then(PUSHn(0n), { as: "destOffset" })
-    .then(CODECOPY())
-    .then(PUSHn(runtimeLength), { as: "size" })
-    .then(PUSHn(0n), { as: "offset" })
-    .then(RETURN())
+    .then(PUSHn(runtimeLength, { debug }), { as: "size" })
+    .then(PUSHn(runtimeOffset, { debug }), { as: "offset" })
+    .then(PUSHn(0n, { debug }), { as: "destOffset" })
+    .then(CODECOPY({ debug }))
+    .then(PUSHn(runtimeLength, { debug }), { as: "size" })
+    .then(PUSHn(0n, { debug }), { as: "offset" })
+    .then(RETURN({ debug }))
     .done();
 }