Document command simulation contracts

README.md

@@ -35,3 +35,8 @@ The authenticated WebAssembly plugin lifecycle uses the manifest, install,
 and installed-response contracts. Fixtures contain only synthetic package
 metadata and no executable module or secret.
 
+Command simulation uses `bot-command-simulate-request.json` and
+`bot-command-simulate-response.json`. A sample response is the default and
+real network requests require an explicit `use_real_request` flag; fixtures
+contain only local synthetic data.
+

contracts/v1/bot-command-simulate-request.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trixie.invalid/contracts/v1/bot-command-simulate-request.json",
+  "title": "Trixie bot command simulation request",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["template"],
+  "properties": {
+    "template": { "type": "string", "minLength": 1, "maxLength": 2000 },
+    "variables": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2000 } },
+    "web_request": { "type": ["object", "null"] },
+    "sample_response": {},
+    "use_real_request": { "type": "boolean", "default": false },
+    "response_fields": {
+      "type": "array",
+      "maxItems": 128,
+      "items": {
+        "type": "array",
+        "prefixItems": [
+          { "type": "string", "minLength": 1, "maxLength": 64 },
+          { "type": "string", "minLength": 1, "maxLength": 256 }
+        ],
+        "items": false,
+        "minItems": 2,
+        "maxItems": 2
+      }
+    }
+  }
+}

contracts/v1/bot-command-simulate-response.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trixie.invalid/contracts/v1/bot-command-simulate-response.json",
+  "title": "Trixie bot command simulation response",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["status", "extracted_variables"],
+  "properties": {
+    "status": { "const": "ok" },
+    "rendered": { "type": ["string", "null"], "maxLength": 2000 },
+    "extracted_variables": { "type": "object", "additionalProperties": { "type": "string" } },
+    "error": { "type": ["string", "null"], "maxLength": 500 }
+  }
+}

fixtures/v1/bot-command-simulate-request.json

@@ -0,0 +1,7 @@
+{
+  "template": "Hello ${user_name}; status=${status}",
+  "variables": { "user_name": "PreviewUser" },
+  "sample_response": { "status": "ok" },
+  "use_real_request": false,
+  "response_fields": [["status", "$.status"]]
+}

fixtures/v1/bot-command-simulate-response.json

@@ -0,0 +1,6 @@
+{
+  "status": "ok",
+  "rendered": "Hello PreviewUser; status=ok",
+  "extracted_variables": { "status": "ok" },
+  "error": null
+}