diff --git a/packages/web/spec/program/context/name.mdx b/packages/web/spec/program/context/name.mdx
new file mode 100644
index 0000000000..31fd7fb17d
--- /dev/null
+++ b/packages/web/spec/program/context/name.mdx
@@ -0,0 +1,14 @@
+---
+sidebar_position: 6
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Named contexts
+
+Contexts may include a `name` property for distinguishing them from
+other contexts. This is particularly useful inside `pick` alternatives,
+where several possible contexts may apply at a given point in execution
+and runtime information is needed to select which one is active.
+
+
diff --git a/packages/web/src/schemas.ts b/packages/web/src/schemas.ts
index 194cdf0344..619c35b043 100644
--- a/packages/web/src/schemas.ts
+++ b/packages/web/src/schemas.ts
@@ -224,7 +224,7 @@ const programSchemaIndex: SchemaIndex = {
href: "/spec/program/context",
},
- ...["code", "variables", "remark", "pick", "gather", "frame"]
+ ...["name", "code", "variables", "remark", "pick", "gather", "frame"]
.map((name) => ({
[`schema:ethdebug/format/program/context/${name}`]: {
href: `/spec/program/context/${name}`,
diff --git a/schemas/program/context.schema.yaml b/schemas/program/context.schema.yaml
index 1a82386220..ba5a4ee87d 100644
--- a/schemas/program/context.schema.yaml
+++ b/schemas/program/context.schema.yaml
@@ -26,6 +26,12 @@ description: |
type: object
allOf:
+ - if:
+ required: ["name"]
+ then:
+ description: |
+ A label for distinguishing this context from others.
+ $ref: "schema:ethdebug/format/program/context/name"
- if:
required: ["code"]
then:
diff --git a/schemas/program/context/name.schema.yaml b/schemas/program/context/name.schema.yaml
index 57d0ce77c3..7591610593 100644
--- a/schemas/program/context/name.schema.yaml
+++ b/schemas/program/context/name.schema.yaml
@@ -3,9 +3,15 @@ $id: "schema:ethdebug/format/program/context/name"
title: ethdebug/format/program/context/name
description: |
- The name of the context, for use in disambiguating future instruction
- annotations that specify one of several possible contexts based on
- information only available at runtime.
+ A label for distinguishing this context from other contexts.
+ This is particularly useful inside `pick` alternatives,
+ where several possible contexts may apply at a given point in
+ execution and runtime information is needed to select which one
+ is active.
+
+ Context names are opaque strings with no format-imposed semantics.
+ Compilers **should** choose names that are meaningful to debugger
+ users.
type: object
properties:
@@ -15,4 +21,7 @@ required:
- name
examples:
+ # example: naming an inlined call site
+ - name: "inlined-call"
+ # example: naming a generic instantiation
- name: "Array"
diff --git a/schemas/program/context/pick.schema.yaml b/schemas/program/context/pick.schema.yaml
index c36c8a9bee..3250900d4d 100644
--- a/schemas/program/context/pick.schema.yaml
+++ b/schemas/program/context/pick.schema.yaml
@@ -33,3 +33,20 @@ examples:
range:
offset: 132
length: 16
+
+ - # example: named alternatives for disambiguation
+ pick:
+ - name: "inlined-call"
+ code:
+ source:
+ id: 5
+ range:
+ offset: 68
+ length: 16
+ - name: "original-site"
+ code:
+ source:
+ id: 5
+ range:
+ offset: 132
+ length: 16