docs/API_CONTRACT.md

# 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.