@openwop/spec-artifacts 2.0.0-rc.0

package/schemas/v2/dispatch-config.schema.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/dispatch-config.schema.json",
+  "title": "DispatchConfig",
+  "description": "Configuration for the `core.dispatch` node typeId (RFC 0007). Pins per-`kind` routing strategies for the dispatch loop. The dispatch node consumes the latest `OrchestratorDecision` (RFC 0006 §C) from the run's projection and acts on it per the per-`kind` semantics in RFC 0007 §D.",
+  "type": "object",
+  "required": [],
+  "properties": {
+    "askUserRouting": {
+      "type": "string",
+      "enum": [
+        "conversation",
+        "clarification",
+        "auto"
+      ],
+      "default": "auto",
+      "description": "Routing surface for `kind: 'ask-user'` decisions. `'conversation'` requires the host to advertise `capabilities.conversationPrimitive: true` (RFC 0005) and uses `conversation.exchange`; `'clarification'` uses the existing `clarification.requested` interrupt (pre-RFC-0010 path); `'auto'` selects `conversation` when the host advertises the conversation-primitive capability and `clarification` otherwise. Hosts that select `'conversation'` without advertising the capability MUST surface a `validation_error` at workflow registration time."
+    },
+    "workerDispatchModel": {
+      "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."
+    },
+    "fanOutPolicy": {
+      "type": "string",
+      "enum": [
+        "sequential",
+        "reject",
+        "parallel"
+      ],
+      "default": "sequential",
+      "description": "Behavior when `decision.kind === 'next-worker'` and `nextWorkerIds.length > 1`. `'sequential'` (default) dispatches each in array order, blocking on each child terminal before starting the next; the dispatch node's output reports the LAST child's `childRunId`/`childStatus` (intermediate child-run identifiers surface in the run's event log via standard `node.*` events). `'reject'` fails the dispatch with a structured `'fan_out_unsupported'` error envelope per `error-envelope.md`. `'parallel'` (RFC 0118) dispatches ALL `nextWorkerIds[i]` as child runs concurrently (bounded by `maxConcurrency`) and joins on their terminals per `joinPolicy`; it REQUIRES the host to advertise `capabilities.dispatch.fanOutSupported: true` — a host that does not MUST surface a `validation_error` at `POST /v1/workflows`."
+    },
+    "joinPolicy": {
+      "type": "object",
+      "description": "RFC 0118. Completion + error-aggregation semantics for `fanOutPolicy: 'parallel'`. Meaningful ONLY when `fanOutPolicy === 'parallel'`; a host MUST surface a `validation_error` at registration if `joinPolicy` is present while `fanOutPolicy !== 'parallel'`. `mode` and `onChildFailure` are orthogonal axes (completion condition vs error aggregation).",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": [
+            "wait-all",
+            "quorum",
+            "first",
+            "race"
+          ],
+          "default": "wait-all",
+          "description": "When the join is satisfied. `'wait-all'` (default) — the dispatch node stays suspended until EVERY dispatched child reaches a terminal state (`completed`/`failed`/`cancelled`); the only mode that never discards a child's outcome. `'quorum'` — satisfied at `quorum` `completed` children (REQUIRES `quorum`, `1 ≤ quorum ≤ nextWorkerIds.length`; a missing/out-of-range `quorum` is a registration `validation_error`); in-flight children are cancelled per the `interrupt-profiles.md` parent-child cascade. `'first'` — satisfied at the first `completed`; remaining cancelled. `'race'` — satisfied at the first terminal of ANY kind (`completed` OR `failed`); remaining cancelled."
+        },
+        "quorum": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Required iff `mode === 'quorum'`. The number of `completed` children that satisfies the join. MUST be `1 ≤ quorum ≤ nextWorkerIds.length`."
+        },
+        "onChildFailure": {
+          "type": "string",
+          "enum": [
+            "collect",
+            "fail-fast",
+            "absorb"
+          ],
+          "default": "collect",
+          "description": "How a non-`completed` child terminal affects the dispatch node. `'collect'` (default) — no individual failure short-circuits; the node waits per `mode`, then reports per-child outcomes in its output (§D). `'fail-fast'` — the first child to reach `failed`/`cancelled` immediately fails the dispatch node and cancels the rest (equivalent to single-child `fail-parent` applied at first failure). `'absorb'` — failed children are recorded in the log + node output but never fail the parent; the join still completes per `mode`. The default deliberately DIVERGES from single-child `core.subWorkflow.onChildFailure: 'fail-parent'` because independent fan-out siblings are the common case (RFC 0118 §Resolved Q1)."
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    },
+    "maxConcurrency": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "RFC 0118. Maximum number of children dispatched concurrently under `fanOutPolicy: 'parallel'`. When `nextWorkerIds.length` exceeds this, the host dispatches in waves of at most `maxConcurrency`, starting a queued child as each in-flight child terminates (the host MUST NOT silently drop children above the ceiling). Absent → host-defined effective concurrency (a host MAY cap to protect itself and MUST advertise that cap as `capabilities.dispatch.maxFanOut`). The EFFECTIVE concurrency is `min(maxConcurrency ?? ∞, capabilities.dispatch.maxFanOut ?? ∞)`. Does not change join semantics — `joinPolicy` evaluates over the full `nextWorkerIds` set. Meaningful only under `fanOutPolicy: 'parallel'`."
+    },
+    "iterationCap": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional per-run hard cap on dispatch-node executions (across all dispatch nodes in the same run). Independent of `RunOptions.configurable.recursionLimit` / `Capabilities.limits.maxNodeExecutions` — when set, the engine MUST surface a `cap.breached` event with `kind: 'dispatch-iterations'` once exceeded and transition the run to `'failed'`. When absent, the run-level `recursionLimit` cap applies normally (each dispatch counts as one node execution against the run total)."
+    },
+    "inputMapping": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "RFC 0022. Default input mapping applied to every dispatched child on the `next-worker` path. Keys are CHILD variable names; values are PARENT variable names. Child receives `inputs[childKey] = parentVariables[parentKey]`. Per-worker overrides (see `perWorkerInputMappings`) take precedence. Mirrors `core.control.subWorkflow.inputMapping` semantics. Gated on `capabilities.agents.dispatchMapping: true`; hosts without that advertisement MUST surface `validation_error` at registration if this field is non-empty."
+    },
+    "outputMapping": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "RFC 0022. Default output mapping applied to every completed child on the `next-worker` path. Keys are PARENT variable names; values are CHILD variable names. After a child reaches terminal `completed`, parent's `parentKey` is set to `childVariables[childKey]`. Failed / cancelled children skip the mapping. Per-worker overrides (see `perWorkerOutputMappings`) take precedence. Mirrors `core.control.subWorkflow.outputMapping` semantics. Gated on `capabilities.agents.dispatchMapping: true`."
+    },
+    "perWorkerInputMappings": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "string"
+        }
+      },
+      "description": "RFC 0022. Per-worker input mapping overrides, keyed by the child `workflowId` that the supervisor may select. When the supervisor's `next-worker` decision names a `workerId` present in this map, the dispatch node uses `perWorkerInputMappings[workerId]` instead of the default `inputMapping`. Lets authors wire distinct variable subsets per potential child."
+    },
+    "perWorkerOutputMappings": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "string"
+        }
+      },
+      "description": "RFC 0022. Per-worker output mapping overrides, same fallback semantics as `perWorkerInputMappings`."
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "askUserRouting": "auto",
+      "workerDispatchModel": "child-run",
+      "fanOutPolicy": "sequential"
+    },
+    {
+      "askUserRouting": "clarification",
+      "fanOutPolicy": "reject",
+      "iterationCap": 25
+    },
+    {
+      "workerDispatchModel": "child-run",
+      "fanOutPolicy": "parallel",
+      "maxConcurrency": 5,
+      "joinPolicy": {
+        "mode": "wait-all",
+        "onChildFailure": "collect"
+      }
+    },
+    {
+      "fanOutPolicy": "parallel",
+      "joinPolicy": {
+        "mode": "quorum",
+        "quorum": 3,
+        "onChildFailure": "fail-fast"
+      }
+    }
+  ],
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/effect-ledger-projection.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/effect-ledger-projection.schema.json",
+  "title": "Effect ledger projection (RFC 0173 §C.2)",
+  "description": "GET /runs/{runId}/effects — the Layer-2 effect records keyed on business identity (the activity recipe is the documented fallback). Content-free of provider payloads.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "runId",
+    "effects"
+  ],
+  "properties": {
+    "runId": {
+      "$ref": "ids.schema.json#/$defs/runId"
+    },
+    "effects": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "effectId",
+          "nodeId",
+          "attempt",
+          "keying",
+          "state",
+          "at"
+        ],
+        "properties": {
+          "effectId": {
+            "$ref": "ids.schema.json#/$defs/effectId"
+          },
+          "nodeId": {
+            "$ref": "ids.schema.json#/$defs/nodeId"
+          },
+          "attempt": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "invocationId": {
+            "type": "string"
+          },
+          "keying": {
+            "type": "string",
+            "enum": [
+              "business-identity",
+              "activity-recipe"
+            ]
+          },
+          "providerKey": {
+            "type": "string",
+            "description": "Redaction-safe provider-side identity (RFC 0150); never credential material."
+          },
+          "state": {
+            "type": "string",
+            "enum": [
+              "claimed",
+              "completed",
+              "released",
+              "escaped"
+            ]
+          },
+          "at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/v2/effect-seam-manifest.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/effect-seam-manifest.schema.json",
+  "title": "Effect-seam manifest (RFC 0173 §C)",
+  "description": "Host-declared, machine-checkable list of every outbound effect path the node runtime can reach (RFC 0173 §C.1: `{ seam, kind, guarded: true, guardedBy }`; `branchReFires` states the RFC 0140 G6 asymmetry). Served at GET /host/effect-seams (canonical, not a test seam). A seam omitted is invisible to the suite (negative-existence); the RFC 0140 R5 audit is the control.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "manifestVersion",
+    "host",
+    "seams"
+  ],
+  "properties": {
+    "manifestVersion": {
+      "const": "1"
+    },
+    "host": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "build"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "build": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "id"
+          ],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "image-digest",
+                "commit",
+                "artifact-sha256"
+              ]
+            },
+            "id": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "seams": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "seam",
+          "kind",
+          "guarded",
+          "guardedBy"
+        ],
+        "properties": {
+          "seam": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$",
+            "description": "The outbound effect path, host-named (e.g. `http.fetch`, `provider.openai.chat`)."
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "http",
+              "queue",
+              "storage",
+              "provider-sdk",
+              "webhook-fanout"
+            ]
+          },
+          "guarded": {
+            "const": true,
+            "description": "RFC 0173 §C.1 — every row MUST be guarded; the scenario asserts it and drives one seam of each kind through the suite's receiver."
+          },
+          "guardedBy": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The suppression mechanism (module, interceptor, or policy) that records the outcome instead of re-firing."
+          },
+          "branchReFires": {
+            "type": "boolean",
+            "description": "RFC 0140 G6 — a `branch` fork re-fires this seam by design; stated here and witnessed as a permission."
+          },
+          "note": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/v2/envelopes/clarification.request.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/envelopes/clarification.request.schema.json",
+  "title": "ClarificationRequestPayload",
+  "description": "Payload for the universal `clarification.request` AI Envelope kind. Emitted by an LLM when it needs additional information from the user before continuing. The engine MUST lift this payload to a `kind: \"clarification\"` `InterruptPayload` per `spec/v1/interrupt.md` §\"`kind: 'clarification'`\" and pause the node, OR refuse the run with `not-applicable` if the host does not implement clarification (clarifications are part of the `openwop-interrupts` profile per `profiles.md`). Counts against `Capabilities.limits.clarificationRounds`; on breach the engine emits `cap.breached { kind: 'clarification' }` and fails the node per `capabilities.md` §\"Engine-enforced limits\".",
+  "type": "object",
+  "required": [
+    "questions"
+  ],
+  "properties": {
+    "reasoning": {
+      "type": "string",
+      "description": "OPTIONAL chain-of-thought field per RFC 0030 §A. Hosts SHOULD instruct the model to populate this with its analytical process before emitting the structured fields when reasoning materially improves output quality. The field is informational only — hosts SHALL NOT route on its contents. Hosts MUST NOT reject envelopes where `reasoning` is absent. Subject to the same SR-1 redaction harness as other envelope payload fields per `ai-envelope.md` §\"Redaction (SR-1 carry-forward)\" and the `envelope-reasoning-secret-redaction` SECURITY invariant."
+    },
+    "questions": {
+      "type": "array",
+      "minItems": 1,
+      "description": "One or more clarification questions to surface to the user. The engine MUST preserve ordering when lifting to the interrupt's `ClarificationData.questions[]`.",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "question"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "description": "Stable id for this question within the envelope. Used by the matching `ClarificationResume.answers[].id`. SHOULD be deterministic across re-emissions of the same logical clarification (so replay can match answers to questions)."
+          },
+          "question": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Human-readable question text. Localization is host-handled; the spec does not normate a per-locale variant on the envelope."
+          },
+          "schema": {
+            "description": "Optional JSON Schema constraining the answer shape (choices, free-text length, etc.). When present, the host's resolve endpoint SHOULD validate the answer against this schema before returning it to the engine.",
+            "type": "object",
+            "additionalProperties": true
+          },
+          "context": {
+            "description": "Optional open-shape metadata bag the LLM MAY use to surface per-question UI hints, trace pointers, or related context. Host-defined. The engine treats this as opaque; SR-1 redaction (`ai-envelope.md` §\"Redaction (SR-1 carry-forward)\") walks every payload field recursively, so any BYOK material that ends up here is scrubbed before persistence.",
+            "type": "object",
+            "additionalProperties": true
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "contextType": {
+      "type": "string",
+      "maxLength": 128,
+      "description": "Optional UI hint for the host (e.g., `\"approval-feedback\"`, `\"form-field\"`). Not normative; passed through to the lifted `ClarificationData.contextType`."
+    }
+  },
+  "additionalProperties": false,
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/envelopes/error.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/envelopes/error.schema.json",
+  "title": "ErrorEnvelopePayload",
+  "description": "Payload for the universal `error` AI Envelope kind. The LLM's error report — the model said `I couldn't do that`. Distinct from the HTTP-level `ErrorEnvelope` in `error-envelope.schema.json`, which is the host's error report. Hosts MUST NOT collapse these two surfaces — an `error` envelope is a successful turn whose payload happens to be an error report, and the recommended `RunEventDoc.type` is `log.appended` (level `error`), NOT `node.failed`. The model deliberately surfaced the failure rather than guessing; treating it as a node failure penalizes correct behavior.",
+  "type": "object",
+  "required": [
+    "code",
+    "message"
+  ],
+  "properties": {
+    "reasoning": {
+      "type": "string",
+      "description": "OPTIONAL chain-of-thought field per RFC 0030 §A — useful when the model is explaining why it could not produce the requested envelope (the analytical process behind a `validation_failed` or `tool_call_refused` decision). Informational only; hosts SHALL NOT route on contents. Hosts MUST NOT reject envelopes where `reasoning` is absent. Subject to SR-1 redaction per `ai-envelope.md` §\"Redaction\" and the `envelope-reasoning-secret-redaction` invariant."
+    },
+    "code": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Namespaced machine-readable error code. SHOULD use snake_case. Recommended codes: `validation_failed` (LLM tried but couldn't satisfy the requested contract), `tool_call_refused` (LLM declined to invoke a tool per a safety guideline), `context_exhausted` (LLM ran out of context window mid-emission), `ambiguous_intent` (LLM couldn't disambiguate the user's request). Vendor codes MAY be namespaced as `<vendor>.<code>` per `host-extensions.md`."
+    },
+    "message": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable error description from the LLM's perspective. Surfaces to users when the host's UI renders error envelopes."
+    },
+    "details": {
+      "type": "object",
+      "description": "Optional structured context. Schema varies by `code` — consumers MUST tolerate missing/unknown fields. Examples: `{requestedKind, requiredFields}` for `validation_failed`, `{toolName, refusalReason}` for `tool_call_refused`.",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false,
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/envelopes/media.audio.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/envelopes/media.audio.schema.json",
+  "title": "MediaAudioPayload",
+  "description": "Payload for the OPTIONAL `media.audio` AI Envelope kind (RFC 0055 §C). Carries a host-served URL reference (preferred) or, below the host's `aiProviders.maxInlineMediaBytes` cap, inline base64 audio data. Pairs with the `meta.rendering.display: \"audio\"` hint. Advertised, opt-in kind — not a MUST-recognize universal kind.",
+  "type": "object",
+  "required": [
+    "bytes"
+  ],
+  "properties": {
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Tenant-scoped, non-guessable host-served asset URL (RFC 0055 §C rule 1). SHOULD be used above `aiProviders.maxInlineMediaBytes`. Enforced by the `media-asset-url-tenant-scoped` SECURITY invariant."
+    },
+    "base64": {
+      "type": "string",
+      "description": "Inline base64-encoded audio, permitted only at or below `aiProviders.maxInlineMediaBytes` (RFC 0055 §C rule 2). Above the cap the host MUST use `url`."
+    },
+    "bytes": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Byte size of the asset."
+    },
+    "mimeType": {
+      "type": "string",
+      "description": "IANA media type (e.g. `audio/mpeg`, `audio/wav`, `audio/ogg`). SHOULD match `meta.rendering.mimeType`."
+    },
+    "durationSeconds": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Optional clip duration in seconds, for a consumer's player UI."
+    },
+    "alt": {
+      "type": "string",
+      "description": "Text alternative / label for accessibility (RFC 0055 §B); mirrors `meta.rendering.alt` when the producer also sets the rendering hint."
+    }
+  },
+  "additionalProperties": false,
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/envelopes/media.file.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/envelopes/media.file.schema.json",
+  "title": "MediaFilePayload",
+  "description": "Payload for the OPTIONAL `media.file` AI Envelope kind (RFC 0055 §C). A downloadable, non-inline-rendered asset (document, archive, dataset). Carries a host-served URL reference (preferred) or, below the host's `aiProviders.maxInlineMediaBytes` cap, inline base64. Pairs with the `meta.rendering.display: \"file\"` hint. Advertised, opt-in kind — not a MUST-recognize universal kind.",
+  "type": "object",
+  "required": [
+    "bytes"
+  ],
+  "properties": {
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Tenant-scoped, non-guessable host-served asset URL (RFC 0055 §C rule 1). SHOULD be used above `aiProviders.maxInlineMediaBytes`. Enforced by the `media-asset-url-tenant-scoped` SECURITY invariant."
+    },
+    "base64": {
+      "type": "string",
+      "description": "Inline base64-encoded file bytes, permitted only at or below `aiProviders.maxInlineMediaBytes` (RFC 0055 §C rule 2). Above the cap the host MUST use `url`."
+    },
+    "bytes": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Byte size of the asset."
+    },
+    "mimeType": {
+      "type": "string",
+      "description": "IANA media type (e.g. `application/pdf`, `text/csv`, `application/zip`). SHOULD match `meta.rendering.mimeType`."
+    },
+    "name": {
+      "type": "string",
+      "description": "Optional suggested filename for download (e.g. `q3-report.pdf`)."
+    },
+    "alt": {
+      "type": "string",
+      "description": "Text alternative / label for accessibility (RFC 0055 §B); mirrors `meta.rendering.alt` when the producer also sets the rendering hint."
+    }
+  },
+  "additionalProperties": false,
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/envelopes/media.image.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/envelopes/media.image.schema.json",
+  "title": "MediaImagePayload",
+  "description": "Payload for the OPTIONAL `media.image` AI Envelope kind (RFC 0055 §C). Carries a host-served URL reference (preferred) or, below the host's `aiProviders.maxInlineMediaBytes` cap, inline base64 image data. Pairs with the `meta.rendering.display: \"image\"` hint. This is an advertised, opt-in kind — not one of the four MUST-recognize universal kinds; a host that emits no `media.*` kind is unaffected.",
+  "type": "object",
+  "required": [
+    "bytes"
+  ],
+  "properties": {
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Tenant-scoped, non-guessable host-served asset URL (RFC 0055 §C rule 1 — signed-token / capability-token discipline). SHOULD be used when the asset exceeds `capabilities.aiProviders.maxInlineMediaBytes`. Enforced by the `media-asset-url-tenant-scoped` SECURITY invariant."
+    },
+    "base64": {
+      "type": "string",
+      "description": "Inline base64-encoded image, permitted only when the asset is at or below `aiProviders.maxInlineMediaBytes` (default 256 KiB, RFC 0055 §C rule 2). Above the cap the host MUST use `url`. Mutually exclusive with `url` in practice — a single envelope carries one or the other."
+    },
+    "bytes": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Byte size of the asset. Required so a consumer can decide whether to inline-render or defer-fetch, and so the cap rule is checkable."
+    },
+    "mimeType": {
+      "type": "string",
+      "description": "IANA media type (e.g. `image/png`, `image/jpeg`, `image/webp`). SHOULD match `meta.rendering.mimeType`."
+    },
+    "alt": {
+      "type": "string",
+      "description": "Text alternative for accessibility (RFC 0055 §B). SHOULD be present so a consumer can describe the image to assistive technology; mirrors `meta.rendering.alt` when the producer also sets the rendering hint."
+    }
+  },
+  "additionalProperties": false,
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/envelopes/schema.request.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/envelopes/schema.request.schema.json",
+  "title": "SchemaRequestPayload",
+  "description": "Payload for the universal `schema.request` AI Envelope kind. Emitted by an LLM when it wants the JSON Schema of a kind it doesn't have memorized (or wants to verify a kind's current shape before emitting). The engine's response is NOT a `RunEventDoc` — it is an out-of-band addition to the LLM's context for the next turn (returned via the same mechanism the host uses to inject system-prompt content). The response document SHOULD include the per-kind JSON Schema at `Capabilities.schemaVersions[envelopeType]`. Counts against `Capabilities.limits.schemaRounds`; on breach the engine emits `cap.breached { kind: 'schema' }` and fails the node per `capabilities.md` §\"Engine-enforced limits\".",
+  "type": "object",
+  "required": [
+    "envelopeType"
+  ],
+  "properties": {
+    "reasoning": {
+      "type": "string",
+      "description": "OPTIONAL chain-of-thought field per RFC 0030 §A — useful when the model wants to explain why it's asking for the schema (e.g., uncertainty about a specific kind's shape). Informational only; hosts SHALL NOT route on contents. Hosts MUST NOT reject envelopes where `reasoning` is absent. Subject to SR-1 redaction per `ai-envelope.md` §\"Redaction\" and the `envelope-reasoning-secret-redaction` invariant."
+    },
+    "envelopeType": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "description": "Envelope kind the LLM is asking about. MUST be present in the host's `Capabilities.supportedEnvelopes` advertisement; engines MUST refuse `schema.request` for unknown kinds with `unknown_envelope_kind` (consistent with the production-flow ordering in `ai-envelope.md`)."
+    },
+    "reason": {
+      "type": "string",
+      "maxLength": 1024,
+      "description": "Optional diagnostic explaining why the LLM is requesting the schema (e.g., `\"I'm not sure my last emission matched\"`). Surfaces in OTel spans and debug bundles; never persisted into security-relevant payloads."
+    }
+  },
+  "additionalProperties": false,
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/envelopes/schema.response.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/envelopes/schema.response.schema.json",
+  "title": "SchemaResponsePayload",
+  "description": "Payload for the universal `schema.response` AI Envelope kind. Side-channel acknowledgement that the LLM received a `schema.request` reply. Never surfaces to users. Engines MAY count this against `Capabilities.limits.envelopesPerTurn` or exempt it; conformance does not lock this choice (see `ai-envelope.md` §\"Universal kinds\").",
+  "type": "object",
+  "required": [
+    "envelopeType",
+    "ack"
+  ],
+  "properties": {
+    "envelopeType": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "description": "Envelope kind whose schema delivery the LLM is acknowledging. SHOULD match the `envelopeType` from the preceding `schema.request`. Engines MAY refuse mismatches with `envelope_invalid` but are not required to (the LLM's acknowledgement is advisory)."
+    },
+    "ack": {
+      "type": "boolean",
+      "const": true,
+      "description": "Always `true`. The field exists so the payload validates structurally; an `ack: false` is meaningless (the LLM would simply not emit this envelope)."
+    }
+  },
+  "additionalProperties": false,
+  "x-openwop-seeded-from": "v1"
+}