@openwop/spec-artifacts 2.0.0-rc.0

package/api/redocly.yaml

@@ -0,0 +1,23 @@
+extends:
+  - recommended
+
+rules:
+  # Discovery endpoints (`/.well-known/openwop`, `/v1/openapi.json`) are unauthenticated
+  # and take no input — they have no meaningful 4XX response surface. 5XX is the
+  # only honest failure mode and is documented inline.
+  operation-4xx-response: off
+
+  # The rule flags `then: { required: [<name>] }` clauses where <name> is not
+  # defined in the `then` clause's OWN `properties` block — but in the standard
+  # JSON Schema 2020-12 `if/then` conditional-requirement idiom (used by
+  # `capabilities.schema.json` to tighten required-fields when `supported: true`),
+  # the property IS defined in the parent's `properties` block. Redocly's rule
+  # doesn't walk to parent scope, so it false-positives on every valid use of
+  # the idiom. Disabling globally is safe because:
+  #
+  #   - the typo-in-required protection the rule provides is also covered by
+  #     `scripts/check-required-properties-defined.mjs` (which walks parent
+  #     scope correctly), wired into `openwop-check.sh` step [4/9] (was cited as [7/9] until RFC 0178 §E.3 corrected it);
+  #   - our only `then/required` sites are the two in `capabilities.schema.json`,
+  #     both of which are well-formed.
+  no-required-schema-properties-undefined: off

package/api/seams-v2.yaml

@@ -0,0 +1,680 @@
+openapi: 3.1.0
+info:
+  title: OpenWOP conformance seams profile (openwop-conformance-seams-v2)
+  version: 2.0.0-rc.0
+  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 remaining host-sample-test-seams.md paths enter with
+    the 2.0.0 suite driver (P3-E).'
+servers:
+- url: https://{host}
+  description: openwop-compliant server
+  variables:
+    host:
+      default: api.example.com
+      description: Replace with your server's hostname.
+paths:
+  /conformance/seams/sample/a2a/tasks/{taskId}:
+    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`.
+
+        '
+      operationId: getA2ATaskState
+      parameters:
+      - name: taskId
+        in: path
+        required: true
+        schema:
+          type: string
+          minLength: 1
+        description: The A2A Task.id (equals the backing OpenWOP runId).
+      responses:
+        '200':
+          description: The persisted durable A2A task projection.
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/a2a-task-state.schema.json
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '501':
+          description: Host does not advertise capabilities.a2a.durableTasks (RFC 0100).
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+  /conformance/seams/workspace/files:
+    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.
+
+        '
+      operationId: listWorkspaceFiles
+      parameters:
+      - $ref: '#/components/parameters/WorkspacePrefix'
+      responses:
+        '200':
+          description: Workspace file metadata (tenant·workspace-scoped; bodies omitted).
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                - files
+                properties:
+                  files:
+                    type: array
+                    items:
+                      $ref: ../schemas/v2/workspace-file.schema.json
+                additionalProperties: false
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '501':
+          description: Host does not advertise capabilities.workspace.supported (RFC 0059).
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+  /conformance/seams/workspace/files/{path}:
+    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.
+
+        '
+      operationId: getWorkspaceFile
+      parameters:
+      - $ref: '#/components/parameters/WorkspacePath'
+      - $ref: '#/components/parameters/WorkspaceVersion'
+      responses:
+        '200':
+          description: The workspace file (current version, or `?version=N` when versioned).
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/workspace-file.schema.json
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '501':
+          description: Host does not advertise capabilities.workspace.supported (RFC 0059).
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+    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`.
+
+        '
+      operationId: putWorkspaceFile
+      parameters:
+      - $ref: '#/components/parameters/WorkspacePath'
+      - $ref: '#/components/parameters/IfMatch'
+      - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: ../schemas/v2/workspace-file-create.schema.json
+      responses:
+        '200':
+          description: File created or replaced. Returns the persisted WorkspaceFile.
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/workspace-file.schema.json
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '409':
+          description: Stale `If-Match` — the file changed since the supplied etag (`workspace_conflict`).
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+        '413':
+          description: Content exceeds `capabilities.workspace.maxFileBytes` (`workspace_too_large`).
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+        '501':
+          description: Host does not advertise capabilities.workspace.supported (RFC 0059).
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+    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.
+
+        '
+      operationId: deleteWorkspaceFile
+      parameters:
+      - $ref: '#/components/parameters/WorkspacePath'
+      - $ref: '#/components/parameters/IdempotencyKey'
+      responses:
+        '204':
+          description: File deleted.
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '501':
+          description: Host does not advertise capabilities.workspace.supported (RFC 0059).
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+  /conformance/seams/packs-test/{name}/-/{version}.tgz:
+    parameters:
+    - $ref: '#/components/parameters/PackName'
+    - $ref: '#/components/parameters/PackVersion'
+    put:
+      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
+
+        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).
+
+        '
+      operationId: putTestPackTarball
+      parameters:
+      - in: header
+        name: OpenWOP-Pack-Signing-Method
+        required: false
+        schema:
+          type: string
+          enum:
+          - sigstore
+          - manual
+          - none
+      - in: header
+        name: OpenWOP-Pack-Sha256
+        required: false
+        schema:
+          type: string
+          pattern: ^sha256-[A-Za-z0-9+/=]+$
+        description: Caller-asserted SHA-256 (server verifies; mismatch surfaces `pack_integrity_failure`).
+      requestBody:
+        required: true
+        description: Gzipped tarball bytes (`application/tar+gzip`, `application/gzip`, `application/x-gzip`, or `application/octet-stream`).
+        content:
+          application/gzip:
+            schema:
+              type: string
+              format: binary
+          application/x-gzip:
+            schema:
+              type: string
+              format: binary
+          application/tar+gzip:
+            schema:
+              type: string
+              format: binary
+          application/octet-stream:
+            schema:
+              type: string
+              format: binary
+      responses:
+        '200':
+          description: Idempotent re-publish — identical sha256 content already published; existing record returned.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TestPackPublishRecord'
+        '201':
+          description: New version published to the test catalog.
+          content:
+            application/json:
+              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`).
+
+            '
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          description: '`forbidden` — caller lacks `packs:publish` scope or the namespace claim.'
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+        '404':
+          description: 'Host does not advertise `capabilities.packs.testMode.supported: true`, or the test-mode env-gate is
+            unset.'
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+        '409':
+          description: '`conflict` (or `version_conflict`) — `(name, version)` already published with different content.'
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+    get:
+      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).'
+      operationId: getTestPackTarball
+      responses:
+        '200':
+          description: Tarball bytes.
+          content:
+            application/tar+gzip:
+              schema:
+                type: string
+                format: binary
+        '400':
+          description: '`invalid_pack_name` or `invalid_version` — URL params malformed.'
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          description: '`forbidden` — caller lacks `packs:read` scope.'
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+        '404':
+          description: 'Pack version not found in the test catalog (or host does not advertise `capabilities.packs.testMode.supported:
+            true`).'
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+  /conformance/seams/packs-test/{name}/-/{version}:
+    parameters:
+    - $ref: '#/components/parameters/PackName'
+    - $ref: '#/components/parameters/PackVersion'
+    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).
+
+        '
+      operationId: deleteTestPackVersion
+      responses:
+        '204':
+          description: Version successfully unpublished from the test catalog.
+        '400':
+          description: '`unpublish_window_expired`, `invalid_pack_name`, or `invalid_version`.'
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          description: '`forbidden` — caller lacks `packs:publish` scope.'
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+        '404':
+          description: Version doesn't exist in the test catalog, or host does not advertise the test-mode capability.
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+  /conformance/seams/packs-test/{name}/-/{version}.sig:
+    parameters:
+    - $ref: '#/components/parameters/PackName'
+    - $ref: '#/components/parameters/PackVersion'
+    get:
+      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).
+
+        '
+      operationId: getTestPackSignature
+      responses:
+        '200':
+          description: Signature blob.
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '302':
+          description: Redirect to a storage-backend signed URL (clients SHOULD follow).
+          headers:
+            Location:
+              schema:
+                type: string
+                format: uri
+        '400':
+          description: '`invalid_pack_name` or `invalid_version` — URL params malformed.'
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '403':
+          description: '`forbidden` — caller lacks `packs:read` scope.'
+          content:
+            application/json:
+              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`.
+
+            '
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/v2/error-envelope.schema.json
+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:
+    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`.
+
+        '
+    WorkspacePath:
+      in: path
+      name: path
+      required: true
+      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`.
+
+        '
+    WorkspacePrefix:
+      in: query
+      name: prefix
+      required: false
+      schema:
+        type: string
+        maxLength: 256
+      description: RFC 0059. Optional prefix filter over the flat `path` namespace for `listWorkspaceFiles`.
+    WorkspaceVersion:
+      in: query
+      name: version
+      required: false
+      schema:
+        type: integer
+        minimum: 1
+      description: 'RFC 0059. When `capabilities.workspace.versioned: true`, request the
+
+        historical snapshot at this version. Absent = latest.
+
+        '
+    IfMatch:
+      in: header
+      name: If-Match
+      required: false
+      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`.
+
+        '
+    PackName:
+      in: path
+      name: name
+      required: true
+      schema:
+        type: string
+        minLength: 3
+        maxLength: 214
+      description: Reverse-DNS pack name per `spec/v1/node-packs.md` §Naming (e.g. `vendor.acme.salesforce-tools`).
+    PackVersion:
+      in: path
+      name: version
+      required: true
+      schema:
+        type: string
+        pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[\w.-]+)?(?:\+[\w.-]+)?$
+      description: SemVer 2.0.0 version of the pack.
+  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'
+  schemas:
+    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
+
+        record returned by `PUT /v1/packs/{name}/-/{version}.tgz`.
+
+        '
+      type: object
+      required:
+      - name
+      - version
+      - tarballSha256
+      - publishedAt
+      properties:
+        name:
+          type: string
+          description: Reverse-DNS pack name as PUT'd.
+        version:
+          type: string
+          description: SemVer 2.0.0 version as PUT'd.
+        tarballSha256:
+          type: string
+          pattern: ^sha256-[A-Za-z0-9+/=]+$
+          description: Server-computed SHA-256 over the uploaded tarball bytes.
+        publishedAt:
+          type: string
+          format: date-time
+        signed:
+          type: boolean
+          description: Whether a sibling `.sig` signature blob was persisted.
+        signingMethod:
+          type: string
+          enum:
+          - sigstore
+          - manual
+          - none
+security:
+- ApiKeyAuth: []