@openwop/spec-artifacts 2.35.1 → 2.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwop/spec-artifacts",
-  "version": "2.35.1",
+  "version": "2.36.0",
   "description": "The OpenWOP machine-readable contract: api/ (OpenAPI, AsyncAPI, the seams profile), schemas/ (v1 and v2 JSON Schemas), the spec/v1 and spec/v2 registries (errors, event codemap, declaration, deprecations, migrations, gaps) and CORPUS-STAMP.json — published from the openwop/openwop corpus tag; the peer dependency @openwop/openwop-conformance digest-checks at start (RFC 0168 §D.2).",
   "license": "Apache-2.0",
   "repository": {

package/schemas/a2a-task-state.schema.json

@@ -24,12 +24,12 @@
     "state": {
       "type": "string",
       "enum": ["submitted", "working", "input-required", "auth-required", "completed", "failed", "canceled", "rejected"],
-      "description": "The A2A 0.3 JSON-RPC wire form (lowercase-hyphen — a2a-integration.md §'Wire-shape spelling drift'). Projected from `run.status` per a2a-integration.md §'State projection (forward)': pending→submitted, running→working, paused→working, waiting-approval/waiting-input→input-required, completed→completed, failed→failed, cancelled→canceled. `auth-required` is carried for reverse-direction fidelity only; the forward projection never sets it (openwop has no native auth interrupt — a2a-integration.md drift point #3)."
+      "description": "The canonical stored vocabulary: lowercase-hyphen, the spelling A2A 0.3's JSON-RPC binding uses (a2a-integration.md §'Wire-shape spelling drift'). An A2A 1.0 interface renders it as `TASK_STATE_*` at the boundary through the a2a-integration.md §D.4 bijection; the stored form does not change. Projected from `run.status` per a2a-integration.md §'State projection (forward)' and §D.4: pending→submitted; running, paused and cancelling (RFC 0094, until terminal)→working; waiting-approval, waiting-input and waiting-external→input-required; completed→completed; failed→failed; cancelled→canceled. `auth-required` is set by the forward projection only for a run suspended on a `credential` interrupt (RFC 0199 §D.1; a2a-integration.md drift point #3 is retired for the forward direction) and is otherwise carried for reverse-direction fidelity."
     },
     "interruptKind": {
       "type": "string",
-      "enum": ["approval", "clarification"],
-      "description": "Present iff `state == 'input-required'`. Disambiguates a2a-integration.md drift point #2 (both approval + clarification project to INPUT_REQUIRED) — carried in `Task.metadata.openwop.interrupt.kind`, the `metadata.openwop.*` shape the doc's Future-work asks to codify."
+      "enum": ["approval", "clarification", "credential"],
+      "description": "Present iff `state` is `input-required` or `auth-required`; `credential` ⇔ `auth-required` in the forward direction (RFC 0199 §D.1) — a rule stated in the prose of a2a-integration.md §'The durable Task projection record'; this schema does not enforce it (the field is not in `required` and there is no conditional). Disambiguates a2a-integration.md drift point #2 (approval and clarification both project to INPUT_REQUIRED) — carried in `Task.metadata.openwop.interrupt.kind`, the `metadata.openwop.*` shape the doc's Future-work asks to codify. The enum names only `approval`, `clarification` and `credential`: a `waiting-external` run, which also projects to input-required, has no value here, and its kind is disambiguated by the `metadata.openwop.interrupt.kind` carrier alone."
     },
     "updatedAt": {
       "type": "string",

package/schemas/artifact-type-pack-manifest.schema.json

@@ -142,11 +142,11 @@
           "items": {
             "type": "string",
             "minLength": 1,
-            "maxLength": 64,
-            "pattern": "^([a-z][a-z0-9]*|vendor\\.[a-z][a-z0-9-]*\\.[a-z][a-z0-9-]*|x-[a-z][a-z0-9-]*)$"
+            "maxLength": 255,
+            "pattern": "^([a-z][a-z0-9]*|vendor\\.[a-z][a-z0-9-]*\\.[a-z][a-z0-9-]*|x-[a-z][a-z0-9-]*|[a-z0-9][a-z0-9!#$&^_.+-]{0,126}/[a-z0-9][a-z0-9!#$&^_.+-]{0,126})$"
           },
           "uniqueItems": true,
-          "description": "Export-format identifiers (hints) a renderer MAY offer. Spec-reserved core identifiers carry interoperable meaning (the lowercase file-extension / common name): `pdf`, `pptx`, `docx`, `xlsx`, `md`, `html`, `txt`, `csv`, `json`, `png`, `svg`, `jpeg`, `step`, `stl`, `dxf`. Domain-specific formats outside the core set MUST be `vendor.<org>.<format>`- or `x-<format>`-prefixed (mirrors the `requiredModelCapabilities` reserved-core + extension idiom). Advisory: this spec assigns no byte-level production semantics to any identifier — it standardizes the identifier so two hosts agree what `pptx` names, not how the bytes are produced."
+          "description": "Export-format identifiers (hints) a renderer MAY offer. Spec-reserved core identifiers carry interoperable meaning (the lowercase file-extension / common name): `pdf`, `pptx`, `docx`, `xlsx`, `md`, `html`, `txt`, `csv`, `json`, `png`, `svg`, `jpeg`, `step`, `stl`, `dxf`. Domain-specific formats outside the core set MUST be `vendor.<org>.<format>`- or `x-<format>`-prefixed (mirrors the `requiredModelCapabilities` reserved-core + extension idiom). An entry MAY instead be a lowercase RFC 6838 media type (`type/subtype`, no parameters; RFC 0205 §C); each reserved alias names exactly one media type per artifact-type-packs.md §\"Export-format aliases\", and a consumer MUST treat the two spellings as one format. Advisory: this spec assigns no byte-level production semantics to any identifier — it standardizes the identifier so two hosts agree what `pptx` names, not how the bytes are produced."
         },
         "syncOn": {
           "type": "string",

package/schemas/capabilities.schema.json

@@ -877,6 +877,10 @@
           "uniqueItems": true,
           "description": "OAuth 2.0 grant types the host performs on a node's behalf."
         },
+        "credentialInterrupt": {
+          "type": "boolean",
+          "description": "RFC 0199 §C. The host suspends a node on a `credential` interrupt instead of failing it when no credential resolves or refresh fails terminally. Absent ⇒ RFC 0047 §C.3 (fail the node with `connector_auth_expired`)."
+        },
         "providers": {
           "type": "array",
           "description": "Provider catalog the host can acquire tokens for. A connector node's `auth.provider` MUST match an `id` here.",
@@ -907,6 +911,19 @@
                   "type": "string"
                 },
                 "description": "Scopes this provider exposes."
+              },
+              "issuer": {
+                "type": "string",
+                "format": "uri",
+                "description": "RFC 0199 §A.4. The provider's authorization-server issuer identifier (RFC 8414 / RFC 9207). Absent ⇒ the host uses a provider-unique redirect URI (RFC 9700 §4.4.2.2)."
+              },
+              "pkce": {
+                "type": "string",
+                "enum": [
+                  "S256",
+                  "unsupported"
+                ],
+                "description": "RFC 0199 §A.1. Absent or `S256` ⇒ the host sends PKCE S256. `unsupported` ⇒ the host sends no PKCE for this provider; such a provider cannot back an MCP reach (§B.2)."
               }
             },
             "additionalProperties": false
@@ -2741,11 +2758,27 @@
             "type": "string"
           },
           "uniqueItems": true,
-          "description": "HMAC signature algorithm ids the host supports (e.g. `v1`)."
+          "description": "HMAC signature algorithm ids the host supports (e.g. `v1`). `standard-webhooks-1` (RFC 0201) names the Standard Webhooks 1.0.0 companion scheme a subscriber opts into per subscription; it is listed only beside `v1`."
         },
         "durable": {
           "type": "boolean",
           "description": "RFC 0083 §A — OPTIONAL opt-in. `true` ⇒ webhook delivery is durable (a trigger-bridge source); absent/`false` ⇒ the best-effort `webhooks.md` contract, unchanged. The best-effort default is NOT relaxed."
+        },
+        "secretRotation": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "overlapSeconds"
+          ],
+          "description": "RFC 0201 §E — zero-downtime secret rotation for subscriptions opted into `standard-webhooks-1`. Advertised only by a host that serves `POST /v1/webhooks/{webhookId}/rotate-secret`.",
+          "properties": {
+            "overlapSeconds": {
+              "type": "integer",
+              "minimum": 60,
+              "maximum": 604800,
+              "description": "How long after a rotation `webhook-signature` carries an entry under the previous secret beside the new one."
+            }
+          }
         }
       }
     },

package/schemas/connection-pack-manifest.schema.json

@@ -218,6 +218,20 @@
             "instanceUrlTemplate": {
               "type": "string",
               "description": "For per-account-host providers (Snowflake/NetSuite/ServiceNow): a template the host fills per connection, e.g. `https://{account}.snowflakecomputing.com`. Its presence signals the provider cannot use a single global OAuth app."
+            },
+            "issuer": {
+              "type": "string",
+              "format": "uri",
+              "pattern": "^https://",
+              "description": "RFC 0199 §A.4/§B.3. The authorization server's issuer identifier. Fixed and manifest-declared, like `endpoints`. OPTIONAL in the schema; a host MUST NOT authorize a `reach.mcp` + `oauth2` provider whose manifest omits it (refused `connection_auth_metadata_mismatch` before any authorization URL is issued)."
+            },
+            "pkce": {
+              "type": "string",
+              "enum": [
+                "S256",
+                "unsupported"
+              ],
+              "description": "RFC 0199 §A.1. Absent or `S256` ⇒ the host sends PKCE S256. `unsupported` ⇒ no PKCE; a host MUST NOT authorize such a provider when it is reached as an MCP server (§B.2)."
             }
           }
         },

package/schemas/debug-bundle.schema.json

@@ -122,7 +122,27 @@
         "required": ["name"],
         "properties": {
           "name": { "type": "string", "minLength": 1 },
+          "traceId": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{32}$",
+            "not": { "const": "00000000000000000000000000000000" },
+            "description": "RFC 0207 §C — W3C Trace Context / OTLP 16-byte trace id (32 lowercase hex) of the trace this span belongs to. SHOULD be present when the span was recorded in a trace; when present it MUST equal that trace's id."
+          },
           "spanId": { "type": "string" },
+          "kind": {
+            "enum": ["internal", "server", "client", "producer", "consumer"],
+            "description": "RFC 0207 §C — OTLP SPAN_KIND_* 1–5, lowercased. Absent means unspecified."
+          },
+          "status": {
+            "type": "object",
+            "required": ["code"],
+            "properties": {
+              "code": { "enum": ["unset", "ok", "error"] },
+              "message": { "type": "string" }
+            },
+            "additionalProperties": false,
+            "description": "RFC 0207 §C — OTLP Status (STATUS_CODE_* 0–2). message is redacted like every attribute."
+          },
           "parentSpanId": {
             "oneOf": [{ "type": "string" }, { "type": "null" }]
           },

package/schemas/dispatch-config.schema.json

@@ -16,7 +16,7 @@
       "type": "string",
       "enum": ["child-run"],
       "default": "child-run",
-      "description": "How `kind: 'next-worker'` is dispatched. v1.x normates only `'child-run'` — each `nextWorkerIds[i]` resolves to a workflow id and is dispatched as a child run via the existing `core.subWorkflow` machinery. Same-run DAG navigation is OUT OF SCOPE for v1.x (deferred to RFC 0013 / v1.3+). Hosts MAY add vendor-extension dispatch models under `vendor.<host>.<model>`; conformance scenarios validate `'child-run'` only."
+      "description": "How `kind: 'next-worker'` is dispatched. v1.x normates only `'child-run'` — each `nextWorkerIds[i]` resolves to a workflow id and is dispatched as a child run via the existing `core.subWorkflow` machinery. Same-run DAG navigation is OUT OF SCOPE for v1.x (deferred to RFC 0013 / v1.3+). The enum is closed: any other value, including a `vendor.<host>.<model>` name, fails validation against this schema, so a host cannot add a dispatch model without an additive schema change. Conformance scenarios validate `'child-run'` only."
     },
     "fanOutPolicy": {
       "type": "string",

package/schemas/localized-content-language-settings.schema.json

@@ -9,13 +9,13 @@
   "properties": {
     "baseLocale": {
       "type": "string",
-      "pattern": "^[a-z]{2}(-[A-Z]{2})?$",
+      "pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$",
       "description": "The locale section `data` is authored in. MUST equal `capabilities.i18n.defaultLocale`."
     },
     "supportedLocales": {
       "type": "array",
-      "description": "BCP-47 tags the tenant authors content translations for. MUST NOT contain `baseLocale`.",
-      "items": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" },
+      "description": "Case-canonical BCP 47 tags (RFC 0206 §A) the tenant authors content translations for. MUST NOT contain `baseLocale`.",
+      "items": { "type": "string", "pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$" },
       "uniqueItems": true
     },
     "autoTranslateOnPublish": {

package/schemas/localized-content-page.schema.json

@@ -45,7 +45,7 @@
             "additionalProperties": false,
             "required": ["locale", "href"],
             "properties": {
-              "locale": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" },
+              "locale": { "type": "string", "pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$" },
               "href": { "type": "string", "format": "uri" }
             }
           }
@@ -53,7 +53,7 @@
         "ogLocaleAlternates": {
           "type": "array",
           "description": "og:locale:alternate values.",
-          "items": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" },
+          "items": { "type": "string", "pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$" },
           "uniqueItems": true
         }
       }

package/schemas/localized-content-section.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openwop.dev/spec/v1/localized-content-section.schema.json",
   "title": "LocalizedContentSection",
-  "description": "RFC 0103 (spec/v1/localized-content.md §B). One section record of an authored content page. A section is ONE record carrying a base `data` payload (authored in the host's `content.baseLocale`) plus a sparse `localizations` map of partial per-locale field overrides — never one record per locale. The negotiated locale's resolved body is computed by the normative per-section field merge (exact-locale → language-family → base `data`, shallow overlay; §C). Body field shapes inside `data`/`localizations` are open and host/section-type-defined; this schema closes the envelope, not the body.",
+  "description": "RFC 0103 (spec/v1/localized-content.md §B). One section record of an authored content page. A section is ONE record carrying a base `data` payload (authored in the host's `content.baseLocale`) plus a sparse `localizations` map of partial per-locale field overrides — never one record per locale. The negotiated locale's resolved body is computed by the normative per-section field merge (exact-locale → script-family (RFC 0206) → language-family → base `data`, shallow overlay; §C). Body field shapes inside `data`/`localizations` are open and host/section-type-defined; this schema closes the envelope, not the body.",
   "type": "object",
   "additionalProperties": false,
   "required": ["sectionId", "sectionType", "data", "localizations", "status", "enabled", "order"],
@@ -24,9 +24,9 @@
     },
     "localizations": {
       "type": "object",
-      "description": "Sparse map of per-locale partial field overrides. MAY be empty (`{}`). Each key is a BCP-47 tag matching `^[a-z]{2}(-[A-Z]{2})?$` and MUST NOT equal `content.baseLocale` (the base locale is carried by `data`). Each value is a partial overlay of `data` fields; missing fields fall through to `data` (per-section merge §C).",
+      "description": "Sparse map of per-locale partial field overrides. MAY be empty (`{}`). Each key is a case-canonical BCP 47 tag (language, optional script, optional region; RFC 0206 §A) matching `^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$` and MUST NOT equal `content.baseLocale` (the base locale is carried by `data`). Each value is a partial overlay of `data` fields; missing fields fall through to `data` (per-section merge §C).",
       "propertyNames": {
-        "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
+        "pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$"
       },
       "additionalProperties": {
         "type": "object",

package/schemas/run-event-payloads.schema.json

@@ -1263,7 +1263,8 @@
             "conversation.start",
             "conversation.exchange",
             "conversation.close",
-            "low-confidence"
+            "low-confidence",
+            "credential"
           ],
           "description": "RFC 0094 \u00a7E \u2014 the full kind union `interrupt.md` defines (mirrors suspend-request.schema.json). Conversation kinds are gated on the conversation capability per capabilities.md."
         },
@@ -1673,7 +1674,8 @@
             "conversation.start",
             "conversation.exchange",
             "conversation.close",
-            "low-confidence"
+            "low-confidence",
+            "credential"
           ],
           "description": "RFC 0094 \u00a7E \u2014 the full kind union `interrupt.md` defines (mirrors suspend-request.schema.json). Conversation kinds are gated on the conversation capability per capabilities.md."
         },

package/schemas/suspend-request.schema.json

@@ -8,8 +8,8 @@
   "properties": {
     "kind": {
       "type": "string",
-      "enum": ["approval", "clarification", "external-event", "custom", "conversation.start", "conversation.exchange", "conversation.close", "low-confidence"],
-      "description": "Discriminator for resume-time routing + UI rendering + observability. Multi-Agent Shift Phase 4 adds `conversation.start` / `conversation.exchange` / `conversation.close` for multi-turn user interjections (see ConversationStartData / ConversationExchangeData / ConversationCloseData below). Phase 1 adds `low-confidence` for the confidence-escalation contract (orchestrator-supervisor suspends below threshold; see LowConfidenceData)."
+      "enum": ["approval", "clarification", "external-event", "custom", "conversation.start", "conversation.exchange", "conversation.close", "low-confidence", "credential"],
+      "description": "Discriminator for resume-time routing + UI rendering + observability. Multi-Agent Shift Phase 4 adds `conversation.start` / `conversation.exchange` / `conversation.close` for multi-turn user interjections (see ConversationStartData / ConversationExchangeData / ConversationCloseData below). Phase 1 adds `low-confidence` for the confidence-escalation contract (orchestrator-supervisor suspends below threshold; see LowConfidenceData). RFC 0199 adds `credential` (see CredentialData), gated on `oauth.credentialInterrupt`."
     },
     "key": {
       "type": "string",
@@ -27,7 +27,8 @@
       "description": "Optional auto-reject after this duration. Engine throws InterruptTimeoutError when exceeded."
     },
     "data": {
-      "oneOf": [
+      "description": "Discriminated payload data. The union below lists every per-kind shape; the root `allOf` binds each `kind` to exactly one of them (`interrupt.md` §Per-kind payloads). `anyOf`, not `oneOf`: the shapes are not mutually exclusive by content — a minimal `conversation.start` and `conversation.close` payload are both `{ conversationId }` — so `kind`, not the data, is the discriminator. Before 2.36.0 this was an unbound `oneOf`, which rejected those two minimal payloads and accepted a payload whose `data` matched a different kind's shape (COMPATIBILITY.md §3, 2026-09-22).",
+      "anyOf": [
         { "$ref": "#/$defs/ApprovalData" },
         { "$ref": "#/$defs/ClarificationData" },
         { "$ref": "#/$defs/ExternalEventData" },
@@ -35,11 +36,24 @@
         { "$ref": "#/$defs/ConversationStartData" },
         { "$ref": "#/$defs/ConversationExchangeData" },
         { "$ref": "#/$defs/ConversationCloseData" },
-        { "$ref": "#/$defs/LowConfidenceData" }
+        { "$ref": "#/$defs/LowConfidenceData" },
+        { "$ref": "#/$defs/CredentialData" }
       ]
     }
   },
   "additionalProperties": false,
+  "$comment": "Binds `data` to `kind`: one if/then per kind, so every kind accepts exactly its own per-kind shape and a payload whose `data` belongs to another kind fails.",
+  "allOf": [
+    { "if": { "properties": { "kind": { "const": "approval" } }, "required": ["kind"] }, "then": { "properties": { "data": { "$ref": "#/$defs/ApprovalData" } } } },
+    { "if": { "properties": { "kind": { "const": "clarification" } }, "required": ["kind"] }, "then": { "properties": { "data": { "$ref": "#/$defs/ClarificationData" } } } },
+    { "if": { "properties": { "kind": { "const": "external-event" } }, "required": ["kind"] }, "then": { "properties": { "data": { "$ref": "#/$defs/ExternalEventData" } } } },
+    { "if": { "properties": { "kind": { "const": "custom" } }, "required": ["kind"] }, "then": { "properties": { "data": { "$ref": "#/$defs/CustomData" } } } },
+    { "if": { "properties": { "kind": { "const": "conversation.start" } }, "required": ["kind"] }, "then": { "properties": { "data": { "$ref": "#/$defs/ConversationStartData" } } } },
+    { "if": { "properties": { "kind": { "const": "conversation.exchange" } }, "required": ["kind"] }, "then": { "properties": { "data": { "$ref": "#/$defs/ConversationExchangeData" } } } },
+    { "if": { "properties": { "kind": { "const": "conversation.close" } }, "required": ["kind"] }, "then": { "properties": { "data": { "$ref": "#/$defs/ConversationCloseData" } } } },
+    { "if": { "properties": { "kind": { "const": "low-confidence" } }, "required": ["kind"] }, "then": { "properties": { "data": { "$ref": "#/$defs/LowConfidenceData" } } } },
+    { "if": { "properties": { "kind": { "const": "credential" } }, "required": ["kind"] }, "then": {"required": ["resumeSchema"], "properties": {"data": {"$ref": "#/$defs/CredentialData"}, "resumeSchema": {"const": {"type": "object", "additionalProperties": false, "required": ["outcome"], "properties": {"outcome": {"enum": ["authorized", "declined"]}}}}}} }
+  ],
   "$defs": {
     "ApprovalData": {
       "type": "object",
@@ -202,6 +216,49 @@
         "decision": { "description": "Optional sketch of the decision the agent WOULD have emitted at threshold-or-above. Lets operators see the un-ratified choice. Shape mirrors `OrchestratorDecision` or the agent's domain-specific decision type." }
       },
       "additionalProperties": false
+    },
+    "CredentialData": {
+      "type": "object",
+      "description": "Payload for kind='credential' (RFC 0199 §C.3). Closed: it names the provider, scopes and reason and carries the host-owned `connectUrl`; it NEVER carries credential material, the interrupt's token, or any value that resolves the interrupt. Gated on `oauth.credentialInterrupt`.",
+      "required": [
+        "provider",
+        "scopes",
+        "reason",
+        "connectUrl"
+      ],
+      "properties": {
+        "provider": {
+          "type": "string",
+          "minLength": 1,
+          "description": "An advertised `oauth.providers[].id`."
+        },
+        "scopes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "reason": {
+          "enum": [
+            "missing",
+            "expired",
+            "insufficient_scope"
+          ]
+        },
+        "connectUrl": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^https://",
+          "description": "Host-owned https URL on the host's own origin that begins the authorization-code grant for the interrupt's initiating Subject. MUST NOT be pre-authenticated and MUST NOT embed the interrupt token."
+        },
+        "credentialRef": {
+          "$ref": "credential-reference.schema.json",
+          "description": "The reference being re-authorized; never material."
+        }
+      },
+      "additionalProperties": false
     }
   }
 }

package/schemas/v2/a2a-task-state.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openwop.dev/spec/v2/a2a-task-state.schema.json",
   "title": "A2ATaskState",
-  "description": "RFC 0100 \u00a72. The durable, persisted projection of an A2A `Task` an OpenWOP host keeps per backing run when it advertises `capabilities.a2a.durableTasks: true` \u2014 durable for the run's whole lifecycle (surviving caller disconnect, host restart within retention, and HITL pauses) so `tasks/get` returns live state after a disconnect. It is the persisted form of the `a2a-integration.md` \u00a7\"State projection (forward)\" mapping, NOT a new mapping. Content-free of run inputs/outputs/artifacts/credential material (SR-1 / `a2a-integration.md` trust boundary) \u2014 artifacts project to A2A `Artifact`s over the A2A transport, not into this record.",
+  "description": "RFC 0100 §2. The durable, persisted projection of an A2A `Task` an OpenWOP host keeps per backing run when it advertises `capabilities.a2a.durableTasks: true` — durable for the run's whole lifecycle (surviving caller disconnect, host restart within retention, and HITL pauses) so `tasks/get` returns live state after a disconnect. It is the persisted form of the `a2a-integration.md` §\"State projection (forward)\" mapping, NOT a new mapping. Content-free of run inputs/outputs/artifacts/credential material (SR-1 / `a2a-integration.md` trust boundary) — artifacts project to A2A `Artifact`s over the A2A transport, not into this record.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -15,7 +15,7 @@
     "taskId": {
       "type": "string",
       "minLength": 1,
-      "description": "The A2A Task.id. MUST equal the backing OpenWOP `runId` (a2a-integration.md \u00a72 \u2014 'the returned runId becomes the A2A Task.id')."
+      "description": "The A2A Task.id. MUST equal the backing OpenWOP `runId` (a2a-integration.md §2 — 'the returned runId becomes the A2A Task.id')."
     },
     "runId": {
       "$ref": "ids.schema.json#/$defs/runId",
@@ -23,7 +23,7 @@
     },
     "contextId": {
       "type": "string",
-      "description": "The A2A context_id (carried as the run tag `a2a:ctx_*` per a2a-integration.md \u00a72)."
+      "description": "The A2A context_id (carried as the run tag `a2a:ctx_*` per a2a-integration.md §2)."
     },
     "state": {
       "type": "string",
@@ -37,15 +37,16 @@
         "canceled",
         "rejected"
       ],
-      "description": "The A2A 0.3 JSON-RPC wire form (lowercase-hyphen \u2014 a2a-integration.md \u00a7'Wire-shape spelling drift'). Projected from `run.status` per a2a-integration.md \u00a7'State projection (forward)': pending\u2192submitted, running\u2192working, paused\u2192working, waiting-approval/waiting-input\u2192input-required, completed\u2192completed, failed\u2192failed, cancelled\u2192canceled. `auth-required` is carried for reverse-direction fidelity only; the forward projection never sets it (openwop has no native auth interrupt \u2014 a2a-integration.md drift point #3)."
+      "description": "The canonical stored vocabulary: lowercase-hyphen, the spelling A2A 0.3's JSON-RPC binding uses (a2a-integration.md §'Wire-shape spelling drift'). An A2A 1.0 interface renders it as `TASK_STATE_*` at the boundary through the a2a-integration.md §D.4 bijection; the stored form does not change. Projected from `run.status` per a2a-integration.md §'State projection (forward)' and §D.4: pending→submitted; running, paused and cancelling (RFC 0094, until terminal)→working; waiting-approval, waiting-input and waiting-external→input-required; completed→completed; failed→failed; cancelled→canceled. `auth-required` is set by the forward projection only for a run suspended on a `credential` interrupt (RFC 0199 §D.1; a2a-integration.md drift point #3 is retired for the forward direction) and is otherwise carried for reverse-direction fidelity."
     },
     "interruptKind": {
       "type": "string",
       "enum": [
         "approval",
-        "clarification"
+        "clarification",
+        "credential"
       ],
-      "description": "Present iff `state == 'input-required'`. Disambiguates a2a-integration.md drift point #2 (both approval + clarification project to INPUT_REQUIRED) \u2014 carried in `Task.metadata.openwop.interrupt.kind`, the `metadata.openwop.*` shape the doc's Future-work asks to codify."
+      "description": "Present iff `state` is `input-required` or `auth-required`; `credential` ⇔ `auth-required` in the forward direction (RFC 0199 §D.1) — a rule stated in the prose of a2a-integration.md §'The durable Task projection record'; this schema does not enforce it (the field is not in `required` and there is no conditional). Disambiguates a2a-integration.md drift point #2 (approval and clarification both project to INPUT_REQUIRED) — carried in `Task.metadata.openwop.interrupt.kind`, the `metadata.openwop.*` shape the doc's Future-work asks to codify. The enum names only `approval`, `clarification` and `credential`: a `waiting-external` run, which also projects to input-required, has no value here, and its kind is disambiguated by the `metadata.openwop.interrupt.kind` carrier alone."
     },
     "updatedAt": {
       "type": "string",
@@ -63,17 +64,17 @@
       "required": [
         "url"
       ],
-      "description": "RFC 0100 \u00a74. A caller-registered A2A push-notification config for this Task.",
+      "description": "RFC 0100 §4. A caller-registered A2A push-notification config for this Task.",
       "properties": {
         "url": {
           "type": "string",
           "format": "uri",
-          "description": "Caller-registered push target. The host MUST validate it through the RFC 0093 webhook-egress SSRF guard before any push (no private/loopback/link-local target) \u2014 SECURITY invariant `a2a-push-egress-ssrf`."
+          "description": "Caller-registered push target. The host MUST validate it through the RFC 0093 webhook-egress SSRF guard before any push (no private/loopback/link-local target) — SECURITY invariant `a2a-push-egress-ssrf`."
         },
         "tokenFingerprint": {
           "type": "string",
           "maxLength": 32,
-          "description": "MAY \u2014 a truncated/salted digest of the caller's push-auth token (NEVER the raw token; same SR-1 rule as RFC 0083's `secretFingerprint`). The A2A push HMAC details (A2A \u00a74.3.3) stay inside the A2A layer per a2a-integration.md."
+          "description": "MAY — a truncated/salted digest of the caller's push-auth token (NEVER the raw token; same SR-1 rule as RFC 0083's `secretFingerprint`). The A2A push HMAC details (A2A §4.3.3) stay inside the A2A layer per a2a-integration.md."
         }
       }
     }

package/schemas/v2/agent-deployment-transition.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openwop.dev/spec/v2/agent-deployment-transition.schema.json",
   "title": "AgentDeploymentTransition",
-  "description": "RFC 0082 \u00a7E. The request body of POST /agents/{agentId}/deployments \u2014 a deployment state-transition request. The host authorizes it fail-closed against the RFC 0049 `deploy:*` scope, runs any configured RFC 0051 approvalGate, enforces the RFC 0081 eval evidence when the gate requires it, and on success emits the matching `deployment.*` event and returns the updated `agent-deployment.schema.json` record. Carries no manifest body or credential material (SR-1).",
+  "description": "RFC 0082 §E. The request body of POST /agents/{agentId}/deployments — a deployment state-transition request. The host authorizes it fail-closed against the RFC 0049 `deploy:*` scope, runs any configured RFC 0051 approvalGate, enforces the RFC 0081 eval evidence when the gate requires it, and on success emits the matching `deployment.*` event and returns the updated `agent-deployment.schema.json` record. Carries no manifest body or credential material (SR-1).",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -24,7 +24,7 @@
         "rollback",
         "adjust-canary"
       ],
-      "description": "The lifecycle operation. `promote`: advance toward production (draft\u2192test\u2192staged\u2192active) into `toState`. `pause`: active\u2192paused. `deprecate`: active\u2192deprecated. `rollback`: active\u2192rolled-back, restoring a prior version. `adjust-canary`: change the active version's `canaryPercent`. Legal transitions + the seven-state machine are normative in `agent-deployment.md` \u00a7C."
+      "description": "The lifecycle operation. `promote`: advance toward production (draft→test→staged→active) into `toState`. `pause`: active→paused. `deprecate`: active→deprecated. `rollback`: active→rolled-back, restoring a prior version. `adjust-canary`: change the active version's `canaryPercent`. Legal transitions + the seven-state machine are normative in `agent-deployment.md` §C."
     },
     "toState": {
       "type": "string",
@@ -43,7 +43,7 @@
       "type": "string",
       "minLength": 1,
       "maxLength": 64,
-      "description": "MAY. The named deployment channel this transition targets (e.g. `stable`). The version becomes resolvable by `AgentRef.channel` = this value (RFC 0082 \u00a7A/\u00a7B)."
+      "description": "MAY. The named deployment channel this transition targets (e.g. `stable`). The version becomes resolvable by `AgentRef.channel` = this value (RFC 0082 §A/§B)."
     },
     "canaryPercent": {
       "type": "integer",
@@ -53,7 +53,7 @@
     },
     "evalRunId": {
       "$ref": "ids.schema.json#/$defs/runId",
-      "description": "MAY. The RFC 0081 eval run whose `EvalSummary.passed` the gate verifies before emitting `deployment.promoted` (the \u00a7E evidence). Required when the target `approvalGate` is configured with `requiredEval`; an unmet eval gate is rejected with `eval_gate_unmet`."
+      "description": "MAY. The RFC 0081 eval run whose `EvalSummary.passed` the gate verifies before emitting `deployment.promoted` (the §E evidence). Required when the target `approvalGate` is configured with `requiredEval`; an unmet eval gate is rejected with `eval_gate_unmet`."
     },
     "reason": {
       "type": "string",

package/schemas/v2/agent-deployment.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openwop.dev/spec/v2/agent-deployment.schema.json",
   "title": "AgentDeployment",
-  "description": "RFC 0082 \u00a7C. A per-(agentId, version) deployment record: the host-runtime lifecycle state of one version of a manifest agent (RFC 0003/0070), distinct from the immutable AgentManifest (which is the pack-distribution descriptor) and from the registry's published semver tags (which version EXISTS, not which version SERVES). Holds the deployment `state`, the named `channels` that resolve to this version, the canary traffic share, the rollback pointer, and the provenance (`evalRunId`/`approvalGateId`) of the last transition. Content-free of any manifest body or credential material (SR-1). The record itself is host-internal; this schema is the canonical wire shape a host exposes via GET /agents/{agentId}/deployments (the endpoint lands at Active \u2192 Accepted per RFC 0082 \u00a7Conformance).",
+  "description": "RFC 0082 §C. A per-(agentId, version) deployment record: the host-runtime lifecycle state of one version of a manifest agent (RFC 0003/0070), distinct from the immutable AgentManifest (which is the pack-distribution descriptor) and from the registry's published semver tags (which version EXISTS, not which version SERVES). Holds the deployment `state`, the named `channels` that resolve to this version, the canary traffic share, the rollback pointer, and the provenance (`evalRunId`/`approvalGateId`) of the last transition. Content-free of any manifest body or credential material (SR-1). The record itself is host-internal; this schema is the canonical wire shape a host exposes via GET /agents/{agentId}/deployments (the endpoint lands at Active → Accepted per RFC 0082 §Conformance).",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -18,7 +18,7 @@
     "version": {
       "type": "string",
       "maxLength": 64,
-      "description": "The concrete agent-definition version this record governs (matches `AgentManifest.version`). A deployment record is per-(agentId, version); a `@channel` reference resolves to exactly one such version per the RFC 0082 \u00a7B pin."
+      "description": "The concrete agent-definition version this record governs (matches `AgentManifest.version`). A deployment record is per-(agentId, version); a `@channel` reference resolves to exactly one such version per the RFC 0082 §B pin."
     },
     "state": {
       "type": "string",
@@ -31,13 +31,13 @@
         "deprecated",
         "rolled-back"
       ],
-      "description": "RFC 0082 \u00a7C lifecycle state. `draft`: authored, not yet evaluated. `test`: undergoing eval (RFC 0081). `staged`: eval-passed, awaiting production promotion. `active`: serving (optionally at `canaryPercent < 100`). `paused`: temporarily withdrawn, recoverable. `deprecated`: sunset \u2014 no new traffic, existing pins honored. `rolled-back`: superseded; `rollbackPointer` names the version that replaced it. Legal transitions: draft\u2192test\u2192staged\u2192active (promotion); active\u2194paused (operational); active\u2192deprecated (terminal); active\u2192rolled-back (recovery, with `rollbackPointer`)."
+      "description": "RFC 0082 §C lifecycle state. `draft`: authored, not yet evaluated. `test`: undergoing eval (RFC 0081). `staged`: eval-passed, awaiting production promotion. `active`: serving (optionally at `canaryPercent < 100`). `paused`: temporarily withdrawn, recoverable. `deprecated`: sunset — no new traffic, existing pins honored. `rolled-back`: superseded; `rollbackPointer` names the version that replaced it. Legal transitions: draft→test→staged→active (promotion); active↔paused (operational); active→deprecated (terminal); active→rolled-back (recovery, with `rollbackPointer`)."
     },
     "canaryPercent": {
       "type": "integer",
       "minimum": 0,
       "maximum": 100,
-      "description": "MAY. For an `active` version, the share (0\u2013100) of channel traffic the \u00a7B pin draw assigns to THIS version; the remainder goes to the prior `active` version on the same channel. Absent \u21d2 100 (full traffic). A host advertising `agents.deployment.canary: false` MUST reject any value < 100. The per-run draw outcome is the recorded-fact `resolvedAgentVersion` (RFC 0082 \u00a7B) \u2014 never re-rolled on replay."
+      "description": "MAY. For an `active` version, the share (0–100) of channel traffic the §B pin draw assigns to THIS version; the remainder goes to the prior `active` version on the same channel. Absent ⇒ 100 (full traffic). A host advertising `agents.deployment.canary: false` MUST reject any value < 100. The per-run draw outcome is the recorded-fact `resolvedAgentVersion` (RFC 0082 §B) — never re-rolled on replay."
     },
     "rollbackPointer": {
       "type": "string",
@@ -51,16 +51,16 @@
         "type": "string",
         "minLength": 1
       },
-      "description": "MAY. The named deployment channels (e.g. `stable`, `canary`) that resolve to this version. A version MAY be on more than one channel (RFC 0082 UQ#4 \u2014 a promoted-to-`stable` version is also resolvable by the reserved `latest` channel = highest active semver). Channel names are host-advertised in `capabilities.agents.deployment.channels`."
+      "description": "MAY. The named deployment channels (e.g. `stable`, `canary`) that resolve to this version. A version MAY be on more than one channel (RFC 0082 UQ#4 — a promoted-to-`stable` version is also resolvable by the reserved `latest` channel = highest active semver). Channel names are host-advertised in `capabilities.agents.deployment.channels`."
     },
     "evalRunId": {
       "$ref": "ids.schema.json#/$defs/runId",
-      "description": "MAY. The RFC 0081 eval run whose `EvalSummary.passed` gated the last promotion into this state (the \u00a7E evidence). Content-free reference, not the eval body."
+      "description": "MAY. The RFC 0081 eval run whose `EvalSummary.passed` gated the last promotion into this state (the §E evidence). Content-free reference, not the eval body."
     },
     "approvalGateId": {
       "type": "string",
       "minLength": 1,
-      "description": "MAY. The RFC 0051 `approvalGate` that authorized the last transition (the \u00a7E human gate). Content-free reference."
+      "description": "MAY. The RFC 0051 `approvalGate` that authorized the last transition (the §E human gate). Content-free reference."
     }
   },
   "x-openwop-seeded-from": "v1"