release: add docs/API_CONTRACT.md

docs/API_CONTRACT.md

@@ -0,0 +1,929 @@
+# API Contract (ORIGINAL REFERENCE)
+
+> **STATUS: the project's authoritative API-contract reference**, preserved from the source repository
+> where the documentation-guard tests validate it. It is included here because those tests and several
+> documents refer to it by name.
+>
+> For the **release-facing** description of the same contract — including the shipped topology, the
+> gateway mirror, the error taxonomy and the entrypoint requirements — see
+> [architecture/08-api-contract.md](architecture/08-api-contract.md). Where the two differ in
+> emphasis, that chapter describes the shipped system.
+
+---
+
+# SatQuery AI — Backend API Contract (v1)
+
+**Status:** SPECIFICATION — the backend implementation is described in
+`docs/DEPLOYMENT_ARCHITECTURE.md`; endpoints below are the contract the frontend
+MUST be built against.
+
+**Audience:** the frontend agent (Cloudflare Pages), and any other API consumer.
+
+**Authority:** the request/response **shapes** are not invented here. They are the
+existing, tested Pydantic models in `core/schemas.py`. This document describes
+them; it does not define new ones. Where a shape is described, the model name is
+given so it can be read directly in the source.
+
+---
+
+## 1. Conventions
+
+| Aspect | Value |
+|---|---|
+| Scheme | HTTPS only (the gateway redirects plain HTTP) |
+| Base path | `/v1/` |
+| Content types | Requests: `application/json` (or `multipart/form-data` for image upload). Responses: `application/json` |
+| Character encoding | UTF-8 |
+| Timestamps | ISO 8601 with `Z` offset, e.g. `2026-09-22T04:12:21.000Z` |
+| Field naming | `snake_case` throughout (matches the Pydantic models) |
+| Versioning | Path version (`/v1/`). A change that removes a field, changes a field's type or meaning, or adds a required field moves to `/v2/`. A purely additive field that existing clients can ignore does not bump the version — but see §1.1: because the server forbids unknown fields on **write**, adding an *input* field is a breaking change for old servers, not for old clients |
+| Schema version | Every response carries `schema_version`. Currently `"1.0"` (`core/schemas.py:21`) |
+| Machine-readable errors | Every error body carries a stable `code` string from the taxonomy in §5 |
+
+### 1.1 Unknown fields are REJECTED, on read and on write
+
+**CORRECTED 2026-09-22 (C-2).** This section previously claimed that consumers
+"MUST tolerate unknown fields on read (forward compatibility)" and that only the
+write direction was strict. **That was wrong, and the code is authoritative.**
+
+`ResultEnvelope`, `HealthStatus`, `AnalysisRequest` and every other
+contract-facing model in `core/schemas.py` sets `extra="forbid"` — **with exactly
+one exception, `GeoMetadata`, which sets `extra="allow"`** (see below).
+Pydantic applies `forbid` symmetrically: an unknown field in a request body is a
+`422`, and an unknown field in a response body raised during `model_validate` is a
+`ValidationError`. A client that parses a response through these models does
+**not** get forward compatibility — it gets a hard failure the moment the server
+emits a field it has never heard of.
+
+> **The one exception, and why it is deliberate.** `GeoMetadata`
+> (`core/schemas.py:120`) sets `extra="allow"` and is the **only** model in the
+> codebase that does. It is the geospatial descriptor attached to
+> `AssetMetadata.geo` and `SpecialistResult.geospatial`, so it **is** reachable in
+> every `/v1/analyze` response. The reason is that a raster reader supplies
+> whatever tags the source file carries, and forbidding unknown keys there would
+> discard provenance a caller may need.
+>
+> **What this means for a client.** The strictness rule above holds for every
+> shape *except* the contents of a `geospatial`/`geo` object. A strict validator
+> will reject an unexpected top-level field, but must **not** reject an unexpected
+> key inside `geospatial` — the server may legitimately add one without a version
+> bump. Treat that sub-object as the single open surface in the contract.
+>
+> This exception was recorded in `docs/STEP7_BACKEND_CHAIN_REPORT.md` but had
+> never reached this document, which is the one a client author reads. Recorded
+> here by the STEP 8 audit as finding C-8.
+
+The consequences, stated plainly because they are easy to get wrong:
+
+- **Additive changes are not free.** Adding a field to a response breaks any
+  client that validates strictly. This is why §2.1's `modalities` field could
+  not simply be dropped into the capability entry without recording it here.
+- **A version bump is required** when a field is added, not only when one is
+  removed. The old row in the table above said the opposite; the corrected row
+  says what the code does.
+- **Clients should be written permissively even though the server is strict.**
+  That is a client-side robustness measure, not a server guarantee, and the
+  server must not be documented as if it provided one.
+
+The direction of this correction matters: the *documentation* was the wrong
+half, so the documentation was fixed and `extra="forbid"` was left alone.
+Loosening the schema to match the prose would have replaced a clear failure with
+a silently-ignored field, which is worse for a machine-readable contract.
+
+---
+
+## 2. Endpoints
+
+The surface is **four** endpoints. The plan fixed three; the owner ruling of
+2026-09-22 added the fourth by choosing Option A for upload (§2.5).
+
+| Method | Path | Purpose | Auth |
+|---|---|---|---|
+| `GET` | `/v1/health` | Liveness + which models are loaded | none |
+| `GET` | `/v1/capabilities` | What this deployment can actually do right now | none |
+| `POST` | `/v1/analyze` | Run one analysis request | none (see §7) |
+| `POST` | `/v1/assets` | Upload one image out of band; returns an opaque handle | none (see §7, §2.5) |
+
+---
+
+### 2.1 `GET /v1/health`
+
+Liveness probe. Cheap. **Must not** load a model, must not touch the GPU.
+
+**Response `200`** — shape is `HealthStatus` (`core/schemas.py:392`). This is the
+measured output of a deployment where the CROMA checkpoint is not shipped:
+
+```json
+{
+  "status": "degraded",
+  "schema_version": "1.0",
+  "models": {
+    "caption": "not_requested",
+    "change": "not_requested",
+    "change_vqa": "not_requested",
+    "grounding": "not_requested",
+    "optical_sar": "absent",
+    "vqa": "not_requested"
+  },
+  "device": "cpu",
+  "gpu_available": false
+}
+```
+
+**Every capability the registry resolves appears in `models`**, and the set is
+identical to `capabilities[].task` in §2.2 — the two endpoints are generated
+from one source, so they cannot enumerate different capabilities. A key is never
+absent; a capability that cannot be served is reported with a state, not by
+omission.
+
+| Field | Type | Notes |
+|---|---|---|
+| `status` | `"ok" \| "degraded" \| "error"` | `degraded` = the service is up but at least one capability is not servable. **Derived, not asserted**: any `absent` capability makes the service `degraded`; any `unavailable` makes it `error` |
+| `schema_version` | `string` | Always present |
+| `models` | `object<string,string>` | Per-capability state. Values are **strings, not booleans**, so a reason can be carried. See §2.3 for the vocabulary |
+| `device` | `string \| null` | `"cpu"`, `"cuda"`, `"mps"`, or `null` if unknown |
+| `gpu_available` | `boolean` | Whether a CUDA/MPS device was detected. `false` is normal on ZeroGPU Spaces until a request is executing |
+
+> **`device` is a closed set, and `null` means the value was not understood.**
+> **F-8, corrected here (2026-09-22).** This row has always published four
+> legal values, but the reader accepted **any** string and echoed it into the
+> field, so `SATQUERY_DEVICE=garbage` served `{"device": "garbage"}` — a value
+> the frontend has no rendering for. The reader now casefolds and validates
+> against the set above; anything unrecognised is served as `null`.
+> `null` is deliberately **not** a silent `"cpu"`: reporting the CPU because the
+> operator mistyped would be a false statement about the deployment, and it is
+> the same mistake that F-7 fixed in a different variable.
+> The case of the operator's input is also no longer significant: before this
+> fix `SATQUERY_DEVICE=CUDA` resolved differently from `SATQUERY_DEVICE=cuda`,
+> which let one payload claim `gpu_available: true` alongside `device: "CUDA"`.
+>
+> **Invariant the frontend may rely on:** if `device == "cuda"` then
+> `gpu_available` is `true`. The converse does **not** hold — a GPU may exist
+> while `device` is `"cpu"` (the operator chose it, or the config did).
+
+**Important for the frontend:** `gpu_available: false` on a ZeroGPU Space is
+**expected**, not an error. ZeroGPU allocates the GPU only for the duration of a
+decorated call. Do not surface this as a fault.
+
+This endpoint is answered **without loading any model and without importing
+torch** — the device is resolved from configuration, not by probing the runtime.
+A liveness probe that built the world would consume GPU quota to say "I am
+alive".
+
+---
+
+### 2.2 `GET /v1/capabilities`
+
+What the deployment can do **right now**, derived from actual artifact presence —
+not from what the code could theoretically do.
+
+**Every capability the registry resolves is listed**, including ones this
+deployment cannot serve. A capability that cannot be served is reported
+`available: false` with a reason, never omitted: omitting it would make it
+invisible to the frontend, which cannot disable an affordance it was never told
+about.
+
+**Response `200`** — this is the measured output of a deployment where four of
+the six capabilities lack their runtime dependencies and `optical_sar` lacks its
+CROMA checkpoint:
+
+```json
+{
+  "schema_version": "1.0",
+  "capabilities": [
+    {
+      "task": "change",
+      "available": true,
+      "reason": null,
+      "requires_pair": true,
+      "max_assets": 2
+    },
+    {
+      "task": "change_vqa",
+      "available": true,
+      "reason": null,
+      "requires_pair": true,
+      "max_assets": 2
+    },
+    {
+      "task": "optical_sar",
+      "available": false,
+      "reason": "the CROMA backbone checkpoint (CROMA_base.pt) is not present in this deployment; without it optical/SAR fusion degrades to sensor-only; the trained optical/SAR fusion head is not present in this deployment; without it no fused prediction is produced",
+      "requires_pair": true,
+      "max_assets": 2,
+      "modalities": ["optical", "sar"]
+    },
+    {
+      "task": "caption",
+      "available": true,
+      "reason": "the SmolVLM weights are fetched from the Hugging Face Hub on first use and no local checkpoint_path is configured in this deployment",
+      "requires_pair": false,
+      "max_assets": 1
+    }
+  ],
+  "deployment": {
+    "platform": "huggingface-spaces",
+    "zerogpu": true,
+    "lazy_load": true,
+    "cache_max_models": 1,
+    "torch_compile": false
+  }
+}
+```
+
+*(Abridged: the real response lists all six. `grounding` and `vqa` are omitted
+here only to keep the example readable. The two reasons shown are verbatim --
+note that `optical_sar`'s names **two** missing artifacts, because two are
+required and both are absent.)*
+
+| Field | Type | Notes |
+|---|---|---|
+| `capabilities[].task` | `string` | One of the `Task` enum values (§3.1) |
+| `capabilities[].available` | `boolean` | Whether the task can be served on this deployment **right now** |
+| `capabilities[].reason` | `string \| null` | **Required when `available` is `false`.** A bare `false` with no reason is not compliant |
+| `capabilities[].modalities` | `string[]` | **Optional; present only for `optical_sar`.** Valid pairings for a modality-sensitive task |
+| `capabilities[].requires_pair` | `boolean` | Whether two assets are required |
+| `capabilities[].max_assets` | `integer` | Maximum assets accepted |
+| `deployment.platform` | `string` | Deployment target, e.g. `"huggingface-spaces"` |
+| `deployment.zerogpu` | `boolean` | Whether GPU work runs under ZeroGPU's per-call allocation |
+| `deployment.lazy_load` | `boolean` | `true` means models load on first use; this is what makes `not_requested` the normal state (§2.3.1) |
+| `deployment.cache_max_models` | `integer` | Resident-model cap. `1` means requests serialize — see the obligation below |
+| `deployment.torch_compile` | `boolean` | Always `false`. `torch.compile` is unsupported on ZeroGPU and the config loader hard-fails on `true` (finding C-8). Echoed here so an operator can confirm the constraint from a single response |
+
+**A `reason` on an *available* capability is not a defect.** Three capabilities
+above are `available: true` and still carry a reason — it reads
+*"…fetched from the Hub on first use, no local checkpoint configured"*. That is
+not an error; it is a disclosure that the first request will be slow and will
+need egress. A frontend that treats a non-null `reason` as a failure will
+mislay every cold start.
+
+**Contract obligations:**
+- The frontend **MUST** build its UI affordances from this response, not from a
+  hardcoded list. A capability that is `available: false` must be shown as
+  disabled **with its `reason` displayed** — never hidden, never silently
+  downgraded to a different task.
+- The deployment block echoes `configs/deploy.yaml`. Note `cache_max_models: 1`:
+  at most one model is resident. Concurrent requests for different specialists
+  will evict each other, so **the frontend must not assume parallel throughput**.
+
+---
+
+### 2.3 Capability state vocabulary
+
+Used in `GET /v1/health` → `models`, and consistent with `capabilities`.
+
+**These five words are the complete permitted vocabulary.** They are the
+contract's vocabulary and are **not** the registry's — see §2.3.1.
+
+| Value | Meaning |
+|---|---|
+| `"loaded"` | Resident and ready |
+| `"absent"` | The artifact is not present in this deployment. Permanent for this revision; not retryable |
+| `"unavailable"` | Present but could not be loaded (corrupt, incompatible, dependency missing). **This is a defect**, distinct from `absent` |
+| `"not_requested"` | Nothing has attempted to load it yet (normal with `lazy_load: true`) |
+| `"evicted"` | Was loaded, was unloaded to make room (`cache_max_models: 1`) |
+
+`absent` and `unavailable` **must not be conflated** in the UI. Absent means "this
+build does not ship it"; unavailable means "this build ships it and it is broken".
+
+---
+
+#### 2.3.1 Why there is a translation layer, and what it must never leak
+
+**Added 2026-09-22 by owner ruling.** This is the section that explains the
+otherwise-odd fact that the system has *two* capability vocabularies.
+
+The registry — the component that resolves specialists — speaks a different
+language from this contract.
+
+**The adapter derives the contract state; it does not read a live registry
+state.** This is the one fact about the layer that is easy to get backwards, so
+it is stated first. `app/deployment.py` inspects the registry's declared **spec
+table** and the **filesystem** and derives the contract state from what it
+finds. It never calls `build()`/`build_all()`, because requirement 4
+(`DEPLOYMENT_ARCHITECTURE.md` §3.3) forbids loading a model to answer a metadata
+request. A live registry state is therefore *not observable* on this path, and
+the registry's word is reconstructed from the contract state — not translated
+into it.
+
+That inversion has one visible consequence: **`loaded` is never emitted, and
+neither is `degraded`.** A capability whose artifacts are all present and which
+has not yet been asked for is reported `not_requested`, not `loaded`, because
+"a model is resident" is a claim no process can honestly make without having
+loaded it. The following table is exhaustive — it lists every state the adapter
+can produce:
+
+| Contract state | When it is emitted | `available` | Why |
+|---|---|---|---|
+| `not_requested` | All declared shipped artifacts are present, and nothing has attempted a load. **The normal healthy state under `lazy_load: true`** | `true` | Nothing is missing. Emitting `loaded` here would claim a model was resident, which cannot be known without loading one (requirement 4) |
+| `absent` | A required shipped artifact is not on disk in this deployment | `false` | Nothing is broken; the deployment does not ship it. The reason names the specific artifact |
+| `unavailable` | Construction was attempted in this process and failed (defect path only) | `false` | Present but broken — a genuine defect, which the contract keeps distinct from `absent` |
+| `evicted` | *(never emitted)* | — | A runtime model-cache fact. No static inspection can observe it, so the server never claims it |
+| `loaded` | *(never emitted)* | — | See above. Note the vocabulary is closed, so a client must still be prepared to read it if a future revision emits it |
+
+> **`available: true` and `models: "not_requested"` coexist by design, and that
+> is not a contradiction.** The two fields answer different questions:
+> `available` is "can this deployment serve this capability?" and `not_requested`
+> is "has anything loaded it yet?". Under `lazy_load: true` the healthy answer to
+> the second is *no, not yet* — for every capability, including ones that will
+> work perfectly on the first request. A frontend that treats `not_requested` as
+> a fault will mislabel a fully working deployment.
+
+Two consequences the frontend must internalise:
+
+1. **`unavailable` means the opposite thing on each side of the layer.** To the
+   registry it is "no builder could be constructed" — a benign state that
+   includes simply not having the artifact. To this contract it is "present but
+   broken, therefore a defect". The same spelling, opposite severity. This is
+   precisely why the layer exists, and why the table above is the only
+   definition a client may rely on. Note the important corollary: the benign
+   registry meaning *does not* surface as `unavailable` here — a missing
+   artifact surfaces as `absent`, which is a different word and a different
+   remedy.
+2. **A capability is never omitted for being unservable.** It is reported
+   `available: false` with a reason. The registry resolves six capabilities
+   regardless of what this host can run.
+
+The registry's own vocabulary is **internal** and is never served on any
+endpoint. `/v1/health` and `/v1/capabilities` are the only sources a client
+needs, and both are generated from the contract vocabulary above.
+
+---
+
+### 2.4 `POST /v1/analyze`
+
+Run one analysis. This is the only endpoint that can consume GPU quota.
+
+#### Request (JSON)
+
+Shape is `AnalysisRequest` (`core/schemas.py:374`). `extra="forbid"`.
+
+```json
+{
+  "assets": ["asset_0", "asset_1"],
+  "query": "How has the built-up area changed between these two dates?",
+  "force_task": "change_vqa",
+  "run_id": "9f2c1c0e-4a5b-4f5e-9a2c-1b3d4e5f6a7b"
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `assets` | `string[]` | **yes** | Minimum length 1. Values are **asset handles returned by the upload step** (§2.5), not base64 and not URLs |
+| `query` | `string` | **yes** | Natural language. Empty string is permitted by the schema but will route to an `unsupported_query` error in practice |
+| `force_task` | `string \| null` | no | One of the `Task` values (§3.1). Bypasses the intent router |
+| `run_id` | `string \| null` | no | Client-supplied correlation id. If omitted the server generates one. **The server always echoes a `run_id` in the response**, so the client should record whichever value comes back |
+
+#### Request (`multipart/form-data`) — the upload path
+
+When images are uploaded directly, use:
+
+```
+POST /v1/analyze
+Content-Type: multipart/form-data
+```
+
+| Part | Type | Notes |
+|---|---|---|
+| `assets` | file, repeatable | 1–2 image files. Field name repeats for the pair |
+| `request` | text | A JSON string of the `AnalysisRequest` body with `assets` omitted |
+
+> **Not yet implemented.** The multipart entry point is part of the gateway's
+> contract but the reference implementation serves the JSON form only. See
+> §8 for the status boundary. Build the frontend against the JSON form, which
+> pairs with `POST /v1/assets`.
+
+---
+
+### 2.5 `POST /v1/assets` — **IMPLEMENTED** (Option A)
+
+> **Superseded decision record.** The paragraphs below originally recorded this
+> endpoint as an unresolved gap with two options. The owner ruling of
+> 2026-09-22 chose **Option A** (out-of-band upload with opaque ephemeral
+> handles). The endpoint is built and is part of the served surface. The
+> original reasoning is retained verbatim underneath, because the reason the
+> fourth endpoint exists at all is the argument in it.
+
+`AnalyzeRequest.assets` is `list[str]` — asset *handles*, not bytes — and the
+plan defines no upload endpoint. Those two facts cannot both hold without a
+fourth endpoint, so there is one.
+
+**Request.** `multipart/form-data` with exactly one part, the file. The
+`Content-Type` of the part is the declared type.
+
+**Response `201`.**
+
+```json
+{
+  "asset_id": "asset_7c6f64a4a4c821e25d518467a1cc5d47",
+  "content_type": "image/png",
+  "bytes": 20481,
+  "expires_at": "2026-09-22T04:42:21.000Z"
+}
+```
+
+Three guarantees the frontend depends on, and the shape of each:
+
+| Concern | Guarantee |
+|---|---|
+| **Opacity** | `asset_id` is `asset_` + 32 hex characters, from `secrets.token_hex(16)`. It is **128 bits of entropy and carries no information about the upload** — no filename, no type, no index, no position. There is no auth in v1 (§7), so this handle **is** the access control for the uploaded bytes |
+| **Size limit** | A per-file byte cap, configurable per deployment (see §2.5.1). **It is enforced at two layers and a client should rely on both.** The *gateway* refuses an over-limit body from a declared `Content-Length` **and**, since the F-6 fix, while reading the bytes — so omitting the header does not evade it (`gateway/app.py::_read_body_bounded`). The *Space* does the same: since the F-9 fix it refuses while reading via the shared `gateway/assets.py::read_body_bounded`, rather than buffering the body and leaving the cap to `store.put()`. **Both layers therefore refuse an over-limit body without holding it in full, and either one alone is sufficient** — a client that reaches the Space directly is covered, not only one that goes through the gateway. An over-limit upload gets `413` and **writes nothing** |
+
+> **F-6, corrected here (2026-09-22).** This row previously read *"enforced on the
+> received bytes — not on a declared `Content-Length`"*. That described the store
+> correctly and the **gateway incorrectly**: at the gateway the cap was applied
+> *only* to the header, because `policy.admit` runs before the body is read and
+> the header is the only evidence it has. Measured through the real ASGI stack
+> with the cap at 8 MiB and a 12 MiB body: a declared `Content-Length` drew `413`
+> (peak 0.2 MiB, 0 bytes read) but an **omitted** one drew `502` with a peak of
+> **13.9 MiB** — the whole body buffered past the cap. Allocation then tracked
+> body size exactly with no ceiling (1/8/16/32/64 MiB in → 3.0/8.1/16.0/32.0/64.0
+> MiB allocated). The gateway now enforces the cap while reading, and pinning
+> tests assert both the refusal and that the boundary is still inclusive at
+> exactly the cap.
+
+> **F-7, corrected here (2026-09-22).** The cap is set by **one** variable,
+> `SATQUERY_MAX_FILE_BYTES`, read by **both** layers — and until this fix each
+> layer **parsed it separately**, so "one variable" did not mean "one value".
+> Measured on four inputs (probe `probe_f7_cap_parsers.py`): `'abc'` and `'4e6'`
+> made the gateway **raise at startup** while the Space **silently returned the
+> 4 MiB default**; `'0'` and `'-1'` were **accepted** by the gateway while the
+> Space rejected them only when the first upload arrived. Neither layer was right
+> in both directions. Both now refuse an unparsable **or non-positive** value,
+> naming the variable, and a cross-layer agreement test drives the whole matrix
+> through both real parsers. A deployment whose cap is malformed no longer starts
+> at all, at either layer, instead of quietly running on a limit nobody chose.
+| **Content-type allowlist** | A **closed list of exactly five types**: `image/tiff` · `image/geotiff` · `image/png` · `image/jpeg` · `application/octet-stream`. A request with **no** declared type is **refused rather than defaulted** — defaulting is how a PDF reaches a raster reader. A disallowed type gets `415`. Media-type parameters are ignored, so `image/tiff; charset=binary` is accepted (`gateway/assets.py::_normalise_content_type`). **`image/tiff` is the type the geospatial specialists need** — a client that uploads only PNG/JPEG can serve the VQA, caption and grounding tasks but not the change or optical/SAR ones |
+| **Retries** | There is **no idempotency key**. A retry is a **new** upload that mints a **new** handle; the previous handle is not reused and is not revoked, it simply lapses on its TTL. A client that retries must therefore use the *latest* handle, and should expect the abandoned one to occupy a slot until it expires |
+
+**Errors.** `413` over the size limit · `415` unsupported or absent content
+type · `503` the asset store is not configured on this deployment · `400` for a
+malformed body. All use the §5 envelope.
+
+**Lifetime.** Handles expire on a TTL and are **refused on read** once lapsed —
+a lapsed handle is rejected even if nothing has swept it, so a client never
+succeeds by racing a cleanup job. Capacity is bounded, and **a live handle is
+never evicted to make room**: when the store is full it refuses (`503`) rather
+than invalidating a handle a client is about to use. A handle is single-use in
+practice — consuming it in `/v1/analyze` does not consume it, so the same handle
+may be analysed repeatedly until it expires.
+
+**What `asset_id` is not.** It is not a path, and the response never discloses
+one. The stored filename is derived from the **content type**, never from the
+client's filename, so a client-supplied `../../` cannot influence where bytes
+land.
+
+---
+
+#### 2.5.1 Original decision record (retained)
+
+The gap this section originally recorded was stated as **"NOT IN THE PLAN"**: the
+plan fixes the surface at three endpoints, none of which accepts a file, yet
+`AnalyzeRequest.assets` is `list[str]` of handles. Both cannot be true without a
+fourth endpoint. The phrase is preserved here because it is the finding, and a
+decision record that deletes the problem it solved is not a record.
+
+| Option | Shape | Trade-off |
+|---|---|---|
+| **A. Out-of-band upload** — **CHOSEN** | `POST /v1/assets` → `{"asset_id": "...", "expires_at": "..."}`. Frontend uploads first, then calls `/v1/analyze` with the returned ids | Keeps `/v1/analyze` JSON-only and lets the gateway enforce a size limit *before* the JSON body is parsed. Costs one extra round trip |
+| **B. Inline multipart** — not chosen | `/v1/analyze` accepts `multipart/form-data` directly (§2.4) | One round trip. Couples upload and analysis; a retry re-uploads |
+
+The three things the frontend needs — *a per-file size limit, a content-type
+allowlist, and an idempotency story for retries* — are specified in the table
+above. Note that "idempotency story" resolved to "there is none, a retry mints a
+new handle", which is a decision rather than an omission: with no request key in
+the contract, a deduplicating server would have to hash payloads, and a
+content-hash handle is exactly the guessable identifier §2.5 forbids.
+
+---
+
+#### Response `200`
+
+Shape is `ResultEnvelope` (`core/schemas.py:383`).
+
+```json
+{
+  "run_id": "9f2c1c0e-4a5b-4f5e-9a2c-1b3d4e5f6a7b",
+  "schema_version": "1.0",
+  "result": {
+    "task": "change_vqa",
+    "answer": "The built-up area increased...",
+    "labels": [],
+    "regions": [],
+    "boxes": [
+      {
+        "x1": 0.12, "y1": 0.34, "x2": 0.56, "y2": 0.78,
+        "label": "expanded built-up area",
+        "score": 0.81,
+        "coordinate_system": "normalized_0_1"
+      }
+    ],
+    "masks": [],
+    "change_map": null,
+    "evidence": [
+      {
+        "evidence_id": "ev_001",
+        "type": "change_map",
+        "score": 0.72,
+        "source_specialist": "change_vqa",
+        "coordinate_system": "normalized_0_1",
+        "coordinates": [0.12, 0.34, 0.56, 0.78],
+        "artifact_ref": null,
+        "payload": {}
+      }
+    ],
+    "confidence": {
+      "raw": 0.991,
+      "calibrated": 0.987,
+      "method": "temperature_scaling",
+      "components": {},
+      "degraded": false,
+      "degradation_reason": null
+    },
+    "geospatial": {},
+    "execution_trace": null,
+    "schema_version": "1.0",
+    "warnings": [],
+    "degraded": false
+  },
+  "trace": {
+    "run_id": "9f2c1c0e-4a5b-4f5e-9a2c-1b3d4e5f6a7b",
+    "task": "change_vqa",
+    "intent": null,
+    "query": "How has the built-up area changed?",
+    "modalities": ["optical"],
+    "workflow": [],
+    "steps": [],
+    "timings": {},
+    "selected_models": [],
+    "parameters": {},
+    "config_hash": "78f1e3700da15aa1",
+    "inputs": [],
+    "outputs": [],
+    "errors": [],
+    "fallbacks": [],
+    "contradiction": false,
+    "validation": {},
+    "confidence": null,
+    "started_at": "2026-09-22T04:12:21.000Z",
+    "finished_at": "2026-09-22T04:12:29.400Z",
+    "schema_version": "1.0"
+  }
+}
+```
+
+> `trace` above lists every field `ExecutionTrace` defines. Fields left `null` or
+> empty here are genuinely optional, not omitted from the contract — the model
+> uses defaults, so they will normally be **present** in a real response. The
+> frontend should read only the ones it needs and tolerate the rest.
+
+#### The fields the frontend must read correctly
+
+| Field | Why it matters |
+|---|---|
+| `result.confidence.value` | **NOT a JSON field.** It is a Python `@property` on `ConfidenceBreakdown` and is **not serialised** (verified: `model_dump()` yields only `calibrated, components, degradation_reason, degraded, method, raw`). To get the number the user should see, read `calibrated` if it is non-null, otherwise `raw` |
+| `result.confidence.method` | `"uncalibrated"` or `"temperature_scaling"`. See §4 |
+| `result.confidence.degraded` / `degradation_reason` | Whether the confidence is trustworthy. **Display the reason verbatim when set** |
+| `result.degraded` + `result.warnings` | The result is served but something was degraded. Warnings are for the operator, not the end user |
+| `result.answer` | `""` for non-VQA tasks. Empty is valid |
+| `result.boxes[].coordinate_system` | **Read this per box.** See §3.2 |
+| `result.boxes[]` flat geometry | `x1, y1, x2, y2` are **flat fields on the box**, not a nested `box` object. `Region` is the one with a nested `box` |
+| `result.evidence[]` shape | Every evidence item carries: `evidence_id` (unique within a result), `type`, `score`, `source_specialist`, `coordinate_system`, `coordinates`, `artifact_ref`, `payload`. Note `score` — not `value` — and `source_specialist` — not `source`. **`artifact_ref` is always `null` in v1** — see "Artifact refs — `null` in v1, and why" above |
+| `result.evidence[].type` | One of 11 `EvidenceType` values: `image_crop`, `tile`, `bounding_box`, `mask`, `change_map`, `optical_view`, `sar_view`, `joint_feature_region`, `statistic`, `geolocation`, `availability_mask` |
+| `trace.steps[].state` | `ControllerState` — the pipeline stage. `detail` and `duration_ms` accompany it |
+| `trace.steps` | Observable facts only. **Never chain-of-thought** (plan section 26). Safe to display |
+| `trace.config_hash` | The frozen config identity. `78f1e3700da15aa1` for this revision |
+
+#### Artifact refs — `null` in v1, and why
+
+**Every `artifact_ref` and `change_map` in a v1 response is `null`.** This is a
+deliberate contract, not a missing value.
+
+F-16 (owner ruling 2026-09-23): **never expose filesystem paths.** The
+specialists *do* render their artifacts — the change map and the optical/SAR
+views are written server-side — but their location is an operator fact, not a
+client-facing one. A response that carried the server's path would disclose the
+deployment's directory layout to an unauthenticated caller, and nothing the
+frontend can do requires it.
+
+**No `artifact://` URI is fabricated in its place.** v1 has **no
+artifact-serving endpoint**, so a URI would be a promise the service cannot
+keep — strictly worse than `null`, because the frontend would build a link that
+404s. The earlier revision of this document showed
+`"artifact_ref": "artifact://run/9f2c.../change_map.png"`; no production file
+ever emitted one, which is exactly how the divergence survived. The example
+above now shows the ruled shape.
+
+What replaces the ref:
+
+| Removed | Replaced by |
+|---|---|
+| `change_map` path | `null`, plus the change statistics in the CHANGE_MAP evidence's `payload` (`total_change_pixels`, `n_components_kept`, `threshold`) |
+| view `artifact_ref` path | `null`, plus `payload.rendered` / `payload.retrievable` / `payload.retrieval` |
+| — | an explicit `warnings[]` entry saying the artifact is **NOT retrievable** |
+
+The frontend must therefore treat `artifact_ref` as **always `null` in v1** and
+read the payload statistics instead. A non-null ref appearing here in future
+means an artifact-serving endpoint was added, and this section changes with it.
+
+---
+
+## 3. Enumerations
+
+These are fixed by `core/schemas.py`. The frontend must treat them as closed sets
+for display, but **must not assume they will never grow** — an unknown value
+should render as its raw string, not crash.
+
+### 3.1 `Task` (`core/schemas.py:35`)
+
+Seven values. Note `unsupported` is a `Task`, not an error — it is how "I do not
+know what you asked" is represented.
+
+| Value | Meaning | Assets |
+|---|---|---|
+| `vqa` | Answer a question about one image | 1 |
+| `caption` | Describe the image | 1 |
+| `grounding` | Locate a described object | 1 |
+| `change` | Detect change between two dates | 2 |
+| `optical_sar` | Fuse optical and SAR | 2 |
+| `change_vqa` | Answer a question about the change | 2 |
+| `unsupported` | The router could not map the request to a specialist | 0 |
+
+### 3.2 Coordinate systems
+
+`CoordinateSystem` is an explicit enum on every spatial field. **This is a
+correctness-critical distinction** and a documented source of silent bugs.
+
+| Value | Meaning | Rendering |
+|---|---|---|
+| `normalized_0_1` | `[0, 1]`, origin **top-left** | Multiply by image width/height |
+| `pixel` | Absolute pixel coordinates | Use directly |
+| `geo` | CRS coordinates (usually EPSG:4326) | Requires a map, not a 2-D canvas |
+
+VRSBench annotations arrive normalised to **0–100**, not 0–1;
+`evaluation.metrics.grounding.benchmark_to_normalized` performs the conversion.
+**The frontend must read the `coordinate_system` field on each `Box`/`Region` and
+must not assume one convention.** A box drawn with the wrong assumption lands in
+plausible-looking wrong places.
+
+> The raw enum values are the exact strings above. Earlier drafts of this document
+> used shorthand (`normalized`, `geographic`); those are **wrong** and would fail
+> schema validation, since `extra="forbid"` and the enum is closed.
+
+### 3.3 `Modality` (`core/schemas.py:50`)
+
+| Value | Meaning |
+|---|---|
+| `optical` | Optical only |
+| `sar` | SAR only |
+| `optical_sar` | Both fused |
+| `unknown` | Undetermined |
+
+---
+
+## 4. The confidence contract
+
+This is the subtlest part of the API and the easiest to mis-render.
+
+`ConfidenceBreakdown` (`core/schemas.py`) has:
+
+| Field | Meaning |
+|---|---|
+| `raw` | The uncalibrated score |
+| `calibrated` | The post-calibration score, or `null` |
+| `method` | `"uncalibrated"` or `"temperature_scaling"` |
+| `components` | A `string -> float` map of the individual signals that fed the confidence. May be empty. **Diagnostic only** — do not compute a confidence from it |
+| `degraded` | Whether this confidence should be trusted |
+| `degradation_reason` | Why, when `degraded` is `true` |
+
+**Rules the frontend MUST follow:**
+
+1. Display `calibrated` when it is not `null`; otherwise display `raw`.
+2. Display `method` next to the value. `temperature_scaling` means a fitted
+   correction was applied; `uncalibrated` means it was not.
+3. **Never present a confidence as a percentage without its method.** A raw
+   0.99 and a calibrated 0.99 do not mean the same thing.
+4. When `degraded` is `true`, show `degradation_reason`. Confidence that is
+   degraded is not a quality signal.
+
+> **Measured caveat, recorded honestly.** The R-02 calibration fit
+> (`artifacts/calibration_v001.json`, `T = 0.9772731820958189`, 16,441 Val rows)
+> found that the raw softmax was **already near-calibrated** (ECE 0.013755) and
+> that temperature scaling made ECE very slightly **worse** (0.014929) while
+> improving NLL marginally (0.689741 → 0.689631). The frontend must not imply
+> that `temperature_scaling` is inherently "more accurate" than `uncalibrated`.
+
+---
+
+## 5. Error contract
+
+Every non-2xx response body has this shape:
+
+```json
+{
+  "error": {
+    "code": "pair_misaligned",
+    "message": "The images are not sufficiently co-registered for spatial analysis.",
+    "detail": "RMSE 4.21 px exceeds the 2.0 px budget",
+    "recoverable": false,
+    "request_id": "req_01H...",
+    "run_id": "9f2c1c0e-..."
+  }
+}
+```
+
+`code` is **stable** and comes from `core/errors.py`. `message` is
+operator-safe (`SatQueryError.user_message`). `detail` is technical and may be
+absent.
+
+### 5.1 HTTP status mapping
+
+| Status | When | `recoverable` |
+|---|---|---|
+| `400` | Malformed JSON, missing required field, or a malformed upload body | `false` |
+| `404` | The path is not an endpoint at all (`routing_error`) | `false` |
+| `405` | The path exists but not for this method (`routing_error`). `GET /v1/assets` is the common case: §2.5 defines it for `POST` only | `false` |
+| `413` | Upload exceeds the per-file size limit | `false` |
+| `415` | Upload's content type is absent or not on the allowlist | `false` |
+| `422` | Schema violation (unknown field with `extra="forbid"`, wrong enum value, `assets` empty) | `false` |
+| `429` | Rate limited. Honours `Retry-After` | `true` |
+| `500` | Unexpected internal failure | `false` |
+| `503` | A required model is `absent` or `unavailable`; or GPU quota exhausted; or the asset store is unconfigured or full | depends |
+| `504` | The specialist exceeded its budget (`specialist_timeout`) | `true` |
+
+`413` and `415` are upload-only (`POST /v1/assets`). A `415` is the expected
+answer to an upload with no declared `Content-Type` — the server refuses rather
+than guessing (§2.5).
+
+**`404` and `405` carry this same envelope**, which is worth stating because they
+are the two statuses a proxy framework raises before any handler runs. A client
+should therefore not special-case them: parse `error.code` as usual. This was
+made true on 2026-09-22 (the gateway previously returned the framework's own
+`{"detail": "Not Found"}` for both, which broke any client that assumed §5);
+`docs/STEP8_FINAL_CONFORMANCE_AUDIT.md` records the finding as F-3.
+
+**A trailing slash is a `307`, not an error — and this is a real footgun.**
+Starlette's default `redirect_slashes` behaviour applies: `GET /v1/analyze/`
+answers `307` with `Location: http://<gateway-host>/v1/analyze`. Two consequences
+a client must handle, both verified against the running app on 2026-09-22:
+
+  * The `Location` is built from the gateway's own host, **not** from the client's
+    request URL, so a redirect followed naively after a `POST` may not land where
+    the caller expects. Do not rely on it.
+  * A `307` preserves the method and body, so a `POST /v1/analyze/` will re-send
+    the body to `/v1/analyze` — which is fine, but it is a second request against
+    the rate limiter, and `/v1/analyze` is a `COSTLY_ROUTE`.
+
+**Use exact paths with no trailing slash.** This is also why the runbook's
+`SATQUERY_SPACE_URL` is normalised with a trailing-slash strip
+(`docs/BACKEND_DEPLOYMENT_RUNBOOK.md` §4.1.1).
+
+### 5.2 The complete `code` taxonomy
+
+From `core/errors.py`. The frontend should map these to user-facing copy; the
+`user_message` field is a safe default.
+
+| `code` | Meaning | Suggested UX |
+|---|---|---|
+| `satquery_error` | **Base class** — the fallback when a more specific code does not apply | Generic failure. Treat an unexpected occurrence as a defect |
+| `input_error` | The uploaded input could not be read | Ask the user to re-upload |
+| `raster_read_error` | Not a readable TIFF/GeoTIFF | "This file is not a readable GeoTIFF" |
+| `missing_crs` | No coordinate reference system | "This image has no georeferencing" |
+| `unsupported_bands` | Band layout unsupported | Explain expected bands |
+| `oversized_image` | Exceeds the pixel budget | Offer downsampling |
+| `pair_incompatible` | The two images do not match | Prompt for a better pair |
+| `pair_misaligned` | Not co-registered | Explain alignment requirement |
+| `temporal_pair_invalid` | Two distinct acquisitions required | Ask for a second date |
+| `routing_error` | Request could not be interpreted | Offer `force_task` |
+| `unsupported_query` | No specialist supports this | Show the capability list |
+| `invalid_request` | Inputs do not support the task | Suggest a valid task |
+| `workflow_plan_error` | Workflow could not be planned | Retry; report if persistent |
+| `specialist_error` | A specialist failed | Generic failure |
+| `model_load_error` | A model could not be loaded | **Defect** — surface it |
+| `model_unavailable` | Model not available in this environment | Disable the capability |
+| `out_of_memory` | OOM; retry at reduced resolution | Suggest a smaller image |
+| `specialist_timeout` | Processing timed out | Offer retry |
+| `schema_validation_error` | The system produced a malformed result | **Defect** — always report |
+| `coordinate_error` | Invalid spatial coordinates | **Defect** |
+| `confidence_range_error` | Confidence out of range | **Defect** |
+| `leakage_violation` | A data isolation rule was violated | **Defect** — never user-facing |
+| `benchmark_freeze_error` | The benchmark is not frozen | Evaluation-only |
+
+**Render `user_message` as the default and override specific codes with better
+copy.** Do not invent a mapping from `detail` — it is not stable.
+
+### 5.3 Gateway-origin codes (a separate set from §5.2)
+
+There is exactly **one** code a client can receive that is *not* in the table
+above, and it does not come from `core/errors.py`:
+
+| `code` | Meaning | Suggested UX |
+|---|---|---|
+| `rate_limited` | **Gateway-origin.** The proxy's per-IP rate limit refused the request; it never reached the Space. `429`, and `Retry-After` is set | Wait `Retry-After` seconds, then retry. Not a bug — see §7 |
+
+Why it is a separate set rather than a §5.2 row: `tests/unit/test_gateway_responsibilities.py`
+asserts that §5.2 and `core/errors.py` are in **exact one-to-one correspondence** (23
+codes), and `tests/unit/test_gateway_policy.py` asserts that a gateway-origin code
+may **never** shadow a taxonomy code. Both hold only if the two sets stay
+disjoint — so `rate_limited` is documented here, beside the taxonomy rather than
+inside it, and the correspondence test keeps its meaning.
+
+The gateway mints this code and only for errors that **originate in the
+gateway**; a code arriving from the Space is never replaced. `rate_limited` is
+declared in `gateway/policy.py` (`GATEWAY_ORIGIN_CODES`) because §5.1 maps HTTP
+`429` to "Rate limited" while the `core/errors.py` taxonomy — which covers the
+*analysis* pipeline, not the proxy — assigns that status no code. Recorded here
+on 2026-09-22, after a check of this document found the code reachable by every
+throttled caller yet absent from every client-facing table.
+`docs/PHASE19_FINAL_HARDENING.md` is the implementation record; this is the
+client-facing one.
+
+---
+
+## 6. Latency, quotas and the realities of this deployment
+
+| Constraint | Value | Source |
+|---|---|---|
+| ZeroGPU free tier | 5 GPU-minutes/day | plan section 48; `configs/deploy.yaml` |
+| Declared GPU durations | vqa 20 s · grounding 45 s · change 30 s · optical_sar 45 s | `configs/deploy.yaml` |
+| Resident models | **1** (`cache_max_models: 1`) | `configs/deploy.yaml` |
+| `torch.compile` | **Disabled** — ZeroGPU does not support it (finding C-8) | `configs/deploy.yaml` |
+| Lazy loading | Enabled — first request for a capability pays a cold start | `configs/deploy.yaml` |
+| Server budget | `agent.timeout_seconds` | `configs/base.yaml` |
+
+**Frontend obligations:**
+
+1. **Show a progress state.** A cold start can take tens of seconds. There is no
+   streaming API in v1; the client sends one request and waits.
+2. **Do not poll `/v1/health` aggressively.** Every `/v1/analyze` costs GPU
+   quota; health checks cost CPU. Polling health in a loop is fine; retrying
+   analyze in a loop is not.
+3. **Serialize requests.** With `cache_max_models: 1`, two concurrent analyses
+   for different tasks will evict each other and make both slower. If the UI
+   allows a queue, process it one at a time.
+4. **Handle `429` and `503` as normal states**, not as bugs. Quota exhaustion is
+   an expected condition on the free tier.
+
+---
+
+## 7. Authentication
+
+**There is no authentication in v1.** This is a recorded boundary, not an
+oversight.
+
+Plan section 74 (Production Readiness Boundary) explicitly excludes auth,
+multi-tenancy, distributed queues and autoscaling from scope. Consequently:
+
+- The API must **not** be exposed on the open internet without a gateway-imposed
+  control. The intended control is the Railway gateway (§`docs/DEPLOYMENT_ARCHITECTURE.md`).
+- Any credentials (HF token, gateway allowlist) live **server-side only** and are
+  never sent to the browser.
+- The frontend **must not** embed an HF token, an API key, or any secret. It
+  talks only to the gateway.
+
+**Do not build a login screen.** There is no auth to log into.
+
+### 7.1 CORS
+
+The gateway sets CORS explicitly to the deployed frontend origin. It does not use
+a wildcard. A preflight `OPTIONS` is answered by the gateway, not by the HF Space.
+
+---
+
+## 8. Status of this contract
+
+| Element | Status |
+|---|---|
+| Endpoint surface (`/v1/health`, `/v1/capabilities`, `/v1/analyze`, `/v1/assets`) | **Fixed** — 3 by the plan, the 4th by the owner ruling of 2026-09-22 (§2.5) |
+| Request/response shapes | **Existing and tested** — `core/schemas.py` |
+| Error taxonomy and `code` values | **Existing and tested** — `core/errors.py` |
+| Error envelope (`{"error": {...}}`) | **Specified here.** The gateway must produce it; the Space's own errors are translated by the gateway |
+| `POST /v1/assets` | **Implemented**, Option A, §2.5. Upload against it |
+| Multipart upload into `/v1/analyze` | **Not implemented**, and not chosen — Option B was rejected, §2.5.1 |
+| How the contract is **verified** | `docs/ITEM5_INTEGRATION_SUITE_SCOPE.md` records what the 26-test integration suite proves (the app's *boundary*, in-process) and what only a live deployment can prove (reachability, cold start, memory ceilings). Read it before treating a green `tests/integration` run as evidence about a deployment — **no test in this repository dials a network address**, including this contract's own `/v1/*` examples |
+| Authentication | **Deliberately absent** (plan section 74) |
+| Streaming / progress | **Not in v1** |
+| Rate-limit values | **Not specified by the plan.** The gateway must choose them; ask the maintainer |
+| Asset TTL, size cap and content-type allowlist values | **Deployment configuration**, not contract constants. The *shape* of each guarantee is fixed (§2.5); the *value* is read from the environment per deployment |
+
+**Nothing in the "Status" column above may be treated as settled if it says
+"Not in v1", "Not implemented" or "Not specified by the plan"** — unless the row
+also names a decision that closed it. Those are gaps this document surfaces
+rather than fills.
+
+---
+
+## 9. Minimal frontend integration checklist
+
+1. `GET /v1/health` on load → show service state, including `degraded`.
+2. `GET /v1/capabilities` → build affordances from the response. Disable
+   unavailable tasks **with their reason shown**.
+3. For each analysis: (a) `POST /v1/assets` per image → collect `asset_id`
+   values; (b) `POST /v1/analyze` with `assets`, `query`, optional `force_task`.
+4. Render `result.answer`, then `confidence` per §4, then `result.warnings`
+   and `confidence.degradation_reason` if present.
+5. Draw `boxes`/`regions` using **each item's own `coordinate_system`**.
+6. Map errors per §5. Default to `user_message`; special-case the codes flagged
+   as defects so they are reported rather than swallowed.
+7. Serialize analyses. Do not retry `429`/`503` in a tight loop.
+8. Never embed a secret. Never build a login screen.