Begin drafting context schema

packages/web/spec/info/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "ethdebug/format/info",
+  "position": 7,
+  "link": null
+}

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" }}
+  />

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.

packages/web/spec/program/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "ethdebug/format/program",
+  "position": 5,
+  "link": null
+}

packages/web/spec/program/context/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Program contexts",
+  "position": 6,
+  "link": null
+}

packages/web/spec/program/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/program/context/code" }}
+  />

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

@@ -0,0 +1,11 @@
+---
+sidebar_position: 3
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Schema
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/program/context" }}
+  />

packages/web/spec/program/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/program/context/variables" }}
+  />

packages/web/spec/program/instruction.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 4
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Instruction schema
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/program/instruction" }}
+  />

packages/web/spec/program/program.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 3
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Schema
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/program" }}
+  />

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;
+
+
+
+}

packages/web/src/schemas.ts

@@ -168,6 +168,33 @@ export const schemaIndex: SchemaIndex = {
     })).reduce((a, b) => ({ ...a, ...b }), {})
   ),
 
+  "schema:ethdebug/format/program/context": {
+    title: "ethdebug/format/program/context schema",
+    href: "/spec/context"
+  },
+
+  ...([
+    "code",
+    "variables"
+  ].map(name => ({
+    [`schema:ethdebug/format/program/context/${name}`]: {
+      href: `/spec/context/${name}`
+    },
+  })).reduce((a, b) => ({ ...a, ...b }), {})),
+
+  "schema:ethdebug/format/program": {
+    title: "ethdebug/format/program schema",
+    href: "/spec/program"
+  },
+
+  ...([
+    "instruction"
+  ].map(name => ({
+    [`schema:ethdebug/format/program/${name}`]: {
+      href: `/spec/program/${name}`
+    },
+  })).reduce((a, b) => ({ ...a, ...b }), {})),
+
   "schema:ethdebug/format/materials/id": {
     title: "Identifier schema",
     href: "/spec/materials/id#identifier-schema"
@@ -187,4 +214,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"
+  },
 };

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: {}

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