release: add docs/GEOSPATIAL.md

docs/GEOSPATIAL.md

@@ -0,0 +1,1747 @@
+# Geospatial — deep reference
+
+**Status tags used on every substantive claim:** `IMPLEMENTED` · `VERIFIED` · `MEASURED` · `ATTEMPTED`
+· `NOT RUN` · `BLOCKED` · `DEFERRED` · `REJECTED` · `OPEN` · `RESOLVED` · `CLOSED`.
+
+Every statement in this document was produced by reading a file in `C:/Users/anish/satquery-ai/`. Where
+a fact is not established from the available evidence, this document writes
+`UNKNOWN — not established from the available evidence`. Where a transform is *declared* in configuration
+but read by no code, that is stated explicitly rather than presented as a working feature. Where a
+capability is absent, it is listed in [§13](#13-what-is-not-implemented-exhaustive) rather than implied.
+
+This chapter is the reference for the **spatial contract**: how a raster becomes an analysed image, what
+georeferencing survives, what coordinate system a box is in, how a sensor's bands become CROMA's canonical
+channels, and which of those steps are actually implemented on the serving path. It is written to be
+sufficient to reconstruct the subsystem from the document alone.
+
+**Sibling documents:** [`DATA_PIPELINE.md`](DATA_PIPELINE.md) (the end-to-end data path, caches and
+artefacts), [`architecture/03-request-lifecycle.md`](architecture/03-request-lifecycle.md) (where the
+PREPROCESS and VALIDATE states sit), [`architecture/05-specialists.md`](architecture/05-specialists.md)
+(the six specialists in full), [`architecture/07-configuration-freeze.md`](architecture/07-configuration-freeze.md)
+(the frozen config identity and every key), [`DATASETS.md`](DATASETS.md) (the corpora and their measured
+shapes).
+
+---
+
+## Table of contents
+
+0. [How to read this document](#0-how-to-read-this-document)
+1. [The raster input contract](#1-the-raster-input-contract)
+2. [CRS handling](#2-crs-handling-geospatialcrs-py)
+3. [Affine transforms and coordinate frames](#3-affine-transforms-and-coordinate-frames)
+4. [The coordinate-system contract](#4-the-coordinate-system-contract)
+5. [Benchmark box scale — 0–100 versus 0–1](#5-benchmark-box-scale--0100-versus-01)
+6. [Band-count modality inference](#6-band-count-modality-inference)
+7. [Radiometric normalisation and representation](#7-radiometric-normalisation-and-representation)
+8. [The CROMA sensor adapter contract](#8-the-croma-sensor-adapter-contract)
+9. [Pair-compatibility rules](#9-pair-compatibility-rules)
+10. [Large-image tiling policy](#10-large-image-tiling-policy)
+11. [Grounding resolution — the frozen 224 decision](#11-grounding-resolution--the-frozen-224-decision)
+12. [Worked examples](#12-worked-examples)
+13. [What is NOT implemented — exhaustive](#13-what-is-not-implemented-exhaustive)
+14. [What is NOT RUN / OPEN / BLOCKED for this topic](#14-what-is-not-run--open--blocked-for-this-topic)
+15. [Where the evidence lives](#15-where-the-evidence-lives)
+
+---
+
+## 0. How to read this document
+
+Three distinctions are load-bearing throughout, and conflating them is the single most common way to
+misread this system:
+
+1. **Declared versus executed.** `configs/base.yaml` is the authoritative registry, and `core/config.py`
+   validates and hashes it at load time. But *declaring* a policy and *executing* it are different
+   claims. The tiling policy, the optical percentile stretch and the SAR dB clip are all declared in
+   `configs/base.yaml` and are all read by no code on the serving path. This document says so at each
+   point rather than presenting the key as a feature.
+2. **Adapter versus encoder.** The CROMA sensor adapter (`specialists/optical_sar/sensor_adapter.py`)
+   performs band mapping, zero-fill and availability masking. CROMA the encoder does **not** receive the
+   availability mask (finding C-1). The mask is consumed by the fusion head. These are separate contracts
+   and §8.9 treats the distinction in full.
+3. **Presentation versus radiometry.** There are two different percentile stretches in this codebase:
+   a per-*scene* 2/98 display stretch in `preprocessing/imagery.py` (and a grayscale cousin in
+   `specialists/change/postprocess.py`), and a per-*channel* `mean ± 2·std` encoder-input stretch in
+   `specialists/optical_sar/radiometry.py`. They serve different purposes and are **not**
+   interchangeable. §7.5 is explicit about why.
+
+The status vocabulary is used on every substantive claim. `MEASURED` means a number was produced by
+executing code; `VERIFIED` means the claim was checked against a second independent source; `IMPLEMENTED`
+means the code exists on the serving path; `DECLARED (not read)` means the value lives in
+`configs/base.yaml` and no code reads it.
+
+---
+
+## 1. The raster input contract
+
+### 1.1 What arrives, and what is accepted
+
+An asset reaches the analysis path through `POST /v1/assets`, which mints an opaque `asset_id`. The
+gateway enforces a **closed content-type allowlist of exactly five types**
+(`docs/API_CONTRACT.md` §2.5):
+
+| Content type | Notes |
+|---|---|
+| `image/tiff` | **The type the geospatial specialists need.** A client that uploads only PNG/JPEG can serve `vqa`, `caption` and `grounding`, but not `change` or `optical_sar` |
+| `image/geotiff` | Accepted; media-type parameters are ignored, so `image/tiff; charset=binary` is accepted |
+| `image/png` | Accepted |
+| `image/jpeg` | Accepted |
+| `application/octet-stream` | Accepted, but the raster reader still has to be able to open the bytes |
+
+Two behaviours are specified rather than defaulted: a request with **no** declared content type is
+**refused** rather than defaulted (defaulting is how a PDF reaches a raster reader), and a disallowed
+type gets `415`. The stored filename is derived from the **content type**, never from the client's
+filename, so a client-supplied `../../` cannot influence where bytes land (`docs/API_CONTRACT.md` §2.5).
+The size cap is enforced at two layers — the gateway and the Space — and both now refuse an unparsable
+or non-positive value rather than silently falling back to a default
+(`docs/API_CONTRACT.md` §2.5, "Size cap").
+
+`artifact_ref` on every `Evidence` item is **always `null` in v1** (`core/schemas.py:225`): v1 exposes no
+artifact-serving endpoint, so a reference a client cannot retrieve is not fabricated. The schema field's
+own description states this — *"Reference to an externally retrievable artifact. NEVER a filesystem path
+(F-16, owner ruling 2026-09-23)"* — and the change and optical-SAR specialists both emit `null` on every
+path (§4.3).
+
+### 1.2 The validation chain
+
+`preprocessing/raster.py` is the first thing every uploaded asset meets. Its module docstring names the
+chain it implements, verbatim:
+
+```
+file -> dimensions -> bands -> dtype -> CRS -> transform -> bounds -> nodata
+     -> modality -> temporal metadata
+```
+
+The module's three design rules are stated at the top of the file and are worth quoting because they
+govern every failure mode below:
+
+> * 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.
+
+### 1.3 `inspect_raster` — header-only validation
+
+`inspect_raster` (`preprocessing/raster.py:96`) validates and describes a raster **without loading its
+pixel data**. Its exact signature:
+
+```python
+def inspect_raster(
+    path: str | Path,
+    *,
+    max_pixels: int | None = None,
+    explicit_modality: str | None = None,
+    compute_hash: bool = False,
+    sensor: SensorDescriptor | None = None,
+) -> AssetMetadata:
+```
+
+The behaviour, field by field:
+
+- The path is checked with `Path(path).exists()` and `is_file()`; a missing path raises `RasterReadError`.
+- `rasterio` is imported lazily; an `ImportError` raises `RasterReadError` rather than a bare error.
+- Inside `rasterio.open(p)`, the reader extracts `width`, `height`, `count`, the sorted set of `dtypes`,
+  the CRS as a string (`ds.crs.to_string() if ds.crs else None`), the affine transform truncated to its
+  first six coefficients (`list(ds.transform)[:6] if ds.transform else None`), the bounds
+  (`list(ds.bounds)`), `nodata`, `resolution` (`list(ds.res)`), the `driver` string, and a tiled flag
+  read through `_safe_is_tiled`.
+- `_safe_is_tiled` (`preprocessing/raster.py:42`) exists because `DatasetReader.is_tiled` is scheduled for
+  removal; it suppresses the pending deprecation and **degrades to `False`** rather than aborting, since
+  the flag is informational metadata only.
+- Degenerate dimensions (`width <= 0 or height <= 0`) raise `RasterReadError`.
+- If `max_pixels` is given and `width * height > max_pixels`, it raises `OversizedImageError` — and the
+  docstring records that this is **recoverable**: *"the caller may downscale"*.
+- A band count `<= 0` raises `UnsupportedBandsError`.
+- Anything else rasterio raises is wrapped: `RasterReadError(f"could not open raster '{p}': {exc}")`.
+
+The return is an `AssetMetadata` (see §1.4) with `modality` from `infer_modality` (§6) and, when
+`compute_hash=True`, the streaming SHA-256 of the file (`file_sha256`, `preprocessing/raster.py:82`,
+chunked at 1 MiB).
+
+`inspect_raster` is called from `core/controller.py::_inspect_asset` during the VALIDATE state, with the
+configured pixel budget passed through. That means the **header-only** nature of the inspection is a real
+property of the serving path: a request never decodes a raster just to learn its shape.
+
+### 1.4 `AssetMetadata` and `GeoMetadata`
+
+`GeoMetadata` (`core/schemas.py:120`) is the geospatial detail carrier. It is `extra="allow"`, which is
+deliberate — the optical-SAR specialist adds cross-sensor keys to it (§4.3):
+
+| Field | Type | Meaning |
+|---|---|---|
+| `crs` | `str \| None` | CRS as a string (e.g. `EPSG:4326`), or `None` |
+| `transform` | `list[float] \| None` | Affine coefficients, row-major, six values |
+| `bounds` | `list[float] \| None` | `[minx, miny, maxx, maxy]` |
+| `width`, `height` | `int \| None` | Raster dimensions in pixels |
+| `band_count` | `int \| None` | Number of bands |
+| `dtype` | `str \| None` | Comma-joined distinct dtypes when the bands disagree |
+| `nodata` | `float \| None` | The nodata sentinel, or `None` |
+| `resolution` | `list[float] \| None` | `(xres, yres)` |
+| `has_crs` | `bool` | `crs_value is not None` |
+| `is_georeferenced` | `bool` | `bool(crs_value and transform)` |
+
+`AssetMetadata` (`core/schemas.py:153`) is `extra="forbid"` and carries:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `asset_id` | `str` | Minted `asset_<12 hex>`, opaque |
+| `path` | `str` | Resolved local path |
+| `modality` | `Modality` | From `infer_modality`, or declared |
+| `sha256` | `str \| None` | Present only when `compute_hash=True` |
+| `geo` | `GeoMetadata` | The block above |
+| `sensor` | `SensorDescriptor \| None` | Present only when a sensor descriptor was supplied |
+| `acquisition_date` | `str \| None` | Temporal metadata |
+| `scene_id`, `dataset_id`, `split` | `str \| None` | Provenance for leakage control |
+
+Note the distinction between `has_crs` and `is_georeferenced`: a raster can carry a CRS but no affine
+transform (or vice versa), and both are recorded. Only when **both** are present is
+`is_georeferenced=True`. `geospatial/transform.py::to_geo` requires the transform, so a raster with
+`has_crs=True` but `transform=None` cannot be converted to geographic coordinates — it will raise
+`CoordinateError("cannot convert to geo: raster has no affine transform")`.
+
+### 1.5 Band reading, writing, and pixel area
+
+`read_bands` (`preprocessing/raster.py:188`) returns `(bands, H, W)` plus a profile that **retains**
+`crs`, `transform` and `bounds` as plain values, so downstream code never loses georeferencing. The
+profile is a copy of `ds.profile` with those three keys overwritten from the live dataset.
+
+`write_raster` (`preprocessing/raster.py:221`) writes an array using a profile captured by `read_bands`,
+and re-applies `crs` and `transform` explicitly in the `rasterio.open(..., "w", ...)` call. It is used by
+evidence generation so change maps stay georeferenced — **except** when the pair is suppressed for poor
+registration, in which case the transform is deliberately dropped (§9.1).
+
+`pixel_area_m2` (`preprocessing/raster.py:259`) returns the area of one pixel in square metres **when the
+CRS is metric**, and `None` otherwise:
+
+```python
+def pixel_area_m2(meta: AssetMetadata) -> float | None:
+    from geospatial.crs import is_metric
+    if not is_metric(meta.geo.crs):
+        return None
+    if not meta.geo.resolution or len(meta.geo.resolution) < 2:
+        return None
+    xres, yres = meta.geo.resolution[0], meta.geo.resolution[1]
+    return abs(xres * yres)
+```
+
+The docstring is explicit: *"Returns None for geographic CRS or unknown resolution — callers must not
+guess."* A degree-based CRS has no meaningful pixel area in metres, so the function refuses rather than
+returning a plausible-looking number.
+
+---
+
+## 2. CRS handling (`geospatial/crs.py`)
+
+CRS comparison is kept **separate** from pixel arithmetic so that *"can these two rasters be compared at
+all?"* is answerable without touching pixels (`geospatial/crs.py` docstring). The module depends on
+`pyproj`.
+
+### 2.1 `parse_crs`
+
+```python
+def parse_crs(value: str | None) -> CRS | None:
+    if value is None or value == "":
+        return None
+    try:
+        return CRS.from_user_input(value)
+    except PyProjCRSError as exc:
+        raise MissingCRSError(f"unparseable CRS '{value}': {exc}") from exc
+```
+
+Absent is `None`; malformed raises. That distinction matters: a missing CRS is a legitimate state
+(degrades to non-geospatial), while a *malformed* one is a defect that must surface.
+
+### 2.2 `describe_crs`
+
+`describe_crs` returns a dict for the execution trace: `present`, `srs`, `name`, `is_geographic`,
+`is_projected`, and `axis_units` (the first axis's `unit_name`). For an absent CRS it returns
+`{"present": False}`.
+
+### 2.3 `compare_crs` and `CRSCompatibility`
+
+`CRSCompatibility` (`geospatial/crs.py:19`) is a frozen dataclass with `compatible`, `identical`,
+`same_units`, `left`, `right`, `reason`, and a derived property:
+
+```python
+@property
+def requires_reprojection(self) -> bool:
+    return self.compatible and not self.identical
+```
+
+`compare_crs` (`geospatial/crs.py:59`) decides:
+
+- **A missing CRS on either side is NOT compatible.** The reason string is
+  `"one or both rasters lack a CRS; spatial comparison is unsafe"`. The docstring records that this is
+  *"not fatal for non-spatial tasks"*.
+- **Identical CRS** (`crs_l.equals(crs_r)`) returns `identical=True`, reason `"identical CRS"`.
+- **Same kind** (both projected or both geographic) returns `compatible=True, identical=False`, reason
+  `"reprojection required (<left name> -> <right name>)"`.
+- **Mixed projected/geographic** returns `compatible=True, identical=False`, with a reason that adds
+  *"reprojection required and should be verified"*. The comment records the rationale: *"Mixing a
+  projected CRS with a geographic one is legal to reproject but signals a pipeline mistake."*
+
+`same_units` compares the first axis's `unit_name` on each side (defaulting to `"unknown"` when there is
+no axis info).
+
+**Crucially: `compare_crs` never reprojects.** It reports whether reprojection is *required*; the actual
+transform is not implemented anywhere (§13).
+
+### 2.4 `is_metric`
+
+```python
+def is_metric(crs_value: str | None) -> bool:
+    crs = parse_crs(crs_value)
+    if crs is None:
+        return False
+    if not crs.is_projected:
+        return False
+    if not crs.axis_info:
+        return False
+    return crs.axis_info[0].unit_name in {"metre", "meter", "m"}
+```
+
+A geographic CRS is never metric here, and the unit check is a closed set of three spellings.
+
+### 2.5 Where CRS comparison is used
+
+The only consumer on the serving path is the change specialist's `_assess_pair`
+(`specialists/change/specialist.py:251`):
+
+```python
+compat = compare_crs(t1.geo.crs, t2.geo.crs)
+if not compat.compatible:
+    warnings.append(
+        f"CRS comparison unavailable ({compat.reason}); change is "
+        f"reported in normalized pixel coordinates only"
+    )
+elif compat.requires_reprojection:
+    warnings.append(
+        f"T1 and T2 use different CRS ({compat.reason}); change is "
+        f"valid only if the rasters already share a pixel grid"
+    )
+```
+
+The comment above it states the policy precisely: *"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."* The
+withholding happens in `ChangeSpecialist._geospatial`, which drops the transform when registration is
+unusable (§9.1).
+
+---
+
+## 3. Affine transforms and coordinate frames
+
+`geospatial/transform.py` is where a normalised 0–1 box, a pixel box and a geographic box are converted
+between. Its module docstring states the non-negotiable rules (citing `docs/ARCHITECTURE_FREEZE.md`
+§2.6):
+
+> * CRS and affine transform are preserved, never silently stripped.
+> * Conversions are explicit about their source and target frames.
+> * A conversion that cannot be performed raises, rather than returning a plausible lie.
+
+That last line is the module's governing principle, and it is why `to_normalized`, `to_pixel` and
+`to_geo` all raise `CoordinateError` when they lack the context a conversion needs.
+
+### 3.1 `PixelWindow` and `GeoBounds`
+
+`PixelWindow` (`geospatial/transform.py:29`) is a frozen dataclass of `[col_min, row_min, col_max,
+row_max]`. Its `__post_init__` **raises** on an inverted window:
+
+```python
+if self.col_max < self.col_min or self.row_max < self.row_min:
+    raise CoordinateError(f"pixel window is inverted: {self.as_list()}")
+```
+
+It exposes `width`, `height` and `area` properties. `GeoBounds` (`geospatial/transform.py:60`) is the
+geographic cousin: `(minx, miny, maxx, maxy)`.
+
+### 3.2 Normalised ↔ pixel
+
+`normalized_to_pixel(box, width, height)` multiplies each coordinate by the corresponding dimension. Its
+docstring records a deliberate choice:
+
+> Values are NOT clipped: a box slightly outside the frame is preserved so the caller can decide whether
+> that is a bug or a legitimate edge case.
+
+It raises `CoordinateError` if `len(box) != 4` or if either dimension is `<= 0`.
+`pixel_to_normalized` is the inverse, dividing by the dimensions.
+
+### 3.3 Pixel ↔ geographic
+
+`pixel_to_geo(window, transform)` applies the affine transform to two corners. The docstring explains the
+axis convention:
+
+> rasterio/affine transforms map (col, row) -> (x, y). The y axis usually points down in pixel space, so
+> the geographic miny comes from the BOTTOM row.
+
+It uses the non-deprecated matmul form `transform @ (col, row)` and then takes `min`/`max` across the two
+corners so the returned `GeoBounds` is ordered. It raises `CoordinateError` if the transform is `None`.
+
+`geo_to_pixel(bounds, transform)` inverts the transform with `~transform`, raising `CoordinateError` if
+the inverse cannot be computed (`"affine transform is not invertible: ..."`).
+
+### 3.4 Schema-aware conversions
+
+`to_normalized`, `to_pixel` and `to_geo` operate on `Box` objects and are schema-aware — they read
+`box.coordinate_system` and return a `Box` with the target system set. The context each requires is
+documented in the docstring:
+
+- `pixel -> normalized` requires `width` and `height`.
+- `geo -> normalized` requires `width`, `height` **and** the affine `transform`.
+
+Each returns early when the box is already in the target frame, and otherwise uses
+`box.model_copy(update={...})` to produce a new box with the new coordinates and the new
+`coordinate_system`.
+
+### 3.5 Intersection and IoU
+
+`intersect(a, b)` returns the axis-aligned intersection of two `PixelWindow`s, or `None` when they are
+disjoint. `iou(a, b)` computes intersection-over-union in `[0, 1]`, returning `0.0` for a disjoint pair
+or a zero-area union. These are used by the grounding NMS path and by change-region overlap.
+
+### 3.6 `affine_from_metadata`
+
+```python
+def affine_from_metadata(geo: GeoMetadata) -> Affine | None:
+    if not geo.transform or len(geo.transform) != 6:
+        return None
+    a, b, c, d, e, f = geo.transform
+    return Affine(a, b, c, d, e, f)
+```
+
+A `GeoMetadata` whose transform is missing or not exactly six values yields `None`; callers treat that as
+"cannot georeference" rather than as an error. This is the bridge the grounding specialist uses in
+`_to_geo_boxes` (§4.3).
+
+---
+
+## 4. The coordinate-system contract
+
+### 4.1 The enum
+
+`CoordinateSystem` (`core/schemas.py:57`) has exactly three members, and the class docstring is a warning
+in itself — *"Never omit this. A bare box is meaningless without it. (C-5)"*:
+
+```python
+class CoordinateSystem(str, Enum):
+    NORMALIZED_0_1 = "normalized_0_1"
+    PIXEL = "pixel"
+    GEO = "geo"
+```
+
+`docs/API_CONTRACT.md` §3.2 fixes the meaning of each value:
+
+| Value | Meaning | Rendering |
+|---|---|---|
+| `normalized_0_1` | `[0, 1]`, origin **top-left** | Multiply by image width/height |
+| `pixel` | Absolute pixel coordinates | Use directly |
+| `geo` | CRS coordinates (usually EPSG:4326) | Requires a map, not a 2-D canvas |
+
+The contract adds a hard warning: *"The frontend must read the `coordinate_system` field on each
+`Box`/`Region` and must not assume one convention. A box drawn with the wrong assumption lands in
+plausible-looking wrong places."* It also records that earlier drafts used shorthand (`normalized`,
+`geographic`) and that those strings are **wrong** — they would fail schema validation, because the
+models are `extra="forbid"` and the enum is closed.
+
+### 4.2 Why it is mandatory — the schema validator
+
+The `Box` model (`core/schemas.py:171`) defaults `coordinate_system` to
+`CoordinateSystem.NORMALIZED_0_1`, and its `_ordered` validator rejects a box whose coordinates do not
+satisfy `x2 >= x1` and `y2 >= y1`. `Region` (`core/schemas.py:189`) and `ChangeRegion`
+(`core/schemas.py:202`) both carry the same field with the same default.
+
+The enforcement that matters is on `Evidence`. `Evidence._spatial_needs_crs`
+(`core/schemas.py:238`) **rejects a spatial evidence item that carries coordinates but no
+coordinate system**:
+
+```python
+@model_validator(mode="after")
+def _spatial_needs_crs(self) -> "Evidence":
+    spatial = {
+        EvidenceType.BOUNDING_BOX,
+        EvidenceType.MASK,
+        EvidenceType.CHANGE_MAP,
+        EvidenceType.TILE,
+        EvidenceType.IMAGE_CROP,
+        EvidenceType.JOINT_FEATURE_REGION,
+    }
+    if self.type in spatial and self.coordinates and self.coordinate_system is None:
+        raise ValueError(
+            f"evidence type '{self.type.value}' carries coordinates "
+            "but no coordinate_system"
+        )
+    return self
+```
+
+So a bare box cannot be published as evidence. The validator fires only when the item both is of a
+spatial type **and** carries coordinates — a `STATISTIC` or `GEOLOCATION` item with no coordinates is
+unaffected, and a spatial item with no coordinates (e.g. an availability-mask record) is also unaffected.
+`GEOLOCATION` is deliberately **not** in the spatial set: a geolocation is a point reference, not a
+rectangle, and the grounding specialist sets its `coordinate_system` to `GEO` explicitly anyway.
+
+Note the interaction with `extra="forbid"`: `Evidence` forbids extra keys, so an author cannot smuggle a
+convention through an undeclared field. `GeoMetadata`, by contrast, is `extra="allow"`, which is how the
+optical-SAR specialist attaches cross-sensor keys (§4.3).
+
+### 4.3 What each specialist emits
+
+| Specialist | Boxes / regions | Evidence coordinate systems |
+|---|---|---|
+| `grounding` | `Box` and `Region` in `NORMALIZED_0_1` | `BOUNDING_BOX` in `NORMALIZED_0_1`; a `GEOLOCATION` item in `GEO` when the CRS allows; `STATISTIC` items with no coordinates |
+| `change` | `ChangeRegion` and `Region` in `NORMALIZED_0_1` | `CHANGE_MAP` and `BOUNDING_BOX` in `NORMALIZED_0_1`; `STATISTIC` items with no coordinates |
+| `optical_sar` | No `regions` (empty list) | `AVAILABILITY_MASK` items (no coordinates); `OPTICAL_VIEW` / `SAR_VIEW` with `coordinates=[0,0,1,1]` in `NORMALIZED_0_1`; a `JOINT_FEATURE_REGION` in `NORMALIZED_0_1`; `STATISTIC` items |
+
+**Grounding.** `GroundingSpecialist.execute` (`specialists/grounding/specialist.py:253`) builds every box
+with an explicit system:
+
+```python
+boxes = [
+    Box(
+        x1=d.box[0], y1=d.box[1], x2=d.box[2], y2=d.box[3],
+        score=d.score, label=request.query,
+        coordinate_system=CoordinateSystem.NORMALIZED_0_1,
+    )
+    for d in decoded
+]
+```
+
+Geographic boxes are **derived, never replacements**: `_to_geo_boxes` (`specialists/grounding/specialist.py:431`)
+converts the normalised boxes to geographic bounds *only* when the raster has a CRS, a transform and
+dimensions, and emits a `GEOLOCATION` evidence item with `coordinate_system=CoordinateSystem.GEO`. When
+the raster has no CRS/transform, the method appends a warning —
+*"raster has no CRS/transform; boxes are reported in normalized coordinates only and cannot be placed on a
+map"* — and returns an empty list. The result's boxes stay normalised; the geo boxes are additional
+evidence for a consumer with a CRS. Its own comment states the rule: *"Pixel and geo coordinates are
+DERIVED, never replacements."*
+
+**Change.** `regions_to_schema` (`specialists/change/postprocess.py:443`) builds `ChangeRegion` objects in
+the requested system. It supports `NORMALIZED_0_1` and `PIXEL` and **raises** for anything else:
+
+```python
+else:
+    raise ValueError(
+        f"regions_to_schema cannot produce {coordinate_system.value} "
+        f"coordinates; convert after this call"
+    )
+```
+
+The change specialist calls it with the default (`NORMALIZED_0_1`). Geographic conversion is a deliberate
+post-step — the docstring records: *"Callers that want geographic coordinates convert afterwards via
+`geospatial.transform`, which keeps this function free of rasterio and CRS concerns."*
+
+**Optical-SAR.** The specialist emits no `regions`. Its view evidence items carry
+`coordinates=[0.0, 0.0, 1.0, 1.0]` in `NORMALIZED_0_1` — the whole frame — because the view is a
+presentation of the canonical tensor, not a localisation. Its `geospatial` block is the **optical**
+asset's georeferencing (chosen because it is the asset a reader can navigate by), with cross-sensor keys
+added via `GeoMetadata`'s `extra="allow"`: `optical_crs`, `sar_crs`, `sar_bounds`, `sar_resolution`,
+`optical_availability`, `sar_availability`, `optical_sensor`, `sar_sensor`, and
+`resolution_ratio_sar_to_optical` when both resolutions are known
+(`specialists/optical_sar/specialist.py:597`). The comment records the reason the two footprints are
+carried separately rather than fused: *"RISAT and Cartosat-2S are different missions with different
+orbits."*
+
+---
+
+## 5. Benchmark box scale — 0–100 versus 0–1
+
+This is a small contract with an outsized failure mode, and the codebase treats it as such.
+
+### 5.1 The two conventions
+
+- **VRSBench** (the grounding benchmark) states verbatim that *"all box coordinates are normalized to
+  0-100"*.
+- **This project** stores every box normalised to **0–1**.
+
+Treating a 0–100 box as a pixel box, or as a 0–1 box, is a silent, catastrophic bug: the numbers are all
+in range, the schema accepts them, and the box lands in the wrong place.
+
+### 5.2 The conversion functions
+
+`geospatial/transform.py:286` provides the conversion, and its docstring names the failure mode it exists
+to prevent:
+
+```python
+def benchmark_boxes_to_normalized(
+    boxes: Iterable[Sequence[float]], scale: float = 100.0
+) -> list[list[float]]:
+    """Convert benchmark boxes (e.g. VRSBench's 0-100) to our internal 0-1.
+
+    Finding from Phase 0: VRSBench states verbatim that "all box coordinates are
+    normalized to 0-100". Treating those numbers as pixels is a silent, catastrophic
+    bug — this function exists so that mistake can be made once, explicitly.
+    """
+    if scale <= 0:
+        raise CoordinateError(f"box scale must be positive, got {scale}")
+    ...
+    out.append([float(v) / scale for v in b])
+```
+
+`normalized_boxes_to_benchmark` is the exact inverse (multiply by `scale`). Both raise on a
+non-positive scale and on a box that is not four values.
+
+A second, independent conversion lives in the evaluation metrics:
+`evaluation/metrics/grounding.py::benchmark_to_normalized(box, scale=100.0)` divides by the scale and
+raises `ValueError(f"scale must be positive, got {scale}")` on a non-positive value. `docs/API_CONTRACT.md`
+§3.2 names it explicitly as the site of the VRSBench conversion.
+
+### 5.3 The declared scale
+
+`configs/base.yaml` declares the conversion factor in the grounding block, with a comment that restates
+the convention:
+
+```yaml
+grounding:
+  ...
+  # VRSBench stores boxes normalised to 0-100; we store 0-1.
+  benchmark_box_scale: 100.0
+  coordinate_system: normalized_0_1
+```
+
+`benchmark_box_scale: 100.0` is therefore the **declared** value, and `100.0` is also the **default
+argument** in both conversion functions. The two agree.
+
+### 5.4 The double-application risk
+
+Because the scale appears in three places — the config key, the `geospatial.transform` default and the
+`evaluation.metrics.grounding` default — there is a real hazard that a caller converts 0–100 → 0–1 and
+then a downstream stage divides by 100 again, producing a box 100× too small in each coordinate. The
+codebase's mitigations are structural rather than documentary:
+
+1. **The conversion is named for its direction.** `benchmark_boxes_to_normalized` and
+   `normalized_boxes_to_benchmark` are inverses with self-describing names, so a reader cannot easily
+   apply the wrong one without noticing.
+2. **The default is the correct scale, not `1.0`.** A caller that forgets to pass `scale` gets `100.0`,
+   which is right for VRSBench and would produce an obviously wrong box (values > 1) for already-0–1
+   input — a loud failure, not a silent one.
+3. **The schema rejects out-of-range values indirectly.** A `Box` built from un-divided VRSBench
+   coordinates would have `score` in range but coordinates in `[0, 100]`; the `_ordered` validator would
+   pass it (the ordering is still valid), so the schema alone does **not** catch this. The catch is that
+   the metrics module's own `benchmark_to_normalized` is the documented entry point, and the resolution
+   experiment and the grounding evaluation both go through it.
+
+**Residual risk — stated honestly.** There is no runtime assertion that a `Box` in
+`NORMALIZED_0_1` actually has coordinates within `[0, 1]`. `Box._ordered` checks only ordering. A
+mis-scaled box would therefore pass schema validation. `UNKNOWN — not established from the available
+evidence` whether any production call site currently constructs a `Box` without going through one of the
+two conversion functions; the serving path (`GroundingSpecialist.execute`) builds boxes from the decoder's
+output, which is already in `[0, 1]`, so the serving path is not exposed. The risk is confined to
+evaluation and experiment code that reads VRSBench directly.
+
+---
+
+## 6. Band-count modality inference
+
+### 6.1 The heuristics
+
+`preprocessing/raster.py` defines two closed sets:
+
+```python
+_OPTICAL_BAND_COUNTS = {3, 4, 8, 11, 12, 13}
+_SAR_BAND_COUNTS = {1, 2}
+```
+
+with the comment: *"Band-count heuristics for modality detection when explicit metadata is absent. These
+are heuristics, not ground truth — the sensor adapter is authoritative when a sensor descriptor is
+supplied."*
+
+### 6.2 `infer_modality`
+
+```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
+    # 12-band optical and 2-band SAR are both plausible; default to optical only
+    # when the count clearly favours it.
+    if band_count >= 4:
+        return Modality.OPTICAL
+    return Modality.UNKNOWN
+```
+
+The decision order is worth reading carefully:
+
+1. An **explicit** label wins if it parses to a `Modality` member. An explicit label that does *not* parse
+   (e.g. `"radar"`) is silently ignored and inference proceeds — the `except ValueError: pass` is
+   deliberate.
+2. `{1, 2}` ⇒ `SAR`.
+3. `{3, 4, 8, 11, 12, 13}` ⇒ `OPTICAL`.
+4. `>= 4` (and not already matched) ⇒ `OPTICAL`.
+5. Otherwise ⇒ `UNKNOWN`.
+
+So the effective mapping is: 1–2 ⇒ SAR; 3–13 ⇒ optical (by set or by the `>= 4` fallback); 0 or a
+non-positive count ⇒ `UNKNOWN` (though `inspect_raster` rejects `band_count <= 0` before this point).
+
+### 6.3 The declared-wins rule
+
+In the optical-SAR specialist, `_assess_pair` (`specialists/optical_sar/specialist.py:223`) uses the
+asset's **declared** modality first, falling back to band-count inference only when it is `UNKNOWN`:
+
+```python
+for asset in assets:
+    modality = asset.modality
+    if modality is Modality.UNKNOWN:
+        inferred = self._infer_modality(asset, warnings)
+        resolved.append(inferred)
+    else:
+        resolved.append(modality)
+```
+
+`_infer_modality` appends a warning that names the heuristic for what it is: *"A band count is a
+heuristic, not a sensor declaration — label the asset explicitly if this is wrong."* The docstring above
+`_assess_pair` states the rationale: *"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."*
+
+### 6.4 Why the heuristic is not authoritative
+
+The comment on the sets and the warning text both point at the same thing: a band count does not identify
+a *sensor*. A 2-band file could be a dual-pol SAR pair or a two-band optical stack; a 4-band file could be
+RGB+NIR or a four-polarisation SAR product. The adapter (§8) is the authoritative path, because it maps
+named bands onto CROMA's canonical channels and records what it could not place.
+
+---
+
+## 7. Radiometric normalisation and representation
+
+This section covers a genuine specification gap and its partial resolution. It is presented in full
+because the gap is load-bearing and the honest state is more useful than a tidy summary.
+
+### 7.1 What configuration declares
+
+`configs/base.yaml` declares two radiometric transforms:
+
+```yaml
+optical:
+  normalization: percentile
+  lower_percentile: 2
+  upper_percentile: 98
+  # CROMA expects exactly 12 optical channels.
+  canonical_channels: 12
+
+sar:
+  representation: db
+  clip_min_db: -30
+  clip_max_db: 5
+  # CROMA expects exactly 2 SAR channels (VV, VH).
+  canonical_channels: 2
+```
+
+So the declared optical normalisation is a **percentile stretch at the 2nd and 98th percentiles**, and the
+declared SAR representation is **decibels clipped to [−30, +5]**.
+
+### 7.2 The DEV-2 ruling — two ordered stages
+
+`docs/PHASE14_CROMA_NORMALISATION_CHANGE.md` records the ruling that governs this. The gap it confirmed:
+CROMA's own example preprocessing is a **per-channel** dynamic-range stretch
+(`mean ± 2·std → [0, 1]`, optionally through a uint8 round-trip), while `configs/base.yaml` specifies
+something structurally different. The ruling's verification table records that a grep of
+`specialists/optical_sar/` for `NORM_*`, `clip_min_db`, `lower_percentile`, `use_8_bit` returned **six
+hits, all constant definitions/labels** at `sensor_adapter.py:125,126,210,323,547,548`, and **zero
+application sites**.
+
+The ruling resolves this by declaring the pipeline to have **two ordered stages**, and it states
+explicitly that they are *not alternatives*:
+
+| Stage | Transform | Owner | Status |
+|---|---|---|---|
+| **Radiometric conditioning** | per-scene percentile / dB-clip, per `configs/base.yaml` | preprocessing / sensor adapter | **specified in the ruling, must be implemented** |
+| **Encoder-input normalisation** | per-channel `mean ± 2·std` → `[0,1]`, then optional `×255` uint8 → `/255` | a new function consumed by `croma.py` | **mandatory, immediate** |
+
+The rationale for the CROMA stage being mandatory: *"it is the only stage that bounds the input range.
+Without it the encoder receives unbounded input."* The `use_8_bit` branch is the safer default because
+the uint8 round-trip **guarantees** `[0, 1]`, whereas the float path's clip applies to a stretch that is
+unbounded by construction (`mean ± 2·std` is not a min/max clamp). The decision on `use_8_bit` is
+**ENABLED**.
+
+### 7.3 The implemented stage — `specialists/optical_sar/radiometry.py`
+
+The **encoder-input** stage is implemented, in full, at `specialists/optical_sar/radiometry.py`. Its
+module docstring states the boundary between what is and is not implemented:
+
+> Implemented: the **encoder-input** stage — per-channel `mean +/- 2*std` -> `[0, 1]`, the transform the
+> CROMA authors' own README instructs users to apply.
+>
+> NOT implemented: the percentile / dB **conditioning** stage that `base.yaml` names.
+
+The transform is quoted verbatim from the CROMA README in the docstring:
+
+```
+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
+```
+
+The module makes two **deliberate deviations** from the README, both documented:
+
+1. **Per sample, not per batch.** The README computes `x[:, c].mean()` over the whole batch, which makes
+   one image's encoding a function of its neighbours. This module computes the window **per sample**,
+   because *"a serving system whose whole point is reproducibility"* must not produce a different answer
+   because another request was batched alongside it. At `N = 1` the two are identical, and the README's
+   own example runs at `N = 1`.
+2. **Unbiased standard deviation (`ddof=1`).** Upstream is torch, whose `.std()` defaults to the unbiased
+   estimator; NumPy's defaults to `ddof=0`. The module uses `ddof=1` to match the reference
+   implementation, and states the numerical immateriality (~1.00003 factor at 120×120) so nobody has to
+   guess which convention a number came from.
+
+The key constants:
+
+| Constant | Value | Meaning |
+|---|---|---|
+| `TRANSFORM_NAME` | `"per_channel_mean_pm_2std"` | Recorded on every trace |
+| `WINDOW_SIGMAS` | `2.0` | The window half-width |
+| `DEFAULT_USE_8_BIT` | `True` | The ruling's decision |
+| `ENV_USE_8_BIT` | `"SATQUERY_CROMA_USE_8_BIT"` | Hash-exempt override channel |
+| `MIN_FINITE_PIXELS` | `2` | Below this, a std is not meaningful |
+| `STATUS_NORMALISED` / `STATUS_UNAVAILABLE` / `STATUS_DEGENERATE` | strings | Per-channel status |
+
+`normalise_for_croma(array, *, use_8_bit, modality)` is **pure and deterministic** — the docstring
+states: *"no sampling, no learned statistics, no RNG, and no dependence on batch composition. Same input
+-> same output."* It accepts `(B, C, H, W)` or `(C, H, W)`, returns a `float32` array of the same shape
+plus a `RadiometryReport`, and leaves skipped channels **exactly zero**.
+
+### 7.4 The zero-channel rule
+
+This is the load-bearing part, and it is the C-1 discipline applied to radiometry. An unavailable channel
+is all zeros (the sensor adapter's convention). Such a channel has `std = 0`, so `max_value - min_value
+== 0` and the stretch divides by zero. The module therefore **skips and leaves at exactly zero** any
+channel with no dynamic range, and records a **different status** for each reason:
+
+- `unavailable` — the channel is all zeros (`if not np.any(channel)`), i.e. the sensor did not measure it.
+- `degenerate` — the channel is present but constant (`_channel_window` returns `None` because
+  `upper - lower <= 0`), i.e. the sensor measured a flat band.
+- `normalised` — the real case.
+
+The docstring explains why the distinction matters: *"'the sensor did not measure this' is not the same
+fact as 'the sensor measured a flat band', and the trace must not merge them."* The mechanism is the
+degenerate-window test, which needs **no mask** — deliberately, because `CROMAEncoder.encode` has a
+pinned signature of exactly `(self, optical, sar)` and finding C-1 says CROMA never receives a mask.
+Inferring unavailability from the data keeps that guard intact.
+
+A non-finite pixel (NaN/Inf) is *"a defective measurement, not a measurement of zero"*; it is pinned to
+`0.0` rather than allowed to propagate a NaN into the frozen encoder, where *"one NaN would poison the
+whole forward pass."* The `finite_pixels` count in the report keeps the gap detectable.
+
+`resolve_use_8_bit(config)` resolves the flag in a documented order — environment variable first, then
+`croma.use_8_bit` when the key exists and is a bool, then `DEFAULT_USE_8_BIT` — and returns
+`(value, source)` where `source` is `"env"`, `"config"` or `"default"`. The reason it is not simply a
+config key is recorded: adding `croma.use_8_bit` to `configs/base.yaml` would move `Config.hash` away
+from the frozen `78f1e3700da15aa1` and detach the Phase 9 benchmark. The hash-exempt channel is the same
+pattern already used for `SATQUERY_DEVICE`.
+
+`summarise(optical_report, sar_report)` bundles both modalities under one `use_8_bit` and **asserts** they
+agree, raising `ValueError` if they do not: *"upstream applies one transform to both."*
+
+### 7.5 The display stretches — a different transform
+
+Two other percentile stretches exist in the codebase. Neither is the CROMA transform, and the DEV-2
+ruling names reusing one of them as **forbidden**.
+
+**`preprocessing/imagery.py::load_image_array`** produces a displayable `(H, W, 3)` uint8 array:
+
+```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)
+```
+
+Its docstring is explicit about its scope: 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."* The
+determinism claim is stated: *"the same file always yields the same array, so a grounding box and a VQA
+answer describe identical pixels."*
+
+`docs/PHASE14_CROMA_NORMALISATION_CHANGE.md` §1.1 records the three disqualifying differences between
+this stretch and CROMA's: it is **per-scene** (one `(lo, hi)` over all bands) rather than **per-channel**;
+it returns **uint8 3-band** rather than float 12-channel; and its **purpose** is presentation, not
+radiometry.
+
+**`specialists/change/postprocess.py::to_grayscale_float`** applies a per-scene 2/98 percentile stretch
+to a grayscale collapse, so that *"a uint16 raster and a uint8 raster of the same scene correlate
+identically."* Its comment records a measured defect fixed in place: `np.percentile` returns float64
+scalars even for float32 input, so the array is promoted; without the explicit
+`.astype(np.float32, copy=False)` the function returns float64 and `cv2.phaseCorrelate` fails its own
+type assertion against a `CV_32F` Hanning window — *"Measured, not theorised."*
+
+### 7.6 The unimplemented stage, and its consequence
+
+The percentile/dB conditioning stage is **not implemented**. The radiometry module's docstring states the
+consequence plainly:
+
+> **Consequence: the two `optical.*` and three `sar.*` config keys are still read by no code.** That is
+> recorded, not fixed.
+
+`docs/PHASE14_CROMA_NORMALISATION_CHANGE.md` §6 item 3 adds: *"A config key that no code reads is worse
+than a missing key: it reads as a satisfied requirement."* The ruling's follow-on table assigns the
+implementation to the engineer, with the alternative of explicitly retiring the keys.
+
+The status of the whole chain is therefore:
+
+| Stage | Declared | Implemented | Read by code |
+|---|---|---|---|
+| Optical percentile 2/98 conditioning | ✅ `optical.*` | ❌ | ❌ |
+| SAR dB clip −30/+5 conditioning | ✅ `sar.*` | ❌ | ❌ |
+| Per-channel `mean ± 2·std` → [0,1] | ✅ (ruling §3.1) | ✅ `radiometry.py` | ✅ (via `training/fusion/extract.py`; see below) |
+
+**Where the implemented stretch actually runs.** The serving-path pipeline
+(`specialists/optical_sar/inference.py::run_pipeline`) does **not** call `normalise_for_croma`. It
+canonicalises, resizes to 120×120 and calls `encoder.encode(...)`. The stretch is applied by the
+**extraction** path (`training/fusion/extract.py`), which states: *"This pipeline applies the DEV-2
+encoder-input stretch itself (`radiometry.normalise_for_croma`), because the arm's `use_8_bit` has to be
+applied at exactly one place."* `extract.py` also refuses an encoder that would stretch a second time:
+`_assert_raw_encoder` *"refuses it by name rather than trusting the caller."* So the implemented
+radiometric transform is a **training-time** transform that feeds the cached features, and the serving
+path's input scaling is whatever `CROMAEncoder.encode` does internally (see §8.9 and the CROMA module).
+
+`UNKNOWN — not established from the available evidence` whether the serving path's encoder applies the
+same `mean ± 2·std` stretch internally; `specialists/optical_sar/croma.py::CROMAEncoder.encode` was
+verified to have the pinned signature `(self, optical, sar)` with no mask parameter, and the extraction
+module's guard implies the encoder *can* apply a stretch when `normalize_input=True` (its default), but
+the exact serving configuration of that flag is not established from the files read for this chapter.
+
+---
+
+## 8. The CROMA sensor adapter contract
+
+`specialists/optical_sar/sensor_adapter.py` is *"the one place where 'some sensor's bands' becomes
+'CROMA's canonical channels', and it exists so that translation is explicit, inspectable and testable."*
+Its module docstring states **the two hard rules** from the architecture plan:
+
+> "No invented missing bands."
+> "Do not fabricate spectral bands."
+
+The failure mode the module prevents is described with unusual clarity:
+
+> A 4-band Cartosat-2S scene maps cleanly onto canonical channels 1-4. Filling channels 5-12 with
+> *something* — a copy of B3 as a fake "red-edge", a zero-order hold, an interpolation — produces a tensor
+> whose shape is correct and whose statistics look plausible. CROMA would run. Nothing would raise. And
+> every downstream number would be computed from channels that no sensor ever measured, presented as if
+> they were measurements.
+
+So: **missing channels are zero-filled, and the availability mask says which ones were real.**
+
+### 8.1 `SensorDescriptor`
+
+The schema object (`core/schemas.py:138`) is `extra="forbid"`, described as the *"Frozen sensor-adapter
+contract (plan section 18)"*:
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `sensor` | `str` | required | Sensor identifier, e.g. `"cartosat_2s"` |
+| `available_bands` | `list[str]` | `[]` | The bands the sensor actually delivers |
+| `band_map` | `dict[str, str]` | `{}` | Source band name → canonical band name |
+| `normalization` | `str` | `"percentile"` | Identifier recorded for the trace |
+| `availability_mask` | `list[bool]` | `[]` | Which canonical channels are real |
+| `resolution` | `float \| None` | `None` | Ground sample distance in metres |
+| `canonical_channels` | `int` | `0` | Target channel count (12 optical, 2 SAR) |
+| `missing_channels_zero_filled` | `bool` | `True` | The zero-fill convention |
+
+**Why `band_map` is canonical-channel-keyed.** The module docstring addresses a direction question: the
+plan's example writes `band_map` sensor-keyed (`{"B1": "c1", ...}`), and the schema types it as
+`dict[str, str]`. This module uses the schema's direction because the question asked at load time is
+forward-looking: *"canonical channel 3 — did I get a real band for it, and if so which one?"*
+`canonical_to_sensor` is exposed as the inverse for reporting.
+
+### 8.2 The canonical channel orders
+
+```python
+OPTICAL_CANONICAL: tuple[str, ...] = (
+    "B01",  # coastal aerosol
+    "B02",  # blue
+    "B03",  # green
+    "B04",  # red
+    "B05",  # red edge 1
+    "B06",  # red edge 2
+    "B07",  # red edge 3
+    "B08",  # NIR
+    "B8A",  # narrow NIR
+    "B09",  # water vapour
+    "B11",  # SWIR 1
+    "B12",  # SWIR 2
+)
+
+SAR_CANONICAL: tuple[str, ...] = ("VV", "VH")
+```
+
+The comment above `OPTICAL_CANONICAL` states the contract: *"The ORDER is part of the contract: channel
+index i must always mean the same physical band, or a pretrained encoder's weights would be applied to
+the wrong input."* This is Sentinel-2 L2A with the cirrus band removed, per CROMA's README: *"Sentinel-2
+must be 12 channels (remove the cirrus band if necessary)."* Note that `B10` (cirrus) is **not** in the
+canonical order — that is the removal.
+
+`SAR_CANONICAL` is described as *"Sentinel-1 dual-pol order CROMA was pretrained with. Positional fallback
+ONLY."*
+
+`_BAND_ALIASES` maps common spellings onto the canonical form: `B1`→`B01`, `BLUE`→`B02`, `NIR`→`B08`,
+`SWIR1`→`B11`, `VVPOL`→`VV`, and so on. The comment is a caution: *"Kept small and explicit: a guess here
+becomes a silently mislabelled band."* `_canonicalise` strips whitespace and underscores and uppercases
+before lookup, and **never invents** a band — an unmapped name passes through unchanged and is later
+rejected.
+
+### 8.3 Building an optical adapter
+
+`build_optical_adapter(sensor, *, available_bands, canonical_channels=12, normalization="percentile",
+resolution=None)` (`specialists/optical_sar/sensor_adapter.py:205`):
+
+- When `available_bands` is `None`, the sensor is looked up in `_KNOWN_OPTICAL_SENSORS`; an unknown
+  sensor with no explicit band list raises `UnsupportedBandsError` — *"refusing to guess a band
+  arrangement."*
+- Each band is canonicalised. Any canonical name **not** in `OPTICAL_CANONICAL` raises
+  `UnsupportedBandsError`: *"do not map onto the canonical Sentinel-2 order ... supply an explicit
+  band_map rather than guessing a position."*
+- Duplicate bands raise.
+- More bands than `canonical_channels` raises.
+- `band_map` is built as `{source: canonical for source, canonical in zip(bands, canonical)}` — keyed by
+  the **source** name, because *"that is what an array row can actually be looked up by."*
+- `availability` is `[canonical_name in band_map.values() for canonical_name in OPTICAL_CANONICAL[:canonical_channels]]`.
+
+The returned descriptor has `missing_channels_zero_filled=True`.
+
+`_KNOWN_OPTICAL_SENSORS` is *"deliberately tiny and explicit. Adding one is a code change, not a guess at
+runtime"*:
+
+| Sensor | Bands |
+|---|---|
+| `sentinel_2` | All 12 canonical |
+| `cartosat_2s` | `["B1", "B2", "B3", "B4"]` |
+| `cartosat_2` | `["B1", "B2", "B3", "B4"]` |
+| `landsat_8` | `["B1", "B2", "B3", "B4"]` |
+
+The comment on `cartosat_2s` is a standing instruction: *"Cartosat-2S is a 4-band VNIR imager. It is NOT a
+Sentinel-2 clone and must not be treated as one: the 8 channels it lacks stay masked-off."*
+
+### 8.4 Describing a SAR sensor — inspect, do not assume
+
+`describe_sar(sensor, *, available_bands, canonical_channels=2, normalization="db", resolution=None)`
+(`specialists/optical_sar/sensor_adapter.py:318`) implements the plan's instruction:
+
+> "RISAT imagery may vary in acquisition/polarization characteristics... the SAR adapter must inspect
+> actual available channels rather than assuming one fixed polarization pair."
+
+The module docstring explains why a hardcoded `["VV", "VH"]` would be wrong: *"ISRO describes RISAT-1 as
+a C-band SAR mission with multiple polarization configurations (single HH, single VV, dual HH+HV, dual
+VV+VH, ...). A hardcoded `["VV", "VH"]` would silently mislabel an HH/HV scene, and the resulting tensor
+would be a *confidently wrong* input rather than a recognisably broken one."*
+
+When `available_bands` names the polarisations, they are honoured. When it does not, the **channel count**
+is used to select the most likely convention, and **the choice is recorded on the descriptor's
+`available_bands`** so the assumption appears in the trace rather than being invisible.
+
+The **slot order is the sensor's own**:
+
+```python
+band_map: dict[str, str] = {source: source for source in bands}
+availability = [i < len(bands) for i in range(canonical_channels)]
+```
+
+The comment explains: *"Forcing HH/HV into a VV/VH frame would mean either relabelling the polarisations
+(a lie the mask would then contradict) or masking both off and discarding real data."* So the tensor holds
+the radar measurements that exist, and `available_bands[i]` says which polarisation slot `i` is.
+
+`_known_sar(sensor)` is described as *"Best-effort polarisation layout for a named SAR sensor, or `[]`"*:
+
+| Sensor key | Returns |
+|---|---|
+| `sentinel_1`, `sentinel1` | `["VV", "VH"]` |
+| `risat*` | `["VV", "VH"]` — **recorded as an ASSUMPTION, not a fact** |
+| `alos_palsar`, `palsar`, `alos2` | `["HH", "HV"]` |
+| anything else | `[]` — *"An empty return is honest: it says 'I do not know this sensor's polarisations'"* |
+
+The `risat` case carries an explicit comment: *"RISAT-1's most common operational mode is dual-pol.
+Recorded as an ASSUMPTION, not a fact — see the module docstring. Callers with real band metadata should
+pass `available_bands` and override this."* This is an `ASSUMPTION` in the project's status vocabulary,
+and it is the reason the hidden-set behaviour on RISAT cannot be claimed as measured.
+
+### 8.5 Applying the canonical layout — `_apply_canonical`
+
+This is *"the function the two hard rules live in"* (`specialists/optical_sar/sensor_adapter.py:428`). It
+places real bands in canonical positions and zero-fills the rest:
+
+```python
+canonical = np.zeros((n_canonical, height, width), dtype=np.float32)
+mask = np.zeros((n_canonical,), dtype=bool)
+
+for source_index, source_name in enumerate(descriptor.available_bands):
+    if source_index >= n_source:
+        continue
+    canonical_name = descriptor.band_map.get(source_name)
+    if canonical_name is None or canonical_name not in order:
+        continue
+    channel_index = order.index(canonical_name)
+    if channel_index >= n_canonical:
+        continue
+    canonical[channel_index] = array[source_index].astype(np.float32)
+    mask[channel_index] = True
+```
+
+The docstring's key claim: *"There is no branch anywhere below that writes a value into an unavailable
+channel."* The absence of such a branch **is** the mask. If no band could be placed while the array
+carries bands, it raises `UnsupportedBandsError` rather than returning an all-zero tensor silently.
+
+`_canonical_order(descriptor)` decides the slot order: for a descriptor whose `available_bands` are all
+SAR polarisations, the order is the descriptor's own list (padded to canonical width); otherwise it is
+`OPTICAL_CANONICAL`.
+
+`adapt_optical` and `adapt_sar` are thin wrappers that call `_apply_canonical` with the right modality
+label. `adapt_sar`'s docstring names the plan's internal representation exactly:
+`canonical_sar[2, H, W]` + `sar_channel_mask[2]`.
+
+### 8.6 `SensorAdapterOutput`
+
+The dataclass returned by `adapt_*` carries `canonical` `(C, H, W)` float32, `mask` `(C,)` bool, and the
+`descriptor`. It exposes `n_channels`, `missing_indices` (`[i for i, ok in enumerate(self.mask) if not
+ok]`), `available_bands`, and a `to_dict()` that includes `n_available` and `missing_channels`.
+
+### 8.7 `positional_fallback_descriptor`
+
+Used when a raster has the right **channel count** for a modality but **no band labels**. The fallback
+order is chosen from `_FALLBACK_SAR_ORDER` (`("VV", "VH")`, `("HH", "HV")`) for 1–2 channels, or the
+canonical optical prefix for ≥3 channels. The fact that it was a fallback is **recorded in the `sensor`
+field** so it *"cannot be mistaken for measured metadata."* The `complement=True` flag selects the other
+convention, which lets a caller test both HH/HV and VV/VH orderings without asserting which is correct.
+
+The optical-SAR specialist uses this in `_descriptor_for`
+(`specialists/optical_sar/specialist.py:398`) and appends a warning that names the assumption: *"The
+polarisation IDENTITY of each channel is NOT known from a band count alone — supply a sensor descriptor
+to state it."*
+
+### 8.8 Finding C-1 — the mask goes to the fusion head, not to CROMA
+
+This is the single most important fact in this section. `core/schemas.py`'s module docstring lists it
+among the findings baked into the schemas: *"C-1 channel-availability mask is a first-class fusion input,
+never a CROMA input."*
+
+`specialists/optical_sar/fusion_head.py` devotes a section to the rationale:
+
+> CROMA is a masked autoencoder. Handing it an availability mask invites it to reconstruct the missing
+> channels — which is precisely the fabrication the sensor adapter exists to prevent: the model would
+> output plausible values for bands no sensor measured, and those values would then be treated as data.
+> The mask is therefore consumed HERE, where it can only do one thing: tell the classifier which inputs
+> to distrust.
+
+Mechanically: `CROMAEncoder.encode` has a pinned signature of exactly `(self, optical, sar)` — the
+radiometry module records that `tests/unit/test_optical_sar_croma.py` *"asserts the absence of any mask
+parameter, because freeze finding C-1 says CROMA never receives one."* The mask instead enters at
+`assemble_fusion_input` (§8.9). The optical-SAR specialist's `JOINT_FEATURE_REGION` evidence item records
+the fact explicitly in its payload: `"mask_consumed_by": "fusion_head"` and `"croma_received_mask":
+False` (`specialists/optical_sar/specialist.py:816`).
+
+`EvidenceType` even has a dedicated member for the mask as trust evidence:
+`AVAILABILITY_MASK = "availability_mask"   # C-1: modality trust evidence` (`core/schemas.py:76`). The
+optical-SAR specialist emits one `AVAILABILITY_MASK` item per modality, carrying the sensor, canonical
+channel count, available bands, band map, the mask itself, the missing indices,
+`missing_channels_zero_filled`, `normalization` and `resolution`.
+
+### 8.9 The frozen fusion concatenation
+
+`specialists/optical_sar/fusion_head.py` defines the concatenation that the mask feeds into:
+
+```
+optical_GAP      (B, 768)
+SAR_GAP          (B, 768)
+joint_GAP        (B, 768)
+optical_mask     (B,  12)     <- availability, from the sensor adapter
+sar_mask         (B,   2)     <- availability, from the sensor adapter
+                 ---------
+concat           (B, 2318)
+```
+
+`expected_fusion_dim(encoder_dim=768, optical_channels=12, sar_channels=2, modalities_used=3)` returns
+`3*768 + 12 + 2 = 2318`. The module recomputes the width and **refuses to build on a mismatch**, so *"a
+config edit cannot silently reshape the first Linear layer into something that trains but means
+nothing."* `core/config.py` recomputes it independently at load time from `croma.encoder_dim`,
+`croma.modalities_used`, `croma.optical_channels` and `croma.sar_channels`, and rejects a config whose
+`fusion.input_dim` disagrees (finding C-1 in the validator's own message).
+
+`assemble_fusion_input` asserts the order rather than assuming it — *"a permutation here produces a tensor
+of exactly the right shape that trains to a worse number — the hardest kind of bug to notice"* — and
+validates that the three GAP vectors agree on batch size and that both masks agree with it.
+
+`channel_dropout(features, mask, *, keep_probabilities, rng)` is the mechanism that *"teaches the head to
+trust the availability mask"*. Its load-bearing line is:
+
+```python
+keep = draws & (msk > 0.0)
+out_mask = keep.astype(np.float32)
+out = out * out_mask
+```
+
+Dropped channels are **zeroed, not renormalised** — *"renormalising would fabricate a scale that the real
+missing-channel case does not have"* — and the mask is updated in lockstep. `docs/PHASE14_CROMA_NORMALISATION_CHANGE.md`
+§5 independently verified this against freeze §2.5 and ruled: *"the engineer's implementation SATISFIES
+§2.5's intent. No change entry required."* Its table records that the `& (msk > 0.0)` guard is the
+load-bearing one: *"no training transform can resurrect a band the sensor did not measure."*
+
+The schedule (plan section 20) is optical at `100/80/60/40%` and SAR at `100/50%`, declared in
+`training/fusion/train.py` as `OPTICAL_DROPOUT_RATES = (1.0, 0.8, 0.6, 0.4)` and
+`SAR_DROPOUT_RATES = (1.0, 0.5)`.
+
+`mask_availability_stats(optical_mask, sar_mask)` returns `optical_available_fraction`,
+`sar_available_fraction`, `optical_channels_present` and `sar_channels_present`. These feed the
+confidence system: the two modality-confidence terms in the optical-SAR specialist are exactly the
+availability fractions, which the specialist's docstring justifies: *"On the hidden set the optical side
+is Cartosat-2S with 4 bands against a canonical 12, so 8 of 12 channels are always absent. A classifier
+resting on 4 measured channels is not the same claim as one resting on 12."*
+
+### 8.10 The optical-SAR confidence components
+
+`OpticalSarSpecialist._confidence_components` (`specialists/optical_sar/specialist.py:481`) implements
+plan section 26's four components with these weights:
+
+```python
+CONFIDENCE_WEIGHTS: dict[str, float] = {
+    "fusion_margin": 0.40,
+    "optical_confidence": 0.20,
+    "sar_confidence": 0.20,
+    "cross_modal_agreement": 0.20,
+}
+```
+
+`cross_modal_agreement` is `cosine(optical_GAP, SAR_GAP)`, rescaled from `[-1, 1]` to `[0, 1]` via
+`AGREEMENT_FLOOR = -1.0`. `cross_modal_agreement` in `inference.py` returns `None` on any exception or a
+shape mismatch, and the specialist treats `None` as a zero component. The composition is a weighted sum,
+**floored to 0.0** when there is no prediction or no trained head — *"Both are signal GAPS, not weak
+signals, so they resolve to 0.0 rather than merely discounting."* The components dict records
+`has_croma`, `trained_head`, `no_prediction` and the raw availability counts, so *"the trace states every
+reason the score is zero, not just the first one encountered."*
+
+---
+
+## 9. Pair-compatibility rules
+
+Two workflows take a **pair** of assets, and both enforce compatibility before reading pixels.
+
+### 9.1 Change — exactly two, temporally distinct, co-registered
+
+`ChangeSpecialist.validate_request` (`specialists/change/specialist.py:190`) enforces **exactly two**
+assets. The comment names both common mistakes: *"ONE asset is the common mistake: the caller treated
+this as a single-image task. THREE is the other: they attached a time series. Both are rejected with the
+same typed error."* The user-facing message is *"Change detection needs exactly two images: an earlier one
+and a later one."*
+
+`_assess_pair` then runs three checks in order:
+
+1. **Temporal distinctness.** Identical `path` raises `TemporalPairError`. Identical `sha256` (when both
+   carry one) also raises: *"a repeated acquisition is not a temporal pair."*
+2. **CRS compatibility** via `compare_crs` (§2.5). Incompatible or reprojection-requiring pairs get a
+   warning, not a refusal — pixel-domain change detection can still proceed, but geographic claims are
+   withheld.
+3. **Registration quality** via `measure_registration` (§9.3).
+
+If registration is **not usable**, the specialist **suppresses spatial claims** while still computing and
+returning the change maps:
+
+> The maps are still returned (the caller may want to look at them), but the REGION CLAIMS are withheld:
+> a region is an assertion about *where* something changed on the ground, and we cannot make it.
+
+`ChangeSpecialist._geospatial` drops the transform in that case, returning a `GeoMetadata` with
+`is_georeferenced=False` — *"a transform invites the caller to place a region on a map, and we have just
+said the regions are not placeable."* `_write_artifacts` writes the map **without** georeferencing when
+suppressed, and the comment explains why copying T1's transform would be wrong: *"Copying T1's transform
+onto it would produce a file that unlocks exactly the placed-on-a-map reading the suppression exists to
+forbid."* The confidence is driven to the floor via a **minimum** against the registration factor, so
+alignment is a gate, not one vote among three.
+
+The change confidence weights are:
+
+```python
+CONFIDENCE_WEIGHTS: dict[str, float] = {
+    "registration_quality": 0.50,
+    "mean_change_probability": 0.30,
+    "component_stability": 0.20,
+}
+```
+
+with `STABILITY_HEADROOM = 0.5`, `DEFAULT_MAX_SHIFT_PX = 8`, `MIN_REGION_PIXELS = 32`.
+
+### 9.2 Optical-SAR — exactly two, one of each modality
+
+`OpticalSarSpecialist.validate_request` (`specialists/optical_sar/specialist.py:192`) enforces **exactly
+two** assets **and** that they are one optical and one SAR. The docstring explains the case worth
+explaining:
+
+> Two optical images is not a malformed request in the way that three is — it is a plausible mistake,
+> from an operator who uploaded a bi-temporal pair to a single-modality workflow, or who labelled a
+> four-band Cartosat scene as SAR.
+>
+> If such a request were accepted, the adapter would place the second optical image into the 2-channel SAR
+> slot, zero-fill, and produce a fused tensor of the correct shape. CROMA would run. The answer would be
+> about one modality while claiming to fuse two.
+
+So the modality check is done on the **assets, before any pixels are read**. `_assess_pair` raises
+`InvalidRequestError` with a machine-readable `reason` of `"two_optical"`, `"two_sar"` or
+`"indeterminate"`, and each carries a user-facing message.
+
+### 9.3 The equal-dimensions requirement, and the 726²-vs-736² error
+
+The change detector requires T1 and T2 to have **identical shapes**. The guard is in the model itself,
+`specialists/change/stanet.py:415`:
+
+```python
+if t1.shape != t2.shape:
+    raise SpecialistError(
+        f"T1 and T2 must have the same shape; got {tuple(t1.shape)} "
+        f"and {tuple(t2.shape)}",
+        specialist="change",
+    )
+```
+
+This is a **hard** requirement, and it is where the bundled demo pair fails. `docs/FINAL_DELIVERY_REPORT.md`
+§6 records it as `DEGRADED`:
+
+| Finding | Status | Detail |
+|---|---|---|
+| Change on the bundled EO pair | DEGRADED | `delta-growth-t0-1975.jpg` (726²) and `t1-2025.jpg` (736²) differ in shape; the change specialist errors (`T1 and T2 must have the same shape`). A same-shape pair, or a resize step, is needed for a clean change demo. |
+
+There is **no resize step on the change path**. `load_image_array` explicitly does not resample
+(§7.5) — its docstring states *"a silent resize here would put every box in the wrong place"* — and the
+change specialist's `_predict` only pads for the encoder's stride-8 requirement, cropping back to the
+original size:
+
+```python
+h, w = t1.shape[-2:]
+if h % 8 or w % 8:
+    ph, pw = (-h) % 8, (-w) % 8
+    t1 = torch.nn.functional.pad(t1, (0, pw, 0, ph), mode="reflect")
+    t2 = torch.nn.functional.pad(t2, (0, pw, 0, ph), mode="reflect")
+```
+
+That padding does **not** reconcile two different input sizes: T1 and T2 are each padded by their own
+`(-dim) % 8`, so a 726² and a 736² input become 728² and 736² respectively — still different — and the
+model raises. The reflect-pad is a *stride* accommodation, not a *pair* accommodation, and the two must
+not be conflated.
+
+**Consequence for operators.** The change workflow requires a same-shape pair, and the failure is
+`IMPLEMENTED` (it raises a typed error with a readable message) rather than silent. A resize or
+co-registration step that reconciles differing dimensions is **not implemented** (§13). The
+`FINAL_DELIVERY_REPORT` records the demo as `DEGRADED` and prescribes *"a same-shape pair, or a resize
+step"* — either would fix the demo; neither is currently in the code path.
+
+### 9.4 Registration measurement
+
+`measure_registration` (`specialists/change/postprocess.py:134`) uses `cv2.phaseCorrelate` on grayscale
+collapses of the two images, returning a `RegistrationQuality` with `shift_x`, `shift_y`, `response`,
+`max_shift_px`, `is_usable` and `reason`. Defaults: `max_shift_px=8`, `min_response=0.15`.
+
+The module docstring is candid about the method's limit:
+
+> Deliberately a TRANSLATION model. Real mis-registration includes rotation and warp, which phase
+> correlation does not recover; a small residual after a translation correction is therefore not proof of
+> good alignment. What the measurement can do honestly is flag the *bad* cases, and that is how it is
+> used: as a gate, not a certificate.
+
+`RegistrationQuality.confidence_factor()` applies two independent penalties and takes the worse:
+a shift penalty (`1.0` at zero shift, `0.0` at `max_shift_px`) and a response factor (`0.0` at zero
+response, `1.0` at response ≥ 0.15). A pair that is offset *and* uncorrelated takes the worse of the two —
+*"the conservative choice."*
+
+A failure to *measure* is treated as a measurement of failure — both mean the pair cannot be trusted
+spatially — but the distinction is recorded in the warning: *"A failure to MEASURE is not the same as a
+measurement of failure."*
+
+Two registration-gate hypotheses were tested and both are recorded as **REJECTED** or
+**INSUFFICIENT**: `docs/CHANGE_REGISTRATION_GATE_COHERENCE_TEST.md` records a rejected hypothesis (AUC S2
+vs S3 ≤ 0.59), and `docs/CHANGE_REGISTRATION_GATE_TEXTURE_TEST.md` records a low-texture signal that was
+**CONFIRMED but INSUFFICIENT**, with option 3 **ELIMINATED**. So the gate as implemented (phase
+correlation) is the surviving method, and no additional coherence- or texture-based gate was adopted.
+
+---
+
+## 10. Large-image tiling policy
+
+### 10.1 What is declared
+
+`configs/base.yaml` declares the full tiling policy:
+
+```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 | Declared meaning |
+|---|---|---|
+| `max_pixels` | 25,000,000 | Pixel budget; exceeding it is recoverable (the caller may downscale) |
+| `tile_size` | 512 | Tile edge in pixels |
+| `tile_overlap` | 128 | Overlap between adjacent tiles |
+| `max_tiles` | 64 | Hard ceiling on tiles **examined** |
+| `top_k_tiles` | 4 | How many tiles are actually sent through a specialist |
+
+The comment states the intended policy: *"whole-image thumbnail first, then top-K tiles."* The change
+workflow declares a different tiling resolution, `change.tile_size: 256` with `change.tile_overlap: 0`
+— 256 is *"the change model's OWN training resolution"* (LEVIR-CD patches are 256×256).
+
+### 10.2 What is enforced
+
+`core/config.py` validates the tiling policy at load time, but only one relationship:
+
+```python
+# --- tiling policy -------------------------------------------------
+if self.get("image.top_k_tiles", 0) > self.get("image.max_tiles", 0):
+    errors.append("image.top_k_tiles cannot exceed image.max_tiles")
+```
+
+So the config loader guarantees that the number of tiles sent through a specialist does not exceed the
+number examined. It does not implement tiling.
+
+The pixel budget **is** enforced, but at the raster-inspection layer rather than as a tiling step:
+`inspect_raster` raises `OversizedImageError` when `width * height > max_pixels`, and the error is
+`recoverable` — the docstring says *"the caller may downscale."* The controller passes the configured
+budget into `_inspect_asset` during VALIDATE.
+
+### 10.3 What is not implemented — the honest status
+
+**The tiling policy is `DECLARED (not read)`.** `image.tile_size`, `image.tile_overlap`, `image.max_tiles`
+and `image.top_k_tiles` appear only in `configs/base.yaml` and in the `core/config.py` validation above.
+No code on the serving path slices a raster into tiles, selects the top-K, or stitches results.
+`architecture/03-request-lifecycle.md` reaches the same conclusion: the tiling policy is referenced only
+in config validation and not implemented on the serving path.
+
+The practical consequence: a raster within the `max_pixels` budget is handed to a specialist **whole**.
+The VLM path pins `processor_longest_edge: 512` so the processor does not upscale and split a tile, but
+that pin assumes a 512-px input — it is a *control against* the processor's default 2048, not a tiling
+step. `core/config.py` enforces the relationship (`processor_longest_edge` must not exceed
+`image.tile_size`), with the measured rationale recorded: the default 2048 upscales a 512 tile 4× and then
+splits it into ~17 sub-images, *"the real figure is ~17x"* against the plan's estimated 4×.
+
+`UNKNOWN — not established from the available evidence` how a raster between the tile size and the pixel
+budget is handled by the VLM path in practice; the config implies the tile policy would govern it, but
+the policy is not implemented, so the behaviour is whatever the specialist does with the whole image.
+
+---
+
+## 11. Grounding resolution — the frozen 224 decision
+
+Grounding runs at **224 px**, and this is one of the project's cleanest pre-registered results.
+`configs/base.yaml`:
+
+```yaml
+grounding:
+  ...
+  # RESOLVED 2026-09-16. 448 did NOT earn its cost over all 16,159 VRSBench
+  # eval records: mean best IoU -0.0147, Recall@0.5 -0.0022, and every recall
+  # threshold lower (-0.0699 @0.10, -0.0243 @0.25), at 1.59x the latency.
+  # Paired over identical samples: mean diff -0.0147, 95% CI [-0.0160,-0.0134],
+  # t = -22.63. 448 was better on 8.5% of records, worse on 20.9%.
+  # Pre-registered rule and the paired test AGREE on 224.
+  # Evidence: docs/PHASE7_RESOLUTION_DECISION.md
+  image_size: 224
+  resolution_frozen: true
+  nms_iou: 0.50
+  max_candidates: 20
+  confidence_threshold: 0.40
+  benchmark_box_scale: 100.0
+  coordinate_system: normalized_0_1
+  encoder_projected_dim: 512
+```
+
+### 11.1 The pre-registered rule
+
+`docs/PHASE7_RESOLUTION_DECISION.md` records the rule, **fixed before the result was seen**:
+
+```
+448 WINS  if Recall@0.5 improves by >= 0.05 absolute
+          OR mean best IoU improves by >= 0.05 absolute
+224 WINS  otherwise
+INCONCLUSIVE if fewer than 30 samples were scored
+```
+
+The artifact records `rule_changed_since_preregistration: false`.
+
+### 11.2 The result
+
+```
+224 WINS
+  recall@0.5 gain 448/224 : -0.0022
+  bestIoU    gain 448/224 : -0.0147
+  latency          ratio  : 1.59x
+```
+
+Neither component came close to the +0.05 margin; both were **negative**. The measured detail:
+
+| Metric | 224 | 448 | Delta |
+|---|---|---|---|
+| Token grid | 7 × 7 = 49 | 14 × 14 = 196 | 4.0× tokens |
+| Mean best IoU | **0.0972** | 0.0825 | **−0.0147** |
+| Recall@0.10 | **0.3298** | 0.2599 | **−0.0699** |
+| Recall@0.25 | **0.1187** | 0.0944 | **−0.0243** |
+| Recall@0.50 | **0.0234** | 0.0212 | **−0.0022** |
+| Latency mean | **20.0 ms** | 31.8 ms | 1.59× |
+| Latency p90 | **20.9 ms** | 32.9 ms | 1.57× |
+| Peak VRAM | **592.1 MB** | 599.8 MB | +7.7 MB |
+
+All 16,159 / 16,159 VRSBench eval records were scored at both resolutions on a Tesla T4.
+
+### 11.3 The paired test
+
+Because both resolutions scored the **same 16,159 samples**, the paired test is the stronger statistic:
+
+```
+paired samples     : 16159
+mean 224           : 0.0972
+mean 448           : 0.0825
+mean paired diff   : -0.0147   (95% CI -0.0160 .. -0.0134)
+t statistic        : -22.63
+CI excludes zero   : True
+
+448 better on      :  1371/16159 ( 8.5%)
+448 worse on       :  3372/16159 (20.9%)
+identical          : 11416/16159 (70.6%)
+```
+
+The paired test and the pre-registered rule **agree**, so there is *"no rule-versus-evidence disagreement
+to escalate."* The win/loss split is informative on its own: 448 wins on only 8.5% and loses on 20.9% —
+*"the finer grid is not merely neutral, it is actively harmful on a fifth of the corpus."*
+
+The recall ladder narrows as the threshold rises (−0.0699 at 0.10, −0.0243 at 0.25, −0.0022 at 0.50),
+which the document reads as *"the signature of a method that cannot reach high IoU either way."*
+
+### 11.4 Why 448 did not help
+
+The document's honest reading: the zero-shot method selects a patch by text similarity and returns that
+patch's box. At 224 a box is 1/7 of the image; at 448 it is 1/14. A finer grid is only better if the
+target is small **and** the similarity peak lands on the correct fine cell. Two things work against that:
+the peak is not sharper at 448 (the similarity field on frozen features is smooth, so the argmax moves
+around), and Recall@0.10 — the loosest threshold — degrades *most*, which means *"the fine grid is adding
+positional noise rather than positional precision."*
+
+The document is careful to attribute this to the zero-shot baseline, not to RemoteCLIP: *"A **learned**
+head trained to regress boxes from these features may respond differently to resolution."*
+
+### 11.5 What the decision does not establish
+
+- **Whether the zero-shot baseline is good.** It is not: mean best IoU 0.0972 and Recall@0.5 0.0234 are
+  *"weak"*. It is an ablation floor for the Phase 8 head.
+- **Whether a trained head has the same resolution sensitivity.** Re-opening the question is legitimate
+  **if** the head's validation curve suggests it, and would be *"a new pre-registered experiment, not a
+  silent retune."*
+- **Anything about hidden ISRO/SAC imagery.** *"VRSBench is overhead optical. The hidden set is
+  Cartosat-2S + RISAT, a different distribution entirely."*
+
+### 11.6 Downstream consequences of the frozen resolution
+
+The frozen resolution propagates into concrete serving parameters:
+
+- **The decode grid.** `build_grounding_specialist` sets `grid = resolution // 32`, so at 224 the grid is
+  **7×7 = 49 cells**. The head emits `(1, 49, 5)` — `[tx, ty, tw, th, objectness]` per cell.
+- **The projected dimension.** `grounding.encoder_projected_dim: 512` is the measured `visual.proj`
+  output of RemoteCLIP ViT-B/32 (the transformer width is 768; `visual.proj` maps to 512). The
+  per-cell feature is `concat([patch, text, patch*text, global_pool]) = 4 × 512 = 2048`, which
+  `grounding_head.feature_dim: 2048` must equal — enforced at load time by `core/config.py`, which
+  rejects any other value, because *"a mismatch here is a SILENT shape error"* that torch raises only at
+  the similarity step, *"after the patch features are already cached."*
+- **NMS.** `grounding.nms_iou: 0.50` is passed to `nms(boxes, scores, iou_threshold)`
+  (`specialists/grounding/head.py:294`).
+- **The serving candidate budget.** `GroundingSpecialist` defaults `max_candidates=6`, **not** the
+  config's `20`. The class docstring records why: *"The Phase 8 decision measured that a 20-box budget
+  inflates mean best IoU relative to the 5.99-box baseline; 6 is the decode-matched setting."* The builder
+  reads `grounding.serving_max_candidates` with a default of 6.
+- **The degenerate-box guard.** `DEGENERATE_AREA_FRACTION = 0.9` drops any zero-shot candidate covering
+  more than 90% of the frame, *"the shape a failed localisation takes once it has been smoothed into a
+  rectangle."* This guard applies to the **zero-shot fallback path only** — *"the trained-head decode is
+  a regressed box with its own learned prior; filtering it would change the frozen Phase 8 benchmark
+  numbers."*
+- **The decode function.** `decode_cell_relative` (`specialists/grounding/head.py:204`) turns
+  `(B, N, 4)` cell-relative parameters into `(B, N, 4)` normalised xyxy, clamped to `[0, 1]` and
+  order-corrected by `enforce_order` (which swaps inverted corners rather than letting IoU go silently to
+  zero). The decode is *"differentiable: the output feeds the box and GIoU losses directly, so the loss is
+  computed on exactly the coordinates the metric measures."*
+
+---
+
+## 12. Worked examples
+
+### 12.1 A 4-band Cartosat-2S optical scene
+
+1. **Inspect.** `inspect_raster` reads `band_count=4`, no CRS or with CRS. `infer_modality(4)` returns
+   `OPTICAL` (4 is in `_OPTICAL_BAND_COUNTS`).
+2. **Descriptor.** With no `SensorDescriptor`, `_descriptor_for` maps the 4 bands positionally onto
+   `OPTICAL_CANONICAL[:4]` = `B01, B02, B03, B04` and appends a warning naming the assumption. With a
+   descriptor built by `build_optical_adapter("cartosat_2s")`, the bands are `["B1","B2","B3","B4"]`
+   canonicalised to `B01..B04`, and `availability = [True, True, True, True, False × 8]`.
+3. **Canonicalise.** `adapt_optical` returns a `(12, H, W)` tensor with channels 0–3 carrying the real
+   bands and channels 4–11 exactly zero, plus a 12-element mask with four `True`.
+4. **Resize.** `resize_to_canonical` bilinearly resizes to `120×120`. The zero channels stay zero.
+5. **Encode.** `encoder.encode(optical_tensor[None], sar_tensor[None])` — **no mask** (C-1).
+6. **Assemble.** `assemble_fusion_input` concatenates the three 768-d GAPs with the 12-element optical
+   mask and the 2-element SAR mask → `(1, 2318)`.
+7. **Head.** With a trained head, the classifier emits 19 logits → softmax → a label and a margin. With
+   no head, `probabilities` stays `None`, `degraded=True`, and no label is invented.
+8. **Evidence.** An `AVAILABILITY_MASK` item per modality records the sensor, the 4 real bands, the band
+   map, the mask (`[true × 4, false × 8]`), and `missing_channels: [4,5,6,7,8,9,10,11]`. A
+   `JOINT_FEATURE_REGION` item records `fusion_input_dim: 2318`, `mask_consumed_by: "fusion_head"`,
+   `croma_received_mask: false`.
+9. **Confidence.** `optical_confidence = 4/12 = 0.3333`; the SAR side contributes its own fraction; the
+   fusion margin (if a head exists) is the largest weight. If no head, the raw confidence is **0.0** with
+   `no_prediction: 1.0` recorded.
+
+### 12.2 A RISAT SAR scene with no band labels
+
+1. **Descriptor.** `positional_fallback_descriptor(stem, 2)` selects `("VV", "VH")` from
+   `_FALLBACK_SAR_ORDER` and records the fallback in the `sensor` field. The specialist appends: *"The
+   polarisation IDENTITY of each channel is NOT known from a band count alone."*
+2. **Canonicalise.** `adapt_sar` returns `(2, H, W)` with both slots filled, mask `[True, True]`.
+3. **Trace.** `available_bands = ["VV", "VH"]` is the **assumption**, not a measurement. A caller with
+   real polarisation labels passes `available_bands=["HH","HV"]`, in which case the descriptor's own order
+   becomes the slot order and the mask reflects it — no relabelling, no discarded data.
+
+### 12.3 A change pair with differing dimensions
+
+1. **Validate.** Exactly two assets, distinct paths/SHA-256, CRS compared.
+2. **Register.** `measure_registration` collapses both to grayscale float32 and runs `phaseCorrelate`.
+3. **Shape check.** If the two images differ in size, `STANetStyleChangeDetector.forward` raises
+   `SpecialistError("T1 and T2 must have the same shape; got ...")` — the 726²/736² case (§9.3). No resize
+   step exists to reconcile them.
+4. **If shapes match but registration is poor:** the maps are still computed, the regions are withheld,
+   the transform is dropped from the `geospatial` block, and the confidence is floored at 0.0 with
+   `suppressed_by_registration: 1.0` recorded.
+
+---
+
+## 13. What is NOT implemented — exhaustive
+
+Each item below was checked against the code. Where a capability is absent, it is named rather than
+implied; where the absence cannot be confirmed from the files read, it is marked `UNKNOWN`.
+
+| Capability | Status | Evidence |
+|---|---|---|
+| **Reprojection pipeline** | **NOT IMPLEMENTED** | `geospatial/crs.py::compare_crs` *reports* `requires_reprojection`; no code performs a reprojection. `preprocessing/imagery.py` explicitly does not reproject. |
+| **Cloud masking** | **NOT IMPLEMENTED** | No cloud, cirrus, QA or `SCL` handling anywhere in `preprocessing/` or the specialists. `UNKNOWN — not established from the available evidence` whether any dataset adapter applies a cloud mask. |
+| **Atmospheric correction** | **NOT IMPLEMENTED** | No atmospheric, surface-reflectance or `L2A`-processing code. Rasters are consumed as delivered. |
+| **Mosaicking** | **NOT IMPLEMENTED** | No mosaicking, seamline or composite code exists. |
+| **Tiling / top-K tile selection** | **DECLARED (not read)** | `image.tile_size`, `image.tile_overlap`, `image.max_tiles`, `image.top_k_tiles` are read only by `core/config.py`'s `top_k_tiles <= max_tiles` check. No serving-path tiling. |
+| **Optical percentile 2/98 conditioning** | **DECLARED (not read)** | `optical.normalization`, `optical.lower_percentile`, `optical.upper_percentile` are read by no code (`radiometry.py` docstring; PHASE14 §1). |
+| **SAR dB clip −30/+5 conditioning** | **DECLARED (not read)** | `sar.representation`, `sar.clip_min_db`, `sar.clip_max_db` are read by no code. |
+| **Resampling / cropping on the display path** | **DELIBERATELY ABSENT** | `preprocessing/imagery.py` docstring: *"It does not resample, crop, or reproject."* |
+| **Resize to reconcile differing pair dimensions** | **NOT IMPLEMENTED** | The change path requires equal shapes and has no reconciling resize (§9.3). |
+| **Nodata filling** | **NOT IMPLEMENTED** | `quality.py` refuses any non-finite input outright; its comment records: *"Filling nodata from the raster profile belongs in the tiling work."* |
+| **Area computation for geographic CRS** | **NOT IMPLEMENTED** | `pixel_area_m2` returns `None` for a non-metric CRS rather than approximating. |
+| **GeoJSON / WKT / KML output** | **NOT IMPLEMENTED** | Coordinates are emitted as lists; no geometry serialisation exists. |
+| **Multi-band raster → RGB band selection policy** | **PARTIAL** | `load_image_array` takes the first three bands as RGB (or repeats a single band); there is no configurable band combination. |
+| **Sensor adapter for sensors beyond the known list** | **REFUSED BY DESIGN** | An unknown optical sensor with no explicit band list raises `UnsupportedBandsError`; `_known_sar` returns `[]` for an unknown SAR sensor. |
+
+**A note on the "not implemented" list.** None of these omissions is hidden. The two most consequential —
+the tiling policy and the radiometric conditioning — are declared in the frozen config and read by no
+code, and both the config comments and the DEV-2 ruling name that state explicitly rather than letting the
+key read as a satisfied requirement.
+
+---
+
+## 14. What is NOT RUN / OPEN / BLOCKED for this topic
+
+### NOT RUN
+
+- **The optical-SAR forward pass at serving time with a trained head.** `CROMA_base.pt` is not present
+  locally and `use_croma.py` must be vendored; the specialist runs sensor-only and produces no label.
+- **A system-level geospatial accuracy benchmark.** No end-to-end benchmark exists; no system-level
+  accuracy is claimed anywhere.
+- **Reprojection of a genuinely mismatched-CRS pair.** The code path that would consume a reprojection is
+  absent, so the case has never been exercised.
+- **Change on a bundled pair with equal dimensions.** The only bundled demo pair is 726² vs 736² and
+  errors; a same-shape pair has not been run as a demo.
+
+### OPEN
+
+- **The `optical.*` / `sar.*` conditioning stage.** `OPEN` — either it gets an implementation or the keys
+  are retired (`docs/PHASE14_CROMA_NORMALISATION_CHANGE.md` §6 item 3).
+- **The arm-constructibility question.** The §4-registered arm B (*"percentile/dB only, no encoder-input
+  stretch"*) is **not constructible** while stage 1 is unimplemented; the arm now named B corresponds to
+  the registered arm C. The ruling records this as *"a human decision and deliberately not resolved."*
+- **The optical-SAR ruling.** Accuracy **0.931** with macro-F1 **0.434161**; ruling **OPEN**. Never quote
+  the accuracy without the macro-F1.
+- **The grounding resolution question after a trained head.** Re-opening 224 is legitimate only as a new
+  pre-registered experiment.
+- **The change-VQA metric ruling.** `OPEN` and owner-gated.
+- **Whether any call site builds a `Box` outside the two conversion functions** (§5.4) — `UNKNOWN`.
+
+### BLOCKED
+
+- **A clean change demo.** Blocked on a same-shape pair or a resize step.
+- **The CROMA normalisation experiment (option c).** Blocked on arm B being non-constructible and on the
+  Arm-B feature cache, which does not exist (`artifacts/optical_sar/fusion_features/` holds only the
+  Arm-A cache).
+- **The gated experiment's sample size.** Cannot be specified until a variance-estimation pass is run;
+  the ruling deliberately declines to invent a number.
+
+### REJECTED
+
+- **448 px grounding resolution.** `REJECTED` by the pre-registered rule and the paired test.
+- **Option (b) — match `base.yaml` alone, accept the shift.** `REJECTED` as a standalone path
+  (`docs/PHASE14_CROMA_NORMALISATION_CHANGE.md` §2.1).
+- **Reusing `preprocessing/imagery.py`'s stretch for CROMA.** `REJECTED` as `forbidden` (§3.3 of the
+  ruling).
+- **Coherence- and texture-based registration gates.** One `REJECTED`, one `CONFIRMED but INSUFFICIENT`.
+
+---
+
+## 15. Where the evidence lives
+
+**Source modules (the code this chapter describes):**
+
+| Path | What it defines |
+|---|---|
+| `preprocessing/raster.py` | The validation chain, `inspect_raster`, `read_bands`, `write_raster`, `infer_modality`, `file_sha256`, `pixel_area_m2` |
+| `preprocessing/imagery.py` | `load_image_array`, `load_pil_image`, the per-scene 2/98 display stretch |
+| `preprocessing/quality.py` | The deterministic quality gate, `MIN_AUTOCORRELATION=0.10`, `NOISE_ENTROPY_BITS=7.8` |
+| `geospatial/crs.py` | `parse_crs`, `describe_crs`, `compare_crs`, `is_metric`, `CRSCompatibility` |
+| `geospatial/transform.py` | `PixelWindow`, `GeoBounds`, `to_normalized`/`to_pixel`/`to_geo`, `intersect`, `iou`, `benchmark_boxes_to_normalized`, `affine_from_metadata` |
+| `core/schemas.py` | `CoordinateSystem`, `GeoMetadata`, `SensorDescriptor`, `AssetMetadata`, `Box`, `Region`, `ChangeRegion`, `Evidence._spatial_needs_crs` |
+| `core/config.py` | Config loading, validation, `Config.hash`, `device_preference` |
+| `specialists/optical_sar/sensor_adapter.py` | `OPTICAL_CANONICAL`, `SAR_CANONICAL`, `build_optical_adapter`, `describe_sar`, `_apply_canonical`, `positional_fallback_descriptor` |
+| `specialists/optical_sar/radiometry.py` | `TRANSFORM_NAME`, `normalise_for_croma`, `resolve_use_8_bit`, the zero-channel rule |
+| `specialists/optical_sar/fusion_head.py` | `expected_fusion_dim`, `assemble_fusion_input`, `channel_dropout`, `build_fusion_head` |
+| `specialists/optical_sar/inference.py` | `run_pipeline`, `resize_to_canonical`, `cross_modal_agreement`, `build_head_from_config` |
+| `specialists/optical_sar/specialist.py` | `_assess_pair`, `_descriptor_for`, `_confidence_components`, `_geospatial` |
+| `specialists/change/postprocess.py` | `RegistrationQuality`, `measure_registration`, `to_grayscale_float`, `regions_to_schema` |
+| `specialists/change/specialist.py` | `_assess_pair`, `_predict`, `_geospatial`, the suppression path |
+| `specialists/change/stanet.py:415` | The equal-shape guard |
+| `specialists/grounding/specialist.py` | `_to_geo_boxes`, the `NORMALIZED_0_1` box construction, `DEGENERATE_AREA_FRACTION` |
+| `specialists/grounding/head.py` | `decode_cell_relative`, `enforce_order`, `nms` |
+| `specialists/grounding/inference.py` | `decode_candidates_from_features`, `ground_phrase` |
+| `evaluation/metrics/grounding.py` | `benchmark_to_normalized(box, scale=100.0)` |
+
+**Configuration:**
+
+- `configs/base.yaml` — `image.*` (tiling), `optical.*`, `sar.*`, `croma.*`, `fusion.*`, `grounding.*`,
+  `grounding_head.*`, `change.*`.
+
+**Documents:**
+
+- `docs/PHASE14_CROMA_NORMALISATION_CHANGE.md` — the DEV-2 ruling, the two ordered stages, the Gate F arm
+  amendment.
+- `docs/CROMA_NORMALISATION_UPSTREAM_EVIDENCE.md` — what is and is not established about CROMA's
+  pretraining distribution.
+- `docs/PHASE7_RESOLUTION_DECISION.md` — the 224/448 decision in full.
+- `docs/CHANGE_REGISTRATION_GATE_COHERENCE_TEST.md`, `docs/CHANGE_REGISTRATION_GATE_TEXTURE_TEST.md` — the
+  rejected and insufficient registration gates.
+- `docs/API_CONTRACT.md` §2.5 (asset allowlist), §3.2 (coordinate systems).
+- `docs/FINAL_DELIVERY_REPORT.md` §6 — the 726²/736² change demo recorded as DEGRADED.
+- `docs/PHASE10_CDVQA_DATA_STATUS.md` — the CDVQA/SECOND pair layout and temporal semantics.
+- `docs/PHASE11_CROMA_STATUS.md` — the reproduced CROMA forward pass.
+
+**Sibling release chapters:**
+
+- [`DATA_PIPELINE.md`](DATA_PIPELINE.md) — the end-to-end data path, caches and artefacts.
+- [`architecture/03-request-lifecycle.md`](architecture/03-request-lifecycle.md) — the nine controller
+  states, including VALIDATE and PREPROCESS.
+- [`architecture/05-specialists.md`](architecture/05-specialists.md) — the six specialists.
+- [`architecture/07-configuration-freeze.md`](architecture/07-configuration-freeze.md) — the frozen hash
+  and every config key.
+- [`DATASETS.md`](DATASETS.md) — the corpora and their measured shapes.