[wip]

packages/tests/schemas/examples.test.ts

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

packages/web/notes

@@ -0,0 +1,22 @@
+ethdebug/format/operation
+ /scope/begin
+ /scope/end
+ /scope/declare
+ /scope/assign
+ /scope/allocate
+ /scope/delete
+
+
+begin
+ **defines scope id (debugger action: push new stack frame for that scope ID)
+ may inherit from another scope id
+ may declare variables
+ may assign variables
+ may allocate variables
+
+
+scope: begin
+id: ...
+declare:
+ x:
+ type:

packages/web/package.json

@@ -4,7 +4,7 @@
  "private": true,
  "scripts": {
  "docusaurus": "docusaurus",
- "start": "docusaurus start",
+ "start": "docusaurus start --host 0.0.0.0",
  "build": "docusaurus build",
  "swizzle": "docusaurus swizzle",
  "deploy": "docusaurus deploy",
@@ -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/_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