@openwop/spec-artifacts 2.0.0-rc.0

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

@@ -0,0 +1,324 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/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. v2: RFC 0171 §A.",
+  "type": "object",
+  "required": [
+    "eventId",
+    "payload",
+    "runId",
+    "schemaVersion",
+    "sequence",
+    "timestamp",
+    "type"
+  ],
+  "properties": {
+    "eventId": {
+      "$ref": "ids.schema.json#/$defs/eventId",
+      "description": "Globally unique ID for this event. Generated by appendAtomic before write; consumers MUST treat as opaque."
+    },
+    "runId": {
+      "$ref": "ids.schema.json#/$defs/runId",
+      "description": "Run this event belongs to."
+    },
+    "nodeId": {
+      "$ref": "ids.schema.json#/$defs/nodeId",
+      "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."
+    },
+    "type": {
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": [
+            "agent.decided",
+            "agent.handoff",
+            "agent.invocation-completed",
+            "agent.invocation-started",
+            "agent.memory-consolidated",
+            "agent.prompt-resolved",
+            "agent.reasoned",
+            "agent.reasoning-delta",
+            "agent.tool-called",
+            "agent.tool-returned",
+            "agent.verified",
+            "approval.granted",
+            "approval.overridden",
+            "approval.received",
+            "approval.rejected",
+            "approval.requested",
+            "artifact.created",
+            "authorization.decided",
+            "budget.consumed",
+            "budget.exhausted",
+            "budget.reserved",
+            "budget.threshold-crossed",
+            "cap.breached",
+            "channel.presence",
+            "channel.written",
+            "clarification.requested",
+            "clarification.resolved",
+            "commitment.fired",
+            "compensation.completed",
+            "compensation.failed",
+            "compensation.manual-intervention-required",
+            "compensation.paused",
+            "compensation.requested",
+            "compensation.started",
+            "connector.auth-expired",
+            "connector.authorized",
+            "context.summarized",
+            "conversation.closed",
+            "conversation.exchanged",
+            "conversation.opened",
+            "deployment.canary-adjusted",
+            "deployment.promoted",
+            "deployment.rolled-back",
+            "deployment.state-changed",
+            "dispatch.fanned-out",
+            "dispatch.joined",
+            "egress.decided",
+            "envelope.nl-to-format-engaged",
+            "envelope.recovery-applied",
+            "envelope.refusal",
+            "envelope.retry-attempted",
+            "envelope.retry-exhausted",
+            "envelope.truncated",
+            "eval.completed",
+            "eval.scored",
+            "eval.started",
+            "goal.closed",
+            "goal.evaluated",
+            "import.applied",
+            "interrupt.requested",
+            "interrupt.resolved",
+            "lease.acquired",
+            "lease.handed-off",
+            "lease.lost",
+            "lease.renewed",
+            "log.appended",
+            "memory.compacted",
+            "memory.written",
+            "model.capability-insufficient",
+            "model.capability-substituted",
+            "negotiation.decided",
+            "node.cancelled",
+            "node.completed",
+            "node.dispatched",
+            "node.failed",
+            "node.resumed",
+            "node.retried",
+            "node.skipped",
+            "node.started",
+            "node.suspend-failed",
+            "node.suspended",
+            "orchestrator.decided",
+            "output.chunk",
+            "prompt.composed",
+            "proposal.activated",
+            "proposal.created",
+            "provider.usage",
+            "replay.diverged",
+            "replay.diverged-at-refusal",
+            "roster.run-initiated",
+            "run.cancelled",
+            "run.completed",
+            "run.dead-lettered",
+            "run.failed",
+            "run.paused",
+            "run.restored-from-snapshot",
+            "run.resume-started",
+            "run.resumed",
+            "run.started",
+            "tool.session-closed",
+            "tool.session-opened",
+            "trigger.delivery-attempted",
+            "trigger.subscription-state-changed",
+            "variable.changed",
+            "version.pinned",
+            "voice.barge-in",
+            "voice.cancelled",
+            "voice.endpoint-candidate",
+            "voice.speech-start",
+            "voice.synthesis-chunk",
+            "voice.transcript",
+            "voice.turn-commit",
+            "workflow-chain.confidence-escalated",
+            "workflow-chain.event",
+            "workflow.loopback-limit",
+            "workflow.restored",
+            "workflow.stalled",
+            "workspace.updated"
+          ]
+        },
+        {
+          "type": "string",
+          "pattern": "^(?!openwop\\.)[a-z][a-z0-9]*(-[a-z0-9]+)*\\.[a-z][a-z0-9]*(-[a-z0-9]+)*(\\.[a-z][a-z0-9]*(-[a-z0-9]+)*)?$"
+        }
+      ],
+      "description": "RFC 0171 §A.1 — a registered protocol type (closed enum generated from spec/v2/event-codemap.json) or a vendor event under <org>.<name>; openwop. is the only reserved prefix. Consumers MUST accept an unknown registered member and MUST NOT act on it (§A.5)."
+    },
+    "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": "The one ordering field; first event 0 (RFC 0171 §A.3)."
+    },
+    "schemaVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Per-event schema version (RFC 0172 §B axis 5)."
+    },
+    "engineVersion": {
+      "type": "integer",
+      "description": "Engine version that produced this event. Used by P4 versioning for compatibility checks. v2: integer everywhere (RFC 0172 §B axis 3).",
+      "minimum": 0
+    },
+    "causationId": {
+      "$ref": "ids.schema.json#/$defs/eventId",
+      "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 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": {
+    "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-options.schema.json

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

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

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/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": {
+      "$ref": "ids.schema.json#/$defs/agentId",
+      "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/v2/orchestrator-decision.schema.json"
+    }
+  },
+  "additionalProperties": false,
+  "x-openwop-seeded-from": "v1"
+}

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

@@ -0,0 +1,207 @@
+{
+  "$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 /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",
+    "owner",
+    "runId",
+    "status",
+    "workflowId"
+  ],
+  "properties": {
+    "runId": {
+      "$ref": "ids.schema.json#/$defs/runId",
+      "description": "Globally unique run identifier."
+    },
+    "workflowId": {
+      "$ref": "ids.schema.json#/$defs/workflowId",
+      "description": "ID of the workflow this run executes."
+    },
+    "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",
+      "additionalProperties": false,
+      "required": [
+        "tenant",
+        "subject"
+      ],
+      "properties": {
+        "tenant": {
+          "$ref": "ids.schema.json#/$defs/tenantId"
+        },
+        "workspace": {
+          "$ref": "ids.schema.json#/$defs/workspaceId"
+        },
+        "subject": {
+          "$ref": "subject.schema.json"
+        }
+      },
+      "description": "RFC 0170 §A.1 — the Subject is the owner; principal/principalKind removed. Copied verbatim onto a fork (§A.4)."
+    },
+    "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.",
+      "additionalProperties": true
+    },
+    "variables": {
+      "type": "object",
+      "description": "Workflow-level variables (caller-supplied inputs + per-node outputs that survive the projection).",
+      "additionalProperties": true
+    },
+    "channels": {
+      "type": "object",
+      "description": "Optional typed state channels (see channels-and-reducers.md). Present when the workflow declares channel-aware mode.",
+      "additionalProperties": true
+    },
+    "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": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "engineVersion": {
+      "type": "integer",
+      "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 §A.2 — the era key; a v2 host writes 3; a v1-era run reads 2."
+    },
+    "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`.",
+      "additionalProperties": true
+    },
+    "configurable": {
+      "type": "object",
+      "description": "Per-run overlay from `RunOptions.configurable` (see run-options.md). Reserved keys: `recursionLimit`, `model`, `temperature`, `maxTokens`, `promptOverrides`.",
+      "additionalProperties": true
+    },
+    "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": false
+    }
+  },
+  "additionalProperties": false
+}