@openwop/spec-artifacts 2.35.1 → 2.36.0

package/spec/v2/interop-map.schema.json

@@ -0,0 +1,458 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/interop-map.schema.json",
+  "title": "OpenWOP v2 interop map",
+  "description": "RFC 0208 — shape of spec/v2/interop-map.json: the normative rows mapping A2A and MCP upstream operations, states, fields and errors onto the v2 wire. Data, not a wire artifact; kept out of schemas/ like event-codemap.schema.json. Checked by scripts/check-interop-map.mjs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema",
+    "$comment",
+    "version",
+    "updated",
+    "pins",
+    "a2a",
+    "mcp"
+  ],
+  "properties": {
+    "$schema": {
+      "const": "./interop-map.schema.json"
+    },
+    "$comment": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1
+    },
+    "updated": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+    },
+    "pins": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "a2a",
+        "mcp"
+      ],
+      "properties": {
+        "a2a": {
+          "$ref": "#/$defs/pin"
+        },
+        "mcp": {
+          "$ref": "#/$defs/pin"
+        },
+        "mcpTasks": {
+          "$ref": "#/$defs/pin",
+          "description": "RFC 0198."
+        }
+      }
+    },
+    "a2a": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "operations",
+        "card",
+        "taskState",
+        "taskStateReverse",
+        "errors",
+        "fields"
+      ],
+      "properties": {
+        "operations": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/operation"
+          }
+        },
+        "card": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/element"
+          }
+        },
+        "taskState": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/stateRow"
+          },
+          "description": "Forward projection; a total function over RunSnapshot.status (gate-checked)."
+        },
+        "taskStateReverse": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/reverseRow"
+          }
+        },
+        "errors": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/errorRow"
+          }
+        },
+        "fields": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/element"
+          }
+        }
+      }
+    },
+    "mcp": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "features",
+        "methods",
+        "headers",
+        "meta",
+        "mrtr",
+        "cache",
+        "authorization"
+      ],
+      "properties": {
+        "features": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/feature"
+          }
+        },
+        "methods": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/operation"
+          }
+        },
+        "headers": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/element"
+          }
+        },
+        "meta": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/element"
+          }
+        },
+        "mrtr": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/element"
+          }
+        },
+        "cache": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/element"
+          }
+        },
+        "authorization": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/element"
+          }
+        },
+        "tasks": {
+          "type": "object",
+          "description": "RFC 0198.",
+          "additionalProperties": false,
+          "required": [
+            "status",
+            "methods",
+            "fields"
+          ],
+          "properties": {
+            "status": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/taskStatusRow"
+              }
+            },
+            "methods": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/operation"
+              }
+            },
+            "fields": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/element"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "runStatus": {
+      "enum": [
+        "pending",
+        "running",
+        "paused",
+        "waiting-approval",
+        "waiting-input",
+        "waiting-external",
+        "completed",
+        "failed",
+        "cancelling",
+        "cancelled"
+      ],
+      "description": "Gate-checked equal to schemas/v2/run-snapshot.schema.json status.enum."
+    },
+    "pin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "spec"
+      ],
+      "properties": {
+        "release": {
+          "type": "string"
+        },
+        "negotiated": {
+          "type": "string",
+          "pattern": "^[0-9]+\\.[0-9]+$"
+        },
+        "revision": {
+          "type": "string",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+        },
+        "extension": {
+          "type": "string"
+        },
+        "spec": {
+          "type": "string",
+          "format": "uri"
+        },
+        "proto": {
+          "type": "string",
+          "format": "uri"
+        },
+        "schema": {
+          "type": "string",
+          "format": "uri"
+        }
+      }
+    },
+    "operation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "upstream",
+        "v2Operation",
+        "requires",
+        "rule"
+      ],
+      "properties": {
+        "upstream": {
+          "type": "string",
+          "minLength": 1
+        },
+        "http": {
+          "type": "string"
+        },
+        "when": {
+          "type": "string"
+        },
+        "v2Operation": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "An operationId in api/v2/openapi.yaml (gate-checked), or null."
+        },
+        "requires": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][A-Za-z0-9]*\\.[a-z][A-Za-z0-9]*$"
+          },
+          "description": "<family>.<facet>, each a property of spec/v2/facets/<family>.schema.json (gate-checked)."
+        },
+        "rule": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "element": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "element",
+        "rule"
+      ],
+      "properties": {
+        "element": {
+          "type": "string",
+          "minLength": 1
+        },
+        "rule": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "feature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "requiredFor",
+        "meaning"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "requiredFor": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^mcp-[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+          }
+        },
+        "meaning": {
+          "type": "string"
+        }
+      }
+    },
+    "stateRow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "runStatus",
+        "stored",
+        "wire"
+      ],
+      "properties": {
+        "runStatus": {
+          "$ref": "#/$defs/runStatus"
+        },
+        "stored": {
+          "enum": [
+            "submitted",
+            "working",
+            "input-required",
+            "auth-required",
+            "completed",
+            "failed",
+            "canceled",
+            "rejected"
+          ],
+          "description": "Gate-checked against schemas/v2/a2a-task-state.schema.json state.enum."
+        },
+        "wire": {
+          "type": "string",
+          "pattern": "^TASK_STATE_[A-Z_]+$"
+        },
+        "interruptKind": {
+          "type": "string",
+          "description": "Optional. A row with interruptKind overrides the default row for its runStatus when the open interrupt has that kind (RFC 0199 adds credential)."
+        },
+        "carrier": {
+          "type": "string"
+        }
+      }
+    },
+    "reverseRow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "wire",
+        "runStatus"
+      ],
+      "properties": {
+        "wire": {
+          "type": "string",
+          "pattern": "^TASK_STATE_[A-Z_]+$"
+        },
+        "runStatus": {
+          "$ref": "#/$defs/runStatus"
+        },
+        "note": {
+          "type": "string"
+        }
+      }
+    },
+    "errorRow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "upstream",
+        "jsonrpc",
+        "grpc",
+        "http",
+        "serverWhen",
+        "clientProjection"
+      ],
+      "properties": {
+        "upstream": {
+          "type": "string"
+        },
+        "jsonrpc": {
+          "type": "integer"
+        },
+        "grpc": {
+          "enum": [
+            "NOT_FOUND",
+            "FAILED_PRECONDITION",
+            "INVALID_ARGUMENT",
+            "INTERNAL",
+            "UNIMPLEMENTED"
+          ]
+        },
+        "http": {
+          "type": "integer",
+          "minimum": 400,
+          "maximum": 599
+        },
+        "serverWhen": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "clientProjection": {
+          "type": "string",
+          "description": "A code in spec/v2/errors.json (gate-checked)."
+        },
+        "note": {
+          "type": "string"
+        }
+      }
+    },
+    "taskStatusRow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "runStatus",
+        "taskStatus"
+      ],
+      "properties": {
+        "runStatus": {
+          "$ref": "#/$defs/runStatus"
+        },
+        "taskStatus": {
+          "enum": [
+            "working",
+            "input_required",
+            "completed",
+            "failed",
+            "cancelled"
+          ]
+        },
+        "note": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/spec/v2/migrations.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "./migrations.schema.json",
+  "$comment": "RFC 0197 §A.2 R1 — the v2→v2 migration register. EMPTY is the correct state at 2.36.0: no 2.x minor has yet replaced a v2 surface, and nothing is scheduled for removal inside the major. The register exists ahead of its first row because R1 cannot be checked without it — a retirement row with no migration row to point at is refused by scripts/check-deprecations.mjs rule 6. The first row this expects is connection-pack `transport: \"streamable-http\"` beside `\"sse\"` (RFC 0197 §\"What this RFC enables next\"), filed as its own RFC with a fresh registry census.",
+  "version": 1,
+  "updated": "2026-09-22",
+  "rows": []
+}

package/spec/v2/migrations.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/migrations.schema.json",
+  "title": "OpenWOP v2→v2 migration register",
+  "description": "Shape of spec/v2/migrations.json (RFC 0197 §A.2 R1). One row per surface a 2.x minor REPLACES or RETIRES inside the major: the old surface, the new one, the minor the new one shipped in, and the spec/v1/deprecations.json `v2-minor` row that schedules the removal. This is not the v1→v2 program: spec/v1/migrations.schema.json keeps its C1–C11 child grammar, which is that program's identity. `rows` may be EMPTY — an empty v2→v2 register is a legal state, and is the state at 2.36.0. Data, not a wire artifact; kept out of schemas/. Validated by scripts/check-migrations.mjs; read by scripts/check-v2-retirement.mjs (R1) and scripts/check-v2-surface-monotone.mjs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "version", "updated", "rows"],
+  "properties": {
+    "$schema": { "type": "string", "const": "./migrations.schema.json" },
+    "$comment": { "type": "string" },
+    "version": { "type": "integer", "const": 1 },
+    "updated": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "rows": {
+      "type": "array",
+      "minItems": 0,
+      "items": { "$ref": "#/$defs/row" },
+      "description": "`minItems: 0`, unlike the v1 register: the v2→v2 program starts with nothing to say, and a register forced to carry a row would be filled with a fiction."
+    }
+  },
+  "$defs": {
+    "row": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "rfc", "kind", "from", "to", "deprecationId", "codemod", "persistedData", "requirementIds"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^openwop\\.migration\\.v2\\.[0-9]+$", "description": "openwop.migration.v2.<n>. The `v2` segment keeps these rows out of the C1–C11 id space scripts/check-migrations.mjs matches against child RFC tables." },
+        "rfc": { "type": "string", "pattern": "^[0-9]{4}$", "description": "The RFC that added the replacement and filed the row." },
+        "kind": { "type": "string", "enum": ["replace", "retire"], "description": "`replace` — a new surface shipped beside the old one and the old one is scheduled out (RFC 0197 §A.1: a new shape is a NEW surface, never a reshape). `retire` — no replacement; admitted only when R1 is satisfied some other way, and today that means it is not admitted at all (RFC 0197 Unresolved 3)." },
+        "from": { "$ref": "#/$defs/surface", "description": "The surface being retired." },
+        "to": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["surface", "addedIn"],
+          "properties": {
+            "surface": { "type": "string", "minLength": 1, "description": "The replacement's wire-visible name." },
+            "path": { "type": "string", "description": "Where the replacement lives: a JSON pointer or dotted path in a schema under schemas/v2/, or a spec/v2/ file path." },
+            "addedIn": { "type": "string", "pattern": "^2\\.[0-9]+$", "description": "RFC 0197 R1 — the 2.x minor the replacement SHIPPED in. It MUST be lower than the linked deprecation row's `removeIn` minor: a replacement that ships in the same minor as the removal gives no one a window to move." }
+          }
+        },
+        "deprecationId": { "type": "string", "pattern": "^openwop\\.deprecation\\.[a-z0-9]+(-[a-z0-9]+)*$", "description": "The spec/v1/deprecations.json row — `removalTrigger` containing `v2-minor` — that schedules the removal. Exactly one migration row per deprecation row (scripts/check-deprecations.mjs)." },
+        "codemod": { "type": ["string", "null"], "pattern": "^openwop\\.codemod\\.[a-z0-9]+(-[a-z0-9]+)*$", "description": "Id of the committed codemod under codemods/<id>/ that rewrites a persisted or emitted artifact, or null when nothing persisted carries the surface." },
+        "persistedData": { "type": "string", "enum": ["unchanged", "translated", "drained", "legacy-stamped", "never-upgraded", "not-persisted"], "description": "Same vocabulary as the v1 register: what happens to data already persisted under the retired surface. RFC 0197 §A.3 means a reader keeps accepting it for the life of the major, so `never-upgraded` and `unchanged` are the common answers." },
+        "requirementIds": { "type": "array", "items": { "type": "string", "pattern": "^openwop\\." }, "description": "conformance/requirements.json ids that witness the replacement." },
+        "note": { "type": "string" }
+      }
+    },
+    "surface": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["surface"],
+      "properties": {
+        "surface": { "type": "string", "minLength": 1 },
+        "path": { "type": "string", "description": "A JSON pointer or dotted path locating it in the v2 tree, in the form scripts/check-v2-surface-monotone.mjs prints: `<file>#<pointer>`." }
+      }
+    }
+  }
+}

package/spec/v2/path-manifest.json

@@ -266,6 +266,11 @@
       "path": "/webhooks/{webhookId}/dead-letters",
       "operationId": "listWebhookDeadLetters"
     },
+    {
+      "method": "POST",
+      "path": "/webhooks/{webhookId}/rotate-secret",
+      "operationId": "rotateWebhookSecret"
+    },
     {
       "method": "GET",
       "path": "/workflows/{workflowId}",
@@ -283,7 +288,7 @@
     }
   ],
   "counts": {
-    "operations": 53,
+    "operations": 54,
     "channels": 2
   }
 }

package/spec/v2/release.json

@@ -1,6 +1,6 @@
 {
   "$comment": "RFC 0172 §D.1 — the one release identity the v2 artifacts derive from. `version` is the next corpus tag `v<version>` (the publish workflow's coordinated-release tag pattern `v*`; RFC 0172's `openwop/v2.<minor>.<patch>` spelling is amended to this at its flip). api/v2/*.yaml info.version, the suite's 2.x version and @openwop/spec-artifacts read it. Bumped by the release PR that cuts the tag, never by hand elsewhere.",
-  "version": "2.35.0",
-  "corpusTag": "v2.35.0",
-  "updated": "2026-09-21"
+  "version": "2.36.0",
+  "corpusTag": "v2.36.0",
+  "updated": "2026-09-23"
 }