From 8fcc3804c33fca446356f87402e5516a0a1378ae Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Thu, 4 Jul 2024 17:46:53 -0400
Subject: [PATCH 01/19] Add very rough sketch of possible context schema

---
 schemas/context.schema.yaml | 46 +++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 schemas/context.schema.yaml

diff --git a/schemas/context.schema.yaml b/schemas/context.schema.yaml
new file mode 100644
index 00000000..b0cabe07
--- /dev/null
+++ b/schemas/context.schema.yaml
@@ -0,0 +1,46 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/context"
+
+title: ethdebug/format/context
+description: |
+  A schema for representing the information known at compile-time about the
+  high-level language concerns at a particular point in code execution.
+
+type: object
+
+properties:
+  variables:
+    type: array
+    items:
+      type: object
+      properties:
+        identifier:
+          type: string
+        declaration:
+          $ref: "schema:ethdebug/format/materials/source-range"
+        type:
+          $ref: "schema:ethdebug/format/type"
+        pointer:
+          $ref: "schema:ethdebug/format/pointer"
+      required:
+        - identifier
+        - declaration
+        - type
+
+minProperties: 1
+additionalProperties: false
+
+examples:
+  - variables:
+      - identifier: x
+        declaration:
+          source:
+            id: 5
+          range:
+            offset: 10
+            length: 56
+        type:
+          kind: string
+        pointer:
+          location: storage
+          slot: 0

From 9fb14f4b6cc2bc03e5e637fdbc594dd77fb787d6 Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Tue, 9 Jul 2024 17:24:50 -0400
Subject: [PATCH 02/19] Move variable stuff to own file

---
 schemas/context.schema.yaml          | 37 +++++++++++++++----------
 schemas/context/variable.schema.yaml | 40 ++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+), 14 deletions(-)
 create mode 100644 schemas/context/variable.schema.yaml

diff --git a/schemas/context.schema.yaml b/schemas/context.schema.yaml
index b0cabe07..bc647848 100644
--- a/schemas/context.schema.yaml
+++ b/schemas/context.schema.yaml
@@ -9,23 +9,26 @@ description: |
 type: object
 
 properties:
+  identifier:
+    type: string
+
   variables:
     type: array
+    description: |
+      Information about known variables at this context's point in code
+      execution, specified as an array whose items each correspond to a unique
+      variable.
+
+      Items in this array **should not** have duplicate non-empty `identifier`
+      values except where high-level language semantics require it. Where
+      possible, use other mechanisms provided by this format to indicate that
+      an identifier's corresponding variable is ambiguous.
     items:
-      type: object
-      properties:
-        identifier:
-          type: string
-        declaration:
-          $ref: "schema:ethdebug/format/materials/source-range"
-        type:
-          $ref: "schema:ethdebug/format/type"
-        pointer:
-          $ref: "schema:ethdebug/format/pointer"
-      required:
-        - identifier
-        - declaration
-        - type
+      $ref: "schema:ethdebug/format/context/variable"
+    additionalItems: false
+
+  code:
+    $ref: "schema:ethdebug/format/materials/source-range"
 
 minProperties: 1
 additionalProperties: false
@@ -44,3 +47,9 @@ examples:
         pointer:
           location: storage
           slot: 0
+    code:
+      source:
+        id: 5
+      range:
+        offset: 68
+        length: 16
diff --git a/schemas/context/variable.schema.yaml b/schemas/context/variable.schema.yaml
new file mode 100644
index 00000000..5f28530f
--- /dev/null
+++ b/schemas/context/variable.schema.yaml
@@ -0,0 +1,40 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/context/variable"
+
+title: ethdebug/format/context/variable
+description: |
+  The information known about a variable at a particular point in the code
+  execution.
+
+type: object
+properties:
+  identifier:
+    type: string
+    minLength: 1
+
+  declaration:
+    description: |
+      Source range corresponding to where the variable was declared.
+    $ref: "schema:ethdebug/format/materials/source-range"
+
+  type:
+    description: |
+      The variable's static type, if it exists.
+    $ref: "schema:ethdebug/format/type"
+
+  pointer:
+    description: |
+      Allocation information for the variable, if it exists.
+    $ref: "schema:ethdebug/format/pointer"
+
+required:
+  - declaration
+
+examples:
+  - identifier: x
+    declaration:
+      source:
+        id: 5
+      range:
+        offset: 10
+        length: 56

From 3b5f106a40a68bc909808ee95fc674c2af184f70 Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Tue, 9 Jul 2024 17:25:02 -0400
Subject: [PATCH 03/19] Add initial spec pages

---
 packages/web/spec/context/_category_.json |  5 +++++
 packages/web/spec/context/context.mdx     | 11 +++++++++++
 packages/web/spec/context/variable.mdx    | 11 +++++++++++
 packages/web/src/schemas.ts               | 15 +++++++++++++++
 4 files changed, 42 insertions(+)
 create mode 100644 packages/web/spec/context/_category_.json
 create mode 100644 packages/web/spec/context/context.mdx
 create mode 100644 packages/web/spec/context/variable.mdx

diff --git a/packages/web/spec/context/_category_.json b/packages/web/spec/context/_category_.json
new file mode 100644
index 00000000..5ba458b8
--- /dev/null
+++ b/packages/web/spec/context/_category_.json
@@ -0,0 +1,5 @@
+{
+  "label": "ethdebug/format/context",
+  "position": 5,
+  "link": null
+}
diff --git a/packages/web/spec/context/context.mdx b/packages/web/spec/context/context.mdx
new file mode 100644
index 00000000..4135b8ef
--- /dev/null
+++ b/packages/web/spec/context/context.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_position: 3
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Schema
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/context" }}
+  />
diff --git a/packages/web/spec/context/variable.mdx b/packages/web/spec/context/variable.mdx
new file mode 100644
index 00000000..d6dcea1f
--- /dev/null
+++ b/packages/web/spec/context/variable.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_position: 2
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Context variables
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/context/variable" }}
+  />
diff --git a/packages/web/src/schemas.ts b/packages/web/src/schemas.ts
index 65a2a87b..8ba3b0c4 100644
--- a/packages/web/src/schemas.ts
+++ b/packages/web/src/schemas.ts
@@ -168,6 +168,16 @@ export const schemaIndex: SchemaIndex = {
     })).reduce((a, b) => ({ ...a, ...b }), {})
   ),
 
+  "schema:ethdebug/format/context": {
+    title: "ethdebug/format/context schema",
+    href: "/spec/context"
+  },
+
+  "schema:ethdebug/format/context/variable": {
+    title: "Variable context schema",
+    href: "/spec/context/variable"
+  },
+
   "schema:ethdebug/format/materials/id": {
     title: "Identifier schema",
     href: "/spec/materials/id#identifier-schema"
@@ -187,4 +197,9 @@ export const schemaIndex: SchemaIndex = {
     title: "Source schema",
     href: "/spec/materials/source"
   },
+
+  "schema:ethdebug/format/materials/source-range": {
+    title: "Source range schema",
+    href: "/spec/materials/source-range"
+  },
 };

From 51c5e79dd857fdac92dafbeaab9707180098612a Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Fri, 12 Jul 2024 03:09:23 -0400
Subject: [PATCH 04/19] Rename identifier to name and add description

---
 schemas/context.schema.yaml | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/schemas/context.schema.yaml b/schemas/context.schema.yaml
index bc647848..b72597be 100644
--- a/schemas/context.schema.yaml
+++ b/schemas/context.schema.yaml
@@ -9,7 +9,11 @@ description: |
 type: object
 
 properties:
-  identifier:
+  name:
+    description: |
+      **Optional**. 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.
     type: string
 
   variables:

From cdf1dfc2571d6d2019e129cb538ac690eead1e83 Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Fri, 12 Jul 2024 03:25:23 -0400
Subject: [PATCH 05/19] Make variable schema into variables schema

---
 schemas/context.schema.yaml           | 14 +-----
 schemas/context/variable.schema.yaml  | 40 ---------------
 schemas/context/variables.schema.yaml | 72 +++++++++++++++++++++++++++
 3 files changed, 73 insertions(+), 53 deletions(-)
 delete mode 100644 schemas/context/variable.schema.yaml
 create mode 100644 schemas/context/variables.schema.yaml

diff --git a/schemas/context.schema.yaml b/schemas/context.schema.yaml
index b72597be..262667f9 100644
--- a/schemas/context.schema.yaml
+++ b/schemas/context.schema.yaml
@@ -17,19 +17,7 @@ properties:
     type: string
 
   variables:
-    type: array
-    description: |
-      Information about known variables at this context's point in code
-      execution, specified as an array whose items each correspond to a unique
-      variable.
-
-      Items in this array **should not** have duplicate non-empty `identifier`
-      values except where high-level language semantics require it. Where
-      possible, use other mechanisms provided by this format to indicate that
-      an identifier's corresponding variable is ambiguous.
-    items:
-      $ref: "schema:ethdebug/format/context/variable"
-    additionalItems: false
+    $ref: "schema:ethdebug/format/context/variables"
 
   code:
     $ref: "schema:ethdebug/format/materials/source-range"
diff --git a/schemas/context/variable.schema.yaml b/schemas/context/variable.schema.yaml
deleted file mode 100644
index 5f28530f..00000000
--- a/schemas/context/variable.schema.yaml
+++ /dev/null
@@ -1,40 +0,0 @@
-$schema: "https://json-schema.org/draft/2020-12/schema"
-$id: "schema:ethdebug/format/context/variable"
-
-title: ethdebug/format/context/variable
-description: |
-  The information known about a variable at a particular point in the code
-  execution.
-
-type: object
-properties:
-  identifier:
-    type: string
-    minLength: 1
-
-  declaration:
-    description: |
-      Source range corresponding to where the variable was declared.
-    $ref: "schema:ethdebug/format/materials/source-range"
-
-  type:
-    description: |
-      The variable's static type, if it exists.
-    $ref: "schema:ethdebug/format/type"
-
-  pointer:
-    description: |
-      Allocation information for the variable, if it exists.
-    $ref: "schema:ethdebug/format/pointer"
-
-required:
-  - declaration
-
-examples:
-  - identifier: x
-    declaration:
-      source:
-        id: 5
-      range:
-        offset: 10
-        length: 56
diff --git a/schemas/context/variables.schema.yaml b/schemas/context/variables.schema.yaml
new file mode 100644
index 00000000..743fa43c
--- /dev/null
+++ b/schemas/context/variables.schema.yaml
@@ -0,0 +1,72 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/context/variables"
+
+title: ethdebug/format/context/variables
+description: |
+  Information about known variables at this context's point in code
+  execution, specified as an array whose items each correspond to a unique
+  variable.
+
+  Items in this array **should not** have duplicate non-empty `identifier`
+  values except where high-level language semantics require it. Where
+  possible, use other mechanisms provided by this format to indicate that
+  an identifier's corresponding variable is ambiguous.
+
+type: array
+items:
+  $ref: "#/$defs/Variable"
+additionalItems: false
+
+$examples:
+  - identifier: x
+    declaration:
+      source:
+        id: 5
+      range:
+        offset: 10
+        length: 56
+    type:
+      kind: string
+    pointer:
+      location: storage
+      slot: 0
+
+$defs:
+  Variable:
+    title: Variable
+    description: |
+      The information known about a variable at a particular point in the code
+      execution.
+
+    type: object
+    properties:
+      identifier:
+        type: string
+        minLength: 1
+
+      declaration:
+        description: |
+          Source range corresponding to where the variable was declared.
+        $ref: "schema:ethdebug/format/materials/source-range"
+
+      type:
+        description: |
+          The variable's static type, if it exists.
+        $ref: "schema:ethdebug/format/type"
+
+      pointer:
+        description: |
+          Allocation information for the variable, if it exists.
+        $ref: "schema:ethdebug/format/pointer"
+
+    required:
+      - declaration
+
+    examples:
+      - identifier: x
+        declaration:
+          source:
+            id: 5
+          range:
+            offset: 10
+            length: 56

From f0e242e7ac346249b130933ee9bf59211742acdc Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Mon, 26 Aug 2024 12:43:33 +0200
Subject: [PATCH 06/19] [wip]

---
 packages/web/spec/context/variable.mdx | 11 --------
 packages/web/src/schemas.ts            |  5 ----
 schemas/context.schema.yaml            | 19 ++++---------
 schemas/context/code.schema.yaml       | 22 +++++++++++++++
 schemas/context/name.schema.yaml       | 18 ++++++++++++
 schemas/context/variables.schema.yaml  | 39 +++++++++++++++-----------
 6 files changed, 68 insertions(+), 46 deletions(-)
 delete mode 100644 packages/web/spec/context/variable.mdx
 create mode 100644 schemas/context/code.schema.yaml
 create mode 100644 schemas/context/name.schema.yaml

diff --git a/packages/web/spec/context/variable.mdx b/packages/web/spec/context/variable.mdx
deleted file mode 100644
index d6dcea1f..00000000
--- a/packages/web/spec/context/variable.mdx
+++ /dev/null
@@ -1,11 +0,0 @@
----
-sidebar_position: 2
----
-
-import SchemaViewer from "@site/src/components/SchemaViewer";
-
-# Context variables
-
-<SchemaViewer
-  schema={{ id: "schema:ethdebug/format/context/variable" }}
-  />
diff --git a/packages/web/src/schemas.ts b/packages/web/src/schemas.ts
index 8ba3b0c4..60cab7dd 100644
--- a/packages/web/src/schemas.ts
+++ b/packages/web/src/schemas.ts
@@ -173,11 +173,6 @@ export const schemaIndex: SchemaIndex = {
     href: "/spec/context"
   },
 
-  "schema:ethdebug/format/context/variable": {
-    title: "Variable context schema",
-    href: "/spec/context/variable"
-  },
-
   "schema:ethdebug/format/materials/id": {
     title: "Identifier schema",
     href: "/spec/materials/id#identifier-schema"
diff --git a/schemas/context.schema.yaml b/schemas/context.schema.yaml
index 262667f9..6b95cabe 100644
--- a/schemas/context.schema.yaml
+++ b/schemas/context.schema.yaml
@@ -8,22 +8,13 @@ description: |
 
 type: object
 
-properties:
-  name:
-    description: |
-      **Optional**. 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.
-    type: string
-
-  variables:
-    $ref: "schema:ethdebug/format/context/variables"
-
-  code:
-    $ref: "schema:ethdebug/format/materials/source-range"
+anyOf:
+  - $ref: "schema:ethdebug/format/context/code"
+  - $ref: "schema:ethdebug/format/context/name"
+  - $ref: "schema:ethdebug/format/context/variables"
 
 minProperties: 1
-additionalProperties: false
+unevaluatedProperties: false
 
 examples:
   - variables:
diff --git a/schemas/context/code.schema.yaml b/schemas/context/code.schema.yaml
new file mode 100644
index 00000000..fd4e0b1c
--- /dev/null
+++ b/schemas/context/code.schema.yaml
@@ -0,0 +1,22 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/context/code"
+
+title: ethdebug/format/context/code
+description: |
+  Information about the source code range corresponding to this point in
+  machine execution.
+
+type: object
+properties:
+  code:
+    $ref: "schema:ethdebug/format/materials/source-range"
+required:
+  - code
+
+examples:
+  - code:
+      source:
+        id: 5
+      range:
+        offset: 68
+        length: 16
diff --git a/schemas/context/name.schema.yaml b/schemas/context/name.schema.yaml
new file mode 100644
index 00000000..c6234149
--- /dev/null
+++ b/schemas/context/name.schema.yaml
@@ -0,0 +1,18 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/context/name"
+
+title: ethdebug/format/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.
+
+type: object
+properties:
+  name:
+    type: string
+required:
+  - name
+
+examples:
+  - name: "Array<T=bytes32>"
diff --git a/schemas/context/variables.schema.yaml b/schemas/context/variables.schema.yaml
index 743fa43c..17eb2fd9 100644
--- a/schemas/context/variables.schema.yaml
+++ b/schemas/context/variables.schema.yaml
@@ -12,24 +12,31 @@ description: |
   possible, use other mechanisms provided by this format to indicate that
   an identifier's corresponding variable is ambiguous.
 
-type: array
-items:
-  $ref: "#/$defs/Variable"
-additionalItems: false
+type: object
+properties:
+  variables:
+    type: array
+    items:
+      $ref: "#/$defs/Variable"
+    minItems: 1
+    additionalItems: false
+required:
+  - variables
 
 $examples:
-  - identifier: x
-    declaration:
-      source:
-        id: 5
-      range:
-        offset: 10
-        length: 56
-    type:
-      kind: string
-    pointer:
-      location: storage
-      slot: 0
+  - variables:
+      identifier: x
+      declaration:
+        source:
+          id: 5
+        range:
+          offset: 10
+          length: 56
+      type:
+        kind: string
+      pointer:
+        location: storage
+        slot: 0
 
 $defs:
   Variable:

From 43787a21ee03881912bb3e272b252b59fc7dc60b Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Tue, 27 Aug 2024 12:26:08 +0200
Subject: [PATCH 07/19] [wip]

---
 packages/web/spec/context/code.mdx      | 11 +++++++++++
 packages/web/spec/context/variables.mdx | 11 +++++++++++
 packages/web/src/schemas.ts             | 10 ++++++++++
 schemas/context.schema.yaml             |  1 -
 4 files changed, 32 insertions(+), 1 deletion(-)
 create mode 100644 packages/web/spec/context/code.mdx
 create mode 100644 packages/web/spec/context/variables.mdx

diff --git a/packages/web/spec/context/code.mdx b/packages/web/spec/context/code.mdx
new file mode 100644
index 00000000..52f6f962
--- /dev/null
+++ b/packages/web/spec/context/code.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_position: 4
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Code contexts
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/context/code" }}
+  />
diff --git a/packages/web/spec/context/variables.mdx b/packages/web/spec/context/variables.mdx
new file mode 100644
index 00000000..fc485a5b
--- /dev/null
+++ b/packages/web/spec/context/variables.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_position: 5
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Variables contexts
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/context/variables" }}
+  />
diff --git a/packages/web/src/schemas.ts b/packages/web/src/schemas.ts
index 60cab7dd..7b078194 100644
--- a/packages/web/src/schemas.ts
+++ b/packages/web/src/schemas.ts
@@ -173,6 +173,16 @@ export const schemaIndex: SchemaIndex = {
     href: "/spec/context"
   },
 
+  "schema:ethdebug/format/context/code": {
+    title: "Code context schema",
+    href: "/spec/context/code"
+  },
+
+  "schema:ethdebug/format/context/variables": {
+    title: "Variables context schema",
+    href: "/spec/context/variables"
+  },
+
   "schema:ethdebug/format/materials/id": {
     title: "Identifier schema",
     href: "/spec/materials/id#identifier-schema"
diff --git a/schemas/context.schema.yaml b/schemas/context.schema.yaml
index 6b95cabe..1a5d3d32 100644
--- a/schemas/context.schema.yaml
+++ b/schemas/context.schema.yaml
@@ -10,7 +10,6 @@ type: object
 
 anyOf:
   - $ref: "schema:ethdebug/format/context/code"
-  - $ref: "schema:ethdebug/format/context/name"
   - $ref: "schema:ethdebug/format/context/variables"
 
 minProperties: 1

From d4b0c14efaada8eb1456f8a8d058f6a9961bfd55 Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Tue, 27 Aug 2024 16:09:43 +0200
Subject: [PATCH 08/19] [wip] bytecode and instruction

---
 packages/web/spec/bytecode/_category_.json |  5 ++
 packages/web/spec/bytecode/bytecode.mdx    | 11 +++++
 packages/web/spec/bytecode/instruction.mdx | 11 +++++
 packages/web/spec/context/_category_.json  |  2 +-
 packages/web/src/schemas.ts                | 26 +++++++---
 schemas/bytecode.schema.yaml               | 56 ++++++++++++++++++++++
 schemas/bytecode/instruction.schema.yaml   | 45 +++++++++++++++++
 7 files changed, 148 insertions(+), 8 deletions(-)
 create mode 100644 packages/web/spec/bytecode/_category_.json
 create mode 100644 packages/web/spec/bytecode/bytecode.mdx
 create mode 100644 packages/web/spec/bytecode/instruction.mdx
 create mode 100644 schemas/bytecode.schema.yaml
 create mode 100644 schemas/bytecode/instruction.schema.yaml

diff --git a/packages/web/spec/bytecode/_category_.json b/packages/web/spec/bytecode/_category_.json
new file mode 100644
index 00000000..0a60683f
--- /dev/null
+++ b/packages/web/spec/bytecode/_category_.json
@@ -0,0 +1,5 @@
+{
+  "label": "ethdebug/format/bytecode",
+  "position": 5,
+  "link": null
+}
diff --git a/packages/web/spec/bytecode/bytecode.mdx b/packages/web/spec/bytecode/bytecode.mdx
new file mode 100644
index 00000000..8f0c6a4e
--- /dev/null
+++ b/packages/web/spec/bytecode/bytecode.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_position: 3
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Schema
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/bytecode" }}
+  />
diff --git a/packages/web/spec/bytecode/instruction.mdx b/packages/web/spec/bytecode/instruction.mdx
new file mode 100644
index 00000000..dcc9f6be
--- /dev/null
+++ b/packages/web/spec/bytecode/instruction.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_position: 4
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Instruction schema
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/bytecode/instruction" }}
+  />
diff --git a/packages/web/spec/context/_category_.json b/packages/web/spec/context/_category_.json
index 5ba458b8..1ef31bcc 100644
--- a/packages/web/spec/context/_category_.json
+++ b/packages/web/spec/context/_category_.json
@@ -1,5 +1,5 @@
 {
   "label": "ethdebug/format/context",
-  "position": 5,
+  "position": 6,
   "link": null
 }
diff --git a/packages/web/src/schemas.ts b/packages/web/src/schemas.ts
index 7b078194..4eb723ab 100644
--- a/packages/web/src/schemas.ts
+++ b/packages/web/src/schemas.ts
@@ -173,16 +173,28 @@ export const schemaIndex: SchemaIndex = {
     href: "/spec/context"
   },
 
-  "schema:ethdebug/format/context/code": {
-    title: "Code context schema",
-    href: "/spec/context/code"
-  },
+  ...([
+    "code",
+    "variables"
+  ].map(name => ({
+    [`schema:ethdebug/format/context/${name}`]: {
+      href: `/spec/context/${name}`
+    },
+  })).reduce((a, b) => ({ ...a, ...b }), {})),
 
-  "schema:ethdebug/format/context/variables": {
-    title: "Variables context schema",
-    href: "/spec/context/variables"
+  "schema:ethdebug/format/bytecode": {
+    title: "ethdebug/format/bytecode schema",
+    href: "/spec/bytecode"
   },
 
+  ...([
+    "instruction"
+  ].map(name => ({
+    [`schema:ethdebug/format/bytecode/${name}`]: {
+      href: `/spec/bytecode/${name}`
+    },
+  })).reduce((a, b) => ({ ...a, ...b }), {})),
+
   "schema:ethdebug/format/materials/id": {
     title: "Identifier schema",
     href: "/spec/materials/id#identifier-schema"
diff --git a/schemas/bytecode.schema.yaml b/schemas/bytecode.schema.yaml
new file mode 100644
index 00000000..8900bfb8
--- /dev/null
+++ b/schemas/bytecode.schema.yaml
@@ -0,0 +1,56 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/bytecode"
+
+title: ethdebug/format/bytecode
+description: |
+  A schema for representing the information pertaining to a particular bytecode
+  for a contract.
+
+type: object
+
+properties:
+  instructions:
+    type: object
+    description: |
+      A mapping from instruction byte offset to instruction annotation.
+
+      For legacy contract bytecode (non-EOF), keys in this mapping are
+      equivalent to the instruction's program counter. For EOF bytecode, keys
+      in this mapping are byte offsets relative to _the start of the
+      container_ (since program counters within EOF are relative to the start of
+      individual code sections within the container).
+
+      Keys in this mapping **must** be specified as `0x`-prefixed hexadecimal
+      strings. Keys **may** vary in bytes length and avoid left-padding with
+      zeroes, except that keys **must** represent at least one byte (`0x` is
+      not allowed).
+
+    patternProperties:
+      "^0x[0-9a-fA-F]{1,}$":
+        $ref: "schema:ethdebug/format/bytecode/instruction"
+
+    additionalProperties: false
+
+required:
+  - instructions
+
+examples:
+  - instructions:
+      "0x00":
+        operation:
+          mnemonic: PUSH1
+          arguments: ["0x60"]
+        context:
+          variables:
+            - identifier: paused
+              declaration:
+                source:
+                  id: 5
+                range:
+                  offset: 10
+                  length: 30
+              type:
+                kind: bool
+              pointer:
+                location: storage
+                slot: 0
diff --git a/schemas/bytecode/instruction.schema.yaml b/schemas/bytecode/instruction.schema.yaml
new file mode 100644
index 00000000..5fc0af70
--- /dev/null
+++ b/schemas/bytecode/instruction.schema.yaml
@@ -0,0 +1,45 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/bytecode/instruction"
+
+title: ethdebug/format/bytecode/instruction
+description: |
+  A schema for representing the information pertaining to a particular instruction
+  in machine code.
+
+type: object
+
+properties:
+  operation:
+    title: Machine operation information
+    type: object
+    properties:
+      mnemonic:
+        description: The mnemonic operation code (PUSH1, e.g.)
+        type: string
+
+      arguments:
+        description: The immediate arguments to the operation, if relevant.
+        type: array
+        minItems: 1
+        items:
+          description: |
+            An immediate value, specified as a `0x`-prefixed hexadecimal string.
+          type: string
+          pattern: "^0x[0-9a-fA-F]{1,}$"
+    required:
+      - mnemonic
+
+  context:
+    $ref: "schema:ethdebug/format/context"
+
+required:
+  - context
+
+examples:
+  - context:
+      code:
+        source:
+          id: 5
+        range:
+          offset: 10
+          length: 30

From b8a807b1aae91cd927be90f40d3c41e633167314 Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Tue, 27 Aug 2024 17:05:06 +0200
Subject: [PATCH 09/19] Allow specifying context before first instruction

---
 schemas/bytecode.schema.yaml             | 6 ++++++
 schemas/bytecode/instruction.schema.yaml | 2 ++
 2 files changed, 8 insertions(+)

diff --git a/schemas/bytecode.schema.yaml b/schemas/bytecode.schema.yaml
index 8900bfb8..4630d8a8 100644
--- a/schemas/bytecode.schema.yaml
+++ b/schemas/bytecode.schema.yaml
@@ -9,6 +9,12 @@ description: |
 type: object
 
 properties:
+  context:
+    description: |
+      The context known to exist prior to the execution of the first
+      instruction in the bytecode.
+    $ref: "schema:ethdebug/format/context"
+
   instructions:
     type: object
     description: |
diff --git a/schemas/bytecode/instruction.schema.yaml b/schemas/bytecode/instruction.schema.yaml
index 5fc0af70..5f6b70b3 100644
--- a/schemas/bytecode/instruction.schema.yaml
+++ b/schemas/bytecode/instruction.schema.yaml
@@ -30,6 +30,8 @@ properties:
       - mnemonic
 
   context:
+    description: |
+      The context known to exist following the execution of this instruction.
     $ref: "schema:ethdebug/format/context"
 
 required:

From 7eed5c95db785c3ef0ad3c171b27186fef9867f4 Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Wed, 28 Aug 2024 12:18:51 +0200
Subject: [PATCH 10/19] Add types map to bytecode

---
 schemas/bytecode.schema.yaml | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/schemas/bytecode.schema.yaml b/schemas/bytecode.schema.yaml
index 4630d8a8..d9dcd6bc 100644
--- a/schemas/bytecode.schema.yaml
+++ b/schemas/bytecode.schema.yaml
@@ -30,13 +30,20 @@ properties:
       strings. Keys **may** vary in bytes length and avoid left-padding with
       zeroes, except that keys **must** represent at least one byte (`0x` is
       not allowed).
-
     patternProperties:
       "^0x[0-9a-fA-F]{1,}$":
         $ref: "schema:ethdebug/format/bytecode/instruction"
-
     additionalProperties: false
 
+  types:
+    type: object
+    description: |
+      A collection of types by name identifier. This field is optional and
+      **may** be used by compilers that wish to minimize the size of output
+      debugging data by de-duplicating type representations.
+    additionalProperties:
+      $ref: "schema:ethdebug/format/type"
+
 required:
   - instructions
 

From 1d33ac2b7cb0ddcd9c52cd76079e4932d19ef239 Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Wed, 28 Aug 2024 12:25:42 +0200
Subject: [PATCH 11/19] Allow using type references in variables contexts

---
 schemas/bytecode.schema.yaml          |  7 ++++--
 schemas/context/variables.schema.yaml | 34 +++++++++++++++------------
 2 files changed, 24 insertions(+), 17 deletions(-)

diff --git a/schemas/bytecode.schema.yaml b/schemas/bytecode.schema.yaml
index d9dcd6bc..8f7f6597 100644
--- a/schemas/bytecode.schema.yaml
+++ b/schemas/bytecode.schema.yaml
@@ -48,7 +48,10 @@ required:
   - instructions
 
 examples:
-  - instructions:
+  - types:
+      "my-bool":
+        kind: bool
+    instructions:
       "0x00":
         operation:
           mnemonic: PUSH1
@@ -63,7 +66,7 @@ examples:
                   offset: 10
                   length: 30
               type:
-                kind: bool
+                id: "my-bool"
               pointer:
                 location: storage
                 slot: 0
diff --git a/schemas/context/variables.schema.yaml b/schemas/context/variables.schema.yaml
index 17eb2fd9..1070da9b 100644
--- a/schemas/context/variables.schema.yaml
+++ b/schemas/context/variables.schema.yaml
@@ -23,20 +23,20 @@ properties:
 required:
   - variables
 
-$examples:
+examples:
   - variables:
-      identifier: x
-      declaration:
-        source:
-          id: 5
-        range:
-          offset: 10
-          length: 56
-      type:
-        kind: string
-      pointer:
-        location: storage
-        slot: 0
+      - identifier: x
+        declaration:
+          source:
+            id: 5
+          range:
+            offset: 10
+            length: 56
+        type:
+          kind: string
+        pointer:
+          location: storage
+          slot: 0
 
 $defs:
   Variable:
@@ -58,8 +58,12 @@ $defs:
 
       type:
         description: |
-          The variable's static type, if it exists.
-        $ref: "schema:ethdebug/format/type"
+          The variable's static type, if it exists. This **must** be specified
+          either as a full **ethdebug/format/type** representation, or an
+          `{ "id": "..." }` type reference object.
+        oneOf:
+          - $ref: "schema:ethdebug/format/type"
+          - $ref: "schema:ethdebug/format/type/reference"
 
       pointer:
         description: |

From 04c6ffa5de462271fac2322c4c7b68492981d809 Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Wed, 28 Aug 2024 17:19:07 +0200
Subject: [PATCH 12/19] Stop indexing instructions by their byte offset

---
 schemas/bytecode.schema.yaml             | 24 ++++++----------------
 schemas/bytecode/instruction.schema.yaml | 26 +++++++++++++++++++++---
 2 files changed, 29 insertions(+), 21 deletions(-)

diff --git a/schemas/bytecode.schema.yaml b/schemas/bytecode.schema.yaml
index 8f7f6597..fda6ade7 100644
--- a/schemas/bytecode.schema.yaml
+++ b/schemas/bytecode.schema.yaml
@@ -16,24 +16,12 @@ properties:
     $ref: "schema:ethdebug/format/context"
 
   instructions:
-    type: object
+    type: array
     description: |
-      A mapping from instruction byte offset to instruction annotation.
-
-      For legacy contract bytecode (non-EOF), keys in this mapping are
-      equivalent to the instruction's program counter. For EOF bytecode, keys
-      in this mapping are byte offsets relative to _the start of the
-      container_ (since program counters within EOF are relative to the start of
-      individual code sections within the container).
-
-      Keys in this mapping **must** be specified as `0x`-prefixed hexadecimal
-      strings. Keys **may** vary in bytes length and avoid left-padding with
-      zeroes, except that keys **must** represent at least one byte (`0x` is
-      not allowed).
-    patternProperties:
-      "^0x[0-9a-fA-F]{1,}$":
-        $ref: "schema:ethdebug/format/bytecode/instruction"
-    additionalProperties: false
+      The full array of instructions for the bytecode.
+    items:
+      $ref: "schema:ethdebug/format/bytecode/instruction"
+    additionalItems: false
 
   types:
     type: object
@@ -52,7 +40,7 @@ examples:
       "my-bool":
         kind: bool
     instructions:
-      "0x00":
+      - offset: 0
         operation:
           mnemonic: PUSH1
           arguments: ["0x60"]
diff --git a/schemas/bytecode/instruction.schema.yaml b/schemas/bytecode/instruction.schema.yaml
index 5f6b70b3..dda77afd 100644
--- a/schemas/bytecode/instruction.schema.yaml
+++ b/schemas/bytecode/instruction.schema.yaml
@@ -3,12 +3,27 @@ $id: "schema:ethdebug/format/bytecode/instruction"
 
 title: ethdebug/format/bytecode/instruction
 description: |
-  A schema for representing the information pertaining to a particular instruction
-  in machine code.
+  A schema for representing the information pertaining to a particular
+  instruction in machine code.
 
 type: object
 
 properties:
+  offset:
+    title: Instruction byte offset
+    description: |
+      The byte offset where the instruction begins within the bytecode.
+
+      For legacy contract bytecode (non-EOF), this value is equivalent to the
+      instruction's program counter. For EOF bytecode, this value **must** be
+      the offset from the start of the container, not the start of a particular
+      code section within that container.
+    oneOf:
+      - type: number
+        minimum: 0
+      - type: string
+        pattern: "^0x[0-9a-fA-F]{1,}$"
+
   operation:
     title: Machine operation information
     type: object
@@ -35,10 +50,15 @@ properties:
     $ref: "schema:ethdebug/format/context"
 
 required:
+  - offset
   - context
 
 examples:
-  - context:
+  - offset: 0
+    operation:
+      mnemonic: "PUSH1"
+      arguments: ["0x60"]
+    context:
       code:
         source:
           id: 5

From 6dbd44e35d1602f52f346a7a1d01b2c9f7035ee1 Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Thu, 29 Aug 2024 13:27:42 +0200
Subject: [PATCH 13/19] Add pointer templates to bytecode schema

---
 schemas/bytecode.schema.yaml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/schemas/bytecode.schema.yaml b/schemas/bytecode.schema.yaml
index fda6ade7..3abf2653 100644
--- a/schemas/bytecode.schema.yaml
+++ b/schemas/bytecode.schema.yaml
@@ -32,6 +32,9 @@ properties:
     additionalProperties:
       $ref: "schema:ethdebug/format/type"
 
+  pointers:
+    $ref: "schema:ethdebug/format/pointer/templates"
+
 required:
   - instructions
 

From 0019557e4868fa599d7927a48f5eebc182e0af89 Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Thu, 29 Aug 2024 14:14:29 +0200
Subject: [PATCH 14/19] Include pointer templates in bytecode example

---
 schemas/bytecode.schema.yaml | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/schemas/bytecode.schema.yaml b/schemas/bytecode.schema.yaml
index 3abf2653..d5f19a4f 100644
--- a/schemas/bytecode.schema.yaml
+++ b/schemas/bytecode.schema.yaml
@@ -42,6 +42,12 @@ examples:
   - types:
       "my-bool":
         kind: bool
+    pointers:
+      "my-storage-bool":
+        expect: ["my-slot"]
+        for:
+          location: storage
+          slot: "my-slot"
     instructions:
       - offset: 0
         operation:
@@ -59,5 +65,7 @@ examples:
               type:
                 id: "my-bool"
               pointer:
-                location: storage
-                slot: 0
+                define:
+                  "my-slot": 0
+                in:
+                  template: "my-storage-bool"

From a553d4e318006a4cc1b7c498b4683a7ddbf9fe06 Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Thu, 29 Aug 2024 17:48:54 +0200
Subject: [PATCH 15/19] Use new data schemas

---
 schemas/bytecode/instruction.schema.yaml | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/schemas/bytecode/instruction.schema.yaml b/schemas/bytecode/instruction.schema.yaml
index dda77afd..4b391ba7 100644
--- a/schemas/bytecode/instruction.schema.yaml
+++ b/schemas/bytecode/instruction.schema.yaml
@@ -19,10 +19,8 @@ properties:
       the offset from the start of the container, not the start of a particular
       code section within that container.
     oneOf:
-      - type: number
-        minimum: 0
-      - type: string
-        pattern: "^0x[0-9a-fA-F]{1,}$"
+      - $ref: "schema:ethdebug/format/data/unsigned"
+      - $ref: "schema:ethdebug/format/data/hex"
 
   operation:
     title: Machine operation information

From 0089228281c297bbc4ce0343001456a9f1dafb7d Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Fri, 30 Aug 2024 13:19:53 +0200
Subject: [PATCH 16/19] Use template schema properly

---
 schemas/bytecode.schema.yaml | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/schemas/bytecode.schema.yaml b/schemas/bytecode.schema.yaml
index d5f19a4f..d5dc3640 100644
--- a/schemas/bytecode.schema.yaml
+++ b/schemas/bytecode.schema.yaml
@@ -24,16 +24,24 @@ properties:
     additionalItems: false
 
   types:
-    type: object
+    title: Types by name
     description: |
       A collection of types by name identifier. This field is optional and
       **may** be used by compilers that wish to minimize the size of output
       debugging data by de-duplicating type representations.
+    type: object
     additionalProperties:
       $ref: "schema:ethdebug/format/type"
 
   pointers:
-    $ref: "schema:ethdebug/format/pointer/templates"
+    title: Pointers by name
+    description: |
+      A collection of pointer templates by name identifier. This field is
+      optional and **may** be used by compilers that wish to minimize the size
+      of output debugging data by de-duplicating type representations.
+    type: object
+    additionalProperties:
+      $ref: "schema:ethdebug/format/pointer/template"
 
 required:
   - instructions

From e5c15093fb44f6d61f46dd51314cd2389775dcf1 Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Fri, 30 Aug 2024 14:59:33 +0200
Subject: [PATCH 17/19] Add note about possibly moving fields

---
 schemas/bytecode.schema.yaml | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/schemas/bytecode.schema.yaml b/schemas/bytecode.schema.yaml
index d5dc3640..1948d6b3 100644
--- a/schemas/bytecode.schema.yaml
+++ b/schemas/bytecode.schema.yaml
@@ -29,6 +29,10 @@ properties:
       A collection of types by name identifier. This field is optional and
       **may** be used by compilers that wish to minimize the size of output
       debugging data by de-duplicating type representations.
+
+      **Note** that this field may duplicate types used by other bytecode
+      resources. To match the data model more closely in the future, this field
+      may be moved to another schema in this format.
     type: object
     additionalProperties:
       $ref: "schema:ethdebug/format/type"
@@ -39,6 +43,10 @@ properties:
       A collection of pointer templates by name identifier. This field is
       optional and **may** be used by compilers that wish to minimize the size
       of output debugging data by de-duplicating type representations.
+
+      **Note** that this field may duplicate pointers used by other bytecode
+      resources. To match the data model more closely in the future, this field
+      may be moved to another schema in this format.
     type: object
     additionalProperties:
       $ref: "schema:ethdebug/format/pointer/template"

From 0c6dc99892e57ff82548b9c150278a0f594ba07d Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Wed, 25 Sep 2024 22:55:49 -0400
Subject: [PATCH 18/19] [wip]

---
 packages/web/sidebars.ts                      |   4 +-
 packages/web/spec/bytecode/_category_.json    |   5 -
 packages/web/spec/context/_category_.json     |   5 -
 packages/web/spec/info/_category_.json        |   5 +
 packages/web/spec/info/info.mdx               |  11 ++
 packages/web/spec/info/overview.mdx           |  52 +++++++
 packages/web/spec/program/_category_.json     |   5 +
 .../web/spec/program/context/_category_.json  |   5 +
 .../web/spec/{ => program}/context/code.mdx   |   2 +-
 .../context/context.mdx}                      |   2 +-
 .../spec/{ => program}/context/variables.mdx  |   2 +-
 .../{bytecode => program}/instruction.mdx     |   2 +-
 .../context.mdx => program/program.mdx}       |   2 +-
 packages/web/src/css/custom.css               |  19 +++
 packages/web/src/schemas.ts                   |  16 +-
 schemas/bytecode.schema.yaml                  |  87 -----------
 schemas/info.schema.yaml                      |  45 ++++++
 schemas/program.schema.yaml                   | 141 ++++++++++++++++++
 schemas/{ => program}/context.schema.yaml     |   8 +-
 .../{ => program}/context/code.schema.yaml    |   4 +-
 .../{ => program}/context/name.schema.yaml    |   4 +-
 .../context/variables.schema.yaml             |   7 +-
 .../instruction.schema.yaml                   |   6 +-
 23 files changed, 312 insertions(+), 127 deletions(-)
 delete mode 100644 packages/web/spec/bytecode/_category_.json
 delete mode 100644 packages/web/spec/context/_category_.json
 create mode 100644 packages/web/spec/info/_category_.json
 create mode 100644 packages/web/spec/info/info.mdx
 create mode 100644 packages/web/spec/info/overview.mdx
 create mode 100644 packages/web/spec/program/_category_.json
 create mode 100644 packages/web/spec/program/context/_category_.json
 rename packages/web/spec/{ => program}/context/code.mdx (66%)
 rename packages/web/spec/{bytecode/bytecode.mdx => program/context/context.mdx} (66%)
 rename packages/web/spec/{ => program}/context/variables.mdx (65%)
 rename packages/web/spec/{bytecode => program}/instruction.mdx (67%)
 rename packages/web/spec/{context/context.mdx => program/program.mdx} (69%)
 delete mode 100644 schemas/bytecode.schema.yaml
 create mode 100644 schemas/info.schema.yaml
 create mode 100644 schemas/program.schema.yaml
 rename schemas/{ => program}/context.schema.yaml (76%)
 rename schemas/{ => program}/context/code.schema.yaml (79%)
 rename schemas/{ => program}/context/name.schema.yaml (79%)
 rename schemas/{ => program}/context/variables.schema.yaml (94%)
 rename schemas/{bytecode => program}/instruction.schema.yaml (91%)

diff --git a/packages/web/sidebars.ts b/packages/web/sidebars.ts
index b20b0437..c050153c 100644
--- a/packages/web/sidebars.ts
+++ b/packages/web/sidebars.ts
@@ -12,7 +12,9 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
  */
 const sidebars: SidebarsConfig = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
-  docsSidebar: [{type: 'autogenerated', dirName: '.'}],
+  docsSidebar: [
+    {type: 'autogenerated', dirName: '.'},
+  ],
 
   // But you can create a sidebar manually
   /*
diff --git a/packages/web/spec/bytecode/_category_.json b/packages/web/spec/bytecode/_category_.json
deleted file mode 100644
index 0a60683f..00000000
--- a/packages/web/spec/bytecode/_category_.json
+++ /dev/null
@@ -1,5 +0,0 @@
-{
-  "label": "ethdebug/format/bytecode",
-  "position": 5,
-  "link": null
-}
diff --git a/packages/web/spec/context/_category_.json b/packages/web/spec/context/_category_.json
deleted file mode 100644
index 1ef31bcc..00000000
--- a/packages/web/spec/context/_category_.json
+++ /dev/null
@@ -1,5 +0,0 @@
-{
-  "label": "ethdebug/format/context",
-  "position": 6,
-  "link": null
-}
diff --git a/packages/web/spec/info/_category_.json b/packages/web/spec/info/_category_.json
new file mode 100644
index 00000000..c5a4b4a8
--- /dev/null
+++ b/packages/web/spec/info/_category_.json
@@ -0,0 +1,5 @@
+{
+  "label": "ethdebug/format/info",
+  "position": 7,
+  "link": null
+}
diff --git a/packages/web/spec/info/info.mdx b/packages/web/spec/info/info.mdx
new file mode 100644
index 00000000..3eb4eb99
--- /dev/null
+++ b/packages/web/spec/info/info.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_position: 2
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Schema
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/info" }}
+  />
diff --git a/packages/web/spec/info/overview.mdx b/packages/web/spec/info/overview.mdx
new file mode 100644
index 00000000..d044ee03
--- /dev/null
+++ b/packages/web/spec/info/overview.mdx
@@ -0,0 +1,52 @@
+---
+sidebar_position: 1
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Overview
+
+:::tip[Summary]
+
+Objects in the **ethdebug/format/info** schema organize debugging data
+associated with a particular compilation. This includes lookup tables of
+types and pointers by their unique name identifiers, as well as optionally may
+include additional information such as complete program listings and compiled
+source contents.
+
+:::
+
+This schema serves as a root schema, in that it (a) aggregates
+all other schemas in this format (either directly or indirectly), and (b) in
+that no other schema aggregates it.
+
+This schema serves as a suitable target for
+[JSON Schema bundling](https://json-schema.org/understanding-json-schema/structuring#bundling),
+e.g., for implementations that want to reduce complexity around validating
+**ethdebug/format** records and don't want to handle reference resolution
+across schema YAML files.
+
+:::warning
+
+**Note**, however, that "root schema" does not imply "objects in the schema
+always contain all relevant debugging data". Due to widespread practice among
+EVM language compilers to produce their own structured JSON output, objects in
+this schema are not necessarily complete records of debug information.
+
+Compilers may choose to divide **distinct portions of debugging data** into
+**distinct sections of compiler JSON output**. For instance, it likely makes
+sense for a compiler to produce debugging data about a particular contract's
+bytecode alongside that contract bytecode's other output information.
+
+At least until tooling accommodates this concern, debugging implementers
+**must** be aware that they will likely need to aggregate debugging data from
+multiple sections of each supported compiler's own output format.
+
+:::
+
+**However**, this schema _is suitable_ for representing a complete and
+standalone debugging data record for a particular compilation, but
+note the optionality of fields such as `compilation` and `programs`.
+Implementations looking to produce such self-contained debugging data objects
+should study the structure of these (and any other optional fields) and ensure
+that such fields are fully populated.
diff --git a/packages/web/spec/program/_category_.json b/packages/web/spec/program/_category_.json
new file mode 100644
index 00000000..aeaea680
--- /dev/null
+++ b/packages/web/spec/program/_category_.json
@@ -0,0 +1,5 @@
+{
+  "label": "ethdebug/format/program",
+  "position": 5,
+  "link": null
+}
diff --git a/packages/web/spec/program/context/_category_.json b/packages/web/spec/program/context/_category_.json
new file mode 100644
index 00000000..4f0c10a2
--- /dev/null
+++ b/packages/web/spec/program/context/_category_.json
@@ -0,0 +1,5 @@
+{
+  "label": "Program contexts",
+  "position": 6,
+  "link": null
+}
diff --git a/packages/web/spec/context/code.mdx b/packages/web/spec/program/context/code.mdx
similarity index 66%
rename from packages/web/spec/context/code.mdx
rename to packages/web/spec/program/context/code.mdx
index 52f6f962..8231b5a4 100644
--- a/packages/web/spec/context/code.mdx
+++ b/packages/web/spec/program/context/code.mdx
@@ -7,5 +7,5 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
 # Code contexts
 
 <SchemaViewer
-  schema={{ id: "schema:ethdebug/format/context/code" }}
+  schema={{ id: "schema:ethdebug/format/program/context/code" }}
   />
diff --git a/packages/web/spec/bytecode/bytecode.mdx b/packages/web/spec/program/context/context.mdx
similarity index 66%
rename from packages/web/spec/bytecode/bytecode.mdx
rename to packages/web/spec/program/context/context.mdx
index 8f0c6a4e..05ee98d7 100644
--- a/packages/web/spec/bytecode/bytecode.mdx
+++ b/packages/web/spec/program/context/context.mdx
@@ -7,5 +7,5 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
 # Schema
 
 <SchemaViewer
-  schema={{ id: "schema:ethdebug/format/bytecode" }}
+  schema={{ id: "schema:ethdebug/format/program/context" }}
   />
diff --git a/packages/web/spec/context/variables.mdx b/packages/web/spec/program/context/variables.mdx
similarity index 65%
rename from packages/web/spec/context/variables.mdx
rename to packages/web/spec/program/context/variables.mdx
index fc485a5b..88e2b552 100644
--- a/packages/web/spec/context/variables.mdx
+++ b/packages/web/spec/program/context/variables.mdx
@@ -7,5 +7,5 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
 # Variables contexts
 
 <SchemaViewer
-  schema={{ id: "schema:ethdebug/format/context/variables" }}
+  schema={{ id: "schema:ethdebug/format/program/context/variables" }}
   />
diff --git a/packages/web/spec/bytecode/instruction.mdx b/packages/web/spec/program/instruction.mdx
similarity index 67%
rename from packages/web/spec/bytecode/instruction.mdx
rename to packages/web/spec/program/instruction.mdx
index dcc9f6be..375e11e7 100644
--- a/packages/web/spec/bytecode/instruction.mdx
+++ b/packages/web/spec/program/instruction.mdx
@@ -7,5 +7,5 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
 # Instruction schema
 
 <SchemaViewer
-  schema={{ id: "schema:ethdebug/format/bytecode/instruction" }}
+  schema={{ id: "schema:ethdebug/format/program/instruction" }}
   />
diff --git a/packages/web/spec/context/context.mdx b/packages/web/spec/program/program.mdx
similarity index 69%
rename from packages/web/spec/context/context.mdx
rename to packages/web/spec/program/program.mdx
index 4135b8ef..c6d59716 100644
--- a/packages/web/spec/context/context.mdx
+++ b/packages/web/spec/program/program.mdx
@@ -7,5 +7,5 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
 # Schema
 
 <SchemaViewer
-  schema={{ id: "schema:ethdebug/format/context" }}
+  schema={{ id: "schema:ethdebug/format/program" }}
   />
diff --git a/packages/web/src/css/custom.css b/packages/web/src/css/custom.css
index ed7727ac..d345640e 100644
--- a/packages/web/src/css/custom.css
+++ b/packages/web/src/css/custom.css
@@ -59,3 +59,22 @@
   text-decoration: underline !important;
   background-color: inherit !important;
 }
+
+.theme-doc-sidebar-item-category.root-schema > * > a::after {
+  margin-left: 0.5em;
+  content: "Root schema";
+  width: min-content;
+  font-size: 66%;
+  font-weight: var(--ifm-font-weight-bold);
+  line-height: 1;
+  text-transform: uppercase;
+  background-color: var(--ifm-badge-background-color);
+  border: var(--ifm-badge-border-width) solid var(--ifm-badge-border-color);
+  border-radius: var(--ifm-badge-border-radius);
+  color: var(--ifm-color-primary-darkest);
+  padding: var(--ifm-badge-padding-vertical) var(--ifrm-badge-padding-horizontal);
+  transform: none;
+
+
+
+}
diff --git a/packages/web/src/schemas.ts b/packages/web/src/schemas.ts
index 4eb723ab..5732b45f 100644
--- a/packages/web/src/schemas.ts
+++ b/packages/web/src/schemas.ts
@@ -168,8 +168,8 @@ export const schemaIndex: SchemaIndex = {
     })).reduce((a, b) => ({ ...a, ...b }), {})
   ),
 
-  "schema:ethdebug/format/context": {
-    title: "ethdebug/format/context schema",
+  "schema:ethdebug/format/program/context": {
+    title: "ethdebug/format/program/context schema",
     href: "/spec/context"
   },
 
@@ -177,21 +177,21 @@ export const schemaIndex: SchemaIndex = {
     "code",
     "variables"
   ].map(name => ({
-    [`schema:ethdebug/format/context/${name}`]: {
+    [`schema:ethdebug/format/program/context/${name}`]: {
       href: `/spec/context/${name}`
     },
   })).reduce((a, b) => ({ ...a, ...b }), {})),
 
-  "schema:ethdebug/format/bytecode": {
-    title: "ethdebug/format/bytecode schema",
-    href: "/spec/bytecode"
+  "schema:ethdebug/format/program": {
+    title: "ethdebug/format/program schema",
+    href: "/spec/program"
   },
 
   ...([
     "instruction"
   ].map(name => ({
-    [`schema:ethdebug/format/bytecode/${name}`]: {
-      href: `/spec/bytecode/${name}`
+    [`schema:ethdebug/format/program/${name}`]: {
+      href: `/spec/program/${name}`
     },
   })).reduce((a, b) => ({ ...a, ...b }), {})),
 
diff --git a/schemas/bytecode.schema.yaml b/schemas/bytecode.schema.yaml
deleted file mode 100644
index 1948d6b3..00000000
--- a/schemas/bytecode.schema.yaml
+++ /dev/null
@@ -1,87 +0,0 @@
-$schema: "https://json-schema.org/draft/2020-12/schema"
-$id: "schema:ethdebug/format/bytecode"
-
-title: ethdebug/format/bytecode
-description: |
-  A schema for representing the information pertaining to a particular bytecode
-  for a contract.
-
-type: object
-
-properties:
-  context:
-    description: |
-      The context known to exist prior to the execution of the first
-      instruction in the bytecode.
-    $ref: "schema:ethdebug/format/context"
-
-  instructions:
-    type: array
-    description: |
-      The full array of instructions for the bytecode.
-    items:
-      $ref: "schema:ethdebug/format/bytecode/instruction"
-    additionalItems: false
-
-  types:
-    title: Types by name
-    description: |
-      A collection of types by name identifier. This field is optional and
-      **may** be used by compilers that wish to minimize the size of output
-      debugging data by de-duplicating type representations.
-
-      **Note** that this field may duplicate types used by other bytecode
-      resources. To match the data model more closely in the future, this field
-      may be moved to another schema in this format.
-    type: object
-    additionalProperties:
-      $ref: "schema:ethdebug/format/type"
-
-  pointers:
-    title: Pointers by name
-    description: |
-      A collection of pointer templates by name identifier. This field is
-      optional and **may** be used by compilers that wish to minimize the size
-      of output debugging data by de-duplicating type representations.
-
-      **Note** that this field may duplicate pointers used by other bytecode
-      resources. To match the data model more closely in the future, this field
-      may be moved to another schema in this format.
-    type: object
-    additionalProperties:
-      $ref: "schema:ethdebug/format/pointer/template"
-
-required:
-  - instructions
-
-examples:
-  - types:
-      "my-bool":
-        kind: bool
-    pointers:
-      "my-storage-bool":
-        expect: ["my-slot"]
-        for:
-          location: storage
-          slot: "my-slot"
-    instructions:
-      - offset: 0
-        operation:
-          mnemonic: PUSH1
-          arguments: ["0x60"]
-        context:
-          variables:
-            - identifier: paused
-              declaration:
-                source:
-                  id: 5
-                range:
-                  offset: 10
-                  length: 30
-              type:
-                id: "my-bool"
-              pointer:
-                define:
-                  "my-slot": 0
-                in:
-                  template: "my-storage-bool"
diff --git a/schemas/info.schema.yaml b/schemas/info.schema.yaml
new file mode 100644
index 00000000..2cbccb60
--- /dev/null
+++ b/schemas/info.schema.yaml
@@ -0,0 +1,45 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/info"
+
+title: ethdebug/format/info
+description: |
+  Objects in this schema organize debugging data relating to a particular
+  compilation, including **ethdebug/format/type** and
+  **ethdebug/format/pointer** records by name identifiers.
+
+  Objects in this schema **may** contain debugging information about individual
+  sources, contracts, and compiled bytecodes, to accommodate use cases that
+  benefit from debugging data being collected together in a single JSON object.
+type: object
+properties:
+  types:
+    title: Types by name
+    description: |
+      A collection of types by name identifier.
+    type: object
+    additionalProperties:
+      $ref: "schema:ethdebug/format/type"
+
+  pointers:
+    title: Pointer templates by name
+    description: |
+      A collection of pointer templates by name identifier.
+    type: object
+    additionalProperties:
+      $ref: "schema:ethdebug/format/pointer/template"
+
+  compilation:
+    $ref: "schema:ethdebug/format/materials/compilation"
+
+  programs:
+    type: array
+    items:
+      $ref: "schema:ethdebug/format/program"
+
+required:
+  - types
+  - pointers
+
+examples:
+  - types: {}
+    pointers: {}
diff --git a/schemas/program.schema.yaml b/schemas/program.schema.yaml
new file mode 100644
index 00000000..013d9a6f
--- /dev/null
+++ b/schemas/program.schema.yaml
@@ -0,0 +1,141 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/program"
+
+title: ethdebug/format/program
+description: |
+  Debugging information about a particular bytecode in a compilation.
+
+type: object
+
+properties:
+  compilation:
+    title: Compilation reference by ID
+    $ref: "schema:ethdebug/format/materials/reference"
+
+  contract:
+    type: object
+    properties:
+      name:
+        type: string
+
+      definition:
+        $ref: "schema:ethdebug/format/materials/source-range"
+
+  environment:
+    title: Bytecode execution environment
+    description: |
+      Whether this bytecode is for contract creation or runtime calls.
+    type: string
+    enum:
+      - call
+      - create
+
+  context:
+    description: |
+      The context known to exist prior to the execution of the first
+      instruction in the bytecode.
+    $ref: "schema:ethdebug/format/program/context"
+
+  instructions:
+    type: array
+    description: |
+      The full array of instructions for the bytecode.
+    items:
+      $ref: "schema:ethdebug/format/program/instruction"
+    additionalItems: false
+
+required:
+  - contract
+  - environment
+  - instructions
+
+examples:
+  - # Incrementing a storage counter
+    #
+    # This example represents the call bytecode for the following pseudo-code:
+    # ```
+    # contract Incrementer;
+    #
+    # storage {
+    #   [0] storedValue: uint256;
+    # };
+    #
+    # code {
+    #   let localValue = storedValue;
+    #   storedValue += 1;
+    #   value = tmp;
+    # };
+    # ```
+    contract:
+      name: "Incrementer"
+      definition:
+        source:
+          id: 0
+    environment: call
+    context:
+      variables:
+        - &stored-value
+          identifier: storedValue
+          type:
+            kind: uint
+            bits: 256
+          pointer:
+            location: storage
+            slot: 0
+    instructions:
+      - offset: 0
+        operation:
+          mnemonic: PUSH0
+        context:
+          variables:
+            - *stored-value
+      - offset: 1
+        operation:
+          mnemonic: SLOAD
+        context:
+          variables:
+            - *stored-value
+            - &local-value
+              identifier: localValue
+              type:
+                kind: uint
+                bits: 256
+              pointer:
+                location: stack
+                slot: 0
+      - offset: 2
+        operation:
+          mnemonic: PUSH1
+          arguments: ["0x01"]
+        context:
+          variables:
+            - *stored-value
+            - <<: *local-value
+              pointer:
+                location: stack
+                slot: 1
+
+      - offset: 4
+        operation:
+          mnemonic: ADD
+        context:
+          variables:
+            - *stored-value
+            - *local-value
+      - offset: 5
+        operation:
+          mnemonic: PUSH0
+        context:
+          variables:
+            - *stored-value
+            - <<: *local-value
+              pointer:
+                location: stack
+                slot: 1
+
+      - offset: 6
+        operation:
+          mnemonic: SSTORE
+        context:
+          variables:
+            - *stored-value
diff --git a/schemas/context.schema.yaml b/schemas/program/context.schema.yaml
similarity index 76%
rename from schemas/context.schema.yaml
rename to schemas/program/context.schema.yaml
index 1a5d3d32..5995bb43 100644
--- a/schemas/context.schema.yaml
+++ b/schemas/program/context.schema.yaml
@@ -1,7 +1,7 @@
 $schema: "https://json-schema.org/draft/2020-12/schema"
-$id: "schema:ethdebug/format/context"
+$id: "schema:ethdebug/format/program/context"
 
-title: ethdebug/format/context
+title: ethdebug/format/program/context
 description: |
   A schema for representing the information known at compile-time about the
   high-level language concerns at a particular point in code execution.
@@ -9,8 +9,8 @@ description: |
 type: object
 
 anyOf:
-  - $ref: "schema:ethdebug/format/context/code"
-  - $ref: "schema:ethdebug/format/context/variables"
+  - $ref: "schema:ethdebug/format/program/context/code"
+  - $ref: "schema:ethdebug/format/program/context/variables"
 
 minProperties: 1
 unevaluatedProperties: false
diff --git a/schemas/context/code.schema.yaml b/schemas/program/context/code.schema.yaml
similarity index 79%
rename from schemas/context/code.schema.yaml
rename to schemas/program/context/code.schema.yaml
index fd4e0b1c..003e8d2c 100644
--- a/schemas/context/code.schema.yaml
+++ b/schemas/program/context/code.schema.yaml
@@ -1,7 +1,7 @@
 $schema: "https://json-schema.org/draft/2020-12/schema"
-$id: "schema:ethdebug/format/context/code"
+$id: "schema:ethdebug/format/program/context/code"
 
-title: ethdebug/format/context/code
+title: ethdebug/format/program/context/code
 description: |
   Information about the source code range corresponding to this point in
   machine execution.
diff --git a/schemas/context/name.schema.yaml b/schemas/program/context/name.schema.yaml
similarity index 79%
rename from schemas/context/name.schema.yaml
rename to schemas/program/context/name.schema.yaml
index c6234149..57d0ce77 100644
--- a/schemas/context/name.schema.yaml
+++ b/schemas/program/context/name.schema.yaml
@@ -1,7 +1,7 @@
 $schema: "https://json-schema.org/draft/2020-12/schema"
-$id: "schema:ethdebug/format/context/name"
+$id: "schema:ethdebug/format/program/context/name"
 
-title: ethdebug/format/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
diff --git a/schemas/context/variables.schema.yaml b/schemas/program/context/variables.schema.yaml
similarity index 94%
rename from schemas/context/variables.schema.yaml
rename to schemas/program/context/variables.schema.yaml
index 1070da9b..32cf2585 100644
--- a/schemas/context/variables.schema.yaml
+++ b/schemas/program/context/variables.schema.yaml
@@ -1,7 +1,7 @@
 $schema: "https://json-schema.org/draft/2020-12/schema"
-$id: "schema:ethdebug/format/context/variables"
+$id: "schema:ethdebug/format/program/context/variables"
 
-title: ethdebug/format/context/variables
+title: ethdebug/format/program/context/variables
 description: |
   Information about known variables at this context's point in code
   execution, specified as an array whose items each correspond to a unique
@@ -70,9 +70,6 @@ $defs:
           Allocation information for the variable, if it exists.
         $ref: "schema:ethdebug/format/pointer"
 
-    required:
-      - declaration
-
     examples:
       - identifier: x
         declaration:
diff --git a/schemas/bytecode/instruction.schema.yaml b/schemas/program/instruction.schema.yaml
similarity index 91%
rename from schemas/bytecode/instruction.schema.yaml
rename to schemas/program/instruction.schema.yaml
index 4b391ba7..2472201c 100644
--- a/schemas/bytecode/instruction.schema.yaml
+++ b/schemas/program/instruction.schema.yaml
@@ -1,7 +1,7 @@
 $schema: "https://json-schema.org/draft/2020-12/schema"
-$id: "schema:ethdebug/format/bytecode/instruction"
+$id: "schema:ethdebug/format/program/instruction"
 
-title: ethdebug/format/bytecode/instruction
+title: ethdebug/format/program/instruction
 description: |
   A schema for representing the information pertaining to a particular
   instruction in machine code.
@@ -45,7 +45,7 @@ properties:
   context:
     description: |
       The context known to exist following the execution of this instruction.
-    $ref: "schema:ethdebug/format/context"
+    $ref: "schema:ethdebug/format/program/context"
 
 required:
   - offset

From 630c9200455c5323889166d18979003f51351343 Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Fri, 27 Sep 2024 21:54:59 -0400
Subject: [PATCH 19/19] undo sidebars change

---
 packages/web/sidebars.ts | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/packages/web/sidebars.ts b/packages/web/sidebars.ts
index c050153c..b20b0437 100644
--- a/packages/web/sidebars.ts
+++ b/packages/web/sidebars.ts
@@ -12,9 +12,7 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
  */
 const sidebars: SidebarsConfig = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
-  docsSidebar: [
-    {type: 'autogenerated', dirName: '.'},
-  ],
+  docsSidebar: [{type: 'autogenerated', dirName: '.'}],
 
   // But you can create a sidebar manually
   /*