@openwop/spec-artifacts 2.0.0-rc.37 → 2.0.0-rc.6

package/schemas/v2/run-event.schema.json

@@ -195,7 +195,131 @@
       "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."
     }
   },
-  "$comment": "RFC 0171 §A / `events.md` §\"The envelope\": in v2 RunEventDoc is CLOSED (`additionalProperties: false`). This reverses the v1 rule, which left the envelope open so v1.x hosts could add optional fields additively. The v2 envelope carries host-specific data in the registered vendor branch, not at the root. Do not restore the v1 sentence: a host that follows it emits root-level extension fields and fails `v2-event-type-closed`, and the schema keyword is the contract while a comment is only a claim about it.",
+  "$comment": "RFC 0094 §G + COMPATIBILITY.md §\"Schema closure\": RunEventDoc is a SERVER-EMITTED shape, so it is open (`additionalProperties: true`) — v1.x hosts may add optional fields additively without breaking schema-validating clients. Client-submitted shapes stay closed at their outermost composition.",
   "additionalProperties": false,
-  "$defs": {}
+  "$defs": {
+    "RunEventType": {
+      "type": "string",
+      "description": "Discriminator for event payload shape. Dotted naming convention. New variants extend the union — readers MUST NOT throw on unknown types (forward-compat: fold best-effort, ignore unknowns). RFC 0151 §D 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 §D would have produced run events that fail schema validation. Payloads carry opaque node/effect IDs, attempt, ordering model, and closed reason codes — never provider bodies or credentials (§D/§G).",
+      "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/v2/run-snapshot.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openwop.dev/spec/v2/run-snapshot.schema.json",
   "title": "RunSnapshot",
-  "description": "Projected run state returned by `GET /runs/{runId}`. Source is the run\u2019s append-only event log (run-event.schema.json) folded through the `RunProjection`. CLOSED in v2 (`additionalProperties: false`): a reader MUST NOT expect to ignore unknown root fields, because there are none to ignore \u2014 host-specific state goes in `extensions`. The v1 schema was open and therefore never had to declare what hosts actually served; closing the object is what made that visible.",
+  "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": [
     "eventLogSchemaVersion",
@@ -34,7 +34,7 @@
         "cancelling",
         "cancelled"
       ],
-      "description": "Current run state. `waiting-external` MUST be used when the suspended interrupt's `kind` is `external-event` per `interrupt-profiles.md \u00a7openwop-interrupt-external-event` \u2014 distinguishes external-event waits from HITL waits at the wire level. `cancelling` (RFC 0094 \u00a7B) is the transitional state between a cancel request being accepted and the terminal `cancelled` \u2014 `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."
+      "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",
@@ -47,7 +47,7 @@
         "failed",
         "manual"
       ],
-      "description": "RFC 0151 \u00a7D \u2014 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 \u2014 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 \u00a7\"Run rollup: compensationStatus\"`: `none` (no `compensation.requested`), `pending` (requested, no `started`), `running` (started, plan active \u2014 a \u00a7E 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 \u2014 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`."
+      "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",
@@ -67,11 +67,11 @@
           "$ref": "subject.schema.json"
         }
       },
-      "description": "RFC 0170 \u00a7A.1 \u2014 the Subject is the owner; principal/principalKind removed. Copied verbatim onto a fork (\u00a7A.4)."
+      "description": "RFC 0170 §A.1 — the Subject is the owner; principal/principalKind removed. Copied verbatim onto a fork (§A.4)."
     },
     "currentNodeId": {
-      "$ref": "ids.schema.json#/$defs/nodeId",
-      "description": "Set when the run is suspended at a specific node (`waiting-approval` / `waiting-input` / `waiting-external`) \u2014 identifies which node holds the interrupt."
+      "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",
@@ -83,15 +83,15 @@
     },
     "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 \u2014 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)."
+      "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` \u2014 `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."
+      "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 \u2014 see version-negotiation.md \u00a7node-states.",
+      "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.",
       "additionalProperties": true
     },
     "variables": {
@@ -129,13 +129,13 @@
     },
     "engineVersion": {
       "type": "integer",
-      "description": "Engine version the run was started under. Used by the projection for forward-compat folds. v2: integer everywhere (RFC 0172 \u00a7B axis 3).",
+      "description": "Engine version the run was started under. Used by the projection for forward-compat folds. v2: integer everywhere (RFC 0172 §B axis 3).",
       "minimum": 0
     },
     "eventLogSchemaVersion": {
       "type": "integer",
       "minimum": 2,
-      "description": "RFC 0176 \u00a7A.2 \u2014 the era key; a v2 host writes 3; a v1-era run reads 2."
+      "description": "RFC 0176 §A.2 — the era key; a v2 host writes 3; a v1-era run reads 2."
     },
     "tags": {
       "type": "array",
@@ -158,11 +158,11 @@
     },
     "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 \u2014 absence does NOT mean zero. Implementation-specific fields (e.g., legacy `cost: number` estimates) MAY appear alongside the spec-canonical fields below.",
+      "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` \u00a7Cost 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.",
+          "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",
@@ -201,27 +201,6 @@
         }
       },
       "additionalProperties": false
-    },
-    "parentRunId": {
-      "$ref": "ids.schema.json#/$defs/runId",
-      "description": "RFC 0022 / `runs.md` \u00a7forkRun \u2014 the run this one was forked from, absent on a root run. Declared because the object is closed: a fork\u2019s lineage is real protocol state, and an undeclared field on a closed object is deleted rather than ignored."
-    },
-    "inputs": {
-      "type": "object",
-      "description": "RFC 0022 \u00a7A \u2014 the inputs the run was created with. Declared for the same reason as parentRunId: the v1 wire carried it under an open schema, and closing the object without a seat would force every host to drop it.",
-      "additionalProperties": true
-    },
-    "extensions": {
-      "type": "object",
-      "additionalProperties": false,
-      "patternProperties": {
-        "^[a-z][a-z0-9]*(-[a-z0-9]+)*\\.[a-z][a-z0-9]*(-[a-z0-9]+)*$": {
-          "type": "object",
-          "additionalProperties": true,
-          "description": "A vendor/host extension record; its shape is the org\u2019s, declared open on purpose."
-        }
-      },
-      "description": "RFC 0169 \u00a7A.4 \u2014 the seat for host-specific snapshot state, keyed `<org>.<name>`. Closing an object without an extension seat does not make hosts stop having extra state; it makes them delete it or serve an invalid document. Every other closed v2 surface has this seat and the snapshot was the omission."
     }
   },
   "additionalProperties": false