@giveitsmaller/contracts 0.83.0 → 0.84.0

package/openapi/api.yaml

@@ -103,7 +103,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.218.0
+  version: 2.219.0
   contact:
     name: API Support
 
@@ -1472,9 +1472,20 @@ paths:
         immutable ledger transaction is written in the same DB
         transaction as the workflow row; the response's
         `processing_plan` reflects the same estimate the reservation
-        was sized against. Refunds (e.g. on terminal failure that the
-        server policy refunds) are emitted as separate ledger rows
-        referencing the reservation via `reference_id`. The
+        was sized against. **Callers pay only for successful results,
+        per job** (owner decisions 610(4) and 635; the policy is data in
+        `schemas/pricing-policy.yaml`). Each job that completes is charged;
+        a job that fails after its retries is refunded, as is cancelled
+        work (a workflow paused for credits has its reservation released at
+        the pause and reserved again on resume), so a `partially_failed`
+        workflow is charged for the jobs that completed. A long-form fan-out is settled
+        at what it actually used and the difference is refunded. Uploading
+        is free; an operation on a larger input costs more, through the
+        size surcharge in that file. Refunds are separate ledger rows
+        referencing the reservation via `reference_id`. ⚠️ **Contract-first:**
+        until api ships the per-job change, the API refunds the WHOLE
+        reservation when any job fails, so a `partially_failed` workflow is
+        charged nothing (`pricing-policy.yaml` `charge.api_today`). The
         idempotency-key wire shape for retried reservation attempts
         is deferred per ADR-0001 §1.7 row 5.
       operationId: createWorkflow
@@ -1580,7 +1591,11 @@ paths:
                         - type: compress
       responses:
         '201':
-          description: Workflow created
+          description: |
+            Workflow created. A long video `compress` that the API runs as an
+            internal fan-out appears as ONE job with ONE `compress` operation
+            whose id is the one `/status` and SSE report; see **LONG-FORM
+            FAN-OUT: ONE PUBLIC ROW** on `GET /api/workflows/{id}/events`.
           content:
             application/json:
               schema:
@@ -2104,7 +2119,12 @@ paths:
                 Optional, best-effort. Present only on the
                 `probe_pending` branch — suggested seconds to wait
                 before re-polling the upload probe and retrying the
-                workflow. Delta-seconds (RFC 9110), mirroring the 429
+                workflow. **A guest (no credential) cannot poll the probe**
+                (`POST /api/uploads/{id}/probe` requires sign-in): it retries
+                the create itself. A `probe_pending` refusal does not count
+                against the guest per-minute create limit and reserves no
+                guest allowance credits (`schemas/anonymous-policy.yaml`
+                `video`). Delta-seconds (RFC 9110), mirroring the 429
                 login path's `Retry-After` convention. Absent until the
                 server-side probe-staleness bound (API `e1Idv6UL`)
                 lands; consumers MUST treat absence as "retry on your
@@ -2327,6 +2347,12 @@ paths:
         Retrieve the current status of a workflow with nested job and operation breakdown.
         Each operation includes its current progress and, when completed, its result
         (download URL, size, metrics).
+
+        A long video `compress` that the API runs as an internal fan-out
+        (split, segments, concat) appears here as ONE job with ONE `compress`
+        operation. See **LONG-FORM FAN-OUT: ONE PUBLIC ROW** on
+        `GET /api/workflows/{id}/events`, which is normative for this
+        endpoint too.
       operationId: getWorkflowStatus
       security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK; identity-scoped to workflow owner)
       x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
@@ -2573,6 +2599,15 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
 
+  # LONG-FORM FAN-OUT fold (section in the description below), read from
+  # compression_api main 2a8dd8d5, paths under compression/src/Jobs/:
+  #   fold + public ids:  Domain/Service/FanOutClusterFolder.php:22-47,218-239,332-354,452-545
+  #   ids:                Domain/Service/FanOutNodeIdFactory.php:82-94,176-196
+  #   public op shape:    Domain/ValueObject/FanOutPublicOperation.php:45,85-87
+  #   SSE frames:         Application/Service/WorkflowSseService.php:333-350,563-671
+  #   create 201 row:     Presentation/Http/Controller/WorkflowController.php:543-589,725-740
+  #   fallback path:      Application/Service/LongFormFanOutBuilder.php:784-830
+  #   concat auto-retry:  Infrastructure/Messaging/Handler/OperationResultHandler.php:712-730
   /api/workflows/{id}/events:
     get:
       summary: Stream workflow events (SSE)
@@ -2880,6 +2915,80 @@ paths:
         (the `id:` and `event:` lines) is transport-level and intentionally
         **not** schema-described.
 
+        ### LONG-FORM FAN-OUT: ONE PUBLIC ROW
+
+        This section is normative for **every read surface**; the `/status`
+        and create-201 descriptions point here rather than restate it.
+
+        The API may run a long video `compress` as an internal fan-out: one
+        `split` job, then N parallel segment `compress` jobs, then a
+        stream-copy concat (`merge`). It applies only to a root job holding a
+        single `compress`, and only one such job per workflow. Today the API
+        also requires that no other job depends on it; a client must not rely
+        on that: if a fanned-out job has dependants, they read the joined
+        output, exactly as they would read the job's output unsplit.
+        **Clients never see the fan-out.** The API folds it into
+        ONE public job with ONE public operation on the create 201,
+        `GET /status` and this stream, and into ONE job row on
+        `GET /api/workflows` (whose rows carry no operations; read the
+        operation from `/status`). On `GET /downloads` the joined file is
+        listed under the original `job_ref` with operation `compress`, when
+        it is delivered at all: only once it is complete, only if the
+        delivery selection includes that job, and only while retained. The
+        internal jobs and operations do not appear on any surface, and this
+        stream sends no frame for them.
+
+        | field | value |
+        |---|---|
+        | `job_ref` / `ref` | the client's **original** job ref, on every surface and every path below |
+        | `job_id` | one server-chosen id for the public job, the same before and after the split expands |
+        | `operation_id` / `operations[0].id` | one server-chosen id, the same on the 201, `/status` and this stream, before and after the split expands (exceptions below) |
+        | `type` | `compress` (never `split` or `merge`), including the output-name marker |
+        | `processing_class` (`/status`, `processing_plan`) | `long_form` |
+        | `depends_on` | `[]` |
+        | outputs | exactly one: the joined file |
+
+        **On this stream** the public operation gets zero or more
+        `operation.progress` frames, then ONE `operation.completed` or ONE
+        `operation.failed`, then ONE `job.completed` or `job.failed` for the
+        public job. A failure can arrive with no progress frame before it,
+        so the terminal frame may be the first one. These frames
+        carry **no `id:` line**. `operation.completed` carries no
+        `result_metadata`, and its `result` stays optional as on every
+        `SseOperationCompletedData`: when it is absent, read the output from
+        `GET /downloads`. `job.failed` can arrive in a later frame batch
+        than `operation.failed`.
+
+        **Progress** is weighted by phase: split 10, segments 80 (shared
+        equally), concat 10. Until the split finishes and the segments exist,
+        it **stays at or below 10**: a long bar at 10% is the split running,
+        not a stall. On this stream it never decreases within one connection.
+        `GET /status` reads a snapshot per poll and can dip briefly between
+        polls. Clients that must not show a backwards bar hold their own
+        maximum per `job_ref`.
+
+        **Failure.** Any failed segment fails the whole public operation. The
+        reported `error_code` is the causing failure; a `never_started`
+        collateral code is reported only when there is no causing one.
+
+        **The operation id is NOT stable in two cases. Key the row on
+        `job_ref`, which is.**
+        1. **Unsplittable input.** When the split finds the file cannot be
+           split, the API runs one plain long-form `compress` instead. It has
+           a **new** `job_id` and `operation_id`, under the same `job_ref`.
+           The first id gets no terminal frame. Its progress starts again
+           from 0, so a bar keyed on `job_ref` goes back from 10 to 0 once.
+        2. **Automatic retry of the concat step.** The retry is a new
+           operation with a new id, and the public row then shows that id.
+           User retries (`POST /api/operations/{id}/retry`) are refused for
+           the internal operations.
+
+        **Downloads.** Before the split finishes the public job's
+        `/downloads` row lists no files; while segments run it can be
+        absent; it lists the one output once the concat completes. On the
+        unsplittable path there is no concat: the fallback `compress` job
+        is an ordinary row and lists its output when it completes.
+
         ### AUTH ON THE STREAM HOST: the CREDENTIAL decides, not the caller
 
         **Two axes, and conflating them is what made two earlier versions of this
@@ -6228,12 +6337,12 @@ paths:
                   value:
                     success: true
                     data:
-                      monthly_balance: 1200
+                      monthly_balance: 800
                       purchased_balance: 5000
-                      overdraft_limit: 500
+                      overdraft_limit: 200
                       overdraft_debt: 0
-                      available_credits: 6700
-                      monthly_allowance: 2000
+                      available_credits: 6000
+                      monthly_allowance: 1000
                       tier: pro
                 pro_overdrafted:
                   summary: Pro tier in overdraft (monthly + purchased exhausted)
@@ -6242,10 +6351,10 @@ paths:
                     data:
                       monthly_balance: 0
                       purchased_balance: 0
-                      overdraft_limit: 500
-                      overdraft_debt: 350
-                      available_credits: 150
-                      monthly_allowance: 2000
+                      overdraft_limit: 200
+                      overdraft_debt: 150
+                      available_credits: 50
+                      monthly_allowance: 1000
                       tier: pro
         '401':
           description: Authentication required.
@@ -8286,7 +8395,10 @@ components:
         overdraft_debt:
           type: integer
           minimum: 0
-          description: Credits currently owed against the overdraft pool.
+          description: >-
+            Credits currently owed against the overdraft pool. Repaid one
+            credit for one credit from the next monthly grant, on every
+            plan (`schemas/pricing-policy.yaml` `overdraft.repayment_ratio`).
         available_credits:
           type: integer
           description: |
@@ -10024,7 +10136,12 @@ components:
         (`ok` → re-`POST /api/workflows` the same request; `corrupt` /
         `unsupported_codec` → surface the probe error, do not retry).
         The `Retry-After` response header (when present) carries the
-        suggested delay in seconds before the next poll/retry.
+        suggested delay in seconds before the next poll/retry. **A guest
+        (no credential) cannot poll**: the probe endpoint requires
+        sign-in, so a guest re-`POST`s the same create on `Retry-After`
+        or its own backoff; the refusal does not count against its
+        per-minute create limit or allowance
+        (`schemas/anonymous-policy.yaml` `video`).
 
         Delivered alongside `ValidationErrorEnvelope`,
         `FeatureNotAvailableResponse`, and
@@ -12482,13 +12599,16 @@ components:
         dropped_options:
           type: array
           description: |
-            Options the SERVER supplied on the caller's behalf and then
-            REMOVED, because the resolved execution path cannot honour
-            them. **Never contains a value the caller sent explicitly** —
-            an explicit option the path cannot honour is refused with
-            `422 feature_not_available`, not silently dropped. That
-            split is the whole rule: a caller who asked for nothing is
-            not punished for our default; a caller who asked for
+            Options holding their DEFAULT (supplied by the server, or
+            sent by the client equal to the schema default, which reads as
+            defaulted — `schemas/FORMAT.md` "Container-conditional
+            defaults") that were then REMOVED or SUBSTITUTED, because the
+            resolved execution path or output container cannot honour
+            them. **Never contains a caller's choice** — a value that
+            differs from the default and cannot be honoured is refused
+            (`422 feature_not_available` / `invalid_options`), not
+            dropped. That split is the whole rule: a caller who asked for
+            nothing is not punished for our default; a caller who asked for
             something is told.
 
             **Why this field exists at all.** Dropping a defaulted
@@ -12510,7 +12630,8 @@ components:
     DroppedOption:
       type: object
       description: |
-        One server-supplied option removed from a job before dispatch.
+        One defaulted option (server-supplied, or sent equal to its
+        schema default) removed or substituted before dispatch.
         **Names the THING, the WHY and the PATH** — the three parts a
         caller needs to act, and the three a single interpolated string
         would fuse into something unparseable.
@@ -12557,12 +12678,29 @@ components:
               caller on a guessed class is the same error as asserting
               a measurement never taken**, so an unmeasured basis
               degrades to a drop and never to a 422.
+            - `container_incompatible_default` — the option held its
+              schema default (omitted, or sent equal to the default),
+              and the output container cannot carry that value, so the
+              container's own default was applied instead; the applied
+              value is in `resolved_value` (e.g. `codec` `h264` on a
+              WebM output → `vp9`; `audio_codec` `copy` of AAC into
+              WebM → `opus`). See `schemas/FORMAT.md`
+              "Container-conditional defaults". Contract-first (api
+              `PSJ1vBC7`).
 
             The class token is deliberately NOT interpolated into this
             string: the reason and the path are separate fields because
             a fused `not_available_on_<class>` is unparseable and
             duplicates `processing_class`.
           example: unavailable_on_processing_class
+        resolved_value:
+          type: string
+          description: |
+            OPTIONAL. The value the server applied in place of the
+            dropped one, when it substituted a value rather than
+            removing the option (`reason: container_incompatible_default`).
+            Absent for a plain drop.
+          example: vp9
 
     ProcessingPlan:
       type: object
@@ -14068,6 +14206,43 @@ components:
             `input_filename`. Ticket [`j2s6T2qf`](https://trello.com/c/j2s6T2qf)
             (FE before→after size, workflow-view launch ask).
           example: 491520
+        input_uploaded_at:
+          type: string
+          format: date-time
+          description: |
+            OPTIONAL. When the server finished receiving the job's input
+            upload: a single-shot upload's accept, or a multipart
+            `complete`. For a job with several uploaded inputs (e.g. a
+            merge), the LATEST of them, since the job cannot start before
+            its last input arrives; inputs that are not uploads (another
+            job's output, an import) are ignored. Absent when the job has no
+            uploaded input, and until the API records it. Card
+            [`6EOlMAz4`](https://trello.com/c/6EOlMAz4) (e2e performance
+            baseline, owner decisions 630/635): with `started_at` and
+            `completed_at` it separates upload, queue and processing time on
+            the server clock. Contract-first: api populates it in a
+            follow-up; a client must treat absence as "not recorded".
+          example: "2026-09-29T21:00:00Z"
+        started_at:
+          type: string
+          format: date-time
+          description: |
+            OPTIONAL. When the job's first operation started processing (the
+            first progress report from a worker). Absent while the job is
+            queued, and for a job that never started. Server clock. See
+            `input_uploaded_at`.
+          example: "2026-09-29T21:00:04Z"
+        completed_at:
+          type: string
+          format: date-time
+          description: |
+            OPTIONAL. When the job reached a terminal `JobStatus`
+            (`completed` or `failed`), on the server clock. Absent while
+            the job is not terminal.
+            `completed_at - started_at` is the job's EXECUTION SPAN: for a
+            chain of operations it includes any wait between them, so it is
+            not pure processing time. See `input_uploaded_at`.
+          example: "2026-09-29T21:00:19Z"
         processing_class:
           $ref: '#/components/schemas/ProcessingClass'
           description: |
@@ -14177,7 +14352,9 @@ components:
             `invalid_format` (input type unsupported),
             `format_mismatch` (declared MIME ≠ content),
             `decode_failed` (input unreadable/corrupt),
-            `output_too_large` (output exceeded the size limit),
+            `output_too_large` (output exceeded the size limit; NOT for a
+            same-format `compress`, which returns the original with
+            `already_optimal` instead — owner decision 645(4)),
             `missing_source` (source not found — fail-fast),
             `invalid_key` (storage key invalid),
             `processing_failed` (non-specific processing failure),
@@ -14276,7 +14453,35 @@ components:
             "already optimised", not as "same size". On an ordinary result it
             is absent or `false`; treat the two the same. Projected by the API from the wire
             `OperationMetrics.already_optimal` (ticket `roNRMilt`).
+            **Charged nothing** (owner decision 645(4),
+            `schemas/pricing-policy.yaml` `charge.not_charged`): the
+            operation's cost is refunded; other operations in the job are
+            charged as usual. Applies to a completed `compress` on the
+            resolved `same_format` route (`output_format` original, absent, or
+            equal to the input's format; not the format-change facade, where
+            the original is not what was asked for). A same-format compress
+            that cannot shrink the file returns this, never `output_too_large`.
+            ⚠️ **Today this holds for SHORT-FORM compress only.** Long-form
+            compress still fails `output_too_large` until lambdas ships its
+            long-form copy path; do not promise "already optimised" or "no
+            charge" for a long-form file before then. Contract-first: until api
+            ships, the operation is charged (`charge.not_charged_api_today`).
+            `already_optimal_kind` says which kind of "already optimised" it
+            was.
           example: true
+        already_optimal_kind:
+          type: string
+          enum: [not_smaller]
+          description: |
+            OPTIONAL, only with `already_optimal: true`: WHY the original was
+            returned. `not_smaller` — the file was compressed and the result
+            was not smaller, so there is no quality trade-off to explain. It
+            is the only kind any worker produces today (no production path
+            declines to encode an efficient source). Absent, or a value you do
+            not know: show neutral "already optimised" copy.
+            Contract-first (card `cDZuuyg8`): projected from the wire
+            `OperationMetrics.already_optimal_kind` once workers emit it.
+          example: not_smaller
         estimated_saving_pct:
           type: number
           minimum: 0
@@ -17167,6 +17372,16 @@ components:
         app:
           type: boolean
           description: Application is running
+        build:
+          type: string
+          description: |
+            OPTIONAL. The release the running image was built as (the API's
+            `APP_VERSION`, e.g. `1.15.2-rc.1`; `dev` for a local build;
+            `unknown` when unset). Unauthenticated on purpose: a timing run
+            reads it before and after, so a code-only deploy in the middle
+            of the run is detectable (card `6EOlMAz4`, e2e performance
+            baseline). Opaque: compare for equality, do not parse.
+          example: "1.15.2-rc.1"
 
     ReadinessResponse:
       type: object

package/operation-capabilities/operation-capabilities.json

@@ -253,7 +253,6 @@
               {
                 "field": "compress.codec",
                 "in": [
-                  "h264",
                   "h265"
                 ]
               }
@@ -860,5 +859,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.218.0"
+  "schema_version": "2.219.0"
 }

package/operations/schemas/compress.yaml

@@ -1217,9 +1217,10 @@ operation:
             Output container. original = keep the input container (default, same-format
             compression). Other values change the container as part of the same job, keeping
             the size cap. When set, the RESOLVED target container determines the valid
-            codec/audio_codec/faststart sets — an absent/default codec resolves to a
-            container-valid one (e.g. webm -> vp9) and is never rejected; only a
-            caller-EXPLICIT incompatible value is rejected.
+            codec/audio_codec/faststart sets — an absent or default-equal value (sent equal
+            to its default counts as the default) resolves to a container-valid one (e.g.
+            webm -> vp9), is never rejected, and is reported in dropped_options; only a
+            NON-default incompatible value is rejected.
         codec:
           type: enum
           values: [h264, h265, vp9, av1]
@@ -1241,8 +1242,10 @@ operation:
             the input container): for a container that cannot carry it (e.g. WebM, which
             carries VP8/VP9/AV1) the server resolves a container-valid codec (WebM -> vp9).
             A DEFAULT value is never rejected — including an explicit `output_format: webm`
-            left at the default `h264` (resolves to vp9, not rejected); only a
-            caller-EXPLICIT incompatible codec is rejected.
+            left at the default `h264` (resolves to vp9, not rejected). A value equal to the
+            default counts as the default even when sent, and the substitution is reported
+            in dropped_options. Only a NON-default codec the container cannot carry is
+            rejected (e.g. h265 on WebM).
         encoding_mode:
           type: enum
           values: [crf, target_size]
@@ -1395,9 +1398,9 @@ operation:
             Move the MP4/MOV moov atom to the front so the file starts playing before it is
             fully downloaded (progressive web playback). MP4/MOV only. CONTAINER-CONDITIONAL
             against the RESOLVED output container (the explicit `output_format` if set, else
-            the input): the default (true) is silently inapplicable for a container with no
-            moov atom (e.g. WebM) — that is NOT a rejection. Only a caller-EXPLICIT
-            faststart:true on such a container is rejected.
+            the input): on a container with no moov atom (e.g. WebM) the default (true),
+            omitted or sent, is dropped and reported in dropped_options — never a rejection.
+            false there asks for nothing and is accepted.
         audio_codec:
           type: enum
           values: [aac, opus, vorbis, copy]
@@ -1422,9 +1425,11 @@ operation:
             the container, an absent/default audio_codec resolves to a container-valid codec
             via the facade (e.g. webm -> opus), NOT a blind copy of an incompatible stream —
             a DEFAULT is never rejected (the exact per-container resolution, incl. ogg
-            vorbis-vs-opus, is an output_format stable-flip prerequisite). A caller-EXPLICIT
-            codec the resolved container cannot carry (e.g. aac on a webm target) is
-            rejected.
+            vorbis-vs-opus, is an output_format stable-flip prerequisite). `copy` sent
+            explicitly counts as the default: if the source audio cannot be copied into the
+            target container it is re-encoded to the container default (webm -> opus) and
+            reported in dropped_options. A NON-default codec the resolved container cannot
+            carry (e.g. aac on a webm target) is rejected.
         audio_bitrate:
           type: enum
           value_type: integer

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.83.0",
-  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.218.0.",
-  "gislContractsSpec": "v2.218.0",
+  "version": "0.84.0",
+  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.219.0.",
+  "gislContractsSpec": "v2.219.0",
   "license": "Apache-2.0",
   "homepage": "https://docs.giveitsmaller.com",
   "bugs": {
@@ -32,6 +32,7 @@
     "./asyncapi/events.yaml": "./asyncapi/events.yaml",
     "./resolution-bands.yaml": "./resolution-bands.yaml",
     "./anonymous-policy.yaml": "./anonymous-policy.yaml",
+    "./pricing-policy.yaml": "./pricing-policy.yaml",
     "./availability/availability.json": "./availability/availability.json",
     "./accepted-options/accepted-options.json": "./accepted-options/accepted-options.json",
     "./accepted-options/image-output-routes.json": "./accepted-options/image-output-routes.json",
@@ -67,7 +68,8 @@
     "operation-capabilities/operation-capabilities.json",
     "code-builder/code-builder-metadata.json",
     "resolution-bands.yaml",
-    "anonymous-policy.yaml"
+    "anonymous-policy.yaml",
+    "pricing-policy.yaml"
   ],
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\"",

package/pricing-policy.yaml

@@ -0,0 +1,82 @@
+# Pricing policy — the ONE declaration of how a workflow is charged
+# (card 8Y2fppO9; owner decisions 610(4) 2026-09-26 and 635 2026-09-29).
+#
+# 1.1.0 (card cDZuuyg8, owner decision 645(4) 2026-09-30): an already-optimised
+# compress is not charged (`charge.not_charged`). Additive.
+#
+# Read by: api (pins its billing constants to it: OperationCostCalculator,
+# CreditReservationService, UserTier::overdraftLimit), the frontend's pricing
+# copy, the SDKs, and tests/test_pricing_policy.py (holds the relations below).
+#
+# ⚠️ CONTRACT-FIRST. Two of these rules are AHEAD of api main 2a8dd8d5, and
+# `api_today` under each says what the API does until it ships the change.
+# A consumer reading this file for a PRICE must not assume the new rule is
+# live until api's release notes say so.
+
+schema_version: "1.1.0"
+
+charge:
+  # Owner 610(4)(a) + 635(1): pay only for successful results, PER JOB.
+  # A job that completes is charged; a job that fails (after its retries) is
+  # refunded, as is cancelled work. A multi-job workflow with one failed job
+  # is charged for the jobs that completed.
+  basis: per_completed_job
+  refunded_on: [job_failed, workflow_cancelled]
+  # A workflow paused for insufficient credits has its reservation RELEASED
+  # at the pause and reserved again on resume (so a pause that expires
+  # unresumed owes nothing). api main: CreditReservationService
+  # releaseForPause / ResumeWorkflowCommandHandler.
+  on_pause: released_then_reserved_again_on_resume
+  # Reserved at create for the whole workflow (402 balance_exhausted if the
+  # caller cannot afford it), settled per job as jobs end.
+  reserved_at: workflow_create
+  # A long-form fan-out is settled at what it actually used; the unused
+  # part of its worst-case reservation is refunded.
+  fan_out_settlement: actual_usage
+  # Owner 645(4): an OPERATION that could not make the file smaller and
+  # returned the original is NOT charged; its cost is refunded. The job's
+  # other operations are charged as usual. Per operation, not per job. The
+  # FULL predicate, all of which must hold (a flag alone is not enough: the
+  # metrics object rides on every result):
+  not_charged:
+    - when:
+        operation_type: compress
+        status: completed
+        route: same_format        # resolved: output_format original/absent OR equal to the input format
+        metric: already_optimal   # metrics.already_optimal == true
+  not_charged_api_today: already_optimal_operations_are_charged
+  # api main 2a8dd8d5 refunds the WHOLE reservation when any job fails, so a
+  # partially_failed workflow is charged nothing (OperationResultHandler
+  # releaseReservationOnFailure). Changing to per-job is api's follow-up.
+  api_today: whole_workflow_refund_on_any_job_failure
+
+upload:
+  # Owner 610(4)(b) + 635(2): uploading costs nothing. Larger files cost more
+  # to PROCESS, through the size surcharge below.
+  charged: false
+
+size_surcharge:
+  # Added to each operation's weight. The size is the JOB's input (its
+  # primary upload), applied to every operation of the job, not each
+  # operation's intermediate input (api CreateWorkflowCommandHandler).
+  basis: job_input_bytes
+  # surcharge per operation:
+  #   surcharge = min(max_credits, floor((bytes - free_bytes) / step_bytes))
+  #   for bytes > free_bytes, else 0.
+  # Binary units: 52,428,800 B = 50 MiB (api OperationCostCalculator).
+  free_bytes: 52428800
+  step_bytes: 52428800
+  credits_per_step: 1
+  max_credits: 500
+
+overdraft:
+  # Owner 610(4)(c) + 635(3). The limit is per account and is returned by
+  # GET /api/v2/credits/balance (`overdraft_limit`), which is the source for
+  # any caller; only the Basic value is policy.
+  basic_limit: 0
+  # Overdraft debt is repaid ONE credit for ONE credit from the next monthly
+  # grant, on every paid plan. There is no per-plan multiplier.
+  repayment_ratio: 1
+  # api main already repays 1:1 (CreditAccount); its unused per-plan
+  # multipliers (UserTier::overdraftRate) are deleted in api's follow-up.
+  api_today: repays_1_to_1_unused_per_plan_multiplier_present