@openwop/spec-artifacts 2.0.0-rc.0

package/schemas/run-event.schema.json

@@ -0,0 +1,211 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/run-event.schema.json",
+  "title": "RunEventDoc",
+  "description": "Persisted event document in the run's append-only event log. Source of truth for run state via projection fold. Canonical OpenWOP v1 event envelope.",
+  "type": "object",
+  "required": [
+    "eventId",
+    "runId",
+    "type",
+    "payload",
+    "timestamp",
+    "sequence"
+  ],
+  "properties": {
+    "eventId": {
+      "type": "string",
+      "description": "Globally unique ID for this event. Generated by appendAtomic before write; consumers MUST treat as opaque.",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "runId": {
+      "type": "string",
+      "description": "Run this event belongs to.",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "nodeId": {
+      "type": "string",
+      "description": "Set for node-scoped events (node.*, approval.*, clarification.*). Lifted to top-level so projection code can key per-node state machines without payload type coercion.",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "type": {
+      "description": "Event-type discriminator. RFC 0094 \u00a7C: either a protocol-owned type from the authoritative `RunEventType` catalog, or a correctly-prefixed vendor-extension event per `host-extensions.md` \u00a7\"Vendor-prefixed namespaces\" (dotted name whose first segment is the vendor's short identifier or reverse-DNS label \u2014 e.g. `acme.canvas.published` \u2014 and is NOT a protocol-owned/registry-reserved prefix). Aligns the schema with `COMPATIBILITY.md` (\"Clients MUST ignore unknown event types\") and `version-negotiation.md` (readers ignore unknown).",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/RunEventType"
+        },
+        {
+          "type": "string",
+          "pattern": "^(?!(?:openwop|core|community|vendor|private|local)\\.)[a-z][a-zA-Z0-9_-]*(\\.[a-zA-Z0-9_-]+)+$",
+          "description": "Vendor-extension event type: two or more dot-separated segments; the leading segment is the vendor prefix and MUST NOT be one of the protocol-owned / registry-reserved prefixes (`openwop.*`, `core.*`, `community.*`, `vendor.*`, `private.*`, `local.*`) per `host-extensions.md` \u00a7\"Canonical prefixes\"."
+        }
+      ]
+    },
+    "payload": {
+      "description": "Event-type-specific payload. Servers MAY validate against per-type schemas; this top-level schema accepts any JSON value.",
+      "type": [
+        "object",
+        "array",
+        "string",
+        "number",
+        "boolean",
+        "null"
+      ]
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp. IO adapters normalize between this canonical form and platform-specific representations (e.g., Firestore Timestamp)."
+    },
+    "sequence": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Monotonic per-run sequence. First event is 0; assigned atomically by appendAtomic."
+    },
+    "schemaVersion": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Per-event schema version. Bumped when an individual event type's payload contract changes. Distinct from per-run eventLogSchemaVersion (which describes the subcollection contract). Reader behavior is tolerant \u2014 unknown future versions fold best-effort."
+    },
+    "engineVersion": {
+      "type": "string",
+      "description": "Engine version that produced this event. Used by P4 versioning for compatibility checks."
+    },
+    "causationId": {
+      "type": "string",
+      "description": "Optional ID of the event that caused this one (e.g., node.completed caused by approval.received). Lets projections build causal chains without inferring from timing.",
+      "minLength": 1,
+      "maxLength": 128
+    }
+  },
+  "$comment": "RFC 0094 \u00a7G + COMPATIBILITY.md \u00a7\"Schema closure\": RunEventDoc is a SERVER-EMITTED shape, so it is open (`additionalProperties: true`) \u2014 v1.x hosts may add optional fields additively without breaking schema-validating clients. Client-submitted shapes stay closed at their outermost composition.",
+  "additionalProperties": true,
+  "$defs": {
+    "RunEventType": {
+      "type": "string",
+      "description": "Discriminator for event payload shape. Dotted naming convention. New variants extend the union \u2014 readers MUST NOT throw on unknown types (forward-compat: fold best-effort, ignore unknowns). RFC 0151 \u00a7D adds the six content-free `compensation.*` events. They are added to this CLOSED enum because without them a conforming host cannot emit them at all: the RFC named the events, the enum did not contain them, and any host following \u00a7D would have produced run events that fail schema validation. Payloads carry opaque node/effect IDs, attempt, ordering model, and closed reason codes \u2014 never provider bodies or credentials (\u00a7D/\u00a7G).",
+      "enum": [
+        "run.started",
+        "run.completed",
+        "run.failed",
+        "run.cancelled",
+        "run.resuming",
+        "run.paused",
+        "run.resumed",
+        "run.restored-from-snapshot",
+        "run.dead_lettered",
+        "node.started",
+        "node.completed",
+        "node.failed",
+        "node.suspended",
+        "node.suspend-failed",
+        "node.resumed",
+        "node.retried",
+        "node.skipped",
+        "node.cancelled",
+        "approval.requested",
+        "approval.received",
+        "approval.granted",
+        "approval.rejected",
+        "approval.overridden",
+        "clarification.requested",
+        "clarification.resolved",
+        "interrupt.requested",
+        "interrupt.resolved",
+        "channel.written",
+        "channel.presence",
+        "context.summarized",
+        "artifact.created",
+        "output.chunk",
+        "variable.changed",
+        "log.appended",
+        "version.pinned",
+        "workflow.restored",
+        "workflow.loopback-limit",
+        "workflow.stalled",
+        "cap.breached",
+        "lease.acquired",
+        "lease.renewed",
+        "lease.lost",
+        "lease.handed-off",
+        "replay.diverged",
+        "replay.divergedAtRefusal",
+        "agent.reasoned",
+        "agent.reasoning.delta",
+        "provider.usage",
+        "prompt.composed",
+        "agent.promptResolved",
+        "model.capability.substituted",
+        "model.capability.insufficient",
+        "envelope.retry.attempted",
+        "envelope.retry.exhausted",
+        "envelope.refusal",
+        "envelope.truncated",
+        "envelope.nlToFormat.engaged",
+        "envelope.recovery.applied",
+        "agent.toolCalled",
+        "agent.toolReturned",
+        "agent.handoff",
+        "agent.decided",
+        "agent.verified",
+        "agent.invocation.started",
+        "agent.invocation.completed",
+        "eval.started",
+        "eval.scored",
+        "eval.completed",
+        "deployment.promoted",
+        "deployment.rolled-back",
+        "deployment.canary.adjusted",
+        "deployment.state.changed",
+        "roster.run.initiated",
+        "tool.session.opened",
+        "tool.session.closed",
+        "egress.decided",
+        "trigger.subscription.state.changed",
+        "trigger.delivery.attempted",
+        "budget.reserved",
+        "budget.consumed",
+        "budget.threshold.crossed",
+        "budget.exhausted",
+        "runOrchestrator.decided",
+        "node.dispatched",
+        "core.dispatch.fanOut",
+        "core.dispatch.join",
+        "conversation.opened",
+        "conversation.exchanged",
+        "conversation.closed",
+        "memory.compacted",
+        "memory.written",
+        "agent.memory.consolidated",
+        "commitment.fired",
+        "workspace.updated",
+        "core.workflowChain.event",
+        "core.workflowChain.confidence-escalated",
+        "connector.authorized",
+        "connector.auth_expired",
+        "authorization.decided",
+        "proposal.created",
+        "proposal.activated",
+        "goal.evaluated",
+        "goal.closed",
+        "import.applied",
+        "voice.speech_start",
+        "voice.transcript",
+        "voice.endpoint_candidate",
+        "voice.turn_commit",
+        "voice.synthesis_chunk",
+        "voice.barge_in",
+        "voice.cancelled",
+        "compensation.requested",
+        "compensation.started",
+        "compensation.completed",
+        "compensation.failed",
+        "compensation.paused",
+        "compensation.manual_intervention_required"
+      ]
+    }
+  }
+}

package/schemas/run-options.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/run-options.schema.json",
+  "title": "RunOptions",
+  "description": "Per-run parameter overlay supplied by the caller in `POST /v1/runs`. See `run-options.md` for full semantics. Reserved keys are typed; unknown keys in `configurable` pass through to the engine. RFC 0094 §A: this schema is OPEN at its own root (no `additionalProperties: false`) because it participates in the composed `createRun` request body in `api/openapi.yaml`; the closure (`unevaluatedProperties: false`) lives at that composition site, the only place JSON Schema 2020-12 can express closure over an `allOf`.",
+  "type": "object",
+  "properties": {
+    "configurable": {
+      "$ref": "#/$defs/Configurable",
+      "description": "Per-run overrides that affect runtime behavior without forking the workflow definition."
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1, "maxLength": 256 },
+      "maxItems": 100,
+      "uniqueItems": false,
+      "description": "Free-form caller tags for filtering/correlation. Server SHOULD enforce maxItems=100 and per-tag maxLength=256."
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Free-form caller metadata. Persisted on the run doc; surfaces back via `RunSnapshot.metadata`. Server MAY enforce a serialized-size limit (recommended: 50KB)."
+    }
+  },
+  "$defs": {
+    "Configurable": {
+      "type": "object",
+      "description": "Reserved keys are typed below; unknown keys pass through verbatim. Implementations declare which keys they consume via `Capabilities.configurable` when advertised.",
+      "properties": {
+        "recursionLimit": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Override the per-run node-execution ceiling. Server clamps to `Capabilities.limits.maxNodeExecutions`."
+        },
+        "model": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Override the AI model for nodes that consume `ctx.config.configurable.model`. Examples: `gpt-4`, `claude-opus-4-7`, `gemini-2.5-pro`."
+        },
+        "temperature": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2,
+          "description": "Override AI temperature. Server SHOULD enforce 0..2 range."
+        },
+        "maxTokens": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Override AI max-tokens cap."
+        },
+        "promptOverrides": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Per-prompt-ID variant override. Map of canonical prompt ID -> override text."
+        },
+        "mockProvider": {
+          "$ref": "#/$defs/MockProvider"
+        }
+      },
+      "additionalProperties": true
+    },
+    "MockProvider": {
+      "type": "object",
+      "description": "Routes AI activity calls through a deterministic mock provider instead of real LLM APIs. Test-keys-only — server returns 403 mock_provider_forbidden on production keys. See run-options.md §Mock provider extension (closes F1).",
+      "required": ["id"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Selects a mock provider from the server's catalog (advertised via `Capabilities.testing.mockProviders`). The spec-canonical baseline `stream-text` MUST be supported for OpenWOP v1.0 conformance; other providers (`tool-calls`, `error`, `usage-only`) are recommended but not required.",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "config": {
+          "type": "object",
+          "description": "Per-provider parameter shape. Each provider documents its own keys; see run-options.md §Canonical mock provider catalog. Common shapes (informative — not enforced at this schema level since providers are pluggable):\n\n  - stream-text: { tokens: string[], delayMsPerToken?: integer, finishReason?: string, usage?: object, model?: string }\n  - tool-calls: { toolCalls: object[], delayMsPerToken?: integer }\n  - error: { code: string, message: string, retryable?: boolean, failAfterMs?: integer }\n  - usage-only: { usage: object }"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/run-orchestrator-decided-event.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/run-orchestrator-decided-event.schema.json",
+  "title": "RunOrchestratorDecidedPayload",
+  "description": "Payload for the `runOrchestrator.decided` RunEvent. Emitted exactly once per orchestrator decision by a `core.orchestrator.supervisor` node (or a host-extension equivalent that advertises orchestration). Carries the deciding agent's identity and the typed decision (orchestrator-decision.schema.json). The event envelope's top-level `nodeId` field carries the supervisor node-id; the payload does NOT duplicate it. See RFC 0006 §E for ordering invariants CO-1/CO-2/CO-3.",
+  "type": "object",
+  "required": ["agentId", "decision"],
+  "properties": {
+    "agentId": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 256,
+      "description": "AgentRef.agentId of the orchestrator that emitted this decision. MUST equal `RunSnapshot.runOrchestrator.agentId` for the run's lifetime — the orchestrator identity is set at the first decision and does not change."
+    },
+    "decision": {
+      "$ref": "https://openwop.dev/spec/v1/orchestrator-decision.schema.json"
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/run-snapshot.schema.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/run-snapshot.schema.json",
+  "title": "RunSnapshot",
+  "description": "Projected run state returned by `GET /v1/runs/{runId}`. Source is the run's append-only event log (run-event.schema.json) folded through the `RunProjection`. Forward-compat tolerant: readers MUST ignore unknown fields rather than reject.",
+  "type": "object",
+  "required": ["runId", "workflowId", "status"],
+  "properties": {
+    "runId": {
+      "type": "string",
+      "description": "Globally unique run identifier.",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "workflowId": {
+      "type": "string",
+      "description": "ID of the workflow this run executes.",
+      "minLength": 1
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "pending",
+        "running",
+        "paused",
+        "waiting-approval",
+        "waiting-input",
+        "waiting-external",
+        "completed",
+        "failed",
+        "cancelling",
+        "cancelled"
+      ],
+      "description": "Current run state. `waiting-external` MUST be used when the suspended interrupt's `kind` is `external-event` per `interrupt-profiles.md §openwop-interrupt-external-event` — distinguishes external-event waits from HITL waits at the wire level. `cancelling` (RFC 0094 §B) is the transitional state between a cancel request being accepted and the terminal `cancelled` — `rest-endpoints.md` and the OpenAPI cancel responses already document the transition; a snapshot read during the cancel cascade carries it. Forward-compat: future statuses MAY be added; readers SHOULD treat unknown values as terminal-unknown rather than throw."
+    },
+    "compensationStatus": {
+      "type": "string",
+      "enum": ["none", "pending", "running", "completed", "partial", "failed", "manual"],
+      "description": "RFC 0151 §D — the run's compensation (unwind) rollup, kept separate from `status` on purpose: `status` is the FORWARD execution state and a closed union exported by the SDK, so RFC 0151 forbids reinterpreting it (there is deliberately no `compensating` run status). OPTIONAL and capability-gated — a host that does not advertise `capabilities.compensation` MUST omit this field; a host that advertises it MUST include it on every snapshot, `none` when no compensation was ever requested for the run. Presence is therefore a wire witness of the advert, and a `none` cannot be read as \"unwind is monitored here\" from a host that would never unwind. Values are the deterministic fold of the six `compensation.*` events over the persisted plan, defined normatively in `spec/v1/compensation.md §\"Run rollup: compensationStatus\"`: `none` (no `compensation.requested`), `pending` (requested, no `started`), `running` (started, plan active — a §E approval pause does NOT change it; the run's own `status: waiting-approval` carries the wait), `completed` (every inverse action completed), `partial` (plan inactive; some completed and some did not — reported, never rounded), `failed` (plan inactive; none completed), `manual` (`manual_intervention_required` recorded and unresolved; takes precedence over `partial`/`failed` while unresolved). Content-free by construction. Resolves RFC 0151 UQ3: `RunSnapshot` (`GET /v1/runs/{runId}`) is the sole owner; debug bundles and the AsyncAPI `run.snapshot` reuse it by `$ref`."
+    },
+    "owner": {
+      "type": "object",
+      "description": "RFC 0048. The identity triple that owns this run. Redaction-safe — `principal` is an opaque identifier, never PII or credential material. Optional: single-tenant hosts omit it. A principal scoped to one `workspace` MUST NOT read a run owned by another (`run_forbidden`).",
+      "required": ["tenant"],
+      "properties": {
+        "tenant": { "type": "string", "minLength": 1, "description": "Top-level isolation boundary." },
+        "workspace": { "type": "string", "minLength": 1, "description": "Optional sub-tenant within the tenant (RFC 0048 workspace)." },
+        "principal": { "type": "string", "minLength": 1, "description": "Acting identity (user or agent) — opaque id, never PII." },
+        "subject": {
+          "$ref": "subject.schema.json",
+          "description": "RFC 0165 \u00a7B. OPTIONAL issuer-scoped Subject record for the acting identity. When present: `subject.tenant` MUST equal `tenant`, `subject.subjectId` MUST equal `principal` when both are present, `subject.kind` MUST equal `principalKind` when both are present. A host that emits it on new runs synthesizes `issuer: \"urn:openwop:legacy\"` for runs that predate emission (\u00a7B.3) and copies it verbatim onto forks (\u00a7B.4)."
+        },
+        "principalKind": {
+          "type": "string",
+          "enum": ["user", "agent", "anonymous"],
+          "description": "RFC 0132. The kind of the acting principal. OPTIONAL and EXPLICIT — absent ⇒ unconstrained (today's RFC 0048 behavior; a host that does not distinguish kinds omits it). `anonymous` ⇒ the RFC 0132 §A anonymous-actor rules and the §C default-deny per-surface grant bind: the `principal` id MUST be opaque, origin-bound, ephemeral, non-cross-linkable, non-PII, and never inherit a role or a default-on tool baseline. A host that advertises `capabilities.anonymousActor` and dispatches through a public surface MUST set `anonymous` on the resulting run. Resolves RFC 0048 §Unresolved-Q1 for the anonymous case."
+        }
+      },
+      "additionalProperties": false
+    },
+    "currentNodeId": {
+      "type": "string",
+      "description": "Set when the run is suspended at a specific node (`waiting-approval` / `waiting-input` / `waiting-external`) — identifies which node holds the interrupt."
+    },
+    "startedAt": { "type": "string", "format": "date-time" },
+    "completedAt": { "type": "string", "format": "date-time" },
+    "agent": {
+      "$ref": "agent-ref.schema.json",
+      "description": "Optional run-level agent identity (Multi-Agent Shift Phase 1). When the run is driven by a single agent, this field carries that agent's `AgentRef`. In supervisor-orchestrated runs (Phase 5), this field rotates as workers hand off — it always carries the active worker for the current node. See `runOrchestrator` for the run-lifetime supervisor identity. Absent for runs with no agent provenance (legacy single-actor host)."
+    },
+    "runOrchestrator": {
+      "$ref": "agent-ref.schema.json",
+      "description": "Optional orchestrator-supervisor identity (Multi-Agent Shift Phase 5). When set, this agent owns dispatch decisions across the run's lifetime; `runOrchestrator.decided` events emitted during the run carry this agent's `agentId`. Distinct from `agent` — `agent` rotates with each worker; `runOrchestrator` is set at run start (or first `core.orchestrator.supervisor` node) and MUST NOT change for the run's lifetime. In single-agent runs (no supervisor), this field is absent; in supervisor runs both fields MAY co-exist."
+    },
+    "nodeStates": {
+      "type": "object",
+      "description": "Per-node state map. Keys are nodeIds; values are implementation-shaped state objects. Spec doesn't constrain the inner shape — see version-negotiation.md §node-states."
+    },
+    "variables": {
+      "type": "object",
+      "description": "Workflow-level variables (caller-supplied inputs + per-node outputs that survive the projection)."
+    },
+    "channels": {
+      "type": "object",
+      "description": "Optional typed state channels (see channels-and-reducers.md). Present when the workflow declares channel-aware mode."
+    },
+    "error": {
+      "type": "object",
+      "description": "Set on terminal `failed`. Structured so consumers can route on code without parsing message text.",
+      "required": ["code", "message"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "details": { "type": "object" }
+      },
+      "additionalProperties": false
+    },
+    "engineVersion": {
+      "type": "string",
+      "description": "Engine version the run was started under. Used by the projection for forward-compat folds."
+    },
+    "eventLogSchemaVersion": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Per-run event-log subcollection schema version. See version-negotiation.md."
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "maxLength": 256 },
+      "maxItems": 100,
+      "description": "Caller-supplied tags from `RunOptions.tags`."
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Caller-supplied metadata from `RunOptions.metadata`."
+    },
+    "configurable": {
+      "type": "object",
+      "description": "Per-run overlay from `RunOptions.configurable` (see run-options.md). Reserved keys: `recursionLimit`, `model`, `temperature`, `maxTokens`, `promptOverrides`."
+    },
+    "metrics": {
+      "type": "object",
+      "description": "Aggregate run-level metrics. Forward-compat: readers MUST tolerate missing/unknown fields. Fields are populated lazily as the engine emits them — absence does NOT mean zero. Implementation-specific fields (e.g., legacy `cost: number` estimates) MAY appear alongside the spec-canonical fields below.",
+      "properties": {
+        "openwopCost": {
+          "type": "object",
+          "description": "Spec-canonical cost rollup aggregated from per-node `recordCost()` calls. Keys mirror the `openwop.cost.*` OTel attribute allowlist (see `observability.md` §Cost attribution). Named `openwopCost` rather than `cost` because some implementations carry a legacy `metrics.cost: number` estimate that predates the typed rollup; using a distinct name avoids collision. Multi-provider runs report `provider`/`model` of the LAST contributing call; SDKs that need per-call detail SHOULD subscribe to OTel spans instead of reading this rollup.",
+          "properties": {
+            "usd": { "type": "number", "minimum": 0, "description": "Total USD cost across all node-level recordCost emissions." },
+            "tokens": {
+              "type": "object",
+              "properties": {
+                "input": { "type": "integer", "minimum": 0 },
+                "output": { "type": "integer", "minimum": 0 }
+              },
+              "additionalProperties": false
+            },
+            "model": { "type": "string", "description": "Model identifier of the most recent recordCost emission (e.g., `claude-opus-4-7`). For multi-model runs, surfaces the last value." },
+            "provider": { "type": "string", "description": "Normalized provider name (e.g., `anthropic`, `openai`, `gemini`)." },
+            "duration_ms": { "type": "integer", "minimum": 0, "description": "Sum of per-call durations across all recordCost emissions in this run." }
+          },
+          "additionalProperties": false
+        }
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/security-advisory.schema.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/security-advisory.schema.json",
+  "title": "SecurityAdvisory",
+  "description": "Registry-owned security advisory for a published OpenWOP pack version. Sourced from registry/security/advisories.json. Every entry MUST be reviewed + merged via maintainer PR; the CI check-advisories gate refuses to deploy if any active advisory targets a pack version that is not already yanked.",
+  "type": "object",
+  "required": ["id", "publishedAt", "severity", "summary", "affected"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Stable advisory identifier. Format: `OPENWOP-YYYY-NNNN` (sequential, assigned by maintainers at PR merge time). MAY also include an aliased CVE ID via `cveIds[]`.",
+      "pattern": "^OPENWOP-[0-9]{4}-[0-9]{4}$"
+    },
+    "cveIds": {
+      "type": "array",
+      "description": "Aliased CVE identifiers if a CVE was reserved through Mitre or a CNA. Listed in cve.mitre.org format.",
+      "items": {
+        "type": "string",
+        "pattern": "^CVE-[0-9]{4}-[0-9]+$"
+      },
+      "uniqueItems": true
+    },
+    "publishedAt": {
+      "type": "string",
+      "format": "date",
+      "description": "Date the advisory was first published (ISO 8601 yyyy-mm-dd). Frozen at merge time; do not update on revision."
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date",
+      "description": "Date of last advisory update. Bump when severity, affected, or fixedIn changes."
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["critical", "high", "medium", "low"],
+      "description": "Severity per the rubric in docs/runbooks/INCIDENT-RESPONSE.md. critical=S0 (yank immediately), high=S1, medium=S2, low=S3."
+    },
+    "cvssV4Score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 10,
+      "description": "Optional CVSS 4.0 base score. Informational; severity field is the authoritative classification."
+    },
+    "summary": {
+      "type": "string",
+      "description": "One-line human-readable summary of the vulnerability. Surfaces in tooling output.",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "details": {
+      "type": "string",
+      "description": "Long-form description: vulnerability mechanism, attack vector, impact, recommended consumer action. May reference external URLs via advisoryUrl."
+    },
+    "advisoryUrl": {
+      "type": "string",
+      "format": "uri",
+      "description": "External advisory link (e.g., GitHub Security Advisory, vendor security page, CVE detail page)."
+    },
+    "affected": {
+      "type": "array",
+      "description": "Pack versions impacted by this advisory. Each entry pins a pack name + a SemVer range. The check-advisories CI gate cross-references this list against every published version and fails if any non-yanked version matches.",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["packName", "versions"],
+        "properties": {
+          "packName": {
+            "type": "string",
+            "description": "Pack name (e.g., `vendor.myndhyve.ai`). MUST exist under registry/v1/packs/.",
+            "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+          },
+          "versions": {
+            "type": "string",
+            "description": "SemVer range using node-semver syntax (`<1.0.0`, `>=1.0.0 <1.0.3`, `1.0.0 || 1.0.1`). Matched against published version numbers via the check-advisories gate."
+          },
+          "fixedIn": {
+            "type": "string",
+            "description": "Earliest version that contains the fix. Consumers MUST upgrade to >= this version. Absent if no fix is available yet (defense-only).",
+            "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.-]+)?(\\+[a-zA-Z0-9.-]+)?$"
+          },
+          "fixedInRef": {
+            "type": "string",
+            "description": "PR or commit reference where the fix landed (e.g., `openwop/openwop#42`). Helps consumers audit the patch."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "credits": {
+      "type": "array",
+      "description": "Acknowledged reporters or researchers.",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "url": { "type": "string", "format": "uri" },
+          "role": {
+            "type": "string",
+            "enum": ["finder", "reporter", "analyst", "coordinator", "remediation-developer"],
+            "description": "Per CSAF role vocabulary. Defaults to `finder` when not specified."
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/self-hosted-runner-dispatch-frame.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/self-hosted-runner-dispatch-frame.schema.json",
+  "title": "SelfHostedRunnerDispatchFrame",
+  "description": "RFC 0122 §Registration + channel. A single model/tool DISPATCH STEP the host routes to a registered runner over the runner↔host channel (`self-hosted-runner.md`). The host is the sole orchestration/persistence/replay authority; this frame carries ONE step's inputs, never a whole run. `inputs` is opaque model/tool input (messages, tool arguments) and MUST NOT contain runner-credential material — the runner holds its own credential locally (SECURITY invariant `runner-credential-non-transit`). `seq` is the per-runner monotonic DISPATCH cursor, a DISTINCT sequence from the run event-log `sequence` (they MUST NOT be conflated); a reconnecting runner resumes via `Last-Event-ID` at this cursor and the host drops any redelivered `{runId, stepId}` whose result is already persisted (at-most-once).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["runId", "stepId", "seq", "kind", "inputs"],
+  "properties": {
+    "runId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The backing OpenWOP run this dispatch belongs to. Host-owned run identity."
+    },
+    "stepId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The dispatch step within the run. The `{runId, stepId}` pair is the at-most-once idempotency key: a runner MUST return the result under the same pair, and the host MUST drop (not re-dispatch) a redelivered `{runId, stepId}` whose result is already persisted."
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "The per-runner monotonic dispatch cursor for the channel. DISTINCT from the run event-log `sequence` (MUST NOT be conflated — conflating them breaks resume dedup). A reconnecting runner resumes via the SSE `Last-Event-ID` at this cursor so a dispatch is never redelivered past it (`stream-modes.md §Resumption`)."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["model", "tool"],
+      "description": "Whether this step dispatches a model call (`model`) or a tool call (`tool`). A host MAY advertise only a subset via `selfHostedRunner.dispatchKinds` and route only those kinds to runners."
+    },
+    "provider": {
+      "type": "string",
+      "minLength": 1,
+      "description": "REQUIRED when `kind == 'model'`. The model provider id the runner dispatches to under its locally-held credential (e.g. a subscription CLI login, a private endpoint). Never a host-held credential."
+    },
+    "model": {
+      "type": "string",
+      "minLength": 1,
+      "description": "REQUIRED when `kind == 'model'`. The model id to run."
+    },
+    "tool": {
+      "type": "string",
+      "minLength": 1,
+      "description": "REQUIRED when `kind == 'tool'`. The tool the runner executes locally."
+    },
+    "inputs": {
+      "type": "object",
+      "description": "Opaque model/tool inputs for this step (messages, tool arguments). MUST NOT contain runner-credential material (`runner-credential-non-transit`). The host sends inputs and receives outputs; the credential stays on the runner."
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "kind": { "const": "model" } } },
+      "then": { "required": ["provider", "model"] }
+    },
+    {
+      "if": { "properties": { "kind": { "const": "tool" } } },
+      "then": { "required": ["tool"] }
+    }
+  ],
+  "examples": [
+    {
+      "runId": "run_x",
+      "stepId": "step_3",
+      "seq": 12,
+      "kind": "model",
+      "provider": "anthropic",
+      "model": "claude-opus-4-8",
+      "inputs": { "messages": [{ "role": "user", "content": "summarize the attached notes" }] }
+    },
+    {
+      "runId": "run_y",
+      "stepId": "step_1",
+      "seq": 0,
+      "kind": "tool",
+      "tool": "local.shell.readFile",
+      "inputs": { "path": "/home/user/notes.txt" }
+    }
+  ]
+}