@giveitsmaller/contracts 0.5.0 → 0.8.0

package/openapi/api.yaml

@@ -42,13 +42,27 @@ info:
     `message_key`. Machine-readable fields (`error`, enum values, status
     codes) stay canonical English.
 
+    - **Currently committed locales:** `en-GB` only (per ticket
+      [`4GKyuYo6`](https://trello.com/c/4GKyuYo6)). The I26 carrier
+      shape (`Accept-Language` + `Content-Language` + `Vary` headers +
+      `locale` envelope field + `message_key` + `message_params`) is
+      stable and exercised; the **catalog** of translated `message`
+      strings is en-GB-only at runtime today. Additional locales (e.g.
+      `pt-PT`) will be advertised by name when their catalogs ship —
+      the request/response carrier shape does NOT change when a new
+      locale lands. Treat unrequested locales as "machine-code +
+      `message_key` path is committed; localised `message` prose is
+      not" until this prose enumerates them by name.
     - **Request:** `Accept-Language` header per RFC 9110 §12.5.4 (q-value
       negotiation supported). The server selects the best-match locale
-      from its supported list; falls back to `en-GB` when no match.
+      from its supported list; falls back to `en-GB` when no match —
+      which, until additional catalogs land, is every non-`en-GB`
+      `Accept-Language`.
     - **Response:** `Content-Language: <locale>` echo on every localised
       response; `Vary: Accept-Language` on every response (CDN/cache
       correctness — different `Accept-Language` requests produce
-      different responses).
+      different responses). `Vary` is emitted unconditionally so the
+      header contract does not flip when a second locale ships.
     - **Fallback locale:** `en-GB` (also the canonical locale for
       `message_key` translations and English `message` prose).
     - **SDK guidance:** switch on `error` (machine code) for typed
@@ -75,7 +89,7 @@ info:
     of truth instead of hardcoding magic numbers. A runtime
     `GET /api/uploads/limits` endpoint for dynamic discovery
     (per-tier / per-environment overrides) is a deferred follow-up.
-  version: 2.15.3
+  version: 2.21.0
   contact:
     name: API Support
 
@@ -103,6 +117,14 @@ tags:
   - name: AudioWatermark
     description: Steganographic audio watermark embed and decode
 
+# Spec-root default per ADR-0016 D2: anonymous-OK unless overridden
+# per-operation. Every inbound operation declares an explicit `security:`
+# block (one of `[]`, `[{bearerAuth: []}, {sessionAuth: []}]`, or
+# `[{}, {bearerAuth: []}, {sessionAuth: []}]`) so the contract is
+# self-documenting — `[]` here protects against future endpoints that
+# accidentally inherit a stricter default.
+security: []
+
 paths:
   # ============================================
   # UPLOAD ENDPOINTS
@@ -122,6 +144,7 @@ paths:
         (10 MB). Files above this size MUST use the multipart upload flow
         instead (`POST /api/uploads/multipart/initiate`).
       operationId: uploadFile
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK; auth attribution if present)
       tags:
         - Upload
       requestBody:
@@ -321,6 +344,7 @@ paths:
 
         After all parts are uploaded to S3, call the complete endpoint to finalise.
       operationId: multipartInitiate
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-tolerant; manifest.userId pinned to caller if authed)
       tags:
         - Upload
       requestBody:
@@ -455,6 +479,8 @@ paths:
         rule and additionally refuse anonymous-initiated sessions
         outright (returning 403 `MULTIPART_SESSION_AUTH_REQUIRED`).
       operationId: multipartComplete
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-tolerant; ownership-scoped per HxUmVr3Y when manifest.userId set)
+      x-identity-scoped: true  # session/ownership-scoped per ADR-0016 D3
       tags:
         - Upload
       requestBody:
@@ -550,6 +576,8 @@ paths:
         Completion-readiness is client-derived (walk all pages, compare
         the count of returned parts to `total_parts`).
       operationId: multipartStatus
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (anon-initiated sessions rejected with MULTIPART_SESSION_AUTH_REQUIRED — see ErrorCode.authentication_required prose)
+      x-identity-scoped: true  # session/ownership-scoped per ADR-0016 D3
       tags:
         - Upload
       parameters:
@@ -674,6 +702,8 @@ paths:
         **Authentication required.** Same `MULTIPART_SESSION_*` codes
         apply as on `/status`.
       operationId: multipartPresign
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (anon-initiated sessions rejected; resume-only endpoint)
+      x-identity-scoped: true  # session/ownership-scoped per ADR-0016 D3
       tags:
         - Upload
       parameters:
@@ -793,6 +823,8 @@ paths:
         **Authentication required.** Same `MULTIPART_SESSION_*` codes
         apply as on `/status` and `/presign`.
       operationId: multipartKeepalive
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (anon-initiated sessions rejected; resume-only endpoint)
+      x-identity-scoped: true  # session/ownership-scoped per ADR-0016 D3
       tags:
         - Upload
       parameters:
@@ -868,6 +900,8 @@ paths:
         - **Audio:** duration, bitrate, channels, sample_rate, codec
         - **Documents:** page_count, dimensions (for PDF)
       operationId: getUploadMetadata
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK; identity-scoped to caller's session/identity)
+      x-identity-scoped: true  # ownership-scoped per ADR-0016 D3
       tags:
         - Upload
       parameters:
@@ -955,6 +989,8 @@ paths:
         same `probed_at` timestamp + result (cached server-side per
         upload).
       operationId: probeUpload
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set; ownership-scoped)
+      x-identity-scoped: true  # ownership-scoped per ADR-0016 D3
       tags:
         - Upload
       x-availability: planned
@@ -1173,6 +1209,8 @@ paths:
         idempotency-key wire shape for retried reservation attempts
         is deferred per ADR-0001 §1.7 row 5.
       operationId: createWorkflow
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK on free-tier baseline; auth required for tier-gated operations)
+      x-identity-scoped: true  # request body dereferences upload file_ids — cross-identity references return 403 per ADR-0016 D3 (NOTE: §D4 ADR sample showed identity_scoped: false; B3 audit flipped to true per §D3 principle — SDK-acked 2026-05-28)
       tags:
         - Workflow
       requestBody:
@@ -1656,6 +1694,8 @@ paths:
         Each operation includes its current progress and, when completed, its result
         (download URL, size, metrics).
       operationId: getWorkflowStatus
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK; identity-scoped to workflow owner)
+      x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
       tags:
         - Workflow
       parameters:
@@ -1737,6 +1777,8 @@ paths:
         Each job's operations are listed with their output files and pre-signed
         download URLs.
       operationId: getWorkflowDownloads
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK; identity-scoped to workflow owner)
+      x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
       tags:
         - Workflow
       parameters:
@@ -1839,6 +1881,8 @@ paths:
         (the `id:` and `event:` lines) is transport-level and intentionally
         **not** schema-described.
       operationId: streamWorkflowEvents
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK; identity-scoped to workflow owner)
+      x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
       tags:
         - Workflow
       parameters:
@@ -1902,6 +1946,8 @@ paths:
         cancel response is the binding "no further reservations
         will be made" signal.
       operationId: cancelWorkflow
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set)
+      x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
       tags:
         - Workflow
       parameters:
@@ -2004,6 +2050,8 @@ paths:
         a 409 (no-op — the workflow is already running, terminal,
         or cancelled).
       operationId: resumeWorkflow
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set)
+      x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
       tags:
         - Workflow
       parameters:
@@ -2125,6 +2173,7 @@ paths:
         on `OptionSchema` (ticket I17). Clients should use these to build
         dynamic forms with availability-aware UX.
       operationId: getOperationsSchema
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK returns free-tier baseline; auth tier-scopes the response)
       tags:
         - Operations
       parameters:
@@ -2150,7 +2199,7 @@ paths:
             still fresh. Strong-ETag comparison.
           schema:
             type: string
-          example: '"v2-pro-47"'
+          example: '"v2-pro-49"'
         - name: If-Modified-Since
           in: header
           required: false
@@ -2183,7 +2232,7 @@ paths:
                 Strong entity tag. Clients send `If-None-Match: <etag>`
                 on subsequent requests to revalidate; the server returns
                 `304 Not Modified` when the response is still fresh.
-              example: '"v2-pro-47"'
+              example: '"v2-pro-49"'
             Last-Modified:
               schema:
                 type: string
@@ -2201,7 +2250,7 @@ paths:
                   summary: Full schema (truncated for brevity)
                   value:
                     schema_version: "2.0.0"
-                    capabilities_version: 47
+                    capabilities_version: 49
                     generated_at: "2026-04-26T09:00:00Z"
                     user_tier: "pro"
                     operations:
@@ -2264,7 +2313,7 @@ paths:
             ETag:
               schema:
                 type: string
-              example: '"v2-pro-47"'
+              example: '"v2-pro-49"'
             Last-Modified:
               schema:
                 type: string
@@ -2287,6 +2336,8 @@ paths:
         The original failed operation is marked as `retried` and a new operation with
         a new ID is created in `pending` state.
       operationId: retryOperation
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK; identity-scoped to operation owner)
+      x-identity-scoped: true  # operation-ownership-scoped per ADR-0016 D3
       tags:
         - Operations
       parameters:
@@ -2340,6 +2391,7 @@ paths:
       summary: Liveness probe
       description: Kubernetes liveness probe endpoint
       operationId: liveness
+      security: []  # anonymous (k8s probe — auth irrelevant)
       tags:
         - Health
       responses:
@@ -2357,6 +2409,7 @@ paths:
       summary: Readiness probe
       description: Kubernetes readiness probe endpoint - checks database and cache connectivity
       operationId: readiness
+      security: []  # anonymous (k8s probe — auth irrelevant)
       tags:
         - Health
       responses:
@@ -2393,6 +2446,7 @@ paths:
           - `429` — infrastructure rate-limit (too many attempts in the current
             window). Distinct from `account_locked`, which is persisted state.
       operationId: loginUser
+      security: []  # anonymous (entry point — you're logging in, no creds yet)
       tags:
         - Auth
       requestBody:
@@ -2580,6 +2634,8 @@ paths:
         endpoint since `AuthController.php:19-22`; this declaration
         catches the contract up).
       operationId: logoutUser
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (logout requires an authenticated principal to invalidate)
+      x-identity-scoped: true  # identity-bound (caller's own session) per ADR-0016 D3 — by symmetry with credits/balance per §D4 sample
       tags:
         - Auth
       responses:
@@ -2674,6 +2730,14 @@ paths:
         per ADR-0001 §1.3); the runtime endpoint returns `404` until
         cross-repo wiring lands.
       operationId: createExternalImport
+      # Auth: REQUIRED defensively. Endpoint is availability:planned (no
+      # controller yet); but the endpoint stores encrypted server-side
+      # secrets (bearer URLs, passwords) and anon-callable secret
+      # storage is almost certainly wrong. Locking the contract here
+      # while we still own the source of truth; runtime tightens to
+      # match when the controller lands. Per ADR-0016 / karen review
+      # on yN309QVb-B2.
+      security: [{bearerAuth: []}, {sessionAuth: []}]
       x-availability: planned
       tags:
         - Upload
@@ -2780,6 +2844,7 @@ paths:
         `feature_not_available` (422) until the Lambda lands. Per
         Tension 1 (ADR-0001 §1.3).
       operationId: decodeAudioWatermark
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set; tier-gated runtime call)
       tags:
         - AudioWatermark
       x-availability: planned
@@ -2877,6 +2942,8 @@ paths:
         SDKs gate UI on `available_credits` for the spend-now affordance
         and on `tier` for tier-upgrade prompts.
       operationId: getCreditsBalance
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (identity-scoped to caller's wallet)
+      x-identity-scoped: true  # caller's wallet — per ADR-0016 §D4 sample
       tags:
         - Billing
       responses:
@@ -2956,13 +3023,18 @@ paths:
 
         Default page is 20 transactions, ordered most-recent-first.
       operationId: getCreditsUsage
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (identity-scoped to caller's usage history)
+      x-identity-scoped: true  # caller's usage history — per ADR-0016 D3
       tags:
         - Billing
       parameters:
         - name: limit
           in: query
           required: false
-          description: Page size. Server may reject larger values with 400.
+          description: |
+            Page size. Server may reject invalid `limit` / `offset`
+            with `422 VALIDATION_FAILED` (per project-wide query-param
+            validation convention).
           schema:
             type: integer
             minimum: 1
@@ -2971,7 +3043,9 @@ paths:
         - name: offset
           in: query
           required: false
-          description: Page offset (zero-based).
+          description: |
+            Page offset (zero-based). Server may reject invalid
+            `limit` / `offset` with `422 VALIDATION_FAILED`.
           schema:
             type: integer
             minimum: 0
@@ -3094,21 +3168,33 @@ paths:
                       total: 47
                       limit: 20
                       offset: 0
-        '400':
-          description: Invalid pagination parameters (limit out of range, offset negative).
+        '401':
+          description: Authentication required.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
-              example:
-                success: false
-                error: "limit must be between 1 and 100"
-        '401':
-          description: Authentication required.
+        '422':
+          description: |
+            Invalid pagination parameters (`limit` out of range,
+            `offset` negative). Per the project-wide query-param
+            validation convention: the API runtime translates parameter
+            constraint violations into `ValidationErrorEnvelope` with
+            `error: "VALIDATION_FAILED"` and structured `details[]`
+            describing each rejected parameter. Replaces the prior
+            `400 ErrorEnvelope` shape — wire change landed via
+            [`gCfdFhdo`](https://trello.com/c/gCfdFhdo) on the API side
+            (contracts caught up via [`d4rJzTcU`](https://trello.com/c/d4rJzTcU)).
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ErrorEnvelope'
+                $ref: '#/components/schemas/ValidationErrorEnvelope'
+              example:
+                success: false
+                error: "VALIDATION_FAILED"
+                details:
+                  - field: "limit"
+                    message: "limit must be between 1 and 100"
         '429':
           description: Rate limit exceeded
           content:
@@ -3139,6 +3225,7 @@ paths:
         On success, returns 204 with no body. The API sends the message via its
         configured delivery channel (e.g. email, queue).
       operationId: submitContact
+      security: []  # anonymous (public contact form)
       tags:
         - Contact
       requestBody:
@@ -3225,6 +3312,38 @@ webhooks:
           description: Callback acknowledged (no body)
 
 components:
+  # Per ADR-0016: auth presence is modeled with OpenAPI-native
+  # `security` / `securitySchemes` (NOT a custom `auth:` field) so codegen,
+  # spectral, and oasdiff understand it natively. Two schemes — the same
+  # Symfony `api` firewall accepts BOTH a bearer API-key and a login-session
+  # cookie. Per-operation `security:` blocks OR the two schemes for the
+  # three idioms (anonymous / required / optional). Spec root carries
+  # `security: []` default (anonymous-OK); per-operation overrides flip
+  # the requirement.
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      description: |
+        API-key bearer authentication. The `ApiKeyAuthenticator`
+        (Symfony `api` firewall) validates
+        `Authorization: Bearer <api-key>` per the prose under
+        `ErrorCode.authentication_required`.
+    sessionAuth:
+      type: apiKey
+      in: cookie
+      name: PHPSESSID
+      description: |
+        Login-session cookie authentication. The `ApiEntryPoint`
+        (Symfony `api` firewall) recognises an authenticated session
+        when the cookie is present and the session has a valid
+        principal. Set by `POST /api/auth/login`; cleared by
+        `POST /api/auth/logout`. Cookie name `PHPSESSID` follows the
+        Symfony / PHP default — no `framework.session.name` override
+        in `compression/config/packages/framework.yaml` as of v2.16.6
+        verification. Update this declaration if the API repo ever
+        adds a `session.name` override.
+
   schemas:
     # ============================================
     # SHARED PRIMITIVES
@@ -3332,10 +3451,13 @@ components:
           type: string
           description: |
             BCP 47 locale tag echoing the resolved `Content-Language`
-            response header value (e.g. `en-GB`, `pt-BR`, `ja-JP`).
-            Lets the SDK confirm which locale the server selected
-            when the request used q-value negotiation across multiple
-            `Accept-Language` values.
+            response header value. Currently always `en-GB` (the only
+            committed locale per `info.description` Localisation block
+            + ticket [`4GKyuYo6`](https://trello.com/c/4GKyuYo6));
+            additional values will appear here when their catalogs
+            ship. Lets the SDK confirm which locale the server
+            selected when the request used q-value negotiation across
+            multiple `Accept-Language` values.
           example: "en-GB"
         message_params:
           type: object
@@ -3379,7 +3501,10 @@ components:
             (generic option/value validation failure), `REQUIRES_REENCODE`
             (per ticket I16-CONS — `merge.video` with
             `re_encode_mode: never` and incompatible inputs; caller
-            resolves by switching to `re_encode_mode: auto` or `always`).
+            resolves by switching to `re_encode_mode: auto` or `always`),
+            `VALIDATION_FAILED` (request/query-param validation failure
+            per the project-wide convention — e.g. `GET /api/v2/credits/usage`
+            invalid `limit`/`offset`).
             SDKs duck-type on this field for typed error-branch helpers.
         message:
           type: string
@@ -3450,6 +3575,26 @@ components:
                   `ErrorEnvelope.message_params`. Excludes cost
                   numbers.
 
+    ReEncodeDecision:
+      type: string
+      description: |
+        Path chosen for `merge.video` when `re_encode_mode=auto`.
+        Server reports the actual path so callers can see why
+        `auto` took the slow path. Absent for non-`merge.video`
+        operations and for `merge.video` when `re_encode_mode` is
+        `always` or `never` (path was caller-fixed). Per ticket
+        I16-CONS (Trello 7nCZXEru).
+
+        Mirrors the AsyncAPI `ReEncodeDecision` (and
+        `OperationMetrics.re_encode_decision`); exposed on the REST
+        `OperationResult.metrics` per ticket zS4e9CI2 so the SDK
+        customer path carries the same signal as the SSE/message
+        surface. Cross-spec enum parity is verified by
+        `tests/test_asyncapi_named_schemas.py`.
+      enum:
+        - stream_copy
+        - re_encode
+
     # ============================================
     # AVAILABILITY METADATA (decorative)
     # ============================================
@@ -6543,8 +6688,19 @@ components:
             - explicit
           per_value_availability:
             terminal:    { availability: stable }
-            all_outputs: { availability: beta }
-            explicit:    { availability: beta }
+            all_outputs: { availability: planned }
+            explicit:    { availability: planned }
+          # Availability flipped beta → planned per ticket
+          # [`co0CERtJ`](https://trello.com/c/co0CERtJ) — the API
+          # runtime currently 422s every non-default `selection.type`
+          # with `feature_not_available`, which per the
+          # `info.description` availability taxonomy IS the `planned`
+          # behaviour (`stable`/`beta` MUST NOT 422). When the API
+          # threads the request-level `delivery.selection` shape, this
+          # flips back. Terminal stays `stable` because the runtime
+          # honours it as the implicit default (`DeliveryPlanComputer`
+          # computes terminal selection regardless of whether the
+          # caller supplied a `delivery` block).
         refs:
           type: array
           description: |
@@ -6571,7 +6727,20 @@ components:
       properties:
         mode:
           type: string
-          description: Delivery mode.
+          description: |
+            Delivery mode. `individual` is the only committed value
+            today (per ticket [`co0CERtJ`](https://trello.com/c/co0CERtJ)).
+            `bundle` and `both` are `planned`: the API runtime returns
+            `422 feature_not_available` for any non-`individual` value,
+            which per the `info.description` availability taxonomy is
+            the `planned` behaviour (`stable`/`beta` MUST NOT 422).
+
+            For workflows that need a packaged output today, compose
+            a terminal `archive` job whose `sources` are
+            `JobOutputSource` refs to the upstream jobs — `archive` is
+            the canonical output-bundler per ADR-0017. `delivery.mode:
+            bundle` is the deferred post-launch ergonomic sugar that
+            will reuse the same `archive` runtime under the hood.
           enum:
             - individual
             - bundle
@@ -6579,8 +6748,8 @@ components:
           default: individual
           per_value_availability:
             individual: { availability: stable }
-            bundle:     { availability: stable }
-            both:       { availability: beta }
+            bundle:     { availability: planned }
+            both:       { availability: planned }
         bundle_format:
           type: string
           enum:
@@ -6611,6 +6780,11 @@ components:
           description: |
             How to pick outputs. Default `terminal` (leaves only).
       example:
+        # Spec example uses `bundle` to document the deferred (planned)
+        # shape end-to-end — see Delivery.mode per_value_availability
+        # for the runtime state. For workflows that need packaged
+        # output today, compose a terminal `archive` job whose
+        # `sources` are `JobOutputSource` refs (ADR-0017).
         mode: bundle
         bundle_format: zip
         bundle_filename: "compressed-photos"
@@ -6980,12 +7154,22 @@ components:
           description: Container-reported duration (audio + video).
         width:
           type: integer
+          format: int64
           minimum: 1
-          description: Pixel width (image + video; best-effort document).
+          description: |
+            Pixel width (image + video; best-effort document). Declared
+            `int64` so Rust SDK generators emit `i64` instead of the
+            default `i32`; `i32` is fine for everything ffmpeg/libcaesium
+            handles today but the format hint keeps the door open for
+            scientific / RAW imagery without future SDK churn (per
+            ticket [`0sTmbUsc`](https://trello.com/c/0sTmbUsc)).
         height:
           type: integer
+          format: int64
           minimum: 1
-          description: Pixel height (image + video; best-effort document).
+          description: |
+            Pixel height (image + video; best-effort document). See
+            `width` for the `format: int64` rationale.
         codec:
           type: string
           description: |
@@ -7020,12 +7204,16 @@ components:
             `29.97`, `23.976`).
         bitrate_bps:
           type: integer
+          format: int64
           minimum: 0
           description: |
             Overall stream bitrate, **bits per second**. Units in
             the field name, mirroring `duration_seconds`, so SDKs
             avoid the kbps-vs-bps guessing trap. Container-reported
-            for video + audio.
+            for video + audio. Declared `int64` so Rust SDK
+            generators emit `i64` instead of `i32`; `i32` caps at
+            ~2.1 Gbps which is tight for future 4K/8K/RAW workloads
+            (per ticket [`0sTmbUsc`](https://trello.com/c/0sTmbUsc)).
         audio_layout:
           type: string
           description: |
@@ -7486,6 +7674,21 @@ components:
             duration_ms:
               type: integer
               description: Processing time in milliseconds
+            re_encode_decision:
+              # Mirrors AsyncAPI OperationMetrics.re_encode_decision so the
+              # REST result surface (SDK customer path) carries the same
+              # merge.video stream-copy-vs-re-encode signal as the SSE/message
+              # channel. Per ticket zS4e9CI2 (unblocks e2e aDFI1FgT).
+              $ref: '#/components/schemas/ReEncodeDecision'
+            re_encode_reason:
+              type: string
+              description: |
+                Advisory explanation for `re_encode_decision` (e.g.
+                `all_inputs_compatible`, `explicit_always_mode`,
+                `input_codec_mismatch`, `input_framerate_mismatch`).
+                Free-form string — not an enum — so the Lambda can emit
+                human-readable diagnostics that evolve without contract
+                changes. Mirrors `OperationMetrics.re_encode_reason`.
 
     # ============================================
     # WORKFLOW DOWNLOAD SCHEMAS
@@ -7752,6 +7955,63 @@ components:
         discriminator-based dispatch reads the snake_case wire key directly
         (`switch (json['result_kind'])`), avoiding the case-mismatch bug
         entirely.
+
+        **v2.16.1 attempted PHP-template fix (superseded by v2.16.5).**
+        The v2.16.1 cut introduced the shared `SseCompletionBase`
+        schema declaring `result_kind: { enum: [single, multi] }` (both
+        literal values together) and had the branch wrappers
+        allOf-merge it. The intent was to fix the v2.15.3 design where
+        `result_kind` was declared only as `enum: [single]` /
+        `enum: [multi]` inside each branch's inline `allOf` block —
+        which made the openapi-generator PHP template flatten only one
+        branch's enum into `getResultKindAllowableValues()`. The
+        v2.16.1 verification at the time confirmed PHP emitted both
+        values, but against the v2.15.3-generated tree, not against a
+        fresh v2.16.1 regen. SDKs later caught (via codex on the
+        v2.16.3 regen, surfaced by ChSmslxj) that v2.16.1's shared-base
+        fix did NOT actually propagate through the PHP template — the
+        template visits each oneOf branch's allOf and only flattens the
+        per-branch single-value enum, NOT the shared base's full-union
+        enum. PHP root model still emitted `RESULT_KIND_MULTI` only
+        (the second branch's value). SseCompletionBase is RETAINED in
+        v2.16.5 for documentation + JSON Schema branch identification
+        + consumers that traverse the allOf chain, but on its own it
+        is NOT load-bearing for PHP correctness.
+
+        **v2.16.5 ChSmslxj PHP-template fix (load-bearing).**
+        Declares `result_kind` with the full `enum: [single, multi]`
+        directly on the ROOT `SseOperationCompletionResult` schema as
+        a sibling of `oneOf` and `discriminator` (with `type: object`
+        + `required: [result_kind]`). The openapi-generator PHP
+        template flattens this root enum cleanly into
+        `getResultKindAllowableValues()`, emitting both
+        `RESULT_KIND_SINGLE` and `RESULT_KIND_MULTI`. The triple
+        declaration (root + SseCompletionBase + per-branch wrappers)
+        is harmless redundancy: the root carries the full union for
+        the PHP template; SseCompletionBase carries the full union
+        for allOf-chain consumers; per-branch wrappers pin to a
+        single literal value for OpenAPI discriminator semantics +
+        JSON Schema branch identification. TypeScript dispatch is
+        unchanged (`switch (json['result_kind'])` reads the
+        snake_case wire key directly — verified on openapi-generator-
+        cli v7.21.0).
+      type: object
+      required:
+        - result_kind
+      properties:
+        result_kind:
+          type: string
+          enum: [single, multi]
+          description: |
+            Discriminator field. The full `[single, multi]` enum is
+            declared directly on the root (this object) so the
+            openapi-generator PHP template flattens both literal
+            values into `getResultKindAllowableValues()` per
+            ChSmslxj. Also declared on the shared `SseCompletionBase`
+            (retained for consumers that traverse the allOf chain)
+            and on each per-branch wrapper (single-value enum pinning
+            the branch). The triple declaration is harmless redundancy
+            necessary for PHP template flattening.
       oneOf:
         - $ref: '#/components/schemas/SseSingleOutputCompletion'
         - $ref: '#/components/schemas/SseMultiOutputCompletionWithKind'
@@ -7761,46 +8021,71 @@ components:
           single: '#/components/schemas/SseSingleOutputCompletion'
           multi: '#/components/schemas/SseMultiOutputCompletionWithKind'
 
+    SseCompletionBase:
+      type: object
+      description: |
+        Shared base schema for the two `SseOperationCompletionResult`
+        branches. Declares the `result_kind` discriminator field as a
+        `[single, multi]` enum with both literal values, then each branch
+        wrapper allOf-merges this base + its body schema.
+
+        **Rationale (v2.16.1):** the v2.15.3 design declared `result_kind`
+        as a single-value `enum [single]` / `enum [multi]` inside each
+        branch's inline `allOf` block. The openapi-generator PHP template
+        for this shape flattens only the FIRST branch's discriminator enum
+        into the root `getResultKindAllowableValues()` list, so PHP
+        deserialisation rejects the other branch's wire value as invalid.
+        Promoting `result_kind` to a shared base with the full union
+        `enum [single, multi]` makes PHP accept both values; the
+        per-branch `enum [single]` / `enum [multi]` (kept on the wrappers
+        for JSON Schema-level branch identification + OpenAPI
+        discriminator semantics) does not regress. TypeScript dispatch
+        continues to use `switch (json['result_kind'])` — confirmed by
+        codegen verification on openapi-generator-cli v7.21.0.
+      required:
+        - result_kind
+      properties:
+        result_kind:
+          type: string
+          enum: [single, multi]
+          description: |
+            Discriminator field on `SseOperationCompletionResult`. The
+            API SSE serializer emits `"single"` for single-output
+            completion payloads and `"multi"` for multi-output payloads;
+            generated SDK dispatch routes on this value to pick the
+            correct branch deserializer.
+
     SseSingleOutputCompletion:
       description: |
         Single-output branch of `SseOperationCompletionResult` — wraps
-        `OperationResult` with a `result_kind: "single"` discriminator field
-        so the openapi-generator dispatch can route by wire-format key
-        (`result_kind`) rather than by structural property presence.
-        See `SseOperationCompletionResult` description for the rationale.
+        `OperationResult` + the shared `SseCompletionBase` + pins
+        `result_kind` to the literal `"single"`. See
+        `SseOperationCompletionResult` description for the rationale +
+        codegen-quirk context.
       allOf:
         - $ref: '#/components/schemas/OperationResult'
+        - $ref: '#/components/schemas/SseCompletionBase'
         - type: object
-          required:
-            - result_kind
           properties:
             result_kind:
               type: string
               enum: [single]
-              description: |
-                Discriminator. Always the literal `"single"` for this branch.
-                Emitted by the API SSE serializer; consumed by
-                `SseOperationCompletionResult` dispatch.
 
     SseMultiOutputCompletionWithKind:
       description: |
         Multi-output branch of `SseOperationCompletionResult` — wraps
-        `SseMultiOutputCompletion` with a `result_kind: "multi"` discriminator
-        field. See `SseOperationCompletionResult` description for the
-        rationale.
+        `SseMultiOutputCompletion` + the shared `SseCompletionBase` +
+        pins `result_kind` to the literal `"multi"`. See
+        `SseOperationCompletionResult` description for the rationale +
+        codegen-quirk context.
       allOf:
         - $ref: '#/components/schemas/SseMultiOutputCompletion'
+        - $ref: '#/components/schemas/SseCompletionBase'
         - type: object
-          required:
-            - result_kind
           properties:
             result_kind:
               type: string
               enum: [multi]
-              description: |
-                Discriminator. Always the literal `"multi"` for this branch.
-                Emitted by the API SSE serializer; consumed by
-                `SseOperationCompletionResult` dispatch.
 
     SseMultiOutputCompletion:
       type: object
@@ -8115,6 +8400,84 @@ components:
             availability metadata per I1 / I17).
           additionalProperties:
             $ref: '#/components/schemas/OperationSchemaDefinition'
+        endpoints:
+          type: object
+          description: |
+            Flat per-endpoint auth/identity projection per
+            [ADR-0016](../docs/decisions/0016-per-endpoint-auth-identity-modeling.md)
+            §D4. Keys are `<METHOD> <PATH>` literals (e.g.
+            `"POST /api/workflows"`); values declare the auth axis +
+            identity-scoping + reserved tier/availability slots +
+            operation_id for SDK ergonomic-layer consumption.
+
+            Webhook operations are EXCLUDED per ADR-0016 §D5 — outbound
+            HMAC-signed callbacks use a separate auth model.
+
+            **Optional in the wire envelope** to keep the runtime
+            endpoint's mirroring obligation incremental: the
+            committed sidecar (yN309QVb-B3 / v2.17.0+) emits this
+            block authoritatively; the runtime `GET /api/operations/
+            schema` MAY mirror it once the API team's runtime
+            generator catches up. Consumers MUST tolerate absent
+            `endpoints` from the runtime endpoint (read the sidecar
+            instead) and MUST tolerate present `endpoints` from
+            either source.
+          additionalProperties:
+            $ref: '#/components/schemas/EndpointProjection'
+
+    EndpointProjection:
+      type: object
+      description: |
+        Per-endpoint projection entry per ADR-0016 §D4. Five fields;
+        `required_tier` and `availability` at endpoint level are
+        reserved/null today (operation-level `required_tier` continues
+        to flow via `operations.*.required_tier`; every shipped
+        endpoint is currently `availability: stable`).
+      required:
+        - auth
+        - identity_scoped
+        - required_tier
+        - availability
+        - operation_id
+      properties:
+        auth:
+          type: string
+          enum: [anonymous, optional, required]
+          description: |
+            3-value projection of the operation's `security:` block:
+            `anonymous` (`security: []`), `optional` (`security`
+            contains the empty requirement `{}`), `required`
+            (otherwise).
+        identity_scoped:
+          type: boolean
+          description: |
+            Value of the `x-identity-scoped` vendor extension on the
+            operation (default `false`). True iff the operation
+            targets an identity-bound resource and cross-identity
+            access returns 403 — OR acts on the caller's implicit
+            identity-scoped data (credits balance, own session).
+        required_tier:
+          description: |
+            Endpoint-level entitlement gate. Reserved/null today —
+            operation-level `required_tier` flows via
+            `operations.*.required_tier` and is NOT duplicated here.
+          oneOf:
+            - $ref: '#/components/schemas/UserTier'
+            - type: 'null'
+        availability:
+          type: string
+          enum: [stable, beta, experimental, planned, deprecated]
+          description: |
+            Endpoint-level availability tag. Currently always
+            `"stable"` for shipped endpoints. Reserved for future
+            `planned` / `deprecated` endpoint-level annotation.
+        operation_id:
+          type: string
+          description: |
+            OpenAPI `operationId` for the operation. SDK code
+            generators anchor on this for method naming; including
+            it in the sidecar saves a round-trip to `openapi/api.yaml`.
+            Per the SDK ask at ADR-0016 B1 sign-off.
 
     OperationSchemaDefinition:
       type: object
@@ -8291,6 +8654,7 @@ components:
             - boolean
             - enum
             - string
+            - array
         description:
           type: string
           description: Human-readable description
@@ -8335,6 +8699,22 @@ components:
             by `make check-per-value-availability` (CI guard, ticket
             [I17 `0gwtwCav`](https://trello.com/c/0gwtwCav)). Runtime
             emission lands with I3.
+        per_value_depends_on:
+          type: object
+          description: |
+            Per-enum-value cross-field constraint map, only meaningful
+            when `type: enum`. Keys MUST be a subset of `values[]`;
+            each entry value is a `depends_on`-shaped condition mapping
+            that the named enum value REQUIRES. Distinct from
+            option-level `depends_on` (which gates applicability with
+            silent-ignore semantics); `per_value_depends_on` rejects
+            the request with `invalid_options` when the named value is
+            chosen and the condition is not met. Verified by
+            `make check-per-value-depends-on` (CI guard, ticket
+            [`bsV3FWM5`](https://trello.com/c/bsV3FWM5)). Runtime
+            emission ships verbatim alongside other availability
+            metadata. See `schemas/FORMAT.md` §per_value_depends_on.
+          additionalProperties: true
         min:
           type: number
           description: Minimum value (for integer/float types)