Add function call tracing documentation

Add invoke/return/revert context documentation across concept,
reference, and spec pages:

- concepts/programs.mdx: new "Function call contexts" section
  explaining the three context types with a SchemaExample
- tracing.mdx: walkthrough of tracing through an internal function
  call (Adder contract), plus external call and revert examples
- Spec pages: added intro prose to function.mdx, return.mdx,
  revert.mdx

Author: gnidan

packages/web/docs/concepts/programs.mdx

@@ -157,6 +157,55 @@ Contexts can be composed using:
 This composition enables describing complex scenarios like conditional variable
 assignments or function inlining.
 
+## Function call contexts
+
+Programs answer "what function are we in?" through three context types
+that track function boundaries during execution:
+
+- **invoke** — marks an instruction that enters a function. Indicates
+  the invocation kind (internal jump, external message call, or
+  contract creation) and provides pointers to call arguments, target
+  address, gas, and value as appropriate.
+- **return** — marks an instruction associated with a successful
+  return from a function. Provides a pointer to the return data.
+- **revert** — marks an instruction associated with a failed call.
+  May include a pointer to revert reason data or a numeric panic
+  code.
+
+All three extend a common **function identity** schema with optional
+fields for the function's name, declaration source range, and type.
+This lets compilers provide as much or as little attribution as
+available — from a fully identified `transfer` call down to an
+anonymous indirect invocation through a function pointer.
+
+<SchemaExample
+  schema="program/context/function/invoke"
+  href="/spec/program/context/function/invoke"
+  title="Internal function call"
+>
+  {`{
+  "invoke": {
+    "identifier": "transfer",
+    "jump": true,
+    "target": {
+      "pointer": { "location": "stack", "slot": 0 }
+    },
+    "arguments": {
+      "pointer": {
+        "group": [
+          { "name": "to", "location": "stack", "slot": 2 },
+          { "name": "amount", "location": "stack", "slot": 3 }
+        ]
+      }
+    }
+  }
+}`}
+</SchemaExample>
+
+A debugger uses these contexts to reconstruct call stacks, show
+function names in stepping UI, and display argument/return values
+alongside source code.
+
 ## What tracing enables
 
 By following contexts through execution, debuggers can provide:

packages/web/docs/core-schemas/programs/tracing.mdx

@@ -121,6 +121,172 @@ b = b + 1;
 }`}
 />
 
+## Tracing through a function call
+
+The examples above trace simple straight-line code. Real programs
+make function calls. **invoke** and **return** contexts let a
+debugger follow execution across function boundaries.
+
+Consider a contract with an internal `add` function:
+
+```
+name Adder;
+
+storage {
+  [0] result: uint256;
+}
+
+create {
+  result = 0;
+}
+
+func add(a: uint256, b: uint256) -> uint256 {
+  return a + b;
+}
+
+code {
+  result = add(3, 4);
+}
+```
+
+The compiler produces a sequence of instructions. The relevant
+instructions look like this (offsets are illustrative):
+
+### Before the call — setting up arguments
+
+At the call site, the compiler pushes arguments onto the stack and
+prepares the jump. The instruction at the JUMP has an **invoke**
+context:
+
+<SchemaExample
+  schema="program/context/function/invoke"
+  href="/spec/program/context/function/invoke"
+  title="Instruction at call site (JUMP)"
+>
+  {`{
+  "invoke": {
+    "identifier": "add",
+    "jump": true,
+    "target": {
+      "pointer": { "location": "stack", "slot": 0 }
+    },
+    "arguments": {
+      "pointer": {
+        "group": [
+          { "name": "a", "location": "stack", "slot": 2 },
+          { "name": "b", "location": "stack", "slot": 3 }
+        ]
+      }
+    }
+  }
+}`}
+</SchemaExample>
+
+The debugger now knows it's entering `add` with arguments at stack
+slots 2 and 3. A trace viewer can show `add(3, 4)` in the call
+stack.
+
+### Inside the function — normal tracing
+
+Inside `add`, instructions carry their own `code` and `variables`
+contexts as usual. The debugger shows the source range within the
+function body, and parameters `a` and `b` appear as in-scope
+variables.
+
+### Returning — the result
+
+When `add` finishes, the JUMP back to the caller has a **return**
+context:
+
+<SchemaExample
+  schema="program/context/function/return"
+  href="/spec/program/context/function/return"
+  title="Instruction at return site (JUMP)"
+>
+  {`{
+  "return": {
+    "identifier": "add",
+    "data": {
+      "pointer": { "location": "stack", "slot": 0 }
+    }
+  }
+}`}
+</SchemaExample>
+
+The debugger pops `add` from the call stack and can display the
+return value (7).
+
+### External calls and reverts
+
+The same pattern applies to external message calls, but with
+additional fields. An external CALL instruction carries gas, value,
+and input data pointers:
+
+<SchemaExample
+  schema="program/context/function/invoke"
+  href="/spec/program/context/function/invoke"
+  title="External call (CALL)"
+>
+  {`{
+  "invoke": {
+    "identifier": "balanceOf",
+    "message": true,
+    "target": {
+      "pointer": { "location": "stack", "slot": 1 }
+    },
+    "gas": {
+      "pointer": { "location": "stack", "slot": 0 }
+    },
+    "input": {
+      "pointer": {
+        "group": [
+          { "name": "selector", "location": "memory",
+            "offset": "0x80", "length": 4 },
+          { "name": "arguments", "location": "memory",
+            "offset": "0x84", "length": "0x20" }
+        ]
+      }
+    }
+  }
+}`}
+</SchemaExample>
+
+If the call reverts, a **revert** context captures the reason:
+
+<SchemaExample
+  schema="program/context/function/revert"
+  href="/spec/program/context/function/revert"
+  title="Revert with reason"
+>
+  {`{
+  "revert": {
+    "identifier": "transfer",
+    "reason": {
+      "pointer": {
+        "location": "memory",
+        "offset": "0x80",
+        "length": "0x64"
+      }
+    }
+  }
+}`}
+</SchemaExample>
+
+For built-in assertion failures, the compiler can provide a panic
+code instead of (or alongside) a reason pointer:
+
+<SchemaExample
+  schema="program/context/function/revert"
+  href="/spec/program/context/function/revert"
+  title="Arithmetic overflow panic"
+>
+  {`{
+  "revert": {
+    "panic": 17
+  }
+}`}
+</SchemaExample>
+
 ## Trace data structure
 
 A trace step captures the EVM state at a single point:

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

@@ -7,7 +7,11 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
 # Function identity
 
 Function contexts (invoke, return, revert) share a common set of
-identity fields for the function being called.
+identity fields for the function being called. All fields are
+optional, allowing compilers to provide as much or as little
+detail as available — from a fully named function with source
+location and type, down to an empty object for an anonymous
+indirect call.
 
 <SchemaViewer
   schema={{ id: "schema:ethdebug/format/program/context/function" }}

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

@@ -6,6 +6,11 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
 
 # Return contexts
 
+A return context marks an instruction associated with a successful
+function return. It extends the function identity schema with a
+pointer to the return data and, for external calls, the success
+status.
+
 <SchemaViewer
   schema={{ id: "schema:ethdebug/format/program/context/function/return" }}
 />

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

@@ -6,6 +6,11 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
 
 # Revert contexts
 
+A revert context marks an instruction associated with a function
+revert. It extends the function identity schema with an optional
+pointer to revert reason data and/or a numeric panic code for
+built-in assertion failures.
+
 <SchemaViewer
   schema={{ id: "schema:ethdebug/format/program/context/function/revert" }}
 />