docs/architecture/03-request-lifecycle.md

# 03 — Request Lifecycle

**Parent:** [Architecture hub](README.md) · **Previous:** [02 Deployment topology](02-deployment-topology.md) ·
**Next:** [04 Router](04-router.md)

**Status tags used in this document:** `IMPLEMENTED` · `VERIFIED` · `MEASURED` · `ATTEMPTED` ·
`NOT RUN` · `BLOCKED` · `DEFERRED` · `REJECTED` · `OPEN` · `RESOLVED` · `CLOSED`.

> **One-paragraph summary.** One analysis travels through a **nine-state controller**
> (`core/controller.py`) whose authority is deliberately narrow: it may **refuse** a plan that fails its own
> preconditions, and otherwise it **executes the plan it is given and assembles the result**. It does not
> decide what runs — that is `core/planner.py` alone — and it does not compute what a specialist computes.
> The path is `AnalysisRequest → router.route() → PolicyPlanner.plan() → dispatch → ResultEnvelope`
> (`core/controller.py:10`). Two properties dominate the design and explain almost every line of the file:
> **partial failure never erases evidence** (a failed step becomes a typed `STATISTIC` record and the run
> continues — there is no early exit on step failure), and **confidence is never averaged** (the run's
> confidence is the *primary step's* score, calibrated; a run whose primary specialist failed has **no**
> confidence rather than a laundered one). Three honest gaps are recorded in this document and none are
> papered over: the controller emits **eight** trace states while the config declares **nine**
> (`PREPROCESS` is never recorded); the deployed serving composition **attaches no router**, so
> `force_task` is de facto required on the live path; and the tiling / percentile / dB-clip policy that
> `configs/base.yaml` declares is **read by no code on the serving path**.

---

## Part A — The controller and the nine states

### 1. Where this subsystem sits

#### 1.1 The five verbs

`docs/ARCHITECTURE_FREEZE.md` §5 assigns each layer exactly one verb, and the controller is written to obey
that allocation rather than to be convenient:

| Layer | Verb | Module |
|---|---|---|
| Router | **understands** | `router/classifier.py` |
| Policy engine | **decides** | `core/planner.py` |
| Specialists | **compute** | `specialists/**` |
| VLM | **explains** | `specialists/vqa/inference.py` |
| Evidence engine | **proves** | `evidence/engine.py` |

The controller is the **dispatcher and assembler** that sits between them. `core/controller.py:5-14` states
its own authority verbatim:

> `docs/ARCHITECTURE_FREEZE.md` section 5 gives the control tier two verbs that live here: the controller
> *dispatches* and *assembles*. It does not decide which specialists run — that is `core.planner`'s job
> alone — and it does not compute anything a specialist computes.

#### 1.2 What the controller is, precisely

`AnalysisController` (`core/controller.py:171`) is the only class in the control tier. Its constructor is:

```python
def __init__(
    self,
    *,
    registry: SpecialistRegistry,
    planner: PolicyPlanner,
    router: Any | None = None,
    evidence: Any | None = None,
    config: Any | None = None,
    budget_seconds: float | None = None,
) -> None
```

Four constructor behaviours are load-bearing and each is documented in the source:

1. **`evidence` is built here, and the calibration artifact is loaded here.** When `evidence` is omitted the
   controller constructs `EvidenceEngine.from_config(config, calibration=load_calibration(config))`
   (`core/controller.py:217-221`). Before 2026-09-22 this call passed **no** `calibration=`, so
   `EvidenceEngine` fell back to its `None` default and every confidence the system emitted said
   `method="uncalibrated"` even once a fitted artifact existed. The comment at `core/controller.py:203-216`
   calls that "the single section 67 immutable-decision violation (`calibrated confidence`)" and records it
   as **a wiring gap, not a missing capability**.
2. **`load_calibration` returns `None`, never a fabricated default** — so an artifact-less deployment still
   degrades to the honest pass-through rather than failing to construct.
3. **`budget_seconds` defaults to `config.get("agent.timeout_seconds", DEFAULT_BUDGET_SECONDS)`**, where
   `DEFAULT_BUDGET_SECONDS: float = 120.0` (`core/controller.py:122`) and
   `configs/base.yaml:240` sets `agent.timeout_seconds: 120`.
4. **`specialists.base.SpecialistRequest` is imported lazily inside `_execute_one`, NOT at module scope.**
   The reason is a real import cycle, spelled out at `core/controller.py:106-115`:
   `specialists.base → core.errors → core/__init__ → core.controller → specialists.base (partially
   initialised) → ImportError`.

#### 1.3 The one public entry point

```python
def run(
    self,
    request: AnalysisRequest,
    *,
    assets: Sequence[AssetMetadata] | None = None,
    asset_modalities: Mapping[str, str] | None = None,
) -> ResultEnvelope
```

Its contract, verbatim from `core/controller.py:254-256`:

> Never raises for a specialist-level failure: those are recorded in the result, the trace and the evidence.
> Raises only for a caller error the schema cannot catch.

`health()` (`core/controller.py:396`) is the other public method and is **retired as a public API path**
(H-1/H-2, owner ruling 2026-09-22). It is retained only as an operator diagnostic. Its docstring is worth
quoting because it is the clearest statement of the health-shape defect in the codebase:

> 1. **The shape is not the contract's.** … `GET /v1/health` [is] fixed to `HealthStatus`
>    (`core/schemas.py:392`), which is `extra="forbid"` with the fields `status, schema_version, models,
>    device, gpu_available`. This method returns `registry, degraded, unavailable, device` — so
>    constructing a `HealthStatus` from its output raises `extra_forbidden` on three keys and reports
>    `status`/`gpu_available` missing. That is finding H-1 …
> 2. **The vocabulary is the registry's, not the contract's.** …

The replacement is `app.deployment.deployment_report()`, which **constructs nothing** — "requirement 4 of
`docs/DEPLOYMENT_ARCHITECTURE.md` section 3.3 forbids loading a model for a metadata request. Calling this
from `/v1/health` would spend the 5 GPU-minute daily budget on health probes."

### 2. The nine states — declared versus emitted

This is the single most important honesty point in this document, so it is stated first and precisely.

#### 2.1 The enum has nine members

`ControllerState` (`core/schemas.py:79-88`) — exact spellings, all upper-case:

| # | Member | Value |
|---|---|---|
| 1 | `RECEIVE` | `"RECEIVE"` |
| 2 | `PARSE` | `"PARSE"` |
| 3 | `VALIDATE` | `"VALIDATE"` |
| 4 | `PLAN` | `"PLAN"` |
| 5 | `PREPROCESS` | `"PREPROCESS"` |
| 6 | `EXECUTE` | `"EXECUTE"` |
| 7 | `AGGREGATE` | `"AGGREGATE"` |
| 8 | `VERIFY` | `"VERIFY"` |
| 9 | `RESPOND` | `"RESPOND"` |

`configs/base.yaml:242-251` repeats the same nine names under `agent.states`, and the frontend mirrors them
again in `frontend/assets/js/mission.js:361`:

```javascript
var STATES = ['RECEIVE', 'PARSE', 'VALIDATE', 'PLAN', 'PREPROCESS', 'EXECUTE', 'AGGREGATE', 'VERIFY', 'RESPOND'];
```

So **three** places declare nine states: the schema, the frozen config, and the frontend.

#### 2.2 The controller records eight

`AnalysisController.run()` calls `self._record(trace, ControllerState.X, …)` for exactly **eight** of the
nine. The full set of `ControllerState` writes in `core/controller.py` is:

| Line | State | Context |
|---|---|---|
| `:279` | `RECEIVE` | `{"asset_count": len(request.assets)}` |
| `:302` | `PARSE` | `{"inputs": […], "modalities": […], "query_length": …}` |
| `:316` | `VALIDATE` | `{"assets": …, "force_task": …, "router": …}` |
| `:342` | `PLAN` | `{"plan": plan.to_trace()}` |
| `:569` | `EXECUTE` | budget-skip outcome |
| `:575` | `EXECUTE` | per-step outcome |
| `:371` | `AGGREGATE` | `{"evidence": …, "degraded": …}` |
| `:781` | `AGGREGATE` | refusal path: `{"refused": True, "refusal": …}` |
| `:385` | `VERIFY` | `{"contradiction": …}` |
| `:784` | `VERIFY` | refusal path: `{"steps": 0}` |
| `:391` | `RESPOND` | `{"answer_length": …}` |
| `:787` | `RESPOND` | refusal path: `{"refused": True}` |

**`PREPROCESS` appears nowhere in `core/controller.py`.** A repository-wide search for `PREPROCESS`
returns: `configs/base.yaml:247`, `core/schemas.py:84`, three frontend files, and training-script
identifiers (`PREPROCESSING_VERSION` in `training/change_vqa/dataset.py`) that are unrelated. There is no
`_record(trace, ControllerState.PREPROCESS, …)` anywhere.

#### 2.3 A test pins the eight, and that is deliberate

`tests/unit/test_controller.py:379-395` asserts the observed sequence:

```python
def test_run_records_controller_states_in_order() -> None:
    controller = _controller({"vqa": _stub_class("vqa")()}, task=Task.VQA)
    envelope = controller.run(_request(1))
    states = [s.state for s in envelope.trace.steps]
    assert states[0] is ControllerState.RECEIVE
    assert states[-1] is ControllerState.RESPOND
    for required in (
        ControllerState.RECEIVE,
        ControllerState.PARSE,
        ControllerState.VALIDATE,
        ControllerState.PLAN,
        ControllerState.EXECUTE,
        ControllerState.AGGREGATE,
        ControllerState.VERIFY,
        ControllerState.RESPOND,
    ):
        assert required in states
```

Note the list: **eight** members. `PREPROCESS` is not in it, and the test does not fail on its absence.

#### 2.4 Why `PREPROCESS` exists but is unrecorded — stated honestly

Three things are true at once and none of them is a contradiction:

1. The **policy** names a `PREPROCESS` phase: `configs/base.yaml:242` lists it among `agent.states`, and the
   frontend's stage model expects it (`frontend/assets/js/mission.js:364` maps `SPECIALIST_STARTED →
   'PREPROCESS'`, and `:371` labels it `'awaiting backend'`).
2. **No code reads `agent.states`.** A repository-wide search for `agent.states` in Python returns
   nothing. The list is declared and never consumed, so it cannot drive the controller.
3. **The controller's actual preprocessing happens inside the specialist**, not in a controller state:
   `_execute_one` constructs a `SpecialistRequest`, calls `specialist.validate_request(...)`, then
   `specialist.execute(...)` (`core/controller.py:621-630`). Anything that could be called "preprocessing"
   — raster reading, percentile stretch, band mapping — happens inside `execute`, i.e. inside the `EXECUTE`
   state, and is recorded there as one `EXECUTE` trace step per plan step.

So the honest statement is: **`PREPROCESS` is a declared state with no emitter.** The frontend must render it
from its own client-side model, not from the backend trace. `frontend/assets/js/mission.js:371` already
labels it `'awaiting backend'`, which is consistent with this. Status: `OPEN` (a schema/config/frontend
declaration that the controller does not honour).

```mermaid
flowchart TB
  subgraph Declared["Declared: 9 states (core/schemas.py:79, configs/base.yaml:242, mission.js:361)"]
    R1[RECEIVE] --> P1[PARSE] --> V1[VALIDATE] --> PL1[PLAN] --> PP1[PREPROCESS] --> E1[EXECUTE] --> A1[AGGREGATE] --> VE1[VERIFY] --> RS1[RESPOND]
  end
  subgraph Emitted["Emitted: 8 trace steps (core/controller.py)"]
    R2[RECEIVE :279] --> P2[PARSE :302] --> V2[VALIDATE :316] --> PL2[PLAN :342] --> E2["EXECUTE :569/:575 (one per step)"] --> A2["AGGREGATE :371 / :781"] --> VE2["VERIFY :385 / :784"] --> RS2["RESPOND :391 / :787"]
  end
  PP1 -.->|"NO EMITTER<br/>OPEN"| E2
```

### 3. State-by-state reference

For each state: what it does, what can fail, and exactly what it emits.

#### 3.1 `RECEIVE` — `core/controller.py:258-279`

**Does.** Allocates the run. `started = time.perf_counter()`; `run_id = request.run_id or self._new_run_id()`
where `_new_run_id()` returns `f"run_{uuid.uuid4().hex[:12]}"` (`core/controller.py:1211-1214`). Constructs
the `ExecutionTrace` with `run_id`, `query=request.query`, `inputs=[_asset_label(a) for a in request.assets]`
and `config_hash=self.config.hash if self.config is not None else None`.

**The `inputs` field is a real disclosure fix, not a cosmetic one.** `core/controller.py:263-275` records
that `ExecutionTrace` is returned verbatim by `POST /v1/analyze`, and it previously echoed `request.assets`
*after* the caller had turned asset **handles** into filesystem **paths** — so the response named the
server-side location of every uploaded byte. `_asset_label` (`core/controller.py:1295-1323`) reduces each
entry to `Path(asset).name`, and it is deliberately the **same call** `_resolve_assets` makes when looking a
modality override up by basename, "so the label and the lookup cannot disagree about what an asset is
called." Recorded as **F-13**.

**Fails.** Nothing. This is a pure allocation.

**Emits.**
```json
{"asset_count": 2}
```

#### 3.2 `PARSE` — `core/controller.py:281-308`

**Does.** Resolves the assets into `AssetMetadata`. If the caller passed `assets=` they are used verbatim
("A caller that has already validated rasters should pass them rather than make the controller inspect the
same files twice"); otherwise `_resolve_assets(request, asset_modalities=…)` inspects each one. Then sets
`trace.modalities = self._modalities(resolved)` — *distinct* modalities in first-seen order
(`core/controller.py:524-531`).

**The inspection is header-only by design.** `_resolve_assets` delegates to
`preprocessing.raster.inspect_raster`, "which opens the raster header and reports band count, dtype, CRS,
transform, bounds and resolution. It does NOT decode pixel data — a 12-band Sentinel-2 tile is ~100 MB and a
four-specialist plan would decode it repeatedly" (`core/controller.py:486-489`).

**The docstring records a real historical defect.** An earlier version built `AssetMetadata(path=path)`,
leaving `geo` and `modality` at their defaults, so every asset reached every specialist with
`band_count=None` and `modality=UNKNOWN`. The visible consequence, quoted at `core/controller.py:497-500`:

> a valid 4-band optical + 2-band SAR pair was rejected by `OpticalSarSpecialist.validate_request` with
> "could not identify one optical and one SAR asset from modalities ['unknown', 'unknown']" — a
> user-visible refusal of a perfectly good request.

**Fails.** A missing or unreadable asset raises `RasterReadError` (typed), which the controller surfaces
with a user message. `core/controller.py:503-506` is explicit that it does **not** degrade to an empty
description, "because 'we could not read this' and 'this had nothing to report' must stay distinguishable."

**Also emits the F-14 fix.** The PARSE detail writes `[_asset_label(a) for a in request.assets]`, not
`list(request.assets)`. `core/controller.py:287-299` records the second instance of the same disclosure with
a **measured** example: "the client sent the handle `asset_d243f7f85d8c2f3c02981f0af9737f01` and received
back `C:\Users\anish\sq_scratch\...\assets\asset_d243...7f01.tif`."

**Emits.**
```json
{
  "inputs": ["a.tif", "b.tif"],
  "modalities": ["optical"],
  "query_length": 47
}
```

#### 3.3 `VALIDATE` — `core/controller.py:310-324`

**Does.** Routes. `prediction = self._route(request)`; `trace.intent = prediction.intent if prediction is not
None else None`; `trace.task = prediction.intent.task if prediction is not None else request.force_task`.

**What routing does, and what it does not.** `_route` (`core/controller.py:458-476`) has two branches:

- **`force_task` is set** → the router is **not consulted at all**. It constructs
  `Intent(task=request.force_task, confidence=1.0, source="forced")` and wraps it in
  `RouterPrediction(intent=intent, above_threshold=True)`. The fact that the router's opinion was bypassed is
  therefore *visible in the trace* (`source="forced"`).
- **`force_task` is `None`** → `if self.router is None: return None`, else
  `return self.router.route(request.query)`.

**`return None` is a hard stop downstream.** `core/controller.py:327-334`:

```python
if prediction is None:
    # No router and no forced task: nothing can be planned. This is a
    # caller error, not a query the system declined.
    raise UnsupportedQueryError(
        "no router configured and no force_task supplied; there is no "
        "way to choose a specialist",
        recoverable=False,
    )
```

**This branch is reachable on the live deployment — see §38.** It is a `raise`, not a recorded failure, and
it is the only `raise` in the happy path.

**Emits.**
```json
{
  "assets": 2,
  "force_task": "change_vqa",
  "router": {"task": "change_vqa", "modality": "unknown", "temporal": true,
             "spatial_output": false, "language_output": true,
             "confidence": 1.0, "source": "forced", "above_threshold": true,
             "used_fallback": false, "fallback_rule": null}
}
```

(The `router` value is `RouterPrediction.to_trace()`, `router/classifier.py:93-106`. When routing is forced it
carries the synthesized prediction, so `source` reads `"forced"`.)

#### 3.4 `PLAN` — `core/controller.py:326-345`

**Does.** `plan = self.planner.plan(prediction, request, assets=resolved)`. Then populates
`trace.parameters` with three things:

```python
trace.parameters = {
    **plan.to_trace(),
    "budget_seconds": self.budget_seconds,
    "registry": self.registry.describe(),
}
```

**Fails.** Nothing here — the planner expresses refusal *in the plan*, never by raising
(`core/planner.py:75-81`: "Refusing is not an error. It returns a valid plan with `refused=True` and a typed
`PlanRefusal`"). If `plan.refused` is true the controller takes the early-return refusal path (§4) and
**never reaches EXECUTE**.

**F-19 is visible in this state's neighbourhood.** `core/controller.py:350-365` records that
`registry.describe()` reports the registry's **memoised** entries, so the PLAN-time snapshot reports the
*previous* request's builds while `trace.selected_models` (populated inside `_execute`) reports *this* one.
Measured in pass 13 with two identical payloads on one controller: "request #1 body `built == []`, request #2
body `built == ['optical_sar']`". The fix re-snapshots **after** execution
(`trace.parameters["registry"] = self.registry.describe()`, `core/controller.py:365`) rather than moving the
PLAN-time assignment, "so the PLAN record's own context stays intact and leaves the early-return refusal path
with a snapshot that is still correct — nothing is built on a refusal."

**Emits.**
```json
{"plan": {"steps": [...], "mode": "sequential", "refused": false, "refusal": null,
          "uncertain": false, "router_source": "forced",
          "effective_confidence": 1.0, "notes": []}}
```

#### 3.5 `PREPROCESS` — **declared, never emitted**

See §2.4. Recorded here as a state so the reference is complete, with its status stated:

| Aspect | Value |
|---|---|
| Declared in | `core/schemas.py:84`, `configs/base.yaml:247`, `frontend/assets/js/mission.js:361` |
| Emitted by | **nothing** — no `_record(trace, ControllerState.PREPROCESS, …)` exists |
| Read from config by | **nothing** — `agent.states` is consumed by no Python code |
| Where the work actually happens | inside `EXECUTE`, inside `specialist.execute(...)` |
| Status | `OPEN` |

#### 3.6 `EXECUTE` — `core/controller.py:347-348`, `:535-709`

**Does.** `outcomes = self._execute(trace, plan, resolved, request, started)`. First sets
`trace.workflow = [step.step_id for step in plan.steps]` (`core/controller.py:545`) — the ordered list of step
ids, which is what makes "step_001 produced the grounding box" a reproducible claim.

Then **for each step**, in plan order:

1. **Budget check, between steps** (`core/controller.py:548-571`). `elapsed = time.perf_counter() - started`;
   if `elapsed > self.budget_seconds` the step is **skipped**, not failed:
   `StepOutcome(step=step, skipped_reason=f"budget_exceeded:{elapsed:.1f}s")`. A trace error is appended with
   `"code": SpecialistTimeoutError.code` and `"message": f"skipped: run budget of {self.budget_seconds}s
   exceeded"`. The comment is an explicit design admission:

   > Budget is checked BETWEEN steps (§5.2). A true per-step timeout needs a worker process or a signal
   > handler, both of which conflict with the single-process monolith constraint more than they benefit. The
   > honest position: v1 bounds total wall clock and records what it skipped.

2. **Run the step** (`_execute_one`, `core/controller.py:599-709`):
   - `entry = self.registry.build(step.capability)` — memoised construction.
   - **If `entry.specialist is None`** the step is a recorded failure:
     `error=self._unavailable_error(step, entry)`, which returns a `ModelUnavailableError` whose detail is
     `f"{step.capability} was planned but could not be constructed"`, suffixed with `entry.detail` when
     present (`core/controller.py:711-719`).
   - Otherwise builds `SpecialistRequest(assets=list(assets), query=request.query,
     params=dict(step.params), run_id=trace.run_id)` and calls `specialist.validate_request(...)` **then**
     `specialist.execute(...)` (`core/controller.py:621-630`).
   - `except SatQueryError as exc:` → recorded as the outcome's error, unchanged.
   - `except Exception as exc:` → **wrapped**, never propagated. The exception's own text is *server-side
     only*: it is logged (`_log.error(..., exc_info=exc)`) and preserved in `context`, while the client
     receives a fixed message. `core/controller.py:687-700`:
     ```python
     error=SpecialistError(
         "unhandled error",
         user_message=(
             "The step failed with an unhandled error. Internal "
             "detail is withheld; see the server-side diagnostics."
         ),
         specialist=step.capability,
         context={
             "step_id": step.step_id,
             "code": "unhandled",
             "exception_type": type(exc).__name__,
             "exception_message": str(exc),
         },
     )
     ```
     The **classification survives**: "the client still learns that this was an UNHANDLED failure rather than
     a known typed error. Losing that would hide the difference between 'we predicted this failure mode' and
     'we did not', which is exactly the distinction `code: unhandled` exists to record"
     (`core/controller.py:644-648`).

3. **Record the outcome** — one `EXECUTE` trace step per plan step, via `outcome.to_trace()`
   (`core/controller.py:154-165`):
   ```json
   {"step_id": "step_001", "capability": "change_vqa", "ok": true,
    "skipped_reason": null, "error_code": null,
    "duration_ms": 8421.377, "registry_state": "available"}
   ```
   And `trace.timings[step.step_id] = round(outcome.duration_ms, 3)`.

4. **Record a client-facing error when the step failed** (`core/controller.py:578-594`):
   ```python
   trace.errors.append({
       "step_id": step.step_id,
       "capability": step.capability,
       "code": outcome.error.code,
       "message": outcome.error.user_message or "The step failed.",
       "recoverable": outcome.error.recoverable,
   })
   ```
   The comment records F-15: "the trace is CLIENT-FACING, so it carries the operator-safe message only. It
   previously preferred `error.detail` — the technical text, which can name filesystem paths and library
   internals — over `user_message`."

**There is no early exit.** The loop body has no `break` and no `return`; the only `continue` is the
budget-skip. `core/controller.py:16-20` states the rule and its reason:

> A failed step never removes itself from the result. It becomes a recorded failure with a typed code, and
> the run continues. Nothing aborts the run; there is no early exit on step failure.

**After the loop.** `trace.selected_models = self._selected_models(outcomes)` (`core/controller.py:596`,
`:721-749`). That walks each outcome's *constructed* specialist and calls `specialist.model_refs()`, deduping
on `f"{name}:{role}"` and building explicit `ModelRef` objects rather than relying on pydantic coercion.

**Fails.** Any `SatQueryError` from `validate_request` or `execute`; any unhandled `Exception` (wrapped); a
`ModelUnavailableError` when construction fails. **None of these aborts the run.**

**Emits.** One `EXECUTE` step per plan step (or per skipped step), plus `trace.workflow`, `trace.timings`,
`trace.errors[]` entries, and `trace.selected_models`.

#### 3.7 `AGGREGATE` — `core/controller.py:367-380`, `_aggregate` `:793-834`

**Does.** `result = self._aggregate(trace, plan, outcomes, prediction, request)`.

`_aggregate` merges N step outcomes into one `SpecialistResult`:

```python
successful = [o for o in outcomes if o.ok]
results = [o.result for o in successful if o.result is not None]

failure_evidence = [self._failure_evidence(o) for o in outcomes if not o.ok]

collection = self.evidence.aggregate(results) if results else None
items: list[Evidence] = list(collection.items) if collection else []
items.extend(self._synthesis_evidence(results, request))
items.extend(failure_evidence)
items = self._renumber(items)
```

Three evidence sources are therefore concatenated in a fixed order:

| Source | Producer | When present |
|---|---|---|
| Aggregated specialist evidence | `EvidenceEngine.aggregate(results)` | whenever any step succeeded |
| Synthesis record | `_synthesis_evidence` | only when **≥ 2** results |
| Failure records | `_failure_evidence` | one per non-ok outcome |

**The failure record is the "absence must be distinguishable from a non-event" rule applied at the control
layer** (`core/controller.py:22-29`):

> If a specialist fails and simply does not contribute evidence, a consumer cannot tell whether it ran and
> found nothing, never ran, or crashed. So a failed step adds one `STATISTIC` evidence item carrying its typed
> code. No schema change is needed: `STATISTIC` is already in the frozen `EvidenceType` vocabulary.

`_failure_evidence` (`core/controller.py:865-887`) produces exactly:
```python
Evidence(
    type=EvidenceType.STATISTIC,
    source_specialist=outcome.step.capability,
    score=0.0,
    payload={
        "step_failed": True,
        "step_id": outcome.step.step_id,
        "code": code,
        "message": message,
        "skipped_reason": outcome.skipped_reason,
    },
)
```
`score=0.0` is deliberate and is not a confidence claim: it is a "strength" slot filled with the only honest
value for "this produced nothing."

`_synthesis_evidence` (`core/controller.py:889-916`) returns `[]` when `len(results) < 2`; otherwise one item
attributed to `"controller"`:
```python
Evidence(
    type=EvidenceType.STATISTIC,
    source_specialist="controller",
    score=None,
    payload={"synthesis": True, "contributors": capabilities, "query": request.query},
)
```
Its docstring names the two facts it exists to make visible: "that several specialists were merged into one
answer, and which query they were answering. Neither belongs to any single specialist, so neither can be
attributed to one."

`_renumber` (`core/controller.py:918-929`) rewrites **every** id to `evidence_{i:03d}` starting at 1, because
"the engine's ids stop being authoritative once controller-authored items are appended."

The state's `detail` re-runs aggregation purely to produce a summary — the aggregate call is cheap and pure:

```python
{"evidence": {"returned": 9, "total_before_limit": 9, "dropped_duplicates": 0,
              "dropped_over_limit": 0, "truncated": false,
              "sources": ["change_vqa"], "types": ["change_map", "statistic"]},
 "degraded": false}
```

**Fails.** Nothing directly. A malformed specialist result would already have failed inside `EXECUTE`.

**Emits.** The `AGGREGATE` trace step, and the assembled `SpecialistResult` (fields enumerated in §14).

#### 3.8 `VERIFY` — `core/controller.py:382-385`, `_verify` `:1120-1147`

**Does two things, both real checks.**

**(a) The `sources` assertion.** `core/controller.py:31-41` explains why this is checkable rather than merely
intended:

> `EvidenceEngine.aggregate` records `sources` BEFORE applying its item cap, so a specialist whose evidence was
> capped away still appears. That makes "no specialist ran and left no trace" *checkable* rather than merely
> intended:
>
> ```
> set(collection.sources) == {capability for each successful step}
> ```
>
> A mismatch means a specialist ran and left nothing behind — the exact failure this design exists to
> prevent. It is enforced in the `VERIFY` state as a real assertion, not a comment.

The implementation (`core/controller.py:1124-1141`):
```python
successful = [o for o in outcomes if o.ok and o.result is not None]
if not successful:
    return
collected = self.evidence.aggregate([o.result for o in successful])
expected = {o.capability for o in successful}
observed = set(collected.sources)
missing = expected - observed
if missing:
    trace.errors.append({
        "step_id": "*",
        "code": "evidence_loss",
        "message": f"specialists produced no evidence: {sorted(missing)}",
    })
```

**(b) A fallback note for an evidence-less result** (`core/controller.py:1143-1147`): for each successful
outcome whose result carries no evidence items, `trace.fallbacks.append(f"{outcome.capability} produced a
result with no evidence items")`.

**Then contradiction detection** runs (`self._detect_contradiction(...)`) and the state's `detail` records the
flag:
```json
{"contradiction": false}
```

**Fails.** Nothing. It records.

**Emits.** The `VERIFY` trace step; possibly `trace.errors[]` with `code: "evidence_loss"`; possibly
`trace.fallbacks[]`.

#### 3.9 `RESPOND` — `core/controller.py:387-394`

**Does.** Final assembly:
```python
result.execution_trace = trace
trace.outputs = [e.evidence_id for e in result.evidence]
trace.confidence = result.confidence
self._record(trace, ControllerState.RESPOND, {"answer_length": len(result.answer)})
trace.finished_at = self._now()
return ResultEnvelope(run_id=run_id, result=result, trace=trace)
```

Three things worth naming:

- **`result.execution_trace = trace`** means the trace is reachable **twice** in the serialized envelope —
  once as `envelope.trace` and once as `envelope.result.execution_trace`. They are the same object. The
  registry docstring at `core/registry.py:570-574` measured the consequence of that duplication for the F-15
  disclosure: a single construction failure "put the vendor directory path into **four** client-visible
  fields — `result.warnings[]`, `result.evidence[].payload["message"]`,
  `trace.parameters.registry.built[<cap>].detail`, and the same registry block again inside
  `result.execution_trace` (the trace is the same object, serialized twice)."
- **`trace.outputs`** is a list of *evidence ids*, not a count and not the answer text. It is the citation
  list a consumer follows to inspect what supported the answer.
- **`trace.finished_at`** is the last write. `TraceStep.started_at` defaults to `_utcnow()` at construction,
  so per-state timings are *start* stamps; per-step durations live in `trace.timings`.

**Fails.** Nothing.

**Emits.** `{"answer_length": 218}`, plus the completed `ResultEnvelope`.

### 4. The refusal path — `_finish_refusal` (`core/controller.py:753-789`)

A refusal is **a successful run with no steps**. The docstring is one line: "A refusal is a successful run
with no steps, not an error."

```python
result = SpecialistResult(
    task=trace.task or Task.UNSUPPORTED,
    answer=message,
    confidence=ConfidenceBreakdown(
        raw=0.0,
        calibrated=None,
        method="uncalibrated",
        degraded=True,
        degradation_reason=f"refused:{refusal.reason}" if refusal else "refused",
    ),
    warnings=list(plan.notes),
    degraded=True,
)
trace.fallbacks.extend(plan.notes)
```

Note the exact state sequence on this path — **it skips `PREPROCESS` and `EXECUTE` entirely, and its
`AGGREGATE` detail is different**:

| State | Detail |
|---|---|
| `RECEIVE` | `{"asset_count": n}` |
| `PARSE` | `{"inputs": […], "modalities": […], "query_length": …}` |
| `VALIDATE` | `{"assets": n, "force_task": …, "router": …}` |
| `PLAN` | `{"plan": {…, "refused": true, "refusal": {…}}}` |
| `AGGREGATE` | `{"refused": true, "refusal": {"code": …, "reason": …, "user_message": …}}` |
| `VERIFY` | `{"steps": 0}` |
| `RESPOND` | `{"refused": true}` |

`trace.confidence = result.confidence` and `trace.finished_at` are set, so the refusal envelope is shaped
exactly like any other. `run_id` comes from `trace.run_id` (the one allocated in `RECEIVE`), so the client's
`run_id` is echoed.

**`raw=0.0, calibrated=None, degraded=True`** is the only honest confidence for a refusal: no specialist ran,
so there is no measurement. `degradation_reason` names the refusal rule, e.g. `"refused:task_unsupported"`.

### 5. The budget — total wall clock, checked between steps

| Aspect | Value | Source |
|---|---|---|
| Key | `agent.timeout_seconds` | `configs/base.yaml:240` |
| Frozen value | `120` | `configs/base.yaml:240` |
| Fallback constant | `DEFAULT_BUDGET_SECONDS = 120.0` | `core/controller.py:122` |
| Read at | `core/controller.py:226` | constructor |
| Checked | between steps, `elapsed > self.budget_seconds` | `core/controller.py:553-554` |
| On exceed | step **skipped**, `skipped_reason="budget_exceeded:{elapsed:.1f}s"` | `core/controller.py:555-558` |
| Trace error code | `SpecialistTimeoutError.code` = `"specialist_timeout"` | `core/errors.py:237-239` |

The design admits the limitation rather than hiding it. There is **no per-step timeout**, because a true one
"needs a worker process or a signal handler, both of which conflict with the single-process monolith
constraint more than they benefit" (`core/controller.py:548-552`).

`SpecialistTimeoutError` is `recoverable=True` (`core/errors.py:256-258`) for two independently recorded
reasons: `API_CONTRACT.md` §5.1 maps `504` with `recoverable: true`, and the plan's Failure Matrix lists
Timeout with recovery "abort specialist" and fallback "partial result" — i.e. the controller continues rather
than failing the request.

### 6. Partial failure never erases evidence

The mechanism is three-part and each part is separately testable:

1. **`StepOutcome` retains the failure** (`core/controller.py:135-165`):
   ```python
   @dataclass
   class StepOutcome:
       step: PlanStep
       result: SpecialistResult | None = None
       registry_entry: RegistryEntry | None = None
       error: SatQueryError | None = None
       duration_ms: float = 0.0
       skipped_reason: str | None = None

       @property
       def ok(self) -> bool:
           return self.result is not None and self.error is None
   ```
   Note `ok` requires **both** a result and no error — a step that somehow produced both is not "ok".

2. **`_failure_evidence` converts it to a `STATISTIC` record** (§3.7) so it survives into `result.evidence`.

3. **`_warnings` converts it to a human-readable line** (`core/controller.py:1014-1052`):
   ```
   "{capability} failed ({code}): {scrubbed reason}"
   "{capability} skipped ({skipped_reason})"
   ```
   The reason comes from `_client_error_reason` — **one** shared implementation, deliberately:
   ```python
   @staticmethod
   def _client_error_reason(error: SatQueryError) -> str:
       return scrub_paths(error.detail) or error.user_message
   ```
   `core/controller.py:838-863` explains that three client-visible carriers report a failed step —
   `result.warnings[]`, `evidence[].payload["message"]` and `trace.errors[].message` — and before F-20 two of
   them published an internals string while the third promised the internals were withheld: "The response
   contradicted itself." The repair has two halves: the **producer** stopped putting internals into `detail`,
   and this function exists "so the rule is written ONCE. Two copies of `scrub_paths(detail) or user_message`
   is how a rule drifts: the next fix lands on whichever copy the author happened to open."

   `detail` is preferred over `user_message` on purpose, because "F-15 established that a typed error's
   `detail` is the actionable diagnostic ("... has no builder 'build_x'", "no GPU in this dimension") while
   the base `user_message` is generic, and three tests pin exactly those diagnostics."

### 7. Contradiction detection — represented, never resolved

`_detect_contradiction` (`core/controller.py:1151-1184`) groups every successful outcome's boxes by
`box.coordinate_system.value`, then compares pairs **within one coordinate system**:

```python
for system, boxes in claims.items():
    if len(boxes) < 2:
        continue
    for i in range(len(boxes)):
        for j in range(i + 1, len(boxes)):
            if _iou(boxes[i], boxes[j]) < CONTRADICTION_IOU_FLOOR:
                trace.contradiction = True
                message = (
                    "specialists produced contradictory spatial claims "
                    f"in {system}; both are retained in evidence"
                )
                if message not in result.warnings:
                    result.warnings.append(message)
                return
```

| Constant | Value | Source |
|---|---|---|
| `CONTRADICTION_IOU_FLOOR` | `0.1` | `core/controller.py:119` |

`_iou` (`core/controller.py:1281-1292`) is plain intersection-over-union returning `0.0` when disjoint.

The design rationale (`core/controller.py:60-66`):

> When two specialists make contradictory spatial claims, both are kept and `trace.contradiction` is set.
> Selecting a winner requires a precedence weight, and any such weight is a value judgment with no measurement
> behind it. It also produces a third box that *neither specialist predicted* — a fabricated coordinate.

Two implementation details matter. **Cross-system comparison is skipped** because "IoU across coordinate
systems is meaningless" (`core/controller.py:1161-1162`). And the method **returns after the first
contradiction**, so at most one warning is added per run.

### 8. Confidence is not averaged

`core/controller.py:43-58` states the rule:

> Per-specialist confidences are uncalibrated and are not probabilities. Averaging two uncalibrated
> hand-weighted sums produces a number that is not a measurement of anything.
>
> The aggregate confidence is therefore the confidence of the **primary step** — the step whose capability
> matches the router's predicted task — passed through the evidence engine's calibration, which degrades
> honestly to `method="uncalibrated"`, `calibrated=None` when no artifact is fitted.

`_confidence` (`core/controller.py:1069-1116`):

```python
primary_task = trace.task
primary = next(
    (r for r in results if primary_task is not None and r.task is primary_task),
    None,
)

components: dict[str, float] = {}
for result in results:
    components[f"{result.task.value}_confidence"] = float(result.confidence.raw)

if primary is None:
    return ConfidenceBreakdown(
        raw=0.0,
        calibrated=None,
        method="uncalibrated",
        components=components,
        degraded=True,
        degradation_reason="primary specialist produced no result",
    )

breakdown = self.evidence.confidence_for(
    primary,
    extra_components=components,
    degraded=primary.degraded,
)
if not breakdown.degraded and prediction is not None:
    if not prediction.above_threshold:
        breakdown = breakdown.model_copy(
            update={
                "degraded": True,
                "degradation_reason": "router confidence below threshold",
            }
        )
return breakdown
```

| Aspect | Behaviour |
|---|---|
| The run's score | the primary step's score, calibrated through the engine's artifact |
| Secondary scores | kept, in `components`, **namespaced** `f"{task.value}_confidence"` |
| Primary absent | `raw=0.0`, `calibrated=None`, `degraded=True`, reason `"primary specialist produced no result"` |
| Specialist said degraded | preserved — `degraded=primary.degraded` is passed through |
| Router uncertain | forces `degraded=True` with reason `"router confidence below threshold"` |

The reasoning for the primary-absent branch is stated flatly: "Reporting a secondary specialist's score as the
run's confidence would launder a failure into a number. Secondaries are not discarded — their raw scores
appear in `components`, namespaced by capability. That is measurable and invents no combination rule"
(`core/controller.py:54-58`).

Note that the final router clause applies **only** when the breakdown is not already degraded, so a
specialist-sourced degradation reason is never overwritten by the router's.

### 9. The answer priority list — a list, not a heuristic

`_answer` (`core/controller.py:933-970`) documents itself as "A priority list, not a heuristic (design
§7.3)":

| # | Rule | Produces |
|---|---|---|
| 1 | the first **ok** outcome whose `capability` is `"vqa"` or `"caption"` and whose `result.answer` is non-empty | that answer verbatim |
| 2 | else the non-empty-answer result with the highest `confidence.value` | `f"[{best.task.value}] {best.answer}"` |
| 3 | else any failures | `f"No result could be produced: {named}."` where `named` is `", ".join(f"{capability} ({error.code or 'skipped'})")` |
| 4 | else `plan.refusal.user_message` | the refusal text |
| 5 | else | `"No specialist produced an answer."` |

Rule 1 exists because "The VLM explains, when it ran (freeze §5)" and rule 2 exists because "else the
highest-confidence specialist answer, **attributed**" — the `[task]` prefix is the attribution, and it is
added here, not by the specialist. The closing note is the constraint that keeps this a list:
"No template composes a narrative from evidence: that is the VLM's job, and only when it actually ran."

### 10. Merging rules — four different operators for four different meanings

`_aggregate` calls four distinct merge helpers, and the choice of helper per field is the design:

| Helper | Semantics | Used for |
|---|---|---|
| `_merge_list` | union, order-preserving, deduped | `labels`, `masks` |
| `_concat` | concatenation in plan-step order, **duplicates preserved** | `regions`, `boxes` |
| `_first_non_none` | first non-`None` in result order | `change_map` |
| `_first_geospatial` | first non-empty geo block | `geospatial` |

`_first_geospatial` (`core/controller.py:1000-1012`) is not merged, and the reason is a coordinate-integrity
argument:

> Not merged: merging CRS or transform fields across assets would silently mix two coordinate reference
> systems into one field, which is a coordinate error the schema cannot catch (design §7.2).

Its selection predicate is `geo.has_crs or geo.crs or geo.bounds`; when nothing qualifies it returns a bare
`GeoMetadata()`.

### 11. `_degraded` — three independent triggers

```python
def _degraded(plan, outcomes, results) -> bool:
    if plan.uncertain:
        return True
    if any(not o.ok for o in outcomes):
        return True
    return any(r.degraded for r in results)
```

So a run is degraded when **any** of: the route was uncertain; any step failed or was skipped; any specialist
result was itself degraded. This is the run-level flag; the *capability-level* flag is a separate vocabulary
(§40).

---

## Part B — The shapes

Everything here is from `core/schemas.py`, which is `SCHEMA_VERSION = "1.0"` (`core/schemas.py:21`). The
module docstring states its status: "This module is the binding contract between every component. Per
docs/ARCHITECTURE_FREEZE.md section 3, no specialist may invent its own result shape."

### 12. `AnalysisRequest` — the inbound shape

`core/schemas.py:412-418`:

```python
class AnalysisRequest(BaseModel):
    model_config = ConfigDict(extra="forbid")

    assets: list[str] = Field(min_length=1)
    query: str
    force_task: Task | None = None
    run_id: str | None = None
```

| Field | Type | Required | Notes |
|---|---|---|---|
| `assets` | `list[str]` | **yes** | `min_length=1`. On the live path these are asset **handles**, rewritten to paths by `app/space_app.py::analyze` before `controller.run()` |
| `query` | `str` | **yes** | no minimum length; an empty string is schema-legal |
| `force_task` | `Task \| None` | no | bypasses the router entirely; recorded as `source="forced"` |
| `run_id` | `str \| None` | no | echoed back; generated as `run_{uuid4hex[:12]}` when omitted |

`extra="forbid"` is why an unknown field is a **422**, not an ignored key. `app/space_app.py:682-703` wraps
`AnalysisRequest.model_validate(payload)` and, on failure, logs the real `ValidationError` server-side while
returning `invalid_request` with the fixed detail "The body was not a valid AnalysisRequest. See
docs/API_CONTRACT.md section 2 for the accepted shape." — F-15 applied at the schema boundary.

### 13. `SpecialistResult` — the master contract

`core/schemas.py:325-343`. Its docstring is one sentence: "Every specialist returns exactly this. No
exceptions."

| Field | Type | Default | Meaning |
|---|---|---|---|
| `task` | `Task` | required | the task this result answers |
| `answer` | `str` | `""` | language output; empty for spatial-only tasks |
| `labels` | `list[str]` | `[]` | class labels |
| `regions` | `list[Region]` | `[]` | spatial results that may not be rectangles |
| `boxes` | `list[Box]` | `[]` | strict rectangles |
| `masks` | `list[str]` | `[]` | artifact refs |
| `change_map` | `str \| None` | `None` | artifact ref — **permanently `null` in v1** (F-16) |
| `evidence` | `list[Evidence]` | `[]` | the citable observations |
| `confidence` | `ConfidenceBreakdown` | required | never an LLM utterance |
| `geospatial` | `GeoMetadata` | `GeoMetadata()` | CRS / transform / bounds |
| `execution_trace` | `ExecutionTrace \| None` | `None` | set by the controller in `RESPOND` |
| `schema_version` | `str` | `"1.0"` | |
| `warnings` | `list[str]` | `[]` | operator-safe warnings |
| `degraded` | `bool` | `False` | |

Two validators run on every construction, and both encode real findings:

**(a) `_unique_evidence_ids`** (`core/schemas.py:345-351`) — `evidence_id` values must be unique within a
result. This is why `_renumber` in the controller exists.

**(b) `_task_output_consistency`** (`core/schemas.py:353-406`) — task-specific degradation rules. Two clauses
are live:

- **GROUNDING with no localisation is degraded, not a crash** (`core/schemas.py:355-361`): if
  `task is Task.GROUNDING and not (self.boxes or self.regions)` and the result is not already degraded, a
  warning is appended and `degraded` is set.
- **CHANGE_VQA with no answer text is degraded** (`core/schemas.py:396-405`): with the explicit caveat that
  "an answer alone is NOT enough to be non-degraded: the specialist sets `degraded` itself when it answered
  from an untrained head, and this validator must not clear that."

A **third** clause was **removed**, and the removal is documented in a long comment at
`core/schemas.py:362-395`. It read:

```python
if self.task is Task.CHANGE and self.change_map is None and not self.regions:
    ... "change analysis produced no spatial output" ... degraded = True
```

The comment records why it died (F-16c, owner ruling 2026-09-23):

> `change_map` was a PROXY for "a map was produced": before F-16 it held a filesystem path whenever a file had
> been written. F-16 made the ref permanently null — a client cannot retrieve it in v1 — so the proxy died,
> the clause collapsed to `not regions`, and a SUCCESSFUL no-change analysis began reporting `degraded: true`.
> A null, non-retrievable artifact ref was manufacturing a degradation.

And the replacement policy:

> No replacement clause is added, deliberately. A narrower "empty answer => degraded" rule was tried and
> backed out: it is not what the ruling asked for, it invented a semantic the specialist already owns, and it
> made a pre-existing, unrelated fixture (`test_change_with_regions_is_not_degraded`, a result with regions and
> no answer) fail. A fix that forces edits to tests it has nothing to do with is signalling over-reach, not
> diligence. **CHANGE is the one task whose `degraded` flag is now set entirely by its specialist.**

That last sentence is a precise, checkable claim about where responsibility sits.

### 14. `ResultEnvelope` — the outbound shape

`core/schemas.py:421-427`:

```python
class ResultEnvelope(BaseModel):
    model_config = ConfigDict(extra="forbid")

    run_id: str
    result: SpecialistResult
    trace: ExecutionTrace
    schema_version: str = SCHEMA_VERSION
```

Three top-level keys plus the version. `extra="forbid"` means the served body has exactly this shape.
`app/space_app.py:728` serializes it with `envelope.model_dump(mode="json")`.

### 15. `ExecutionTrace`, `TraceStep`, `ModelRef`

#### 15.1 `ExecutionTrace` (`core/schemas.py:296-319`)

Its docstring comment above the class reads: "Execution trace (observable facts only — never
chain-of-thought)".

| Field | Type | Default | Written by |
|---|---|---|---|
| `run_id` | `str` | `run_{uuid4hex[:12]}` | `RECEIVE` |
| `schema_version` | `str` | `"1.0"` | schema |
| `task` | `Task \| None` | `None` | `VALIDATE` |
| `query` | `str \| None` | `None` | `RECEIVE` |
| `inputs` | `list[str]` | `[]` | `RECEIVE` (basenames) |
| `modalities` | `list[Modality]` | `[]` | `PARSE` |
| `intent` | `Intent \| None` | `None` | `VALIDATE` |
| `validation` | `dict[str, Any]` | `{}` | **nothing** — see §15.4 |
| `workflow` | `list[str]` | `[]` | `EXECUTE` (step ids) |
| `steps` | `list[TraceStep]` | `[]` | every state |
| `selected_models` | `list[ModelRef]` | `[]` | `EXECUTE` (post-loop) |
| `parameters` | `dict[str, Any]` | `{}` | `PLAN`, then re-snapshotted after `EXECUTE` |
| `outputs` | `list[str]` | `[]` | `RESPOND` (evidence ids) |
| `confidence` | `ConfidenceBreakdown \| None` | `None` | `RESPOND` |
| `timings` | `dict[str, float]` | `{}` | `EXECUTE` (per step) |
| `fallbacks` | `list[str]` | `[]` | `VERIFY`, refusal path |
| `errors` | `list[dict[str, Any]]` | `[]` | `EXECUTE`, `VERIFY` |
| `contradiction` | `bool` | `False` | `VERIFY` |
| `config_hash` | `str \| None` | `None` | `RECEIVE` |
| `started_at` | `str` | `_utcnow()` | construction |
| `finished_at` | `str \| None` | `None` | `RESPOND` |

#### 15.2 `TraceStep` (`core/schemas.py:279-285`)

```python
class TraceStep(BaseModel):
    model_config = ConfigDict(extra="forbid")

    state: ControllerState
    started_at: str = Field(default_factory=_utcnow)
    duration_ms: float | None = None
    detail: dict[str, Any] = Field(default_factory=dict)
```

`_record` (`core/controller.py:1188-1197`) appends `TraceStep(state=state, detail=self._jsonable(detail or
{}))`. `duration_ms` is **left at `None`** by `_record` — the controller never sets it; per-step durations go
to `trace.timings` instead.

`_jsonable` (`core/controller.py:1265-1278`) recursively stringifies anything exotic, because "`ExecutionTrace.
steps[].detail` is a free-form dict, and a plan carries tuples and enums that `json.dumps` would reject.
Stringifying the leaves preserves the fact without inventing structure."

#### 15.3 `ModelRef` (`core/schemas.py:288-293`)

```python
class ModelRef(BaseModel):
    model_config = ConfigDict(extra="forbid")

    name: str
    revision: str | None = None
    role: str | None = None
```

Built explicitly in `_selected_models` rather than relying on dict coercion: "pydantic would coerce a dict
only by emitting a serialization warning. Constructing the type explicitly keeps the contract honest instead
of relying on coercion" (`core/controller.py:724-727`).

#### 15.4 `validation` is always `{}` — an honest gap

`ExecutionTrace.validation` is typed `dict[str, Any]` with a `default_factory=dict`, and a repository-wide
search finds **no writer**: no `trace.validation = …`, no `validation=` construction, no `trace.validation[…]`
subscript anywhere in `core/`, `app/`, `deploy/` or the frontend. So on the live path the field serializes as
`{}` in every response.

The validation facts that *are* observable live elsewhere and are not lost:

| Fact | Where it is observable |
|---|---|
| router decision + provenance | `trace.intent` and the `VALIDATE` step's `detail["router"]` |
| plan steps, mode, refusal, notes | `trace.parameters` and the `PLAN` step's `detail["plan"]` |
| per-step success/failure/skip | each `EXECUTE` step's `detail` |
| evidence-loss check | `trace.errors[]` with `code: "evidence_loss"` |

Status: `OPEN` — a schema field with no producer. It is recorded rather than removed because removing it would
be a schema change to the frozen `SCHEMA_VERSION = "1.0"` contract.

### 16. `ConfidenceBreakdown` (`core/schemas.py:259-273`)

Docstring: "Never an LLM utterance. Always measurable signals (plan section 26)."

| Field | Type | Default | Notes |
|---|---|---|---|
| `raw` | `float` | required | `ge=0.0, le=1.0` |
| `calibrated` | `float \| None` | `None` | `ge=0.0, le=1.0` when present |
| `method` | `str` | `"uncalibrated"` | `"temperature_scaling"` when a fit was applied |
| `components` | `dict[str, float]` | `{}` | diagnostic only |
| `degraded` | `bool` | `False` | |
| `degradation_reason` | `str \| None` | `None` | |

And the one property (`core/schemas.py:271-273`):

```python
@property
def value(self) -> float:
    return self.calibrated if self.calibrated is not None else self.raw
```

`value` is what `_answer`'s rule 2 ranks on. The deeper treatment of calibration — the formula, `_is_effective`,
`_EPS`, `_sigmoid`, the artifact object, and the **measured** result that ECE went 0.013755 → 0.014929
(**worse**) — is in [06 Evidence and confidence](06-evidence-and-confidence.md) §7–§10 and is not repeated here.

### 17. Supporting shapes

#### 17.1 `AssetMetadata` (`core/schemas.py:153-165`)

```python
class AssetMetadata(BaseModel):
    model_config = ConfigDict(extra="forbid")

    asset_id: str = Field(default_factory=lambda: _new_id("asset"))
    path: str
    modality: Modality = Modality.UNKNOWN
    sha256: str | None = None
    geo: GeoMetadata = Field(default_factory=GeoMetadata)
    sensor: SensorDescriptor | None = None
    acquisition_date: str | None = None
    scene_id: str | None = None
    dataset_id: str | None = None
    split: str | None = None
```

`_new_id` is `f"{prefix}_{uuid.uuid4().hex[:12]}"` (`core/schemas.py:28-29`). Note `path` is required and is
the **resolved** path (`inspect_raster` sets `path=str(p.resolve())`).

#### 17.2 `GeoMetadata` (`core/schemas.py:120-135`)

`extra="allow"` — deliberately the one open shape in the module. Fields: `crs`, `transform` (6 affine
coefficients, row-major), `bounds` (`[minx, miny, maxx, maxy]`), `width`, `height`, `band_count`, `dtype`,
`nodata`, `resolution`, `has_crs: bool = False`, `is_georeferenced: bool = False`. `inspect_raster` also
passes `driver` and `is_tiled` (`preprocessing/raster.py:173-174`), which only work because `extra="allow"`.

#### 17.3 `SensorDescriptor` (`core/schemas.py:138-150`)

Frozen sensor-adapter contract (plan §18), `extra="forbid"`: `sensor`, `available_bands`, `band_map`,
`normalization: str = "percentile"`, `availability_mask: list[bool]`, `resolution`, `canonical_channels: int =
0`, `missing_channels_zero_filled: bool = True`. The `availability_mask` is the **C-1** finding's carrier: the
channel-availability mask is a first-class fusion input, never a CROMA input.

#### 17.4 Spatial shapes

| Shape | Line | Fields |
|---|---|---|
| `Box` | `core/schemas.py:171-186` | `x1, y1, x2, y2`, `score ∈ [0,1]`, `label`, `coordinate_system` (default `normalized_0_1`) |
| `Region` | `:189-199` | `region_id`, `box: Box \| None`, `mask_ref: str \| None`, `label`, `score`, `coordinate_system` |
| `ChangeRegion` | `:202-210` | `region_id`, `box: Box`, `area_pixels: int (ge=0)`, `mean_probability ∈ [0,1]`, `stability ∈ [0,1] \| None`, `coordinate_system` |

`Box._ordered` (`core/schemas.py:182-186`) raises unless `x2 >= x1 and y2 >= y1` — a self-intersecting box is
not representable.

`Evidence` and the eleven-member `EvidenceType` vocabulary are the subject of
[06](06-evidence-and-confidence.md) §2–§4 and are cross-referenced rather than restated. The one thing worth
repeating here because it is a **validator on the request lifecycle's output**:
`Evidence._spatial_needs_crs` (`core/schemas.py:238-253`) refuses coordinates without a `coordinate_system`
for the six spatial types (`BOUNDING_BOX`, `MASK`, `CHANGE_MAP`, `TILE`, `IMAGE_CROP`,
`JOINT_FEATURE_REGION`).

### 18. The enums

#### 18.1 `Task` (`core/schemas.py:35-47`) — seven members

| Value | Note from the source |
|---|---|
| `vqa` | question answering about **one** asset |
| `caption` | description of one asset |
| `grounding` | localisation on one asset |
| `change` | the change **detector**; returns a spatial change map with **no language output** |
| `optical_sar` | optical + SAR fusion |
| `change_vqa` | R-02. two temporally corresponding assets + a change-oriented question in, a short answer out |
| `unsupported` | the refusal label |

The `change_vqa` comment is a precise disambiguation and worth quoting: "Distinct from CHANGE, which is the
change *detector* and returns a spatial change map with no language output, and distinct from VQA, which
answers about ONE asset. **The three are not interchangeable and the planner must not substitute one for
another.**"

#### 18.2 `Modality` (`core/schemas.py:50-54`) — four members

`optical` · `sar` · `optical_sar` · `unknown`.

#### 18.3 `CoordinateSystem` (`core/schemas.py:57-62`) — three members

`normalized_0_1` · `pixel` · `geo`. The docstring is the whole point: "Never omit this. A bare box is
meaningless without it. (C-5)".

#### 18.4 `EvidenceType` (`core/schemas.py:65-76`) — eleven members

`image_crop` · `tile` · `bounding_box` · `mask` · `change_map` · `optical_view` · `sar_view` ·
`joint_feature_region` · `statistic` · `geolocation` · `availability_mask`.

`statistic` is the member the controller depends on for both failure records and synthesis records;
`availability_mask` carries the C-1 comment inline: "C-1: modality trust evidence".

#### 18.5 `ControllerState` — see §2.1.

### 19. `Intent` — advisory only

`core/schemas.py:94-114`:

```python
class Intent(BaseModel):
    """Output of the learned router. Advisory only — the controller decides."""
    model_config = ConfigDict(extra="forbid")

    task: Task
    modality: Modality = Modality.UNKNOWN
    temporal: bool = False
    spatial_output: bool = False
    language_output: bool = True
    confidence: float = Field(ge=0.0, le=1.0)
    source: Literal["learned", "lexical_fallback", "forced"] = "learned"

    @model_validator(mode="after")
    def _consistency(self) -> "Intent":
        if self.task in (Task.CHANGE, Task.CHANGE_VQA) and not self.temporal:
            self.temporal = True
        if self.task is Task.OPTICAL_SAR and self.modality is Modality.UNKNOWN:
            self.modality = Modality.OPTICAL_SAR
        return self
```

Two coherence repairs are encoded in the validator: a change-family task is forced `temporal=True`, and an
`optical_sar` task with an unknown modality is forced to `optical_sar`. The comment notes the asymmetry that
is *not* repaired: "A temporal task without spatial output is legal; the reverse is not implied."

`Intent.source` is the **provenance** field, and it has exactly three legal values. It is what the planner's
provenance discount keys on (§28.3).

`RouterPrediction` (`router/classifier.py:80-106`) wraps an `Intent` with the evidence needed to explain it:

| Field | Type | Default |
|---|---|---|
| `intent` | `Intent` | required |
| `task_probs` | `dict[str, float]` | `{}` |
| `modality_probs` | `dict[str, float]` | `{}` |
| `binary_probs` | `dict[str, float]` | `{}` |
| `used_fallback` | `bool` | `False` |
| `fallback_rule` | `str \| None` | `None` |
| `matched_terms` | `tuple[str, ...]` | `()` |
| `above_threshold` | `bool` | `True` |

`to_trace()` publishes ten keys and, like every other trace writer in the codebase, is commented "Observable
facts only. No chain-of-thought."

### 20. `StepOutcome` — the internal outcome record

`core/controller.py:135-165`. Internal (not in `__all__`'s served surface, though it *is* exported). Fields:
`step: PlanStep`, `result: SpecialistResult | None`, `registry_entry: RegistryEntry | None`, `error:
SatQueryError | None`, `duration_ms: float`, `skipped_reason: str | None`. Properties `ok` and `capability`;
method `to_trace()` (the shape shown in §3.6).

---

## Part C — Validation

### 21. The raster contract

`preprocessing/raster.py:1-14` states the chain it implements and the three rules it obeys:

> ```
> file -> dimensions -> bands -> dtype -> CRS -> transform -> bounds -> nodata
>      -> modality -> temporal metadata
> ```
>
> Design rules:
> * Never raise a bare exception. Every failure is a typed SatQueryError.
> * Never silently drop geospatial metadata. If the source had a CRS, the returned AssetMetadata says so.
> * A missing CRS degrades to non-geospatial mode; it does not abort.

`inspect_raster` (`preprocessing/raster.py:96-185`) enforces, in order:

| Check | Failure | Error code | Recoverable |
|---|---|---|---|
| path exists | `not p.exists()` | `raster_read_error` | no |
| is a regular file | `not p.is_file()` | `raster_read_error` | no |
| rasterio importable | `ImportError` | `raster_read_error` | no |
| openable | any rasterio exception | `raster_read_error` | no |
| non-degenerate dims | `width <= 0 or height <= 0` | `raster_read_error` | no |
| pixel budget | `width * height > max_pixels` | `oversized_image` | **yes** |
| band count | `band_count <= 0` | `unsupported_bands` | no |

`OversizedImageError` and `MissingCRSError` both default `recoverable=True` in their own constructors
(`core/errors.py:137-139`, `:152-154`), so "the caller may downscale" is a machine-readable statement rather
than prose.

**CRS absence does not abort.** `GeoMetadata.has_crs` and `is_georeferenced` record the fact, and
`inspect_raster` returns normally. `MissingCRSError` exists in the taxonomy but `inspect_raster` does not
raise it — the degradable path is taken instead.

**Hash is opt-in.** `compute_hash: bool = False`; when true, `file_sha256` streams in 1 MiB chunks
(`preprocessing/raster.py:82-88`). Change detection needs it (see §26).

### 22. Modality inference — band-count heuristic

`preprocessing/raster.py:35-74`. The two sets are exact:

```python
_OPTICAL_BAND_COUNTS = {3, 4, 8, 11, 12, 13}
_SAR_BAND_COUNTS = {1, 2}
```

```python
def infer_modality(band_count: int, explicit: str | None = None) -> Modality:
    if explicit:
        try:
            return Modality(explicit.lower())
        except ValueError:
            pass

    if band_count in _SAR_BAND_COUNTS:
        return Modality.SAR
    if band_count in _OPTICAL_BAND_COUNTS:
        return Modality.OPTICAL
    if band_count >= 4:
        return Modality.OPTICAL
    return Modality.UNKNOWN
```

Resolution order, exhaustively:

| `band_count` | Result | Rule |
|---|---|---|
| 1 | `sar` | member of `{1, 2}` |
| 2 | `sar` | member of `{1, 2}` |
| 3 | `optical` | member of `{3, 4, 8, 11, 12, 13}` |
| 4 | `optical` | member of `{3, 4, 8, 11, 12, 13}` |
| 5–7 | `optical` | `>= 4` fallback |
| 8 | `optical` | member of the set |
| 9, 10 | `optical` | `>= 4` fallback |
| 11 | `optical` | member of the set |
| 12 | `optical` | member of the set |
| 13 | `optical` | member of the set |
| 14+ | `optical` | `>= 4` fallback |
| 0 or negative | `unsupported_bands` raised earlier | `band_count <= 0` check |

**The heuristic is declared as a heuristic.** `preprocessing/raster.py:35-37`: "These are heuristics, not
ground truth — the sensor adapter is authoritative when a sensor descriptor is supplied."

**The genuinely ambiguous case is 1 band, and the code says so.** A single-band GeoTIFF is a perfectly
ordinary SAR product *and* a perfectly ordinary panchromatic optical product; the band count cannot tell them
apart. `_normalise_modality_overrides` (`core/controller.py:1217-1250`) records that "Rather than guess, the
caller may declare the modality" and that the override "is genuinely ambiguous for a 1-band scene".
`infer_modality`'s own comment at `preprocessing/raster.py:70-71` repeats it: "12-band optical and 2-band SAR
are both plausible; default to optical only when the count clearly favours it."

**An unparsable explicit label is silently ignored by `infer_modality`** — the `except ValueError: pass` falls
through to the count heuristic. That is safe only because the caller-side validator is strict (§23).

### 23. Explicit modality overrides — validated at the boundary

`core/controller.py:1217-1250`:

```python
def _normalise_modality_overrides(overrides):
    if not overrides:
        return {}
    valid = {m.value for m in Modality}
    normalised: dict[str, str] = {}
    for key, value in overrides.items():
        text = str(value).strip().lower()
        if text not in valid:
            raise ValueError(
                f"asset_modalities[{key!r}] = {value!r} is not a valid modality; "
                f"expected one of {sorted(valid)}"
            )
        normalised[str(key)] = text
    return normalised
```

| Aspect | Behaviour |
|---|---|
| Values | `.strip().lower()` then membership in `{optical, sar, optical_sar, unknown}` |
| Invalid value | **raises** `ValueError` — never silently ignored |
| Keys | **not** normalised; looked up against the exact asset string *and* its basename |
| Lookup | `overrides.get(str(path)) or overrides.get(Path(path).name)` (`core/controller.py:519`) |
| Authoritative over | the band-count heuristic (`inspect_raster(explicit_modality=…)`) |

The rationale is stated as a principle about boundaries: "Values are normalised and validated here, at the
boundary where they enter the system, so a typo fails immediately and loudly instead of silently degrading to
'unknown' three layers down. A declaration that is ignored without complaint would be worse than a loud
error: the caller would believe an override took effect when it did not" (`core/controller.py:1228-1233`).

**The serving path does not currently pass overrides.** `app/space_app.py::analyze` calls
`controller.run(request)` with no `asset_modalities=`, and `AnalysisRequest` has no field for them. So on the
live path the override channel is reachable only from an in-process caller, and a 1-band ambiguous asset is
resolved by the heuristic. Status: `IMPLEMENTED (not reachable from the HTTP surface)`.

### 24. The per-file cap — 4,194,304 bytes, enforced at two layers

| Layer | Value | Source | Enforcement |
|---|---|---|---|
| Gateway | `max_file_bytes: int = 4 * 1024 * 1024` | `gateway/policy.py:221` | declared `Content-Length` **and** while reading (`gateway/app.py::_read_body_bounded`, F-6) |
| Space | `_asset_max_file_bytes()` default `4 * 1024 * 1024` | `app/space_app.py:359` | while reading via the shared `gateway/assets.py::read_body_bounded` (F-9) |

`4 * 1024 * 1024 = 4,194,304` bytes = 4 MiB. Both layers read the **same** variable,
`SATQUERY_MAX_FILE_BYTES`, and both **refuse** an unparsable or non-positive value rather than defaulting —
F-7. `app/space_app.py:318-378` documents the measured divergence before the fix:

> `SATQUERY_MAX_FILE_BYTES='abc'` or `'4e6'` → this function silently returned the 4 MiB DEFAULT while the
> gateway RAISED AT STARTUP for the same value.
>
> `SATQUERY_MAX_FILE_BYTES='0'` or `'-1'` → this function RETURNED THE VALUE ('0' / -1) while the gateway,
> once its own non-positive guard was added, REFUSED it.

The Space's refusal names the variable and the offending text, because "this is read while building the store
and an operator can only see it in a Space's build or start log."

**The cap is a request-side limit, not a raster limit.** A 4 MiB GeoTIFF is comfortably within the cap; the
*pixel* budget is separate (§25).

### 25. The pixel budget — 25,000,000

| Key | Value | Source |
|---|---|---|
| `image.max_pixels` | `25000000` | `configs/base.yaml:17` |
| Enforced at | `inspect_raster(max_pixels=…)` | `preprocessing/raster.py:152-156` |
| Error | `OversizedImageError` (`oversized_image`), `recoverable=True` | `core/errors.py:147-154` |

25,000,000 pixels is 25 MP. The error carries structured context:
`{"width": …, "height": …, "max_pixels": …}`.

**Who passes `max_pixels` on the live path is not established from the available evidence.** The controller
calls `_inspect_asset(path, explicit_modality)`, which calls `inspect_raster(path,
explicit_modality=explicit_modality)` with **no** `max_pixels` (`core/controller.py:1253-1262`). So unless
the deployed build differs, the live path does **not** enforce the 25 MP budget at inspection time.
Status: `UNKNOWN — not established from the available evidence` for whether the deployed inference build
passes the value. The key is declared, and `tests/geospatial/test_transform.py:381` exercises
`inspect_raster(geotiff, max_pixels=10)`, so the mechanism is tested; the live wiring is not evidenced.

### 26. Equal-dimension pairs for change tasks

The change detector requires T1 and T2 to be the same shape. `specialists/change/stanet.py:417`:

```python
f"T1 and T2 must have the same shape; got {tuple(t1.shape)} "
```

and again at `:580` (`"must have the same shape"`). The comparison is on the **decoded tensor shape**, not on
the raster header, so it is enforced inside the detector forward pass rather than at validation.

**The pair checks that *are* at validation time** are in `specialists/change/specialist.py:225-272`
(`_assess_pair`), and they run in this order:

| # | Check | Error | Code |
|---|---|---|---|
| 1 | `t1.path == t2.path` | `TemporalPairError` | `temporal_pair_invalid` |
| 2 | `t1.sha256 == t2.sha256` (when both present) | `TemporalPairError` | `temporal_pair_invalid` |
| 3 | CRS compatibility (`geospatial.crs.compare_crs`) | **warning**, not an error | — |
| 4 | registration quality (`measure_registration`) | degrades to `is_usable=False` | — |

Check 1's comment names both mistakes it catches: "ONE asset is the common mistake: the caller treated this as
a single-image task. THREE is the other: they attached a time series." Check 2's message is the rule:
"T1 and T2 have identical sha256; a repeated acquisition is not a temporal pair."

Check 3 is deliberately a warning. `specialists/change/specialist.py:255-262`:

> No CRS on either side is NOT fatal for pixel-domain change detection — the two rasters still tile to the
> same grid. It IS fatal for any claim about ground coordinates, so the warning is recorded and the geospatial
> block is withheld downstream.

Check 4 is where the "measurement of failure" distinction lives (`specialists/change/specialist.py:274-307`):
"A failure to MEASURE is not the same as a measurement of failure, but both mean the pair cannot be trusted
spatially, so both produce an unusable verdict. The distinction is recorded in the warning." A measurement
failure returns `RegistrationQuality(shift_x=0.0, shift_y=0.0, response=0.0, max_shift_px=…, is_usable=False,
reason="registration measurement failed")` — and the non-zero `reason` is what makes "we could not measure"
distinguishable from "we measured zero shift".

`execute` reuses the same assessment rather than measuring twice: "Split out so `execute` can reuse the SAME
assessment the validator made, rather than measuring registration twice and reporting two numbers that could
disagree" (`specialists/change/specialist.py:228-230`). The consequence when registration is unusable
(`:321-326`) is a **suppression**, not a failure:

> poor co-registration: {reason}. Spatial change claims are suppressed; confidence reflects the measurement,
> not the change map.

### 27. GeoTIFF acceptance for optical-SAR

The optical-SAR specialist's validation is exactly two assets, both present, one optical and one SAR
(`specialists/optical_sar/specialist.py:192-293`):

| # | Check | Error |
|---|---|---|
| 1 | `request.asset_count != 2` | `InvalidRequestError` |
| 2 | each `Path(asset.path).exists()` | `InvalidRequestError` |
| 3 | `_assess_pair(...)` | `InvalidRequestError` (three distinct messages) |

The user-facing message for check 1 is the clearest statement of the requirement in the codebase:

> "Optical-SAR fusion needs exactly two images: one optical and one radar (SAR)."

`_assess_pair` (`specialists/optical_sar/specialist.py:223-293`) resolves each asset's modality by **declared
value first, band-count inference second**:

> Modality comes from the asset's declared `modality`, falling back to a band-count inference through
> `preprocessing.raster.infer_modality`. The declared value wins when present, because the caller may know
> something the band count does not — a 2-band Cartosat stack, or a 12-band decomposition product.

It then classifies and refuses on three distinct conditions, each with its own `reason` in the error context:

| Condition | `reason` | User message |
|---|---|---|
| two optical | `two_optical` | "Both uploaded images look like optical imagery. This workflow needs one optical image and one radar (SAR) image." |
| two SAR | `two_sar` | "Both uploaded images look like radar (SAR) imagery. This workflow needs one optical image and one radar (SAR) image." |
| neither clean | `indeterminate` | "Could not tell which image is optical and which is radar. Please label the images so one is optical and one is SAR." |

Only the third case — one `optical` and one `sar` — returns a `PairAssessment`. The `indeterminate` branch is
the one the F-13-era `UNKNOWN`/`UNKNOWN` defect produced, and its message is the one quoted in
`core/controller.py:497-500`.

**Band-count inference used for pairing produces a warning, not a silent decision.**
`specialists/optical_sar/specialist.py:309-315` appends:

> asset {name} had no declared modality; inferred '{modality}' from {band_count} band(s). A band count is a
> heuristic, not a sensor declaration -- label the asset explicitly if this is wrong.

So "we guessed" is always visible in `result.warnings[]`.

**A GeoTIFF is required, not merely accepted.** The format gate is upstream: `POST /v1/assets` accepts a
closed list of five content types (`image/tiff`, `image/geotiff`, `image/png`, `image/jpeg`,
`application/octet-stream`), and `API_CONTRACT.md` §2.5 records the consequence in the row itself: "**`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." A PNG therefore passes the upload gate
and fails later at `inspect_raster` with `raster_read_error`.

### 28. The planner's decision rules

The planner is pure: "No models, no torch, no filesystem, no clock — every rule below is unit-testable with a
hand-built `RouterPrediction`" (`core/planner.py:256-258`).

#### 28.1 Refusals — a closed list

`_refusal_for` (`core/planner.py:412-426`) is four lines and its comment is "The closed refusal list from §8.
Order matters: query first."

| # | Condition | `code` | `reason` | `user_message` |
|---|---|---|---|---|
| 1 | `task is Task.UNSUPPORTED` | `unsupported_query` | `task_unsupported` | `UnsupportedQueryError.user_message` = "No specialist supports this request." |
| 2 | `asset_count < 1` | `invalid_request` | `zero_assets` | `InvalidRequestError.user_message` = "The uploaded inputs do not support the requested task." |

A third refusal is produced **after** the availability gate (`core/planner.py:358-372`):

| # | Condition | `code` | `reason` | `user_message` |
|---|---|---|---|---|
| 3 | every step dropped as unavailable | `model_unavailable` | `no_available_specialist` | "No specialist is available for this request in this environment." |

Note that refusal #3 uses `_refusal(...)` with `code="model_unavailable"` — a **string**, not
`ModelUnavailableError.code`. Both happen to be `"model_unavailable"`, so they agree, but they are not the
same source.

`asset_count < 1` is unreachable through the HTTP surface because `AnalysisRequest.assets` is
`Field(min_length=1)`. It is reachable from an in-process caller, and it is kept for that reason.

#### 28.2 Step construction and `§3.5` widening

The primary step is built from `TASK_CAPABILITY[task]` with `reason=f"task:{task.value}"` and
`required=True` (`core/planner.py:325-333`).

Then `_widening_steps` (`core/planner.py:434-508`) may add up to two more, from a closed set of rules:

| Rule | Condition | Step added | `reason` | `required` |
|---|---|---|---|---|
| change + language → answer | `task is CHANGE and asset_count >= 2 and intent.language_output` **and** `change_vqa` is known | `change_vqa` | `task:change+language_output:answer` | `False` |
| change + language → caption | same, **but** `change_vqa` unknown | `caption`, index `asset_count - 1` | `task:change+language_output` | `False` |
| spatial + language | `intent.spatial_output and intent.language_output and asset_count >= 1` and `task is not GROUNDING` | `grounding`, index `0` | `aspect:spatial_output` | `False` |

The first two are **alternatives, not both**, and the comment says why (`core/planner.py:460-469`): "Which
language output … depends on what the deployment has. With a change-VQA capability registered (R-02), the
request is satisfied by an ANSWER to the change question — which is the specific thing that was asked.
Without it, the fallback is to caption the later acquisition, which is the one a 'what changed' answer
describes. These are alternatives, not two things to do … Adding both would spend a step on a strictly weaker
output."

Note the caption fallback indexes `asset_count - 1` — the **later** acquisition — while every other one-asset
capability indexes `0`.

**Availability is deliberately not gated here.** `core/planner.py:450-454`:

> Availability is NOT gated here. The step is added whenever its rule fires, and `_drop_unavailable` removes it
> with a recorded note if the capability is unregistered. Gating here as well would create a second, silent
> availability check whose omission leaves no trace — exactly the "absence indistinguishable from a
> non-event" failure that §4.3 forbids.

Why widening exists at all is stated concretely (`core/planner.py:23-31`): "A query needing two specialists
can never get both. The router returns ONE task; *'what changed between these two images, and describe the
scene'* routes to `change` alone, and the caption is lost. Section §3.5 is what recovers it."

#### 28.3 The provenance discount — a reading, not a gate

| Constant | Value | Source |
|---|---|---|
| `LEXICAL_FALLBACK_DISCOUNT` | `0.75` | `core/planner.py:110` |
| `SETTLED_CONFIDENCE` | `0.60` | `core/planner.py:116` |

```python
@staticmethod
def _effective_confidence(prediction) -> float:
    raw = float(prediction.intent.confidence)
    if prediction.intent.source == "lexical_fallback":
        return raw * LEXICAL_FALLBACK_DISCOUNT
    return raw
```

The distinction is stated as an evidence argument (`core/planner.py:57-62`):

> A lexical fallback at 0.9 is not the same evidence as a learned model at 0.9: one is a regex that matched,
> the other is a learned distribution. Treating them identically would let a matched keyword outrank the model
> it fell back from. So the planner applies a **provenance discount** — not a second numeric gate — to its own
> reading of the confidence, and never edits `Intent.confidence` itself.

The measured fact that makes the discount necessary is in the same comment: "on the spec section 29 examples
the fallback returns 0.850-0.920 against the trained model's 0.780-1.000 — **the fallback can be MORE
confident**."

**`SETTLED_CONFIDENCE = 0.60` is declared but not used as a gate.** A repository search finds it exported in
`__all__` and documented at `core/planner.py:112-116`, but no comparison against it appears in `plan()`. The
uncertainty test that actually runs is `not prediction.above_threshold`
(`core/planner.py:339-344`, `:315`, `:368`, `:389`). The threshold itself is applied **once**, in the router
(`router/classifier.py:289`, `:308`), and the planner's docstring is explicit that re-reading it here would be
a second independent gate over the same quantity:

> So the planner consumes `above_threshold` (a bool), never the numeric threshold. Re-reading
> `router.confidence_threshold` here would be a second, independent gate over the same quantity — two places
> bound to one knob, which is how a threshold ends up meaning two different things.

Status of `SETTLED_CONFIDENCE`: `IMPLEMENTED (declared and exported, not read)`. This is an honest gap of the
same class as `PREPROCESS`.

#### 28.4 The discretionary explanation step

`core/planner.py:339-352`:

```python
if (
    not prediction.above_threshold
    and prediction.intent.language_output
    and "vqa" not in {s.capability for s in steps}
    and self._capability_known("vqa")
):
    self._append(
        steps,
        capability="vqa",
        indices=(0,),
        reason="uncertain_route:explain",
        required=False,
    )
    notes.append("uncertain route: added an explanation step")
```

Four conditions, all necessary: the route must be **uncertain**, the request must want **language**, the plan
must not already contain `vqa`, and the capability must be **known**. `required=False`, so a failure degrades
rather than invalidating.

#### 28.5 The availability gate

`_drop_unavailable` (`core/planner.py:572-602`) removes steps whose capability is not in
`registry.available()`, appending `f"dropped step {step_id} ({capability}): capability not registered"` to
`notes` for each. The docstring distinguishes declaration from construction, which is the boundary the
planner must not cross:

> Note this filters only on *declaration*. Whether a declared capability can actually be CONSTRUCTED is
> discovered by the controller, which records an `UNAVAILABLE` registry entry — the planner must not attempt
> construction, which would defeat the lazy-load design.

If `registry.available()` raises, `_registry_ok()` returns `False` and the filter is **skipped entirely**,
returning the steps unchanged — "a broken registry is not a plan error" (`core/planner.py:569`).

#### 28.6 The step cap, and the honest gap

```python
if self.max_steps is not None and len(steps) > self.max_steps:
    dropped = [s.capability for s in steps[self.max_steps:]]
    notes.append(
        f"plan truncated at {self.max_steps} steps; dropped {dropped}"
    )
    steps = steps[: self.max_steps]
```

| Aspect | Value |
|---|---|
| Constructor parameter | `max_steps: int | None = None` (`core/planner.py:270`) |
| Documented as mirroring | `agent.max_specialists` (`core/planner.py:265-266`) |
| `agent.max_specialists` value | `4` (`configs/base.yaml:239`) |
| **Read by any code** | **no** — a repository search for `agent.max_specialists` in Python returns only the planner's own docstring |
| What the serving composition passes | `PolicyPlanner(registry)` — **no `max_steps`** (`app/serving.py:263`) |
| Consequence on the live path | `max_steps is None`, so **no truncation is applied** |

Status: `OPEN` — the cap exists, is tested (`tests/unit/test_planner.py:454
test_max_steps_truncates_and_records`), and is not wired to the frozen config key that names it. In practice
the reachable plan length is small (primary + at most two widening steps = 3), so the unwired cap is not
currently load-bearing; that is an observation about today's rule set, not a guarantee.

#### 28.7 `PlanMode`

`_mode_for` (`core/planner.py:613-632`) returns `PARALLEL_SAFE` only when there are at least two steps **and**
the asset index sets are pairwise disjoint. The docstring states the outcome plainly:

> With today's four specialists asset indices commonly overlap — a change plan and a caption plan can both
> read asset 1 — so this legitimately returns SEQUENTIAL in normal operation. That is correct, not a
> limitation (§3.4).

And the enum's own docstring (`core/planner.py:148-158`) is emphatic that the marker is a **declaration**, not
a directive: "v1 executes both modes sequentially — freeze section 5 forbids worker pools, queues and async
frameworks. The marker records that a future `ThreadPoolExecutor` would be sound."

### 29. `CAPABILITY_ASSETS` — the asset-count-aware dispatch rule

`core/planner.py:133-142`:

| Capability | Assets | Note |
|---|---|---|
| `vqa` | 1 | |
| `caption` | 1 | |
| `grounding` | 1 | |
| `change` | 2 | |
| `optical_sar` | 2 | |
| `change_vqa` | 2 | "Two assets, like `change` — the difference is the output, not the input: a short language answer rather than a change map." |

`TASK_CAPABILITY` (`core/planner.py:121-128`) maps the six routable tasks onto those keys, with
`UNSUPPORTED` **deliberately absent**: "it is a refusal, not a capability."

```python
TASK_CAPABILITY: Mapping[Task, str] = {
    Task.VQA: "vqa",
    Task.CAPTION: "caption",
    Task.GROUNDING: "grounding",
    Task.CHANGE: "change",
    Task.OPTICAL_SAR: "optical_sar",
    Task.CHANGE_VQA: "change_vqa",
}
```

**`_indices_for`** (`core/planner.py:527-537`) is the dispatch rule:

```python
needed = CAPABILITY_ASSETS.get(capability, 1)
return tuple(range(min(needed, asset_count)))
```

So a two-asset capability on a two-asset request takes `(0, 1)`; on a one-asset request it takes `(0,)` — a
**partial** index set, which the specialist's own `validate_request` then refuses with
`InvalidRequestError`. The planner's comment explains the division of labour: "the specialists validate their
own asset count and pairing rules, and duplicating that logic here would give two places to disagree."

**The registry's spec table independently declares the same counts**
(`core/registry.py:192-259`: `requires_assets=1` for grounding, `2` for change / change_vqa / optical_sar,
`None` for vqa and caption), and `app/deployment.py:199-203` notes that `CapabilityRequirement` carries "**no
new numbers** — it is a view, not a third copy", with a test
(`test_the_adapter_artifact_table_matches_the_registry`) that keeps the two in agreement.

**`change_vqa` is deliberately not keyed `vqa`.** `core/registry.py:221-226`:

> The capability key is `change_vqa`, which is deliberately NOT `vqa`: a `vqa`-keyed row would make the
> planner route a two-asset change question to the one-asset VLM and silently answer about only one of the
> two acquisitions.

### 30. What the router's ontology does and does not contain

`configs/base.yaml:59-66` sets `router.num_tasks: 6` and lists six tasks: `vqa`, `caption`, `grounding`,
`change`, `optical_sar`, `unsupported`.

**`change_vqa` is not in the router's label space.** `router/classifier.py:45-52` maps six labels to schema
tasks and `_assert_schema_alignment()` (`router/classifier.py:62-77`) fails loudly if `label_space.TASK_CLASSES`
contains a label with no schema mapping — but the direction checked is *label → schema*, not *schema → label*.
`Task.CHANGE_VQA` has no router label.

`core/config.py:198-206` validates the two router invariants that *are* checked:

```python
tasks = self.get("router.tasks") or []
if "unsupported" not in tasks:
    errors.append("router.tasks must include 'unsupported'")
if self.get("router.num_tasks") != len(tasks):
    errors.append(
        f"router.num_tasks={self.get('router.num_tasks')} does not match "
        f"router.tasks length ({len(tasks)})"
    )
```

Consequence for the lifecycle: a `change_vqa` result is reachable on the live path only via `force_task`, or
via the planner's widening rule (§28.2) when the router returns `change` **with** `language_output` set. The
widening path is the designed route to it; `force_task` is the direct one. Note that the widening path
requires a **router** to have produced the `change` intent with `language_output=True` — see §38.

---

## Part D — Preprocessing

This part documents the preprocessing policy `configs/base.yaml` declares, and states precisely which parts
are executed. The distinction matters more here than anywhere else in the document, because **the config
declares more than the serving path implements**.

### 31. The tiling policy — declared, validated, and not implemented in serving

#### 31.1 The declared values

`configs/base.yaml:16-24`:

```yaml
image:
  max_pixels: 25000000
  tile_size: 512
  tile_overlap: 128
  max_tiles: 64
  # plan section 9.1 tile policy: whole-image thumbnail first, then top-K tiles.
  # max_tiles is the hard ceiling on tiles *examined*; top_k_tiles is how many
  # are actually sent through a specialist.
  top_k_tiles: 4
```

| Key | Value | Meaning (from the config's own comment) |
|---|---|---|
| `image.tile_size` | `512` | the tile edge |
| `image.tile_overlap` | `128` | overlap between adjacent tiles |
| `image.max_tiles` | `64` | **hard ceiling on tiles *examined*** |
| `image.top_k_tiles` | `4` | how many tiles are **actually sent through a specialist** |
| `image.max_pixels` | `25000000` | see §25 |

#### 31.2 The "whole-image thumbnail first, then top-K tiles" rule

The rule is stated in the config comment above (`plan section 9.1 tile policy: whole-image thumbnail first,
then top-K tiles`), and the two-tier structure is what `max_tiles` versus `top_k_tiles` encodes: 64 is the
examination budget, 4 is the specialist budget. `preprocessing/imagery.py:10-15` names the same stage from
the other direction:

> What this does NOT do
> ---------------------
> It does not resample, crop, or reproject. Those change the pixel grid, and the grounding specialist converts
> normalized boxes to pixel coordinates using the ORIGINAL raster's dimensions — a silent resize here would
> put every box in the wrong place. **Size changes belong in the tiling stage, which records what it did.**

#### 31.3 The invariants that *are* enforced

`core/config.py` validates two cross-keys, and both are enforced at load time:

| Invariant | Check | Line |
|---|---|---|
| `top_k_tiles <= max_tiles` | `errors.append("image.top_k_tiles cannot exceed image.max_tiles")` | `core/config.py:215-216` |
| `processor_longest_edge <= tile_size` | raises if `proc_edge > tile_size`, naming F5-2 | `core/config.py:137-142` |
| `tile_overlap < tile_size` (both image and change) | asserted by test | `tests/test_config.py:219-222` |

The second is the load-bearing one for cost, and its comment records the **measured** figures: the
processor's default `longest_edge` of 2048 upscales a 512 px tile 4× and then splits it into 17 sub-images
with 1142 prompt tokens, versus 1 image when pinned. "The plan estimated a 4x overrun; the real figure is
~17x."

`tests/test_config.py:159-162` pins the pin itself: `test_processor_pin_is_tied_to_tile_size` asserts
`cfg.get("vlm.processor_longest_edge") == cfg.get("image.tile_size")`. So the two values are held equal by
test, not by comment.

#### 31.4 The honest gap: no serving-path tiler exists

A repository search for a tiling implementation — `def tile`, `class Tiler`, `iter_tiles`, `select_tiles` —
returns **nothing** outside `.scratch/`. `preprocessing/` contains exactly four modules:
`__init__.py`, `imagery.py`, `quality.py`, `raster.py`. There is no `preprocessing/tiling.py`.

What the search *does* return for the `image.*` tiling keys is: `core/config.py` (validation),
`scripts/check_env.py:170-172` (a diagnostic print), and `tests/test_config.py` (assertions). The
`change.tile_size` key is a **different** key and is genuinely consumed — by
`training/change/train.py` and `scripts/{eval_change,sweep_change_threshold,train_change,verify_levir_real}.py`
via a `_fit_to_tile` helper that "Centre-crop[s] or zero-pad[s] every array to a `tile_size` square."

So the precise statement is:

| Item | Status |
|---|---|
| The tiling **policy** is declared in config | `IMPLEMENTED` |
| The policy's internal invariants are validated at load | `IMPLEMENTED` |
| The policy's invariants are pinned by tests | `VERIFIED` |
| `change.tile_size` (256) is consumed by training/eval scripts | `IMPLEMENTED` |
| A serving-path tiler that examines `max_tiles` and forwards `top_k_tiles` | **NOT FOUND — not established from the available evidence** |
| `image.tile_size` / `tile_overlap` / `max_tiles` / `top_k_tiles` read by any runtime code path | **NO** |

The `image.*` keys are therefore *frozen declarations awaiting a consumer*. They are not dead values — they
are validated, hashed into `Config.hash`, and they constrain `vlm.processor_longest_edge` — but the specific
behaviour named in the config comment is not executed by the code in this repository. Status: `OPEN`.

### 32. Percentile normalisation 2/98 for optical

#### 32.1 The declared values

`configs/base.yaml:26-31`:

```yaml
optical:
  normalization: percentile
  lower_percentile: 2
  upper_percentile: 98
  canonical_channels: 12
```

#### 32.2 What *is* implemented: a hardcoded 2/98 display stretch

`preprocessing/imagery.py:60-67` — the shared raster-to-displayable conversion:

```python
arr = array.astype(np.float32)
finite = arr[np.isfinite(arr)]
if finite.size:
    lo, hi = np.percentile(finite, (2, 98))
    if hi > lo:
        arr = (arr - lo) / (hi - lo)
arr = np.clip(arr, 0.0, 1.0)
return (arr * 255).astype(np.uint8)
```

The **same** 2/98 pair appears, independently hardcoded, in two more places:

| Site | Line |
|---|---|
| `specialists/vqa/inference.py` | `:87` — `lo, hi = np.percentile(finite, (2, 98))` |
| `specialists/change/postprocess.py` | `:117` — `lo, hi = np.percentile(finite, (2, 98))` |

Three implementations, one numeric pair, and **none of them reads `optical.lower_percentile` /
`optical.upper_percentile`**. The values coincide with the config; the config is not the source.

Two properties of the implemented stretch are worth naming:

- **It is deterministic**, and `preprocessing/imagery.py:7-8` makes that a stated guarantee: "The percentile
  stretch is deterministic: the same file always yields the same array, so a grounding box and a VQA answer
  describe identical pixels." That is why one shared implementation exists rather than two: "duplicating that
  logic in two modules is how the two drift apart."
- **It uses only finite values** (`finite = arr[np.isfinite(arr)]`), so "a nodata sentinel does not crush the
  dynamic range" (`preprocessing/imagery.py:29-30`).

The stretch maps to a `(H, W, 3)` uint8 array. The band selection is the first three bands, with two
special cases (`preprocessing/imagery.py:50-58`): a >3-band raster is truncated to its first three, and a
1-band raster is repeated three times.

#### 32.3 What is *not* implemented: the config-driven conditioning stage

`specialists/optical_sar/radiometry.py:5-14` states the position without hedging:

> `configs/base.yaml` declares two radiometric transforms:
>
> ```
> optical: {normalization: percentile, lower_percentile: 2, upper_percentile: 98}
> sar:     {representation: db, clip_min_db: -30, clip_max_db: 5}
> ```
>
> **Neither is read by any code.**

And `:29-37`:

> NOT implemented: the percentile / dB **conditioning** stage that `base.yaml` names. The ruling
> (`PHASE14_CROMA_NORMALISATION_CHANGE.md` section 2.2) states the two are ordered stages, not alternatives,
> and that both must run. The second is specified here; the first remains unspecified and unsourced — no
> source examined in `docs/CROMA_NORMALISATION_UPSTREAM_EVIDENCE.md` uses or endorses a percentile stretch or
> a dB clip. Implementing a guess for it is exactly the fabrication the DEV-2 ruling exists to prevent, so it
> is left visibly absent rather than silently approximated. **Consequence: the two `optical.*` and three
> `sar.*` config keys are still read by no code.** That is recorded, not fixed.

The pipeline diagram in the same module (`:39-44`) is the clearest statement of where the gap sits:

```
GeoTIFF -> band map + zero-fill + availability mask   (sensor_adapter)
        -> [percentile / dB conditioning]             (NOT IMPLEMENTED)
        -> per-channel mean +/- 2*std -> [0, 1]       <- THIS MODULE
        -> CROMA.encode
```

So: for the **display path** (VQA, caption, grounding, change postprocessing) a 2/98 percentile stretch
exists and is exercised. For the **CROMA fusion path** the percentile stage does not exist, and the module
that would own it says so.

### 33. dB clip −30…+5 for SAR

`configs/base.yaml:33-38`:

```yaml
sar:
  representation: db
  clip_min_db: -30
  clip_max_db: 5
  canonical_channels: 2
```

| Key | Value | Consumed by |
|---|---|---|
| `sar.representation` | `"db"` | **nothing** |
| `sar.clip_min_db` | `-30` | **nothing** |
| `sar.clip_max_db` | `5` | **nothing** |
| `sar.canonical_channels` | `2` | validation only, via `croma.sar_channels` |

`croma.sar_channels: 2` **is** validated: `core/config.py:167-168` raises unless
`self.get("croma.sar_channels") == 2`, with the message "croma.sar_channels must be 2 (CROMA s1_channels is
fixed)". The comment above the check explains the direction: "CROMA expects exactly 2 SAR channels (VV, VH)."

The three `sar.*` conditioning keys (`representation`, `clip_min_db`, `clip_max_db`) are read by no code, as
`specialists/optical_sar/radiometry.py:36-37` states explicitly.

### 34. What *is* implemented on the CROMA input path — mean ± 2σ

`specialists/optical_sar/radiometry.py:21-27`:

> Implemented: the **encoder-input** stage — per-channel `mean +/- 2*std` -> `[0, 1]`, the transform the CROMA
> authors' own README instructs users to apply … (corroborated by the authors' instruction for their released
> benchmark tensors: *"convert tensors to floats and divide by 255"*).

The transform, quoted verbatim from the module (`:48-55`):

```python
min_value = x[:, c].mean() - 2 * x[:, c].std()
max_value = x[:, c].mean() + 2 * x[:, c].std()
img = (x[:, c] - min_value) / (max_value - min_value) * 255.0
img = clip(img, 0, 255).to(uint8)
# before the forward pass:
x = x.float() / 255
```

**A deliberate deviation is documented and justified.** The README computes the mean over the **whole batch**,
which makes one image's encoding depend on its neighbours. `:57-69`:

> That makes a single image's encoding a function of its neighbours, which is unacceptable for a serving
> system whose whole point is reproducibility: the same query must not produce a different answer because
> another request was batched alongside it.
>
> This module computes the window **per sample**, over that sample's channel only.

This is the same reproducibility principle that makes `EvidenceEngine.aggregate` pure and
`evidence_digest()` exist.

### 35. `change.tile_size` — a different key, genuinely consumed

`configs/base.yaml:182-197`:

```yaml
change:
  tile_size: 256
  tile_overlap: 0
  threshold: 0.50
  min_component_pixels: 32
  encoder: resnet18
  sa_mode: PAM
  pretrained: true
  ...
```

| Key | Value | Consumed by | Notes |
|---|---|---|---|
| `change.tile_size` | `256` | `training/change/train.py` + 4 scripts | the detector's input tensor; **not** `image.tile_size` (512) |
| `change.tile_overlap` | `0` | test assertion only | `tests/test_config.py:222` |
| `change.threshold` | `0.50` | `specialists/change/specialist.py:900` | `threshold=float(config.get("change.threshold", 0.5))` |
| `change.min_component_pixels` | `32` | `specialists/change/specialist.py:901` | `min_component_pixels=int(config.get("change.min_component_pixels", 32))` |
| `change.encoder` | `resnet18` | validated required | `core/config.py:209-210` |
| `change.sa_mode` | `PAM` | validated ∈ `{BAM, PAM}` | `core/config.py:211-212` |

Note the two tile sizes are different **and both real**: the VLM/fusion path is pinned to 512 via
`vlm.processor_longest_edge`, and the change detector is pinned to 256. `scripts/train_change.py:159` prints
"tile size : 256px (encoder stride 8)", which is the reason 256 is the value and not something else.

`change.threshold` and `change.min_component_pixels` are the two keys that shape the change output, and both
are read with the config value as the primary and the same number as the fallback — so a config load failure
cannot silently change detector behaviour.

---

## Part E — The execution events, the trace, and the live path

### 36. The eight execution events

`frontend/assets/js/core.js:616-620`:

```javascript
SQ.EVENT_NAMES = [
  'QUERY_RECEIVED', 'QUERY_UNDERSTOOD', 'ROUTE_SELECTED',
  'SPECIALIST_STARTED', 'SPECIALIST_COMPLETED',
  'EVIDENCE_GENERATED', 'CONFIDENCE_COMPUTED', 'RESULT_ASSEMBLED'
];
```

And the eight stages they drive (`frontend/assets/js/core.js:605-614`):

| Stage id | Label | Driven by event |
|---|---|---|
| `QUERY` | QUERY | `QUERY_RECEIVED` |
| `UNDERSTAND` | UNDERSTAND | `QUERY_UNDERSTOOD` |
| `ROUTE` | ROUTE | `ROUTE_SELECTED` |
| `ANALYZE` | ANALYZE | `SPECIALIST_STARTED` |
| `GROUND` | GROUND | `SPECIALIST_COMPLETED` |
| `EVIDENCE` | EVIDENCE | `EVIDENCE_GENERATED` |
| `CONFIDENCE` | CONFIDENCE | `CONFIDENCE_COMPUTED` |
| `ANSWER` | ANSWER | `RESULT_ASSEMBLED` |

The event protocol and its measured trace fill (94.4444 %) are the subject of
[06](06-evidence-and-confidence.md) §13 and are cross-referenced rather than restated here. What matters for
*this* document is the mapping boundary: the eight events are a **frontend** protocol emitted by
`SQ.run`/`SQ.ingest` (`frontend/assets/js/core.js:742`), not a backend protocol. The backend emits
`ControllerState` trace steps (§2.2). `frontend/assets/js/mission.js:361-371` is where the two vocabularies are
reconciled, and it does so by mapping `SPECIALIST_STARTED → 'PREPROCESS'` and `SPECIALIST_COMPLETED →
'EXECUTE'` — which is how the frontend renders the state the backend never emits.

### 37. The client-side policy is not the router

`frontend/assets/js/core.js:623-675` defines `SQ.policy(query)` — a deterministic regex policy that returns
`{task, specialists, route}`. It is explicitly labelled `deterministic: true` and its rule list is returned in
`route.rules` so a UI can display which rules fired. `frontend/assets/js/mission.js` has a parallel
`interpret()`.

**This is not `router/classifier.py`.** It is a client-side stand-in, and the distinction matters because the
task names differ: `SQ.policy` produces `'CHANGE_ANALYSIS'`, `'CHANGE_VQA'`, `'SAR_ANALYSIS'`, `'GROUNDING'`,
`'VLM_CAPTION'`, `'VLM_QA'`, and specialist names like `'CHANGE_DETECTOR'`, `'EVIDENCE_EXTRACTOR'`,
`'VLM_REASONER'`, `'GROUNDING_HEAD'`, `'IMAGE_REGISTRATION'`. The backend's `Task` enum values are lowercase
and are `vqa`, `caption`, `grounding`, `change`, `optical_sar`, `change_vqa`, `unsupported`. The mapping
between the two happens in `mission.js` when it builds `force_task`.

Two comments in `SQ.policy` record real routing defects it fixes, and they are worth quoting because they are
the same class of bug the backend planner's widening rules address:

> `built` was removed and `new` counts only outside a `where` question. "Where is the built-up area?" — the
> architecture page's OWN sample — previously fired `intent.change` on "built", then `intent.quantify` on
> "area", and was answered as CHANGE_VQA with a CHANGE_DETECTOR specialist: a location question routed to a
> change question.

The fix is ordering plus a guard: `where` is evaluated **first**, and `newAsChange = /\bnew\b/.test(q) &&
!where`.

### 38. The live path attaches no router — `force_task` is de facto required

This is the most consequential lifecycle fact about the deployed system, and it is established by three
independent pieces of evidence.

#### 38.1 `build_serving_controller` passes no router

`app/serving.py:247-265`:

```python
def build_serving_controller(config=None, *, device=None) -> AnalysisController:
    cfg = load_config() if config is None else config
    registry = build_serving_registry(cfg, device=device)
    return AnalysisController(
        registry=registry,
        planner=PolicyPlanner(registry),
        config=cfg,
    )
```

Its own docstring says so explicitly (`app/serving.py:254-257`):

> Constructed with `registry=`, `planner=` and `config=` only. **No router is attached**, so a caller drives
> it with `AnalysisRequest(..., force_task=...)`; a natural-language router can be supplied by the caller's
> own composition if the router weights are available.

#### 38.2 `IntentRouter` is never constructed outside tests

A repository-wide search for `IntentRouter(` and `router=` in Python — excluding `.scratch/`, `.venv/` and
`tests/` — returns **nothing**. `app/space_app.py:184` calls `build_serving_controller()`, and
`app/serving.py` is the only constructor. So the router is *implemented and trained* but **not composed into
the serving process**.

#### 38.3 The consequence, and how the system compensates

Because `self.router is None`, `_route` returns `None` for any request without `force_task`, and
`core/controller.py:327-334` raises `UnsupportedQueryError(..., recoverable=False)`. So on the live
deployment:

| Request | Outcome |
|---|---|
| `force_task` present | routed as `source="forced"`, `confidence=1.0`, `above_threshold=True`; the plan runs |
| `force_task` absent | **`unsupported_query`**, `recoverable=false` — no plan is built |

The frontend compensates by always sending it. `frontend/assets/js/live.js:302`:
`if (opts.forceTask) body.force_task = opts.forceTask;` — and `:288` records that "`force_task` is omitted
rather than sent as null" because the schema is `extra="forbid"`-strict about unknown values while a `null`
for a declared optional field is legal. `frontend/assets/js/mission.js:661` sets
`force_task: forced` from the page's own lexical `interpret()`.

`docs/FRONTEND_INTEGRATION.md:94` states the operational rule: "**Always send `force_task` when the UI knows
the intent.** The user picked …" — and `:89` shows the field as `force_task: "change_vqa", // optional; omit
to let the router decide`.

#### 38.4 What follows from this, stated precisely

| Claim | Status |
|---|---|
| The router is `IMPLEMENTED` and trained | `VERIFIED` (`router/classifier.py`, `router/adapter.py`, `router/encoder.py`, `router/fallback.py`, `router/label_space.py`) |
| The router has a measured validation number | `MEASURED` — 0.965116, **validation, ungated, n = 86**; the **test split was NOT RUN** |
| The router is attached to the deployed controller | **NO** — no `router=` argument exists outside tests |
| `force_task` is required on the live path | **YES**, in effect |
| `Intent.source` on the live path | always `"forced"` |
| The planner's `LEXICAL_FALLBACK_DISCOUNT` is exercised on the live path | **NO** — it keys on `source == "lexical_fallback"`, which cannot occur when routing is forced |
| The planner's uncertainty clause (`not above_threshold`) is exercised on the live path | **NO** — a forced prediction is constructed with `above_threshold=True` |
| The planner's widening rules fire on the live path | **only** the `spatial_output + language_output` rule, and only when the caller's own `force_task`/`Intent` says so; the change+language rule requires `intent.language_output`, which a forced `Intent` leaves at its default `True` (`core/schemas.py:102`) |

That last row is worth being careful about. A forced `Intent` is constructed as
`Intent(task=request.force_task, confidence=1.0, source="forced")` (`core/controller.py:468-472`), so
`language_output` takes its **default of `True`** and `temporal`/`spatial_output` take their defaults of
`False` — except that `Intent._consistency` forces `temporal=True` for a change-family task. Therefore a
`force_task="change"` request on a two-asset plan **does** satisfy the widening rule's `intent.language_output`
condition, and if `change_vqa` is registered the planner will add a change-VQA step. So the widening path is
reachable on the live deployment through `force_task` — but the *uncertainty* path is not.

Status: `OPEN` for "the router is not composed into the serving path". This is a composition gap, not a
missing capability, and it is the same shape of defect as the calibration wiring gap documented at
`core/controller.py:203-216`.

```mermaid
sequenceDiagram
  participant FE as Browser (mission.js)
  participant GW as Gateway (Render)
  participant SP as Space (build_space_app)
  participant CO as AnalysisController
  participant PL as PolicyPlanner
  participant RG as SpecialistRegistry
  participant SPEC as Specialist

  FE->>FE: SQ.policy(query) / interpret(query)
  FE->>FE: choose force_task (de facto required)
  FE->>GW: POST /api/v1/analyze {assets:[handle], query, force_task}
  GW->>GW: validate · CORS · size · rate limit · request_id
  GW->>SP: forward to /v1/analyze
  SP->>SP: AnalysisRequest.model_validate(payload)
  SP->>SP: handle -> AssetStore.get() -> path
  SP->>CO: controller.run(request)
  CO->>CO: RECEIVE
  CO->>CO: PARSE (inspect_raster headers only)
  CO->>CO: VALIDATE (_route -> forced Intent)
  Note over CO: router is None on the live path<br/>force_task is therefore required
  CO->>PL: planner.plan(prediction, request, assets)
  PL-->>CO: ExecutionPlan (steps, mode, notes)
  CO->>CO: PLAN
  loop each plan step
    CO->>RG: registry.build(capability) (memoised)
    RG-->>CO: RegistryEntry (AVAILABLE / DEGRADED / UNAVAILABLE)
    CO->>SPEC: validate_request(SpecialistRequest)
    CO->>SPEC: execute(SpecialistRequest)
    SPEC-->>CO: SpecialistResult | typed error
    CO->>CO: EXECUTE (record outcome, timing, error)
  end
  CO->>CO: AGGREGATE (evidence + failures + synthesis, renumbered)
  CO->>CO: VERIFY (sources assertion, contradiction)
  CO->>CO: RESPOND (outputs, confidence, finished_at)
  CO-->>SP: ResultEnvelope
  SP-->>GW: 200 envelope (JSON)
  GW-->>FE: envelope + error translation
```

### 39. Degraded versus error — the distinction, stated once

The codebase applies the same rule in five places, and it is worth collecting them because the lifecycle
depends on all five agreeing.

| Situation | Behaviour | Why |
|---|---|---|
| An **optional artifact is absent** (no change checkpoint, no fusion head, no calibration) | **degrade** — construct, mark degraded, answer honestly | `app/space_app.py:24-26`: "Absent artifacts degrade; *corrupt* artifacts raise `ModelLoadError`. A Space that refuses to boot because an optional artifact is missing is worse than one serving a reduced capability set." |
| An artifact is **present but corrupt** | **raise** `ModelLoadError` | `core/registry.py:63-75`: "a `ModelLoadError` / `ModelUnavailableError` raised during construction maps to `UNAVAILABLE` (a defect, surfaced loudly), NOT retried as `DEGRADED`. The registry is not the place to helpfully re-add a fallback the builder refused." |
| A **specialist step fails** | **record and continue** | `core/controller.py:16-20`: partial failure never erases evidence; no early exit |
| A **plan cannot run at all** | **refuse** — a successful run with no steps | `core/planner.py:75-81` |
| The **primary specialist failed** | **no confidence** — `raw=0.0`, `degraded=True` | `core/controller.py:54-58`: reporting a secondary's score "would launder a failure into a number" |

The change specialist encodes the absent-vs-corrupt distinction in its builder, and the registry's docstring
quotes it as the canonical statement (`core/registry.py:68-71`, quoting
`specialists/change/specialist.py:834-838`):

> silently running an untrained model because a real checkpoint failed to load would be the worst outcome.

Two further distinctions of the same family, both stated in the source:

- **"we could not measure" ≠ "we measured failure."** `specialists/change/specialist.py:279-281`, with the
  distinction recorded in a non-zero `reason` string.
- **"could not be built" ≠ "was never asked for."** `core/registry.py:49-61` — `build()` returns an
  `UNAVAILABLE` entry rather than raising (except for an unknown capability) "so the controller can say
  'optical_sar was planned but could not be constructed: CROMA could not load' instead of either crashing or
  pretending the step never existed."

### 40. The three registry states, and how they reach the client

`RegistryState` (`core/registry.py:102-107`): `AVAILABLE` (`"available"`), `DEGRADED` (`"degraded"`),
`UNAVAILABLE` (`"unavailable"`).

`PLANABLE_STATES = frozenset({AVAILABLE, DEGRADED})` (`core/registry.py:113-115`) — DEGRADED is planable
deliberately: "a degraded specialist still runs and returns an honest, degraded result, so a local install with
no trained weights exercises real code paths."

`_degradation_of` (`core/registry.py:527-548`) is duck-typed and conservative: it checks `has_checkpoint`,
`has_head`, `has_encoder` for `False`, and `model is None`; "a specialist that does not expose any recognised
flag is reported AVAILABLE, because inventing a degradation the specialist did not declare would be worse than
reporting a clean build."

**The registry vocabulary never reaches a client.** `app/deployment.py:185-189`:

```python
REGISTRY_TO_CONTRACT: Mapping[str, str] = {
    "available": "loaded",
    "degraded": "loaded",
    "unavailable": "absent",
}
```

and `app/deployment.py:179-184` explains why `unavailable → "absent"` is the right default:

> `UNAVAILABLE` is deliberately mapped to `"absent"` here and refined to `"unavailable"` only when the
> artifacts are demonstrably present. Mapping it straight to `"unavailable"` would be the single most damaging
> mistranslation available in this module: it would label every missing artifact a defect.

`CONTRACT_STATES = frozenset({"loaded", "absent", "unavailable", "not_requested", "evicted"})`
(`app/deployment.py:175-177`) is listed as data "so a test can assert the adapter never emits anything outside
it — the whole point of an adapter is that its output range is checked."

The **run-level** `SpecialistResult.degraded` and the **capability-level** `RegistryState` are therefore two
different vocabularies answering two different questions, and `DeploymentReport.status`
(`app/deployment.py:704-725`) is a third:

> `degraded` = *"the service is up but at least one expected artifact is absent"*. Two things follow … a
> capability that is merely `not_requested` does **not** degrade the service — under `lazy_load: true` that is
> every capability on a fresh process, and reporting `degraded` for a healthy idle service would make the
> field useless as a probe; `unavailable` (present but broken) is a defect. It is reported as `error`, not
> `degraded`, because the two have different remedies.

### 41. `_gpu_durations` — declared, never executed

`app/space_app.py:109-116` transcribes the frozen ZeroGPU durations:

| Task | Duration (seconds) |
|---|---|
| `vqa` | 20 |
| `caption` | 20 |
| `grounding` | 45 |
| `change` | 30 |
| `optical_sar` | 45 |
| `change_vqa` | 30 |

`change_vqa` "has no key of its own and reuses `change`, because adding a key would move `Config.hash` off
`78f1e3700da15aa1`" (`app/space_app.py:106-108`).

`decorate_gpu` (`app/space_app.py:144-165`) applies `spaces.GPU(duration=duration)` when the `spaces` package
is importable, and an **identity decorator** when it is not. The module docstring records the consequence
without softening it (`app/space_app.py:40-42`):

> The consequence is recorded in `docs/PHASE19_FINAL_HARDENING.md`: the ZeroGPU decoration has **never
> executed** here. It is specified from finding C-8 and the frozen `gpu_duration_*` values, and that is all it
> is.

`decorate_gpu` raises `KeyError` for a task with no declared duration — "A task with no declared duration is a
programming error, not a default: silently picking a duration would reserve the wrong amount of the 5
GPU-minute daily budget."

---

## Part F — Worked examples

These examples are constructed from the code paths documented above. The trace shapes are exact; the
`duration_ms` and id values are illustrative.

### 42. Worked example — a change-VQA request end to end

**Request.**
```json
{
  "assets": ["asset_7c6f64a4a4c821e25d518467a1cc5d47", "asset_b1f0c2d3e4a59687766554433221100f"],
  "query": "How much new construction appeared between these two dates?",
  "force_task": "change_vqa"
}
```

**Stage 1 — the Space rewrites handles to paths.** `app/space_app.py:705-724` resolves both handles through
`store.resolve_many`, raising `input_error` with "One or more asset handles are unknown or have expired." on
failure, then rebuilds the request with `model_copy(update={"assets": [str(handle.path) for handle in
handles]})`. Note `model_copy` rather than mutation, "because `AnalysisRequest` is the contract's model and a
handler must not rewrite a validated request in place."

**Stage 2 — `RECEIVE`.** `run_id = "run_9c1f4e7a2b30"` (generated; none was supplied).
`trace.inputs = ["t1.tif", "t2.tif"]` — basenames, not the resolved paths.
```json
{"asset_count": 2}
```

**Stage 3 — `PARSE`.** Both rasters are inspected header-only. Both are 4-band → `infer_modality(4)` →
`optical`.
```json
{"inputs": ["t1.tif", "t2.tif"], "modalities": ["optical"], "query_length": 54}
```

**Stage 4 — `VALIDATE`.** `force_task` is set, so the router is bypassed and a synthetic prediction is built.
`Intent._consistency` forces `temporal=True` because the task is in the change family. `trace.task =
Task.CHANGE_VQA`.
```json
{"assets": 2, "force_task": "change_vqa",
 "router": {"task": "change_vqa", "modality": "unknown", "temporal": true,
            "spatial_output": false, "language_output": true, "confidence": 1.0,
            "source": "forced", "above_threshold": true, "used_fallback": false,
            "fallback_rule": null}}
```

**Stage 5 — `PLAN`.** `_refusal_for(CHANGE_VQA, 2)` returns `None`. The primary step is `change_vqa` with
`reason="task:change_vqa"`, `required=True`, `params={}`, `asset_indices=(0, 1)`. `_widening_steps`:
`task is Task.CHANGE` is **false** (it is `CHANGE_VQA`), so the change+language rule does not fire;
`intent.spatial_output` is `False`, so the spatial rule does not fire. `prediction.above_threshold` is `True`,
so no explanation step. `_drop_unavailable` keeps the step because `change_vqa` is registered.
`_mode_for` returns `SEQUENTIAL` (one step).
```json
{"plan": {"steps": [{"step_id": "step_001", "capability": "change_vqa",
                     "specialist": "change_vqa", "asset_indices": [0, 1],
                     "reason": "task:change_vqa", "required": true}],
          "mode": "sequential", "refused": false, "refusal": null, "uncertain": false,
          "router_source": "forced", "effective_confidence": 1.0, "notes": []}}
```

**Stage 6 — `EXECUTE`.** `registry.build("change_vqa")` runs `_wired_change_vqa_builder`, which passes the
shared STANet checkpoint when it exists and the change-VQA head when it exists, `None` otherwise. Suppose both
exist: the entry is `AVAILABLE`. `validate_request` requires exactly two assets and calls `_assess_pair`
(temporal distinctness, CRS compatibility, registration). `execute` runs.
```json
{"step_id": "step_001", "capability": "change_vqa", "ok": true, "skipped_reason": null,
 "error_code": null, "duration_ms": 14203.882, "registry_state": "available"}
```

**Stage 7 — `AGGREGATE`.** One result, so `_synthesis_evidence` returns `[]` (fewer than two results). No
failures. The engine's collection is renumbered to `evidence_001…`.
```json
{"evidence": {"returned": 3, "total_before_limit": 3, "dropped_duplicates": 0,
              "dropped_over_limit": 0, "truncated": false,
              "sources": ["change_vqa"], "types": ["change_map", "statistic"]},
 "degraded": false}
```

**Stage 8 — `VERIFY`.** `expected = {"change_vqa"}`, `observed = {"change_vqa"}` → no `evidence_loss`. One
result with boxes in one coordinate system → no contradiction (a single box cannot contradict itself, and the
pairwise loop needs at least two).
```json
{"contradiction": false}
```

**Stage 9 — `RESPOND`.** `trace.outputs = ["evidence_001", "evidence_002", "evidence_003"]`;
`trace.confidence = result.confidence`.
```json
{"answer_length": 187}
```

### 43. Worked example — a refusal

**Request.** `{"assets": ["a.tif"], "query": "What is the GDP of France?"}` — routed (or forced) to
`unsupported`.

`_refusal_for` returns refusal #1 immediately, before any step is built:

```json
{"plan": {"steps": [], "mode": "sequential", "refused": true,
          "refusal": {"code": "unsupported_query", "reason": "task_unsupported",
                      "user_message": "No specialist supports this request."},
          "uncertain": false, "router_source": "forced",
          "effective_confidence": 1.0, "notes": ["refused:task_unsupported"]}}
```

The envelope carries `result.answer == "No specialist supports this request."`,
`result.confidence.raw == 0.0`, `calibrated == null`, `degraded == true`,
`degradation_reason == "refused:task_unsupported"`, `result.warnings ==
["refused:task_unsupported"]`, and `trace.fallbacks == ["refused:task_unsupported"]`. The state sequence is
RECEIVE → PARSE → VALIDATE → PLAN → AGGREGATE(`{"refused": true, …}`) → VERIFY(`{"steps": 0}`) →
RESPOND(`{"refused": true}`).

### 44. Worked example — partial failure producing a degraded envelope

**Request.** `{"assets": ["a.tif", "b.tif"], "query": "What changed, and describe the later scene?",
"force_task": "change"}`.

**PLAN.** Primary step `change` (`reason="task:change"`, `required=True`, `indices=(0,1)`). `_widening_steps`:
`task is CHANGE` and `asset_count >= 2` and `intent.language_output` is `True` (the forced `Intent`'s
default). If `change_vqa` is **known**, a `change_vqa` step is added with
`reason="task:change+language_output:answer"`, `required=False`; the note
`"change + language request: added a change-VQA step"` is appended. If `change_vqa` is **not** known, a
`caption` step is added at index `asset_count - 1` with `reason="task:change+language_output"` and the note
`"change + language request: added a caption step"`.

**EXECUTE.** Suppose the change step succeeds but the change-VQA step fails with an unhandled exception.
`_execute_one` logs the traceback and returns a `StepOutcome` with the fixed-message `SpecialistError`. Two
`EXECUTE` steps are recorded: `step_001 ok=true`, `step_002 ok=false, error_code="specialist_error"`.

`trace.errors` gains:
```json
{"step_id": "step_002", "capability": "change_vqa", "code": "specialist_error",
 "message": "The step failed with an unhandled error. Internal detail is withheld; see the server-side diagnostics.",
 "recoverable": false}
```

**AGGREGATE.** `results = [change_result]`. `failure_evidence` produces one `STATISTIC` item for
`change_vqa` with `payload.step_failed == true` and `payload.code == "specialist_error"`.
`_synthesis_evidence` returns `[]` because `len(results) < 2` — note that a *failure* does not count as a
result, so the synthesis record does **not** appear here. `_warnings` appends
`"change_vqa failed (specialist_error): <scrubbed reason>"`.

**Confidence.** `primary_task = trace.task = Task.CHANGE`. `primary = next((r for r in results if r.task is
Task.CHANGE), None)` → the change result **is** found. So the run's confidence is the change specialist's,
calibrated, with `components == {"change_confidence": <raw>}`. The failure does **not** zero the confidence —
but `_degraded` returns `True` because `any(not o.ok for o in outcomes)`.

**VERIFY.** `expected = {"change"}`, `observed = {"change"}` → no `evidence_loss`.

**Result.** `answer` comes from rule 1 (no vqa/caption succeeded), then rule 2 (the change result has an
answer), giving `"[change] No change detected above threshold 0.50. …"` or the region-bearing text.
`result.degraded == True`; `result.warnings` carries the failure line; `result.evidence` carries the
`STATISTIC` failure record. The envelope is a **200**, not a 5xx.

---

## Part G — Boundaries

### 45. What is NOT RUN, OPEN, BLOCKED or REJECTED for this topic

| # | Item | Status | Evidence |
|---|---|---|---|
| 1 | `PREPROCESS` emitted as a trace state | `OPEN` | declared in `core/schemas.py:84`, `configs/base.yaml:247`, `mission.js:361`; no emitter in `core/controller.py`; test at `tests/unit/test_controller.py:385-393` lists eight |
| 2 | `agent.states` read by any code | `OPEN` | no Python reader |
| 3 | `agent.max_specialists` wired to `PolicyPlanner(max_steps=…)` | `OPEN` | key at `configs/base.yaml:239`; `PolicyPlanner(registry)` at `app/serving.py:263`; no reader of the key |
| 4 | `agent.unload_after_workflow` read by any code | `OPEN` | no Python reader |
| 5 | `SETTLED_CONFIDENCE` used as a gate | `OPEN` | declared/exported at `core/planner.py:116`; no comparison in `plan()` |
| 6 | `ExecutionTrace.validation` populated | `OPEN` | no writer anywhere; always `{}` |
| 7 | Router composed into the serving controller | `OPEN` | `app/serving.py:247-265` passes no `router=`; `IntentRouter(` never constructed outside tests |
| 8 | Serving-path tiler honouring `image.max_tiles` / `top_k_tiles` | `OPEN` | no tiling module in `preprocessing/`; keys read only by config validation, `scripts/check_env.py` and tests |
| 9 | `optical.lower_percentile` / `upper_percentile` read by code | `OPEN` | `specialists/optical_sar/radiometry.py:36-37` states it; the implemented 2/98 is hardcoded in three places |
| 10 | `sar.representation` / `clip_min_db` / `clip_max_db` read by code | `OPEN` | `specialists/optical_sar/radiometry.py:36-37` |
| 11 | `image.max_pixels` passed to `inspect_raster` on the live path | `UNKNOWN` | `core/controller.py:1253-1262` passes no `max_pixels`; whether the deployed build differs is `UNKNOWN — not established from the available evidence` |
| 12 | Asset modality overrides reachable from the HTTP surface | `IMPLEMENTED (not reachable)` | `_normalise_modality_overrides` exists; `AnalysisRequest` has no field for it |
| 13 | A per-step timeout | `REJECTED` | `core/controller.py:548-552` — needs a worker process or signal handler, which conflicts with the single-process monolith constraint |
| 14 | Any narrative composed from evidence by a template | `REJECTED` | `core/controller.py:946-948` — "that is the VLM's job, and only when it actually ran" |
| 15 | Averaging specialist confidences | `REJECTED` | `core/controller.py:43-47` |
| 16 | Resolving contradictory spatial claims by precedence weight | `REJECTED` | `core/controller.py:60-66` — "any such weight is a value judgment with no measurement behind it" |
| 17 | Parallel execution of plan steps | `NOT RUN` | `PlanMode.PARALLEL_SAFE` is a declaration; "v1 executes both modes sequentially" |
| 18 | ZeroGPU decoration executed | `NOT RUN` | `app/space_app.py:40-42` — "has **never executed** here" |
| 19 | An end-to-end benchmark of the request lifecycle | **does not exist** | no system-level accuracy is claimed |
| 20 | Router test split | `NOT RUN` | 0.965116 is **validation, ungated, n = 86**; the test split was not run |
| 21 | B-07 (tunnel gap; the `transport_mode: auto` fallthrough) | `OPEN` | patch prepared, **NOT deployed** — see [02](02-deployment-topology.md) §6 |
| 22 | B-02 (`codespace_name` trailing `\n`) | `OPEN` (cosmetic) | see [02](02-deployment-topology.md) §7 |

### 46. Where the evidence lives

| Claim area | File(s) |
|---|---|
| The controller, the FSM, `StepOutcome` | `core/controller.py` (1331 lines) |
| All shapes and enums | `core/schemas.py` (462 lines) |
| The planner, refusals, widening, `CAPABILITY_ASSETS` | `core/planner.py` (661 lines) |
| The registry, three states, `PLANABLE_STATES` | `core/registry.py` (639 lines) |
| The error taxonomy and `scrub_paths` | `core/errors.py` |
| Config load, validation, `Config.hash` | `core/config.py` (275 lines) |
| The frozen values | `configs/base.yaml` (295 lines) |
| Raster contract, modality inference | `preprocessing/raster.py` |
| The implemented 2/98 display stretch | `preprocessing/imagery.py` |
| The CROMA input stage and the not-implemented conditioning | `specialists/optical_sar/radiometry.py` |
| Change pair checks and degraded sites | `specialists/change/specialist.py`, `specialists/change/stanet.py` |
| Optical-SAR pair assessment | `specialists/optical_sar/specialist.py` |
| The specialist interface | `specialists/base.py` |
| Evidence aggregation and `confidence_for` | `evidence/engine.py` |
| The serving composition root | `app/serving.py` |
| The four HTTP routes, asset store, GPU decoration | `app/space_app.py` (735 lines) |
| Health / capability payloads, contract vocabulary | `app/deployment.py` (1232 lines) |
| Router inference and the lexical fallback | `router/classifier.py` (474 lines) |
| The eight execution events and the run engine | `frontend/assets/js/core.js`, `frontend/assets/js/mission.js` |
| The state-order test | `tests/unit/test_controller.py:379-395` |
| The tiling invariants | `tests/test_config.py:159-162`, `:214-222` |
| The endpoint contract | `docs/API_CONTRACT.md` §2.4, §4, §5 |
| The frontend integration rule for `force_task` | `docs/FRONTEND_INTEGRATION.md:89-94` |

### 47. Cross-references

| For | See |
|---|---|
| The evidence schema, `EvidenceType`, the aggregation pipeline | [06 Evidence and confidence](06-evidence-and-confidence.md) §2–§6 |
| The confidence system, temperature scaling, the measured ECE result | [06](06-evidence-and-confidence.md) §7–§11 |
| `ExecutionTrace` and the eight events in depth | [06](06-evidence-and-confidence.md) §12–§14 |
| The router, the five-head adapter, the label space, `interpret()` vs `chooseTask()` | [04 Router](04-router.md) |
| Per-specialist entry points, preprocessing, postprocessing, outputs | [05 Specialists](05-specialists.md) |
| The frozen config registry and its invariants | [07 Configuration freeze](07-configuration-freeze.md) |
| The four endpoints and the error envelopes | [08 API contract](08-api-contract.md) |
| The four tiers, the tunnel, the wake flow | [02 Deployment topology](02-deployment-topology.md) |