@openwop/openwop-conformance 1.1.1 → 1.3.0

package/schemas/capabilities.schema.json

@@ -49,6 +49,23 @@
       "additionalProperties": false,
       "description": "Hard limits enforced by the engine. See capabilities.md §3."
     },
+    "envelopeStrictness": {
+      "type": "string",
+      "enum": ["warn", "strict"],
+      "description": "AI Envelope schema-version drift handling per `spec/v1/ai-envelope.md` §\"Capability handshake integration\" (DRAFT v1.x). Optional in v1.x; default when absent is `warn`. Under `warn`, the engine MUST attempt validation against the advertised version of a kind and log `envelope_schema_version_drift` when the emitted `schemaVersion` is lower than advertised. Under `strict`, the same condition MUST cause refusal with `unknown_schema_version`. Emitted `schemaVersion` higher than advertised MUST refuse regardless of strictness."
+    },
+    "envelopeContracts": {
+      "type": "object",
+      "description": "AI Envelope contract-gating advertisement per `spec/v1/ai-envelope.md` §\"Capability handshake integration\" (DRAFT v1.x). Optional in v1.x. When `advertised: true`, the host's node-pack manifests carry `EnvelopeContract` blocks per `ai-envelope.md` §\"Envelope Contract\"; tooling and conformance scenarios gate on this flag. When `advertised: false` or the block is absent, hosts MAY accept envelopes without per-typeId `accepts[]` enforcement.",
+      "required": ["advertised"],
+      "properties": {
+        "advertised": {
+          "type": "boolean",
+          "description": "Host's node-pack manifests carry `EnvelopeContract` blocks."
+        }
+      },
+      "additionalProperties": false
+    },
     "extensions": {
       "type": "object",
       "description": "Optional per-canvas-type or per-workflow extensions (additional envelope types, override limits)."
@@ -193,6 +210,17 @@
       "uniqueItems": true,
       "description": "Optional v1 host-advertised opaque capability ids that NodeModules may declare in `NodeModule.requires`. Naming convention: dotted, domain-scoped (`chat.sendPrompt`, `canvas.write`, `secrets.byok`). Provider value shapes are documented per-capability alongside consumers, NOT in the protocol package — the protocol owns the *check*, not domain provider contracts. A client that submits a workflow whose nodes declare a `requires` entry SHOULD first verify the host advertises that capability; a host that lacks a capability MUST refuse to dispatch nodes that declare it, terminating the run with `RunSnapshot.error.code = 'capability_not_provided'`. See `capabilities.md` §\"Runtime capabilities\"."
     },
+    "providerUsage": {
+      "type": "object",
+      "description": "RFC 0026 (Draft). Hosts that emit `provider.usage` events after every LLM provider invocation per RFC 0026 §B. The event carries per-call token counts in the durable event log; cost rollup remains in `RunSnapshot.metrics.openwopCost`. Old hosts ignore.",
+      "properties": {
+        "supported": { "type": "boolean", "description": "Host emits one `provider.usage` event per LLM provider call." },
+        "costEstimates": { "type": "boolean", "description": "When true, the host includes `costEstimateUsd` on `provider.usage` events using its internal rate table. When false/absent, only token counts are emitted." },
+        "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Default ISO 4217 currency for `costEstimateUsd` values. When absent, USD is assumed." }
+      },
+      "required": ["supported"],
+      "additionalProperties": false
+    },
     "aiProviders": {
       "type": "object",
       "description": "Optional v1 companion to `secrets`. Advertises which AI providers the host's AI-proxy can route to and which permit BYOK.",
@@ -266,6 +294,17 @@
       },
       "additionalProperties": true
     },
+    "conformance": {
+      "type": "object",
+      "description": "Conformance-only capability block (RFC 0023). Advertises which conformance-only typeIds (`core.conformance.*`) the host has registered. Hosts that don't ship conformance-only typeIds omit this block entirely. Production deployments SHOULD omit this block; conformance-only typeIds carry test hooks (e.g., `mockReasoning`, `mockConfidence`) that MUST NOT be reachable from production tenants.",
+      "properties": {
+        "mockAgent": {
+          "type": "boolean",
+          "description": "RFC 0023 §B.2. When `true`, the host has registered the `core.conformance.mock-agent` typeId. The scenarios `agentReasoningEvents.test.ts` and `agentConfidenceEscalation.test.ts` rely on the typeId being reachable. Hosts that register the typeId only for workflow ids matching the conformance fixture prefix (`conformance-*`) and refuse it for other tenants MAY still advertise `true` — the advertisement says only that the typeId is reachable from the conformance suite, not that it is reachable from arbitrary workflows."
+        }
+      },
+      "additionalProperties": false
+    },
     "fixtures": {
       "type": "array",
       "items": { "type": "string", "minLength": 1 },
@@ -311,6 +350,11 @@
           "type": "boolean",
           "description": "Phase 6. When `true`, host advertises that it implements the `core.dispatch` Core typeId AND honors the conservative-path commitment CP-2 (`core.dispatch` MUST NOT mutate the run's DAG mid-run). Implies (but does NOT require) `agents.orchestrator: true`."
         },
+        "dispatchMapping": {
+          "type": "boolean",
+          "default": false,
+          "description": "Phase 6.1 (RFC 0022 §A). When `true`, host honors `inputMapping` / `outputMapping` / `perWorkerInputMappings` / `perWorkerOutputMappings` on `DispatchConfig` — building child inputs from parent variables before dispatch and harvesting child variables into parent variables on completion. Implies (but does NOT require) `agents.dispatch: true`. Hosts that set `agents.dispatch: true` but omit / `false` this flag MUST refuse workflows that carry non-empty mapping fields at registration with `validation_error` + `details.requiredCapability: 'agents.dispatchMapping'`."
+        },
         "reasoning": {
           "type": "object",
           "description": "Phase 1 reasoning-event verbosity configuration.",
@@ -324,6 +368,11 @@
               "type": "integer",
               "minimum": 0,
               "description": "Effective cap on reasoning trace length when verbosity is `summary`. Default 512 tokens."
+            },
+            "streaming": {
+              "type": "boolean",
+              "default": false,
+              "description": "RFC 0024. When `true`, the host MAY emit `agent.reasoning.delta` events while a reasoning block is still open, in addition to the final `agent.reasoned`. Hosts that omit / `false` this flag emit only the final `agent.reasoned`. Consumers MUST tolerate both modes."
             }
           },
           "additionalProperties": false
@@ -384,6 +433,221 @@
       "type": "boolean",
       "description": "Multi-Agent Shift Phase 4. When `true`, host advertises that it implements the `core.conversationGate` typeId AND honors the `conversation.start` / `conversation.exchange` / `conversation.close` suspend variants. Hosts that don't claim this fall back to `clarification.requested` interrupts for multi-turn user interjections."
     },
+    "subWorkflow": {
+      "type": "object",
+      "description": "Capability surface for `core.subWorkflow` extensions. The baseline `core.subWorkflow` contract (RFC 0007 + `node-packs.md` §contract) is unconditional and does NOT require a capability flag; this object carries the additive extensions a host MAY support. Added by RFC 0022 §B + §C.",
+      "properties": {
+        "inputMapping": {
+          "type": "boolean",
+          "default": false,
+          "description": "RFC 0022 §B. When `true`, host honors the `inputMapping` field on `core.subWorkflow` configs — seeding the child workflow's initial variable bag from `parentVariables[parentKey]` projections, overriding any matching `variables[].defaultValue` declaration on the child. When `false` or absent, hosts MUST refuse workflows that carry a non-empty `inputMapping` at registration with `validation_error` + `details.requiredCapability: 'subWorkflow.inputMapping'`. Silent ignore is NOT conformant."
+        }
+      },
+      "additionalProperties": false
+    },
+    "fs": {
+      "type": "object",
+      "description": "RFC 0014 (`Active`). Filesystem capability — read/write/list/stat/delete inside a sandbox root. Required by the `core.openwop.files` pack. Hosts MUST resolve every input path relative to `sandboxRoot`, reject any path that escapes via `..` segments or symlinks, and enforce `maxFileSizeBytes` on write. Path-traversal rejection is normative — see `SECURITY/invariants.yaml` row `fs-path-traversal`.",
+      "properties": {
+        "supported": {
+          "type": "boolean",
+          "description": "Host advertises `ctx.fs.{read,write,delete,stat,list}`. `false` (or omission) signals the host does NOT expose a filesystem surface; `core.openwop.files` registration MUST refuse on such hosts."
+        },
+        "sandboxRoot": {
+          "type": "string",
+          "description": "Absolute path. Every fs operation is resolved relative to this root. MUST be set when `supported: true`."
+        },
+        "maxFileSizeBytes": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Per-file size cap enforced on write. 0 = unlimited (NOT recommended). Reads of files larger than this MAY return `file_too_large`."
+        },
+        "image": {
+          "type": "object",
+          "description": "Image-processing sub-capability. Optional.",
+          "properties": {
+            "supported": { "type": "boolean" },
+            "formats": {
+              "type": "array",
+              "items": { "type": "string", "enum": ["jpeg", "png", "webp", "avif", "gif"] }
+            }
+          },
+          "additionalProperties": false
+        },
+        "pdf": {
+          "type": "object",
+          "description": "PDF-processing sub-capability. Optional.",
+          "properties": {
+            "supported": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        },
+        "transport": {
+          "type": "object",
+          "description": "Network file-transport sub-capabilities. Optional.",
+          "properties": {
+            "ftp": { "type": "boolean" },
+            "sftp": { "type": "boolean" },
+            "ssh": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "if": { "properties": { "supported": { "const": true } }, "required": ["supported"] },
+      "then": { "required": ["supported", "sandboxRoot"] },
+      "additionalProperties": false
+    },
+    "kvStorage": {
+      "type": "object",
+      "description": "RFC 0015 (`Active`). TTL-aware key-value store with atomic increment + compare-and-swap. Required by `core.openwop.storage` kv-* nodes. Hosts MUST partition values by tenant (`kv-cross-tenant-isolation` invariant) and atomically apply increments + CAS when those flags are advertised.",
+      "properties": {
+        "supported": { "type": "boolean" },
+        "maxKeyBytes": { "type": "integer", "minimum": 0 },
+        "maxValueBytes": { "type": "integer", "minimum": 0 },
+        "maxTtlSeconds": { "type": "integer", "minimum": 0 },
+        "atomicIncrement": { "type": "boolean" },
+        "compareAndSwap": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "tableStorage": {
+      "type": "object",
+      "description": "RFC 0016 (`Active`). Structured-record store with user-defined schemas. Sibling to kvStorage. Cross-tenant isolation enforced (mirrors RFC 0015 invariant).",
+      "properties": {
+        "supported": { "type": "boolean" },
+        "maxRowsPerTable": { "type": "integer", "minimum": 0 },
+        "maxColumnsPerRow": { "type": "integer", "minimum": 0 },
+        "indexable": { "type": "boolean" },
+        "fullTextSearch": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "queueBus": {
+      "type": "object",
+      "description": "RFC 0017 (`Active`). Inbound queue + stream capability — publish, consume (trigger), ack/nack/dead-letter. Cross-tenant message isolation invariant (`queue-cross-tenant-isolation`). Sibling to host.messaging (which is outbound-egress-only).",
+      "properties": {
+        "supported": { "type": "boolean" },
+        "backends": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["rabbitmq", "kafka", "sqs", "sns", "pubsub", "mqtt", "nats", "redis-streams", "in-memory"] }
+        },
+        "deadLetterSupported": { "type": "boolean" },
+        "stream": {
+          "type": "object",
+          "properties": {
+            "supported": { "type": "boolean" },
+            "fromBeginning": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "sql": {
+      "type": "object",
+      "description": "RFC 0018 (`Active`). SQL database adapter with parametric-only enforcement. Hosts MUST reject non-parametric queries that inline user input (`sql-parametric-only` invariant — guards against SQL injection across every workflow).",
+      "properties": {
+        "supported": { "type": "boolean" },
+        "datasources": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
+        "transactions": { "type": "boolean" },
+        "drivers": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["postgres", "mysql", "mariadb", "sqlite", "mssql", "clickhouse", "snowflake", "bigquery", "duckdb"] }
+        }
+      },
+      "additionalProperties": false
+    },
+    "nosql": {
+      "type": "object",
+      "description": "RFC 0018 (`Active`). MongoDB-shape document store adapter.",
+      "properties": {
+        "supported": { "type": "boolean" },
+        "datasources": { "type": "array" },
+        "drivers": { "type": "array", "items": { "type": "string", "enum": ["mongodb", "dynamodb", "cosmosdb", "firestore"] } }
+      },
+      "additionalProperties": false
+    },
+    "vectorStore": {
+      "type": "object",
+      "description": "RFC 0018 (`Active`). Vector-DB capability for k-NN search.",
+      "properties": {
+        "supported": { "type": "boolean" },
+        "collections": { "type": "array" },
+        "backends": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["pinecone", "qdrant", "weaviate", "milvus", "pgvector", "redis", "mongodb-atlas", "chroma", "azure-ai-search", "in-memory"] }
+        }
+      },
+      "additionalProperties": false
+    },
+    "searchIndex": {
+      "type": "object",
+      "description": "RFC 0018 (`Active`). Full-text search index adapter.",
+      "properties": {
+        "supported": { "type": "boolean" },
+        "indexes": { "type": "array" },
+        "backends": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["elasticsearch", "opensearch", "meilisearch", "typesense", "algolia"] }
+        }
+      },
+      "additionalProperties": false
+    },
+    "blobStorage": {
+      "type": "object",
+      "description": "RFC 0019 (`Active`). Binary artifact store with presigned URLs. Per-bucket tenant isolation. Presigned URLs MUST expire at the advertised TTL.",
+      "properties": {
+        "supported": { "type": "boolean" },
+        "buckets": { "type": "array" },
+        "presignSupported": { "type": "boolean" },
+        "maxObjectBytes": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "cache": {
+      "type": "object",
+      "description": "RFC 0019 (`Active`). TTL cache for HTTP / AI response memoization. Per-tenant scoping; TTL drift ≤ 1s.",
+      "properties": {
+        "supported": { "type": "boolean" },
+        "maxValueBytes": { "type": "integer", "minimum": 0 },
+        "maxTtlSeconds": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "workflowChainPacks": {
+      "type": "object",
+      "description": "RFC 0013 (Phase 1, `Draft`). When `supported: true`, the host's workflow editor implements workflow-chain pack expansion per `workflow-chain-packs.md` — author drops a chain tile, host resolves the pack, prompts for `parameters`, substitutes `{{params.<name>}}` placeholders, rewrites node ids, splices the resulting DAG into the parent workflow. Hosts that don't implement expansion omit this block (or set `supported: false`); conformance scenarios under `conformance/src/scenarios/workflow-chain-*.test.ts` skip cleanly against those hosts.",
+      "properties": {
+        "supported": {
+          "type": "boolean",
+          "description": "Whether the host's workflow editor implements chain expansion at author time. `false` (or omission) signals the host does NOT consume workflow-chain packs."
+        }
+      },
+      "required": ["supported"],
+      "additionalProperties": false
+    },
+    "mcp": {
+      "type": "object",
+      "description": "RFC 0020 (`Active`). MCP (Model Context Protocol) composition surface. The client half is consumed implicitly via `host.mcp` host-surface; this block adds the optional server half — workflow exposed AS an MCP server with bidirectional sampling/elicitation bridges.",
+      "properties": {
+        "supported": { "type": "boolean", "description": "Host advertises a client-side MCP surface (ctx.mcp.*). See spec/v1/mcp-integration.md." },
+        "serverMount": {
+          "type": "object",
+          "description": "Server-side MCP composition (workflow IS an MCP server). When supported, the host mounts an MCP endpoint and routes inbound tools/call, resources/read, prompts/get into workflows. Inbound MUST be treated as `trustBoundary: 'untrusted'`.",
+          "properties": {
+            "supported": { "type": "boolean" },
+            "transports": {
+              "type": "array",
+              "items": { "type": "string", "enum": ["stdio", "streamable-http"] }
+            },
+            "samplingBridge": { "type": "boolean", "description": "Inbound sampling/createMessage bridges to the workflow's ctx.callAI." },
+            "elicitationBridge": { "type": "boolean", "description": "Inbound elicitation/create bridges to ctx.suspend." }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
     "compliance": {
       "type": "object",
       "description": "Privacy / compliance behavior advertised to clients (closes O5). Lets consumers know what masking mode is in effect so a `\"[REDACTED]\"` value in event log payloads is recognizable as a server-side mask vs an upstream null.",

package/schemas/core-conformance-mock-agent-config.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/core-conformance-mock-agent-config.schema.json",
+  "title": "CoreConformanceMockAgentConfig",
+  "description": "Config shape for the `core.conformance.mock-agent` typeId (RFC 0023). Conformance-only — hosts MUST refuse this typeId for production tenants unless `capabilities.conformance.mockAgent` is advertised. Emission contract is normative per RFC 0023 §B: when set, the host fires `agent.reasoned`, `agent.toolCalled`/`agent.toolReturned` pairs, `agent.handoff`, and `agent.decided` in the order documented, then evaluates the resolved escalation threshold against any `confidence` value and follows with `node.suspended { reason: 'low-confidence' }` when below threshold (`spec/v1/interrupt.md` §`kind: \"low-confidence\"`).",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "agentId": {
+      "type": "string",
+      "minLength": 3,
+      "description": "Optional override for the `agentId` field carried on emitted `agent.*` events. Resolution order: this field → `nodes[].agent.agentId` (the workflow-level pin) → a host-minted synthetic id (e.g., `host:mock-agent:<nodeId>`). Hosts SHOULD prefer the workflow-level pin so conformance fixtures stay self-describing."
+    },
+    "mockReasoning": {
+      "oneOf": [
+        { "type": "boolean" },
+        {
+          "type": "object",
+          "required": ["summary"],
+          "additionalProperties": false,
+          "properties": {
+            "summary": {
+              "type": "string",
+              "description": "Short one-line digest, projected onto `agent.reasoned.payload.summary` per RFC 0002 §B."
+            },
+            "trace": {
+              "type": "string",
+              "description": "Full reasoning text. Hosts SHOULD redact when the run advertises BYOK + redaction per RFC 0002 §B (`agent.reasoned`)."
+            },
+            "tokenCount": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Optional reasoning-token count for observability/cost attribution."
+            },
+            "streamChunks": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "RFC 0024. When present, the host MUST emit one `agent.reasoning.delta` event per array entry (in order; `sequence` starts at 0 and increments by 1), THEN emit the closing `agent.reasoned` event whose `reasoning` field equals the concatenation of all `streamChunks`. When absent, only the closing `agent.reasoned` event fires (the pre-RFC-0024 behavior). Gated at conformance test time on `capabilities.agents.reasoning.streaming: true`."
+            }
+          }
+        }
+      ],
+      "description": "When set, emit `agent.reasoned`. Boolean `true` MUST surface a host-generated stub summary; an object is projected onto the `agent.reasoned` payload shape from RFC 0002 §B. When unset, no `agent.reasoned` event is emitted."
+    },
+    "mockToolCalls": {
+      "type": "array",
+      "description": "Emit `agent.toolCalled` + `agent.toolReturned` pairs in array order. Each pair shares a host-minted `callId`; the `agent.toolReturned.causationId` MUST equal the corresponding `agent.toolCalled.eventId` per RFC 0002 §B. An entry without `result` and without `error` is invalid and MUST be rejected at registration.",
+      "items": {
+        "type": "object",
+        "required": ["toolId"],
+        "additionalProperties": false,
+        "properties": {
+          "toolId": {
+            "type": "string",
+            "description": "Tool identifier in `<scope>:<tool-id>` form, projected onto `agent.toolCalled.payload.toolId` and `agent.toolReturned.payload.toolId`."
+          },
+          "arguments": {
+            "description": "Arguments object projected onto `agent.toolCalled.payload.arguments`. Any JSON value."
+          },
+          "result": {
+            "description": "Success result projected onto `agent.toolReturned.payload.result`. Any JSON value. Mutually exclusive with `error` (validators that need stricter enforcement SHOULD layer it host-side)."
+          },
+          "error": {
+            "$ref": "#/$defs/ErrorEnvelope",
+            "description": "Failure projected onto `agent.toolReturned.payload.error`. Shape matches `error-envelope.schema.json` (inlined here as `$defs.ErrorEnvelope` so the spec-corpus validity test can compile this schema in isolation). When present, the paired `agent.toolReturned` event MUST omit `result`."
+          },
+          "durationMs": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Optional duration projected onto `agent.toolReturned.payload.durationMs`."
+          }
+        }
+      }
+    },
+    "mockHandoff": {
+      "type": "object",
+      "required": ["toAgentId"],
+      "additionalProperties": false,
+      "description": "When set, emit `agent.handoff` with `from` taken from `nodes[].agent` (the current node's pin) and `to.agentId` taken from `toAgentId`. When `nodes[].agent` is absent, hosts MUST use a synthetic `from` AgentRef referencing the resolved emitter `agentId`.",
+      "properties": {
+        "toAgentId": {
+          "type": "string",
+          "minLength": 3,
+          "description": "Destination agent identifier; projected onto `agent.handoff.payload.to.agentId` per RFC 0002 §B (`agent.handoff`)."
+        },
+        "reason": {
+          "type": "string",
+          "description": "Optional free-form reason; projected onto `agent.handoff.payload.reason`."
+        },
+        "context": {
+          "description": "Optional payload value handed across the boundary; projected onto `agent.handoff.payload.context`."
+        }
+      }
+    },
+    "mockDecision": {
+      "type": "object",
+      "required": ["decision"],
+      "additionalProperties": false,
+      "description": "When set, emit `agent.decided`. When `confidence` is present AND below the resolved escalation threshold (`RunOptions.configurable.escalationThreshold` overrides `agent-manifest.confidence.defaultThreshold` overrides the spec default `0.7`), the host MUST follow the `agent.decided` event with `node.suspended { reason: 'low-confidence' }` and transition the run to `'waiting-approval'` per `spec/v1/interrupt.md:278`.",
+      "properties": {
+        "decision": {
+          "description": "Host-defined decision payload projected onto `agent.decided.payload.decision`. Any JSON value."
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Optional confidence in `[0.0, 1.0]`. Triggers the §F escalation contract from RFC 0002 when below the resolved threshold."
+        },
+        "reasoning": {
+          "type": "string",
+          "description": "Optional rationale projected onto `agent.decided.payload.reasoning`."
+        }
+      }
+    },
+    "mockConfidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Shorthand. When set AND `mockDecision` is absent, the host emits `agent.decided` with a synthetic decision payload (host-defined; the conformance suite does not assert on its shape) carrying this confidence. Triggers the same escalation contract as `mockDecision.confidence`. Retained for compatibility with the pre-RFC-0023 fixture surface; new fixtures SHOULD prefer the explicit `mockDecision` form."
+    }
+  },
+  "examples": [
+    {
+      "mockReasoning": { "summary": "Considered three options; chose A.", "tokenCount": 42 },
+      "mockToolCalls": [
+        { "toolId": "openwop.search.web", "arguments": { "q": "openwop" }, "result": ["hit-1", "hit-2"], "durationMs": 12 }
+      ],
+      "mockDecision": { "decision": { "next": "summarize" }, "confidence": 0.92 }
+    },
+    {
+      "mockDecision": { "decision": { "kind": "stub-low-conf" }, "confidence": 0.5 }
+    },
+    {
+      "mockConfidence": 0.5
+    }
+  ],
+  "$defs": {
+    "ErrorEnvelope": {
+      "title": "ErrorEnvelope",
+      "description": "Inlined from `error-envelope.schema.json` for in-isolation Ajv compile. Spec corpus schemas compile under the conformance suite's per-file Ajv harness which does not preload sibling schemas — cross-file `$ref`s would fail. The wire shape MUST match `https://openwop.dev/spec/v1/error-envelope.schema.json`; this $defs entry is a copy, not a divergence.",
+      "type": "object",
+      "required": ["error", "message"],
+      "properties": {
+        "error": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "details": { "type": "object" }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/dispatch-config.schema.json

@@ -28,6 +28,32 @@
       "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,

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

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/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": {
+    "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": 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
+}

package/schemas/envelopes/error.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/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": {
+    "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": false
+}

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

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/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": {
+    "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
+}

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

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/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_payload_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
+}

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

@@ -10,6 +10,11 @@
     { "properties": { "agents": { "type": "array", "minItems": 1 } }, "required": ["agents"] }
   ],
   "properties": {
+    "kind": {
+      "type": "string",
+      "const": "node",
+      "description": "Pack kind discriminator. For node packs (the default and original kind) `kind` is either omitted entirely OR set to the literal string `\"node\"`. Manifests carrying `kind: \"workflow-chain\"` validate against `workflow-chain-pack-manifest.schema.json` instead — see workflow-chain-packs.md and RFC 0013."
+    },
     "name": {
       "type": "string",
       "description": "Reverse-DNS pack name. Reserved scopes: `core.*` (spec-canonical), `vendor.<org>.*` (vendor-published), `community.<author>.*` (individual), `private.<host>.*` (host-internal — MUST NOT appear in `packs.openwop.dev`). `local.*` is for in-repo unpublished packs and MUST NOT appear in any registry. See node-packs.md §Naming for the full reservation table.",