format: add activation identifier to correlate invocations with returns

An invocation and the return (or revert) that ends the same activation
can now carry a matching `activation` string. A debugger uses it to pair
a call with its return directly — independent of trace order, without
relying on strictly nested invoke/return ordering. Distinct activations
carry distinct values, unique within a program.

- Schema: add an optional `activation` string to the invoke, return, and
  revert contexts; add a worked example pairing an invoke with its return
  by a shared value.
- TS types: add `activation` to the invoke/return/revert types and
  validate it in their guards. Also add the `Name` context type and
  guard, which the schema defined but the types were missing.

Author: gnidan

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

@@ -3,6 +3,7 @@ import { Type } from "#types/type";
 import { Pointer, isPointer } from "#types/pointer";
 
 export type Context =
+  | Context.Name
   | Context.Code
   | Context.Variables
   | Context.Remark
@@ -15,6 +16,7 @@ export type Context =
 
 export const isContext = (value: unknown): value is Context =>
   [
+    Context.isName,
     Context.isCode,
     Context.isVariables,
     Context.isRemark,
@@ -27,6 +29,16 @@ export const isContext = (value: unknown): value is Context =>
   ].some((guard) => guard(value));
 
 export namespace Context {
+  export interface Name {
+    name: string;
+  }
+
+  export const isName = (value: unknown): value is Name =>
+    typeof value === "object" &&
+    !!value &&
+    "name" in value &&
+    typeof value.name === "string";
+
   export interface Code {
     code: Materials.SourceRange;
   }
@@ -155,15 +167,17 @@ export namespace Context {
     Invoke.isInvocation(value.invoke);
 
   export namespace Invoke {
-    export type Invocation = Function.Identity &
-      (
+    export type Invocation = Function.Identity & {
+      activation?: string;
+    } & (
         | Invocation.InternalCall
         | Invocation.ExternalCall
         | Invocation.ContractCreation
       );
 
     export const isInvocation = (value: unknown): value is Invocation =>
       Function.isIdentity(value) &&
+      (!("activation" in value) || typeof value.activation === "string") &&
       (Invocation.isInternalCall(value) ||
         Invocation.isExternalCall(value) ||
         Invocation.isContractCreation(value));
@@ -241,14 +255,16 @@ export namespace Context {
     export interface Info extends Function.Identity {
       data?: Function.PointerRef;
       success?: Function.PointerRef;
+      activation?: string;
     }
 
     export const isInfo = (value: unknown): value is Info =>
       Function.isIdentity(value) &&
       typeof value === "object" &&
       !!value &&
       (!("data" in value) || Function.isPointerRef(value.data)) &&
-      (!("success" in value) || Function.isPointerRef(value.success));
+      (!("success" in value) || Function.isPointerRef(value.success)) &&
+      (!("activation" in value) || typeof value.activation === "string");
   }
 
   export interface Revert {
@@ -265,13 +281,15 @@ export namespace Context {
     export interface Info extends Function.Identity {
       reason?: Function.PointerRef;
       panic?: number;
+      activation?: string;
     }
 
     export const isInfo = (value: unknown): value is Info =>
       Function.isIdentity(value) &&
       typeof value === "object" &&
       !!value &&
       (!("reason" in value) || Function.isPointerRef(value.reason)) &&
-      (!("panic" in value) || typeof value.panic === "number");
+      (!("panic" in value) || typeof value.panic === "number") &&
+      (!("activation" in value) || typeof value.activation === "string");
   }
 }

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

@@ -43,6 +43,18 @@ properties:
 
     $ref: "schema:ethdebug/format/program/context/function"
 
+    properties:
+      activation:
+        type: string
+        title: Activation identifier
+        description: |
+          Correlation identifier pairing this invocation with its
+          matching return or revert. The invoke that opens an
+          activation and the return or revert that closes it carry
+          the same value; distinct activations carry distinct
+          values, unique within the program. Lets a debugger pair a
+          call with its return independent of trace order. Optional.
+
     allOf:
       - oneOf:
           - required: [jump]
@@ -283,6 +295,9 @@ examples:
             - name: "amount"
               location: stack
               slot: 2
+      # The matching return context carries the same `activation`
+      # value, pairing this call with its return.
+      activation: "transfer#0"
 
   # -----------------------------------------------------------
   # External CALL: token.balanceOf(account)

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

@@ -49,6 +49,17 @@ properties:
         required:
           - pointer
 
+      activation:
+        type: string
+        title: Activation identifier
+        description: |
+          Correlation identifier for the activation this return
+          ends. Matches the `activation` on the `invoke` that
+          opened the same activation; distinct activations carry
+          distinct values, unique within the program. Lets a
+          debugger pair a return with its invocation independent
+          of trace order. Optional.
+
     unevaluatedProperties: false
 
 required:
@@ -75,6 +86,9 @@ examples:
         pointer:
           location: stack
           slot: 0
+      # Same `activation` value as the opening `invoke`, pairing
+      # this return with its call.
+      activation: "transfer#0"
 
   # -----------------------------------------------------------
   # External call return: processing result of a CALL

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

@@ -37,6 +37,17 @@ properties:
           (e.g., Solidity uses codes like 0x11 for arithmetic
           overflow).
 
+      activation:
+        type: string
+        title: Activation identifier
+        description: |
+          Correlation identifier for the activation this revert
+          ends. Matches the `activation` on the `invoke` that
+          opened the same activation; distinct activations carry
+          distinct values, unique within the program. Lets a
+          debugger pair an abnormal exit with its invocation
+          independent of trace order. Optional.
+
     unevaluatedProperties: false
 
 required: