format: make invoke.target optional for internal calls (#242)

Internal calls via JUMP normally carry a code pointer to the callee's
entry point, but there isn't always a meaningful target to record — e.g.
at the first instruction of an inlined body, where the JUMP has been
elided. The callee identity (identifier, declaration, type) stays
meaningful; the target does not. Same pattern as return.data being
optional.

- Schema: drop `target` from InternalCall.required; expand the
  description; add a worked example for the no-target case.
- TS types: mark `target` optional; relax the guard.
- bugc: guard target access in patchInvokeInContext (+ tests assert
  target is defined before dereferencing).

Wave 1 of the transform-context → main split (#31): transform-schema-
independent. Forward-references to `transform:["inline"]` in the prose/
example are deferred to the wave that lands the transform schema.

Author: gnidan

packages/bugc/src/evmgen/call-contexts.test.ts

@@ -97,7 +97,8 @@ code {
       expect(typeof invoke.declaration!.range!.length).toBe("number");
 
       // Target should be a code pointer (not stack)
-      expect(Pointer.Region.isCode(call.target.pointer)).toBe(true);
+      expect(call.target).toBeDefined();
+      expect(Pointer.Region.isCode(call.target!.pointer)).toBe(true);
 
       // Caller JUMP should NOT have argument pointers
       // (args live on the callee JUMPDEST invoke context)
@@ -156,7 +157,8 @@ code {
       expect(call.identifier).toBe("add");
 
       // Target should be a code pointer
-      expect(Pointer.Region.isCode(call.target.pointer)).toBe(true);
+      expect(call.target).toBeDefined();
+      expect(Pointer.Region.isCode(call.target!.pointer)).toBe(true);
 
       // Should have argument pointers matching
       // function parameters

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

@@ -537,6 +537,8 @@ function patchInvokeInContext(
   const offset = functionRegistry[invoke.identifier];
   if (offset === undefined) return;
 
+  if (!invoke.target) return;
+
   const ptr = invoke.target.pointer;
   if (Format.Pointer.Region.isCode(ptr)) {
     ptr.offset = `0x${offset.toString(16)}`;

packages/bugc/src/evmgen/optimizer-contexts.test.ts

@@ -502,7 +502,8 @@ code { r = count(0, 5); }`;
           expect(Invocation.isInternalCall(invocation)).toBe(true);
           const internalCall =
             invocation as Format.Program.Context.Invoke.Invocation.InternalCall;
-          const invokeTarget = internalCall.target.pointer;
+          expect(internalCall.target).toBeDefined();
+          const invokeTarget = internalCall.target!.pointer;
           expect(invokeTarget).toBeDefined();
           expect(
             "offset" in invokeTarget ? invokeTarget.offset : undefined,

packages/format/src/types/program/context.ts

@@ -171,7 +171,7 @@ export namespace Context {
     export namespace Invocation {
       export interface InternalCall extends Function.Identity {
         jump: true;
-        target: Function.PointerRef;
+        target?: Function.PointerRef;
         arguments?: Function.PointerRef;
       }
 
@@ -180,8 +180,7 @@ export namespace Context {
         !!value &&
         "jump" in value &&
         value.jump === true &&
-        "target" in value &&
-        Function.isPointerRef(value.target) &&
+        (!("target" in value) || Function.isPointerRef(value.target)) &&
         (!("arguments" in value) || Function.isPointerRef(value.arguments));
 
       export interface ExternalCall extends Function.Identity {

packages/web/spec/program/context/function/invoke.mdx

@@ -51,6 +51,13 @@ caller's JUMP has already consumed the destination from the stack, so
 pointer slot values reflect the post-JUMP layout. The target points
 to a code location and arguments are passed on the stack.
 
+The `target` field is optional. It may be omitted when there is no
+meaningful code pointer to record — most notably at the first
+instruction of an inlined function body, where the inlining pass
+has elided the JUMP that would normally carry the target. The
+callee identity (`identifier`, `declaration`, `type`) remains
+meaningful in this case.
+
 <SchemaViewer
   schema={{ id: "schema:ethdebug/format/program/context/function/invoke" }}
   pointer="#/$defs/InternalCall"

schemas/program/context/function/invoke.schema.yaml

@@ -88,6 +88,13 @@ $defs:
         description: |
           Pointer to the target of the invocation. For internal
           calls, this typically points to a code location.
+          Optional: may be omitted when there is no meaningful
+          target pointer to record, e.g., at the first
+          instruction of an inlined function body where the
+          inlining pass has elided the JUMP that would normally
+          carry this pointer. The callee identity
+          (`identifier`, `declaration`, `type`) is still
+          meaningful in this case.
         properties:
           pointer:
             $ref: "schema:ethdebug/format/pointer"
@@ -107,7 +114,7 @@ $defs:
           - pointer
         additionalProperties: false
 
-    required: [jump, target]
+    required: [jump]
 
   ExternalCall:
     title: External call
@@ -284,6 +291,25 @@ examples:
               location: stack
               slot: 2
 
+  # -----------------------------------------------------------
+  # Inlined internal call: no target pointer
+  # -----------------------------------------------------------
+  # When the compiler inlines a function, the JUMP that would
+  # normally carry the invoke context has been elided — there
+  # is no physical call instruction and no code target to
+  # point at. The invoke context still records the callee's
+  # identity so the debugger can maintain a source-level call
+  # stack.
+  - invoke:
+      identifier: "transfer"
+      declaration:
+        source:
+          id: 0
+        range:
+          offset: 128
+          length: 95
+      jump: true
+
   # -----------------------------------------------------------
   # External CALL: token.balanceOf(account)
   # -----------------------------------------------------------