@openwop/spec-artifacts 2.0.0-rc.0

package/api/v2/openapi.yaml

@@ -0,0 +1,3139 @@
+openapi: 3.1.0
+info:
+  title: OpenWOP v2 API
+  version: 2.0.0-rc.0
+  summary: REST surface for declaring, executing, suspending, resuming, and observing multi-step workflows.
+  description: GENERATED by scripts/derive-v2-api.py from api/openapi.yaml and the RFC 0167 children (v2 charter Phase 3,
+    P3-C). Bare origin, unversioned path keys, negotiation by `OpenWOP-Version` + `protocolVersions[]` (RFC 0172 §A). No seam
+    or test-mode operation lives here (RFC 0168 §C.2 — see api/seams-v2.yaml). Every non-standard header is `OpenWOP-<Name>`
+    (RFC 0171 §C.1). Retry timing lives in `Retry-After` only (RFC 0171 §B.2).
+  contact:
+    name: openwop spec working group
+    url: https://openwop.dev/spec/v1/
+  license:
+    name: Apache-2.0
+    identifier: Apache-2.0
+externalDocs:
+  description: openwop spec v1 corpus
+  url: https://openwop.dev/spec/v1/
+servers:
+- url: https://{host}
+  description: openwop-compliant server
+  variables:
+    host:
+      default: api.example.com
+      description: Replace with your server's hostname.
+security:
+- ApiKeyAuth: []
+tags:
+- name: discovery
+  description: Public capability + spec discovery (no auth required).
+- name: workflows
+  description: Workflow definition manifest.
+- name: runs
+  description: Run lifecycle — create, read, stream, cancel, fork.
+- name: agents
+  description: Manifest-agent inventory (RFC 0072 §A). Read-only; gated on capabilities.agents.manifestRuntime. Dispatch rides
+    the run surface (WorkflowNode.agent + POST /v1/runs).
+- name: tools
+  description: Portable tool catalog (RFC 0078 §B). Read-only ToolDescriptor projection across tool sources (node-pack / workflow
+    / mcp / connector / host-extension); gated on capabilities.toolCatalog; authorization-scoped per §F-2.
+- name: hitl
+  description: Human-in-the-loop interrupts and approvals.
+- name: artifacts
+  description: Run-produced artifacts.
+- name: webhooks
+  description: Subscribe to run events via outbound HTTP.
+- name: triggers
+  description: Durable trigger-bridge subscriptions (RFC 0083). RFC 0099 adds the external-event create surface (`POST /v1/trigger-subscriptions`);
+    gated on `capabilities.triggerBridge.ingestion.registrationEndpoint`.
+- name: audit
+  description: Audit-log integrity verification (gated on the `openwop-audit-log-integrity` profile).
+- name: prompts
+  description: Prompt-template library — list, fetch, render, mutate (RFC 0028; gated on `capabilities.prompts.*`).
+- name: content
+  description: Localized authored content — public delivery + tenant-scoped admin CRUD (RFC 0103; gated on `capabilities.content.supported`).
+- name: host
+  description: Host-capability resources — e.g. the RFC 0059 agent workspace file store (gated on `capabilities.workspace.*`).
+- name: packs-test
+  description: 'RFC 0025 (`Draft`). Test-mode mirror of the production `/v1/packs/*` publish/get/delete/sig surface against
+
+    an isolated catalog. Gated on `capabilities.packs.testMode.supported: true` plus the reference impl''s
+
+    `OPENWOP_PACKS_TEST_NAMESPACE_ENABLED=true` env-gate. Lets the conformance suite exercise the documented
+
+    19-code publish error catalog without `packs:publish` scope on the real registry. Hosts that haven''t
+
+    mounted this surface MUST return `404 Not Found` for every path under `/v1/packs-test/`.
+
+
+    Scope note (RFC 0094 §I): the PRODUCTION `/v1/packs/*` surface these paths mirror is specified in
+
+    `spec/v1/registry-operations.md` + `node-packs.md` §"Registry HTTP API" and is served by a registry
+
+    service (a distinct deployable from the host), so it is intentionally NOT defined in this host
+
+    OpenAPI document.
+
+    '
+paths:
+  /.well-known/openwop:
+    get:
+      tags:
+      - discovery
+      summary: Capability declaration handshake.
+      operationId: getCapabilities
+      security: []
+      parameters:
+      - name: If-None-Match
+        in: header
+        required: false
+        schema:
+          type: string
+        description: RFC 0165 §C.2. Standard conditional request against the discovery document's `ETag`; a matching value
+          SHOULD yield `304 Not Modified`.
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: Capabilities object — see `capabilities.md`.
+          headers:
+            Cache-Control:
+              schema:
+                type: string
+              example: public, max-age=300
+            ETag:
+              schema:
+                type: string
+              description: Optional probe handle for mid-session capability change detection. Deprecated toward v2 (RFC 0165
+                §C.2).
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Capabilities'
+        '304':
+          description: RFC 0165 §C.2 — `If-None-Match` matched the current `ETag`; the body is unchanged.
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '503':
+          description: Server unable to compute capabilities (transient).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /openapi.json:
+    get:
+      tags:
+      - discovery
+      summary: Self-describing OpenAPI 3.1 spec.
+      operationId: getOpenApiSpec
+      security: []
+      responses:
+        '200':
+          description: This document.
+          content:
+            application/json:
+              schema:
+                type: object
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '503':
+          description: Server unable to serve spec (transient).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+      parameters:
+      - $ref: '#/components/parameters/OpenWOPVersion'
+  /workflows/{workflowId}:
+    get:
+      tags:
+      - workflows
+      summary: Read a workflow definition.
+      operationId: getWorkflow
+      parameters:
+      - $ref: '#/components/parameters/WorkflowId'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: Workflow definition.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/workflow-definition.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /runs:
+    post:
+      tags:
+      - runs
+      summary: Create a new run.
+      operationId: createRun
+      parameters:
+      - $ref: '#/components/parameters/IdempotencyKey'
+      - in: header
+        name: OpenWOP-Dedup
+        schema:
+          type: string
+          enum:
+          - enforce
+        description: When set, server cross-host claim system rejects duplicate `(tenantId, scopeId)` pairs with `409 Conflict`.
+      - in: header
+        name: OpenWOP-Force-Engine-Version
+        schema:
+          type: integer
+          minimum: 0
+        description: '**Test-keys-only.** When set, the server emits events for this run AS IF it
+
+          were running the specified engine version (must be within the server''s
+
+          advertised `Capabilities.testing.forceEngineVersionRange`). Used by the
+
+          conformance suite to verify version-negotiation fold-best-effort tolerance
+
+          across the spec''s forward-compat matrix. Servers MUST reject on production
+
+          API keys with `403 force_engine_version_forbidden`. Closes F5.
+
+          '
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              unevaluatedProperties: false
+              allOf:
+              - type: object
+                properties:
+                  workflowId:
+                    type: string
+                    minLength: 1
+                  inputs:
+                    type: object
+                    description: Workflow inputs (consumed by triggers/nodes).
+                  residency:
+                    $ref: ../../schemas/v2/residency.schema.json
+                  tenantId:
+                    type: string
+                    description: Tenant scoping. Server typically defaults from API key.
+                  scopeId:
+                    type: string
+                    description: Opaque correlation ID for `X-Dedup` semantics.
+                  callbackUrl:
+                    type: string
+                    format: uri
+                    description: Signed-token HITL callback URL (see `interrupt.md`).
+                  mode:
+                    type: string
+                    enum:
+                    - eval
+                    description: 'RFC 0081 §B. When `eval`, this run is an eval-suite projection
+
+                      (not a workflow run): the host runs the `evalSuiteRef` against
+
+                      `agentId`, emits the content-free `eval.*` family, and terminates
+
+                      with an `EvalSummary` readable via `GET /v1/runs/{runId}/eval-summary`.
+
+                      Capability-gated on `capabilities.agents.evalSuite.supported`; a
+
+                      host that omits it rejects `mode: "eval"` with 501. Omit for a
+
+                      normal workflow run.
+
+                      '
+                  evalSuiteRef:
+                    type: string
+                    minLength: 1
+                    description: RFC 0081 — URI of the `AgentEvalSuite` to run. Required when mode is `eval`.
+                  agentId:
+                    type: string
+                    minLength: 1
+                    description: RFC 0081 — the manifest agent the eval suite targets. Required when mode is `eval`.
+                if:
+                  properties:
+                    mode:
+                      const: eval
+                  required:
+                  - mode
+                then:
+                  required:
+                  - evalSuiteRef
+                  - agentId
+                else:
+                  required:
+                  - workflowId
+              - $ref: ../../schemas/v2/run-options.schema.json
+      responses:
+        '201':
+          description: Run accepted.
+          headers:
+            OpenWOP-Idempotent-Replay:
+              schema:
+                type: boolean
+              description: Set when the response was served from the idempotency cache.
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                - runId
+                - status
+                - eventsUrl
+                properties:
+                  runId:
+                    type: string
+                  status:
+                    type: string
+                    enum:
+                    - pending
+                    - running
+                    - waiting-approval
+                    - waiting-input
+                    - waiting-external
+                  eventsUrl:
+                    type: string
+                    format: uri
+                  statusUrl:
+                    type: string
+                    format: uri
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '409':
+          description: '`X-Dedup` collision OR concurrent `Idempotency-Key` collision.'
+          headers:
+            Retry-After:
+              schema:
+                type: integer
+              description: Seconds until the active claim is stale-eligible.
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RunClaimConflict'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+  /runs/{runId}:
+    get:
+      tags:
+      - runs
+      summary: Read run state (cached projection).
+      operationId: getRun
+      parameters:
+      - $ref: '#/components/parameters/RunId'
+      - in: header
+        name: If-None-Match
+        required: false
+        schema:
+          type: string
+        description: 'RFC 0115. Conditional revalidation. When this carries the
+
+          current `ETag`, the host responds `304 Not Modified` with no
+
+          body (capability-gated on `restTransport.conditionalRunGet`).
+
+          '
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: Projected run state.
+          headers:
+            ETag:
+              schema:
+                type: string
+              description: 'RFC 0115. Strong validator derived from the run''s latest
+
+                persisted event-log sequence number; changes on every
+
+                observable state transition, stable while none occurs.
+
+                '
+            Content-Encoding:
+              required: false
+              schema:
+                type: string
+                enum:
+                - gzip
+                - br
+                - zstd
+              description: 'RFC 0115. Present only when the host negotiated compression
+
+                from `Accept-Encoding`; pairs with `Vary: Accept-Encoding`.
+
+                The decoded body is byte-identical to the identity body.
+
+                '
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RunSnapshot'
+        '304':
+          description: RFC 0115. Not Modified — `If-None-Match` matched the current `ETag`. Empty body.
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /runs/{runId}/events:
+    get:
+      tags:
+      - runs
+      summary: SSE stream of run events.
+      operationId: streamRunEvents
+      parameters:
+      - $ref: '#/components/parameters/RunId'
+      - in: query
+        name: streamMode
+        schema:
+          type: string
+          pattern: ^(values|(updates|messages|debug)(,(updates|messages|debug))*)$
+          default: updates
+        description: RFC 0171 §E.1 — the closed set and its comma-separated combinations; `values` never combines.
+      - in: query
+        name: bufferMs
+        schema:
+          type: integer
+          minimum: 0
+          maximum: 5000
+        description: 'Optional batching hint per S3 closure. When set, the server
+
+          accumulates events for up to N ms (or until a forced-flush
+
+          trigger fires — terminal events, suspensions, connection close)
+
+          and emits a single SSE event with `event: batch` and `data:` as
+
+          a JSON array of `RunEventDoc`. Range 0..5000; `0` = no buffering.
+
+          See `stream-modes.md` §Aggregation hint.
+
+          '
+      - in: header
+        name: Last-Event-ID
+        schema:
+          type: string
+        description: Resume from sequence after this ID.
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: SSE stream. Auto-closes on terminal event. Keep-alive comments every 30s.
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                description: SSE events. Each event has `id:`, `event:`, `data:` per RFC 8895.
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          description: Unsupported `streamMode`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UnsupportedStreamMode'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /runs/{runId}/events/poll:
+    get:
+      tags:
+      - runs
+      summary: Long-poll fallback for non-SSE clients.
+      operationId: pollRunEvents
+      parameters:
+      - $ref: '#/components/parameters/RunId'
+      - in: query
+        name: afterSequence
+        schema:
+          type: integer
+          minimum: 0
+        description: RFC 0171 §E.2 — return events with `sequence > afterSequence`; omission means from the first event (sequence
+          0). `lastSequence` and `since` are gone.
+      - in: query
+        name: timeout
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 60
+          default: 30
+        description: Seconds to wait for new events. Max 60.
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: Events since `lastSequence`.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: false
+                required:
+                - runId
+                - events
+                - lastSequence
+                - status
+                - isTerminal
+                properties:
+                  runId:
+                    $ref: ../../schemas/v2/ids.schema.json#/$defs/runId
+                  events:
+                    type: array
+                    items:
+                      $ref: ../../schemas/v2/run-event.schema.json
+                  lastSequence:
+                    type: integer
+                    minimum: -1
+                    description: The highest sequence in the log at the time of the response (one meaning); -1 when the log
+                      is empty.
+                  status:
+                    type: string
+                  isTerminal:
+                    type: boolean
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /runs/{runId}/cancel:
+    post:
+      tags:
+      - runs
+      summary: Cancel an in-flight run.
+      operationId: cancelRun
+      parameters:
+      - $ref: '#/components/parameters/RunId'
+      - $ref: '#/components/parameters/IdempotencyKey'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reason:
+                  type: string
+      responses:
+        '200':
+          description: Run cancellation accepted (cascade may be async).
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  runId:
+                    type: string
+                  status:
+                    type: string
+                    enum:
+                    - cancelled
+                    - cancelling
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /runs/{runId}/annotations:
+    post:
+      tags:
+      - runs
+      summary: Record a non-blocking quality annotation on a run (RFC 0056).
+      operationId: createAnnotation
+      parameters:
+      - $ref: '#/components/parameters/RunId'
+      - $ref: '#/components/parameters/IdempotencyKey'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: ../../schemas/v2/annotation-create.schema.json
+      responses:
+        '201':
+          description: Annotation recorded. Returns the persisted annotation.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/annotation.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '501':
+          description: Host does not advertise capabilities.feedback.supported (RFC 0056).
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+    get:
+      tags:
+      - runs
+      summary: List the annotations recorded on a run (RFC 0056).
+      operationId: listAnnotations
+      parameters:
+      - $ref: '#/components/parameters/RunId'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: Annotations for the run (tenant-scoped).
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                - annotations
+                properties:
+                  annotations:
+                    type: array
+                    items:
+                      $ref: ../../schemas/v2/annotation.schema.json
+                additionalProperties: false
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '501':
+          description: Host does not advertise capabilities.feedback.supported (RFC 0056).
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /trigger-subscriptions:
+    post:
+      tags:
+      - triggers
+      summary: Register an external-event trigger subscription (RFC 0099).
+      description: 'Creates an external-event (`webhook`/`email`/`form`) TriggerSubscription
+
+        bound to a workflow, with a dedup config and a source-authenticity
+
+        verification policy (RFC 0099 §F.2). The `workflowId` MUST resolve under
+
+        the caller''s RFC 0048 owner triple. The response carries the created
+
+        TriggerSubscription plus a source-specific `binding`; the binding
+
+        secret/URL is returned ONCE and is not re-fetchable in cleartext.
+
+        '
+      operationId: createTriggerSubscription
+      parameters:
+      - $ref: '#/components/parameters/IdempotencyKey'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: ../../schemas/v2/trigger-subscription-registration.schema.json
+      responses:
+        '201':
+          description: Subscription created. Returns the TriggerSubscription + a source-specific binding.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                - subscription
+                - binding
+                additionalProperties: false
+                properties:
+                  subscription:
+                    $ref: ../../schemas/v2/trigger-subscription.schema.json
+                  binding:
+                    type: object
+                    description: 'Source-specific binding the caller needs to wire the external
+
+                      source. For `webhook`: `{ ingestUrl, secretFingerprint }`; for
+
+                      `email`: `{ ingestAddress }`; for `form`: `{ ingestUrl }`. The
+
+                      secret is returned once at creation (SR-1).
+
+                      '
+                    additionalProperties: true
+                    properties:
+                      ingestUrl:
+                        type: string
+                        format: uri
+                      ingestAddress:
+                        type: string
+                      secretFingerprint:
+                        type: string
+                        maxLength: 32
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '501':
+          description: Host does not advertise capabilities.triggerBridge.ingestion.registrationEndpoint (RFC 0099).
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /content/pages/{slug}:
+    get:
+      tags:
+      - content
+      security: []
+      summary: Deliver a published content page resolved for the negotiated locale (RFC 0103 §D).
+      description: 'Resolves the published page `slug` for the locale negotiated from
+
+        `Accept-Language` (i18n.md fallback: q-value order → language family →
+
+        `content.baseLocale`), applies the per-section field merge
+
+        (`localized-content.md` §C), and returns the already-merged sections in
+
+        render order. Sets `Content-Language` to the locale used,
+
+        `Vary: Accept-Language, Accept-Encoding`, and
+
+        `Cache-Control: public, max-age=300, stale-while-revalidate=3600`.
+
+        Serves `status: "published"` content only. Tenant is host-resolved
+
+        (`localized-content.md` §F): credential-derived when authenticated,
+
+        host-defined (e.g. domain) when anonymous. A `slug` absent for the
+
+        resolved tenant returns the same `404` as a nonexistent slug (no
+
+        cross-tenant enumeration).
+
+        '
+      operationId: getContentPage
+      parameters:
+      - name: slug
+        in: path
+        required: true
+        schema:
+          type: string
+          pattern: ^[a-z][a-z0-9-]*$
+        description: The page slug.
+      - name: Accept-Language
+        in: header
+        required: false
+        schema:
+          type: string
+        description: BCP-47 preference list; authoritative for locale selection (i18n.md). A malformed value MUST NOT 400.
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: The resolved, published page for the negotiated locale.
+          headers:
+            Content-Language:
+              schema:
+                type: string
+              description: The BCP-47 locale actually used (equals the response `locale`).
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/localized-content-page-response.schema.json
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '501':
+          description: Host does not advertise capabilities.content.supported (RFC 0103).
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /content/pages:
+    get:
+      tags:
+      - content
+      summary: List content pages for the caller's tenant (RFC 0103 §D, admin).
+      description: 'Tenant-scoped admin listing of pages (draft + published). Requires a
+
+        principal with `content.read` scope.
+
+        '
+      operationId: listContentPages
+      responses:
+        '200':
+          description: The caller-tenant's pages.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: ../../schemas/v2/localized-content-page.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '501':
+          description: Host does not advertise capabilities.content.supported (RFC 0103).
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+      parameters:
+      - $ref: '#/components/parameters/OpenWOPVersion'
+    post:
+      tags:
+      - content
+      summary: Create a content page (RFC 0103 §D, admin).
+      description: Tenant-scoped page creation. Requires `content.write` scope.
+      operationId: createContentPage
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: ../../schemas/v2/localized-content-page.schema.json
+      responses:
+        '201':
+          description: The created page.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/localized-content-page.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          description: Invalid request (e.g. baseLocale in supportedLocales, or a malformed locale/slug).
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+      parameters:
+      - $ref: '#/components/parameters/OpenWOPVersion'
+  /content/pages/{pageId}/sections/{sectionId}:
+    put:
+      tags:
+      - content
+      summary: Upsert a section's base or per-locale fields (RFC 0103 §D, admin).
+      description: 'Locale-targeted write: `locale == content.baseLocale` upserts the
+
+        section''s base `data`; any other (BCP-47-subset) locale upserts
+
+        `localizations[locale]`. Tenant-scoped; requires `content.write`.
+
+        '
+      operationId: putContentSection
+      parameters:
+      - name: pageId
+        in: path
+        required: true
+        schema:
+          type: string
+          minLength: 1
+      - name: sectionId
+        in: path
+        required: true
+        schema:
+          type: string
+          minLength: 1
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required:
+              - locale
+              - data
+              properties:
+                locale:
+                  type: string
+                  pattern: ^[a-z]{2}(-[A-Z]{2})?$
+                  description: Target locale; baseLocale upserts `data`, else `localizations[locale]`.
+                data:
+                  type: object
+                  additionalProperties: true
+                  description: The field overlay for the target locale.
+      responses:
+        '200':
+          description: The updated section record.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/localized-content-section.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          description: Invalid request (e.g. baseLocale in supportedLocales, or a malformed locale/slug).
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /content/settings:
+    get:
+      tags:
+      - content
+      summary: Read the tenant's content language settings (RFC 0103 §B, admin).
+      description: Tenant-scoped read of `{ baseLocale, supportedLocales, autoTranslateOnPublish }`. Requires `content.read`.
+      operationId: getContentSettings
+      responses:
+        '200':
+          description: The tenant's language settings.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/localized-content-language-settings.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '501':
+          description: Host does not advertise capabilities.content.supported (RFC 0103).
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+      parameters:
+      - $ref: '#/components/parameters/OpenWOPVersion'
+    put:
+      tags:
+      - content
+      summary: Update the tenant's content language settings (RFC 0103 §B, admin).
+      description: 'Tenant-scoped settings update. The invariant `baseLocale ∉
+
+        supportedLocales` MUST hold (else `400`). Requires `content.write`.
+
+        '
+      operationId: putContentSettings
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: ../../schemas/v2/localized-content-language-settings.schema.json
+      responses:
+        '200':
+          description: The updated language settings.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/localized-content-language-settings.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          description: Invalid request (e.g. baseLocale in supportedLocales, or a malformed locale/slug).
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+      parameters:
+      - $ref: '#/components/parameters/OpenWOPVersion'
+  /runs:bulk-cancel:
+    post:
+      tags:
+      - runs
+      summary: Cancel a set of in-flight runs in a single request.
+      description: 'Per `spec/v1/rest-endpoints.md` §"POST /v1/runs:bulk-cancel". Accepts
+
+        a non-empty array of runIds and processes each cancellation
+
+        independently. Returns `200` with a per-id results array even when
+
+        some individual cancellations fail; the top-level operation succeeds
+
+        when the request reached the host, regardless of per-id outcomes.
+
+        Hosts enforce a host-defined cap on the array length (RECOMMENDED
+
+        100); over-cap requests return `400 validation_error`.
+
+        '
+      operationId: bulkCancelRuns
+      parameters:
+      - $ref: '#/components/parameters/IdempotencyKey'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - runIds
+              properties:
+                runIds:
+                  type: array
+                  minItems: 1
+                  maxItems: 100
+                  items:
+                    type: string
+                    minLength: 1
+                    maxLength: 128
+                reason:
+                  type: string
+                  maxLength: 512
+              additionalProperties: false
+      responses:
+        '200':
+          description: Per-id cancel results.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                - results
+                properties:
+                  results:
+                    type: array
+                    items:
+                      type: object
+                      required:
+                      - runId
+                      - ok
+                      properties:
+                        runId:
+                          type: string
+                          minLength: 1
+                        ok:
+                          type: boolean
+                        status:
+                          type: string
+                          enum:
+                          - cancelled
+                          - cancelling
+                        error:
+                          $ref: ../../schemas/v2/error-envelope.schema.json
+                      additionalProperties: false
+                additionalProperties: false
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+  /runs/{runId}:fork:
+    post:
+      tags:
+      - runs
+      summary: Fork the run for replay or branch (see `replay.md`).
+      operationId: forkRun
+      parameters:
+      - $ref: '#/components/parameters/RunId'
+      - $ref: '#/components/parameters/IdempotencyKey'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - mode
+              properties:
+                fromSeq:
+                  type: integer
+                  minimum: 0
+                  description: 'Inclusive — events `< fromSeq` are fixed history; `>= fromSeq` are re-executed.
+
+                    Required for `branch` (the branch point). Optional for `replay`; when omitted,
+
+                    defaults to `0` (full re-execution from source-run start) per `replay.md`
+
+                    §"Replay-mode defaults".
+
+                    '
+                mode:
+                  type: string
+                  enum:
+                  - replay
+                  - branch
+                runOptionsOverlay:
+                  type: object
+                  description: For `branch` mode only — caller-supplied `RunOptions` to overlay.
+              additionalProperties: false
+      responses:
+        '201':
+          description: Fork accepted, new run started.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                - runId
+                - sourceRunId
+                - mode
+                - status
+                - eventsUrl
+                properties:
+                  runId:
+                    type: string
+                  sourceRunId:
+                    type: string
+                  fromSeq:
+                    type: integer
+                  mode:
+                    type: string
+                    enum:
+                    - replay
+                    - branch
+                  status:
+                    type: string
+                  eventsUrl:
+                    type: string
+                    format: uri
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          description: Invalid `fromSeq`, `replay` with non-empty `runOptionsOverlay`, etc.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '422':
+          description: '`fromSeq` references a sequence number that doesn''t exist in the source run''s event log.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /runs/{runId}/ancestry:
+    get:
+      tags:
+      - runs
+      summary: 'RFC 0040 §C — return the run''s immediate parent in the cross-host
+
+        composition chain. Capability-gated on
+
+        `capabilities.multiAgent.executionModel.crossHostCausation.ancestryEndpointSupported: true`;
+
+        hosts that don''t advertise return 404 not_found. Clients walk the full
+
+        chain by following `parent.wellKnownUrl` per response, one hop at a
+
+        time.
+
+        '
+      operationId: getRunAncestry
+      parameters:
+      - $ref: '#/components/parameters/RunId'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: 'Run''s immediate parent (or `parent: null` for top-level runs).
+
+            '
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/run-ancestry-response.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: 'Either the run doesn''t exist, OR the host doesn''t advertise
+
+            `crossHostCausation.ancestryEndpointSupported: true` and treats
+
+            the endpoint as absent. Clients can disambiguate by inspecting
+
+            the host''s discovery doc.
+
+            '
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /agents:
+    get:
+      tags:
+      - agents
+      summary: 'RFC 0072 §A — list the manifest agents this host has installed into its
+
+        AgentRegistry (RFC 0070). Capability-gated on
+
+        `capabilities.agents.manifestRuntime.supported: true`; hosts that don''t
+
+        advertise it return 404. Read-only projection — never carries the
+
+        system-prompt body, resolved handoff schemas, or credential material (SR-1).
+
+        Dispatch is not a bespoke endpoint: a manifest agent is invoked as a run
+
+        whose node pins it via `WorkflowNode.agent` + `POST /v1/runs` (RFC 0072 §B).
+
+        RFC 0074 — the result is scoped to the authenticated principal''s owner
+
+        triple (RFC 0048). When `capabilities.agents.manifestRuntime.installScope`
+
+        is `''tenant''`, only the agents available to the caller''s tenant·workspace
+
+        are returned (an agent another workspace installed is absent, never
+
+        disclosed); when `''host''` (default) the inventory is host-global as in
+
+        RFC 0072. A `''tenant''`-scoped host MUST reject unauthenticated/unscoped
+
+        requests per its standard auth contract rather than fall back to a global list.
+
+        '
+      operationId: listAgents
+      responses:
+        '200':
+          description: Installed manifest agents (agentId-sorted).
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/agent-inventory-response.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: 'Host does not advertise `capabilities.agents.manifestRuntime` and
+
+            treats the endpoint as absent.
+
+            '
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+      parameters:
+      - $ref: '#/components/parameters/OpenWOPVersion'
+  /agents/{agentId}:
+    get:
+      tags:
+      - agents
+      summary: 'RFC 0072 §A — return one installed manifest agent''s inventory entry, or
+
+        404 when no such agent is installed (or the host doesn''t advertise
+
+        `capabilities.agents.manifestRuntime`). RFC 0074 — resolved within the
+
+        authenticated principal''s owner triple (RFC 0048): on an
+
+        `installScope: ''tenant''` host an agent the caller''s workspace has not
+
+        approved 404s identically to "not installed", so the surface never
+
+        discloses another tenant''s inventory.
+
+        '
+      operationId: getAgent
+      parameters:
+      - in: path
+        name: agentId
+        required: true
+        schema:
+          type: string
+          pattern: ^(?!roster$|org-chart$).+$
+        description: 'The manifest agentId. MUST NOT be the reserved literals `roster` or
+
+          `org-chart` — those name the sibling collection routes
+
+          (`/v1/agents/roster`, `/v1/agents/org-chart`), so excluding them here
+
+          keeps `/v1/agents/{agentId}` unambiguous against them.
+
+          '
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: The agent's inventory entry.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/agent-inventory-response.schema.json#/$defs/AgentInventoryEntry
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: No such agent, or the host doesn't advertise the capability.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /agents/{agentId}/deployments:
+    get:
+      tags:
+      - agents
+      summary: 'RFC 0082 §C/§E — list the deployment records (per-(agentId, version)) for
+
+        a manifest agent: the lifecycle `state`, the named `channels`, the canary
+
+        share, the rollback pointer, and the last-transition provenance. Read-only,
+
+        content-free of any manifest body or credential (SR-1). Capability-gated on
+
+        `capabilities.agents.deployment.supported: true`; hosts that don''t advertise
+
+        it return 404. Tenant-scoped to the caller''s owner triple (RFC 0048/0074)
+
+        when `installScope: ''tenant''`.
+
+        '
+      operationId: listAgentDeployments
+      parameters:
+      - in: path
+        name: agentId
+        required: true
+        schema:
+          type: string
+          pattern: ^(?!roster$|org-chart$).+$
+        description: 'The manifest agentId. MUST NOT be the reserved literals `roster` or
+
+          `org-chart` — those name the sibling collection routes
+
+          (`/v1/agents/roster/{rosterId}`, `/v1/agents/org-chart/{departmentId}`),
+
+          so excluding them here keeps `/v1/agents/{agentId}/deployments`
+
+          unambiguous against them.
+
+          '
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: The agent's deployment records (version-sorted).
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: ../../schemas/v2/agent-deployment.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: No such agent, or the host doesn't advertise `capabilities.agents.deployment`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+    post:
+      tags:
+      - agents
+      summary: 'RFC 0082 §E — request a deployment state transition (promote / pause /
+
+        deprecate / rollback / adjust-canary). The host MUST authorize fail-closed
+
+        against the RFC 0049 `deploy:*` scope (absent/unseeded role denies), run any
+
+        configured RFC 0051 approvalGate, and — when the gate carries `requiredEval`
+
+        — verify the referenced RFC 0081 eval run is terminal and `EvalSummary.passed`
+
+        BEFORE emitting `deployment.promoted`. On success returns the updated
+
+        deployment record and emits the matching content-free `deployment.*` event.
+
+        '
+      operationId: transitionAgentDeployment
+      parameters:
+      - in: path
+        name: agentId
+        required: true
+        schema:
+          type: string
+        description: The manifest agentId.
+      - $ref: '#/components/parameters/IdempotencyKey'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: ../../schemas/v2/agent-deployment-transition.schema.json
+      responses:
+        '200':
+          description: The deployment record after the applied transition.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/agent-deployment.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          description: 'Validation error, or a transition that the host''s advertised
+
+            `states`/`canary` cannot satisfy, or `no_active_deployment` when a
+
+            referenced channel resolves to no active version.
+
+            '
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          description: 'Fail-closed authorization denial (the principal lacks the required
+
+            `deploy:*` scope — RFC 0049), or `eval_gate_unmet` when a `requiredEval`
+
+            gate''s referenced eval run is not terminal-and-passed (RFC 0081).
+
+            '
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '404':
+          description: No such agent, or the host doesn't advertise `capabilities.agents.deployment`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /agents/roster:
+    get:
+      tags:
+      - agents
+      summary: 'RFC 0086 §B — list the standing agent roster (named "digital-twin
+
+        employee" instances + their workflow portfolios) visible to the
+
+        caller. Capability-gated on `capabilities.agents.roster.supported:
+
+        true`; hosts that don''t advertise it return 404. Tenant-scoped per
+
+        RFC 0074 — on an `installScope: ''tenant''` host only the caller''s
+
+        owner-triple entries are returned. Read-only; content-free (SR-1).
+
+        '
+      operationId: listAgentRoster
+      responses:
+        '200':
+          description: The caller's standing roster (rosterId-sorted).
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/agent-roster-response.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Host does not advertise `capabilities.agents.roster`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+      parameters:
+      - $ref: '#/components/parameters/OpenWOPVersion'
+  /agents/roster/{rosterId}:
+    get:
+      tags:
+      - agents
+      summary: 'RFC 0086 §B — return one standing roster entry, or 404 when no such
+
+        entry exists, the host doesn''t advertise `capabilities.agents.roster`,
+
+        or (on an `installScope: ''tenant''` host) the entry is outside the
+
+        caller''s owner triple — a cross-tenant entry 404s identically to
+
+        "not found", never disclosing another tenant''s roster.
+
+        '
+      operationId: getAgentRosterEntry
+      parameters:
+      - in: path
+        name: rosterId
+        required: true
+        schema:
+          type: string
+        description: The standing instance id (a `host:<id>` AgentRef agentId).
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: The roster entry.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/agent-roster-entry.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: No such entry, cross-tenant, or capability unadvertised.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /agents/org-chart:
+    get:
+      tags:
+      - agents
+      summary: 'RFC 0087 §C — return the caller''s agent org-chart (departments + roles
+
+        + `reportsTo` edges over roster members). Capability-gated on
+
+        `capabilities.agents.orgChart.supported: true`; hosts that don''t
+
+        advertise it return 404. Tenant-scoped per RFC 0074. DESCRIPTIVE only:
+
+        an org edge confers no authority (§B `org-position-no-authority-escalation`).
+
+        '
+      operationId: getAgentOrgChart
+      responses:
+        '200':
+          description: The caller's org-chart.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/agent-org-chart.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Host does not advertise `capabilities.agents.orgChart`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+      parameters:
+      - $ref: '#/components/parameters/OpenWOPVersion'
+  /agents/org-chart/{departmentId}:
+    get:
+      tags:
+      - agents
+      summary: 'RFC 0087 §D — one department''s subtree + responsibility roll-up (the
+
+        union of its members'' RFC 0086 portfolios). `?recursive=false` narrows
+
+        the roll-up to direct members without changing the response shape.
+
+        404 when the department is unknown, cross-tenant, or the host doesn''t
+
+        advertise `capabilities.agents.orgChart`. The roll-up grants nothing (§B).
+
+        '
+      operationId: getAgentOrgChartDepartment
+      parameters:
+      - in: path
+        name: departmentId
+        required: true
+        schema:
+          type: string
+        description: The department id to root the subtree + roll-up at.
+      - in: query
+        name: recursive
+        required: false
+        schema:
+          type: boolean
+          default: true
+        description: When `false`, the roll-up scopes to direct members only.
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: The department subtree + responsibility roll-up.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/org-chart-responsibility-view.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Unknown/cross-tenant department, or capability unadvertised.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /tools:
+    get:
+      tags:
+      - tools
+      summary: 'RFC 0078 §B — list the portable `ToolDescriptor`s visible to the caller
+
+        across every tool source (node-pack / workflow / mcp / connector /
+
+        host-extension). Capability-gated on
+
+        `capabilities.toolCatalog.supported: true`; hosts that don''t advertise
+
+        it return 404. §F-2 — the projection is authorization-scoped: a
+
+        principal sees only the tools it may invoke, and a second principal MUST
+
+        NOT see another principal''s tools (non-disclosure). Read-only; each
+
+        descriptor is content-free of any credential material (SR-1).
+
+        '
+      operationId: listTools
+      parameters:
+      - name: view
+        in: query
+        required: false
+        schema:
+          type: string
+          enum:
+          - standard
+          - compact
+          default: standard
+        description: 'RFC 0112. `compact` returns the `{ tools: CompactToolDescriptor[] }` projection — heavy descriptor fields
+          omitted and `inputSchema` bounded to the compact structural subset — when the host advertises `capabilities.toolCatalog.compactView:
+          true`. Defaults to `standard`; a host that does not advertise `compactView` treats `view=compact` as any unknown
+          query param and returns the standard view.
+
+          '
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: 'The caller''s authorized tool catalog (standard array, or the compact `{ tools: [] }` projection when
+            `view=compact`).'
+          content:
+            application/json:
+              schema:
+                oneOf:
+                - type: array
+                  items:
+                    $ref: ../../schemas/v2/tool-descriptor.schema.json
+                - type: object
+                  required:
+                  - tools
+                  properties:
+                    tools:
+                      type: array
+                      items:
+                        $ref: ../../schemas/v2/compact-tool-descriptor.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Host does not advertise `capabilities.toolCatalog`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /tools/{toolId}:
+    get:
+      tags:
+      - tools
+      summary: 'RFC 0078 §B — return one `ToolDescriptor` by its stable `toolId`, or 404
+
+        when no such tool exists, the caller isn''t authorized for it (§F-2
+
+        non-disclosure — a cross-principal tool 404s identically to "not
+
+        found"), or the host doesn''t advertise `capabilities.toolCatalog`.
+
+        '
+      operationId: getTool
+      parameters:
+      - in: path
+        name: toolId
+        required: true
+        schema:
+          type: string
+        description: The stable tool id (`ToolDescriptor.toolId`).
+      - name: view
+        in: query
+        required: false
+        schema:
+          type: string
+          enum:
+          - standard
+          - compact
+          default: standard
+        description: 'RFC 0112. `compact` returns one `CompactToolDescriptor` (heavy fields omitted; `inputSchema` bounded
+          to the compact structural subset) when the host advertises `capabilities.toolCatalog.compactView: true`. Defaults
+          to `standard`; a host that does not advertise `compactView` treats `view=compact` as any unknown query param.
+
+          '
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: The tool descriptor (standard, or one `CompactToolDescriptor` when `view=compact`).
+          content:
+            application/json:
+              schema:
+                oneOf:
+                - $ref: ../../schemas/v2/tool-descriptor.schema.json
+                - $ref: ../../schemas/v2/compact-tool-descriptor.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: No such tool, unauthorized, or capability unadvertised.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /runs/{runId}/eval-summary:
+    get:
+      tags:
+      - runs
+      summary: 'RFC 0081 §C — return the `EvalSummary` scorecard for a terminal eval run
+
+        (a run started with `mode: "eval"`): aggregate + per-task scores, cost,
+
+        latency, schema-validity, and redaction-safe safety findings, plus the
+
+        suite provenance and (regression mode) the score delta vs a baseline.
+
+        Content-free of task output / rubric prose / credentials (SR-1; the
+
+        `eval-summary-no-content-leak` invariant). Capability-gated on
+
+        `capabilities.agents.evalSuite.supported: true`; hosts that don''t advertise
+
+        it return 404. 409 when the run is not yet terminal.
+
+        '
+      operationId: getEvalSummary
+      parameters:
+      - $ref: '#/components/parameters/RunId'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: The eval run's scorecard.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/eval-summary.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: 'No such run, the run is not an eval run, or the host doesn''t advertise
+
+            `capabilities.agents.evalSuite`.
+
+            '
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '409':
+          description: The eval run is still running; the summary is not yet final.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /runs/{runId}:diff:
+    get:
+      tags:
+      - runs
+      summary: 'RFC 0054 — return a deterministic, replay-aware structured diff of
+
+        two runs (typically a run and its RFC 0011 fork): `divergedAtSeq` +
+
+        ordered `eventDiffs[]` + `stateDiff`. The diff is a pure function of
+
+        the two event logs (see `replay.md` determinism contract). Requires
+
+        `runs:read` on BOTH runs. Hosts that don''t implement it return 404.
+
+        '
+      operationId: diffRun
+      parameters:
+      - $ref: '#/components/parameters/RunId'
+      - name: against
+        in: query
+        required: true
+        description: The other run id to diff `{runId}` against (the `b` run).
+        schema:
+          type: string
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: 'Structured diff of the two runs. `divergedAtSeq: null` + empty
+
+            `eventDiffs` when the logs are identical.
+
+            '
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/run-diff-response.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          description: Missing or malformed `against` query parameter.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          description: 'Caller lacks `runs:read` on `{runId}` and/or on `against`
+
+            (`forbidden`); composes with RFC 0048 cross-workspace
+
+            isolation.
+
+            '
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '404':
+          description: 'Either run doesn''t exist, OR the host doesn''t implement the diff
+
+            endpoint and treats the path as absent.
+
+            '
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /runs/{runId}:pause:
+    post:
+      tags:
+      - runs
+      summary: Administratively pause an in-flight run (RFC Track 13).
+      description: 'Operator-driven pause distinct from cancel (terminal) and HITL suspend (workflow-driven).
+
+        Emits a `run.paused` event when the pause takes effect; exit only via `:resume` or `:cancel`.
+
+        '
+      operationId: pauseRun
+      parameters:
+      - $ref: '#/components/parameters/RunId'
+      - $ref: '#/components/parameters/IdempotencyKey'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reason:
+                  type: string
+                  description: Free-form rationale, persisted on the `run.paused` event payload.
+                drainPolicy:
+                  type: string
+                  enum:
+                  - immediate
+                  - drain-current-node
+                  default: drain-current-node
+                  description: '`immediate` snapshots between events; `drain-current-node` lets the running node
+
+                    reach a terminal before transitioning to `paused`.
+
+                    '
+              additionalProperties: false
+      responses:
+        '202':
+          description: Pause requested; transition emits `run.paused` when complete.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                - runId
+                - status
+                properties:
+                  runId:
+                    type: string
+                  status:
+                    type: string
+                    enum:
+                    - paused
+                  pausedAt:
+                    type: string
+                    format: date-time
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: Run is already paused, terminal, or in a state that cannot be paused.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /runs/{runId}:resume:
+    post:
+      tags:
+      - runs
+      summary: Resume a paused run (RFC Track 13).
+      description: 'Reverses a prior `:pause`. Run transitions from `paused` to `running` and emits `run.resumed`.
+
+        '
+      operationId: resumeRun
+      parameters:
+      - $ref: '#/components/parameters/RunId'
+      - $ref: '#/components/parameters/IdempotencyKey'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reason:
+                  type: string
+              additionalProperties: false
+      responses:
+        '202':
+          description: Resume requested.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                - runId
+                - status
+                properties:
+                  runId:
+                    type: string
+                  status:
+                    type: string
+                    enum:
+                    - running
+                  resumedAt:
+                    type: string
+                    format: date-time
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: Run is not currently paused.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /runs/{runId}/interrupts/{nodeId}:
+    post:
+      tags:
+      - hitl
+      summary: Resolve an interrupt via the run-scoped surface.
+      operationId: resolveInterruptByRun
+      parameters:
+      - $ref: '#/components/parameters/RunId'
+      - in: path
+        name: nodeId
+        required: true
+        schema:
+          type: string
+          minLength: 1
+      - $ref: '#/components/parameters/IdempotencyKey'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - resumeValue
+              properties:
+                resumeValue:
+                  description: Validated against the interrupt's `resumeSchema` if declared.
+              additionalProperties: false
+      responses:
+        '200':
+          description: Interrupt resolved; executor unblocks.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  runId:
+                    type: string
+                  nodeId:
+                    type: string
+                  status:
+                    type: string
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Interrupt not found or already resolved.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '409':
+          description: Concurrent resolve — only one wins.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '422':
+          description: Run was cancelled while interrupt was pending.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /interrupts/{token}:
+    parameters:
+    - in: path
+      name: token
+      required: true
+      schema:
+        type: string
+      description: HMAC-signed token issued by the server at suspension time. Format `base64url(payload).hmac_sha256(secret,
+        payload)`.
+    get:
+      tags:
+      - hitl
+      summary: Inspect an interrupt without resolving (signed-token surface).
+      operationId: inspectInterruptByToken
+      security: []
+      responses:
+        '200':
+          description: Interrupt details.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/suspend-request.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '410':
+          description: Token expired.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+      parameters:
+      - $ref: '#/components/parameters/OpenWOPVersion'
+    post:
+      tags:
+      - hitl
+      summary: Resolve an interrupt via signed token (asynchronous callback).
+      operationId: resolveInterruptByToken
+      security: []
+      parameters:
+      - $ref: '#/components/parameters/IdempotencyKey'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - resumeValue
+              properties:
+                resumeValue: {}
+              additionalProperties: false
+      responses:
+        '200':
+          description: Resolution accepted.
+          content:
+            application/json:
+              schema:
+                type: object
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '410':
+          description: Token expired.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /runs/{runId}/artifacts/{artifactId}:
+    get:
+      tags:
+      - artifacts
+      summary: Read a run-produced artifact.
+      operationId: getArtifact
+      parameters:
+      - $ref: '#/components/parameters/RunId'
+      - in: path
+        name: artifactId
+        required: true
+        schema:
+          type: string
+          minLength: 1
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: Artifact payload.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: Implementation-defined artifact shape.
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /webhooks:
+    post:
+      tags:
+      - webhooks
+      summary: Register a webhook subscription.
+      operationId: registerWebhook
+      parameters:
+      - $ref: '#/components/parameters/IdempotencyKey'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - url
+              - events
+              properties:
+                url:
+                  type: string
+                  format: uri
+                events:
+                  type: array
+                  items:
+                    type: string
+                  description: Event types to subscribe to (see `run-event.schema.json` enum).
+                secret:
+                  type: string
+                  description: Server signs payloads with this secret using HMAC-SHA256.
+                tags:
+                  type: array
+                  items:
+                    type: string
+                  description: Filter to runs carrying these tags (see `run-options.md`).
+              additionalProperties: false
+      responses:
+        '201':
+          description: Webhook registered.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                - webhookId
+                properties:
+                  webhookId:
+                    type: string
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+  /webhooks/{webhookId}:
+    delete:
+      tags:
+      - webhooks
+      summary: Unregister a webhook.
+      operationId: unregisterWebhook
+      parameters:
+      - in: path
+        name: webhookId
+        required: true
+        schema:
+          type: string
+          minLength: 1
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '204':
+          description: Unregistered.
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /audit/verify:
+    get:
+      tags:
+      - audit
+      summary: Verify the audit-log hash chain over [fromSeq, toSeq].
+      description: 'Per `spec/v1/auth-profiles.md` §`openwop-audit-log-integrity` §4. The
+
+        verifier re-walks audit-log entries in the requested range,
+
+        re-computes each entry''s `prevHash` from the canonical RFC 8785 JCS
+
+        serialization of the prior entry, verifies signed checkpoints
+
+        against the host''s advertised `auditLogIntegrity.checkpointPublicKey`,
+
+        and returns `chainValid` + an enumeration of any anomalies.
+
+        Hosts MUST require the `audit:read` scope. Hosts that do NOT
+
+        advertise the `openwop-audit-log-integrity` profile MAY omit this
+
+        endpoint entirely (clients SHOULD pre-flight via `/.well-known/openwop`).
+
+        '
+      operationId: verifyAuditLog
+      parameters:
+      - in: query
+        name: fromSeq
+        required: true
+        schema:
+          type: integer
+          minimum: 0
+        description: First audit-log sequence to include (inclusive).
+      - in: query
+        name: toSeq
+        required: true
+        schema:
+          type: integer
+          minimum: 0
+        description: Last audit-log sequence to include (inclusive). MUST be >= fromSeq.
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: Verification result.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/audit-verify-result.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Host does not advertise the audit-log-integrity profile.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /prompts:
+    get:
+      tags:
+      - prompts
+      summary: List prompt templates available to the caller.
+      operationId: listPromptTemplates
+      parameters:
+      - in: query
+        name: kind
+        schema:
+          type: string
+          enum:
+          - system
+          - user
+          - few-shot
+          - schema-hint
+        description: Filter by `PromptTemplate.kind`.
+      - in: query
+        name: tag
+        schema:
+          type: string
+        description: 'Filter to templates whose `tags[]` contains this exact tag.
+
+          Hosts MAY accept the parameter multiple times; the semantic
+
+          when repeated is AND (every named tag must be present).
+
+          '
+      - in: query
+        name: modelClass
+        schema:
+          type: string
+        description: Filter to templates whose `modelHints.modelClass` matches.
+      - in: query
+        name: source
+        schema:
+          type: string
+          enum:
+          - host
+          - pack
+          - user
+        description: Filter by `meta.source` provenance.
+      - in: query
+        name: cursor
+        schema:
+          type: string
+        description: Opaque pagination cursor.
+      - in: query
+        name: limit
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 200
+          default: 50
+        description: Maximum entries per page.
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      responses:
+        '200':
+          description: Paginated list of templates.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                - items
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: ../../schemas/v2/prompt-template.schema.json
+                  nextCursor:
+                    type: string
+                    description: Opaque cursor; absent on the final page.
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '501':
+          description: Host does not advertise capabilities.prompts.endpointsSupported. (RFC 0028 §A — supported gates Phase
+            A node-execution composition; endpointsSupported gates this REST surface independently.)
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+    post:
+      tags:
+      - prompts
+      summary: Create a new prompt template (mutable libraries only).
+      operationId: createPromptTemplate
+      parameters:
+      - $ref: '#/components/parameters/IdempotencyKey'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: ../../schemas/v2/prompt-template.schema.json
+      responses:
+        '201':
+          description: Template created. `Location` header carries the canonical URI.
+          headers:
+            Location:
+              schema:
+                type: string
+              description: Canonical URI of the new template.
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '409':
+          description: A template with this `(templateId, version)` pair already exists.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '501':
+          description: Host does not advertise capabilities.prompts.mutableLibrary.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+  /prompts/{templateId}:
+    parameters:
+    - in: path
+      name: templateId
+      required: true
+      schema:
+        type: string
+        pattern: ^[a-z0-9][a-z0-9._-]{0,127}$
+      description: PromptTemplate.templateId per RFC 0027.
+    - in: query
+      name: version
+      schema:
+        type: string
+        pattern: ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$
+      description: Pin to a specific SemVer version; latest when omitted.
+    - in: query
+      name: libraryId
+      schema:
+        type: string
+        pattern: ^[a-z0-9][a-z0-9._-]{0,127}$
+      description: 'Disambiguate when multiple installed packs ship the same
+
+        templateId. Hosts MUST return `prompt_ref_ambiguous` if
+
+        ambiguous and libraryId is omitted.
+
+        '
+    get:
+      tags:
+      - prompts
+      summary: Fetch a single prompt template.
+      operationId: getPromptTemplate
+      responses:
+        '200':
+          description: The PromptTemplate.
+          headers:
+            ETag:
+              schema:
+                type: string
+              description: SHA-256 of the canonical body.
+            Cache-Control:
+              schema:
+                type: string
+              description: Honors immutable semantics when version was pinned.
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/prompt-template.schema.json
+        '304':
+          description: Conditional revalidation succeeded.
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          description: '`prompt_ref_ambiguous` when libraryId disambiguation is required.'
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: No such template (or version).
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '501':
+          description: Host does not advertise capabilities.prompts.endpointsSupported. (RFC 0028 §A — supported gates Phase
+            A node-execution composition; endpointsSupported gates this REST surface independently.)
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+      parameters:
+      - $ref: '#/components/parameters/OpenWOPVersion'
+    put:
+      tags:
+      - prompts
+      summary: Replace a prompt template (mutable libraries; user-source only).
+      operationId: updatePromptTemplate
+      parameters:
+      - $ref: '#/components/parameters/IdempotencyKey'
+      - $ref: '#/components/parameters/OpenWOPVersion'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: ../../schemas/v2/prompt-template.schema.json
+      responses:
+        '200':
+          description: Template updated.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/prompt-template.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          description: Template is pack-sourced or host-built-in (read-only).
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '404':
+          description: No such template.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '409':
+          description: Submitted version does not exceed stored version (SemVer).
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '501':
+          description: Host does not advertise capabilities.prompts.mutableLibrary.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+    delete:
+      tags:
+      - prompts
+      summary: Delete a prompt template (mutable libraries; user-source only).
+      operationId: deletePromptTemplate
+      responses:
+        '204':
+          description: Template deleted.
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          description: Template is pack-sourced or host-built-in (read-only).
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '404':
+          description: No such template.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '501':
+          description: Host does not advertise capabilities.prompts.mutableLibrary.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+      parameters:
+      - $ref: '#/components/parameters/OpenWOPVersion'
+  /prompts:render:
+    post:
+      tags:
+      - prompts
+      summary: Render a prompt template with supplied variable bindings.
+      description: 'Returns the composed body + sha256 hash + per-variable hashes.
+
+        The response''s `hash` MUST equal the `hash` that a matching
+
+        `prompt.composed` event would carry at dispatch time for the
+
+        same `(ref, variables, contentTrust)` inputs (RFC 0028 §A
+
+        deterministic-render invariant; RFC 0027 §F replay invariant).
+
+        Does NOT dispatch an LLM call. Secret-source variable values
+
+        MUST be supplied as `[REDACTED:<credentialRef>]` markers; the
+
+        host resolves the plaintext internally and never echoes it in
+
+        the `composed` response field per SR-1.
+
+        '
+      operationId: renderPromptTemplate
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - ref
+              - variables
+              properties:
+                ref:
+                  $ref: ../../schemas/v2/prompt-ref.schema.json
+                variables:
+                  type: object
+                  description: 'Variable bindings keyed by `PromptVariable.name`.
+
+                    Secret-source bindings carry `[REDACTED:<credentialRef>]`
+
+                    markers; the host resolves the real value internally.
+
+                    '
+                  additionalProperties: true
+                contentTrust:
+                  type: string
+                  enum:
+                  - trusted
+                  - untrusted
+                  description: 'Aggregate trust marker for the supplied bindings,
+
+                    propagated through composition per RFC 0027 §E.
+
+                    '
+      responses:
+        '200':
+          description: Composed result.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                - hash
+                - refs
+                - variableHashes
+                properties:
+                  composed:
+                    type: string
+                    description: Full composed body. Present only when observability is `full`.
+                  hash:
+                    type: string
+                    pattern: ^sha256:[0-9a-f]{64}$
+                  refs:
+                    type: array
+                    items:
+                      type: string
+                  variableHashes:
+                    type: object
+                    additionalProperties:
+                      type: string
+                      pattern: ^sha256:[0-9a-f]{64}$
+                  contentTrust:
+                    type: string
+                    enum:
+                    - trusted
+                    - untrusted
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '400':
+          description: '`prompt_variable_unresolved` (required variable missing),
+
+            `prompt_variable_type_mismatch` (bound type vs. declared type),
+
+            or `prompt_ref_invalid` (malformed PromptRef).
+
+            '
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Referenced template does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '501':
+          description: Host does not advertise capabilities.prompts.endpointsSupported. (RFC 0028 §A — supported gates Phase
+            A node-execution composition; endpointsSupported gates this REST surface independently.)
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/error-envelope.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+      parameters:
+      - $ref: '#/components/parameters/OpenWOPVersion'
+  /host/effect-seams:
+    get:
+      tags:
+      - Host
+      operationId: getEffectSeamManifest
+      summary: The host-declared effect-seam manifest (RFC 0173 §C)
+      description: Every outbound effect seam replay suppression covers. A seam omitted here is invisible to the suite; the
+        RFC 0140 R5 audit is the control.
+      responses:
+        '200':
+          description: The manifest.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/effect-seam-manifest.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+      parameters:
+      - $ref: '#/components/parameters/OpenWOPVersion'
+  /runs/{runId}/compensation:
+    parameters:
+    - $ref: '#/components/parameters/RunId'
+    get:
+      tags:
+      - Runs
+      operationId: getRunCompensation
+      summary: Compensation plan and attempts for a run (RFC 0173 §C.1)
+      description: The read projection that makes compensation a core obligation with a deployed-wire witness (RFC 0151 G9
+        / RFC 0173 §B).
+      responses:
+        '200':
+          description: The projection.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/compensation-projection.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      parameters:
+      - $ref: '#/components/parameters/OpenWOPVersion'
+  /runs/{runId}/effects:
+    parameters:
+    - $ref: '#/components/parameters/RunId'
+    get:
+      tags:
+      - Runs
+      operationId: getRunEffects
+      summary: The Layer-2 effect ledger for a run (RFC 0173 §C.2)
+      description: Business-identity keyed effect records; the witness for the Layer-2 effect-identity obligation.
+      responses:
+        '200':
+          description: The ledger projection.
+          content:
+            application/json:
+              schema:
+                $ref: ../../schemas/v2/effect-ledger-projection.schema.json
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      parameters:
+      - $ref: '#/components/parameters/OpenWOPVersion'
+  /host/events:
+    get:
+      tags:
+      - Host
+      operationId: streamHostEvents
+      summary: Host-scoped events (heartbeat.*) as SSE (RFC 0171 §E.1)
+      description: The documented default hostEvents address; a host MAY declare another under `heartbeat.deliveryChannel`.
+        Content-free of run data.
+      responses:
+        '200':
+          description: text/event-stream of hostEvents messages.
+          content:
+            text/event-stream:
+              schema:
+                type: string
+          headers:
+            OpenWOP-Version:
+              $ref: '#/components/headers/OpenWOPVersion'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+      parameters:
+      - $ref: '#/components/parameters/OpenWOPVersion'
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: API key
+      description: 'openwop API key. Format implementation-defined; reference impl uses `hk_`/`hk_test_` prefixes.
+
+        Each key carries one or more scopes from the canonical vocabulary
+
+        (`manifest:read`, `runs:create`, `runs:read`, `runs:cancel`,
+
+        `artifacts:read`, `webhooks:manage`, `approvals:respond`, `audit:read`).
+
+        See `auth.md`.
+
+        '
+  parameters:
+    WorkflowId:
+      in: path
+      name: workflowId
+      required: true
+      schema:
+        type: string
+        minLength: 1
+        maxLength: 128
+    RunId:
+      in: path
+      name: runId
+      required: true
+      schema:
+        type: string
+        minLength: 1
+        maxLength: 128
+    IdempotencyKey:
+      in: header
+      name: Idempotency-Key
+      required: false
+      schema:
+        type: string
+        maxLength: 255
+      description: 'Per-mutation idempotency token (see `idempotency.md` Layer 1).
+
+        Server caches `(tenantId, endpoint, key)` → response for ≥24h.
+
+        Duplicate requests return the cached response with header
+
+        `OpenWOP-Idempotent-Replay: true`.
+
+        '
+    OpenWOPVersion:
+      name: OpenWOP-Version
+      in: header
+      required: false
+      schema:
+        type: string
+        pattern: ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$
+      description: RFC 0172 §A.3 — selects a listed major.minor; absent ⇒ the host's `preferredVersion`; unlisted ⇒ 406 protocol_version_unsupported.
+  responses:
+    Unauthenticated:
+      description: Missing or invalid credential.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Forbidden:
+      description: Credential valid but lacks required scope or fails resource binding.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    NotFound:
+      description: Resource doesn't exist or caller can't see it (do not leak existence).
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    ValidationError:
+      description: Request body or parameters malformed.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    RateLimited:
+      description: Too many requests.
+      headers:
+        Retry-After:
+          schema:
+            type: integer
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+  schemas:
+    Error:
+      $ref: ../../schemas/v2/error-envelope.schema.json
+    Capabilities:
+      $ref: ../../schemas/v2/capabilities.schema.json
+    RunSnapshot:
+      $ref: ../../schemas/v2/run-snapshot.schema.json
+    RunClaimConflict:
+      $ref: ../../schemas/v2/error-envelope.schema.json
+      description: RFC 0171 §B.1 — the former one-member enum `RunClaimConflict` is the generated error envelope (`error`
+        carries the code).
+    UnsupportedStreamMode:
+      $ref: ../../schemas/v2/error-envelope.schema.json
+      description: RFC 0171 §B.1 — the former one-member enum `UnsupportedStreamMode` is the generated error envelope (`error`
+        carries the code).
+  headers:
+    OpenWOPVersion:
+      schema:
+        type: string
+      description: RFC 0172 §A.4 — the contract that produced this response; MUST equal the one used.
+      required: true