@openwop/spec-artifacts 2.42.5 → 2.42.7

package/api/seams-v2.yaml

@@ -1,15 +1,16 @@
 openapi: 3.1.0
 info:
   title: OpenWOP conformance seams profile (openwop-conformance-seams-v2)
-  version: 2.42.5
-  description: 'GENERATED by scripts/derive-v2-api.py. RFC 0168 §C: the seams are a versioned conformance profile with their
-    own document and path space (/conformance/seams/…), validated against the canonical v2 schemas with no tolerance path,
-    forbidden from the capability namespace (a host advertises the profile, never a testSeams flag). This document carries
-    the nine operations the v1 canonical document used to carry; the 2.0.0 suite driver (P3-E2) rewrites the remaining host-sample-test-seams.md
-    paths into this space, and P3-E3 adds the two RFC 0176 seams (event-log seed, inbound webhook receiver).'
+  version: 2.42.7
+  description: 'The OpenWOP conformance seams profile (`openwop-conformance-seams-v2`): test-only operations in their own
+    path space, `/conformance/seams/…`. The profile is versioned and validated against the canonical v2 schemas with no tolerance
+    path. It is not a capability: a host advertises the profile, never a `testSeams` flag.
+
+
+    Generated from `api/openapi.yaml` by `scripts/derive-v2-api.py`; do not edit.'
 servers:
 - url: https://{host}
-  description: openwop-compliant server
+  description: An OpenWOP server.
   variables:
     host:
       default: api.example.com
@@ -19,18 +20,10 @@ paths:
     get:
       tags:
       - host
-      summary: Read the persisted durable A2A task projection (RFC 0100, host-extension).
-      description: 'Returns the persisted `A2ATaskState` for `taskId` (== the backing
-
-        `runId`) per RFC 0100 §2 — a host-extension convenience read of the
-
-        durable projection that survives caller disconnect. The normative A2A
-
-        read surface remains the A2A `tasks/get` JSON-RPC method. Hosts that do
-
-        not advertise `capabilities.a2a.durableTasks` return `501`.
-
-        '
+      summary: Read the persisted durable A2A task projection (host extension).
+      description: 'Returns the persisted `A2ATaskState` for `taskId` (equal to the backing `runId`): a host-extension convenience
+        read of the durable projection, which survives caller disconnect. The normative A2A read surface remains the A2A `tasks/get`
+        JSON-RPC method. Hosts that do not advertise `capabilities.a2a.durableTasks` return `501`.'
       operationId: getA2ATaskState
       security:
       - ApiKeyAuth:
@@ -61,7 +54,7 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
         '501':
-          description: Host does not advertise capabilities.a2a.durableTasks (RFC 0100).
+          description: Host does not advertise `capabilities.a2a.durableTasks`.
           content:
             application/json:
               schema:
@@ -70,14 +63,9 @@ paths:
     get:
       tags:
       - host
-      summary: List workspace file metadata for the caller's tenant·workspace (RFC 0059).
-      description: 'Returns file metadata (no bodies) for the caller''s `{tenant,
-
-        workspace}` per RFC 0059 §C. Optional `?prefix=` filters the flat
-
-        `path` namespace to entries starting with the given prefix.
-
-        '
+      summary: List workspace file metadata for the caller's tenant·workspace.
+      description: Returns file metadata, without bodies, for the caller's `{tenant, workspace}`. An optional `?prefix=` filters
+        the flat `path` namespace to entries starting with that prefix.
       operationId: listWorkspaceFiles
       security:
       - ApiKeyAuth:
@@ -108,7 +96,7 @@ paths:
         '403':
           $ref: '#/components/responses/Forbidden'
         '501':
-          description: Host does not advertise capabilities.workspace.supported (RFC 0059).
+          description: Host does not advertise `capabilities.workspace.supported`.
           content:
             application/json:
               schema:
@@ -117,14 +105,9 @@ paths:
     get:
       tags:
       - host
-      summary: Read one workspace file (RFC 0059).
-      description: 'Returns the `WorkspaceFile` at `path` for the caller''s `{tenant,
-
-        workspace}`. When `capabilities.workspace.versioned: true`, an
-
-        optional `?version=N` returns the historical snapshot at version N.
-
-        '
+      summary: Read one workspace file.
+      description: 'Returns the `WorkspaceFile` at `path` for the caller''s `{tenant, workspace}`. When `capabilities.workspace.versioned:
+        true`, an optional `?version=N` returns the historical snapshot at version N.'
       operationId: getWorkspaceFile
       security:
       - ApiKeyAuth:
@@ -150,7 +133,7 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
         '501':
-          description: Host does not advertise capabilities.workspace.supported (RFC 0059).
+          description: Host does not advertise `capabilities.workspace.supported`.
           content:
             application/json:
               schema:
@@ -158,20 +141,11 @@ paths:
     put:
       tags:
       - host
-      summary: Atomic create/replace of a workspace file (RFC 0059).
-      description: 'Atomically creates or replaces the file at `path` per RFC 0059 §C.
-
-        MUST honor `If-Match: <etag>` — a stale token returns `409
-
-        workspace_conflict` (`details.currentVersion` carries the live
-
-        version). On success the host bumps `version`, recomputes `etag`,
-
-        and emits a `workspace.updated` event. A `content` exceeding
-
-        `capabilities.workspace.maxFileBytes` returns `workspace_too_large`.
-
-        '
+      summary: Atomically create or replace a workspace file.
+      description: 'Atomically creates or replaces the file at `path`. MUST honor `If-Match: <etag>`: a stale token returns
+        `409 workspace_conflict`, with `details.currentVersion` carrying the live version. On success the host bumps `version`,
+        recomputes `etag`, and emits a `workspace.updated` event. A `content` exceeding `capabilities.workspace.maxFileBytes`
+        returns `workspace_too_large`.'
       operationId: putWorkspaceFile
       security:
       - ApiKeyAuth:
@@ -216,7 +190,7 @@ paths:
               schema:
                 $ref: ../schemas/v2/error-envelope.schema.json
         '501':
-          description: Host does not advertise capabilities.workspace.supported (RFC 0059).
+          description: Host does not advertise `capabilities.workspace.supported`.
           content:
             application/json:
               schema:
@@ -224,12 +198,9 @@ paths:
     delete:
       tags:
       - host
-      summary: Delete a workspace file (RFC 0059).
-      description: 'Removes the file at `path` (and, when `versioned: true`, writes a
-
-        tombstone). Emits a `workspace.updated` event on success.
-
-        '
+      summary: Delete a workspace file.
+      description: 'Removes the file at `path` (and, when `versioned: true`, writes a tombstone). Emits a `workspace.updated`
+        event on success.'
       operationId: deleteWorkspaceFile
       security:
       - ApiKeyAuth:
@@ -251,7 +222,7 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
         '501':
-          description: Host does not advertise capabilities.workspace.supported (RFC 0059).
+          description: Host does not advertise `capabilities.workspace.supported`.
           content:
             application/json:
               schema:
@@ -264,35 +235,15 @@ paths:
       tags:
       - packs-test
       summary: Publish a pack tarball to the isolated test catalog.
-      description: 'Mirror of `PUT /v1/packs/{name}/-/{version}.tgz` per
-
-        `spec/v1/node-packs.md` §"PUT /v1/packs/{name}/-/{version}.tgz".
-
-        Request shape, response shape, status codes, and the 19-code
-
-        publish error catalog (`invalid_pack_scope`, `invalid_pack_name`,
-
-        `invalid_version`, `invalid_body`, eight `tarball_*` codes,
-
-        `invalid_manifest`, `manifest_mismatch` (or the granular
-
-        `manifest_name_mismatch` / `manifest_version_mismatch` pair),
-
-        `pack_integrity_failure`, `unsupported_runtime`, `forbidden`,
-
-        `conflict`/`version_conflict`) MUST be served verbatim. The
-
-        test catalog MUST be isolated per RFC 0025 §C — a pack PUT''d
+      description: 'Mirrors the registry''s `PUT /v1/packs/{name}/-/{version}.tgz` (`spec/v1/node-packs.md`). The request
+        shape, response shape, status codes, and publish error catalog MUST be served verbatim: `invalid_pack_scope`, `invalid_pack_name`,
+        `invalid_version`, `invalid_body`, eight `tarball_*` codes, `invalid_manifest`, `manifest_mismatch` (or the granular
+        `manifest_name_mismatch` / `manifest_version_mismatch` pair), `pack_integrity_failure`, `unsupported_runtime`, `forbidden`,
+        `conflict`/`version_conflict`.
 
-        here MUST NOT appear in `GET /v1/packs/{name}` listings.
 
-        The mirrored production path is registry-service surface
-
-        (`registry-operations.md`), not defined in this host document
-
-        (see the `packs-test` tag scope note).
-
-        '
+        The test catalog MUST be isolated: a pack PUT here MUST NOT appear in `GET /v1/packs/{name}` listings. The mirrored
+        production path is registry-service surface (`registry-operations.md`), not defined in this document.'
       operationId: putTestPackTarball
       security:
       - ApiKeyAuth:
@@ -352,29 +303,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/TestPackPublishRecord'
         '400':
-          description: 'One of the 17 spec-documented 400-class publish error codes:
-
-            URL/scope (`invalid_pack_scope`, `invalid_pack_name`, `invalid_version`),
-
-            body shape (`invalid_body`),
-
-            tarball extraction (`tarball_gunzip_failed`, `tarball_too_large`,
-
-            `tarball_manifest_missing`, `tarball_manifest_too_large`,
-
-            `tarball_manifest_not_json`, `tarball_entry_missing`,
-
-            `tarball_entry_too_large`, `tarball_path_traversal`,
-
-            `tarball_tar_parse_failed`),
-
-            manifest contents (`invalid_manifest`, `manifest_mismatch` or
-
-            the granular `manifest_name_mismatch` / `manifest_version_mismatch` pair,
-
-            `pack_integrity_failure`, `unsupported_runtime`).
-
-            '
+          description: 'One of the documented 400-class publish error codes: URL or scope (`invalid_pack_scope`, `invalid_pack_name`,
+            `invalid_version`), body shape (`invalid_body`), tarball extraction (`tarball_gunzip_failed`, `tarball_too_large`,
+            `tarball_manifest_missing`, `tarball_manifest_too_large`, `tarball_manifest_not_json`, `tarball_entry_missing`,
+            `tarball_entry_too_large`, `tarball_path_traversal`, `tarball_tar_parse_failed`), or manifest contents (`invalid_manifest`,
+            `manifest_mismatch` or the granular `manifest_name_mismatch` / `manifest_version_mismatch` pair, `pack_integrity_failure`,
+            `unsupported_runtime`).'
           content:
             application/json:
               schema:
@@ -404,10 +338,9 @@ paths:
       tags:
       - packs-test
       summary: Fetch a published test-catalog tarball.
-      description: 'Mirror of `GET /v1/packs/{name}/-/{version}.tgz`. Returns the gzipped tarball bytes with `Content-Type:
-        application/tar+gzip` and an `ETag: "sha256-..."` matching the manifest''s `tarballSha256`. The mirrored production
-        path is registry-service surface (`registry-operations.md`), not defined in this host document (see the `packs-test`
-        tag scope note).'
+      description: 'Mirrors the registry''s `GET /v1/packs/{name}/-/{version}.tgz`. Returns the gzipped tarball bytes with
+        `Content-Type: application/tar+gzip` and an `ETag: "sha256-..."` matching the manifest''s `tarballSha256`. The mirrored
+        production path is registry-service surface (`registry-operations.md`), not defined in this document.'
       operationId: getTestPackTarball
       security:
       - ApiKeyAuth:
@@ -452,26 +385,11 @@ paths:
     delete:
       tags:
       - packs-test
-      summary: Unpublish a test-catalog version (mirrors unpublish-window semantics).
-      description: 'Mirror of `DELETE /v1/packs/{name}/-/{version}` per
-
-        `spec/v1/node-packs.md`. Returns `400 unpublish_window_expired`
-
-        for versions older than the registry''s unpublish window
-
-        (default 72h). Test-mode implementations MAY shorten the
-
-        window for tractable conformance fixtures but MUST surface
-
-        the same error code. The mirrored production path is
-
-        registry-service surface (`registry-operations.md`), not
-
-        defined in this host document (see the `packs-test` tag
-
-        scope note).
-
-        '
+      summary: Unpublish a test-catalog version (same unpublish-window semantics as the registry).
+      description: Mirrors the registry's `DELETE /v1/packs/{name}/-/{version}` (`spec/v1/node-packs.md`). Returns `400 unpublish_window_expired`
+        for versions older than the registry's unpublish window (default 72h). Test-mode implementations MAY shorten the window
+        for tractable conformance fixtures but MUST surface the same error code. The mirrored production path is registry-service
+        surface (`registry-operations.md`), not defined in this document.
       operationId: deleteTestPackVersion
       security:
       - ApiKeyAuth:
@@ -511,17 +429,9 @@ paths:
       tags:
       - packs-test
       summary: Fetch the detached Ed25519 signature for a test-catalog pack.
-      description: 'Mirror of `GET /v1/packs/{name}/-/{version}.sig`. Returns the
-
-        signature blob over `pack.json` for this version. MAY 302-redirect
-
-        to a storage-backend signed URL. The mirrored production path is
-
-        registry-service surface (`registry-operations.md`), not defined
-
-        in this host document (see the `packs-test` tag scope note).
-
-        '
+      description: Mirrors the registry's `GET /v1/packs/{name}/-/{version}.sig`. Returns the signature blob over `pack.json`
+        for this version. MAY 302-redirect to a storage-backend signed URL. The mirrored production path is registry-service
+        surface (`registry-operations.md`), not defined in this document.
       operationId: getTestPackSignature
       security:
       - ApiKeyAuth:
@@ -560,19 +470,9 @@ paths:
               schema:
                 $ref: ../schemas/v2/error-envelope.schema.json
         '404':
-          description: '`signature_not_available` — version is missing, yanked,
-
-            unsigned at publish time, OR the registry''s storage backend
-
-            is unwired. The four cases are intentionally
-
-            indistinguishable per spec/v1/node-packs.md §"GET /v1/packs/{name}/-/{version}.sig".
-
-            Also returned when the host does not advertise
-
-            `capabilities.packs.testMode.supported: true`.
-
-            '
+          description: '`signature_not_available`: the version is missing, yanked, or unsigned at publish time, or the registry''s
+            storage backend is unwired. The four cases are intentionally indistinguishable (spec/v1/node-packs.md). Also returned
+            when the host does not advertise `capabilities.packs.testMode.supported: true`.'
           content:
             application/json:
               schema:
@@ -582,11 +482,11 @@ paths:
       tags:
       - Seams
       operationId: seedEra2EventLog
-      summary: Persist a run whose event log is in v1 vocabulary (era 2) — RFC 0176 §A/§B/§C witnesses
-      description: 'The host MUST persist the rows verbatim (v1 `type` strings, the given `sequence` space, no era stamp:
-        the run reads as era `2` by the absent-⇒-`2` rule of persistence.md) and MUST NOT translate at write time; the read
-        projection is what the scenarios `v2-v1-events-translated`, `v2-unmapped-type-refused`, `v2-fork-a-v1-run` and `v2-pinned-run-disposition`
-        witness. `status` is the snapshot status the seeded run holds.'
+      summary: Persist a run whose event log uses v1 vocabulary (era 2)
+      description: 'Seeds a run whose stored event log is in v1 vocabulary. The host MUST persist the rows verbatim: v1 `type`
+        strings, the given `sequence` space, and no era stamp, so the run reads as era `2` by the absent-⇒-`2` rule of persistence.md.
+        The host MUST NOT translate at write time. The scenarios `v2-v1-events-translated`, `v2-unmapped-type-refused`, `v2-fork-a-v1-run`
+        and `v2-pinned-run-disposition` witness the read projection. `status` is the snapshot status the seeded run holds.'
       requestBody:
         required: true
         content:
@@ -648,22 +548,79 @@ paths:
           $ref: '#/components/responses/ValidationError'
         '401':
           $ref: '#/components/responses/Unauthenticated'
+  /conformance/seams/sample/event-log/append:
+    post:
+      tags:
+      - Seams
+      operationId: appendEra2Event
+      summary: Append a v2-named event to a seeded era-2 run through the host's production writer
+      description: 'The host MUST append the event through the same writer its own code uses for that run (the storage boundary
+        that applies the writer rule, persistence.md §The writer rule) and MUST NOT branch on the seam. An era-2 run stores
+        the event under its v1 spelling (the codemap''s v1 side), so the production read returns the v2 `type` given here.
+
+
+        The seam MUST refuse a `runId` that `seedEra2EventLog` did not create with `404`, exactly as for an unknown run, so
+        it cannot inject into a real run. A terminal run answers `409 run_terminal`; a `type` that is not a v2 registry name
+        answers `400`. Used by `v2-era-2-append-vocabulary`.'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required:
+              - runId
+              - type
+              - payload
+              properties:
+                runId:
+                  $ref: ../schemas/v2/ids.schema.json#/$defs/runId
+                type:
+                  type: string
+                  description: A v2 event type name (schemas/v2/run-event.schema.json `type` enum).
+                payload:
+                  type: object
+      responses:
+        '202':
+          description: The event was appended.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: false
+                required:
+                - runId
+                - sequence
+                properties:
+                  runId:
+                    $ref: ../schemas/v2/ids.schema.json#/$defs/runId
+                  sequence:
+                    type: integer
+                    minimum: 0
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: The run is terminal (`run_terminal`).
   /conformance/seams/sample/effect-seams/fire:
     post:
       tags:
       - Seams
       operationId: fireEffectSeam
-      summary: Fire one named effect-seam manifest row inside a run — RFC 0173 §C no-re-fire witness
+      summary: Fire one named effect seam inside a run
       description: 'The host runs a workflow that drives the named seam once. The scenario then forks the run in `replay`
-        mode and reads `GET /runs/{runId}/effects` on the fork: a GUARDED seam MUST NOT produce a new effect attempt there,
-        because replay suppression is unconditional (`replay.md` §Suppression rule 1) and does not depend on `branchReFires`,
-        which states only what a `branch` re-fires by design (§Branch: a host "MUST NOT report that as replay suppression").
-        The witness is the host own Layer-2 ledger, so the leg needs no externally reachable receiver. Without this seam the
-        replay-suppression obligation is only claims-checkable. HOW THE TARGET IS CHOSEN (suite 2.0.3): the scenario fires
-        the first `GET /host/effect-seams` row with `guarded: true`, not every row, and records `inapplicable` without calling
-        this operation at all when no row is guarded. Stated here because it is a contract an implementer cannot see from
-        the request body — until 2.0.2 the filter also required `branchReFires: false`, and a host whose seams all honestly
-        re-fire on branch would have built this seam only to find the scenario still declining to call it.'
+        mode and reads `GET /runs/{runId}/effects` on the fork. A guarded seam MUST NOT produce a new effect attempt there:
+        replay suppression is unconditional (`replay.md` §Suppression rule 1) and does not depend on `branchReFires`, which
+        states only what a `branch` re-fires by design (§Branch: a host "MUST NOT report that as replay suppression"). The
+        witness is the host''s own Layer-2 ledger, so the leg needs no externally reachable receiver.
+
+
+        The scenario fires the first `GET /host/effect-seams` row with `guarded: true`, not every row. When no row is guarded
+        it records `inapplicable` without calling this operation.'
       requestBody:
         required: true
         content:
@@ -677,12 +634,12 @@ paths:
                 seam:
                   type: string
                   minLength: 1
-                  description: The `seam` value of a row in GET /host/effect-seams.
+                  description: The `seam` value of a row in `GET /host/effect-seams`.
                 receiverUrl:
                   type: string
                   format: uri
-                  description: Optional destination for seams whose kind needs one. Omitted, the host uses its own unreachable
-                    fixture destination — the witness is the effect ledger, not delivery.
+                  description: Optional destination, for seams whose kind needs one. Omitted, the host uses its own unreachable
+                    fixture destination; the witness is the effect ledger, not delivery.
       responses:
         '201':
           description: The run that fired the seam.
@@ -707,11 +664,10 @@ paths:
       tags:
       - Seams
       operationId: forceEffectTransportRetry
-      summary: Drive one effect through the suite fixture provider with a forced transport retry — RFC 0173 §D.2 G4 witness
-      description: 'The host issues one outbound effect to `providerUrl` and retries it at the transport layer. The suite
-        fixture provider records the idempotency key of each attempt: a Layer-2 host MUST present the SAME business-identity
-        key across both attempts, so a provider that sees a changed key fails the leg. Without this seam the effect-identity
-        obligation is only claims-checkable.'
+      summary: Drive one effect through the suite's fixture provider with a forced transport retry
+      description: The host issues one outbound effect to `providerUrl` and retries it at the transport layer. The fixture
+        provider records the idempotency key of each attempt. A Layer-2 host MUST present the same business-identity key on
+        both attempts; a provider that sees a changed key fails the leg.
       requestBody:
         required: true
         content:
@@ -752,12 +708,11 @@ paths:
       tags:
       - Seams
       operationId: armIdempotencyHold
-      summary: Hold the caller's next same-key create in flight — RFC 0213 §B witness
+      summary: Hold the caller's next same-key create in flight
       description: 'Arms a single-use hold: the caller tenant''s next real `POST /runs` carrying `key` as its Idempotency-Key
         keeps its Layer-1 claim in flight for `holdMs` after claiming, then completes normally. The seam MUST NOT answer a
         create or emit a 409: the refusal a concurrent same-key create receives while the claim is held comes from the host''s
-        production in-flight branch (idempotency.md §Concurrency). Keyed by (tenant, key); single-use; an unarmed key is never
-        delayed.'
+        production in-flight branch (idempotency.md §Concurrency). Keyed by (tenant, key); an unarmed key is never delayed.'
       requestBody:
         required: true
         content:
@@ -801,10 +756,11 @@ paths:
       tags:
       - Seams
       operationId: receiveWebhookDelivery
-      summary: Run a webhook delivery through the host's inbound receiver — RFC 0176 §D.2 witness
-      description: The v2 host as a subscriber. The host verifies `headers` + `body` with its production verifier using `secret`
-        as the subscription secret and reports the verdict; an `X-openwop-*`-only scheme-`v1` delivery over `{timestamp}.{rawBody}`
-        MUST be accepted (`v2-v1-signed-webhook-accepted`), and a tampered signature MUST be refused.
+      summary: Run a webhook delivery through the host's inbound receiver
+      description: Exercises the host as a webhook subscriber. The host verifies `headers` and `body` with its production
+        verifier, using `secret` as the subscription secret, and reports the verdict. A scheme-`v1` delivery carrying only
+        `X-openwop-*` headers, signed over `{timestamp}.{rawBody}`, MUST be accepted (`v2-v1-signed-webhook-accepted`); a
+        tampered signature MUST be refused.
       requestBody:
         required: true
         content:
@@ -850,19 +806,24 @@ paths:
       tags:
       - Seams
       operationId: emitA2uiSurface
-      summary: Admit one `ui.a2ui-surface` envelope into a run through the production envelope-admission path — RFC 0209 witness
-      description: 'A real `ui.a2ui-surface` envelope is emitted by a model inside a node turn, so the suite cannot choose
-        one from the canonical wire. This seam supplies the envelope ONLY. The host MUST admit it through its PRODUCTION envelope-admission
-        path — the envelope-kind catalog (`supportedEnvelopes`, `schemaVersions`, `envelopeStrictness`, events.md §"The envelope-kind
-        catalog"), validation against the ONE per-kind branch the schema version selects (never the `anyOf` union), the RFC
-        0209 cross-field rules (every message `surfaceId` equals the payload `surfaceId`; a `createSurface.catalogId` equals
-        the payload `catalogId`), the surface-fold guard (spec/v2/ext/a2uiSurface/README.md §"The fold"), trust propagation
-        and SR-1 redaction — and MUST record it exactly as production would. It MUST NOT be a mock that records without those
-        rules. `envelope.nodeId`, when present, binds the surface to that node, so a surface emitted at a node suspended on
-        an `approval` interrupt is the surface whose `resume` action would resolve it (§"Trust": a tainted fold blocks that
-        interrupt). Refusals use the canonical error envelope: `422 unknown_schema_version` above the floor or under `strict`
-        below it, `422 envelope_invalid` for a payload that fails its branch, a cross-field rule or the fold guard, `422 unknown_envelope_kind`
-        when the host does not list the kind; `details` SHOULD name the rule. A host that has not wired the seam answers `404`/`405`,
+      summary: Admit one `ui.a2ui-surface` envelope into a run through the production admission path
+      description: 'Supplies one `ui.a2ui-surface` envelope for the host to admit. A real one is emitted by a model inside
+        a node turn, so the suite cannot choose one from the canonical wire; this seam supplies the envelope only.
+
+
+        The host MUST admit it through its production envelope-admission path and MUST record it exactly as production would.
+        That path covers the envelope-kind catalog (`supportedEnvelopes`, `schemaVersions`, `envelopeStrictness`; events.md
+        §"The envelope-kind catalog"), validation against the one per-kind branch the schema version selects (never the `anyOf`
+        union), the cross-field rules (every message `surfaceId` equals the payload `surfaceId`; a `createSurface.catalogId`
+        equals the payload `catalogId`), the surface-fold guard (spec/v2/ext/a2uiSurface/README.md §"The fold"), trust propagation,
+        and SR-1 redaction. It MUST NOT be a mock that records without those rules. `envelope.nodeId`, when present, binds
+        the surface to that node, so a surface emitted at a node suspended on an `approval` interrupt is the surface whose
+        `resume` action would resolve it (§"Trust": a tainted fold blocks that interrupt).
+
+
+        Refusals use the canonical error envelope: `422 unknown_schema_version` above the floor, or below it under `strict`;
+        `422 envelope_invalid` for a payload that fails its branch, a cross-field rule, or the fold guard; `422 unknown_envelope_kind`
+        when the host does not list the kind. `details` SHOULD name the rule. A host that has not wired the seam answers `404`/`405`,
         and the scenario records `inapplicable`.'
       requestBody:
         required: true
@@ -912,19 +873,23 @@ paths:
       tags:
       - Seams
       operationId: startOAuthAuthorization
-      summary: Begin an authorization-code grant for the caller through the production authorization-URL builder — RFC 0199
-        §A/§B witness
-      description: 'Points `provider` at the given endpoints (the suite''s authorization-server double) — a test-only provider
-        definition, or, with `connection`, the connection pack''s provider through the host''s PRODUCTION registration path,
-        which runs the RFC 0199 §B.3 discovery and pins its tuple — and then begins an authorization-code grant for the AUTHENTICATED
-        caller by calling the host''s PRODUCTION authorization-URL builder, returning the URL a user agent would be redirected
-        to. The builder MUST be the one production uses (PKCE S256, a fresh `state` bound to the caller''s Subject and the
-        provider, the provider''s fixed redirect URI, `iss` expectations, `resource` for an MCP reach); a seam that assembles
-        its own URL measures a stub, and a bundle citing it MUST say which. The grant completes on the host''s PRODUCTION
-        callback route, which the suite calls as the user agent. `redirectUri` is a probe: the host MUST ignore it (the redirect
-        URI is fixed per provider, oauth.md rule 5). A refused grant — an MCP-reach provider with no `issuer`, `pkce: "unsupported"`,
-        or discovered metadata that disagrees with the manifest or the pinned tuple — is `422 connection_auth_metadata_mismatch`
-        and no authorization URL is issued. A host that has not wired the seam answers `404`, and the scenarios record `blocked`.'
+      summary: Begin an authorization-code grant through the production authorization-URL builder
+      description: 'Points `provider` at the given endpoints (the suite''s authorization-server double), then begins an authorization-code
+        grant for the authenticated caller by calling the host''s production authorization-URL builder, and returns the URL
+        a user agent would be redirected to. The provider is a test-only provider definition or, with `connection`, the connection
+        pack''s provider registered through the host''s production registration path, which runs discovery and pins its tuple.
+
+
+        The builder MUST be the one production uses: PKCE S256, a fresh `state` bound to the caller''s Subject and the provider,
+        the provider''s fixed redirect URI, `iss` expectations, and `resource` for an MCP reach. A seam that assembles its
+        own URL measures a stub, and a bundle citing it MUST say which. The grant completes on the host''s production callback
+        route, which the suite calls as the user agent. `redirectUri` is a probe: the host MUST ignore it (the redirect URI
+        is fixed per provider, oauth.md rule 5).
+
+
+        A refused grant (an MCP-reach provider with no `issuer`, `pkce: "unsupported"`, or discovered metadata that disagrees
+        with the manifest or the pinned tuple) is `422 connection_auth_metadata_mismatch`, and no authorization URL is issued.
+        A host that has not wired the seam answers `404`, and the scenarios record `blocked`.'
       requestBody:
         required: true
         content:
@@ -962,8 +927,8 @@ paths:
                     minLength: 1
                 connection:
                   $ref: ../schemas/v2/connection-pack-manifest.schema.json
-                  description: A connection pack whose provider is reached as an MCP server (RFC 0199 §B); registered through
-                    the production path.
+                  description: A connection pack whose provider is reached as an MCP server; registered through the production
+                    path.
                 redirectUri:
                   type: string
                   description: A probe the host MUST ignore.
@@ -999,14 +964,13 @@ paths:
       tags:
       - Seams
       operationId: expireOAuthAccessToken
-      summary: Expire the caller's stored access token for a provider so its next use refreshes — RFC 0199 §C.2(b) / RFC 0047
-        §C.3 witness
-      description: 'Marks the access token of the caller''s stored credential for `provider` expired. Nothing else: the next
-        node that uses it refreshes through the host''s PRODUCTION refresh path against the provider''s token endpoint (the
-        suite''s double, which decides whether the refresh token is still good). A terminal refresh failure then follows oauth.md
-        §Token lifecycle — `connector.auth-expired`, and either the node fails `connector_auth_expired` or, under `oauth.credentialInterrupt`,
-        it suspends on a `credential` interrupt with `reason: "expired"`. `404` when the caller holds no credential for the
-        provider.'
+      summary: Expire the caller's stored access token for a provider so its next use refreshes
+      description: 'Marks the access token of the caller''s stored credential for `provider` expired, and nothing else. The
+        next node that uses it refreshes through the host''s production refresh path against the provider''s token endpoint
+        (the suite''s double, which decides whether the refresh token is still good). A terminal refresh failure then follows
+        oauth.md §Token lifecycle: `connector.auth-expired`, and either the node fails `connector_auth_expired` or, under
+        `oauth.credentialInterrupt`, it suspends on a `credential` interrupt with `reason: "expired"`. `404` when the caller
+        holds no credential for the provider.'
       requestBody:
         required: true
         content:
@@ -1034,9 +998,9 @@ paths:
       tags:
       - Seams
       operationId: mintLaneCredential
-      summary: Mint a fresh credential on an advertised lane for the caller's tenant — RFC 0170 §B.3 witness
+      summary: Mint a fresh credential on an advertised lane for the caller's tenant
       description: 'Issues a new credential on `lane` (an advertised `auth.lanes[].lane` whose `revocation` is `next-request`;
-        absent ⇒ `api-key`) for the AUTHENTICATED caller''s tenant, through the host''s PRODUCTION issuance path, so the credential
+        absent ⇒ `api-key`) for the authenticated caller''s tenant, through the host''s production issuance path, so the credential
         it returns authenticates on the canonical API exactly as an ordinary one does. The suite uses it only to hold a credential
         it can then revoke: the revocation, and the refusal on the next request (`401 credential_revoked`), are production
         behaviour the seam does not simulate. A host that has not wired the seam answers `404`, and the scenario records the
@@ -1079,8 +1043,7 @@ paths:
                     - kind
                     description: 'How the suite presents `credential` on the canonical API. Absent ⇒ bearer. A lane whose
                       production credential is cookie-borne (a `session` lane) answers `{ kind: "cookie", name }`, and the
-                      suite sends `Cookie: <name>=<credential>`. Added so a cookie lane that honours `next-request` revocation
-                      can be witnessed without advertising a false rule.'
+                      suite sends `Cookie: <name>=<credential>`.'
                     properties:
                       kind:
                         type: string
@@ -1090,7 +1053,7 @@ paths:
                       name:
                         type: string
                         pattern: ^[!#$%&'*+.^_`|~0-9A-Za-z-]+$
-                        description: The cookie name (RFC 6265 token). Required when `kind` is `cookie`.
+                        description: The cookie name (an RFC 6265 token). Required when `kind` is `cookie`.
                     if:
                       properties:
                         kind:
@@ -1113,8 +1076,8 @@ paths:
       tags:
       - Seams
       operationId: revokeLaneCredential
-      summary: Revoke a credential the mint seam issued — RFC 0170 §B.3 witness
-      description: Revokes `credential` through the host's PRODUCTION revocation path. On a `next-request` lane the very next
+      summary: Revoke a credential the mint seam issued
+      description: Revokes `credential` through the host's production revocation path. On a `next-request` lane the very next
         request presenting it MUST be refused `401 credential_revoked` (identity.md §2.2); the suite observes that on the
         canonical API, not through this seam. `404` when no active credential matches.
       requestBody:
@@ -1160,16 +1123,25 @@ paths:
       tags:
       - Seams
       operationId: getTranscriptWindow
-      summary: The host's own accounting of what it fed the model on one orchestrator turn — RFC 0111 witness
-      description: 'The orchestrator transcript a host assembles each iteration is host-internal and never crosses the wire.
-        This seam returns what the host fed the model on turn `iteration` of `runId`: `tokenCount` in the advertised `contextBudget.tokenCounter`
-        unit (MUST be ≤ `transcriptTokenBudget`), `eventIds` (the verbatim recent tail, in event-log order), `summarizedRanges`,
-        and `entries[] { eventId, rendered }` — the exact text fed per item, REQUIRED when `tokenCounter` is `chars` so the
-        suite can sum the rendered Unicode code points and require it to equal `tokenCount`. A summary substitution''s entry
-        names its `context.summarized` event and renders the summary text. Served in test mode only; `rendered` MUST NOT carry
-        secret material (SR-1). The ceiling is advertise-and-attest: the seam proves the declared accounting is consistent
-        and bounded, not that nothing else reached the model. A turn past the run''s last answers `400`/`422`; an unwired
-        seam answers `404`/`405`.'
+      summary: Read the host's accounting of what it fed the model on one orchestrator turn
+      description: 'Returns what the host fed the model on turn `iteration` of `runId`. The orchestrator transcript a host
+        assembles each iteration is host-internal and never crosses the wire, so this seam reports the host''s own accounting:
+
+
+        - `tokenCount`, in the advertised `contextBudget.tokenCounter` unit. MUST be ≤ `transcriptTokenBudget`.
+
+        - `eventIds`: the verbatim recent tail, in event-log order.
+
+        - `summarizedRanges`.
+
+        - `entries[] { eventId, rendered }`: the exact text fed per item. REQUIRED when `tokenCounter` is `chars`, so the
+        suite can sum the rendered Unicode code points and require the sum to equal `tokenCount`. A summary substitution''s
+        entry names its `context.summarized` event and renders the summary text.
+
+
+        Served in test mode only; `rendered` MUST NOT carry secret material (SR-1). The ceiling is advertise-and-attest: the
+        seam proves the declared accounting is consistent and bounded, not that nothing else reached the model. A turn past
+        the run''s last answers `400`/`422`; an unwired seam answers `404`/`405`.'
       parameters:
       - name: runId
         in: query
@@ -1255,28 +1227,13 @@ components:
       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`.
-
-        '
+      description: OpenWOP API key. The format is implementation-defined; the reference implementation 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`.
     OAuth2:
       type: oauth2
-      description: 'RFC 0200 §F. OAuth 2.0 lanes — v1 `openwop-auth-oauth2-client-credentials`,
-
-        v2 `auth.lanes[].lane: "oauth2"`. Discovery is RFC 9728 Protected Resource
-
-        Metadata at the path-inserted well-known URI (`identity.md` §2.5).
-
-        Placeholder URLs.
-
-        '
+      description: 'The OAuth 2.0 lane (`auth.lanes[].lane: "oauth2"`). Discovery is RFC 9728 Protected Resource Metadata
+        at the path-inserted well-known URI (`identity.md` §2.5). The URLs are placeholders.'
       flows:
         clientCredentials:
           tokenUrl: https://issuer.example/oauth2/token
@@ -1328,26 +1285,14 @@ components:
     OpenIdConnect:
       type: openIdConnect
       openIdConnectUrl: https://issuer.example/.well-known/openid-configuration
-      description: 'RFC 0200 §F. v1 `openwop-auth-oidc-user-bearer` / v2 `auth.lanes[].lane: "oidc"`.
-
-        An ID token MAY be the bearer only when its `aud` equals the host''s configured
-
-        audience (`identity.md` §2.1); any other `aud` is `audience_mismatch`.
-
-        Placeholder URL.
-
-        '
+      description: 'The OpenID Connect lane (`auth.lanes[].lane: "oidc"`). An ID token MAY be the bearer only when its `aud`
+        equals the host''s configured audience (`identity.md` §2.1); any other `aud` is `audience_mismatch`. The URL is a
+        placeholder.'
     MutualTLS:
       type: mutualTLS
-      description: 'RFC 0200 §F. v1 `openwop-auth-mtls` / v2 `auth.lanes[].lane: "mtls"`. In OpenWOP
-
-        mTLS is required *in addition to* a bearer, never instead of one, so it appears
-
-        in no canonical requirement below: a host that requires it adds `MutualTLS: []`
-
-        inside each requirement object (AND).
-
-        '
+      description: 'The mTLS lane (`auth.lanes[].lane: "mtls"`). mTLS is required *in addition to* a bearer, never instead
+        of one, so it appears in no canonical requirement below. A host that requires it adds `MutualTLS: []` inside each
+        requirement object (AND).'
   parameters:
     IdempotencyKey:
       in: header
@@ -1356,15 +1301,8 @@ components:
       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`.
-
-        '
+      description: 'Per-mutation idempotency token (`idempotency.md` Layer 1). The server caches `(tenantId, endpoint, key)`
+        → response for ≥24h. A duplicate request returns the cached response with `OpenWOP-Idempotent-Replay: true`.'
     WorkspacePath:
       in: path
       name: path
@@ -1372,13 +1310,8 @@ components:
       schema:
         type: string
         pattern: ^[A-Za-z0-9][A-Za-z0-9._/-]{0,255}$
-      description: 'RFC 0059 workspace-relative file path. Flat namespace with
-
-        `/`-in-names; no `..`, no leading `/`. Matches
-
-        `workspace-file.schema.json#path`.
-
-        '
+      description: Workspace-relative file path in a flat namespace that allows `/` in names; no `..` and no leading `/`.
+        Matches `workspace-file.schema.json#path`.
     WorkspacePrefix:
       in: query
       name: prefix
@@ -1386,7 +1319,7 @@ components:
       schema:
         type: string
         maxLength: 256
-      description: RFC 0059. Optional prefix filter over the flat `path` namespace for `listWorkspaceFiles`.
+      description: Optional prefix filter over the flat `path` namespace for `listWorkspaceFiles`.
     WorkspaceVersion:
       in: query
       name: version
@@ -1394,11 +1327,8 @@ components:
       schema:
         type: integer
         minimum: 1
-      description: 'RFC 0059. When `capabilities.workspace.versioned: true`, request the
-
-        historical snapshot at this version. Absent = latest.
-
-        '
+      description: 'When `capabilities.workspace.versioned: true`, requests the historical snapshot at this version. Absent
+        means latest.'
     IfMatch:
       in: header
       name: If-Match
@@ -1406,11 +1336,8 @@ components:
       schema:
         type: string
         maxLength: 255
-      description: 'RFC 0059 optimistic-concurrency token — the file''s current `etag`.
-
-        A `PUT` carrying a stale `If-Match` returns `409 workspace_conflict`.
-
-        '
+      description: 'Optimistic-concurrency token: the file''s current `etag`. A `PUT` carrying a stale `If-Match` returns
+        `409 workspace_conflict`.'
     PackName:
       in: path
       name: name
@@ -1433,8 +1360,8 @@ components:
       description: Missing or invalid credential.
       headers:
         WWW-Authenticate:
-          description: RFC 0200 §B — `Bearer` challenge; `resource_metadata` and `error="invalid_token"` on a host with an
-            oauth2/oidc lane. Never on a non-disclosure 404.
+          description: A `Bearer` challenge. On a host with an oauth2 or oidc lane it carries `resource_metadata` and `error="invalid_token"`.
+            Never sent on a non-disclosure 404.
           schema:
             type: string
       content:
@@ -1445,8 +1372,8 @@ components:
       description: Credential valid but lacks required scope or fails resource binding.
       headers:
         WWW-Authenticate:
-          description: RFC 0200 §B — `error="insufficient_scope"` with every required `scope` on a scope refusal; absent on
-            a resource-binding 403.
+          description: On a scope refusal, `error="insufficient_scope"` with every required `scope`. Absent on a resource-binding
+            403.
           schema:
             type: string
       content:
@@ -1469,13 +1396,8 @@ components:
     Error:
       $ref: ../schemas/v2/error-envelope.schema.json
     TestPackPublishRecord:
-      description: 'Response body for a successful publish against the test-mode
-
-        registry namespace (RFC 0025). Mirror of the production publish
-
+      description: Response body for a successful publish to the test-mode registry namespace. Mirrors the production publish
         record returned by `PUT /v1/packs/{name}/-/{version}.tgz`.
-
-        '
       type: object
       required:
       - name