[wip]

packages/tests/schemas/examples.test.ts

@@ -13,6 +13,7 @@ const idsOfSchemasAllowedToOmitExamples = new Set([
   "schema:ethdebug/format/type/elementary",
   "schema:ethdebug/format/pointer/region",
   "schema:ethdebug/format/pointer/collection",
+  "schema:ethdebug/format/pointer/operation",
 ]);
 
 describe("Examples", () => {

packages/web/spec/operation/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "ethdebug/format/operation",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Work-in-progress formal schema for ethdebug format"
+  }
+}

packages/web/spec/operation/concepts.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 2
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Key concepts
+
+## Operations do not represent runtime
+
+##

packages/web/spec/operation/overview.mdx

@@ -0,0 +1,50 @@
+---
+sidebar_position: 1
+---
+
+# Overview
+
+:::warning
+
+This schema is **very incomplete** and is missing subschemas for
+several essential kinds of operations.
+
+:::
+
+:::tip
+
+**ethdebug/format/operation** is a JSON schema for describing things that
+happen in high-level languages, such as the beginning of a function call or
+a variable's declaration as some type.
+
+Debuggers observe machine execution at the low-level and present a view of
+the changing machine state using the semantics of the high-level language.
+Doing this requires debuggers to keep track of the state of the machine in
+high-level terms and identify when machine instructions modify this state.
+
+This schema provides a means for compilers to represent high-level language
+operations as part of the annotation for individual machine instructions.
+Because of this, this schema inherently lacks a certain runtime completeness
+that might be desirable: e.g., compilers cannot indicate "this instruction
+is where we recurse into this function the first time", because that
+instruction might be used for the first recursion, the second recursion, and
+all the recursions.
+
+:::
+
+
+This format defines a schema for representing state transitions in high-level
+language models of computation.
+
+JSON values in this schema represent the point at which some high-level state
+change has definitely occurred. Values in this schema are designed for
+compilers to include as part of the broader schemas for annotating a specific
+machine instruction.
+
+## Reading this schema
+
+The **ethdebug/format/operation** schema is a root schema that composes
+other related schemas in the ethdebug/format/operation/* namespace.
+
+These schemas (like all schemas in this format) are specified as
+[JSON Schema](https://json-schema.org), draft 2020-12.

packages/web/spec/operation/schema.mdx

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

packages/web/spec/operation/scope/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Scope operations",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Work-in-progress formal schema for ethdebug format"
+  }
+}

packages/web/spec/operation/scope/actions.mdx

@@ -0,0 +1,52 @@
+---
+sidebar_position: 6
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Variable actions
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/operation/scope/actions" }}
+  />
+
+## Declaration actions
+
+### Declare variable as type {#declare}
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/operation/scope/actions" }}
+  pointer="#/$defs/Declare"
+  />
+
+### Undeclare variable {#undeclare}
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/operation/scope/actions" }}
+  pointer="#/$defs/Undeclare"
+  />
+
+## Allocation actions
+
+### Allocate variable at pointer {#allocate}
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/operation/scope/actions" }}
+  pointer="#/$defs/Allocate"
+  />
+
+### Deallocate variable {#deallocate}
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/operation/scope/actions" }}
+  pointer="#/$defs/Deallocate"
+  />
+
+## Assignment action
+
+### Assign variable {#assign}
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/operation/scope/actions" }}
+  pointer="#/$defs/Assign"
+  />

packages/web/spec/operation/scope/begin.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 3
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Begin a new scope
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/operation/scope/begin" }}
+  />

packages/web/spec/operation/scope/end.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 5
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# End a scope
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/operation/scope/end" }}
+  />

packages/web/spec/operation/scope/modify.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 4
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Modify an existing scope
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/operation/scope/modify" }}
+  />

packages/web/spec/operation/scope/scope.mdx

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

packages/web/spec/operation/scope/semantics.mdx

@@ -0,0 +1,5 @@
+---
+sidebar_position: 1
+---
+
+# Semantics of scopes

packages/web/src/schemas.ts

@@ -150,4 +150,30 @@ export const schemaIndex: SchemaIndex = {
     title: "Region reference",
     href: "/spec/pointer/expression#region-references"
   },
+
+  "schema:ethdebug/format/operation/scope": {
+    href: "/spec/operation/scope"
+  },
+
+  ...(
+    ["begin", "modify", "end"].map(action => ({
+      [`schema:ethdebug/format/operation/scope/${action}`]: {
+        href: "/spec/operation/scope/begin"
+      },
+    })).reduce((a, b) => ({ ...a, ...b }), {})
+  ),
+
+  "schema:ethdebug/format/operation/scope/actions": {
+    href: "/spec/operation/scope/actions",
+    title: "Variable actions"
+  },
+
+  ...(
+    ["Declare", "Undeclare", "Allocate", "Deallocate", "Assign"].map(def => ({
+      [`schema:ethdebug/format/operation/scope/actions#/$defs/${def}`]: {
+        title: `${def} variable schema`,
+        href: `/spec/operation/scope/actions#${def.toLowerCase()}`
+      }
+    })).reduce((a, b) => ({ ...a, ...b }), {})
+  ),
 };

schemas/operation.schema.yaml

@@ -0,0 +1,76 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/operation"
+
+title: ethdebug/format/operation
+description:
+  Represents an operation that corresponds to behavior provided by the
+  semantics of a high-level language (such as a variable allocation or a
+  function call)
+
+type: object
+properties:
+  domain:
+    type: string
+
+required: [domain]
+
+if:
+  type: object
+  title: Known domain
+  description:
+    If `domain` adheres to the set of known domains defined by this schema
+  properties:
+    domain:
+      $ref: "#/$defs/Domain"
+
+then:
+  type: object
+  title: Known operation
+  description:
+    Then the object must adhere to the corresponding operation schema for that
+    domain.
+
+  allOf:
+    - if:
+        properties:
+          domain:
+            const: scope
+      then:
+        $ref: "schema:ethdebug/format/operation/scope"
+
+    - if:
+        properties:
+          domain:
+            const: nil
+      then:
+        title: Nil operation
+        description:
+          Indicates that no operation happened
+        unevaluatedProperties: false
+
+else: true
+
+examples:
+  - domain: scope
+    begin:
+      id: __contract__Guestbook__
+    variables:
+      visitors:
+        declare:
+          type:
+            kind: mapping
+            contains:
+              key:
+                type:
+                  kind: address
+                  payable: false
+              value:
+                type:
+                  kind: bool
+
+$defs:
+  Domain:
+    type: string
+    enum:
+      - scope
+      - nil

schemas/operation/scope.schema.yaml

@@ -0,0 +1,69 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/operation/scope"
+
+title: ethdebug/format/operation/scope
+description: |
+  An operation that either begins, modifies, or ends a scope.
+
+type: object
+
+properties:
+  domain:
+    const: scope
+
+required: [domain]
+
+unevaluatedProperties: false
+
+allOf:
+  - oneOf:
+      - required: [begin]
+      - required: [scope]
+      - required: [end]
+  - if:
+      required: [begin]
+    then:
+      $ref: "schema:ethdebug/format/operation/scope/begin"
+
+  - if:
+      required: [scope]
+    then:
+      $ref: "schema:ethdebug/format/operation/scope/modify"
+
+  - if:
+      required: [end]
+    then:
+      $ref: "schema:ethdebug/format/operation/scope/end"
+
+
+examples:
+  - domain: scope
+    begin:
+      id: 1
+      parent:
+        id: 0
+    variables:
+      x:
+        declare:
+          type:
+            kind: uint
+            bits: 256
+        allocate:
+          pointer:
+            location: stack
+            slot: 0
+  - domain: scope
+    scope:
+      id: 1
+    variables:
+      x:
+        assign: true
+  - domain: scope
+    scope:
+      id: 1
+    variables:
+      x:
+        deallocate: true
+  - domain: scope
+    end:
+      id: 1