@giveitsmaller/contracts 0.42.0 → 0.43.0

package/openapi/api.yaml

@@ -89,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.123.0
+  version: 2.124.0
   contact:
     name: API Support
 
@@ -10971,6 +10971,287 @@ components:
             and its presence from either source. Per ticket
             [`kybXQe2S`](https://trello.com/c/kybXQe2S).
           $ref: '#/components/schemas/ImageEncodeCapabilities'
+        capabilities:
+          type: object
+          description: |
+            Tier-scoped operation-capability matrix (the
+            [operation-capability constraint model](../operation-capabilities/operation-capabilities.json),
+            ADR-0024) — per operation type: `accepts` (media classes),
+            `produces`, `availability`, `sole_op`, and the three
+            constraint families (`excludes` / `requires` /
+            `option_conflicts`). Consumers use it to pre-validate
+            operation composition (compatibility, ordering, output
+            propagation) without hardcoding pairwise rules.
+
+            **Per-op `input` block is intentionally NOT typed here**
+            (out of scope — a separate API follow-up). Each
+            `OperationCapability` is therefore left OPEN: the runtime
+            MAY include `input` (and future capability fields) untyped,
+            and consumers MUST tolerate them.
+
+            **Optional in the wire envelope** (same incremental-mirroring
+            stance as `endpoints` / `workflow_features` /
+            `image_encode_capabilities`): the runtime
+            `GET /api/operations/schema` emits it (API ticket
+            `uneE8Yoz`); the committed sidecar MAY mirror it once the
+            generator catches up. Consumers MUST tolerate its absence
+            and its presence from either source. Per ticket
+            [`9E3oqGNK`](https://trello.com/c/9E3oqGNK).
+          additionalProperties:
+            $ref: '#/components/schemas/OperationCapability'
+        output_properties:
+          type: object
+          description: |
+            Output-format property table (`output_format` → media facts)
+            backing the capability model's forward output-propagation:
+            `hasAudioTrack` (does this format carry an audio stream) and
+            `isAnimated` (single-frame vs animated; `"maybe"` for formats
+            that can be either, e.g. GIF/WebP). Consumers use it to reason
+            about what a chained operation's output can feed downstream.
+
+            **Tier-invariant** — a fixed codec fact, not an entitlement
+            (carries no `availability`).
+
+            **Optional in the wire envelope** (same incremental-mirroring
+            stance as the sibling blocks above). Per ticket
+            [`9E3oqGNK`](https://trello.com/c/9E3oqGNK).
+          additionalProperties:
+            $ref: '#/components/schemas/OutputProperties'
+
+    OperationCapability:
+      type: object
+      description: |
+        One operation type's capability entry in the `capabilities`
+        matrix (ADR-0024 operation-capability constraint model). The
+        object is deliberately OPEN (no `additionalProperties: false`):
+        the per-op `input` block is out of scope for this typing pass
+        (a separate API follow-up) and rides through untyped, as do any
+        future capability fields. Consumers MUST tolerate extra keys.
+      properties:
+        accepts:
+          type: array
+          description: |
+            Media classes this operation accepts as input (e.g.
+            `image`, `video`, `audio`, `document`, or `*` for
+            media-agnostic). Coarse media-class tokens, not MIME types —
+            per-MIME applicability lives in `operations.*.mime_groups`.
+          items:
+            type: string
+        availability:
+          $ref: '#/components/schemas/AvailabilityValue'
+        sole_op:
+          type: boolean
+          description: |
+            True when the operation must be the only operation in its job
+            (bypasses chain validation; ADR-0025). False/absent ⇒ chainable.
+        produces:
+          $ref: '#/components/schemas/CapabilityProduces'
+        excludes:
+          type: array
+          description: |
+            Hard-incompatibility constraints — when the `when` condition
+            holds the operation/option combination is rejected with the
+            constraint's `wire_code`.
+          items:
+            $ref: '#/components/schemas/CapabilityConstraint'
+        requires:
+          type: array
+          description: |
+            Co-requirement constraints — when `when` holds, the
+            `requires_field` MUST be present (else `wire_code`,
+            typically `invalid_options`).
+          items:
+            $ref: '#/components/schemas/CapabilityConstraint'
+        option_conflicts:
+          type: array
+          description: |
+            Mutually-exclusive option constraints within the operation.
+          items:
+            $ref: '#/components/schemas/CapabilityConstraint'
+
+    CapabilityProduces:
+      description: |
+        How an operation derives its output media type, for forward
+        output-propagation through a chain. Exactly one form:
+        - `same_as_input: true` — output mirrors the input format
+          (e.g. watermark, passthrough).
+        - `from_option: <option>` — output format is taken from the
+          named option's resolved value (e.g. `output_format`,
+          `output_type`, `format`).
+        - `fixed: <format>` — output is always this concrete format
+          (e.g. `audio_to_video` always produces `mp4`).
+      oneOf:
+        - type: object
+          additionalProperties: false
+          required: [same_as_input]
+          properties:
+            same_as_input:
+              type: boolean
+              enum: [true]
+        - type: object
+          additionalProperties: false
+          required: [from_option]
+          properties:
+            from_option:
+              type: string
+        - type: object
+          additionalProperties: false
+          required: [fixed]
+          properties:
+            fixed:
+              type: string
+
+    CapabilityConstraint:
+      type: object
+      description: |
+        A single capability constraint (member of `excludes` /
+        `requires` / `option_conflicts`). The `when` condition is
+        evaluated against the resolved operation + sibling-operation
+        context; when it holds, the constraint fires.
+      required:
+        - constraint_id
+        - message
+        - wire_code
+        - when
+      properties:
+        constraint_id:
+          type: string
+          description: Stable identifier for the constraint (for logs / docs / tests).
+        message:
+          type: string
+          description: |
+            Human-readable rejection message. MAY contain `{placeholder}`
+            tokens (e.g. `{output_format}`) the API interpolates at
+            evaluation time.
+        wire_code:
+          type: string
+          description: |
+            Error code emitted when the constraint fires. Aligns with the
+            error envelope `error_code` vocabulary.
+          enum:
+            - feature_not_available
+            - invalid_options
+            - INVALID_OPERATION_ORDER
+            - OPERATION_NOT_VALID_FOR_OUTPUT
+        when:
+          $ref: '#/components/schemas/CapabilityCondition'
+        availability:
+          $ref: '#/components/schemas/AvailabilityValue'
+        eval_scope:
+          type: string
+          description: |
+            Where the constraint is evaluated. `api` marks constraints the
+            API create-path enforces (vs purely-advisory ones consumers
+            mirror for UX). Absent ⇒ unscoped/advisory.
+          enum: [api]
+        requires_field:
+          type: string
+          description: |
+            Only on `requires` constraints — the field path that must be
+            present when `when` holds (e.g. `compress.target_size_bytes`).
+
+    CapabilityCondition:
+      description: |
+        Recursive condition node (the `Cond` field-token model, ADR-0024
+        §2). Exactly ONE form per node — a boolean combinator (`all` /
+        `any` / `not`) OR a single leaf test. A leaf tests one `field`
+        token with exactly one operator (`equals` / `in` / `isSet`),
+        except `opSelected` which is a standalone leaf asserting a
+        sibling operation of that type is present in the job. Consumers
+        compute field tokens locally from the resolved request (no new
+        wire field). Modelled as a `oneOf` of the valid forms (each
+        `additionalProperties: false`) so the grammar is enforced rather
+        than advertised as a loose bag of optional keys.
+      oneOf:
+        - type: object
+          additionalProperties: false
+          required: [all]
+          properties:
+            all:
+              type: array
+              description: All sub-conditions must hold (logical AND).
+              items:
+                $ref: '#/components/schemas/CapabilityCondition'
+        - type: object
+          additionalProperties: false
+          required: [any]
+          properties:
+            any:
+              type: array
+              description: At least one sub-condition must hold (logical OR).
+              items:
+                $ref: '#/components/schemas/CapabilityCondition'
+        - type: object
+          additionalProperties: false
+          required: [not]
+          properties:
+            not:
+              $ref: '#/components/schemas/CapabilityCondition'
+        - type: object
+          additionalProperties: false
+          required: [field, equals]
+          properties:
+            field:
+              type: string
+              description: Field token under test (e.g. `output_format`, `compress.encoding_mode`).
+            equals:
+              description: Leaf test — `field` equals this value (string or boolean).
+        - type: object
+          additionalProperties: false
+          required: [field, in]
+          properties:
+            field:
+              type: string
+              description: Field token under test.
+            in:
+              type: array
+              description: Leaf test — `field` is one of these values.
+              items: {}
+        - type: object
+          additionalProperties: false
+          required: [field, isSet]
+          properties:
+            field:
+              type: string
+              description: Field token under test.
+            isSet:
+              type: boolean
+              enum: [true]
+              description: |
+                Leaf test — asserts `field` is present/set. Only the
+                positive form is used; negate via a wrapping `not` node.
+        - type: object
+          additionalProperties: false
+          required: [opSelected]
+          properties:
+            opSelected:
+              type: string
+              description: |
+                Standalone leaf — true when a sibling operation of this
+                type is selected in the same job (e.g. `compress`,
+                `convert`).
+
+    OutputProperties:
+      type: object
+      description: |
+        Media facts for one output format, backing forward
+        output-propagation in the capability model.
+      required:
+        - hasAudioTrack
+        - isAnimated
+      properties:
+        hasAudioTrack:
+          type: boolean
+          description: Whether this format carries an audio stream.
+        isAnimated:
+          description: |
+            Whether output of this format is animated. `true` / `false`
+            for formats that are always one or the other; `"maybe"` for
+            formats that can be either (e.g. GIF, WebP).
+          oneOf:
+            - type: boolean
+            - type: string
+              enum: [maybe]
 
     EndpointProjection:
       type: object

package/operation-capabilities/operation-capabilities.json

@@ -515,5 +515,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.123.0"
+  "schema_version": "2.124.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "MIT",
   "type": "module",