thundercode
/

SatQuery

@@ -1,929 +0,0 @@
-# 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.