@giveitsmaller/contracts 0.61.0 → 0.62.0

package/openapi/api.yaml

@@ -89,15 +89,28 @@ 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.189.0
+  version: 2.191.0
   contact:
     name: API Support
 
+# The production host was ABSENT from this block entirely until 2026-08-11 —
+# for EVERY endpoint, not just one. That was not merely untidy: prod's SSE
+# consumer fell back to the wrong host precisely because the correct one lived
+# only in deployment config, where nothing could catch the divergence. A host
+# that exists only in an env var is a convention; a host declared here is a fact
+# every generated client picks up.
+#
+# The staging/prod asymmetry is DELIBERATE and must not be "tidied": prod sets
+# `environment_subdomain` to empty, so the domain base IS the root; staging sets
+# it to `staging`, hence the extra label. Values resolved from terraform code by
+# the terraform session, not from anyone's memory.
 servers:
   - url: http://localhost:8080
     description: Local development
   - url: https://api.staging.giveitsmaller.com
     description: Staging environment
+  - url: https://api.giveitsmaller.com
+    description: Production environment
 
 tags:
   - name: Upload
@@ -1164,9 +1177,30 @@ paths:
         NOT inline per-operation `result_metadata` or output details (avoids
         N×M×K payload blow-up). Drill in via `GET /api/workflows/{id}/status`
         (per-op detail incl. `result_metadata`) and
-        `GET /api/workflows/{id}/downloads` (deliverables). Rows persist until
-        GDPR purge — workflows whose 24h download window has expired are still
-        listed. Per ticket [`nLK1IO1k`](https://trello.com/c/nLK1IO1k) (A1).
+        `GET /api/workflows/{id}/downloads` (deliverables).
+
+        **Rows persist until GDPR purge — a workflow whose outputs have been
+        retention-purged is STILL LISTED.** So a row appearing here does not
+        imply its deliverables are still downloadable; read
+        `retention_expires_at` on the downloads response for that.
+
+        ⚠️ **This sentence used to say "whose 24h download window has expired".
+        That figure was WRONG and was the only place in this spec it appeared.**
+        The download-retention window is **per-tier — free 7 days / paid 30
+        days / enterprise custom** — computed from the workflow's `created_at`
+        and reported as `retention_expires_at` on
+        `GET /api/workflows/{id}/downloads`
+        ([`G58ei6Z9`](https://trello.com/c/G58ei6Z9)). The stale clause almost
+        certainly predates that field and nobody re-read it when the field
+        landed.
+        **It mattered because THREE clocks are involved and this was the one in
+        the casually-read place:** `bundle.expires_at` is the short-lived
+        pre-signed URL expiry (**access**), `retention_expires_at` is when the
+        deliverables are removed (**data**), and the workflow's own
+        `expires_at` is a record TTL on the paused path. **A download link
+        expiring does not mean the object is gone** — a distinction this spec
+        states correctly on `retention_expires_at` and used to contradict here.
+        Per ticket [`nLK1IO1k`](https://trello.com/c/nLK1IO1k) (A1).
       operationId: listWorkflows
       security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 — user-scoped list, no anonymous access)
       x-identity-scoped: true  # caller's own workflows — implicit identity-scoped, per ADR-0016 D3 (cf. credits/usage)
@@ -3996,6 +4030,402 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
 
+  /api/auth/account:
+    delete:
+      summary: Request deletion of the authenticated user's account
+      # THE CONTRACT IS CATCHING UP TO SHIPPED BEHAVIOUR. Every status code,
+      # error code and wire key below was read from the implementation
+      # (AccountDeletionController + its feature tests), not designed here.
+      #
+      # ⚠️ WHAT HAPPENS TO STORED OUTPUTS IS DELIBERATELY NOT DECLARED. There
+      # is a confirmed retention defect under a fleet-wide fix freeze, and a
+      # deletion GUARANTEE is the one claim this repo must not lead the
+      # implementation on: `planned` assumes the caller gets a refusal it can
+      # see, and a retention gap refuses nothing. Declaring removal before
+      # removal works would put a false claim on a privacy path. Tracked on
+      # ticket [`NSIPubON`](https://trello.com/c/NSIPubON) as a USER decision,
+      # alongside what happens to purchased credits.
+      description: |
+        Requests deletion of the caller's own account. **This is a request,
+        not an immediate deletion** — it opens a **30-day grace period**
+        during which `POST /api/auth/account/cancel-deletion` reverses it.
+
+        Re-verifies the caller's password: `current_password` is required.
+
+        **Deletion is REFUSED while the account has workflows in progress**
+        (`409 WORKFLOWS_IN_PROGRESS`). A client must be prepared for that
+        branch — it is not an error state the user can resolve by retrying
+        immediately, and it is the answer to "what happens to my in-flight
+        work": nothing, because the deletion does not start.
+
+        **Side effect a caller cannot otherwise discover:** a successful
+        request **revokes the account's API keys immediately**, before the
+        grace period elapses, and reports how many in `api_keys_revoked`.
+        Cancelling the deletion does **not** restore them.
+
+        Hard deletion runs after grace expiry and is **not exposed to
+        callers**; the terminal states surface as the `account_deleted` and
+        `account_deletion_expired` error codes on subsequent requests.
+      operationId: requestAccountDeletion
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (authenticated principal)
+      x-identity-scoped: true  # identity-bound (caller's own account)
+      tags:
+        - Auth
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - current_password
+              properties:
+                current_password:
+                  type: string
+                  minLength: 1
+            example:
+              current_password: "s3cretpw"
+      responses:
+        '200':
+          description: |
+            Deletion requested; the 30-day grace period has started.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: false
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    type: object
+                    additionalProperties: false
+                    required:
+                      - message
+                      - api_keys_revoked
+                    properties:
+                      message:
+                        type: string
+                        description: Human-readable confirmation naming the grace period.
+                      api_keys_revoked:
+                        type: integer
+                        minimum: 0
+                        description: |
+                          How many of the account's API keys were revoked by
+                          this request. Revocation is **immediate** and is
+                          **not** undone by cancelling the deletion.
+              example:
+                success: true
+                data:
+                  message: "Account deletion requested. You have 30 days to cancel."
+                  api_keys_revoked: 2
+        '403':
+          description: |
+            The supplied `current_password` is incorrect
+            (`error: INVALID_PASSWORD`, `error_type: invalid_password`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "INVALID_PASSWORD"
+                error_type: "invalid_password"
+                message: "Current password is incorrect."
+        '409':
+          description: |
+            Two distinct conflicts, discriminated by `error_type`:
+
+            - `already_requested` (`error: ALREADY_REQUESTED`) — a deletion
+              request is already open for this account.
+            - `workflows_in_progress` (`error: WORKFLOWS_IN_PROGRESS`) — the
+              account has running workflows and deletion is refused until
+              they reach a terminal state.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "WORKFLOWS_IN_PROGRESS"
+                error_type: "workflows_in_progress"
+        '401':
+          description: No authenticated principal.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "AUTHENTICATION_REQUIRED"
+                error_type: "authentication_required"
+                message: "Authentication required."
+        '404':
+          description: |
+            The authenticated principal no longer resolves to a stored user
+            (`error: USER_NOT_FOUND`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "USER_NOT_FOUND"
+        '422':
+          description: |
+            Structured input validation failure — e.g. a blank
+            `current_password`. `details[].field` carries the wire key
+            `current_password`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationErrorEnvelope'
+              example:
+                success: false
+                error_type: validation_error
+                error: "Validation failed"
+                details:
+                  - field: "current_password"
+                    message: "Current password is required."
+        '429':
+          description: |
+            Rate limit exceeded — the deletion request has its own per-user
+            hourly limiter, separate from the cancel limiter. Carries a
+            `Retry-After` response header.
+          headers:
+            Retry-After:
+              description: Seconds to wait before retrying. Delta-seconds (RFC 9110).
+              schema:
+                type: integer
+                minimum: 0
+              example: 60
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/auth/account/cancel-deletion:
+    post:
+      summary: Cancel a pending account-deletion request
+      description: |
+        Reverses a deletion request while the **30-day grace period** is
+        still open. Takes no request body — the caller's identity is the
+        whole input.
+
+        **`410 Gone` is the expiry signal** and is the only way a client
+        learns the grace period has run out. Distinguish it from `409`: a
+        `409` means there was never a request to cancel, a `410` means there
+        was one and it is too late.
+
+        **API keys revoked by the deletion request are NOT restored.**
+      operationId: cancelAccountDeletion
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (authenticated principal)
+      x-identity-scoped: true  # identity-bound (caller's own account)
+      tags:
+        - Auth
+      responses:
+        '200':
+          description: The pending deletion request was cancelled.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: false
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    type: object
+                    additionalProperties: false
+                    required:
+                      - message
+                    properties:
+                      message:
+                        type: string
+              example:
+                success: true
+                data:
+                  message: "Account deletion has been cancelled."
+        '409':
+          description: |
+            No deletion request is open for this account
+            (`error: NO_DELETION_REQUEST`, `error_type: no_deletion_request`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "NO_DELETION_REQUEST"
+                error_type: "no_deletion_request"
+        '410':
+          description: |
+            The 30-day grace period has expired and the deletion can no
+            longer be cancelled (`error: GRACE_PERIOD_EXPIRED`,
+            `error_type: grace_period_expired`). **This is the expiry
+            signal** — see also the `account_deletion_expired` error code.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "GRACE_PERIOD_EXPIRED"
+                error_type: "grace_period_expired"
+        '401':
+          description: No authenticated principal.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "AUTHENTICATION_REQUIRED"
+                error_type: "authentication_required"
+                message: "Authentication required."
+        '404':
+          description: |
+            The authenticated principal no longer resolves to a stored user
+            (`error: USER_NOT_FOUND`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "USER_NOT_FOUND"
+        '429':
+          description: |
+            Rate limit exceeded — the cancel path has its own per-user hourly
+            limiter, separate from the deletion-request limiter. Carries a
+            `Retry-After` response header.
+          headers:
+            Retry-After:
+              description: Seconds to wait before retrying. Delta-seconds (RFC 9110).
+              schema:
+                type: integer
+                minimum: 0
+              example: 60
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/auth/account/export:
+    get:
+      summary: Export the authenticated user's data (GDPR)
+      description: |
+        Returns the account's stored data as JSON: `profile`, `uploads`,
+        `workflows`, `api_keys` and `billing`, plus an `exported_at`
+        timestamp.
+
+        **The response carries the account's full PII**, so the server sets
+        `Cache-Control: no-store` — **not** merely `no-cache`. A client MUST
+        NOT write this payload to shared or persistent storage.
+
+        Independent of the deletion flow: exporting neither starts nor
+        cancels a deletion.
+      operationId: exportAccountData
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (authenticated principal)
+      x-identity-scoped: true  # identity-bound (caller's own data)
+      tags:
+        - Auth
+      responses:
+        '200':
+          description: |
+            The account's exported data. The per-section payload shapes are
+            **deliberately not pinned here** — they are a data dump for the
+            account holder, not an integration surface, and pinning them
+            would freeze internal record shapes into this contract.
+          headers:
+            Cache-Control:
+              description: Always `no-store` — the payload carries full PII.
+              schema:
+                type: string
+              example: "no-store"
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: false
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    type: object
+                    required:
+                      - exported_at
+                      - profile
+                    properties:
+                      exported_at:
+                        type: string
+                        format: date-time
+                      profile:
+                        type: object
+                      uploads:
+                        type: array
+                        items:
+                          type: object
+                      workflows:
+                        type: array
+                        items:
+                          type: object
+                      api_keys:
+                        type: array
+                        items:
+                          type: object
+                      billing:
+                        type: object
+        '401':
+          description: No authenticated principal.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "AUTHENTICATION_REQUIRED"
+                error_type: "authentication_required"
+                message: "Authentication required."
+        '404':
+          description: |
+            The authenticated principal no longer resolves to a stored user
+            (`error: USER_NOT_FOUND`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "USER_NOT_FOUND"
+        '429':
+          description: |
+            Data-export rate limit reached. Carries a `Retry-After` response
+            header.
+          headers:
+            Retry-After:
+              description: Seconds to wait before retrying. Delta-seconds (RFC 9110).
+              schema:
+                type: integer
+                minimum: 0
+              example: 60
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
   /api/auth/confirm-email-change:
     post:
       summary: Confirm a pending email-address change
@@ -5185,6 +5615,18 @@ paths:
       operationId: createBillingCheckoutSession
       security: [{bearerAuth: []}, {sessionAuth: []}]  # required (IS_AUTHENTICATED_FULLY; anonymous/partial sessions → 401)
       x-identity-scoped: true  # the checkout session is created for the authenticated caller
+      # DOWNGRADE, and it clears standing policies 3 and 4 by MEASUREMENT
+      # rather than by absence of evidence: e2e drove this endpoint on staging
+      # 2026-08-11 and got 422 `feature_not_available` with
+      # `availability: planned`, WITH CONTROLS — unauthenticated gives 401 and
+      # GET gives 405, so the 422 is the feature gate and not a bad payload or
+      # a missing route. api confirmed `STRIPE_CHECKOUT_ENABLED=false` and five
+      # empty price IDs on the live task definition.
+      #
+      # Flipping this back to `stable` is an UPGRADE and is covered by the
+      # standing freeze (hub, 2026-08-11): no availability upgrade to `stable`
+      # before launch without an explicit per-flip ruling.
+      x-availability: planned
       tags:
         - Billing
       requestBody:
@@ -6751,6 +7193,138 @@ components:
               $ref: '#/components/schemas/AccountLimitEntry'
             max_total_input_size_bytes:
               $ref: '#/components/schemas/AccountLimitEntry'
+            max_duration_seconds:
+              # OPTIONAL in this expand step; NOT in `required` above until
+              # api emits it. Unit is SECONDS — carried by the key name, per
+              # AccountLimitEntry.
+              $ref: '#/components/schemas/AccountLimitEntry'
+
+    MediaCategory:
+      type: string
+      enum: [image, video, audio, document]
+      description: |
+        Coarse input media family, as used by the tier-default surface.
+        **Not** a MIME type and **not** an operation `mime_group` — those are
+        finer-grained and live in the operation schemas. This vocabulary
+        exists so a client can filter a file picker without enumerating MIMEs.
+
+    TierDefaults:
+      type: object
+      additionalProperties: false
+      description: |
+        The **published default limits**, readable by an ANONYMOUS caller.
+
+        **Why this exists separately from `GET /api/v2/account/limits`:** that
+        endpoint is per-account and override-aware, so it requires auth and
+        returns `401` to an anonymous caller — **correctly**, because
+        `effective` / `tier_default` / `overridden` is meaningless without an
+        account. What a logged-out visitor needs is the **tier defaults**,
+        which are not per-account. This publishes AS DATA what the `UserTier`
+        description already publishes as prose.
+
+        **The server is authoritative for the values.** This contract declares
+        the SHAPE; the numbers are computed per environment and per tier
+        model, and a client MUST read them here rather than hard-coding a
+        table (the drift this field exists to end).
+      required:
+        - media_categories
+        - by_audience
+      properties:
+        media_categories:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/MediaCategory'
+          description: |
+            The input media families available **to every audience,
+            including anonymous**. Declared ONCE, not per-tier, because it
+            does not vary — hub decision 25 made audio universal, and there
+            is now no tier boundary at which the category axis changes.
+
+            ⚠️ **Deliberately NOT a per-audience allow-list.** A structure
+            with one row per tier, every row identical, is a gate whose every
+            row is open — it reads as an entitlement mechanism while
+            encoding no entitlement, and the next reader maintains it as
+            though it did. If a future tier DOES restrict categories, this
+            field moves into `by_audience` in a deliberate change, and that
+            change is where the restriction gets argued.
+        by_audience:
+          type: object
+          additionalProperties: false
+          description: |
+            The limits that genuinely DO vary, keyed by audience. Contains
+            only axes with real variance; an axis that is uniform belongs
+            beside `media_categories`, not here.
+
+            **`anonymous` is a key here but deliberately NOT a `UserTier`
+            value.** `UserTier` is a subscription tier and anonymous is the
+            ABSENCE of one — putting it in that enum would place a
+            non-subscription value inside the ordering that drives upgrade
+            prompts (`free < pro < max < enterprise`), where it has no
+            position.
+            ⚠️ **And keeping them distinct is not pedantry — the conflation
+            has already shipped once.** This endpoint's `user_tier`
+            description used to say anonymous callers "receive the `free`
+            tier baseline view", which became false the moment the two were
+            allowed to differ. **A vocabulary that cannot express the
+            difference invites prose asserting they are the same.**
+          required:
+            - anonymous
+            - free
+            - pro
+            - max
+            - enterprise
+          properties:
+            anonymous:
+              $ref: '#/components/schemas/TierDefaultLimits'
+            free:
+              $ref: '#/components/schemas/TierDefaultLimits'
+            pro:
+              $ref: '#/components/schemas/TierDefaultLimits'
+            max:
+              $ref: '#/components/schemas/TierDefaultLimits'
+            enterprise:
+              $ref: '#/components/schemas/TierDefaultLimits'
+
+    TierDefaultLimits:
+      type: object
+      additionalProperties: false
+      description: |
+        One audience's default limits. **Defaults, not entitlements** — a
+        specific account may carry an override, which only
+        `GET /api/v2/account/limits` can report.
+      required:
+        - max_upload_size_bytes
+        - max_duration_seconds
+      properties:
+        max_upload_size_bytes:
+          type: integer
+          format: int64
+          minimum: 1
+          description: |
+            Per-FILE upload cap. Same axis as
+            `AccountLimits.limits.max_upload_size_bytes`.
+
+            ⚠️ **A client MUST NOT treat this as the only size bound.** The
+            per-operation processing ceilings (`max_input_size_bytes` in the
+            operation schemas) are a **different axis and a different
+            number**, and can be SMALLER than this cap — an upload that
+            succeeds may still be rejected at operation time. A picker that
+            shows one number without the other will let a user pick a file
+            the product cannot process.
+        max_duration_seconds:
+          type: [integer, "null"]
+          minimum: 0
+          description: |
+            Per-upload duration cap for time-based media. `null` where the
+            audience has no duration cap.
+
+            ⚠️ **DISTINCT from `processing_class.short_form.max_input_duration`
+            (`PT5M`) in the operation schemas, which it may numerically
+            equal.** That is the short-form/long-form PROCESSING boundary and
+            applies to every audience; this is an entitlement. Two concepts,
+            one integer — read this one for entitlement.
 
     AccountLimitEntry:
       type: object
@@ -6769,14 +7343,16 @@ components:
           type: integer
           minimum: 1
           description: |
-            The cap in force for this account, in bytes
-            (`override ?? tier_default`).
+            The cap in force for this account (`override ?? tier_default`),
+            **in this limit's own unit** — bytes for the `*_bytes` keys,
+            seconds for the `*_seconds` keys. **The unit is carried by the
+            key name, not by this field.**
         tier_default:
           type: integer
           minimum: 1
           description: |
-            The tier's default cap for this limit, in bytes (already public
-            via the tier model).
+            The tier's default cap for this limit, in the same unit as
+            `effective` (already public via the tier model).
         overridden:
           type: boolean
           description: |
@@ -11468,11 +12044,50 @@ components:
 
     CodegenUploadPlaceholder:
       type: object
+      # ⚠️ THIS DESCRIPTION USED TO SAY "the original upload is
+      # consumed/expired". THAT WAS FALSE, and it contradicted this contract's
+      # own schema: `UploadSource` accepts `{type: upload, file_id}` at
+      # workflow-create, so a client reading the schema builds file reuse while
+      # a client reading this sentence concludes it cannot work. Both shipped,
+      # in the same published artefact.
+      #
+      # Corrected 2026-08-12 from api's code read: NOTHING marks an upload
+      # consumed — no column, no flag, no state — nothing deletes it when a
+      # workflow completes, and the `uploads` row is independent of workflow
+      # lifecycle. An upload is REUSABLE.
+      #
+      # ⚠️ THE UPLOAD LIFETIME IS STILL UNDECLARED AND IS DELIBERATELY NOT
+      # INVENTED HERE. The only true sense in which an upload "expires" is the
+      # stored bytes ageing out of the input bucket, which is a storage
+      # lifecycle and not currently a contract concept at all. That number is
+      # terraform's measurement; it has been relayed to this session as 3 days
+      # and NEITHER api NOR this session has verified it, so it is not written
+      # into the contract. Asked of terraform 2026-08-12; lands as a follow-up
+      # if and only if they confirm it AND confirm staging and prod agree —
+      # this contract has no environment axis, so a lifetime true in one
+      # environment and false in the other cannot be expressed honestly.
       description: |
         Stand-in for a user UPLOAD source in a replay projection — descriptive
-        metadata so a consumer can re-prompt for an equivalent file. NOT the
-        bytes or storage key (the original upload is consumed/expired), so it is
-        deliberately NOT a re-submittable `UploadSource`.
+        metadata so a consumer can re-prompt for an equivalent file. Carries
+        NOT the bytes or the storage key, only the descriptive fields below.
+
+        **This placeholder is about what the PROJECTION carries, not about
+        whether the upload still exists.** An upload is **not** consumed by
+        being used: nothing marks it spent, and referencing the same `file_id`
+        again at `POST /api/workflows` via `UploadSource` is valid — that is
+        how a caller re-runs a file with different settings, or runs a
+        different operation on it.
+
+        The projection omits the `file_id` because a replay snippet is meant to
+        be re-runnable by **any** reader, including one who never held that
+        upload; it is a code sample, not a resume token.
+
+        ⚠️ **How long an upload remains referenceable is NOT declared by this
+        contract.** The stored bytes are subject to an input-bucket retention
+        lifecycle that this spec does not state, so a caller MUST be prepared
+        for a `file_id` that was valid to stop being usable, and MUST NOT infer
+        a lifetime from the workflow `expires_at` TTL — **those are different
+        clocks on different objects, and the workflow one is longer.**
       required:
         - kind
       properties:
@@ -12849,12 +13464,25 @@ components:
             - type: string
             - type: 'null'
           example: "production"
+        tier_defaults:
+          # Anonymous-readable. Declared here rather than on
+          # /api/v2/account/limits because that surface is per-account and
+          # override-aware, so it 401s an anonymous caller — correctly.
+          $ref: '#/components/schemas/TierDefaults'
         user_tier:
           description: |
             Tier of the calling user. Anonymous (unauthenticated) callers
-            see `null` on the wire and receive the `free` tier baseline
-            view. Used by clients to render upgrade prompts on tier-gated
-            features.
+            see `null` on the wire. Used by clients to render upgrade
+            prompts on tier-gated features.
+
+            ⚠️ **`null` does NOT mean "the free tier".** This description
+            previously said anonymous callers "receive the `free` tier
+            baseline view"; that stopped being true when the anonymous and
+            free limits were allowed to differ (hub decisions 22 + 25 —
+            anonymous carries a shorter duration entitlement than a
+            signed-in free user). **Anonymous is the ABSENCE of a tier, not
+            the lowest one.** Read `tier_defaults.by_audience.anonymous`
+            for what an unauthenticated caller may actually do.
           oneOf:
             - $ref: '#/components/schemas/UserTier'
             - type: 'null'