@openwop/spec-artifacts 2.0.0-rc.0

package/schemas/trigger-event.schema.json

@@ -0,0 +1,222 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/trigger-event.schema.json",
+  "title": "TriggerEvent",
+  "description": "RFC 0099 §F.1. The normalized external-event envelope a host hands a started run as `ctx.triggerData` when an externally-originated event (`webhook`/`email`/`form`/`stream`/`change`) is delivered to an `active` TriggerSubscription (RFC 0083). This is an IN-RUN payload only — it never appears on the durable event log; the `trigger.delivery.attempted` event stays content-free (RFC 0083 §C / SECURITY `trigger-ingestion-content-redaction`). A TriggerEvent carries exactly the per-source sub-object matching its `source`. All content is `untrusted` (SECURITY `threat-model-prompt-injection.md`).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["source", "subscriptionId", "deliveryId", "receivedAt"],
+  "properties": {
+    "source": {
+      "type": "string",
+      "enum": ["webhook", "email", "form", "stream", "change"],
+      "description": "Which external source originated the event. A TriggerEvent MUST carry exactly the per-source sub-object matching this value and MUST NOT carry the others (RFC 0099 §F.1; `stream`/`change` per RFC 0127)."
+    },
+    "subscriptionId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The RFC 0083 §B subscription this event was delivered to."
+    },
+    "deliveryId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable per-delivery id; equals the `causationId` stamped on `run.started` (RFC 0083 §C-3 / RFC 0040)."
+    },
+    "dedupKey": {
+      "type": "string",
+      "description": "The host-opaque dedup key (RFC 0083 §C-1). Present iff the subscription's `dedupEnabled`. MUST NOT embed inbound body/header content in cleartext (SECURITY `trigger-ingestion-content-redaction`)."
+    },
+    "receivedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the host received the external event."
+    },
+    "verified": {
+      "type": "boolean",
+      "description": "Whether the host verified the source's authenticity (webhook signature / email DMARC / form CSRF+origin) before delivery per the subscription's `verification` policy (RFC 0099 §F.2). A run MUST be able to gate on this."
+    },
+    "contentTrust": {
+      "type": "string",
+      "enum": ["untrusted"],
+      "description": "Always `untrusted`. Inbound external content reaching an LLM node MUST be wrapped per `threat-model-prompt-injection.md` §UNTRUSTED; a TriggerEvent MUST NOT directly advance a HITL approval gate (the `prompt-injection-mcp-no-approval` invariant generalizes)."
+    },
+    "permittedPurposes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "RFC 0128 — OPTIONAL declared uses the receiver is permitted to make of the accompanying data. Opaque purpose strings mapped to the host's local vocabulary; carries purpose categories only, never subject identifiers or consent records. Absent ⇒ unlabelled (no constraint asserted); `[]` ⇒ no onward use permitted (NOT the same as absent). A host advertising `purposePropagation` MUST honor the RFC 0128 §3 propagation rules for this label."
+    },
+    "webhook": { "$ref": "#/$defs/WebhookEvent" },
+    "email": { "$ref": "#/$defs/EmailEvent" },
+    "form": { "$ref": "#/$defs/FormEvent" },
+    "stream": { "$ref": "#/$defs/StreamEvent" },
+    "change": { "$ref": "#/$defs/ChangeEvent" }
+  },
+  "allOf": [
+    {
+      "description": "RFC 0099 §F.1 — a TriggerEvent MUST carry exactly the per-source sub-object matching its `source` and MUST NOT carry the others.",
+      "if": { "properties": { "source": { "const": "webhook" } } },
+      "then": { "not": { "anyOf": [{ "required": ["email"] }, { "required": ["form"] }, { "required": ["stream"] }, { "required": ["change"] }] } }
+    },
+    {
+      "if": { "properties": { "source": { "const": "email" } } },
+      "then": { "not": { "anyOf": [{ "required": ["webhook"] }, { "required": ["form"] }, { "required": ["stream"] }, { "required": ["change"] }] } }
+    },
+    {
+      "if": { "properties": { "source": { "const": "form" } } },
+      "then": { "not": { "anyOf": [{ "required": ["webhook"] }, { "required": ["email"] }, { "required": ["stream"] }, { "required": ["change"] }] } }
+    },
+    {
+      "if": { "properties": { "source": { "const": "stream" } } },
+      "then": { "not": { "anyOf": [{ "required": ["webhook"] }, { "required": ["email"] }, { "required": ["form"] }, { "required": ["change"] }] } }
+    },
+    {
+      "if": { "properties": { "source": { "const": "change" } } },
+      "then": { "not": { "anyOf": [{ "required": ["webhook"] }, { "required": ["email"] }, { "required": ["form"] }, { "required": ["stream"] }] } }
+    }
+  ],
+  "$defs": {
+    "WebhookEvent": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Present iff `source == \"webhook\"`.",
+      "properties": {
+        "method": { "type": "string", "enum": ["POST", "PUT", "PATCH"] },
+        "headers": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Host-allowlisted headers only — a host MUST NOT pass through `Authorization`, `Cookie`, `Proxy-Authorization`, or any header carrying credential material (RFC 0099 §F.1 / SECURITY `trigger-ingestion-content-redaction`)."
+        },
+        "body": {
+          "description": "The parsed JSON body, or a string for non-JSON. Bounded by `triggerBridge.ingestion.maxBodyBytes`."
+        }
+      }
+    },
+    "EmailEvent": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Present iff `source == \"email\"`.",
+      "properties": {
+        "from": { "type": "string" },
+        "to": { "type": "array", "items": { "type": "string" } },
+        "subject": { "type": "string" },
+        "text": { "type": "string" },
+        "html": { "type": "string" },
+        "attachments": { "type": "array", "items": { "$ref": "#/$defs/AttachmentRef" } }
+      }
+    },
+    "FormEvent": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Present iff `source == \"form\"`.",
+      "properties": {
+        "fields": { "type": "object", "additionalProperties": true, "description": "The submitted field map." },
+        "files": { "type": "array", "items": { "$ref": "#/$defs/AttachmentRef" } }
+      }
+    },
+    "StreamEvent": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Present iff `source == \"stream\"` (RFC 0127). One message consumed from a streaming broker (Kafka / Kinesis / Pub-Sub); the host is the consumer and each delivered message normalizes to one TriggerEvent. The broker connection is a credential-brokered egress (RFC 0095), never a wire field.",
+      "properties": {
+        "topic": { "type": "string", "description": "The broker topic/stream/subscription name the message was consumed from." },
+        "partition": { "type": "integer", "minimum": 0, "description": "Broker partition/shard, where the broker has one. With `offset`, feeds the RFC 0127 §4 dedup-key guidance `(topic, partition, offset)`." },
+        "offset": { "type": "string", "description": "Broker offset / sequence number as an opaque string (brokers disagree on integer width)." },
+        "key": { "type": "string", "description": "The message key, where the broker has one." },
+        "message": { "description": "The consumed message payload — parsed JSON, or a string for non-JSON. Bounded by `triggerBridge.ingestion.maxBodyBytes`." }
+      }
+    },
+    "ChangeEvent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["op"],
+      "description": "Present iff `source == \"change\"` (RFC 0127). One change-data-capture record from a warehouse/database changelog. `op` is REQUIRED. The warehouse connection is a credential-brokered egress (RFC 0095), never a wire field.",
+      "properties": {
+        "op": { "type": "string", "enum": ["insert", "update", "delete"], "description": "The change operation. REQUIRED (RFC 0127 §2 / resolved Q1 — one `change` source with an `op` discriminator, not per-verb sources)." },
+        "table": { "type": "string", "description": "The source table/collection/entity name. With `changelogId`, feeds the RFC 0127 §4 dedup-key guidance `(table, changelog-id)`." },
+        "changelogId": { "type": "string", "description": "The changelog position/LSN/row-version as an opaque string." },
+        "before": { "description": "The pre-image row where the feed provides one (typically `update`/`delete`). Parsed JSON. Bounded by `triggerBridge.ingestion.maxBodyBytes`." },
+        "after": { "description": "The post-image row where the feed provides one (typically `insert`/`update`). Parsed JSON. Bounded by `triggerBridge.ingestion.maxBodyBytes`." }
+      }
+    },
+    "AttachmentRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ref"],
+      "description": "A host-internal opaque handle to a resolved attachment/upload — NEVER a raw external URL the run is expected to fetch itself (RFC 0099 §F.1/§F.4). The host resolves and ingests attachments through its SSRF guard (SECURITY `trigger-ingestion-ssrf`), then hands the run an internal ref.",
+      "properties": {
+        "ref": {
+          "type": "string",
+          "minLength": 1,
+          "description": "A host-internal opaque handle (e.g. a `host.blobStorage` key)."
+        },
+        "filename": { "type": "string" },
+        "mediaType": { "type": "string" },
+        "bytes": { "type": "integer", "minimum": 0 }
+      }
+    }
+  },
+  "examples": [
+    {
+      "source": "email",
+      "subscriptionId": "sub_7",
+      "deliveryId": "dlv_a1b2",
+      "dedupKey": "msgid:abc@in.example.com",
+      "receivedAt": "2026-06-13T18:04:11Z",
+      "verified": true,
+      "contentTrust": "untrusted",
+      "email": {
+        "from": "customer@example.org",
+        "to": ["triage-support+sub_7@in.example.com"],
+        "subject": "Cannot log in",
+        "text": "I keep getting a 403.",
+        "attachments": [{ "ref": "blob_a1", "filename": "screenshot.png", "mediaType": "image/png", "bytes": 20481 }]
+      }
+    },
+    {
+      "source": "webhook",
+      "subscriptionId": "sub_9",
+      "deliveryId": "dlv_c3d4",
+      "receivedAt": "2026-06-13T18:10:00Z",
+      "verified": true,
+      "contentTrust": "untrusted",
+      "webhook": {
+        "method": "POST",
+        "headers": { "X-Event-Type": "issue.created" },
+        "body": { "issue": { "id": 42, "title": "Bug" } }
+      }
+    },
+    {
+      "source": "stream",
+      "subscriptionId": "sub_12",
+      "deliveryId": "dlv_e5f6",
+      "dedupKey": "events:3:88412",
+      "receivedAt": "2026-07-06T12:00:00Z",
+      "verified": true,
+      "contentTrust": "untrusted",
+      "stream": {
+        "topic": "events",
+        "partition": 3,
+        "offset": "88412",
+        "key": "user_77",
+        "message": { "type": "page_view", "path": "/pricing" }
+      }
+    },
+    {
+      "source": "change",
+      "subscriptionId": "sub_13",
+      "deliveryId": "dlv_a7b8",
+      "dedupKey": "contacts:lsn:0/1C4F9D0",
+      "receivedAt": "2026-07-06T12:01:00Z",
+      "verified": true,
+      "contentTrust": "untrusted",
+      "permittedPurposes": ["analytics"],
+      "change": {
+        "op": "update",
+        "table": "contacts",
+        "changelogId": "0/1C4F9D0",
+        "before": { "id": 77, "tier": "free" },
+        "after": { "id": 77, "tier": "pro" }
+      }
+    }
+  ]
+}

package/schemas/trigger-subscription-registration.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/trigger-subscription-registration.schema.json",
+  "title": "TriggerSubscriptionRegistration",
+  "description": "RFC 0099 §F.2. The portable create request for an external-event trigger subscription, served by `POST /v1/trigger-subscriptions`. Binds an external source (`webhook`/`email`/`form`) to a Workflow to start, with a dedup config and a source-authenticity verification policy. This is the unified create surface RFC 0083 UQ1 left per-source. The response returns the created `TriggerSubscription` (RFC 0083 §B) plus a source-specific `binding`; the binding secret/URL is returned ONCE at creation and is not re-fetchable in cleartext (SR-1).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["source", "workflowId"],
+  "properties": {
+    "source": {
+      "type": "string",
+      "enum": ["webhook", "email", "form", "stream", "change"],
+      "description": "The external source this subscription ingests. MUST appear in the host's `capabilities.triggerBridge.ingestion.externalSources[]`."
+    },
+    "workflowId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The Workflow a delivered event starts (the run's `workflowId`). MUST resolve under the caller's RFC 0048 owner triple — a registration MUST NOT bind a workflow the caller cannot start (RFC 0049 scope check)."
+    },
+    "dedupEnabled": {
+      "type": "boolean",
+      "default": true,
+      "description": "Per RFC 0083 §C-1. Defaults true for external sources — at-least-once inbound delivery without dedup is a footgun."
+    },
+    "retryPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Delivery retry policy (RFC 0083 §C-2). Same shape as `trigger-subscription.schema.json#/properties/retryPolicy`. On exhaustion the delivery transitions to `dead-lettered` (RFC 0053).",
+      "properties": {
+        "maxAttempts": { "type": "integer", "minimum": 1, "description": "Maximum delivery attempts before dead-lettering." },
+        "backoff": { "type": "string", "enum": ["none", "fixed", "exponential"], "description": "Backoff strategy between attempts." }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Source-authenticity policy. The host MUST verify per this policy BEFORE delivery and stamp `TriggerEvent.verified`; an event failing a `required` verification MUST NOT start a run (it transitions `trigger.delivery.attempted{outcome:'dead-lettered'}` with `trigger.subscription.state.changed.reason:'signature-invalid'`).",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["required", "best-effort", "none"],
+          "default": "required",
+          "description": "`required`: an unverified event is dead-lettered, no run. `best-effort`: the host verifies when it can and stamps `verified` accordingly but still delivers. `none`: no verification."
+        }
+      }
+    },
+    "inputMapping": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "OPTIONAL host-extension hint mapping `TriggerEvent` fields onto the workflow's `inputs`. Non-normative shape (host-specific); absent ⇒ the run receives the whole `TriggerEvent` as `ctx.triggerData`."
+    }
+  },
+  "examples": [
+    {
+      "source": "email",
+      "workflowId": "triage-support",
+      "dedupEnabled": true,
+      "verification": { "mode": "required" }
+    },
+    {
+      "source": "webhook",
+      "workflowId": "ingest-jira-issue",
+      "verification": { "mode": "required" },
+      "retryPolicy": { "maxAttempts": 5, "backoff": "exponential" }
+    }
+  ]
+}

package/schemas/trigger-subscription.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/trigger-subscription.schema.json",
+  "title": "TriggerSubscription",
+  "description": "RFC 0083 §B. A durable inbound-trigger subscription record (a webhook registration, a schedule, a queue consumer) with a standardized four-state machine layered over the existing per-source registration. Composes RFC 0052/0053/0017 + webhooks.md + RFC 0040 causation; the channel wire format stays a vendor extension (§E). Content-free of inbound payloads/credentials (SR-1).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["subscriptionId", "source", "state"],
+  "properties": {
+    "subscriptionId": { "type": "string", "minLength": 1, "description": "Stable host-unique id for the subscription. Correlates the §C delivery events + the management surface." },
+    "source": { "type": "string", "enum": ["webhook", "schedule", "queue", "email", "form", "stream", "change"], "description": "Which trigger source backs the subscription. Channels beyond these (Slack/Discord/SMS) bridge as a vendor extension by registering a subscription of the closest source kind (§E)." },
+    "state": { "type": "string", "enum": ["active", "paused", "failed", "dead-lettered"], "description": "The §B state. `active`: accepting + delivering; `paused`: retained, not delivering (operator-held); `failed`: delivery failing past policy (the webhooks.md circuit-breaker generalized); `dead-lettered`: terminal, deliveries routed to the RFC 0053 sink." },
+    "dedupEnabled": { "type": "boolean", "description": "When true, the host de-duplicates inbound events by `dedupKey` within the retention window (§C-1; the idempotency.md Layer-1 model applied to inbound triggers)." },
+    "retryPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Delivery retry policy (§C-2). On exhaustion the subscription/delivery transitions to `dead-lettered` (RFC 0053).",
+      "properties": {
+        "maxAttempts": { "type": "integer", "minimum": 1, "description": "Maximum delivery attempts before dead-lettering." },
+        "backoff": { "type": "string", "enum": ["none", "fixed", "exponential"], "description": "Backoff strategy between attempts." }
+      }
+    },
+    "webhookId": { "type": "string", "minLength": 1, "description": "MAY — for `source: \"webhook\"`, the existing webhooks.md register key (unchanged; the state machine layers over it)." },
+    "secretFingerprint": { "type": "string", "minLength": 1, "maxLength": 32, "description": "MAY — for `source: \"webhook\"`, an identifier for the signing secret (the `(webhookId, secretFingerprint)` register key). It MUST be a **salted or host-keyed, TRUNCATED** one-way digest (e.g. the first 8–16 hex of `HMAC(hostKey, secret)`) — NOT the raw secret (SR-1) and NOT a full unsalted `SHA256(secret)` (a full unsalted hash of a low-entropy secret is an offline brute-force / confirmation oracle). The `maxLength: 32` ceiling structurally rejects a full 64-hex digest." }
+  }
+}

package/schemas/ui-plugin-message.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/ui-plugin-message.schema.json",
+  "title": "UiPluginMessage",
+  "description": "RFC 0117 (amended by RFC 0119). The `ui-plugin/1` host-RPC envelope exchanged between a sandboxed front-end plugin and its host across the isolation boundary (transport per `capabilities.uiPlugins.isolation` — browser `postMessage` for `cross-origin-iframe`, host-call for `wasm`, IPC for `process`/`container`/`vm`; the envelope shape is identical across all). Every message carries `openwop: \"ui-plugin/1\"` (the protocol version tag — a host MUST ignore messages whose tag it does not recognize) and is one of: a plugin→host `request` (a `method` from the closed allowlist + a monotonic `id` for response correlation), a host→plugin `response` (`ok` + `result` on success, or `ok:false` + `error` on failure), or a host→plugin `event` (a one-way notification, e.g. `host.themeChanged`). The host exposes ONLY the methods the plugin declared in its manifest `hostApi` AND that the host recognizes; any other method MUST be rejected with an `error` response, never silently executed (`frontend-plugin-rpc-allowlist`). `artifact.write` carries the optimistic-concurrency `version` token (RFC 0117 §Concurrency, modeled on the RFC 0059 `host.workspace` `If-Match`/ETag pattern). See `spec/v1/frontend-plugin-packs.md`.",
+  "oneOf": [
+    { "$ref": "#/$defs/request" },
+    { "$ref": "#/$defs/response" },
+    { "$ref": "#/$defs/event" }
+  ],
+  "$defs": {
+    "request": {
+      "type": "object",
+      "title": "UiPluginRequest",
+      "description": "Plugin→host RPC call. The host MUST reject any `method` not in BOTH the plugin's declared `hostApi` allowlist AND the host's advertised `capabilities.uiPlugins.hostApi` set, returning a `response` with `ok:false` and `error.code: \"method_not_allowed\"`.",
+      "required": ["openwop", "type", "id", "method"],
+      "additionalProperties": false,
+      "properties": {
+        "openwop": { "const": "ui-plugin/1" },
+        "type": { "const": "request" },
+        "id": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Monotonic, plugin-minted correlation id. The host's `response` echoes it verbatim."
+        },
+        "method": {
+          "type": "string",
+          "enum": ["artifact.read", "artifact.write", "host.toast", "host.navigate"]
+        },
+        "params": {
+          "type": "object",
+          "description": "Method arguments. For `artifact.write`, `params.version` is REQUIRED and carries the opaque token last returned by `artifact.read`/a prior `artifact.write` (optimistic concurrency, §Concurrency). The host MUST reject a `version` it did not mint with `error.code: \"artifact_conflict\"`.",
+          "additionalProperties": true
+        }
+      }
+    },
+    "response": {
+      "type": "object",
+      "title": "UiPluginResponse",
+      "description": "Host→plugin reply to a `request`, correlated by `id`. Exactly one of `result` (when `ok:true`) or `error` (when `ok:false`).",
+      "required": ["openwop", "type", "id", "ok"],
+      "additionalProperties": false,
+      "properties": {
+        "openwop": { "const": "ui-plugin/1" },
+        "type": { "const": "response" },
+        "id": { "type": "integer", "minimum": 0 },
+        "ok": { "type": "boolean" },
+        "result": {
+          "description": "Present iff `ok:true`. For `artifact.read` the result object carries the typed artifact payload (RFC 0071) plus an opaque `version` token. For a successful `artifact.write` the result carries the NEW opaque `version` (so the editor continues without a re-read).",
+          "type": "object",
+          "additionalProperties": true
+        },
+        "error": {
+          "description": "Present iff `ok:false`.",
+          "$ref": "#/$defs/error"
+        }
+      }
+    },
+    "event": {
+      "type": "object",
+      "title": "UiPluginEvent",
+      "description": "Host→plugin one-way notification (no `id`, no response). E.g. `host.themeChanged`. A plugin MUST tolerate unknown event names.",
+      "required": ["openwop", "type", "event"],
+      "additionalProperties": false,
+      "properties": {
+        "openwop": { "const": "ui-plugin/1" },
+        "type": { "const": "event" },
+        "event": { "type": "string" },
+        "data": { "type": "object", "additionalProperties": true }
+      }
+    },
+    "error": {
+      "type": "object",
+      "required": ["code"],
+      "additionalProperties": false,
+      "properties": {
+        "code": {
+          "type": "string",
+          "description": "Stable error code. `method_not_allowed`: the requested `method` is not in the plugin+host allowlist (`frontend-plugin-rpc-allowlist`). `artifact_conflict`: an `artifact.write` carried a stale/unknown `version` — the host MUST NOT persist and MUST return the current `version` in `currentVersion` (optimistic concurrency, parallel to RFC 0059 `workspace_conflict`). `artifact_not_found` / `unauthorized` / `internal`: standard host-mediated failures.",
+          "enum": ["method_not_allowed", "artifact_conflict", "artifact_not_found", "unauthorized", "internal"]
+        },
+        "message": { "type": "string", "description": "Human-readable detail. MUST NOT carry secret material." },
+        "currentVersion": {
+          "type": "string",
+          "description": "Present iff `code: \"artifact_conflict\"`. The host's current opaque `version` for the artifact, so the plugin can re-read/merge and retry. Opaque: the plugin MUST round-trip it verbatim and MUST NOT parse or mint it."
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,102 @@
+{
+  "$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 §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": [
+    "taskId",
+    "runId",
+    "state",
+    "updatedAt"
+  ],
+  "properties": {
+    "taskId": {
+      "type": "string",
+      "minLength": 1,
+      "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",
+      "description": "The backing OpenWOP run. Bound 1:1 to `taskId`."
+    },
+    "contextId": {
+      "type": "string",
+      "description": "The A2A context_id (carried as the run tag `a2a:ctx_*` per a2a-integration.md §2)."
+    },
+    "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)."
+    },
+    "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."
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the projected state last changed."
+    },
+    "pushConfig": {
+      "$ref": "#/$defs/PushConfig"
+    }
+  },
+  "$defs": {
+    "PushConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "url"
+      ],
+      "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) — SECURITY invariant `a2a-push-egress-ssrf`."
+        },
+        "tokenFingerprint": {
+          "type": "string",
+          "maxLength": 32,
+          "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."
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "taskId": "run_x",
+      "runId": "run_x",
+      "contextId": "ctx_42",
+      "state": "input-required",
+      "interruptKind": "approval",
+      "updatedAt": "2026-06-13T19:00:00Z",
+      "pushConfig": {
+        "url": "https://caller.example.com/a2a/push",
+        "tokenFingerprint": "a1b2c3d4e5f6"
+      }
+    },
+    {
+      "taskId": "run_y",
+      "runId": "run_y",
+      "state": "completed",
+      "updatedAt": "2026-06-13T19:05:00Z"
+    }
+  ],
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/a2ui-surface-delta-frame.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/a2ui-surface-delta-frame.schema.json",
+  "title": "A2uiSurfaceDeltaFrame",
+  "description": "RFC 0114. A HOST-SIDE TRANSPORT frame carrying an RFC 6902 (JSON-Patch) delta over a recorded `ui.a2ui-surface` envelope (RFC 0102). Delivered ONLY over the run event stream (`GET /v1/runs/{runId}/events`) to a subscriber that negotiated `?a2uiDelta=1`; every other consumer (the event-log read, replay, `:fork`, any non-negotiating subscriber) receives the materialized FULL surface. This is NOT a recorded-envelope shape: the canonical `ui.a2ui-surface.schema.json` envelope is UNCHANGED and always full. The consumer applies the `patch` to the surface last delivered under `surfaceRef`, then re-validates the result against the closed `catalogVersion` catalog before render (the same fail-closed validation a full surface receives, RFC 0102 §1); on ANY apply/validation failure it falls back to store-without-render and the host re-materializes the full surface.",
+  "type": "object",
+  "required": [
+    "surfaceRef",
+    "catalogVersion",
+    "patch"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "surfaceRef": {
+      "type": "string",
+      "description": "REQUIRED — the recorded `ui.a2ui-surface` envelope id this delta patches. The consumer applies `patch` to the surface last delivered under this ref.",
+      "minLength": 1
+    },
+    "catalogVersion": {
+      "type": "string",
+      "description": "REQUIRED — the A2UI catalog version. MUST equal the referenced full surface's `catalogVersion`; a catalog-version change MUST start from a fresh full surface, never a delta.",
+      "minLength": 1
+    },
+    "patch": {
+      "type": "array",
+      "minItems": 1,
+      "description": "REQUIRED — a non-empty RFC 6902 (JSON-Patch) document applied over the surface last delivered under `surfaceRef`. The `test` op is EXCLUDED (a fire-and-forget transport frame cannot act on a failed conditional); `move`/`copy` are permitted but OPTIONAL to support.",
+      "items": {
+        "type": "object",
+        "required": [
+          "op",
+          "path"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "op": {
+            "enum": [
+              "add",
+              "remove",
+              "replace",
+              "move",
+              "copy"
+            ],
+            "description": "RFC 6902 operation. `test` is deliberately excluded."
+          },
+          "path": {
+            "type": "string",
+            "description": "RFC 6901 JSON-Pointer into the target surface."
+          },
+          "from": {
+            "type": "string",
+            "description": "RFC 6901 JSON-Pointer source for `move`/`copy`."
+          },
+          "value": {
+            "description": "The value for `add`/`replace`. Walked by the SR-1 redaction harness exactly like a full-surface value (RFC 0114)."
+          }
+        }
+      }
+    }
+  },
+  "x-openwop-seeded-from": "v1"
+}

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

@@ -0,0 +1,67 @@
+{
+  "$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 §E. The request body of POST /v1/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": [
+    "version",
+    "transition"
+  ],
+  "properties": {
+    "version": {
+      "type": "string",
+      "maxLength": 64,
+      "description": "The concrete agent-definition version the transition targets (matches `AgentManifest.version`)."
+    },
+    "transition": {
+      "type": "string",
+      "enum": [
+        "promote",
+        "pause",
+        "deprecate",
+        "rollback",
+        "adjust-canary"
+      ],
+      "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",
+      "enum": [
+        "draft",
+        "test",
+        "staged",
+        "active",
+        "paused",
+        "deprecated",
+        "rolled-back"
+      ],
+      "description": "MAY. The target lifecycle state for a `promote` transition. A host MUST reject a transition into a state it does not advertise in `capabilities.agents.deployment.states`."
+    },
+    "channel": {
+      "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 §A/§B)."
+    },
+    "canaryPercent": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 100,
+      "description": "MAY. For `promote` to `active` or `adjust-canary`, the share of channel traffic this version takes. A host advertising `capabilities.agents.deployment.canary: false` MUST reject any value < 100."
+    },
+    "evalRunId": {
+      "type": "string",
+      "minLength": 1,
+      "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",
+      "minLength": 1,
+      "maxLength": 512,
+      "description": "MAY. A short redaction-safe reason label (NOT free-text content), surfaced on `deployment.rolled-back.reason`. Same posture as `run.dead_lettered.reason`."
+    }
+  },
+  "x-openwop-seeded-from": "v1"
+}