From 30235f248d73075c74a629b38ba3c391447eefeb Mon Sep 17 00:00:00 2001 From: "g. nicholas d'andrea" Date: Mon, 9 Mar 2026 16:15:52 -0400 Subject: [PATCH 1/4] Integrate orphaned context/name schema into program context Wire the existing but unreferenced context/name.schema.yaml into program/context.schema.yaml using the same if/then pattern as other context properties. Update the name schema description to clarify its role in disambiguating pick alternatives. Add a named pick example to demonstrate the intended usage. --- schemas/program/context.schema.yaml | 7 +++++++ schemas/program/context/name.schema.yaml | 13 ++++++++++--- schemas/program/context/pick.schema.yaml | 17 +++++++++++++++++ 3 files changed, 34 insertions(+), 3 deletions(-) diff --git a/schemas/program/context.schema.yaml b/schemas/program/context.schema.yaml index 1a82386220..65f44f57de 100644 --- a/schemas/program/context.schema.yaml +++ b/schemas/program/context.schema.yaml @@ -26,6 +26,13 @@ description: | type: object allOf: + - if: + required: ["name"] + then: + description: | + A label for this context, for use in identifying it from + other contexts (e.g., to disambiguate `pick` alternatives). + $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..32113da9a9 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 this context, for use in identifying it 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,5 @@ required: - name examples: + - name: "inlined-call" - 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 From 11cbed5eb07b0c5ddb6c884cbd614433091eb6fe Mon Sep 17 00:00:00 2001 From: "g. nicholas d'andrea" Date: Mon, 9 Mar 2026 16:25:36 -0400 Subject: [PATCH 2/4] Polish context/name descriptions per writer review - Use "distinguishing" instead of "identifying it from" - Shorten inline description in context.schema.yaml to match sibling entries' style - Add example comments to name.schema.yaml examples --- schemas/program/context.schema.yaml | 3 +-- schemas/program/context/name.schema.yaml | 6 ++++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/schemas/program/context.schema.yaml b/schemas/program/context.schema.yaml index 65f44f57de..ba5a4ee87d 100644 --- a/schemas/program/context.schema.yaml +++ b/schemas/program/context.schema.yaml @@ -30,8 +30,7 @@ allOf: required: ["name"] then: description: | - A label for this context, for use in identifying it from - other contexts (e.g., to disambiguate `pick` alternatives). + A label for distinguishing this context from others. $ref: "schema:ethdebug/format/program/context/name" - if: required: ["code"] diff --git a/schemas/program/context/name.schema.yaml b/schemas/program/context/name.schema.yaml index 32113da9a9..7591610593 100644 --- a/schemas/program/context/name.schema.yaml +++ b/schemas/program/context/name.schema.yaml @@ -3,8 +3,8 @@ $id: "schema:ethdebug/format/program/context/name" title: ethdebug/format/program/context/name description: | - A label for this context, for use in identifying it from other - contexts. This is particularly useful inside `pick` alternatives, + 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. @@ -21,5 +21,7 @@ required: - name examples: + # example: naming an inlined call site - name: "inlined-call" + # example: naming a generic instantiation - name: "Array" From fa32d7af6100daee263e9de89a893c7cdac5e397 Mon Sep 17 00:00:00 2001 From: "g. nicholas d'andrea" Date: Mon, 9 Mar 2026 16:27:47 -0400 Subject: [PATCH 3/4] Add spec page and schemas.ts entry for context/name Add name.mdx doc page following the pattern of sibling context pages (remark, frame, etc.). Register the schema ID in schemas.ts so the spec site links to the new page. --- packages/web/spec/program/context/name.mdx | 16 ++++++++++++++++ packages/web/src/schemas.ts | 2 +- 2 files changed, 17 insertions(+), 1 deletion(-) create mode 100644 packages/web/spec/program/context/name.mdx diff --git a/packages/web/spec/program/context/name.mdx b/packages/web/spec/program/context/name.mdx new file mode 100644 index 0000000000..e939921cd8 --- /dev/null +++ b/packages/web/spec/program/context/name.mdx @@ -0,0 +1,16 @@ +--- +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}`, From 9284b2282b41e971dee64048aac5ac2249c74b53 Mon Sep 17 00:00:00 2001 From: "g. nicholas d'andrea" Date: Mon, 9 Mar 2026 16:30:39 -0400 Subject: [PATCH 4/4] Fix formatting in name.mdx spec page --- packages/web/spec/program/context/name.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/packages/web/spec/program/context/name.mdx b/packages/web/spec/program/context/name.mdx index e939921cd8..31fd7fb17d 100644 --- a/packages/web/spec/program/context/name.mdx +++ b/packages/web/spec/program/context/name.mdx @@ -11,6 +11,4 @@ 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. - +