docs/GEOSPATIAL.md

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 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 (the end-to-end data path, caches and artefacts), architecture/03-request-lifecycle.md (where the PREPROCESS and VALIDATE states sit), architecture/05-specialists.md (the six specialists in full), architecture/07-configuration-freeze.md (the frozen config identity and every key), DATASETS.md (the corpora and their measured shapes).

---

Table of contents

0. How to read this document
1. The raster input contract
2. CRS handling
3. Affine transforms and coordinate frames
4. The coordinate-system contract
5. Benchmark box scale — 0–100 versus 0–1
6. Band-count modality inference
7. Radiometric normalisation and representation
8. The CROMA sensor adapter contract
9. Pair-compatibility rules
10. Large-image tiling policy
11. Grounding resolution — the frozen 224 decision
12. Worked examples
13. What is NOT implemented — exhaustive
14. What is NOT RUN / OPEN / BLOCKED for this topic
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:

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:

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

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:

@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

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):

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:

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 PixelWindows, 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

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)":

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:

@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:

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:

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:

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:

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:

_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

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:

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:

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:

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

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

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 — the end-to-end data path, caches and artefacts.
• architecture/03-request-lifecycle.md — the nine controller states, including VALIDATE and PREPROCESS.
• architecture/05-specialists.md — the six specialists.
• architecture/07-configuration-freeze.md — the frozen hash and every config key.
• DATASETS.md — the corpora and their measured shapes.