[wip]

packages/web/package.json

@@ -22,6 +22,7 @@
     "@fortawesome/free-brands-svg-icons": "^6.5.1",
     "@fortawesome/free-solid-svg-icons": "^6.5.1",
     "@fortawesome/react-fontawesome": "^0.2.0",
+    "@hyperjump/json-schema": "1.6.7",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^1.2.1",
     "docusaurus-json-schema-plugin": "^1.11.0",

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

@@ -3,3 +3,48 @@ 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

@@ -9,3 +9,7 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
 <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/base.mdx → packages/web/spec/operation/scope/begin.mdx

@@ -4,8 +4,8 @@ sidebar_position: 3
 
 import SchemaViewer from "@site/src/components/SchemaViewer";
 
-# Base schema
+# Begin a new scope
 
 <SchemaViewer
-  schema={{ id: "schema:ethdebug/format/operation/base" }}
+  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

@@ -6,4 +6,71 @@ 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