From 9471413aa0e8c5130f09da1682dfbcb633838413 Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Mon, 3 Feb 2025 00:11:35 -0500
Subject: [PATCH] Define remark program instruction context

---
 packages/web/spec/program/context/remark.mdx | 15 +++++++++++++++
 packages/web/src/schemas.ts                  |  2 +-
 schemas/program/context.schema.yaml          |  1 +
 schemas/program/context/remark.schema.yaml   | 19 +++++++++++++++++++
 4 files changed, 36 insertions(+), 1 deletion(-)
 create mode 100644 packages/web/spec/program/context/remark.mdx
 create mode 100644 schemas/program/context/remark.schema.yaml

diff --git a/packages/web/spec/program/context/remark.mdx b/packages/web/spec/program/context/remark.mdx
new file mode 100644
index 000000000..7658c363e
--- /dev/null
+++ b/packages/web/spec/program/context/remark.mdx
@@ -0,0 +1,15 @@
+---
+sidebar_position: 6
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Human-readable annotations
+
+Contexts may include a human-readable comment. This feature is included to
+assist in human annotation of **ethdebug/format** data and is not primarily
+for compilers to use.
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/program/context/remark" }}
+  />
diff --git a/packages/web/src/schemas.ts b/packages/web/src/schemas.ts
index 2f9649965..3de8c4edf 100644
--- a/packages/web/src/schemas.ts
+++ b/packages/web/src/schemas.ts
@@ -215,7 +215,7 @@ const programSchemaIndex: SchemaIndex = {
   },
 
   ...(
-    ["code", "variables"].map(name => ({
+    ["code", "variables", "remark"].map(name => ({
       [`schema:ethdebug/format/program/context/${name}`]: {
         href: `/spec/program/context/${name}`
       }
diff --git a/schemas/program/context.schema.yaml b/schemas/program/context.schema.yaml
index 5995bb433..72dca425b 100644
--- a/schemas/program/context.schema.yaml
+++ b/schemas/program/context.schema.yaml
@@ -11,6 +11,7 @@ type: object
 anyOf:
   - $ref: "schema:ethdebug/format/program/context/code"
   - $ref: "schema:ethdebug/format/program/context/variables"
+  - $ref: "schema:ethdebug/format/program/context/remark"
 
 minProperties: 1
 unevaluatedProperties: false
diff --git a/schemas/program/context/remark.schema.yaml b/schemas/program/context/remark.schema.yaml
new file mode 100644
index 000000000..505565418
--- /dev/null
+++ b/schemas/program/context/remark.schema.yaml
@@ -0,0 +1,19 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/program/context/remark"
+
+title: ethdebug/format/program/context/remark
+description: |
+  Human-readable information about the instruction. This field is intended
+  primarily not for compilers to use directly, but rather for humans
+  (directly or indirectly) to use as an annotation field.
+
+type: object
+properties:
+  remark:
+    type: string
+
+required:
+  - remark
+
+examples:
+  - remark: "jump to end if zero"