@openwop/spec-artifacts 2.0.0-rc.0

package/schemas/conversation-turn.schema.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/conversation-turn.schema.json",
+  "title": "ConversationTurn",
+  "description": "One turn in a multi-turn conversation. Structural superset of `ConversationMessage` (RFC 0002 §G — append-only, idempotent on `messageId`, replay-deterministic). Adds `role`, optional `agent` reference, and `turnIndex` discriminators. Folds through the existing `applyMessage` reducer unchanged. See RFC 0005 §C.",
+  "type": "object",
+  "required": ["messageId", "from", "content", "ts", "role", "turnIndex"],
+  "properties": {
+    "messageId": {
+      "type": "string",
+      "description": "Dedup key. Producers MUST construct a deterministic id so re-folding is idempotent. Recommended encoding: `${conversationId}:${turnIndex}:${role}` (e.g., `run-abc:n1:0:7:agent`).",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "from": {
+      "type": "string",
+      "description": "Sender identity. Either an agent ID (RFC 0002 §A1) or the literal `'user'` for human-originated turns.",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "to": {
+      "type": "string",
+      "description": "Optional addressee. Absent = broadcast to the conversation's group (or the run's default participants).",
+      "maxLength": 256
+    },
+    "groupId": {
+      "type": "string",
+      "description": "Optional shared-agent group ID. When set, the turn is scoped to the `shared:<groupId>` agent context per RFC 0002 §A8.",
+      "maxLength": 256
+    },
+    "content": {
+      "description": "Opaque turn content. Protocol does not standardize the shape; hosts use Zod schemas at the application layer for structured turns. Pass-through for any JSON value.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    },
+    "ts": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Turn timestamp (ms epoch). Caller's clock; replay carries through unchanged for determinism."
+    },
+    "role": {
+      "type": "string",
+      "enum": ["user", "agent", "system"],
+      "description": "Discriminator distinguishing human-originated turns (`'user'`), AI-agent-originated turns (`'agent'`), and host-emitted procedural turns (`'system'` — e.g., `'conversation timed out'`)."
+    },
+    "agent": {
+      "type": "object",
+      "description": "Optional agent reference (RFC 0002 §A1 `AgentRef`) for `role: 'agent'` turns. The same shape RFC 0002 reserves on `RunSnapshot.agent` and `node.started.payload.agent` — propagated through inheritance.",
+      "properties": {
+        "agentId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "agentSharing": {
+          "type": "string",
+          "enum": ["isolated", "shared", "shared:%shared%"],
+          "description": "Per RFC 0002 §A8 — `shared:<groupId>` requires a `groupId` field on the message."
+        },
+        "memoryRef": {
+          "type": "string",
+          "description": "Opaque memory reference per RFC 0002 §A + RFC 0004 §A. Resolves to `MemoryEntry[]` via host `MemoryAdapter` for cross-run conversation continuity."
+        },
+        "model": {
+          "type": "object",
+          "description": "RFC 0109 — OPTIONAL provenance: which model produced this `role: 'agent'` turn. NON-SECRET, NON-PII: provider + model identifiers ONLY (`additionalProperties: false` forbids any credential/endpoint/prompt leaking in — the SR-1 secret-redaction guard). Stamped at emit; read VERBATIM on `:fork` (never re-resolved). A host that stamps it MUST advertise `conversationTurnModelProvenance.supported: true`. Absent ⇒ no advertisement; clients MUST tolerate its absence.",
+          "additionalProperties": false,
+          "required": ["provider", "model"],
+          "properties": {
+            "provider": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Provider identifier (e.g. `anthropic`, `openai`, `google`). Non-secret." },
+            "model": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Model identifier as the provider names it (e.g. `claude-opus-4-8`). Non-secret." }
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "turnIndex": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "0-based index within the conversation. `conversation.opened.initialTurn` carries `turnIndex: 0`; subsequent `conversation.exchanged` turns increment monotonically; `conversation.closed.finalTurn` carries the highest index."
+    },
+    "speakerId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "description": "RFC 0101. Stable speaker identity of this turn — the roster INSTANCE id of the agent that produced it (the `host:<id>` AgentRef agentId per `agent-roster-entry.schema.json` §A / RFC 0086), NOT the manifest/class `AgentRef.agentId`. REQUIRED when `role: 'agent'` (the conditional below) so that 'turn N was spoken by agent X' is an observable, replay-stable, cross-host-projectable fact in a multi-party transcript. When a `participants` roster is declared on `conversation.opened` (RFC 0101), `speakerId` MUST be a member of that roster; a turn whose `speakerId` is not a participant MUST be rejected (host-enforced, capability-gated on `multiPartyConversation.supported`). For `role: 'user'` / `role: 'system'` turns the field is OPTIONAL and carries no normative meaning. Additive-safe: pre-RFC-0101 `role: 'agent'` turns that omit it are accepted by hosts that do NOT advertise `multiPartyConversation`."
+    }
+  },
+  "allOf": [
+    {
+      "$comment": "RFC 0101 — agent turns MUST carry speaker attribution. Conditional (not unconditional `required`) so the field is only mandatory for `role: 'agent'`; `user`/`system` turns and pre-RFC-0101 producers on non-multi-party hosts are unaffected. Capability-gated: hosts enforce this only when advertising `multiPartyConversation.supported` (capabilities.schema.json).",
+      "if": { "properties": { "role": { "const": "agent" } }, "required": ["role"] },
+      "then": { "required": ["speakerId"] }
+    }
+  ],
+  "examples": [
+    {
+      "$comment": "RFC 0101 POSITIVE — an agent turn in a multi-party council carrying speaker attribution (the roster instance id).",
+      "messageId": "council-q1:1:agent",
+      "from": "host:advisor-cfo",
+      "content": "From a cash-runway view I'd push the launch one quarter.",
+      "ts": 1718900000000,
+      "role": "agent",
+      "turnIndex": 1,
+      "speakerId": "host:advisor-cfo"
+    },
+    {
+      "$comment": "RFC 0101 POSITIVE — a user turn; speakerId is OPTIONAL for non-agent roles and omitted here.",
+      "messageId": "council-q1:0:user",
+      "from": "user",
+      "content": "Should we launch in Q3 or Q4?",
+      "ts": 1718900000000,
+      "role": "user",
+      "turnIndex": 0
+    }
+  ],
+  "$comment": "RFC 0101 NEGATIVE (covered by the `allOf`/`if` conditional + conversation scenarios, NOT validatable as an `examples[]` entry which must be VALID): a `{ role: 'agent', ... }` turn that OMITS `speakerId` MUST FAIL validation; see conformance/src/scenarios/multi-party-conversation-shape.test.ts.",
+  "additionalProperties": true
+}

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/credential-provenance.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/credential-provenance.schema.json",
+  "title": "CredentialProvenance",
+  "description": "RFC 0079 §A. Metadata ABOUT a host-issued credential (an RFC 0046 stored reference or an RFC 0047 OAuth token) attached at the tool/egress boundary — never the secret value (SR-1; reuses the RFC 0046 `credential-payload-redaction` posture). Travels with the egress decision, not the credential material. The §C audience-binding MUST is evaluated against `audiences`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["credentialId", "issuer", "audiences"],
+  "properties": {
+    "credentialId": { "type": "string", "minLength": 1, "description": "Stable host-issued id for the credential (the RFC 0046 `ref`, or an OAuth-grant id). Correlates audit + the Keys-page view. NOT the secret value." },
+    "issuer": { "type": "string", "minLength": 1, "description": "Who minted/owns the credential — the host itself (`host`), an RFC 0047 OAuth provider id, or a BYOK principal (RFC 0046). Lets a consumer distinguish host-managed from caller-supplied credentials." },
+    "audiences": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "REQUIRED. The destination hosts/domains (or destination-class ids) the credential is valid for. The §C binding MUST is evaluated against this list — a credential MUST NOT be attached to an egress outside its audiences. Matching is exact host or an explicit `*.domain` suffix form (no arbitrary regex — injection risk; RFC 0079 §UQ1)." },
+    "scopes": { "type": "array", "items": { "type": "string" }, "uniqueItems": true, "description": "MAY — RFC 0049 scopes the credential grants (e.g. `egress:stripe:charge`)." },
+    "expiresAt": { "type": "string", "format": "date-time", "description": "MAY — credential expiry; an expired credential MUST NOT be attached (deny, `reason: \"expired\"`)." },
+    "redactionPolicy": { "type": "string", "enum": ["always", "hash", "host-policy"], "description": "MAY — how the credential surfaces in logs/events. `always`: never appears (default posture, SR-1); `hash`: an SR-1-redacted digest MAY appear; `host-policy`: host-defined. The secret value itself is NEVER on the wire regardless." },
+    "auditCorrelationId": { "type": "string", "minLength": 1, "description": "MAY — id correlating this credential's egress decisions across the run's `egress.decided` events + the host audit log." }
+  }
+}

package/schemas/credential-reference.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/credential-reference.schema.json",
+  "title": "CredentialReference",
+  "description": "RFC 0046. An opaque, host-issued handle to a stored credential. This is the ONLY credential artifact permitted on the wire — it NEVER carries key material. The host's host.credentials resolver dereferences it into the node sandbox at execution time (SECURITY invariant `credential-payload-redaction`).",
+  "type": "object",
+  "required": ["ref"],
+  "properties": {
+    "ref": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Opaque host-issued identifier, e.g. `cred_a3b9c2`. Hosts MUST NOT encode secret material in the ref."
+    },
+    "scope": {
+      "type": "string",
+      "enum": ["user", "workspace", "tenant"],
+      "description": "Resolution scope. MUST match a scope in `capabilities.credentials.scopes`. Absent ⇒ the host's default scope."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/debug-bundle.schema.json

@@ -0,0 +1,196 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/debug-bundle.schema.json",
+  "title": "RunDebugBundle",
+  "description": "Portable JSON export of a single run's diagnostic state. See spec/v1/debug-bundle.md. Additive over v1 per COMPATIBILITY.md §2.1: optional endpoint; hosts MAY omit.",
+  "type": "object",
+  "required": [
+    "bundleVersion",
+    "generatedAt",
+    "host",
+    "run",
+    "events",
+    "redactionApplied",
+    "redactionMode"
+  ],
+  "properties": {
+    "bundleVersion": {
+      "type": "string",
+      "description": "Schema version of the bundle. v1.x bundles are '1'.",
+      "pattern": "^[0-9]+(\\.[0-9]+)?$"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when the host generated this response."
+    },
+    "host": {
+      "type": "object",
+      "description": "Identifies the host that produced the bundle.",
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "vendor": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "run": {
+      "type": "object",
+      "description": "Run snapshot — same shape as GET /v1/runs/{runId}. See run-snapshot.schema.json.",
+      "required": ["runId", "workflowId", "status"],
+      "properties": {
+        "runId": { "type": "string", "minLength": 1 },
+        "workflowId": { "type": "string", "minLength": 1 },
+        "status": {
+          "type": "string",
+          "enum": [
+            "pending",
+            "running",
+            "completed",
+            "failed",
+            "cancelled",
+            "waiting-approval",
+            "waiting-clarification"
+          ]
+        },
+        "startedAt": { "type": "string", "format": "date-time" },
+        "endedAt": {
+          "oneOf": [
+            { "type": "string", "format": "date-time" },
+            { "type": "null" }
+          ]
+        },
+        "error": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["code"],
+              "properties": {
+                "code": { "type": "string", "minLength": 1 },
+                "message": { "type": "string" }
+              },
+              "additionalProperties": true
+            }
+          ]
+        },
+        "inputs": { "type": "object" },
+        "variables": { "type": "object" },
+        "currentNodeId": {
+          "oneOf": [{ "type": "string" }, { "type": "null" }]
+        },
+        "nodeStates": { "type": "object" },
+        "metrics": { "type": "object" }
+      },
+      "additionalProperties": true
+    },
+    "events": {
+      "type": "array",
+      "description": "Full event log for this run, in order. Each entry follows run-event.schema.json.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "sequence": {
+            "oneOf": [
+              { "type": "integer", "minimum": 0 },
+              { "type": "null" }
+            ]
+          },
+          "seq": {
+            "oneOf": [
+              { "type": "integer", "minimum": 0 },
+              { "type": "null" }
+            ],
+            "description": "Legacy alias for `sequence`. Hosts that pre-date the rename emit `seq`. Clients accept either."
+          },
+          "type": { "type": "string", "minLength": 1 },
+          "timestamp": { "type": "string", "format": "date-time" },
+          "nodeId": {
+            "oneOf": [{ "type": "string" }, { "type": "null" }]
+          },
+          "data": {}
+        },
+        "additionalProperties": true
+      }
+    },
+    "spans": {
+      "type": "array",
+      "description": "OTel-format spans per spec/v1/observability.md. Empty array if host doesn't emit spans.",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "spanId": { "type": "string" },
+          "parentSpanId": {
+            "oneOf": [{ "type": "string" }, { "type": "null" }]
+          },
+          "startedAt": { "type": "string", "format": "date-time" },
+          "endedAt": {
+            "oneOf": [
+              { "type": "string", "format": "date-time" },
+              { "type": "null" }
+            ]
+          },
+          "attributes": { "type": "object" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "description": "Aggregate metrics for the run.",
+      "properties": {
+        "openwopCost": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "properties": {
+                "usd": { "type": "number", "minimum": 0 },
+                "tokens": {
+                  "type": "object",
+                  "properties": {
+                    "input": { "type": "integer", "minimum": 0 },
+                    "output": { "type": "integer", "minimum": 0 }
+                  },
+                  "additionalProperties": false
+                },
+                "model": { "type": "string" },
+                "provider": { "type": "string" },
+                "duration_ms": { "type": "number", "minimum": 0 }
+              },
+              "additionalProperties": true
+            }
+          ]
+        },
+        "nodeCount": { "type": "integer", "minimum": 0 },
+        "eventCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "MUST equal events.length per spec/v1/debug-bundle.md."
+        }
+      },
+      "additionalProperties": true
+    },
+    "redactionApplied": {
+      "type": "boolean",
+      "description": "True if any field in this bundle was masked/omitted/hashed by the host's redaction harness."
+    },
+    "redactionMode": {
+      "type": "string",
+      "enum": ["mask", "omit", "hash", "passthrough"],
+      "description": "Masking mode in effect per capabilities.compliance.defaultMode."
+    },
+    "truncated": {
+      "type": "boolean",
+      "description": "True when the bundle was truncated to fit the host's size cap."
+    },
+    "truncatedReason": {
+      "type": "string",
+      "description": "Why truncation occurred (e.g., 'events_truncated_to_size_cap')."
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/dispatch-config.schema.json

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