docs/architecture/05-specialists.md

05 — Specialists

Chapter status: written against the code at C:/Users/anish/satquery-ai/**, read directly. Companion chapters: 03-request-lifecycle.md (how a specialist is selected and called), 04-router.md (how the task is decided), 06-evidence-and-confidence.md (what the emitted evidence means), 07-configuration-freeze.md (the config hash and why nothing may move it).

Read this first. A specialist is where SatQuery AI stops being a pipeline and starts being a measurement. Everything upstream of it — the router, the planner, the controller, the API — exists to decide which specialist to call and to carry its output back out with its provenance intact. Everything downstream of it is presentation. This chapter documents all six specialists exhaustively: their class, entry point, frozen backbone, trained module, exact preprocessing, exact postprocessing, output shape, emitted evidence, measured metric with its protocol, and limitations.

A note on how to read the status labels. Every substantive claim below carries one of the status words defined in the release style guide (IMPLEMENTED · VERIFIED · MEASURED · ATTEMPTED · NOT RUN · BLOCKED · DEFERRED · REJECTED · OPEN · RESOLVED · CLOSED). Where a fact is missing, the text says UNKNOWN — not established from the available evidence rather than guessing.

---

Contents

Part	Sections	Subject
0	§1–§4	What a specialist is: the ABC, the registry, the universal rules
A	§5–§10	vqa and caption — the SmolVLM specialist
B	§11–§17	grounding — RemoteCLIP plus the trained head
C	§18–§26	change — STANet-style Siamese detector
D	§27–§34	change_vqa — the closed-vocabulary CDVQA head
E	§35–§43	optical_sar — CROMA plus the fusion head
F	§44–§48	Cross-cutting: evidence, confidence, degradation, open items

---

Part 0 — What a specialist is

§1 The Specialist contract

Every specialist is a concrete subclass of Specialist in specialists/base.py (137 lines). The contract is small and it is frozen.

§1.1 SpecialistRequest

SpecialistRequest is a frozen dataclass — the controller builds one and no specialist may mutate it:

@dataclass(frozen=True)
class SpecialistRequest:
    assets: list[Asset]           # the images this request is about
    query: str                    # the operator's question, verbatim
    params: dict[str, Any]        # plan-step parameters (see 04-router.md §43)
    run_id: str                   # the run this request belongs to

It exposes one derived property:

Property	Meaning
asset_count	len(self.assets). This is the number every specialist's validate_request branches on.

params is where a plan step's parameters arrive. core/planner.py's _params_for populates it, and it is also where a future planner could hand a change map to the change-VQA specialist (see §32.4 — the hook exists and is documented as unused).

§1.2 The abstract surface

Specialist declares three class attributes and four abstract methods:

Member	Kind	Contract
name	class attr	Stable identifier. Matches the capabilities string the planner looks up.
version	class attr	Semantic version string. Every specialist in this release is "0.1.0".
capabilities	class attr	Tuple of capability strings this specialist can serve.
validate_request(request)	abstract	Raise a typed error for anything that cannot be served. Must not silently repair.
execute(request)	abstract	Produce a SpecialistResult.
produce_evidence(result)	abstract	Return the evidence for an already-computed result. Never invents a new artifact.
estimate_confidence(result)	abstract	Return the ConfidenceBreakdown for an already-computed result.

Four concrete helpers are provided by the base class:

Helper	Behaviour
supports(capability)	capability in self.capabilities. Used by the registry's capability lookup.
require_assets(request, n)	Raises InvalidRequestError when asset_count != n.
require_capability(capability)	Raises when this specialist does not declare the capability.
model_refs()	Returns list[dict[str, str]] naming the models loaded. Defaults to empty; every specialist that loads a model overrides it.
describe()	Returns a dict of identity facts. Specialists extend it with their own degradation state.
__repr__	Includes name, version and capabilities.

The produce_evidence / estimate_confidence shape is deliberate. They take a result, not a request. That is what makes "evidence is a projection of what was computed" structurally true rather than a convention: a specialist that never ran has no result to project evidence from, so it cannot manufacture evidence for a request it did not serve.

§1.3 The five registered specialists

name	capabilities	Module	Backbone	Trained module
vlm	("vqa", "caption")	specialists/vqa/inference.py	SmolVLM-500M-Instruct @ a7da5b986cb5	LoRA adapter (model.text_model only)
grounding	("grounding",)	specialists/grounding/specialist.py	RemoteCLIP ViT-B/32 @ bf1d8a3ccf2d	GroundingHead, 1,052,677 params
change	("change",)	specialists/change/specialist.py	ResNet-18 (torchvision)	STANetStyleChangeDetector, 4-level Siamese
change_vqa	("change_vqa",)	specialists/change/vqa_specialist.py	frozen STANet detector + MiniLM	change_vqa_head_v1, 1,453,912 params
optical_sar	("optical_sar",)	specialists/optical_sar/specialist.py	CROMA-base @ 0dd28e3d633b	FusionHead, 1,201,711 params

One specialist serves two capabilities. vlm declares ("vqa", "caption") because both are the same model with a different prompt kind (§10). The planner's CAPABILITY_ASSETS in core/planner.py turns each capability into an asset-count requirement, and TASK_CAPABILITY maps the six router task classes onto these capability strings — see 04-router.md §39–§43.

§1.4 Status of each specialist, in one table

This is the single most important table in the chapter. Do not read any metric below without its status column.

Task	Artifact exists	Artifact measured	Wired into serving by default	Status
caption	yes	yes (exact_match 0.963 on 1,000 adapted-test questions)	yes	USABLE_VERIFIED — ACCEPTANCE-REJECTED
vqa	same adapter	same	yes	USABLE_VERIFIED — ACCEPTANCE-REJECTED
grounding	yes (head.pt, 12.6 MB)	yes (two protocols, two decode variants)	yes — build_grounding_specialist loads DEFAULT_HEAD_PATH	MEASURED
change	yes (head.pt)	yes (pooled IoU 0.8122 on 2,048 tiles)	no — deliberately not wired (see §22.5)	VERIFIED
change_vqa	yes (head.pt, 5,822,809 bytes)	yes (two test sets)	yes (app/serving.py:76-78)	MEASURED, metric ruling OPEN
optical_sar	yes (production head, 14,427,457 bytes)	yes (accuracy 0.931 with macro-F1 0.434161)	head loadable; CROMA resolution is environment-dependent	MEASURED, ruling OPEN

Two rows are worth restating because they are the two most common ways to state this project's results wrongly:

• change is VERIFIED and is not deployed. The trained checkpoint exists, is benchmarked, and is deliberately not referenced from configs/base.yaml. §22.5 gives the exact reason.
• The VLM adapter is USABLE_VERIFIED but ACCEPTANCE-REJECTED. Those are different words about different things. §9.4 quotes the closure record.

---

§2 Where a specialist sits in the pipeline

flowchart TD
    Q["operator query + assets"] --> R["IntentRouter.route()<br/>see 04-router.md"]
    R --> I["Intent<br/>task, modality, confidence, above_threshold"]
    I --> P["PolicyPlanner.plan()"]
    P --> EP["ExecutionPlan<br/>ordered PlanStep list"]
    EP --> C["Controller<br/>dispatch loop"]
    C --> REG["SpecialistRegistry"]
    REG --> S1["vlm"]
    REG --> S2["grounding"]
    REG --> S3["change"]
    REG --> S4["change_vqa"]
    REG --> S5["optical_sar"]
    S1 --> SR["SpecialistResult<br/>answer, labels, regions, evidence,<br/>confidence, geospatial, degraded, warnings"]
    S2 --> SR
    S3 --> SR
    S4 --> SR
    S5 --> SR
    SR --> EE["EvidenceEngine<br/>see 06-evidence-and-confidence.md"]
    EE --> TR["ExecutionTrace<br/>published"]

The registry caches the specialist instance. That fact has a measurable consequence for change_vqa: the planner plans both a change step and a change_vqa step for a change+language request, so the STANet detector runs twice for one request — but the weights are loaded once, so the second cost is a forward pass, not a 60 MB load. The specialist's own docstring states this cost rather than hiding it (specialists/change/vqa_specialist.py:16-27).

---

§3 The three vocabularies you must not confuse

This chapter uses three vocabularies, and conflating any two of them produces a wrong statement.

Vocabulary	Where it lives	Members	Used for
Router task classes	router/label_space.py:TASK_CLASSES	6: vqa, caption, grounding, change, optical_sar, unsupported	What the router predicted
Task enum	core/schemas.py:Task	7: the six above plus change_vqa	What a SpecialistResult is labelled with
Planner capabilities	core/planner.py:TASK_CAPABILITY	6, including change_vqa, excluding unsupported	What the planner asks a specialist for

The router's class space has no change_vqa member. The Task enum and the planner do. This is why a change_vqa result can exist while no router prediction ever names it — the planner derives the change_vqa step from a change prediction plus a language signal (04-router.md §43).

---

§4 The universal rules every specialist obeys

These rules are not stylistic preferences. Each one is implemented, and each one has a test or a measured behaviour behind it.

§4.1 Never invent a value

The strongest statement of this rule in the codebase is in the optical-SAR sensor adapter (specialists/optical_sar/sensor_adapter.py:9-28):

"No invented missing bands." … "a band the sensor did not produce must never acquire values."

The module names the failure mode precisely: a 4-band Cartosat-2S scene maps cleanly onto canonical channels 1–4; filling channels 5–12 with a copy of B3 as a fake "red-edge" produces a tensor of the correct shape whose statistics look plausible. "CROMA would run. Nothing would raise."

The same rule appears in four other places with different subjects:

Place	What must not be invented
specialists/change/postprocess.py	A change region where the pair is mis-registered
specialists/grounding/specialist.py	A coordinate — the VLM is never asked for one (finding C-5)
specialists/change/vqa_specialist.py	An answer from an untrained 19-way classifier
specialists/optical_sar/radiometry.py	A dynamic range for a channel the sensor did not measure

§4.2 Degrade, do not crash — and say which piece is missing

A missing artifact is a deployment fact. A corrupt artifact is a bug. Every specialist draws that line identically:

Situation	Behaviour	Rationale (verbatim from the code)
Artifact absent	Construct, mark degraded=True, name the missing piece in warnings	"a missing artifact is a deployment case, not a crash"
Artifact named and exists but unreadable	Raise ModelLoadError	"Degrading to an untrained model because a real checkpoint failed to load would turn a broken deployment into a silently-wrong one"

The three specialists that load a checkpoint each restate this: specialists/change/specialist.py:866-870, specialists/change/vqa_specialist.py:534-538, specialists/optical_sar/inference.py:373-376.

§4.3 A signal gap is not a weak signal

When there is nothing to be confident about, the confidence is 0.0, not a discounted mid-range number. Three specialists implement this floor explicitly:

Specialist	Floor condition	Source
change	suppressed, untrained, or zero regions	specialists/change/specialist.py:692-693
optical_sar	no prediction, or untrained head	specialists/optical_sar/specialist.py:526-536
change_vqa	no trained head at all	specialists/change/vqa_specialist.py:322-352

The change specialist's comment explains why the third floor exists: an empty result previously scored ≈0.5, because a well-aligned pair contributes its full 0.50 registration weight while both signal terms are 0.0. "A confidence of 0.5 on 'no change found' reads as 'we are fairly sure', which overstates it."

§4.4 Artifact references are never filesystem paths

Finding F-16 (owner ruling 2026-09-23) forbids exposing a filesystem path to a client. The implementation is not "omit the field" — it is "emit the evidence item with artifact_ref = None and say in the payload that the artifact is not retrievable":

payload={
    "rendered": rendered,
    "retrievable": False,
    "retrieval": "no artifact-serving endpoint in v1",
}

Both sites that write an artifact implement this: specialists/change/specialist.py:513-587 (the change map) and specialists/optical_sar/specialist.py:752-799 (the optical and SAR views). The optical-SAR comment calls them "the sibling site of the same ruling" and states why both had to be brought into line: "fixing one and not the other leaves the ruling half implemented, which is how the divergence would survive a green suite."

The change specialist adds a second, sharper consequence. When the pair is suppressed the map is written without georeferencing:

"Copying T1's transform onto it would produce a file that unlocks exactly the placed-on-a-map reading the suppression exists to forbid: a downstream tool would happily render it over the wrong ground."

_geospatial implements the same rule on the metadata path: when registration is unusable it returns GeoMetadata(..., is_georeferenced=False) with the transform dropped.

§4.5 No LLM-generated confidence, no LLM-generated coordinates

Freeze section 5 states both prohibitions. The implementation is that the VLM is never asked:

Specialist	The VLM's permitted job
grounding	explain boxes the head produced (prompt kind explain_grounding)
change	"A language model may narrate it; it may not produce it"
change_vqa	explain the answer the head produced
optical_sar	narrate a label the classifier already decided

specialists/optical_sar/prompts.py:6-18 states the consequence of getting this wrong: "A VLM asked to classify would produce a plausible label with no measurement behind it, and that label would sit next to a real confidence score looking equally authoritative."

---

Part A — vqa and caption: the SmolVLM specialist

The VQA and caption tasks are served by one specialist, vlm, with two prompt kinds. This part covers the model wrapper (§5), the prompts (§6), the specialist itself (§7), the input-quality gate that makes the whole thing defensible (§8), and the measured result with its acceptance status (§9).

§5 The frozen backbone: specialists/vqa/model.py

specialists/vqa/model.py is 434 lines and is written against findings F5-1 through F5-4. Its docstring names all four before any code appears.

§5.1 The checkpoint

Property	Value	Source
Checkpoint	HuggingFaceTB/SmolVLM-500M-Instruct	docs/PHASE5_VLM_CONTRACT.md
Pinned revision	a7da5b986cb5	same
transformers version the contract was verified against	5.17.0	same
Base parameter count	516,165,824	artifacts/vlm/phase6_closure.json
Frozen parameters	507,482,304	same
Trainable parameters after LoRA	8,683,520	same
Trainable as a fraction of total	1.68231208 %	same
Trainable as a fraction of base	1.71109809 %	same

§5.2 Finding F5-1 — the loader class is absent, not deprecated

The plan (finding C-2) said AutoModelForVision2Seq was "deprecated" and prescribed a fallback. The Phase 5 probe measured the truth:

Class	transformers 5.17.0
AutoModelForImageTextToText	present
AutoModelForVision2Seq	ABSENT
AutoModelForMultimodalLM	present
AutoModel	present

"ABSENT" means referencing it raises AttributeError at import time. There is nothing to fall back to. So the loader is resolved by hasattr() feature detection, not by version comparison and not by try/except around an import. LOADER_CANDIDATES holds three class names in preference order, resolve_loader_class() walks them, and VLMLoadInfo records which one won. Config key: vlm.loader_class_preference: auto.

§5.3 Finding F5-2 — the processor must be pinned, and the cost was 17×, not 4×

This is the finding with the largest deployment consequence.

INPUT: one 512×512 RGB tile

DEFAULT  (size.longest_edge = 2048, do_image_splitting = True)
    pixel_values  (1, 17, 3, 512, 512)     <- 17 images
    input_ids     (1, 1142)                <- 1142 tokens

PINNED   (size = {"longest_edge": 512})
    pixel_values  (1,  1, 3, 512, 512)     <-  1 image

The chain: resize 512 → 2048 (longest_edge), then do_image_splitting=True cuts the 2048 image into 4×4 = 16 sub-images of 512 each, plus 1 overview image. 16 + 1 = 17.

The plan estimated "~4×". The measurement is ~17×. The Phase 5 record states why the correction matters: "the difference between '4×' and '17×' is the difference between a cost you absorb and a cost that makes the deployment quota non-viable." At 1,142 prompt tokens per call, an un-pinned processor would spend a user's entire daily ZeroGPU quota (5 GPU-minutes/day) on one or two queries.

Resolution, and it is enforced twice. _build_processor passes the pin explicitly:

size={"longest_edge": self.processor_longest_edge}

and generate() carries a regression guard: if _count_images(...) reports more than one image in a batch, it raises. A silent re-widening of the pin cannot survive. The smoke test confirms the pin holds in the real load path, not just in the probe:

max_images_seen      1     <- F5-2 pin holds in the real load path

Unpinned, that field would read 17.

§5.4 Finding F5-3 — <image> tokens come from the chat template

Hand-written prompt strings fail:

ValueError: The total number of <image> tokens in the prompts should be the
same as the number of images passed. Found [0] <image> tokens and [1] images
per sample.

The chat template inserts them; a raw string does not. So build_messages never emits a raw string — it returns a message structure with {"type": "image"} entries, and the processor's apply_chat_template renders it. Config key: vlm.prompt_must_use_chat_template: true.

specialists/optical_sar/prompts.py:137-156 reuses the same discipline through render_for_vlm, and it raises when the processor lacks apply_chat_template rather than falling back:

"constructing the prompt string by hand is what finding F5-3 records as broken, and there is no safe fallback."

§5.5 Finding F5-4 — the dtype kwarg is not discoverable by signature

Neither AutoModelForImageTextToText.from_pretrained nor PreTrainedModel.from_pretrained exposes dtype or torch_dtype as named parameters. Both are absorbed through **kwargs. Signature inspection is therefore the wrong tool.

DTYPE_KWARG_CANDIDATES = ("dtype", "torch_dtype") and _load_with_dtype_fallback attempts the preferred spelling (dtype, the v5 name) and on TypeError retries once with torch_dtype (the v4 name). This is a call-time fallback, not an introspection. Verified live: the loader resolves to AutoModelForImageTextToText and the kwarg to dtype on transformers 5.17.0.

§5.6 The adapter is attached or the load fails

_attach_adapter wraps the base model in a PeftModel. If attachment fails it raises rather than silently serving the base model:

"raises rather than silently serving base"

The adapter path comes from ADAPTER_ENV_VAR = "SATQUERY_VLM_ADAPTER", and _adapter_sha256 records the digest so a swapped adapter is detectable. The promoted adapter's weights digest is 07c76a75fa04624880ed7730590f5fdd7b145a8232e3c0af411c3c545a5adf5e and its tree hash is 5c6b86317d1e65962702dc9e377009b3df41cc13de1b15bceccb70ad977775e7 (artifacts/vlm/phase6_closure.json).

§5.7 The measured wrapper surface

Symbol	Contract
SmolVLM.__init__(checkpoint, revision, processor_longest_edge, device, torch_dtype, do_image_splitting=True, adapter_path=None)	Loads base, attaches adapter, builds processor with the pin
generate(...)	Greedy decode; enforces the single-image guard
_count_images(...)	Counts images in a prepared batch — the F5-2 guard's input
unload()	Frees the model. Relevant on a quota-metered deployment.
build_vlm(config, ...)	Constructs from the central config
VLMLoadInfo	Records loader class, dtype kwarg spelling, processor pin, adapter digest

---

§6 The prompt set: specialists/vqa/prompts.py

130 lines, one job: make every prompt a versioned, hashed, chat-template-rendered object.

§6.1 PROMPT_VERSION = "v001"

The version string travels into the execution trace, so a result can be attributed to the exact wording that produced it. Bumping it on any wording change is the whole mechanism.

§6.2 PromptKind — four kinds, one model

PromptKind	Used by	What it asks for
vqa	task vqa	A short answer to the operator's question
caption	task caption	A description of the image
explain_grounding	task grounding (narration only)	Prose about boxes the head produced
explain_change	task change / change_vqa (narration only)	Prose about a change the detector produced

Two of the four are narration kinds: they receive already-computed facts and are forbidden from deriving new ones. That is the §4.5 rule made structural.

§6.3 SYSTEM_PREAMBLE

The system instruction is reproduced verbatim in docs/PHASE5_VLM_CONTRACT.md and is the same text that failed to prevent the F5-5 hallucination:

"Answer only from what is visible… If the image does not contain enough information, say so plainly."

The Phase 5 record draws the conclusion explicitly: "The instruction was already as explicit as it can be written." A 500M-parameter VLM will generate something for any tensor it is handed, and asking it to self-assess reliably is asking it to perform the exact operation it just failed. This is why §8 exists.

§6.4 _INSTRUCTIONS and build_messages

_INSTRUCTIONS maps each PromptKind to its user-side instruction text. build_messages(kind, user_text, *, image_count=1, evidence_context=None) assembles the system+user structure with image_count image placeholders and returns the structure — never a rendered string. evidence_context is where a narration prompt's already-computed facts enter.

describe_prompts() returns the prompt inventory with a _short_hash per entry, so the prompt set itself is content-addressed.

---

§7 The specialist: specialists/vqa/inference.py

422 lines. This is the module that turns a loaded SmolVLM into a Specialist.

§7.1 Identity

Attribute	Value
name	"vlm"
version	"0.1.0"
capabilities	("vqa", "caption")
max_new_tokens	128
do_sample	False (greedy — deterministic)
max_images_per_call	1

max_images_per_call = 1 is the F5-2 pin restated at the specialist layer.

§7.2 validate_request

Checks asset count against max_images_per_call and checks each path exists. A VQA or caption request is a single-image request; asking for two images is rejected rather than silently using the first (the same discipline change applies in the other direction — see §22.3).

§7.3 Image preparation

_load_image_array implements the display-path stretch:

Step	Detail
Percentile stretch	2nd–98th percentile, computed over finite values only
Output scale	scaled to 255, cast to uint8
Non-finite handling	excluded from the percentile computation

_load_image wraps this into the PIL object the processor expects.

Note the scope difference that docs/PHASE14_OPTICAL_SAR_DECISIONS.md §3 flags: this stretch is one lo, hi pair across the whole flattened tensor, returns uint8, and truncates to the first three bands. It is correctly scoped to the VLM/grounding display path and "must not be reused" as a CROMA input path — feeding CROMA through it would silently discard 9 of the required 12 channels.

§7.4 The quality gate runs before the model

execute performs the quality assessment before calling the model:

quality gate  ->  (blocking verdict) -> _refuse(...)
              ->  (usable)           -> model.generate(...)

The order is the entire point. By the time the model sees a tensor, the tensor has already been classified as imagery. §8 documents the gate.

§7.5 Answer normalisation and refusal detection

_normalize_answer trims and normalises the generated text. _looks_like_refusal tests the output against _REFUSAL_MARKERS, a 6-entry tuple of phrases that indicate the model declined. A refusal is detected rather than treated as an answer.

§7.6 _confidence_for — the gate is a multiplier, not a term

This is the single most easily-misread function in the specialist, and the code says so:

base = 0.5 * schema_valid + 0.5 * not_refused
raw  = base * input_usable          # the gate is a MULTIPLIER, not a term

Component	Meaning
schema_valid	The output parsed into the expected shape
not_refused	The output was not a refusal
input_usable	The quality gate said the input was usable

Why a multiplier matters: a weighted sum would let a perfectly-formed answer about a noise tensor retain most of its score. A multiplier means an unusable input zeroes the confidence outright, which is the honest reading — a fluent sentence about random bytes is worth nothing.

The measured confidence components on a real structured run:

{schema_valid: 1.0, declined: 0.0, input_usable: 1.0,
 input_structured: 1.0, autocorrelation: 0.9929}

§7.7 The emitted result

Field	Content
answer	The normalised generation, or the refusal text
labels	Derived from the answer
evidence	Generated-text evidence with the prompt version and model refs
confidence	ConfidenceBreakdown with method naming the estimator
degraded	Set when the input gate flagged a degraded (non-blocking) verdict
warnings	The gate's reason, the refusal marker matched, any degradation note

build_vqa_specialist(config, ...) is the construction entry point.

§7.8 Measured latency on CPU

From the Phase 5 smoke test, on CPU:

Path	Measured
Caption generation	11.6 s
VQA generation	5.5 s

These are CPU figures for a single 512×512 tile at the pinned processor setting. They are recorded because the deployment quota is metered in GPU-minutes and the CPU number is the honest upper bound for a local run. A GPU latency figure for this specialist is UNKNOWN — not established from the available evidence.

---

§8 The input-quality gate: preprocessing/quality.py

348 lines. This module exists because of finding F5-5, which is the most important finding in Phase 5.

§8.1 The measurement that created the module

The slow probe loaded the real model and ran one generation on a 512×512 array of uniform random bytes, with the system preamble present:

"A black and white photograph of a man and a woman, who appear to be in a
 room, with a table in front of them."

Not a refusal. Not "I cannot determine this". A fluent, specific, wholly fabricated scene description, produced at the first opportunity.

§8.2 Why a prompt cannot fix it

The Phase 5 record states the argument in three sentences: the instruction was already as explicit as it can be written; a 500M-parameter VLM will generate something for any input tensor; and asking it to self-assess reliably is asking it to perform the exact operation it just failed. The plan's §65 requirement — "the system should never pretend it knows more about its evidence than the evidence supports" — cannot be discharged inside the model. So the control is placed upstream of the model.

§8.3 The verdict vocabulary

QualityVerdict	Meaning	Blocks the model?
STRUCTURED	Looks like imagery	no
FLAT	Constant or near-constant; no texture	no (degraded)
NOISE	Uncorrelated with itself; not imagery	yes
TOO_SMALL	Below min_side = 16	no (degraded)
INVALID_VALUES	Contains non-finite values	yes

BLOCKING_VERDICTS = {QualityVerdict.NOISE, QualityVerdict.INVALID_VALUES}

§8.4 The discriminating signal is lag-1 autocorrelation, not variance

The constants:

Constant	Value	Role
MIN_AUTOCORRELATION	0.10	Below this, the image is not self-correlated
FLAT_STD_EPSILON	1e-6	Below this normalised std, the image is flat
NOISE_ENTROPY_BITS	7.8	Second, redundant signal

Measured on four input classes plus one non-finite case (docs/PHASE5_VLM_CONTRACT.md):

input	verdict	autocorrelation	entropy
structured ramp+texture	structured	0.9524	7.5810
uniform random noise	noise	-0.0082	7.9882
salt-and-pepper	noise	-0.0098	1.0000
constant / all-zero tile	flat	1.0000	0.0000

The margin analysis is the important part. Autocorrelation separates by 0.96 against a 0.10 threshold. Entropy separates by 0.22 bits against a 7.8 threshold. "Autocorrelation carries the gate; entropy is a redundant second signal." Both are kept so that a change to either cannot silently disable the gate, and a test — test_autocorrelation_is_the_load_bearing_signal_not_entropy — asserts which one is doing the work, "so a future tuning of the entropy threshold is not mistaken for a weakening of the control."

Why variance alone cannot do this: a flat desert scene and an all-zero tile both have near-zero variance. The desert has strong neighbour correlation; the zero tile does not.

§8.5 The size-dependent bug, and its fix

The initial guard was finite_fraction < 0.999. One NaN in a 64×64 array is 0.99976, which is not less than 0.999 — so the defect passed on a large image and was caught on a small one. The verdict depended on image dimensions rather than on the defect.

Now: finite_fraction < 1.0. Any non-finite value is disqualifying, at every size. Verified at 32, 64, 128 and 256. The Phase 5 record names the class of bug: "a control whose behaviour depends on an irrelevant parameter is not a control" — the same class as the seed-dependent split ordering in Phase 4.

Two related decisions:

Function	Behaviour on non-finite input
lag1_autocorrelation	Raises. A NaN would fall through every branch in assess_image_quality and produce a verdict that means nothing.
histogram_entropy	Filters. Correct for a histogram statistic, wrong for a joint one.

lag1_autocorrelation returns 1.0 for a constant image by definition — which is why a constant tile is FLAT, not NOISE.

§8.6 ImageQuality and the assessment function

ImageQuality is the record: verdict, autocorrelation, std_normalized, entropy_bits, finite_fraction, shape, plus is_usable, is_degraded, to_dict() and reason.

assess_image_quality(...) evaluates in this order:

1. Non-finite fraction — finite_fraction < 1.0 ⇒ INVALID_VALUES (disqualifying, no tolerance)
2. Size — min_side < 16 ⇒ TOO_SMALL
3. Noise — autocorrelation < MIN_AUTOCORRELATION and entropy_bits >= NOISE_ENTROPY_BITS ⇒ NOISE
4. A second, autocorrelation-only NOISE branch
5. Flat — normalised std below FLAT_STD_EPSILON ⇒ FLAT
6. Otherwise STRUCTURED

§8.7 Scope, and the known limitation

Scope. "This gate is for input validity, not for answer correctness." It prevents the system from answering questions about data that is not imagery. It does not and cannot detect a hallucination on a valid image — that remains the job of evidence grounding (Phase 13) and confidence calibration, "and it is why the VLM is never the source of coordinates or confidence."

Known limitation, recorded rather than discovered later. A float GeoTIFF whose nodata sentinel is NaN is refused by the gate, because finite_fraction < 1.0 treats the sentinel as corruption. This is deliberate — the alternative is computing correlation over NaN and reporting a meaningless verdict — but it means NaN-nodata rasters need the sentinel filled from the raster profile before the gate is consulted. The Phase 5 record assigns that work to the tiling path.

---

§9 The VLM's measured result and acceptance status

§9.1 The measurement

From artifacts/vlm/phase6_closure.json, key path why_usable_verified.adapted_test:

Metric	Value
exact_match	0.963
f1	0.96432
precision	0.963391
recall	0.965251
n	1,000
n_available	1,000
truncated	false
confusion	tp 500, tn 463, fp 19, fn 18

§9.2 The normalisation order is load-bearing

The closure record states the order explicitly and explains why:

Order	Step
1	evaluation.metrics.vqa.normalize_answer (VQA-v2 R1–R6)
2	strip surrounding quotes and whitespace
3	fold yes/no synonym families

"order is load-bearing: normalize_answer preserves apostrophes, so normalize_answer("'Yes.'") == "'yes'" and folding before stripping would miss the synonym map"

The synonym families are {no: [false, n, no]} and {yes: [true, y, yes]}. Normalisation version v001.

§9.3 The primary endpoint and the excluded metrics

primary_endpoint is "presence-question normalised exact-match accuracy".

BLEU and ROUGE are excluded, with the reason recorded verbatim: "target answers are one token; BLEU/ROUGE are meaningless at that length and BERTScore is unavailable offline."

§9.4 The acceptance rejection — USABLE ≠ ACCEPTED

The closure record's headline is:

"Phase 6 is closed. The Run 1 LoRA adapter is promoted to the production VLM adapter: USABLE and VERIFIED, but ACCEPTANCE-REJECTED."

production_adapter.use_status is USABLE_VERIFIED. production_adapter.acceptance_status is REJECTED. Both are true at once, and neither may be dropped.

Why acceptance was rejected (key path why_acceptance_rejected):

Element	Value
Rule version	v002
Decision split	test
accept_min_delta_pp	5.0
ceiling	2.0
ceiling_baseline_pp	95.0
Test baseline	46.80 pp
Adapted	96.30 pp
Delta	+49.50 pp
Failing class	Mixed forest: 100.00 → 87.8788, a drop of 12.1212 pp, n = 33
Outcome	1 of 19 classes fails, 11 improved, 5 held

So the adapter improved aggregate accuracy by 49.5 percentage points and was still rejected, because one class lost more than the ceiling allows. The rejection is a rule firing correctly, not a model failing. The record also carries the §8.6 unfloored minimum-size exposure note explaining the n=33 support.

§9.5 The preserved adjudication records

Three earlier records are preserved and immutable:

Record	Status	Delta
v001_val_rejected	REJECTED	val_delta_pp 42.0
v002_independent_test_rejected	REJECTED	test_delta_pp 49.5
v002_val_accepted_NOT_final	ACCEPTED	— (val only; not final)

forward_rule: run 1 is frozen; new work requires a new version. Nothing here is reopened.

§9.6 The artifact verification

Property	Value
Artifact verdict	verified
Manifest check	14 / 14 clean
Tree hash	5c6b86317d1e65962702dc9e377009b3df41cc13de1b15bceccb70ad977775e7
Weights sha256	07c76a75fa04624880ed7730590f5fdd7b145a8232e3c0af411c3c545a5adf5e
Config hash	78f1e3700da15aa1
vision_tower_untouched	trainable = {'model.text_model': 8683520} only

That last row is the architectural fact: only the language model was adapted. The vision tower is byte-identical to the base checkpoint. This is why the adapter is described as a text-side adaptation and not a vision adaptation, and it constrains what a future adapter version could claim.

§9.7 The end-to-end smoke evidence

Two inputs, one model, one prompt, two outputs (docs/PHASE5_VLM_CONTRACT.md):

input	output
uniform noise	"A black and white photograph of a man and a woman, who appear to be in a room, with a table in front of them."
structured imagery	"The image is a satellite image of a large, flat, blue-green area."

The second is a defensible description of a smooth ramp. The first is a fabrication. Nothing in the prompt distinguishes them; only the deterministic gate does, and it decides before the model is called.

---

§10 caption versus vqa: one specialist, two kinds

The router's task space has both vqa and caption as separate classes, and the planner maps both onto the vlm specialist. The difference between them is entirely in the prompt kind:

Aspect	vqa	caption
Router task class	vqa	caption
PromptKind	vqa	caption
Assets	1	1
Capability asked of the specialist	vqa	caption
Specialist instance	the same cached vlm object	the same cached vlm object
Model	identical	identical
Decode	greedy, max_new_tokens=128	identical
Gate	identical	identical

Consequence for the metrics. The 0.963 / 0.96432 figures in §9.1 are measured on presence questions — the primary endpoint is explicitly "presence-question normalised exact-match accuracy". A separate caption-quality metric (BLEU, ROUGE, CIDEr, human rating) does not exist in this release, and the closure record says why BLEU/ROUGE were excluded for the VQA endpoint. A caption-specific quantitative metric is UNKNOWN — not established from the available evidence. The caption path's evidence is qualitative (§9.7) plus the shared gate measurements.

Consequence for the router's own defect. The router-defect case study in 04-router.md §44–§47 turns on exactly this boundary: the query "Where are the built-up areas in this image?" collapsed to vqa when it should have been grounding. The vlm specialist answered "River" — a fluent, plausible, wrong answer of precisely the kind §8.2 says a prompt cannot prevent. The fix was in the frontend's interpret(), not in this specialist. That is the correct place for the fix: the specialist cannot know it was asked the wrong question.

---

Part B — grounding: RemoteCLIP plus a trained head

Grounding answers "where is X in this image?" and it is the specialist with the most carefully separated set of measured numbers in the project. This part documents the frozen encoder (§11), the zero-shot baseline that is deliberately not the product (§12), the trained head (§13), the specialist that dispatches between them (§14), the resolution decision (§15), and — most importantly — the two protocols and two decode variants that must never be collapsed into one number (§16).

§11 The frozen backbone: specialists/grounding/remoteclip.py

356 lines, written against measured facts rather than the model card. The docstring's opening line is the operating principle: "Written against measured facts, not the model card."

§11.1 The checkpoint and the measured contract

Property	Value	Source
Checkpoint	chendelong/RemoteCLIP → RemoteCLIP-ViT-B-32.pt	docs/PHASE7_GROUNDING_CONTRACT.md
Pinned revision	bf1d8a3ccf2d	same
File size	605.2 MB	same
Loader	open_clip.create_model_and_transforms("ViT-B-32", pretrained=<local .pt path>)	same
open-clip-torch version verified	3.3.0	same
Parameters	151,277,313	same
patch_size	32	same
Transformer width	768	same
Projected dim	512	same
Text dim	512	same

VERIFIED_PATCH_SIZE = 32, VERIFIED_TRANSFORMER_WIDTH = 768, VERIFIED_PROJECTED_DIM = 512, VERIFIED_PARAMETERS = 151_277_313 are module constants asserted at load time by _verify_contract().

§11.2 Finding P7-1 — the projected dimension is 512, not 768

This is the finding that bites. visual.positional_embedding is 768 wide and visual.proj is (768, 512). The embeddings comparable against the text tower are the projected ones: 512.

"Using 768 anywhere here would be a shape error that torch would only surface at the similarity computation, by which point the patch features have already been computed and cached."

_verify_contract() asserts the projected dim at load time for exactly this reason. It checks four things:

Check	Fails with
visual.patch_size == 32	ModelLoadError naming the observed value
visual.positional_embedding.shape[-1] == 768	ModelLoadError
positional_embedding.shape[0] == (resolution // 32) ** 2 + 1	ModelLoadError naming the expected count
visual.proj.shape[1] == 512	ModelLoadError

The third check is the one that catches a resolution mismatch: at 224 px with patch 32, the grid needs 1 CLS + 49 patches = 50 entries; at 448 it needs 1 + 196 = 197.

§11.3 Finding P7-2 — 448 interpolation works, and was measured

property	@224	@448
visual.image_size	(224, 224)	(448, 448)
visual.patch_size	(32, 32)	(32, 32)
positional_embedding	(50, 768)	(197, 768)
patch token grid	7 × 7 = 49	14 × 14 = 196
projected feature dim	512	512
text feature dim	512	512
vision time	0.0802 s	0.1802 s
cell size	1/7 ≈ 0.143 of width	1/14 ≈ 0.071
token increase	—	4.0×
attention cost (n²)	—	16.0×

The plan's C-5 arithmetic (patch 32 ⇒ 224/32 = 7 and 448/32 = 14) is confirmed by measurement. The plan's estimate that the finer grid costs "~4×" in tokens is exact (4.0×); the attention cost is 16× (n²), which the plan did not state.

force_image_size=448 produced positional_embedding of (197, 768) — resize_pos_embed interpolated the 50-entry embedding to 197 entries.

§11.4 Finding P7-3 — the 448 text-encoding error is UNEXPLAINED

The first probe run reported, at 448 only:

text encoding FAILED : TypeError: Unexpected type <class 'list'>

Isolated re-measurement did not reproduce it. Both resolutions behaved identically: SimpleTokenizer → returns a Tensor of shape (2, 77) → encode_text → (2, 512).

Status: UNVERIFIED. The cause is not established. The Phase 7 record states the position plainly: "It may have been a transient, an interaction with the probe's call order, or something the isolation run did not reproduce. It is recorded rather than papered over."

The defensive torch.as_tensor conversion in encode_text stays — "it is cheap and correct regardless" — but it is not claimed to be the fix for a failure whose cause is unknown. The code comment records why the conversion exists at all: "open_clip.get_tokenizer returns a tensor for some backends and a list for others, and encode_text rejects a list. That mismatch cost one probe run its 448 measurement."

§11.5 The encoder surface

Symbol	Contract
SUPPORTED_RESOLUTIONS = (224, 448)	Any other resolution raises ModelLoadError. "Both were measured to load correctly; an unmeasured resolution must not be assumed to."
EncodedImage	cls (512,), patch_tokens (n_patches, 512), grid (h, w), resolution
EncodedImage.n_patches / .dim	Derived properties
EncodedImage.patch_index(row, col)	Row-major index, bounds-checked — raises IndexError outside the grid
EncodedImage.token_boxes()	Normalised [x1,y1,x2,y2] for every patch token
RemoteCLIPEncoder.encode_image(image)	Returns an EncodedImage
RemoteCLIPEncoder.encode_text(texts)	Returns normalised (n, 512) features
RemoteCLIPEncoder.grid_size	resolution // 32
RemoteCLIPEncoder.describe()	Model, checkpoint, resolution, grid, n_patches, embedding_dim, device, frozen: True
build_encoder(config, resolution, device, checkpoint_path)	Constructs from config; checkpoint_path avoids the Hub fetch

token_boxes() is worth reading closely because it makes the localization floor explicit in the docstring: each token covers 1/grid_w by 1/grid_h of the image. At 224 that is 1/7 (0.143) of the width; at 448 it is 1/14 (0.071). No decode can produce a boundary finer than the grid, and pretending otherwise would be inventing precision the model does not have.

§11.6 encode_image replicates the vision forward, and says so

visual.forward does not expose per-patch tokens, so encode_image reimplements the forward up to ln_post:

patches = visual.conv1(x)
patches = patches.reshape(...).permute(0, 2, 1)
tokens  = torch.cat([cls, patches], dim=1)
tokens  = tokens + visual.positional_embedding
tokens  = visual.ln_pre(tokens)
tokens  = visual.transformer(tokens.permute(1, 0, 2)).permute(1, 0, 2)
tokens  = visual.ln_post(tokens)
cls_out   = tokens[:, 0, :]
patch_out = tokens[:, 1:, :]
if visual.proj is not None:
    cls_out   = cls_out   @ visual.proj
    patch_out = patch_out @ visual.proj

The docstring's claim is testable and tested: "Verified to reproduce the same CLS vector."

§11.7 Two load routes, and why one is preferred

Route	Behaviour
pretrained=<local .pt path>	Routes through open_clip.load_checkpoint(), which performs convert_state_dict, resize_pos_embed and resize_text_pos_embed
Manual torch.load + load_state_dict	Works, but skips all three normalisations

The README's manual route is therefore the fallback, not the default. build_encoder prefers a local checkpoint_path (which "removes the run's dependence on Hub availability and pins the exact bytes being measured") and only falls through to hf_hub_download(repo, filename, revision=revision) when none is given.

---

§12 The zero-shot baseline: specialists/grounding/inference.py

270 lines. The first line of the docstring is the most important sentence in the module:

"This is the BASELINE, not the product."

It exists so the resolution experiment has something to measure before the head was written, and so there is an ablation floor to compare the head against. It is not a claim about localization quality.

§12.1 The method

image  -> RemoteCLIP patch tokens (N, 512)
phrase -> RemoteCLIP text embedding (512,)
similarity = normalized_patches @ normalized_text   -> (N,)
reshape to (grid_h, grid_w)
-> box

No learned parameters. similarity_map L2-normalises both sides first, and the docstring explains why: "Without that the dot product is dominated by whichever vector happens to have the larger norm, which is a property of the features rather than of the match."

It also guards two degenerate cases: a zero-norm patch row is set to norm 1.0, and a zero-norm text embedding raises ValueError.

§12.2 The two box strategies

Strategy	Definition	Why it is reported
argmax	The single highest-scoring patch, as its token box	"the pure localization floor: the best a patch-similarity model can do at this grid resolution with no smoothing"
threshold	Bounding box of every patch scoring within delta of the peak	"Usually larger and sometimes better on objects that span several patches, sometimes worse when the peak is a spurious spike"

DEFAULT_DELTA = 0.02, and the docstring is explicit that this is "a starting value, not a tuned one — it is an ablation variable, and tuning it belongs on validation data."

threshold_candidate returns None when only one patch qualifies, because the box would be identical to argmax and reporting it twice adds nothing. The box spans min-to-max of the selected patches, so it is aligned to the token grid — "pretending to a finer boundary than the grid supports would be inventing precision the model does not have."

§12.3 decode_candidates_from_features — one decode, and why that matters

This function is the only implementation of the zero-shot decode, and its docstring records the defect that made that necessary. It is quoted here in full because it is the clearest example in the project of a measurement being wrong for a reason that had nothing to do with the model:

The Phase 8 evaluation script originally built its own single-box baseline with argmax_candidate, while Phase 7 measured the baseline through ground_phrase. Same 16,159 records, same metric, same cached features — but a different DECODE:

Phase 7 via ground_phrase  : mean best IoU 0.0972
eval via argmax_candidate  : mean best IoU 0.0092

A 10× gap. The eval printed head beats zero-shot: True (+0.1123) when the matched comparison was +0.0243. Both clear the 0.02 bar, but only the second is a claim about the head rather than about the decode.

The fix is structural: "there is now exactly one place that turns similarity into boxes."

The decode itself:

Step	Behaviour
1	Compute the similarity map
2	Append the threshold candidate if it exists
3	Walk patches in descending similarity
4	Accept a patch only if it beats its 4-neighbours (a local maximum)
5	Skip a patch within one cell of an already-accepted maximum
6	Stop at top_k (default 5)
7	If nothing was accepted, fall back to the single argmax candidate

Step 4's rationale is in the code: "Without this, top_k returns k adjacent patches from a single blob, which looks like k detections and is really one." Step 6's rationale is also in the code: "the zero-shot field has one strong peak and a tail of noise, and flooding the output would make precision meaningless."

§12.4 The verification that the fix is real

The Phase 8 record's check is the strongest available form of this claim — a numeric identity:

Phase 7 recorded baseline (cross-check) : 0.0972
this run's zero-shot, same samples      : 0.0972
|difference|                            : 0.0000

"If the decode still differed, the two would not agree to four decimals."

---

§13 The trained head: specialists/grounding/head.py

490 lines. This is the module that turns 49 frozen patch tokens plus a text embedding into boxes.

§13.1 Why 224 and not 448

The head's docstring opens with the decision and its measurement: the 448 option was REJECTED, on a paired t of −22.63. §15 gives the full record.

§13.2 The per-cell feature

For each of the 49 cells, the head builds a 2048-dimensional feature:

concat([ p_i,        # the cell's own projected patch token  (512)
         t,          # the text embedding, broadcast           (512)
         p_i * t,    # the elementwise interaction            (512)
         global_pool # the mean patch token, broadcast        (512) ])

4 × 512 = 2048. build_head asserts feature_dim == 4 × VERIFIED_PROJECTED_DIM, so a change to the encoder's projected dim cannot silently reshape the head's first layer.

§13.3 The head module

GroundingHead(feature_dim=2048, hidden_dim=512, dropout=0.10)

Submodule	Shape
proj	2048 → 512
norm	LayerNorm(512)
drop	Dropout(0.10)
out	512 → 5

The five outputs are, in order, tx, ty, tw, th, objectness (artifacts/grounding/remoteclip_grounding_v001/training_metadata.json → head.outputs).

_init_weights:

Parameter	Init
proj.weight	nn.init.normal_(std=0.02)
out.weight	nn.init.normal_(std=0.01)
out.bias	zeros, then out.bias[4] = -2.0

The -2.0 on the objectness bias is the same trick the change detector uses on its final logit: it starts the objectness prior low so the early epochs are not spent un-learning a saturated sigmoid.

forward carries three shape guards, including one on the assembled feature width — the guard that would fire if the concatenation in §13.2 were ever changed without changing feature_dim.

EPS = 1e-7 guards the box-width/height logs against a zero denominator.

§13.4 The decode: cell_relative

decode_cell_relative is a YOLO-style cell-relative decode. The head predicts offsets relative to the cell rather than absolute coordinates, which is what makes a 7×7 grid capable of producing a box smaller than a cell. The decode name cell_relative travels in the artifact metadata so a re-run under a different decode is distinguishable.

enforce_order normalises a box so x1 ≤ x2 and y1 ≤ y2 — a predicted box with swapped corners is a real output shape and clamping it is cheaper and more honest than discarding it.

assign_positive_cell selects the single positive cell for a ground-truth box by its centre. One cell, not many: this is a per-cell single-object assignment, and the choice is recorded in the module rather than left implicit.

§13.5 NMS and IoU, implemented in pure torch

nms(...) and _box_iou(...) are implemented in torch rather than pulled from a detection library. The consequence is that the head has no dependency beyond torch, and the NMS threshold travels as a parameter (nms_iou=0.50 at the specialist layer, §14.2).

§13.6 The loss

grounding_loss(box_weight=0.5, giou_weight=0.3, confidence_weight=0.2,
               positive_confidence_weight=20.0)

Term	Weight	Note
Box (L1 on the four offsets)	0.5
GIoU	0.3	giou_loss is implemented in the module
Confidence (BCE on objectness)	0.2
Positive-cell confidence multiplier	20.0	Applied to the positive cell's confidence term

positive_confidence_weight = 20.0 is the term that fixes the objectness prior. The measured trajectory shows it working: conf falls from an over-confident 0.7897 at epoch 1 to 0.5685 at epoch 20 while val_iou rises. The Phase 8 record reads the pattern: "box and giou fall together, which is the healthy pattern (a falling box with a rising giou would mean the box is drifting in size)."

LossBreakdown returns the four components separately so the trajectory above is reportable per term rather than as one scalar.

§13.7 The head's parameter count

1,052,677 parameters (docs/PHASE8_GROUNDING_HEAD_DECISION.md, confirmed in training_metadata.json → head_parameters). The Phase 8 record's framing of the result is precise: "a 1.05M-parameter head over frozen 7×7 RemoteCLIP tokens beats a cosine-argmax baseline by 2.6× on mean best IoU (0.2566 vs 0.0972) at matched candidate budget."

§13.8 The 20-epoch validation trajectory

From training_metadata.json → history, CPU, ~37 s/epoch:

epoch	loss_total	loss_box	loss_giou	loss_confidence	val_iou_argmax	val_recall50_argmax
1	0.428415	0.06405	0.794837	0.789694	0.0436	0.0157
5	0.386406	0.048939	0.758093	0.672542	0.0673	0.0365
10	0.365261	0.044586	0.731306	0.617881	0.0831	0.0506
11	0.361891	0.043897	0.726564	0.609865	0.0901	0.0573
12	0.358045	0.04327	0.720912	0.600681	0.0899	—
20	0.3419	0.0401	0.6937	0.5685	0.0943	—

best_val_iou recorded as 0.0946 (training_metadata.json), first_val_iou 0.0436. lr starts at 1e-4 and follows a cosine schedule (1e-4 → 9.931806517013612e-05 → 9.729086208503174e-05 → …).

training_metadata.json records "beats_baseline": false. That is not a contradiction of §16 and it must not be read as one. The field compares the head's validation IoU (0.0946) against the zero-shot eval baseline (0.0972) — two different splits. §16.4 gives the full explanation of the val/eval gap. The honest summary is: the artifact's own metadata field says false; the decode-matched eval protocol says the head wins by +0.1594 IoU. Both are in the record; neither replaces the other.

---

§14 The specialist: specialists/grounding/specialist.py

852 lines. This is the module that decides which decode to run and carries the result out with its provenance.

§14.1 The frozen contract

1 image + phrase  ->  RemoteCLIP @ 224  ->  49 projected patch tokens
                  ->  GroundingHead     ->  49 x (tx, ty, tw, th, objectness)
                  ->  decode            ->  boxes + scores
                  ->  confidence        ->  ConfidenceBreakdown
                  ->  evidence          ->  BOUNDING_BOX / GEOLOCATION / STATISTIC

§14.2 The constructor surface

Parameter	Default	Meaning
grid	7	The token grid side at 224
nms_iou	0.50	IoU above which two boxes are considered the same object
max_candidates	6	Cap on emitted boxes
score_threshold	0.30	Minimum objectness to emit a box
head_top_k	5	Top-k selection inside the head decode
resolution	224	Encoder resolution

max_candidates defaults to 6, not 20. The config carries grounding.max_candidates: 20; the serving path uses grounding.serving_max_candidates = 6. This is not a typo and it is not an oversight — §16.3 explains that 20 versus 6 is the difference between the canonical protocol's number and the decode-matched one, and build_grounding_specialist deliberately takes the matched value.

§14.3 Two degraded modes

The module declares two, and they are different failures:

Mode	Condition	Behaviour
No trained head	has_head is False	Zero-shot decode; the result is marked degraded and the reason names the missing head
Head load failure	A head path was named and exists but cannot be read	HeadLoadReport records invalid; the reason travels in the result

has_head distinguishes "we have a trained head" from "we have a module with random weights in it" — the same distinction change.has_checkpoint and optical_sar.has_head make (§4.2).

§14.4 Why the VLM is not asked for coordinates (finding C-5)

The module's own section header is WHY THE VLM IS NOT ASKED FOR COORDINATES (C-5). The rule: the head produces the boxes; a language model may narrate them and may not produce them. The same rule is restated in specialists/change/specialist.py:54-57 for the change map, and in specialists/optical_sar/prompts.py for the class label. It is one rule with four applications.

§14.5 The confidence derivation

CONFIDENCE_WEIGHTS = {
    "max_objectness":      0.40,
    "top_mean_objectness": 0.35,
    "score_contrast":      0.25,
}

Component	Definition	Why
max_objectness	The highest objectness among emitted boxes	The single strongest signal the head produced
top_mean_objectness	Mean objectness over the top boxes	Guards against one lucky peak
score_contrast	Separation between the top score and the rest	A flat score field is not a detection

_score_stats computes these from the decoded boxes. _confidence_for composes them, and — like the change specialist — the composition includes a minimum against the peak signal rather than a pure weighted sum.

§14.6 The degenerate-box guard

DEGENERATE_AREA_FRACTION = 0.9

A box covering ≥ 90% of the frame is not a localization; it is a failure that looks like one. The guard applies only to the zero-shot path, and the module records the measurement that motivated it: the zero-shot path was observed producing a full-frame box with x1=0 y1=0 x2=1 y2=1.

_drop_degenerate filters them, and _build_evidence emits a separate STATISTIC item recording what was dropped and why. The reason it is a STATISTIC and not a BOUNDING_BOX is the same reason the change specialist's withheld-region record is a STATISTIC: emitting the boxes would defeat the suppression.

§14.7 _decode_with_head and the argmax fallback

When no box clears score_threshold, the decode falls back to the argmax cell rather than emitting nothing. This is why head_argmax is a reported variant at all (§16.2) — it is a real runtime path, not a hypothetical. Its measured mean best IoU is 0.1215.

§14.8 Evidence emitted

EvidenceType	When	Payload highlights
BOUNDING_BOX	One per emitted box	coordinates = [x1, y1, x2, y2], coordinate_system, score, label
GEOLOCATION	When the asset carries georeferencing	CRS and transform facts
STATISTIC	Always	Decode variant, thresholds, candidate counts, score statistics
STATISTIC (degenerate)	Only when boxes were dropped	n_dropped and the reason

§14.9 DEFAULT_HEAD_PATH is a code constant, not a config key

specialists/grounding/specialist.py carries a long comment titled "WHY THIS IS A CODE CONSTANT AND NOT A CONFIG KEY". The reasoning, in brief:

• head_path was never set in configs/base.yaml;
• configs/base.yaml is hashed, and the hash is frozen at 78f1e3700da15aa1 (§4.4 of 07-configuration-freeze.md);
• adding a key would move the hash and detach the project's benchmark numbers from their config;
• so head_path=None now means "use the shipped head" rather than "no head".

This is the same trap the optical-SAR radiometry module documents for croma.use_8_bit and croma.checkpoint_path (§37.5, §35.7). Three modules independently arrive at the same workaround, and each one names the reason rather than leaving a bare constant.

§14.10 Head loading has exactly four outcomes

load_grounding_head returns a HeadLoadReport with requested_path, resolved_path, loaded, source, reason, detail. The four outcomes are:

Outcome	loaded	source	Meaning
none	False	none	No path was requested
missing	False	missing	A path was requested and does not exist — a deployment case
invalid	False	invalid	The path exists and cannot be read — a corrupt artifact, and the reason is named
loaded	True	shipped / explicit	A trained head is in memory

Distinguishing missing from invalid is the §4.2 rule expressed as a data structure rather than a branch.

§14.11 build_grounding_specialist and the 6-versus-20 decision

build_grounding_specialist(config, ...)  # uses grounding.serving_max_candidates = 6

The comment at the call site records that it deliberately takes the config's serving_max_candidates (6) rather than max_candidates (20). §16.3 gives the measurement behind that choice.

---

§15 The resolution decision: 448 was rejected

§15.1 The claim under test

The plan's C-5 arithmetic said a 448 px grid would give 14×14 = 196 cells at 1/14 of the image each, versus 7×7 = 49 cells at 1/7. Finer cells should localize better. The counter-arguments were the measured costs from P7-2: 4× the tokens and 16× the attention.

§15.2 The decision

448 was REJECTED, on a paired t of −22.63. The measurement was run over the full 16,159-record VRSBench eval set, in the same style as the Phase 7 resolution decision — which docs/PHASE14_OPTICAL_SAR_DECISIONS.md §3 cites as the project's practice: "224px was frozen by measurement over all 16,159 eval records rather than by preference."

§15.3 The recorded costs

Cost	@224	@448
Patch tokens	49	196 (4.0×)
Attention cost (n²)	—	16.0×
Vision forward time	0.0802 s	0.1802 s
Peak encoder VRAM	592 MB	not recorded as a headline figure
Cell size	~0.143 of width	~0.071

§15.4 What the resolution experiment did not establish

From docs/PHASE7_GROUNDING_CONTRACT.md, verbatim in substance:

• Whether 448 improves localization was not established by the contract probe — "the probe measures the encoder's token grid, not the quality of any box derived from it." That is what the resolution experiment was for, and it returned a negative.
• Whether the zero-shot baseline is any good — "the baseline exists as an ablation floor for the Phase 8 head, not as a claim."
• Anything about real remote-sensing imagery — "A synthetic fixture proves the pipeline runs, not that it localizes."

---

§16 The two protocols and the two decode variants

This section is the single most important part of this chapter. The style guide's rule is that grounding is "measured under two protocols (canonical 0.2838 / matched6 0.2566) and two decode variants (head_argmax 0.1215, zero-shot 0.0972). Never quote one alone."

§16.1 The canonical protocol (eval_result_canonical.json)

Property	Value
head_threshold	0.2838
recall@0.10	0.6882
recall@0.25	0.5047
recall@0.50	0.2198
latency	2.205 ms
head_decode.config_default_top_k	20
head_decode.top_k	20
n	16,159
grid	7
resolution	224
device	cpu
config_hash	78f1e3700da15aa1

§16.2 The two decode variants inside the canonical protocol

Strategy	boxes/image	mean best IoU	Recall@0.10	Recall@0.25	Recall@0.50	latency
zero-shot (multi-candidate)	5.99	0.0972	0.3298	0.1188	0.0234	—
head argmax	1	0.1215	0.3183	0.2088	0.0795	0.655 ms
head threshold, top_k=6	6	0.2566	0.6315	0.4545	0.1938	—
head threshold, top_k=20 (config)	20	0.2838	0.6882	0.5047	0.2198	2.205 ms

zero_shot_matched in the canonical file carries delta: 0.02, top_k: 5, mean_candidates: 5.99.

The head_argmax number is identical in both protocol files: 0.1215. That is expected — the argmax decode emits exactly one box, so a change to the candidate cap cannot affect it. It is a useful consistency check on the two files.

§16.3 The matched protocol (eval_result_matched6.json)

Property	Value
head_threshold	0.2566
recall@0.10	0.6315
recall@0.25	0.4545
recall@0.50	0.1938
head_decode.top_k	6
head_argmax	0.1215 (identical to canonical)
n	16,159
config_hash	78f1e3700da15aa1

§16.4 Why two protocols exist, and why the gap is expected

The candidate-count defect is the reason. Mean best IoU is a max over predictions, so emitting more boxes raises it mechanically. The head's threshold decode defaulted to max_candidates: 20 while the baseline emits 5.99 — "an uncontrolled asymmetry in the head's favour."

The fix, from docs/PHASE8_GROUNDING_HEAD_DECISION.md:

--head-top-k and --head-score-threshold overrides, plus a head_decode block recorded in the artifact. Without it the artifact could not say which setting produced its number, and a re-run at config default silently yields a different figure.

The measured cost of capping to the baseline's own budget:

head top_k	mean best IoU	delta vs zero-shot
20 (config default)	0.2838	+0.1866
6 (matched to baseline's 5.99)	0.2566	+0.1594

Capping costs 0.027 IoU. "The win survives."

The decode-matched delta is therefore:

Metric	Delta
mean best IoU	+0.1594
Recall@0.50	+0.1704

The bar was MIN_IMPROVEMENT_IOU = 0.02. The measured margin is 8× the bar.

And the honest caveat that must travel with the matched number:

head_argmax vs zero-shot is not an apples-to-apples comparison: 1 box against ~6 boxes flatters the head, because mean best IoU takes the max over predictions. It is reported because it is the number directly comparable to the Phase 7 resolution experiment's zero-shot argmax, not because it decides anything.

§16.5 Recall@0.50 is the metric the head made live

Strategy	Recall@0.50
zero-shot	0.0234
head argmax	0.0795
head threshold top_k=6	0.1938
head threshold top_k=20	0.2198

The Phase 8 record states the significance: "at the zero-shot level Recall@0.5 was near-dead (0.0234), which is the degeneracy the Phase 7 decision record flagged. A trained head is what makes that metric live." From 0.0234 to 0.1938 is an 8.3× improvement.

§16.6 The validation/eval gap, which is not a bug

Split	mean best IoU
Validation (held-out slice of the train split)	0.0946 (best), 0.0436 at epoch 1
Eval (VRSBench eval split)	0.2566 (matched6) / 0.2838 (canonical)

The Phase 8 record's explanation, quoted because it is the only correct way to read the two numbers together:

"These are not comparable and the gap is expected: validation is a held-out slice of the TRAIN split, which has noisier ground truth (29.5% of its boxes are out-of-range and filtered, and the surviving ones come from a different annotation pass). The train split's own labels are harder than the eval split's. This is a property of VRSBench, not a bug."

This is why training_metadata.json says beats_baseline: false (§13.8): it compares the validation IoU (0.0946) against the eval baseline (0.0972). The field is not wrong about what it compares; it is just comparing the wrong pair for the question "does the head beat the baseline?"

§16.7 What the eval does and does not establish

From docs/PHASE8_GROUNDING_HEAD_DECISION.md, the "What this does NOT establish" list:

• It is not a benchmark result. "This is the VRSBench eval split, which is the public test set for this dataset. It is legitimately evaluation data and was never trained on — but 'beats the zero-shot baseline on VRSBench eval' is not the same as 'performs well on the hidden ISRO/SAC set'."
• Nothing about the hidden distribution. "VRSBench is overhead optical. The hidden set is Cartosat-2S + RISAT, which is a different distribution entirely."
• head_threshold at top_k=20 was not tuned. "20 is the config default, not a validation-selected optimum. Selecting it on eval would be benchmark tuning."
• At the time Phase 8 closed, the head was not yet wired into the specialist — that was recorded as the remaining integration step. It has since been wired (§14.9, §14.11).

---

§17 Grounding: limitations

#	Limitation	Status
1	The 0.2838 / 0.2566 numbers are VRSBench eval, not the hidden Cartosat-2S + RISAT set	OPEN — no hidden-set evaluation exists
2	head_threshold at top_k=20 is a config default, not a validation-selected optimum	OPEN — Phase 13 calibration may revisit on validation only
3	The localization floor is the token grid: 1/7 of the image per cell at 224	Structural. token_boxes() documents it rather than hiding it.
4	Zero-shot Recall@0.50 is near-degenerate (0.0234)	Measured, explained by the head's improvement
5	The 448 text-encoding TypeError (P7-3) is unreproduced and unexplained	UNVERIFIED — cause not established
6	The GEOLOCATION evidence depends on the asset carrying georeferencing	Deployment-dependent; no georeferencing means no GEOLOCATION item
7	max_candidates is 20 in config and 6 in serving	Documented, deliberate (§14.11). The two produce different numbers.
8	The 810 MB remoteclip_grounding_v001.zip archives a 754 MB feature cache	Recorded as wasteful; the two 11.8 MB _eval_* archives are what need transferring
9	A stale untagged remoteclip_grounding_v001_eval.zip exists	Recorded as superseded; should be ignored

---

Part C — change: the STANet-style Siamese detector

Change detection is the project's only VERIFIED headline (docs/DOCS_STYLE_GUIDE.md §3: "pooled IoU 0.8122 / macro IoU 0.8457 / pooled F1 0.8964 — the only VERIFIED headline"). It is also the specialist whose trained checkpoint is deliberately not wired into serving. This part documents the model (§18), the attention memory line (§19), the loss (§20), post-processing and registration (§21), the specialist (§22), the dataset and split (§23), training (§24), the measured result (§25) and the limitations (§26).

§18 The model: specialists/change/stanet.py

694 lines. The docstring's first paragraph states the provenance decision:

"The architecture follows STANet's shape — shared Siamese encoder, spatial-temporal attention over feature differences, feature-difference aggregation decoder — reimplemented rather than vendored, per the Phase 0 resolution of finding C-9 (the upstream repo is Python 3.6-era and depends on visdom/apex)."

§18.1 The forward path

T1 ---> [ shared encoder ] ---> f1  (4 levels)
T2 ---> [ shared encoder ] ---> f2  (4 levels)
                                  |
                      |f1 - f2| + concat([f1, f2, |f1-f2|])
                                  |
                          spatial attention (PAM)
                                  |
                        progressive decoder + skips
                                  |
                          1-channel change logit

§18.2 Weights are tied, not copied

"Both branches call the SAME module instance. There is no second encoder to fall out of sync. This is the 'shared encoder' requirement from plan section 16 enforced by construction, not by convention."

STANetStyleChangeDetector.forward calls self.encoder(t1) and self.encoder(t2) on the same SharedResNetEncoder instance. DifferenceFusion.forward(f1, f2) computes torch.abs(f1 - f2) and reduces concat([f1, f2, diff]) (3× channels) back to the working width via a Conv2d(3C → out) + BatchNorm2d + ReLU.

§18.3 The measured encoder shapes

From the module docstring, for a ResNet-18 trunk at 256×256 input:

Level	Channels	Spatial	Positions
layer1	64	64×64	4,096
layer2	128	32×32	1,024
layer3	256	16×16	256
layer4	512	8×8	64

ENCODER_CHANNELS = (64, 128, 256, 512) is the module constant, "verified by probe against torchvision resnet18."

§18.4 The constructor and its guards

STANetStyleChangeDetector(*, width=128, pretrained=False, weights_path=None,
                          frozen_encoder=False, sa_mode="PAM",
                          attention_budget_bytes=DEFAULT_ATTENTION_BUDGET_BYTES)

Guard	Condition	Error
sa_mode	must be "PAM" or "BAM"	SpecialistError
width	must be ≥ 8	SpecialistError
attention_budget_bytes	must be ≥ 0	SpecialistError
input shape	t1.shape == t2.shape	SpecialistError
input rank	must be 4-D	SpecialistError
spatial divisibility	h % 8 == 0 and w % 8 == 0	SpecialistError naming the encoder stride

sa_mode="BAM" is declared in config but not implemented, and it raises rather than silently aliasing PAM:

"BAM is the channel/co-occurrence variant in STANet. Kept as a declared-but-unimplemented branch rather than silently aliasing PAM, so a config asking for BAM fails visibly here."

§18.5 The decoder

Progressive, coarse-to-fine, with a skip at every level:

Module	Composition
dec3	DecoderBlock(width, width, width)
dec2	DecoderBlock(width, width, width)
dec1	DecoderBlock(width, width, width // 2)
final_up	ConvTranspose2d(width//2, width//2, 4, stride=4) + BN + ReLU
head	Conv2d(width//2, 1, 1)

DecoderBlock is Conv2d(in+skip, out, 3) + BN + ReLU + Conv2d(out, out, 3) + BN + ReLU, with a bilinear F.interpolate to the skip's spatial size before concatenation. The path is 8×8 → 16 → 32 → 64 → 256 at width=128.

forward ends with a final safety interpolation if x.shape[-2:] != (h, w), so the returned logits are always at input resolution.

_init_head:

nn.init.normal_(self.head.weight, std=0.01)
self.head.bias.fill_(FINAL_BIAS_INIT)   # -2.0

FINAL_BIAS_INIT = -2.0, with the rationale in the module constant's comment: "LEVIR-CD's changed-pixel fraction is roughly 5–15%, so a bias of -2.0 starts the prior near 0.12 rather than 0.5 and stops the first epochs being spent un-learning a saturated sigmoid."

§18.6 ChangeOutput

Field	Shape / type
logits	(B, 1, H, W) at input resolution
probabilities	sigmoid(logits)
attention_applied	list[int] — levels where attention ran
attention_skipped	list[int] — levels where it was skipped for memory
attention_bytes	dict[int, int] — the computed matrix size per level

to_trace() renders the three attention fields with the byte keys stringified, so the trace can report which levels were skipped and why. The docstring states the purpose: "Skips are returned in the output so the trace can report them."

§18.7 Pretrained weights are not a hard dependency

Config says change.pretrained: true. A first run with no local cache needs a download from download.pytorch.org, which may be unavailable. The resolution order:

Order	Source	On success	On failure
1	A local weights_path	Loaded, pretrained_used = True	ModelLoadError (a named file that does not exist)
2	ResNet18_Weights.IMAGENET1K_V1 download	Loaded, pretrained_used = True	Falls through to 3
3	Random initialisation	load_warning set explicitly	—

Two details matter. First, the local-file branch uses strict=False deliberately and then checks the missing keys by hand:

trunk_missing = [k for k in missing if not any(k.startswith(p) for p in ("fc.",))]
if trunk_missing:
    raise ModelLoadError(...)

The comment explains: "strict=False because a checkpoint's dict may carry head weights we do not use; anything MISSING from the trunk is a real problem." Second, the random-init fallback produces an explicit warning rather than silence:

"Random init is a legitimate starting point for change detection — the task is pixel-pair comparison, not ImageNet classification — but the caller is told, because 'pretrained: true' in a config must not become a lie when the download fails."

§18.8 Checkpoint I/O is strict

Function	Behaviour
save_change_model(path, model, metadata)	Saves {"state_dict", "config"}; writes model_metadata.json beside it when metadata is given
load_change_model(path, device)	Reads the embedded config, reconstructs, then load_state_dict(..., strict=True)

Two ModelLoadError paths, both named:

• A checkpoint with no embedded config — "it cannot be reconstructed without guessing the architecture".
• A state_dict that does not match the reconstructed architecture — so "an architecture drift fails loudly."

load_change_model calls model.eval(). build_change_specialist then sets model._satquery_trained = True, which is the provenance marker has_checkpoint reads (§22.1).

---

§19 The attention memory line is computed, not assumed

This is the section of the model most likely to be misread, and the module devotes a full docstring section to it.

§19.1 The arithmetic

STANet's PAM builds a full positions × positions attention matrix. At batch 8, fp32:

Level	Positions	Bytes	Verdict
layer1	4,096	8 * 4096² * 4 = 537.0 MB	exceeds the budget
layer2	1,024	8 * 1024² * 4 = 33.5 MB	fine
layer3	256	8 * 256² * 4 = 2.1 MB	fine
layer4	64	8 * 64² * 4 = 0.13 MB	fine

attention_matrix_bytes(batch, positions, dtype_bytes=4) is the function that computes this.

§19.2 The decision

DEFAULT_ATTENTION_BUDGET_BYTES = 256 * 1024 * 1024   # 256 MB

The constant's comment gives the reasoning: "256 MB leaves room for activations, gradients and the optimizer state inside a 15 GB T4 while comfortably admitting layer2 (33.5 MB) and excluding layer1 (537 MB) at the standard batch size of 8."

So attention is applied at layers 2, 3 and 4 and skipped at layer 1, where the difference features are fused directly instead.

§19.3 The decision is recomputed every forward pass

SpatialAttention.forward(x, budget_bytes) returns (features, applied, bytes):

needed = attention_matrix_bytes(b, h * w, x.element_size())
if needed > budget_bytes:
    return x, False, needed        # skip: features pass through unchanged

The consequence, in the module's words: "The decision is recomputed on every forward pass from the ACTUAL batch size and a byte budget, so changing batch size or tile size moves the line correctly rather than silently overrunning memory."

§19.4 The deviation is recorded, not hidden

"This is a deviation from a literal STANet reproduction, and it is recorded as one: attention at 64×64 would not fit. It is not a silent substitution."

The SpatialAttention module itself is PAM-shaped: 1×1 query, key, value and out convolutions, with hidden = max(1, channels // reduction) at reduction = 8, scale = sqrt(hidden), softmax over the key axis, and a residual x + self.out(attended).

---

§20 The loss: change_loss

§20.1 Why Dice is not decoration

def dice_loss(logits, target, eps=1e-6):
    prob = torch.sigmoid(logits)
    intersection = (prob_flat * target_flat).sum(dim=1)
    denominator  = prob_flat.sum(dim=1) + target_flat.sum(dim=1)
    dice = (2.0 * intersection + eps) / (denominator + eps)
    return 1.0 - dice.mean()

The docstring's argument:

"BCE alone is minimised by predicting 'no change' everywhere when change is rare, which is exactly the imbalance LEVIR-CD has. Dice is computed on the soft probabilities so it is differentiable and directly optimises region overlap."

eps guards the empty-target case: "a tile with no change has numerator 0 and denominator 0, which would be NaN without it."

§20.2 The composite

change_loss(logits, target, *, bce_weight=0.5, dice_weight=0.5, pos_weight=None)

total = bce_weight * BCEWithLogits(logits, target, pos_weight) + dice_weight * Dice

ChangeLossBreakdown returns total, bce, dice separately with a to_dict().

The 0.5/0.5 default is a config value, not a tuned one. training/change/train.py's docstring records a real defect here:

"An earlier version of the training script accepted those arguments and then passed literal 0.5/0.5, making every config value a silent no-op. tests/unit/test_change_train_script_contract.py pins that this cannot come back."

pos_weight is deliberately left None by default with the reason stated: "the Dice term already addresses the class imbalance, so this is left as an explicit tuning knob rather than a hidden default."

---

§21 Post-processing and registration: specialists/change/postprocess.py

507 lines. Everything here is deterministic — "no model, no sampling, same input same output."

§21.1 Why registration quality is measured, not assumed

The module quotes plan section 16 directly:

"If registration quality is too poor: lower confidence, optionally refuse precise spatial claims. Never convert bad registration into artificial certainty."

And then explains the failure mode: "A change detector fed two mis-registered images reports change along every edge in the scene. That output is not wrong so much as meaningless, and it looks exactly like a confident detection."

So alignment is measured before the change map is trusted, and the measurement travels with the result.

§21.2 The method: cv2.phaseCorrelate

measure_registration(t1, t2, *, max_shift_px=8, min_response=0.15) returns a RegistrationQuality:

Field	Meaning
shift_x, shift_y	Sub-pixel translation
response	Correlation response in [0, 1]
max_shift_px	The tolerance used
is_usable	The verdict
reason	A sentence naming the failure

Two failure conditions, with the reasons recorded verbatim:

Condition	reason
magnitude > max_shift_px	"acquisitions are offset by {m}px (limit {max}px); change along every edge is expected"
response < min_response	"phase-correlation response {r} is below {min}; the pair shares no translatable structure"
otherwise	"translation within tolerance"

§21.3 The gate is a gate, not a certificate

The module is unusually careful about what the measurement can claim:

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

§21.4 confidence_factor()

shift_penalty   = max(0.0, 1.0 - shift_magnitude / max_shift_px)
response_factor = min(1.0, max(0.0, response / 0.15))
return min(shift_penalty, response_factor)

Two independent penalties, and whichever is worse wins. The docstring: "A pair that is offset AND uncorrelated takes the worse of the two, which is the conservative choice." A non-positive max_shift_px yields a shift_penalty of 0.0.

§21.5 The float32 cast that is not redundant

to_grayscale_float collapses (H,W), (H,W,C) and (C,H,W) to a 2-D float32 array in [0, 1], percentile-stretched so a uint16 raster and a uint8 raster of the same scene correlate identically. Its final line carries a long comment worth reproducing, because it is a measured OpenCV interaction:

"np.percentile returns float64 scalars even for a float32 input, so out - lo promotes the whole array to float64. Without this cast the function returns float64 while its docstring promises float32 — and cv2.phaseCorrelate then fails its own type assertion: src1.type() == window.type(), with a CV_32F Hanning window. Measured, not theorised."

measure_registration then re-checks the dtype explicitly, so "a future change to either side fails with a readable message instead of an OpenCV assertion." It creates a cv2.createHanningWindow((w, h), cv2.CV_32F) because "without one the FFT edge effects dominate and a perfectly aligned pair can score badly."

Non-finite returns are coerced to 0.0 for response, dx and dy rather than propagated.

§21.6 Region extraction

Constant / parameter	Value
DEFAULT_KERNEL_SIZE	3
open_iterations	1
close_iterations	2
min_component_pixels	32
connectivity	8

The morphology order matters and is documented. morphological_cleanup does open then close, not the reverse:

"Opening removes isolated speckle first, so the closing that follows merges genuine regions rather than fusing specks into false blobs. Reversing the order produces measurably larger regions."

The kernel is cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3)). kernel_size <= 1 makes the function a no-op passthrough "so a caller can disable it without branching."

connected_regions(mask, probabilities=None, min_pixels=32) uses cv2.connectedComponentsWithStats(..., connectivity=8) and returns (kept_regions, n_components_before_filtering). Two decisions are documented:

• 8-connectivity, because "a diagonal chain of changed pixels is one object on the ground, and 4-connectivity would fragment it."
• The raw count is returned, because "Dropping without recording would hide how noisy the map actually was."

Regions are sorted by descending area. RegionStats carries label, area_pixels, bbox_px (col_min, row_min, col_max, row_max), mean_probability, plus width and height properties.

§21.7 The raw mask is what gets scored

postprocess_change_map(probabilities, *, threshold=0.5, kernel_size=3, open_iterations=1, close_iterations=2, min_component_pixels=32, apply_morphology=True) returns a PostprocessResult carrying both masks:

Field	Content
binary_mask	The RAW binarized mask
cleaned_mask	The morphology-cleaned mask
regions	Kept regions with statistics
n_components_raw / n_components_kept	Before and after the area filter
total_change_pixels	Sum over the cleaned mask
change_fraction	total_change_pixels / binary_mask.size

"The RAW binary mask is retained alongside the cleaned one. Metrics are reported on the raw mask by default, because morphology is a presentation aid and applying it before scoring would inflate the numbers relative to the literature. The cleaned mask is what gets drawn."

training/change/train.py's docstring restates this from the training side and makes the consequence concrete: "A val number produced by a different mask than the one the benchmark scores is not a val number."

§21.8 regions_to_schema — the schema bridge

Converts RegionStats into schema ChangeRegion objects, building the Box in the requested coordinate system (NORMALIZED_0_1 or PIXEL). Geographic coordinates are explicitly out of scope:

"Callers that want geographic coordinates convert afterwards via geospatial.transform, which keeps this function free of rasterio and CRS concerns."

Any other coordinate system raises ValueError naming it. Non-positive image dimensions raise.

---

§22 The specialist: specialists/change/specialist.py

916 lines.

§22.1 Identity and the has_checkpoint property

Attribute	Value
name	"change"
version	"0.1.0"
capabilities	("change",)
threshold	0.5
min_component_pixels	MIN_REGION_PIXELS = 32
max_shift_px	DEFAULT_MAX_SHIFT_PX = 8
min_registration_response	0.15

@property
def has_checkpoint(self) -> bool:
    return bool(getattr(self.model, "_satquery_trained", False))

model is never None in practice — an untrained one is still a model. This property is what distinguishes "a checkpoint was loaded" from "we built a random one and are being honest about it."

§22.2 Why this module exists

The docstring's second paragraph is a piece of project history worth keeping:

"This is the module that makes the Phase 9 model actually dispatchable; before it existed the architecture, post-processing and metrics all passed their tests while the controller had nothing to call, because specialists/change/ had no Specialist subclass."

§22.3 Two assets, not one

"Change detection is meaningless on a single image, and undefined on three. validate_request enforces exactly two, because a silent 'just use the first two' would produce a confident answer to a question the caller did not ask."

The count check raises InvalidRequestError with a user-facing message — "Change detection needs exactly two images: an earlier one and a later one." — and a context dict naming expected: 2 and actual: n. The code comment notes the two real cases: "ONE asset is the common mistake… THREE is the other: they attached a time series."

§22.4 _assess_pair — three checks, in order

validate_request calls _assess_pair, and execute reuses the same assessment rather than measuring twice:

"Split out so execute can reuse the SAME assessment the validator made, rather than measuring registration twice and reporting two numbers that could disagree."

Order	Check	Failure
1	t1.path == t2.path	TemporalPairError — "T1 and T2 are the same file"
2	t1.sha256 == t2.sha256 (when both present)	TemporalPairError — "a repeated acquisition is not a temporal pair"
3	geospatial.crs.compare_crs(t1.geo.crs, t2.geo.crs)	Not fatal; a warning
4	measure_registration(...)	Produces the RegistrationQuality

The CRS branch is nuanced and the comment says why:

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

Two distinct warnings result: one for "comparison unavailable" (no CRS to compare) and one for "different CRS" (requires_reprojection).

_measure_registration_for degrades to a zero-quality verdict on failure, and the distinction it preserves is worth quoting:

"A failure to MEASURE is not the same as a measurement of failure, but both mean the pair cannot be trusted spatially, so both produce an unusable verdict. The distinction is recorded in the warning."

§22.5 Degraded mode: no checkpoint wired by default

This is the section that explains why a VERIFIED specialist is not deployed. The docstring is explicit:

"A trained head now exists and is benchmarked (artifacts/change/levir_change_v001/head.pt, test pooled IoU 0.8122), yet it is deliberately NOT wired into serving by default. Populating change.checkpoint_path in configs/base.yaml would move Config.hash, and scripts/eval_change.py refuses to score on a hash drift (exit 3) — so that one edit would invalidate the project's own benchmark number. The wiring path is therefore the registry builders= override (see core/registry.py), which injects the checkpoint without touching the config."

So the chain is: benchmark number ↔ config hash ↔ base.yaml. Adding the key to wire the model would detach the benchmark from its config. The registry override is the escape hatch, and it is the same pattern the optical-SAR modules use for their own hash-exempt values (§35.7, §37.5).

The degraded behaviour follows Phase 8's precedent: "a missing artifact is a deployment case, not a crash. The specialist runs the randomly-initialised model, marks the result degraded, and says so plainly — because a randomly-initialised change map is a map of noise, and presenting it as a detection would be exactly the fabrication the evidence system exists to prevent."

§22.6 Suppression: poor registration withholds spatial claims

In execute, when not reg.is_usable:

Action	Detail
Warning appended	"poor co-registration: {reason}. Spatial change claims are suppressed; confidence reflects the measurement, not the change map."
Regions	Withheld — regions = [], and a warning says how many were withheld
Change map	Still written, but without georeferencing
geospatial	is_georeferenced=False, transform dropped
confidence.degraded	True, with the reason "pair not co-registered; spatial claims suppressed"

The comment on the suppression branch: "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."

§22.7 _predict — the stride-8 reflect pad

h, w = t1.shape[-2:]
if h % 8 or w % 8:
    ph, pw = (-h) % 8, (-w) % 8
    t1 = F.pad(t1, (0, pw, 0, ph), mode="reflect")
    t2 = F.pad(t2, (0, pw, 0, ph), mode="reflect")
    warnings.append(f"padded {h}x{w} to {h+ph}x{w+pw} ...")

Then, after the forward pass, prob[:h, :w] crops back. The comment calls it "a PRESENTATION crop — every downstream coordinate is computed against the original (h, w)." This is the difference between refusing a raster that is one pixel off and silently answering about a padded image.

_to_tensor normalises (H,W,3) uint8 → (1,3,H,W) float32 in [0,1], handling (H,W) by stacking three copies, a single-channel 3-D array by repeating, and more-than-3 channels by truncating to the first three.

§22.8 The confidence composition

CONFIDENCE_WEIGHTS = {
    "registration_quality":    0.50,
    "mean_change_probability": 0.30,
    "component_stability":     0.20,
}
STABILITY_HEADROOM = 0.5

Component	Derivation
registration_quality	_registration_factor(reg) — 0.0 when unusable, else reg.confidence_factor() clipped to [0,1]
mean_change_probability	Mean probability over the pixels inside the kept regions' bounding boxes
component_stability	clip((mean(in_region - threshold) / STABILITY_HEADROOM), 0, 1)
n_regions	Count of kept regions (recorded, not weighted)
shift_magnitude_px	The measured translation magnitude (recorded, not weighted)
trained_checkpoint	1.0 if a checkpoint is loaded, else 0.0
suppressed_by_registration	1.0 when suppressed
no_regions_detected	1.0 when no regions were kept

Two structural decisions are documented in the code.

First, the minimum. The composition is a weighted sum then a minimum against the registration factor:

"The minimum is the load-bearing part. A weighted sum alone would let a bright, stable-looking change map carry a mis-registered pair to a respectable score — and an unregistered pair produces edge-change everywhere, which is exactly the bright, stable output that would win the sum. Taking the minimum makes alignment a gate."

Second, the ordering of the flags. suppressed_by_registration is recorded before any early return:

"Recorded BEFORE any early return, so a pair that is BOTH mis-registered and untrained reports both facts. An earlier ordering returned on the untrained floor first and left this component unset, which made the trace say only half of what was wrong."

The three floors all resolve to 0.0:

Floor	Why it is a gap, not a weak signal
suppressed	"mis-registered pair; change along every edge is expected, so a change map says nothing"
untrained	"random weights; any region is noise wearing a box"
no regions	"nothing was detected, so there is nothing to be confident ABOUT"

STABILITY_HEADROOM = 0.5 is documented as "the mean headroom over the threshold, normalized", with the measured note: "Measured on the untrained path: headroom is near-zero, so stability is near-zero, which is the honest reading of a random model."

§22.9 _write_artifacts and F-16

The change map is written to artifact_dir / f"change_map_{stem}.tif" as (probabilities * 255) uint8, with the profile derived from T1 and count removed. When suppressed, crs, transform and bounds are removed from the profile and crs/transform set to None.

The function returns {"change_map": None} on every path — including success — because v1 has no artifact-serving endpoint:

"A URI is NOT fabricated in its place — artifact:// appears in the older API_CONTRACT section 2.4 example and no production file has ever emitted one, so inventing one here would trade a path disclosure for a broken promise."

Artifact rendering failures are swallowed with a warning, on the grounds that "Artifact rendering is a presentation concern. Failing the whole analysis because a raster could not be written would be wrong."

§22.10 Evidence emitted

Order	EvidenceType	Condition	Score	Payload highlights
1	CHANGE_MAP	always	None when suppressed, else the mean probability	threshold, n_components_raw, n_components_kept, total_change_pixels, suppressed_by_registration
2..n	BOUNDING_BOX	one per emitted region	region.mean_probability	rank, area_pixels, label: "change"
n+1	STATISTIC	always	None when suppressed, else reg.confidence_factor()	registration (full to_dict()), usable_for_spatial_claims, n_regions_emitted, n_regions_withheld
n+2	STATISTIC	only when suppressed and regions were withheld	None	spatial_claims_suppressed: True, n_withheld, reason

The last item's comment: "Deliberately a STATISTIC, not a BOUNDING_BOX: emitting the boxes would defeat the suppression. It is an audit entry describing what was discarded and why."

§22.11 The three answer templates

execute composes the answer string from the branch it took, and every number in it was computed:

Branch	Answer shape
Suppressed	"Change detection could not be trusted: the two acquisitions are not co-registered ({m}px offset, response {r}). {n} candidate change pixel(s) were found but are not attributable to real change."
No regions	"No change detected above threshold {t}. {n} raw change pixel(s) remained after filtering."
Regions present	"Detected change in {k} region(s), largest {n} px. {m} change pixel(s) total."

labels is [request.query] when the query is non-empty, else []. regions emits a schema Region for each ChangeRegion, "so a consumer reading either gets the same answer."

---

§23 The dataset and the split

§23.1 LEVIR-CD-256

training/change/dataset.py documents the frozen split in three places:

"keykeylv/levir-cd-256 ships list/train.txt (7120 lines), list/val.txt (1024) and list/test.txt (2048) — which is exactly the frozen change.levir_split: 7120/1024/2048 in configs/base.yaml."

Split	Tiles	Source
train	7,120	list/train.txt
val	1,024	list/val.txt
test	2,048	list/test.txt

The imagery is 1,024×1,024 PNG, 3-channel RGB. At change.tile_size = 256 a 1,024 px scene is 4×4 = 16 tiles.

§23.2 The leakage guard runs before the model is built

training/change/train.py's docstring states the problem and the ordering:

"LEVIR-CD ships neighbouring 256px crops of the same 1024px scene. A split by patch puts near-duplicate crops on both sides of the boundary, and validation then measures memorisation. assert_image_disjoint is called BEFORE the model is built, so a leaky split costs nothing and cannot be trained past. It raises rather than warns."

§23.3 One tile per item, and why

_fit_to_tile takes "a deterministic CENTRE CROP when the source is larger and zero-pads when it is smaller. Both T1 and T2 receive the identical crop/pad, so the padding contributes nothing to the difference features."

The docstring explains the accounting choice: "One tile per item keeps len(dataset) == len(items), which keeps the scene-disjointness accounting exact; expanding to a 4×4 tile grid is a throughput decision that belongs to the caller, not to the leakage guard."

§23.4 Why the forward pass is separate from the scoring

"evaluate used to forward and score in a single pass, discarding the probability maps as it went. Selecting a threshold requires the opposite shape: forward ONCE over a split, then score the SAME maps at many thresholds."

So collect_change_predictions does the forward pass once and both evaluate and sweep_thresholds consume its output through the one score_dataset call. "The single-shot number and every swept number therefore come off one code path; two implementations would be free to drift apart, and a sweep that disagreed with the shipped evaluation would be worse than no sweep."

---

§24 Training

training/change/train.py owns: ChangePairDataset, collate, change_loss (forwarded), collect_change_predictions, evaluate, sweep_thresholds, train_change_head, load_trained_change_model.

§24.1 The measured run

From artifacts/change/levir_change_v001/training_metadata.json and model_metadata.json:

Property	Value
device	cuda
duration_seconds	4,012.29 (≈ 67 minutes)
config_hash	78f1e3700da15aa1
created_at	2026-09-18T07:07:23.837669+00:00
best_val_iou	0.8232
first_val_iou	0.7336
Epochs recorded	20
Seconds/epoch	~192–258 (first epoch 257.82, then ~195)

§24.2 The validation trajectory

epoch	loss_total	loss_bce	loss_dice	lr	val_f1	val_iou
1	0.395229	0.07263	0.717829	9.938441702975688e-04	0.8463	0.7336
2	0.357495	0.046482	0.668507	9.755282581475768e-04	0.8540	0.7452
3	0.346795	0.039562	0.654029	9.455032620941839e-04	0.8560	0.7483
4	0.341699	0.036661	0.646737	9.045084971874737e-04	0.8742	0.7766
5	0.338594	0.035361	0.641827	8.535533905932737e-04	0.8762	0.7797
6	0.334499	0.033099	0.635899	7.938926261462366e-04	0.8843	0.7927
7	0.331346	0.031438	0.631255	7.269952498697733e-04	0.8817	0.7884
8	0.328748	0.029929	0.627567	6.545084971874737e-04	0.8845	0.7929
9	0.326422	0.028804	0.624040	5.782172325201155e-04	0.8784	0.7832
10	0.323244	0.026835	0.619652	5.000000000000000e-04	0.8860	0.7953
11	0.320457	0.025265	0.615650	4.217827674798847e-04	0.8964	0.8123
12	—	0.024490	—	—	—	—

The learning-rate column is a cosine schedule from 1e-3, and the two loss components fall together — the healthy pattern §20 and the Phase 8 record both describe.

§24.3 The validation split's composition

Property	Value
n	1,024 tiles
n_images_with_change	436
n_pixels	67,108,864
mean_change_fraction	0.042
threshold	0.5
seconds	13.18

mean_change_fraction = 0.042 is the concrete reason FINAL_BIAS_INIT = -2.0 and the Dice term exist (§18.5, §20.1).

§24.4 final_val — pooled and macro, both reported

Aggregate	IoU	F1	Precision	Recall	mIoU
pooled	0.8232	0.9030	0.9176	0.8890	0.9075
macro	0.7507	0.8317	0.8778	0.8122	0.8645

Pixel counts on validation: tp 2,503,593, tn 64,067,679, fp 224,917, fn 312,675.

Note the collision of numbers to avoid: validation pooled recall is 0.8890 and validation macro recall is 0.8122. The test pooled IoU is also 0.8122. Three different quantities share that value on this artifact, and a careless citation will conflate them.

---

§25 The measured result: artifacts/change/eval_test/eval_result.json

This is the VERIFIED headline. Both the pooled and the macro aggregate must travel together.

§25.1 The test protocol

Property	Value
n	2,048 tiles
n_images_with_change	935
threshold	0.5
tile_size	256
seconds	55.359
device	cuda
environment	Linux, torch 2.10.0+cu128
config_hash	78f1e3700da15aa1

§25.2 The result

Aggregate	IoU	F1	Precision	Recall	mIoU
pooled	0.8122	0.8964	0.9195	0.8745	0.9007
macro	0.7180	0.7962	—	—	0.8457

§25.3 The checkpoint_embedded_config

The eval result records the architecture the checkpoint carries, so a re-run can prove it used the same model:

{
  "encoder": "resnet18",
  "encoder_channels": [64, 128, 256, 512],
  "frozen_encoder": false,
  "pretrained_used": true,
  "sa_mode": "PAM",
  "width": 128,
  "attention_budget_bytes": 268435456
}

attention_budget_bytes = 268435456 = 256 MB, matching DEFAULT_ATTENTION_BUDGET_BYTES (§19.2).

§25.4 A naming discrepancy that must be recorded, not smoothed

The release style guide's "facts that must never be stated wrongly" row for change reads:

"pooled IoU 0.8122 / macro IoU 0.8457 / pooled F1 0.8964"

The artifact's own keys say:

Artifact key	Value	Artifact's own name for it
pooled.iou	0.8122	pooled IoU
pooled.f1	0.8964	pooled F1
macro.iou	0.7180	macro IoU
macro.miou	0.8457	macro mIoU

So the style guide's shorthand "macro IoU 0.8457" corresponds to the artifact's macro.miou, not its macro.iou (which is 0.7180). Both numbers are real; they measure different things. This chapter states both, and the discrepancy in naming is recorded here rather than resolved by choosing one. The unambiguous form of the headline is: pooled IoU 0.8122, pooled F1 0.8964, macro IoU 0.7180, macro mIoU 0.8457, on 2,048 LEVIR-CD-256 test tiles at threshold 0.5.

§25.5 What the result does not establish

From docs/PHASE9_GPU_RUN_RESULTS.md:

#	Limitation	Recorded detail
1	Not comparable to published LEVIR-CD numbers without care	"This is LEVIR-CD-256, the 256-pixel-tiled variant… BIT / ChangeFormer figures are on the original 1024px LEVIR-CD with different [protocol]"
2	The split firewall held — no test data was seen in training	"The run record contains train_scenes: 445 and val_scenes: 64 and no test entry at all"
3	The validation split did not function as a selection set	"…epoch beat the first. The validation split did not function as a selection set for [selection]"
4	The test split was not re-scored	"The script refuses any --split other than [test] … verified by passing bogus paths alongside --split test"
5	The threshold was not swept on test	scripts/sweep_change_threshold.py; its test_split_touched field is false

Item 5 is the same firewall discipline as the router's threshold sweep (04-router.md §33): the sweep reads validation, and the test split is not touched.

---

§26 Change: limitations

#	Limitation	Status
1	The trained checkpoint is not wired into serving by default — the specialist runs untrained unless the registry override injects the checkpoint	Deliberate. §22.5 gives the config-hash reason.
2	The test number is LEVIR-CD-256, a 256-px-tiled variant, and is not directly comparable to published 1024-px LEVIR-CD figures	OPEN — documented, not resolved
3	Registration quality is a translation model; rotation and warp are not recovered	Structural. §21.3.
4	Attention is skipped at layer 1 (537 MB > 256 MB budget)	A recorded deviation from literal STANet, not a silent substitution
5	sa_mode="BAM" is declared in config and not implemented	Raises visibly rather than aliasing PAM
6	The macro/pooled naming collision (§25.4)	Recorded. Four distinct quantities share two similar names.
7	The validation split did not function as a selection set	Measured; the checkpoint was selected by best_val_iou regardless
8	change_map is null on every path because v1 has no artifact-serving endpoint	By design (F-16)
9	Validation pooled IoU (0.8232) exceeds test pooled IoU (0.8122)	Measured; both reported

---

Part D — change_vqa: the closed-vocabulary CDVQA head

change_vqa is the specialist that answers a question about what changed between two images. It is the only specialist whose answer space is closed and enumerable, and that fact determines its entire architecture. This part documents the vocabulary (§27), the two-stage head (§28), the numerical defect that killed the first real run (§29), the frozen feature contract (§30), training and the run record (§31), the specialist (§32), the measured result across two test sets (§33), and the limitations (§34).

§27 The vocabulary and the ontology: training/change_vqa/vocab.py

349 lines. The module opens with the measurement that made the whole design possible.

§27.1 The measured dataset

Measured on the shipped dataset (2026-09-21):

Split	Scenes	Questions	Distinct answers
Train	1,600	65,967	19
Val	400	16,441	19
Test	968	39,686	19
Test2	968	31,036	19

And the conclusion the module draws from it:

"Every answer is a member of one of eight per-type frozen vocabularies. That fact is the single most important design input for R-02: it means the reasoning head can be a 19-way classifier conditioned on the question, and does not need to be a language model."

§27.2 The 19 answers are derived, never typed out

ANSWER_VOCABULARY = tuple(sorted({a for vocab in ANSWER_VOCABULARIES.values() for a in vocab}))

The union is 2 (yes/no) + 11 (ratio bins) + 6 (change classes) = 19, and the module explains why it is derived from a frozen constant rather than from the observed split:

"It is deliberately NOT derived from the answers observed in a split. A vocabulary built from Train would silently shrink if a split ever lacked a rare answer, and the index of every other answer would shift with it — a silent label corruption that no shape check would catch."

validate_vocabulary() asserts the derivation against the frozen ontology and returns a report rather than only raising, "so a caller can record the numbers in an artifact instead of re-deriving them."

§27.3 The six change classes, in frozen channel order

CHANGE_CLASS_ORDER = ("NVG_surface", "buildings", "low_vegetation",
                      "trees", "water", "playgrounds")

The comment is load-bearing: "This order is the channel order of the class-wise change estimator's output, so it must never be re-sorted."

§27.4 The ratio bins, and why a string sort would be a bug

Vocabulary	Count	Members
RATIO_BINS (change_ratio)	11	0, 0_to_10, 10_to_20, …, 90_to_100
RATIO_TYPE_BINS (change_ratio_types)	9	0, 0_to_10, …, 70_to_80

"Kept as explicit tuples so a bin index is never inferred from a string sort ('10_to_20' < '0_to_10' lexicographically, which would be a silent off-by-one across eight bins)."

validate_vocabulary enforces both the subset relation (the 9-bin vocabulary must be a subset of the 11-bin one) and numeric ordering. The 0 bin is real — "a rare but measured exact-zero answer; dropping it would silently mis-count the vocabulary."

The per-split drift is recorded rather than crashed on: Val omits 60_to_70 and 70_to_80; Test and Test2 omit 70_to_80.

§27.5 The eight question types, plus an explicit unknown slot

#	QUESTION_TYPE_ORDER	Class-scoped?	Answers
0	change_or_not	yes	yes/no
1	change_ratio	no	11 bins
2	change_ratio_types	yes	9 bins
3	change_to_what	yes	6 classes
4	increase_or_not	yes	yes/no
5	decrease_or_not	yes	yes/no
6	largest_change	no	6 classes
7	smallest_change	no	6 classes

Plus UNKNOWN_QUESTION_TYPE = "unknown" at index 8, giving QUESTION_TYPE_SLOTS of 9 and N_QUESTION_TYPE_SLOTS = 9.

"Giving the unresolvable case its own embedding slot is more honest than forcing it into one of the eight and letting a wrong type mask a correct answer."

§27.6 The type resolver, and why its rule order is load-bearing

_TYPE_RULES = (
    ("largest_change",    ("largest",)),
    ("smallest_change",   ("smallest",)),
    ("change_to_what",    ("changed to", "change to", "change into")),
    ("increase_or_not",   ("increase",)),
    ("decrease_or_not",   ("decrease",)),
    ("change_ratio_types",("change percentage", "change ratio", "how much area")),
    ("change_ratio",      ("percentage", "ratio", "percent")),
    ("change_or_not",     ("changed", "change")),
)

"Order is load-bearing: 'What is the largest change ... ?' contains the substring 'change', so a change_or_not rule tested first would swallow every largest_change question. The list is ordered most-specific first and is the ONLY place this decision is made."

resolve_question_type(question) returns (qtype, resolved). resolved is False when no rule fired, and the caller must use UNKNOWN_QUESTION_TYPE rather than guessing. The docstring states the separation of concerns: "This exists for the FREE-FORM path only. The benchmark path reads the gold type from the annotation, and evaluation reports the two separately so a resolver error can never be mistaken for a model error."

resolve_change_class scans longest surface form first, "so 'low vegetation' is never matched as 'vegetation' by a shorter, greedier alternative." resolve_temporal_reference tests post markers first, "because 'post-change' contains 'change' and a naive pre/post scan would be order-dependent in a way that is not visible in the code." A question naming both returns "unspecified" rather than silently preferring one.

§27.7 The legal-answer mask

def legal_answer_mask(qtype) -> tuple[bool, ...] | None:
    legal = LEGAL_ANSWERS.get(qtype)
    if legal is None:
        return None            # "do not mask"
    return tuple(answer in legal for answer in ANSWER_VOCABULARY)

None means do not mask, and the reason is precise: "Returning an all-False mask for an unknown type would make every answer illegal and collapse the argmax to index 0 — a silent, confident wrong answer."

Two more decisions in the same area:

• Training never masks. "Training never masks, because masking during training would hide a mis-resolved type behind a plausible-looking loss."
• The mask is off by default at inference. predict_answers(apply_type_mask=False) by default, "so the caller can report masked and unmasked numbers separately instead of quietly reporting the better one."

§27.8 ratio_bin_for and the 85% figure

ratio_bin_for(fraction, *, per_class=False) maps a change fraction in [0,1] onto the bin vocabulary. Bins are half-open [lo, hi) with the exact-zero case as its own bin. The measured accuracy:

"Measured against 40 real change_ratio rows computed from label1/label2, this convention reproduces the gold bin 34/40 = 85% of the time; the residual is annotation noise between the maps and the annotator, not a binning error."

§27.9 Surface forms and the temporal markers

CLASS_SURFACE_FORMS maps each machine name to the prose the dataset actually uses — because "the dataset never uses the machine name ('NVG_surface') in prose":

Machine name	Surface forms
NVG_surface	non-vegetated ground surface, non vegetated ground surface
buildings	buildings, building
low_vegetation	low vegetation
trees	trees, tree
water	water
playgrounds	playgrounds, playground

Marker set	Members
_PRE_MARKERS (6)	pre-change, pre-event, first image, before image, pre change, pre event
_POST_MARKERS (6)	post-change, post-event, second image, after image, post change, post event

Temporal reference is part of the question. The module's own section explains why:

"Measured on real rows, four of the eight types name WHICH acquisition they mean… That is information the model cannot recover from the change features alone — the same scene has a different correct answer for the pre-image and the post-image."

TEMPORAL_REFERENCE_ORDER = ("unspecified", "pre", "post"), giving 3 slots.

§27.10 The template table: training/change_vqa/prompts.py

TEMPLATES maps each of the eight types to a canonical surface form, "checked against real dataset rows":

Type	Template
change_or_not	"Have the areas of {class} changed?"
change_ratio	"What is the percentage of changed regions?"
change_ratio_types	"What is the change percentage of {class} in the pre-change image?"
change_to_what	"What have the areas of {class} in the pre-change image mainly changed to?"
increase_or_not	"Did the areas of {class} increase?"
decrease_or_not	"Did the areas of {class} decrease?"
largest_change	"What is the largest change?"
smallest_change	"What type of change is the smallest?"

CLASS_SCOPED_TYPES (5) and GLOBAL_TYPES (3) partition the eight, and validate_templates() asserts the partition rather than trusting it:

class_scoped = tuple(t for t in QUESTION_TYPE_ORDER if "{class}" in TEMPLATES[t])
assert set(class_scoped) == set(CLASS_SCOPED_TYPES), ...

DEFAULT_CLASS = "buildings", chosen because it is "the most common class-scoped subject in Train (4,416 rows) and, more importantly, it is a real class rather than a placeholder — a placeholder would generate queries the resolver cannot map." canonical_query(..., fallback_to_default=False) gives the strict mode for callers that must not invent a subject.

---

§28 The two-stage head: training/change_vqa/model.py

679 lines. The architecture is constrained by four measured facts, and the module lists them before designing anything.

§28.1 The constraints

Fact	Consequence
The answer space is closed with 19 members across 8 types	A generative decoder is ruled out; 19-way classification is strictly easier and exactly matches the metric
Answers are short (yes, no, buildings, 10_to_20), never sentences	No sequence decoding needed
label1/label2 ship for all 2,968 scenes	Class-wise change is computable supervision, not a guessed target
The budget is ≤ 3 h on T4×2	Nothing large can be trained

§28.2 The two stages

STAGE 1  change representation -> class-wise change estimate
         "how much did each of the six classes change, and in which direction?"
         (13 outputs, directly supervised by label1/label2)

STAGE 2  class-wise estimate + question -> answer
         "given what changed and what was asked, which of the 19 answers?"

The crucial structural point, in the module's words:

"Stage 1 is not decoration and it is not an auxiliary loss bolted on. Its outputs are CONCATENATED into stage 2's input, so the answer is computed FROM the change estimate — the same way a person answers 'what is the largest change?' by first working out the per-class changes and then picking the largest. The gradient flows through the estimate, so stage 1 is trained by the answer loss as well as by its own."

And the reason it exists at all:

"This is why the head can answer largest_change and smallest_change at all. A single pooled vector cannot support 'which class changed most' — it has no per-class structure to compare. The estimator supplies exactly that structure."

Two-stage, not two-model. "There is one trainable module and one loss."

§28.3 The module-level constants

Constant	Value
ARCHITECTURE_VERSION	"change_vqa_head_v1"
DEFAULT_TRUNK_DIM	512
DEFAULT_TEXT_DIM	256
DEFAULT_DROPOUT	0.10
DEFAULT_QTYPE_EMBED_DIM	32
DEFAULT_TEMPORAL_EMBED_DIM	8
N_ESTIMATOR_OUTPUTS	2 * 6 + 1 = 13

ARCHITECTURE_VERSION is checked on load, so "a checkpoint written under an older definition fails to load rather than silently re-interpreting its weights."

§28.4 The layer-by-layer architecture

Block	Layers	Shapes
estimator (stage 1)	Linear(change_feature_dim, 256) → GELU → Linear(256, 13)	1045 → 256 → 13
change_trunk	Linear(change_feature_dim, trunk_dim) → LayerNorm → GELU → Dropout	1045 → 512
qtype_embed	Embedding(9, 32)	9 slots × 32
temporal_embed	Embedding(3, 8)	3 slots × 8
question_trunk	Linear(text_feature_dim + 32 + 8, text_dim) → LayerNorm → GELU	296 → 256
answer_head (stage 2)	Linear(781, 512) → GELU → Dropout → Linear(512, 256) → GELU → Linear(256, 19)	781 → 512 → 256 → 19

fused = trunk_dim + text_dim + N_ESTIMATOR_OUTPUTS = 512 + 256 + 13 = 781.

§28.5 The estimator's output decomposition

estimate   = self.estimator(change_features)
mag_raw    = estimate[:, :6]        # class magnitudes
delta_raw  = estimate[:, 6:12]      # signed class deltas
total_raw  = estimate[:, 12]        # global changed fraction

class_mag     = torch.sigmoid(mag_raw)     # (B, 6) in [0, 1]
class_delta   = torch.tanh(delta_raw)      # (B, 6) in [-1, 1]
total_changed = torch.sigmoid(total_raw)   # (B,)   in [0, 1]

The activation choices carry meaning: a magnitude is non-negative (sigmoid), a delta is signed (tanh), and a total fraction is non-negative (sigmoid).

§28.6 The question side

question = self.question_trunk(
    torch.cat([text_features, self.qtype_embed(qtype_index),
               self.temporal_embed(temporal_index)], dim=1)
)
fused  = torch.cat([change, question, estimate], dim=1)
logits = self.answer_head(fused)

The question enters as three things: the frozen MiniLM text embedding, a learned type embedding, and a learned temporal-reference embedding. The estimator output enters the fusion as well as being supervised, which is what makes stage 1 a genuine bottleneck rather than a side branch.

§28.7 _init_weights

for module in self.modules():
    if isinstance(module, nn.Linear):
        nn.init.xavier_uniform_(module.weight)
        if module.bias is not None:
            nn.init.zeros_(module.bias)
final = self.answer_head[-1]
nn.init.normal_(final.weight, std=0.01)
final.bias.fill_(0.0)

The comment on the final layer states the reason for the small init and the zero bias: "The class distribution is heavily skewed (yes+no are 58% of Train), so a zero-biased head would begin by predicting the majority class and take several epochs to leave it; the estimator's bias is left at zero because its targets are already balanced in [0, 1]."

That 58% figure is checkable against the measured answer counts (§31.3): yes 22,396 + no 25,612 = 48,008 of 82,408 = 58.3%.

§28.8 ChangeVQAOutput and the logits fields

ChangeVQAOutput carries answer_logits, class_mag, class_delta, total_changed, legal_mask_applied, and two fields that are not part of the published contract:

Field	Purpose
mag_logits	The pre-sigmoid logits behind class_mag
total_logits	The pre-sigmoid logits behind total_changed

The docstring is explicit about why they exist and why they are not published:

"These are NOT part of the published contract — to_evidence() emits the probabilities, predict_answers() returns them, and serving consumes them, so nothing downstream reads these two fields. They exist for exactly one reason: the LOSS must be computed from logits, because BCE(sigmoid(z), t) is numerically unusable at saturation."

§29 is the reason.

to_evidence(index=0) returns the class-wise estimate as an evidence payload with 6-dp rounding "because a longer float would suggest a precision the estimator does not have." The .detach() calls are explained: a caller may build evidence from a training forward pass, and float() on a grad-carrying tensor emits a UserWarning — "a warning that trains a reader to ignore warnings."

§28.9 _apply_legal_mask

usable = mask.any(dim=1)
if not bool(usable.any()):
    return logits, False
masked = logits.masked_fill(~mask & usable.unsqueeze(1), float("-inf"))
masked = torch.where(usable.unsqueeze(1), masked, logits)

A row whose every answer is illegal would argmax to index 0 — "a confident wrong answer with no trace of why." Such a row is left unmasked, "because an unmasked answer is a legitimate answer and a masked empty row is a silent corruption." A shape mismatch between mask and logits raises SpecialistError.

§28.10 The loss

DEFAULT_LOSS_WEIGHTS = {
    "answer":        1.0,
    "magnitude":     1.0,
    "delta":         1.0,
    "total_changed": 0.5,
}

answer    = F.cross_entropy(output.answer_logits, answer_index)
magnitude = binary_cross_entropy_from_logits(output.mag_logits, class_mag)
delta     = F.mse_loss(output.class_delta, class_delta)
total     = binary_cross_entropy_from_logits(output.total_logits, total_changed)
combined  = w["answer"]*answer + w["magnitude"]*magnitude + w["delta"]*delta + w["total_changed"]*total

Design decision	Reason
The answer term dominates	"the answer is the deliverable"
Estimator terms are weighted 1.0	"strong enough to shape a usable per-class representation (weight ~1.0 against a term whose natural scale is ~0.2) and small enough not to pull the trunk away from the answer objective"
The two BCE terms use the logits form	§29
cross_entropy and mse_loss are called directly	Both are autocast-safe

The targets come from label1/label2, so "they are exact — there is no pseudo-labelling anywhere in this loss."

§28.11 predict_answers — the serving path

predict_answers(model, *, change_features, text_features, qtype_indices,
                temporal_indices, qtypes=None, apply_type_mask=False, device="cpu")

model.eval() + torch.no_grad() + argmax. It returns the full (B, 19) softmax — not just the argmax — and the docstring gives the reason: "the full (B, 19) softmax, so top-k metrics are computed rather than skipped."

Returned key	Content
answer_index	(B,) argmax indices
answer	(B,) answer strings
confidence	(B,) top-1 probability
margin	(B,) top1 − top2
probabilities	(B, 19) full softmax
class_mag, class_delta, total_changed	The stage-1 estimator outputs
legal_mask_applied	Whether the mask fired

---

§29 The saturated-BCE defect, and why the logits form is mandatory

This is the most instructive defect in the project, because the failure was silent, the mechanism was non-obvious, and the fix changes nothing about what the model emits.

§29.1 The measurement

Drive the estimator to a saturated logit and compare the two forms:

Case	BCE(sigmoid(z), t)	BCEWithLogits(z, t)
z = -30, t = 1 backward	−0.0936 (should be −1.0)	−1.0
z = +30, t = 0 forward	65.0 (true value 30.0)	exact

Two separate defects, both caused by taking the log of a probability.

§29.2 Defect 1 — the backward divides by p(1−p)

d/dp = (p − t) / (p * (1 − p)). At p = 1.0 exactly that is −1 / 0, which PyTorch clamps to a finite −9.99999996e11.

"Because the result is finite, GradScaler never flags it, never skips the step, and it reaches the optimizer intact. AdamW then squares it into the second-moment estimate: v ~ (1e12)² = 1e24, which suppresses every subsequent update to that parameter."

That is the mechanism behind the observed epoch-1-to-epoch-2 collapse: val_acc 0.4388 → 0.2656 with mean confidence 0.9996. The confidence tells the story — the model became more certain while becoming less correct, which is exactly the signature of a poisoned optimizer state.

§29.3 Defect 2 — the forward is wrong, not merely unstable

PyTorch clamps each element at 100, so a saturated element silently reports 65.0 where the true value is 30.0. "The loss stops measuring the quantity it claims to measure."

§29.4 Saturation is not an AMP problem

"sigmoid(17.0) is exactly 1.0 in plain fp32. fp16 reaches it sooner (|z| ≥ 18 under autocast), but the fp32 path saturates as well, so --no-amp would only have moved the failure."

This is why the fix is not "disable AMP". The numerical form was wrong regardless of precision.

§29.5 Why BCEWithLogits cannot saturate

"BCEWithLogits uses the log-sum-exp identity: the forward is exact for any finite logit, and the backward is sigmoid(z) - t, bounded in [−1, 1]. There is no division by a probability anywhere in it, so it cannot saturate."

§29.6 The fix changes nothing observable

"Using them changes NOTHING about what the model emits: class_mag is still sigmoid(mag_raw), and to_evidence(), predict_answers() and serving are untouched. Only the internal loss arithmetic changes, from an explosive-and-wrong form to the exact one."

§29.7 The fallback, and its two constraints

binary_cross_entropy_probabilities is kept "for a caller that holds only probabilities, and for a ChangeVQAOutput built by hand without logits. The training path does not use it." It has to satisfy two constraints:

Constraint	Detail
Must run with autocast disabled	"aten::binary_cross_entropy is registered as an outright ERROR under CUDA autocast, and that registration is unconditional — it fires whatever the operand dtypes are, so casting to fp32 is necessary but not sufficient. This was the very first Kaggle failure: RuntimeError: ... are unsafe to autocast."
Must keep its operand away from 0 and 1	prediction.float().clamp(min=eps, max=1.0 - eps) bounds the derivative at about 1/eps ~ 8.4e6 instead of 1e12

The clamp is a no-op for any probability inside (eps, 1−eps), "so it changes nothing in the interior — it only refuses to divide by zero."

§29.8 The lesson for the release

The defect is recorded in docs/RESEARCH_NOTES.md §1 as one of the project's findings. It is worth noting why it survived until a real run: the shapes were all correct, the loss decreased on the first epoch, and the only symptom was a number that got worse while its confidence went up. A green unit suite cannot catch this. The evidence that it was fixed is the run record's epoch history (§31.4), where val_accuracy rises monotonically to epoch 8 and then plateaus rather than collapsing.

---

§30 The frozen feature contract: training/change_vqa/features.py

642 lines. The module's first section explains the budget decision.

§30.1 Why frozen features

"Plan section 46 budgets CDVQA at ≤ 3 h on T4×2. A head trained end to end through the STANet encoder would spend that budget re-learning a change representation the project already has a trained checkpoint for (artifacts/change/levir_change_v001/head.pt, test pooled IoU 0.8122). The plan also forbids retraining STANet unless evidence demands it."

Measured effect: "the trainable parameter count falls from ~15.8 M to ~1.5 M and the training loop becomes a few minutes on a T4 rather than hours."

§30.2 The feature is three things, not one

CHANGE_FEATURE_DIM = 1045, and each part answers a different question the ontology asks:

Part	Dim	Derivation	Answers
level_pooled	1024	4 levels × 128 ch × {mean, max}	"what does the change look like locally?"
change_stats	5	mean, std, frac>0.3, frac>0.5, frac>0.7 of the change probability map	"how much of the scene changed?" → change_or_not, change_ratio, change_ratio_types
change_grid	16	adaptive 4×4 pool of the same map	"WHERE did it change?" → largest_change, smallest_change

Total: 1024 + 5 + 16 = 1045.

"The spatial parts are not decoration. Without change_grid the head would see a scene-global average and could not distinguish 'buildings changed in one corner' from 'buildings changed everywhere', which is precisely the difference between largest_change and smallest_change."

§30.3 The constants are derived, never typed

N_LEVELS = 4
LEVEL_CHANNELS = 128
LEVEL_POOLED_DIM  = N_LEVELS * LEVEL_CHANNELS * 2        # 1024
CHANGE_STATS_DIM  = 2 + len(CHANGE_STAT_THRESHOLDS)      # 5
CHANGE_GRID_DIM   = CHANGE_GRID * CHANGE_GRID            # 16
CHANGE_FEATURE_DIM = LEVEL_POOLED_DIM + CHANGE_STATS_DIM + CHANGE_GRID_DIM   # 1045

"Derived, never typed: a literal here would drift silently from the pooling code below and produce a shape error three files away."

extract re-checks vector_np.shape[0] != CHANGE_FEATURE_DIM at runtime and raises FeatureExtractionError naming the drift.

§30.4 The text side

Constant	Value
TEXT_ENCODER_NAME	"sentence-transformers/all-MiniLM-L6-v2"
TEXT_FEATURE_DIM	384

"MiniLM is already a project dependency (the intent router uses it) and is present in the local HF cache, so reusing it costs no new download and no new licence surface."

TextFeatureExtractor.encode uses normalize_embeddings=True, batch_size=256, and checks the output width against TEXT_FEATURE_DIM.

Note the identity chain this creates. The same MiniLM revision (1110a243fdf4, §2 of 04-router.md) serves the router and the change-VQA question encoder. The router's finding F4-1 (max_length 128 against a 256 tokenizer ceiling) applies to the router's encoder configuration; the change-VQA path uses SentenceTransformer.encode with its own defaults. Whether the two paths use the same effective truncation length is UNKNOWN — not established from the available evidence — the change-VQA path does not set max_seq_length explicitly in features.py, and the router's setting is applied to its own encoder instance.

§30.5 Equivalence is proven, not assumed

ChangeFeatureExtractor.extract re-runs the detector's submodules to capture the intermediate fused levels that STANetStyleChangeDetector.forward does not return. That is a second implementation of one forward pass, and the module names the hazard:

"That is a second implementation of one forward pass, so it is a drift hazard — and it is closed by a test that asserts the probability map produced here is bit-identical to STANetStyleChangeDetector.forward(...).probabilities (tests/unit/test_change_vqa_features.py). The frozen module is not modified to expose the intermediates, because not touching it is the stronger guarantee."

§30.6 The extraction itself

f1 = model.encoder(t1); f2 = model.encoder(t2)
for level, (a, b) in enumerate(zip(f1, f2)):
    fused = model.fuse[level](a, b)
    fused, _ran, _needed = model.attention[level](fused, model.attention_budget_bytes)
    levels.append(fused)
x = levels[3]
x = model.dec3(x, levels[2]); x = model.dec2(x, levels[1]); x = model.dec1(x, levels[0])
x = model.final_up(x)
probability = torch.sigmoid(model.head(x))

Note that the attention budget is honoured exactly as the model's own forward does (§19.3), so the frozen path and the training path take the same attention decisions.

Pooling:

for level_features in levels:
    pooled.append(level_features.mean(dim=(2, 3)))    # 128 per level
    pooled.append(level_features.amax(dim=(2, 3)))    # 128 per level
level_pooled = torch.cat(pooled, dim=1).reshape(-1)   # 1024

Stats: flat.mean(), flat.std(unbiased=False), and (flat > t).float().mean() for each of (0.3, 0.5, 0.7).

Grid: F.adaptive_avg_pool2d(probability, (4, 4)).reshape(-1) → 16.

§30.7 The facts dict

extract returns (vector, facts) where facts carries the interpretable intermediates:

Key	Content
change_probability_mean	Mean of the probability map
change_probability_std	Std of the probability map
change_fraction_gt_0_5	Fraction of pixels above 0.5
change_probability_max	Peak probability
change_grid	The 16 pooled values, flattened
image_size	The working resolution
trained_detector	Whether the extractor carries trained weights

The reason facts exists: "so a caller can emit them as evidence without recomputing anything."

§30.8 Working resolution

DEFAULT_IMAGE_SIZE = 256, with the reason:

"256 is the change model's OWN training resolution (configs/base.yaml: change.tile_size: 256; LEVIR-CD patches are 256×256). Feeding the native 512 would push the frozen encoder outside the distribution it was trained on, so 256 is the faithful default and 512 is offered as an explicit, recorded alternative."

§30.9 Spec hashes: two, not one

feature_spec_hash(image_size, *, extractor)   -> "c801326f85a185f8"   (measured config)
text_spec_hash(*, encoder, revision=None)     -> "d2801ea1a314354a"   (measured config)

feature_spec_hash includes the extractor string, which is "stanet:trained" or "stanet:untrained" — so the spec hash already encodes trained-versus-untrained state, and comparing it covers the detector-state mismatch (§32.3).

text_spec_hash is deliberately separate:

"A separate hash from feature_spec_hash on purpose: the change cache and the text cache are written by different steps and can legitimately be rebuilt independently. One combined hash would force a full re-extraction of both whenever either changed, and — worse — would let a stale text cache pass a check it should fail."

§30.10 The caches refuse a mismatch

ChangeFeatureCache and TextFeatureCache both carry their spec hash with the tensors, and both read methods accept expect_spec_hash and raise FeatureExtractionError on disagreement:

"A cache built at a different resolution or with a different extractor is detected on read and refused, because a silently-mismatched cache produces a model that trains on one representation and is served another — a failure that looks like a modelling problem and is not one."

extract_change_features skips an unreadable scene and reports it through on_progress and the returned failures list, "never silently dropped: a scene missing from the cache is a training sample the model never sees, and the caller must be able to count how many that was."

---

§31 Training and the run record

training/change_vqa/train.py is 1,337 lines. The CLI defaults are module constants:

Constant	Value
DEFAULT_TIME_LIMIT_SECONDS	3 * 3600 = 10,800
DEFAULT_EPOCHS	40
DEFAULT_BATCH_SIZE	128
DEFAULT_LR	1e-3
DEFAULT_WEIGHT_DECAY	1e-4
DEFAULT_WARMUP_RATIO	0.05
DEFAULT_GRAD_CLIP	1.0
DEFAULT_PATIENCE	6
DEFAULT_MIN_DELTA	1e-4

§31.1 The guide's pinned invocation

docs/R02_KAGGLE_TRAINING_GUIDE.md records the intended configuration and the hardware:

Setting	Value
Hardware	GPU T4 ×2 (plan's hardware row for change-VQA is T4×2)
Internet	On — the MiniLM question encoder must be fetched
Invocation	epochs=40, batch_size=128, seed=42, patience=6, time_limit=10800s
AMP	torch.float16 with a GradScaler on Turing; chosen from compute capability, "never from the GPU name"

The guide's acceptance criteria for the run record:

Field	Required
epochs completed	≥ 1
stop reason	epochs_exhausted or early_stopping — not time_limit_reached

And the two failure readings: time_limit_reached with 0 epochs means "the budget is shorter than one epoch"; with epochs > 0 it means "the run stopped early and did not converge… a truncated run is not the result."

§31.2 The actual run's optimization block

From artifacts/change_vqa/run/run_record.json → optimization:

Property	Value
optimizer	AdamW
scheduler	cosine_with_warmup
lr	0.001
weight_decay	0.0001
batch_size	256 (the guide's default is 128; the run used 256)
grad_clip	1.0
epochs_requested	40
epochs_completed	14
total_steps_planned	10,320
warmup_steps	516
amp_enabled	true
amp_dtype	torch.float16
amp_reason	"cuda autocast (float16) with GradScaler"
grad_scaler	true
native_bfloat16	false
loss_weights	{answer: 1.0, delta: 1.0, magnitude: 1.0, total_changed: 0.5}

§31.3 The dataset block

Property	Value
dataset_id	cdvqa
preprocessing_version	change_vqa_preproc_v1
n_records	82,408
n_unique_scenes	2,000
n_unique_pairs	2,000
n_distinct_answers	19
answers_outside_frozen_vocabulary	[]
answers_illegal_for_their_type	0
is_clean	true
inconsistent_examples	[]
leakage	[]
`pairwise_scene_overlap.Train	Val`
balancing.enabled	false
selection_drops (train and val, both feature kinds)	all 0

Measured answer counts across the 82,408 records:

Answer	Count
no	25,612
yes	22,396
NVG_surface	6,007
0	5,783
0_to_10	5,652
buildings	5,582
low_vegetation	3,504
trees	2,107
10_to_20	1,504
water	849
80_to_90	661
20_to_30	642
90_to_100	570
70_to_80	375
30_to_40	344
60_to_70	240
40_to_50	203
playgrounds	202
50_to_60	175

Measured question-type counts (the record's list is longer than this excerpt; the first five are):

Question type	Count
change_or_not	28,799
change_ratio_types	12,149
decrease_or_not	9,574
change_to_what	6,251
change_ratio	4,000

The skew is the reason for the init in §28.7: yes + no = 48,008 of 82,408 = 58.3%, and the two largest single answers are both yes/no. The remaining question-type counts are present in run_record.json but were not enumerated for this chapter — UNKNOWN — not established from the available evidence for the full list.

§31.4 The per-epoch history

14 epochs, 258 batches each, ~3.9–4.9 s per epoch:

epoch	train_loss	answer_ce	class_magnitude_bce	class_delta_mse	total_changed_bce	val_accuracy	val_macro_f1	val_mean_confidence
1	2.079901	1.281604	0.349198	0.197054	0.504090	0.657320	0.250128	0.648931
2	1.326787	0.773919	0.210475	0.101778	0.481230	0.684569	0.294345	0.676931
3	1.306581	0.743776	0.208142	0.116304	0.476719	0.678973	0.320151	0.666959
8	1.175368	0.701174	0.201106	0.041983	0.462210	0.700018	0.377504	0.702580

Epoch 8 is the selected epoch, on Val answer accuracy = 0.700018 (selection.best_epoch = 8, selection.best_accuracy = 0.700018, selection.metric = "Val answer accuracy", selection.stop_reason = "early_stopping", patience = 6, min_delta = 0.0001).

The contrast with §29.2 is the point: the saturated-BCE run collapsed from val_acc 0.4388 to 0.2656 with confidence 0.9996. This run rises to 0.700018 at epoch 8 with confidence 0.7026 and then stops on patience. The fix is visible in the history, not asserted by it.

§31.5 Budget

Property	Value
budget.elapsed_seconds	64.278
budget.time_limit_seconds	10,800.0
budget.clock	time.monotonic

64 seconds against a 10,800-second budget. The head is small, the features are frozen and cached, and the entire training is a few minutes of T4 time — which is exactly the outcome §30.1 predicted when it chose frozen features.

§31.6 The recorded state

run_record.json → state is TRAINED_UNVERIFIED, with the note:

"training produces an artifact, not a verified capability. R-02 reaches VERIFIED only after the returned checkpoint has been evaluated on the held-out split."

model_metadata.json records state: TRAINED_UNVERIFIED, test_splits_used: false, detector_trained: true, epoch: 8, confidence_method: "uncalibrated", and val_answer_accuracy: 0.700018.

---

§32 The specialist: specialists/change/vqa_specialist.py

616 lines.

§32.1 Identity

Attribute	Value
name	"change_vqa"
version	"0.1.0"
capabilities	("change_vqa",)
LOW_CONFIDENCE_THRESHOLD	0.40
apply_type_mask (serving default)	True

LOW_CONFIDENCE_THRESHOLD = 0.40 is described as "a reporting threshold, not a calibration."

§32.2 What it answers

"It answers the eight CDVQA question types (change_or_not, change_ratio, change_ratio_types, change_to_what, increase_or_not, decrease_or_not, largest_change, smallest_change) over a closed 19-answer space."

TEMPORAL_ORDER_NOTE records the temporal convention and, importantly, its evidential strength:

"T1=pre, T2=post. label1=pre/label2=post proven (agreement 1.0000 over 2,968 scenes); im1=pre/im2=post supported statistically, not proven."

That distinction travels in the evidence payload "so a reader can see which leg the result rests on."

§32.3 The three refusal conditions

unavailable_reason() returns None when servable, otherwise a string naming what is missing. Three conditions, checked in order:

Condition	Message fragment
No trained head	"a trained change-VQA head (expected at {path})"
No feature extractor	"a change feature extractor"
No text encoder	"a question text encoder"
Feature-spec mismatch	the mismatch string from feature_spec_mismatch()

feature_spec_mismatch() is worth its own note because it is a refusal, not a warning, and the docstring explains the measurement that justified it:

"Measured on this repository: configs/base.yaml's change: section carries no checkpoint_path key, so the registry builds the change feature extractor with checkpoint_path=None and gets an UNTRAINED STANet — while scripts/prepare_change_vqa.py defaults to the trained LEVIR checkpoint. Training and serving would therefore consume different representations, and the head would still emit a fluent yes."

So the comparison is head_metadata["change_cache_spec"] (what the head was trained on) against feature_extractor.spec_hash (what this deployment produces). Because the spec hash encodes trained-versus-untrained (§30.9), one comparison covers both the resolution/pooling mismatch and the detector-state mismatch.

§32.4 The hook that exists and is not wired

"execute therefore accepts an optional change_map path in request.params for a future planner to populate. It is unused today and documented as such, so the hook exists without pretending the wiring does."

And the cost the module states rather than hides: when the planner routes a change+language request it plans both a change step and a change_vqa step, so the detector runs twice for one request.

"* the model weights are loaded ONCE — the registry caches the specialist instance, so the second cost is a forward pass, not a 60 MB load;

• the alternative (passing the change map from the change step into this one) needs the controller to hand artifacts between steps, which it does not do today. Inventing that here would be a second execution model."

§32.5 Degraded mode produces no answer, on purpose

This is the most distinctive decision in the specialist, and the docstring argues it at length:

"ChangeSpecialist degrades to an untrained detector and still emits a change map. This specialist must not copy that, because the outputs are not comparable: a random change map is visibly noise, whereas an untrained 19-way classifier still emits a fluent, confident-looking yes. A user cannot tell the second from a real answer, so the untrained case returns no answer at all — answer="", degraded=True, and a warning naming exactly which piece is missing."

_unavailable_result therefore returns answer="", labels=[], evidence=[], a ConfidenceBreakdown(raw=0.0, calibrated=None, method="unavailable", degraded=True, degradation_reason=reason) and two warnings — one naming the reason, one carrying TEMPORAL_ORDER_NOTE.

The distinction between the two degraded philosophies is the correct one and is worth stating plainly: a change map can be shown with a warning because its wrongness is visible; a word cannot, because its wrongness is invisible.

§32.6 The status this implies

"R-02 is IMPLEMENTATION_READY_TRAINING_PENDING, so with no trained head on disk this specialist registers as AVAILABLE (it constructs) but answers nothing until the trained artifact is dropped in. Registering it as UNAVAILABLE would be a different claim, and the wrong one — the capability exists, its weights do not yet."

The trained head now exists (§31), so this paragraph is a record of the state at the time of writing, not the current state. It is retained because the distinction it draws — capability present, weights absent — is the same distinction the registry needs to make for change (§22.5).

§32.7 Confidence is uncalibrated and says so

_confidence returns a ConfidenceBreakdown with method="uncalibrated" and calibrated=None, so value returns raw. Components:

Component	Meaning
top1_minus_top2	The margin
top1_probability	The chosen answer's softmax
top2_probability	The runner-up's softmax
n_answers_considered	19
entropy_normalised	-Σ p log p / log 19

The docstring states the position: "Nothing is fitted — the R-03 calibration contract is a separate, open ruling."

§32.8 Two evidence items

_answer_evidence emits exactly two:

#	kind	Score	Payload highlights
1	answer_distribution	confidence	question_type, answer, answer_index, n_answers, top_5 with probabilities, top1_minus_top2, type_mask_applied, confidence_method
2	class_wise_change_estimate	total_changed	class_order, class_change_magnitude (6), class_change_delta (6), total_changed_fraction, estimator_is_learned: True, temporal_order

The docstring's reason for the second item: "A reader can see WHICH class the model believed changed and by how much, rather than only the final word — which is the difference between an explainable answer and a lucky one."

§32.9 validate_request

Exactly 2 assets, both present on disk. The docstring names the common mistake: "the caller treated a change question as an ordinary VQA question about a single image, which would produce an answer about one acquisition rather than about what changed between two."

§32.10 build_change_vqa_specialist

build_change_vqa_specialist(config, checkpoint_path=None, *, head_path=None,
                            artifact_dir=None, device=None)

Three artifacts are built in order: the change feature extractor, the head (only when head_path exists), and the text encoder. The ModelLoadError behaviour is stated in the docstring:

"A checkpoint was named and exists but cannot be read. That is a corrupt artifact, not a missing one. Degrading to an untrained model because a real checkpoint failed to load would turn a broken deployment into a silently-wrong one."

One extra refusal: a head whose model_metadata.json cannot be parsed raises SpecialistError, because "Without it the head's trained feature spec cannot be checked against this deployment, so the head would be served without a skew check."

---

§33 The measured result: two test sets

The two test sets must always be quoted together. docs/DOCS_STYLE_GUIDE.md §3: "Change-VQA | two test sets: test 0.697626/0.378373 and test2 0.651469/0.372309; ruling OPEN."

§33.1 The promotion record

From artifacts/change_vqa/run/PROMOTION.json:

Property	Value
schema	change_vqa_promotion_v1
Promoted	2026-09-22T05:17:00Z
architecture	change_vqa_head_v1
Artifact sha256	cfae5e43b97ca930f568dc5b8ae4f36b24e9ff717af226159802206ffd63a82a
Bytes	5,822,809
parameters	1,453,912
non_finite_tensors	0

§33.2 The result, both test sets

Metric	test	test2
accuracy	0.697626367	0.651469262
macro F1	0.378373275	0.372308516
n_scored	39,686	31,036
majority baseline (global)	0.311546	0.178728

mask_gain is 0.0 on both, and metric_ruling is OPEN.

The two test sets are not interchangeable. Test has 39,686 scored questions and test2 has 31,036 — the difference is the split sizes recorded in §27.1 (39,686 and 31,036), so both are scored in full and neither is a subset of the other. Why the two sets differ in accuracy by 4.6 points is UNKNOWN — not established from the available evidence; what the record does establish is that both were scored under the same promotion identity.

§33.3 The identity block

Every identity field the promotion record pins:

Field	Value
config_hash	78f1e3700da15aa1
dataset_id	cdvqa
feature_spec	change_feat_v1
change_cache_spec	c801326f85a185f8
text_cache_spec	d2801ea1a314354a
preprocessing_version	change_vqa_preproc_v1
seed	42
epoch_selected	8
selected_on	"Val answer accuracy"
val_answer_accuracy	0.700018
stop_reason	early_stopping

The two spec hashes match §30.9 exactly — the caches the head was trained on are the ones the record names.

§33.4 The frozen dependency

Property	Value
Dependency	STANet detector
sha256	c5ef31277b67aa01a593aec0eac503eeaccc6d674349fda20ca44c9cc6f8e9fa
Bytes	63,231,009

This is the frozen feature extractor's identity: the change-VQA head is meaningless without the exact detector whose features it was fit to. §32.3's mismatch refusal exists precisely to enforce this at serving time.

§33.5 Verification and serving wiring

Property	Value
Verification	93 passed / 0 failed
serving_wiring	app/serving.py:76-78

§33.6 What the result does not establish

#	Limitation
1	The metric_ruling is OPEN — the metric protocol itself is not finally ruled on
2	mask_gain is 0.0, so the type mask contributes nothing measurable on these splits (it is on by default in serving)
3	The confidence is uncalibrated; the R-03 calibration contract is a separate, open ruling
4	The head was selected on validation accuracy (0.700018), not on either test set; both test numbers are post-selection measurements
5	state was TRAINED_UNVERIFIED in model_metadata.json at the time of the run record; the promotion record supersedes it but both are on disk
6	Accuracy 0.6976 with macro F1 0.3784 — the gap is large, because the 19-answer space is skewed (§31.3)
7	The two test sets differ by 4.6 accuracy points for a reason not established by any record read for this chapter

---

§34 Change-VQA: limitations

#	Limitation	Status
1	Metric ruling OPEN	OPEN
2	Two test sets reported; neither is a single headline	OPEN — both must be quoted
3	mask_gain 0.0	Measured; the mask is on in serving but contributes nothing measurable
4	Confidence uncalibrated	OPEN — R-03 contract unresolved
5	The detector runs twice per change+language request	Documented cost; the alternative needs controller artifact passing, which does not exist
6	change_map hand-off hook exists and is unused	Documented as unused
7	The default serving path may build an untrained feature extractor (change.checkpoint_path is absent from base.yaml)	Mitigated by the feature-spec mismatch refusal (§32.3), which turns the mismatch into a refusal rather than a wrong answer
8	The MiniLM truncation length on this path is not pinned the way the router's is	UNKNOWN — not established from the available evidence
9	The full question-type count list was not enumerated for this chapter	UNKNOWN — not established from the available evidence (present in run_record.json)

---

Part E — optical_sar: CROMA plus the fusion head

The spec calls this the #1 evaluation priority, and it is the only workflow whose inputs are two different sensors. That difference is what the whole subsystem exists to manage honestly. This part documents the encoder (§35), the sensor adapter (§36), the radiometry (§37), the fusion head (§38), the inference pipeline (§39), the specialist (§40), training and the production head (§41), the measured result (§42), and the limitations (§43).

§35 The frozen backbone: specialists/optical_sar/croma.py

673 lines. Its docstring's opening line is the freeze rule restated: "Written against the REAL model interface, fetched and read during this pass. Every claim below is traceable to a source, because the freeze rule is that implementation proceeds from verified facts."

§35.1 The verified interface

Property	Value	Source
Repository	https://github.com/antofuller/CROMA	fetched 2026-09-18
Model card	https://huggingface.co/antofuller/CROMA @ revision 0dd28e3d633b	same
Loading	PretrainedCROMA(pretrained_path=..., size='base', modality='both', image_resolution=120)	same
Vendored file	use_croma.py — "MUST be vendored; not on PyPI"	same
Forward	model(SAR_images=..., optical_images=...)	same
Default size	120 × 120 px	same
Optical channels	12 (Sentinel-2, cirrus removed)	same
SAR channels	2 (Sentinel-1)	same
Encoder dim	768	same
Mask argument	none — "confirmed by the forward signature above (finding C-1)"	same

The forward returns a dict with six keys:

Key	Shape
SAR_encodings	(B, n_patches, dim)
SAR_GAP	(B, dim)
optical_encodings	(B, n_patches, dim)
optical_GAP	(B, dim)
joint_encodings	(B, n_patches, dim)
joint_GAP	(B, dim)

§35.2 The module constants

Constant	Value
VERIFIED_ENCODER_DIM	768
VERIFIED_OPTICAL_CHANNELS	12
VERIFIED_SAR_CHANNELS	2
VERIFIED_SIZE	"base"
VERIFIED_MODALITY	"both"
VERIFIED_PATCHES_AT_120	225
REQUIRED_VENDOR_FILE	"use_croma.py"
CROMA_REPO_URL	the GitHub URL

The 225 constant carries an important note: "120 / 8 = 15 → 15² = 225 patches. The freeze states this; the README does NOT, so it is verified against the loaded model instead of trusted." This is DEV-3 in the Phase 14 rulings — "CONSISTENT but UNVERIFIED" — and the ruling states the correct response to an unverifiable claim: "croma.py checks the patch count against 225 at load time and raises rather than assuming. That is the right response to an unverifiable claim."

§35.3 The verified constructor deviation (DEV-1)

"Freeze section 2.5 does not name the constructor. The real one is use_croma.PretrainedCROMA, living in a file that must be vendored rather than pip-installed. This module imports it by locating use_croma.py on disk and raises a typed ModelLoadError naming that requirement when it is absent — rather than silently substituting a different loader, which is what 'adapting silently' would look like."

The Phase 14 ruling on this is ACCEPTED as an implementation detail. No ARCHITECTURE CHANGE entry — "This is a loading mechanism, not an architectural deviation."

load_vendored_pretrained_croma(vendor_dir) uses importlib.util.spec_from_file_location to load the file directly, and raises ModelLoadError quoting upstream's own instruction when the file is absent:

"CROMA requires the vendored use_croma.py, which is not in '{dir}'. It is not available on PyPI; download it from {repo} (the official instructions are 'you will need the use_croma.py file and pretrained weights'). Place it in the optical_sar vendor directory and retry."

It also raises if the module loads but does not define PretrainedCROMA, naming the first twelve public names it did find.

The vendored file's identity is recorded: specialists/optical_sar/vendor/use_croma.py, 14,556 bytes, sha256 a38567beed29eb08108a47cdc97fe98aec50fd4be0bd98a5266bcd18aafb7c5b. Discovering it required adding einops to requirements.txt.

§35.4 CROMA is never given a mask (finding C-1)

"The forward pass takes exactly two arguments. The availability mask travels alongside and is consumed by the fusion head (finding C-1). encode returns the CROMA dict unchanged and the caller assembles; there is deliberately no mask= parameter anywhere in this module."

CROMAEncoder.encode(self, optical, sar) has exactly that signature, and a unit test asserts the absence of a mask parameter:

"CROMAEncoder.encode has a pinned signature of exactly (self, optical, sar) — 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 reason CROMA must not receive the mask is in the fusion head's docstring (§38.1) and is the sharpest statement of the project's fabrication rule: CROMA is a masked autoencoder, and 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."

describe() records "receives_mask": False explicitly, so the trace states the rule rather than implying it.

§35.5 The verified contract check

_verify_contract() fires at load time and asserts one thing: that the model is actually frozen.

trainable = [n for n, p in self.model.named_parameters() if p.requires_grad]
if trainable:
    raise ModelLoadError(f"CROMA was expected frozen but {len(trainable)} parameter tensor(s) require grad, ...")

The constructor already calls model.eval() and param.requires_grad_(False) on every parameter; the check exists because "The model is frozen by construction; nothing here may unfreeze it."

The % 8 check is re-verified here too, even though core/config.py enforces it (finding C-7), "because this class can be constructed directly by tests."

§35.6 CROMAEncoding and _to_encoding

CROMAEncoding carries the three GAP vectors, the three token tensors, resolution, n_patches, and an optional radiometry: RadiometrySummary. The token tensors are kept "because evidence may want to show where a representation came from (spec's joint_feature_region)."

as_forward_dict() renders the three GAPs under the keys assemble_fusion_input expects.

_to_encoding validates three things:

Check	Failure
The output is a dict	ModelLoadError naming the type and the expected keys
All three GAP keys are present	ModelLoadError naming the missing keys and the keys actually present
Each GAP is (B, 768)	ModelLoadError naming the observed shape

Token tensors are more forgiving by design: a missing token key yields a zero-width array rather than an error, and a (B, dim, n_patches) layout is transposed rather than rejected — "Some builds return (B, dim, n_patches). Transpose rather than fail, and record the observed shape in the caller's trace."

§35.7 Checkpoint resolution: hash-exempt, pinned identity first

This is the same config-hash trap as §14.9 and §22.5, and the module documents it at length.

"Config.hash is a sha256 over the whole registry with NO exclusion mechanism (core/config.py:76-80). The shipped artifacts record 78f1e3700da15aa1, and scripts/eval_change.py refuses to score on a drift (exit 3), so writing croma.checkpoint_path into base.yaml today would detach the project's benchmark numbers from their config."

ENV_CROMA_CHECKPOINT = "SATQUERY_CROMA_CHECKPOINT" is the hash-exempt channel — "Deliberately the same hash-exempt channel radiometry.resolve_use_8_bit uses."

resolve_checkpoint_path(config) returns (path, source) with a four-step order, most specific first:

Step	Source	Condition	On a missing path
1	"env"	SATQUERY_CROMA_CHECKPOINT is set and non-empty	raises ModelLoadError
2	"config"	croma.checkpoint_path exists and is a non-empty string	raises ModelLoadError
3	"hub-cache"	The pinned (repo, file, revision) triple resolves through the Hub cache	falls through
4	"absent"	Nothing resolved	returns (None, "absent")

Two design points the docstring defends:

Offline first. Step 3 tries local_files_only=True before False:

"Serving composition must not depend on a network round trip. A cached, revision-pinned snapshot resolves locally and is byte-stable; only a genuine cache miss falls through to the Hub. That ordering is what makes the default serving composition work on a machine that has the artifact and no egress."

Raising versus degrading. Steps 1–2 raise; step 4 degrades:

"An explicitly specified path (steps 1–2) that does not exist raises ModelLoadError… a typo'd operator path is a misconfiguration, not an absent artifact, and silently degrading on it is the 'config surface that advertises a capability the code lacks' failure this repo has already ruled against (F-17). An artifact that is simply absent (step 4) is a deployment case."

The four source values are exported as stable literals — CHECKPOINT_SOURCE_ENV, _CONFIG, _HUB_CACHE, _ABSENT — "Recorded alongside the path so the choice is never invisible. Stable literals, not free text."

§35.8 The measured CROMA facts

From docs/PHASE14_OPTICAL_SAR_DECISIONS.md §6 item 5 and its update, plus artifacts/optical_sar/croma_forward.json:

Property	Value
Checkpoint bytes	777,563,846
Checkpoint sha256	0238d814b53108f3574bf1ea240e38a0a6edd46173816d9a6962070561893b63
Parameters	194,365,440
Forward pass, batch 2 @ 120 px, CPU	0.89 s
Checks passed	13 / 13
n_patches measured	225
GAP shapes measured	(B, 768)
Token shapes measured	(B, 225, 768)

Two structural facts surfaced that no document had recorded:

Fact	Detail
CROMA-base is asymmetric	s1_depth = 6, s2_depth = 12
The joint cross-attention is directional	SAR queries optical

Both are recorded in docs/ARCHITECTURE_CHANGE_CROMA.md DEV-3 and docs/PHASE11_CROMA_STATUS.md.

§35.9 The Phase 14 contract verification

The Phase 14 record re-fetched the upstream README and confirmed every frozen §2.5 row by hand:

Frozen §2.5 claim	Upstream README	Verdict
size='base', modality='both'	matches the constructor call	MATCH
image_resolution=120 native	"CROMA's default image size is 120x120px"	MATCH
optical 12 channels	"Sentinel-2 must be 12 channels (remove the cirrus band…)"	MATCH
SAR 2 channels	"Sentinel-1 must be 2 channels"	MATCH
no mask to CROMA (C-1)	forward takes only SAR_images=, optical_images=	MATCH
768-d per modality	"base model uses 768 dimensional feature representation"	MATCH
keys optical_GAP/SAR_GAP/joint_GAP	documented verbatim	MATCH

Verdict: "the frozen §2.5 contract is accurate."

---

§36 The sensor adapter: specialists/optical_sar/sensor_adapter.py

556 lines. This module is where "some sensor's bands" becomes "CROMA's canonical channels", and it is the enforcement point for §4.1.

§36.1 The two hard rules

Plan sections 18 and 20 state them without qualification:

"No invented missing bands." "Do not fabricate spectral bands."

And the module explains the failure mode this prevents, in the passage quoted in §4.1. The conclusion: "missing channels are zero-filled, and the availability mask says which ones were real. The mask is the load-bearing part. A zero-filled channel is indistinguishable from a genuinely black pixel without it; with it, the fusion head (finding C-1) can learn to discount the channels that carry no information."

§36.2 The canonical optical channels

OPTICAL_CANONICAL is the 12 Sentinel-2 L2A bands with cirrus removed:

Index	Band	Meaning
0	B01	coastal aerosol
1	B02	blue
2	B03	green
3	B04	red
4	B05	red edge 1
5	B06	red edge 2
6	B07	red edge 3
7	B08	NIR
8	B8A	narrow NIR
9	B09	water vapour
10	B11	SWIR 1
11	B12	SWIR 2

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

CROMA's README states the requirement: "Sentinel-2 must be 12 channels (remove the cirrus band if necessary)."

SAR_CANONICAL = ("VV", "VH") — "Sentinel-1 dual-pol order CROMA was pretrained with. Positional fallback ONLY."

§36.3 The alias table

_BAND_ALIASES maps the spellings seen in the wild onto canonical names, and the comment states the risk: "Kept small and explicit: a guess here becomes a silently mislabelled band."

Group	Aliases
Sentinel-2 / generic	B1→B01 … B8→B08, B8A, B9→B09, B10, B11, B12
Named colours	COASTAL→B01, BLUE→B02, GREEN→B03, RED→B04, NIR→B08, SWIR1→B11, SWIR2→B12
SAR polarisations	HH, HV, VV, VH, VVPOL→VV, VHPOL→VH

_canonicalise strips, uppercases, and removes spaces and underscores before lookup.

§36.4 Why band_map is canonical-channel-keyed

The schema declares band_map: dict[str, str], and the plan's example writes it sensor-keyed. This module uses source → canonical and the docstring explains:

"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?' That is the question the zero-fill loop asks, and it is the question the fusion head's mask is about."

A second, concrete reason is given at the construction site: keying by canonical index "would force a name→index search that breaks as soon as a sensor names its bands differently from the canonical spelling (Cartosat-2S's 'B1' vs canonical 'B01')." canonical_to_sensor is exposed as the inverse for reporting.

§36.5 _canonical_order — optical is fixed, SAR is the descriptor's own

listed = list(descriptor.available_bands)
if listed and all(b in {"HH", "HV", "VV", "VH"} for b in listed):
    return tuple(listed)
return OPTICAL_CANONICAL

"Optical channels are placed by identity against the Sentinel-2 order, so this returns the fixed OPTICAL_CANONICAL. SAR is different: a descriptor's own polarisations DEFINE its slot order (plan section 19 — inspect, do not assume a fixed pair), so the order is the descriptor's available_bands list, padded to the canonical width. An HH/HV sensor therefore has slots ("HH", "HV"), which is what the mask and the tensor agree on."

§36.6 build_optical_adapter

build_optical_adapter(sensor, *, available_bands=None, canonical_channels=12,
                      normalization=NORM_PERCENTILE, resolution=None) -> SensorDescriptor

Guard	Error
No bands known for the sensor and none supplied	UnsupportedBandsError — "refusing to guess a band arrangement"
A band name not in OPTICAL_CANONICAL	UnsupportedBandsError naming the unmapped bands
Duplicate bands	UnsupportedBandsError
More bands than canonical_channels	UnsupportedBandsError

The second guard's comment states the principle: "The band NAME is not in the canonical order. That is not fatal — the sensor may name its bands differently — but it cannot be placed, and inventing a position for it is the forbidden move."

_KNOWN_OPTICAL_SENSORS is deliberately tiny and explicit:

Sensor	Bands
sentinel_2	the full 12
cartosat_2s	["B1","B2","B3","B4"]
cartosat_2	["B1","B2","B3","B4"]
landsat_8	["B1","B2","B3","B4"]

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

§36.7 describe_sar — inspect, do not assume

Plan section 19: "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's reasoning:

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

describe_sar honours supplied available_bands when present and falls back to _known_sar(sensor) otherwise. The slot order is the sensor's own:

"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. Keeping the sensor's own order and identifying each slot in available_bands preserves both."

_known_sar returns:

Sensor key	Polarisations	Note
sentinel_1, sentinel1	["VV","VH"]
anything starting 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'"

Refusals: unrecognised polarisations, duplicates, and more polarisations than the canonical width.

§36.8 _apply_canonical — the enforcement point

for source_index, source_name in enumerate(descriptor.available_bands):
    if source_index >= n_source:
        continue                      # do NOT read a neighbouring band to fill the gap
    canonical_name = descriptor.band_map.get(source_name)
    if canonical_name is None or canonical_name not in order:
        continue                      # a real band with no canonical slot stays out
    channel_index = order.index(canonical_name)
    if channel_index >= n_canonical:
        continue
    canonical[channel_index] = array[source_index]
    mask[channel_index] = True

The docstring's framing is the clearest statement of the rule in the codebase:

"Read it as the enforcement point: a source band goes to at most one canonical channel, and any channel with no source band is written as zeros and marked unavailable. There is no branch anywhere below that writes a value into an unavailable channel."

If no source band could be placed at all, it raises UnsupportedBandsError rather than returning an all-zero tensor.

adapt_optical and adapt_sar are the two thin wrappers. adapt_sar's docstring calls it "Plan section 19's internal representation, exactly."

§36.9 The measured band adaptation

Verified by direct execution in the Phase 14 pass — Cartosat-2S (4 bands) into the 12-channel canonical order:

band_map   = {'B1': 'B01', 'B2': 'B02', 'B3': 'B03', 'B4': 'B04'}
mask       = [T, T, T, T, F, F, F, F, F, F, F, F]
canonical  = (12, H, W)
per-channel abs-sum = [64, 64, 64, 64, 0, 0, 0, 0, 0, 0, 0, 0]

"Data lands in slots 0–3; slots 4–11 are exactly zero and masked False. Cartosat's B1–B4 are mapped positionally onto the first four canonical slots and are not claimed to be Sentinel-2 equivalents."

§36.10 The measured SAR refusals

adapt_sar(bands=['XX','YY'], sensor='risat')
  -> UnsupportedBandsError: "SAR polarisation(s) ['XX','YY'] ... are not recognised;
     supply explicit polarisation labels rather than assuming a fixed pair"

3 polarisations into a 2-channel canonical form
  -> UnsupportedBandsError: "sensor 'risat' has 3 polarisations but the
     canonical SAR representation holds 2"

"Both are the correct refusals. A positional guess here would have fabricated a VV/VH pair the sensor may not have measured."

§36.11 positional_fallback_descriptor

For a raster with the right channel count but no band labels. The fallback order is chosen from _FALLBACK_SAR_ORDER = (("VV","VH"), ("HH","HV")) for ≤2 channels or the canonical optical prefix otherwise, and "the fact that it was a fallback is recorded in sensor so it cannot be mistaken for measured metadata."

complement=True selects the other convention, "which lets a caller test both HH/HV and VV/VH orderings without asserting which is correct."

§36.12 SensorAdapterOutput

Member	Content
canonical	(C, H, W) float32 — real bands in canonical position, absent channels present but zero
mask	(C,) bool — True where the channel came from a real band
descriptor	The SensorDescriptor recording the mapping and normalisation
n_channels	Derived
missing_indices	Derived — indices where the mask is False
available_bands	From the descriptor
to_dict()	Sensor, bands, band map, canonical channel count, n_available, missing channels, normalisation, resolution

---

§37 Radiometry: specialists/optical_sar/radiometry.py

580 lines, and it implements a ruling rather than a preference.

§37.1 The gap it closes

"configs/base.yaml declares two radiometric transforms… Neither is read by any code. CROMA's released inference wrapper (vendor/use_croma.py, sha256 a38567beed29eb08) applies no input scaling either — verified first-hand: the module defines no normalize, and a grep for normal|255|mean|std|percentile|clip|uint8 returns only internal nn.LayerNorm layers and mean(dim=1) GAP calls."

So the encoder was receiving whatever dynamic range the caller happened to hand it — "a silent distribution shift away from the [0, 1]-ish input the frozen pretrained weights were fit under."

§37.2 What is implemented, and what is not

Stage	Status
Encoder-input — per-channel mean ± 2·std → [0, 1]	IMPLEMENTED
Conditioning — percentile / dB clip	NOT IMPLEMENTED

"The ruling (PHASE14_CROMA_NORMALISATION_CHANGE.md section 2.2) states the two are ordered stages, not alternatives, and that both must run. The second is specified here; the first remains unspecified and unsourced — no source examined in docs/CROMA_NORMALISATION_UPSTREAM_EVIDENCE.md uses or endorses a percentile stretch or a dB clip. Implementing a guess for it is exactly the fabrication the DEV-2 ruling exists to prevent, so it is left visibly absent rather than silently approximated."

Consequence, stated in the module: "the two optical.* and three sar.* config keys are still read by no code. That is recorded, not fixed." This is item 6 in the Phase 14 outstanding table, and it is the one item that remains open in that table — "It is not closed cosmetically."

The pipeline position:

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

§37.3 The transform, verbatim from the CROMA README

Per channel c:

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

§37.4 Two deliberate deviations from upstream

#	Deviation	Reason
1	Per sample, not per batch	"The README computes x[:, c].mean() over the whole batch, so at N > 1 the window depends on what else is in the batch. That makes a single image's encoding a function of its neighbours, which is unacceptable for a serving system whose whole point is reproducibility: the same query must not produce a different answer because another request was batched alongside it."
2	Unbiased standard deviation	"Upstream is torch, whose .std() defaults to the unbiased estimator (ddof=1). NumPy's .std() defaults to ddof=0. This module uses ddof=1 to match the reference implementation… At 120×120 the two differ by a factor of ~1.00003, so the choice is numerically immaterial — it is made for fidelity, and stated so nobody has to guess which convention a number came from."

Deviation 1 is justified as the ruling's own reading: PHASE14_CROMA_NORMALISATION_CHANGE.md §3.1.1 "already specifies the (C, H, W) tensor — i.e. one sample — so this is the ruling's own reading, not a reinterpretation. At N = 1 the two are identical; the README's own example runs at N = 1."

§37.5 The zero-channel rule, and why no mask is needed

"An unavailable channel is all zeros — that is the sensor adapter's convention, and the same rule the fusion head's dropout obeys. Such a channel has std = 0, so max_value - min_value == 0 and the stretch divides by zero.

Unavailable channels are therefore skipped and left at exactly zero. They are never normalised and never given a fabricated scale. This is the C-1 discipline applied to radiometry: the same rule that forbids inventing a band forbids inventing a dynamic range for a band that does not exist."

And the mechanism is deliberate: "The degenerate-window test is the mechanism, and it needs no mask. That is deliberate: CROMAEncoder.encode has a pinned signature of exactly (self, optical, sar)… Inferring unavailability from the data keeps that guard intact while still honouring the rule, and it is robust to a caller that forgets to pass a mask."

§37.6 The three channel statuses

Status	Condition	Meaning
STATUS_UNAVAILABLE	The channel is all zeros	"the sensor did not measure this"
STATUS_DEGENERATE	The channel is present but has a zero-width window	"the sensor measured a flat band"
STATUS_NORMALISED	A window exists and was applied	The real case

The distinction is preserved rather than merged: "it is recorded with a different status (degenerate) so the trace distinguishes 'the sensor did not measure this' from 'the sensor measured a flat band'. Nothing is invented in either case."

warnings_for(report) emits a note only for degenerate channels, because "A masked-off channel is the expected case and produces no warning — Cartosat-2S always has 8 of 12 optical channels absent, and warning about it every request would be noise. A present channel that could not be stretched is a data defect and must be visible."

§37.7 Non-finite pixels

"A non-finite pixel is a defective measurement, not a measurement of zero, and it has no place in a linear stretch. It is pinned to 0.0 — the same value the sensor adapter uses for 'nothing was measured here' — rather than left to propagate NaN into the frozen encoder, where one NaN would poison the whole forward pass (and, on the uint8 path, raise a cast warning even when the clip happens to bound it). finite_pixels in the report keeps the gap detectable."

§37.8 The constants and records

Symbol	Value / role
TRANSFORM_NAME	"per_channel_mean_pm_2std"
WINDOW_SIGMAS	2.0
DEFAULT_USE_8_BIT	True
ENV_USE_8_BIT	"SATQUERY_CROMA_USE_8_BIT"
MIN_FINITE_PIXELS	2
MODALITY_OPTICAL / MODALITY_SAR	"optical" / "sar"

Record	Content
ChannelWindow	sample, channel, status, lower, upper, finite_pixels, skipped
RadiometryReport	modality, transform, use_8_bit, n_samples, n_channels, windows; plus skipped, normalised_channels, unavailable_channels, degenerate_channels, to_dict(max_windows=64)
RadiometrySummary	use_8_bit, transform, optical, sar, to_dict()

ChannelWindow.lower/upper are None for a skipped channel — "deliberately, because a skipped channel has no window, and recording 0.0 there would read as a real measurement of a zero-width range."

RadiometryReport.to_dict never silently truncates — it sets truncated: true and reports windows_total.

normalised_channels lists a channel only when it was normalised in every sample: "A channel normalised in only some samples is not listed: the point of this property is to answer 'did this channel carry real signal?', and 'sometimes' is not an answer to that."

§37.9 use_8_bit resolution, and the same hash trap

resolve_use_8_bit(config) -> (value, source)   # source in {"env", "config", "default"}

Order	Source	Condition
1	"env"	SATQUERY_CROMA_USE_8_BIT set and non-empty; parses {1, true, yes, on}
2	"config"	croma.use_8_bit exists and is a bool
3	"default"	DEFAULT_USE_8_BIT = True, per the ruling

The reasoning is the §35.7 trap restated, and it names the precedent: "the same pattern already used for SATQUERY_DEVICE. The value is recorded in every trace either way, so it is never invisible."

§37.10 Why use_8_bit defaults to True

PHASE14_CROMA_NORMALISATION_CHANGE.md §2.2 decides use_8_bit: ENABLED.

"The uint8 round-trip guarantees the [0, 1] range the frozen encoder requires; the float path's clip is applied to a stretch that is unbounded by construction (mean ± 2*std is not a min/max clamp)."

The quantisation is "a bounded, uniform error (~1/256 of full scale) and it is what guarantees the range invariant."

§37.11 normalise_for_croma is pure and deterministic

"The function is pure and deterministic: no sampling, no learned statistics, no RNG, and no dependence on batch composition. Same input → same output."

The _channel_window helper uses float64 for the statistics — "a 120×120 float32 channel can accumulate enough error in mean to matter once it is divided by a narrow window."

§37.12 summarise asserts the two modalities agree

if optical_report.use_8_bit != sar_report.use_8_bit:
    raise ValueError(...)

"They must agree: the ruling requires the identical stretch on both, and the vendored use_croma.py uses one ViT class for both modalities with no divergence (vendor/use_croma.py:54,68). Asserted rather than assumed."

§37.13 What this module cannot claim

"That the transform matches CROMA's pretraining input distribution. The author states the pretraining dataloader 'followed SatMAE's data preprocessing' and that it 'was specific to the hardware I used' — and it was never released (CROMA_NORMALISATION_UPSTREAM_EVIDENCE.md sections 2.6 and 5.3). The exact pretraining distribution is therefore not recoverable from public sources.

This is the transform the authors' own code instructs users to apply, adopted as the best-supported default. It is not a verified match, and the gated experiment in PHASE14_CROMA_NORMALISATION_CHANGE.md section 4 is the only mechanism that could ever turn it into one."

describe_transform records "source": "CROMA README normalize() -- the authors' instructed transform", which is the shape of the transform, not a claim about its provenance.

§37.14 The control arm

CROMAEncoder(normalize_input=False) exists for the ruling's gated experiment (arm B needs a no-stretch control). The docstring is emphatic that it is not a production setting:

"It is not a supported production setting: with it off, the frozen encoder receives whatever dynamic range the caller supplied, which is the silent distribution shift the ruling exists to close."

describe() renders the disabled case as {"applied": False, "use_8_bit": None, "source": "input normalisation disabled at construction"} — "Recorded as 'not applied' rather than omitted, so a trace can never show a normalisation that did not run."

---

§38 The fusion head: specialists/optical_sar/fusion_head.py

395 lines.

§38.1 The frozen concatenation

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)

2318 = 3 × 768 + 12 + 2.

The width is derived three times, and the third is a refusal:

Place	Behaviour
configs/base.yaml	fusion.input_dim = 2318
core/config.py	Recomputes it as len(modalities_used) * encoder_dim + optical_channels + sar_channels at load time (finding C-1)
fusion_head.py	Recomputes it again from the CROMA config 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."

expected_fusion_dim(*, encoder_dim=768, optical_channels=12, sar_channels=2, modalities_used=3) implements the arithmetic.

§38.2 Why the mask goes here and not into CROMA (finding C-1)

The module's section header is WHY THE MASK GOES HERE AND NOT INTO CROMA (finding C-1), and its argument is the sharpest statement of the fabrication rule in the project:

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

assemble_fusion_input asserts the concatenation order rather than assuming it:

"Order is frozen (freeze section 2.5). It is asserted rather than assumed, because a permutation here produces a tensor of exactly the right shape that trains to a worse number — the hardest kind of bug to notice."

Guards: a missing CROMA_GAP_KEYS member, a wrong component width, a batch-size disagreement among the three GAPs, a batch-size disagreement between the masks and the features, and a final width check against expected_fusion_dim. Each raises SpecialistError naming the shapes involved.

§38.3 FusionInput carries the parts

"Carrying the parts is not redundancy: the confidence system (plan section 26) needs optical_mask and sar_mask separately to report how much of each modality was actually present, and recovering them by slicing the concatenation re-derives the layout in a second place."

§38.4 Mandatory channel/band dropout

Freeze section 2.5: "Channel/band dropout during fusion-head training is mandatory; it is what teaches the head to trust the availability mask."

The module explains the mechanism precisely:

"With no dropout, the head learns to read channel 4 of the optical vector unconditionally, because in training channel 4 was always present. On the hidden set (Cartosat-2S, 4 bands) channels 5-12 are always zero — and a head that never saw a masked channel treats those zeros as a measurement of blackness rather than as absence. Dropout makes 'this channel is missing' a state the head has been trained under, so the mask becomes informative instead of decorative."

channel_dropout(features, mask, *, keep_probabilities, rng):

Step	Behaviour
1	Validate features.shape == mask.shape
2	Validate keep_probabilities ⊆ [0, 1]
3	Per sample, draw a keep fraction uniformly from keep_probabilities
4	Bernoulli-draw per channel against that fraction
5	keep = draws & (mask > 0.0) — an unavailable channel stays unavailable
6	Zero the dropped features; return the updated mask

Two decisions the docstring defends:

"The mask is updated to match the dropped features. That is the entire point — dropping features while leaving the mask saying 'present' would teach the head that the mask lies."

"Dropped channels are zeroed, not renormalised — renormalising would fabricate a scale that the real missing-channel case does not have."

And: "channel_dropout is a real function, not a flag: it is tested directly, because a training-time transform that never actually ran is one of the easiest things to ship broken."

§38.5 The dropout schedule

Plan section 20's robustness schedule: optical at 100/80/60/40 % channel availability, SAR at 100/50 %.

§38.6 The measured dropout behaviour

Verified by direct execution in the Phase 14 pass:

Property	Result
p=1.0 keeps all 48/48 available channels	PASS
p=0.4 drops to 18/48 (~40%)	PASS
Dropped features are exactly 0.0 (not renormalised)	PASS
Bands the sensor never measured stay dropped even at p=1.0	PASS
Seeded RNG is deterministic	PASS

"The third and fourth rows are the load-bearing ones: dropping features while leaving the mask 'present' would teach the head that the mask lies, and renormalising would fabricate a scale the real missing-channel case does not have. The implementation avoids both."

The Phase 14 ruling on this is explicit: the implementation "satisfies the freeze's intent — zeroing rather than renormalising is not merely acceptable, it is the only choice consistent with §2.5's stated rationale." No change entry.

§38.7 mask_availability_stats

{
    "optical_available_fraction": ...,
    "sar_available_fraction": ...,
    "optical_channels_present": ...,
    "sar_channels_present": ...,
}

"Fraction of each modality actually present. Feeds the confidence system."

§38.8 The torch head

build_fusion_head(*, input_dim, hidden_dim, task_dim, dropout, device="cpu")

LayerNorm(input_dim) -> Linear(input_dim, hidden_dim) -> GELU -> Dropout
                     -> Linear(hidden_dim, task_dim)

Guard	Behaviour
device != "cpu"	SpecialistError — "The plan's deployment boundary allows CPU-only operation (freeze section 4: cpu_mode required). A device string that would silently fall back is worse than a refusal."
input_dim != 2318	ModelLoadError naming finding C-1

No activation on the output, and the comment gives the reason: "this is a logit-producing task head, and a softmax here would be applied twice once a loss function adds its own."

load_fusion_head(path, *, device="cpu", **kwargs) builds the head, loads the state dict (unwrapping a {"state_dict": ...} wrapper when present), calls eval(), and sets head._satquery_trained = True. A load failure raises ModelLoadError — "A corrupt artifact is NOT the same as a missing one, and must never be silently replaced by an untrained head."

§38.9 The head's parameter count

1,201,711 parameters (artifacts/optical_sar/fusion_head_production_v001/production_head_record.json → head_config.head_parameters), with input_dim 2318, hidden_dim 512, task_dim 19, dropout 0.2.

---

§39 The inference pipeline: specialists/optical_sar/inference.py

405 lines. The seam between "an image on disk" and "three GAP vectors plus two masks."

§39.1 The pipeline

optical raster -> sensor adapter -> (12, H, W) + mask[12]
SAR raster     -> sensor adapter -> ( 2, H, W) + mask[2]
resize to CROMA's 120x120
CROMA(SAR_images=..., optical_images=...)     <- no mask, ever
assemble_fusion_input                         <- mask enters HERE
fusion head -> logits -> probabilities

§39.2 Why the module is separate

"Kept separate from specialist.py so the tensor plumbing can be tested without a Specialist and without a raster, and separate from croma.py so that module stays a thin wrapper over someone else's model."

§39.3 resize_to_canonical

(C, H, W) → (C, resolution, resolution), bilinearly, via cv2.INTER_LINEAR with a torch F.interpolate fallback when OpenCV is absent. The docstring's reasoning:

"Everything in the chain is in the same units, so plain interpolation is correct. Nearest-neighbour would be wrong for the continuous optical reflectance channels; for the zero-filled channels it costs nothing either way, since interpolating zeros gives zeros."

§39.4 Degradation is a first-class outcome

"Two artifacts are needed and neither is guaranteed to exist in this environment: CROMA_base.pt (777.6 MB) and the vendored use_croma.py, plus a trained fusion head (which has never been trained). Per Phase 8's precedent and Phase 9's, a missing artifact is a DEPLOYMENT case, not a crash. run_pipeline reports which pieces were missing and returns a result marked degraded rather than raising — but it never invents a prediction to fill the gap. When the head is absent there is no class output at all, and the caller is told so in warnings."

§39.5 What is computed with no artifact at all

"Everything on the sensor side. The masks, the canonical channel placement, the availability statistics and the modality validation are all real work that requires no weights, and they are exactly the facts that tell an operator why a result is or is not trustworthy on Cartosat-2S + RISAT. Those keep running when the models do not."

§39.6 The three exit paths

Path	Condition	probabilities	degraded	Reason recorded
No CROMA	encoder is None	None (placeholder tensor of the right shape)	True	"CROMA is not loaded"
No head	head is None	None	True	"no trained fusion head"
Full path	both present	(1, task_dim)	bool(reasons)	possibly "fusion head is not a trained artifact"

The placeholder's docstring is careful: "Deliberately NOT used for a prediction. It exists so the result object has a consistent shape and the caller can read the masks; probabilities stays None so nothing can mistake it for an inference."

§39.7 The two hard failures

if stats["optical_channels_present"] == 0:  raise SpecialistError(...)
if stats["sar_channels_present"]     == 0:  raise SpecialistError(...)

These raise rather than degrade, and the docstring explains the boundary: "SpecialistError: the caller passed arrays that cannot be canonicalised at all — a programming error, not a deployment state."

Below that, a warning is emitted whenever fewer channels than the canonical width are present, and it names the number and says "No band was invented to fill them."

§39.8 The patch-count check

if encoding.n_patches != (resolution // 8) ** 2:
    warnings.append(f"CROMA returned {encoding.n_patches} patches; at {resolution}px with stride 8 the frozen spec expects {(resolution // 8) ** 2}")

A warning, not a raise, because the encoding is still usable — but the discrepancy is recorded rather than passed over.

§39.9 The class-count check

if probabilities.shape[1] != task_dim:
    raise SpecialistError(f"fusion head emitted {probabilities.shape[1]} classes, expected {task_dim}")

This one raises: a head whose output width disagrees with the configured class count cannot be interpreted.

§39.10 The decision and the margin

order     = np.argsort(probabilities[0])[::-1]
predicted = int(order[0])
margin    = float(probabilities[0][order[0]] - probabilities[0][order[1]])
agreement = cross_modal_agreement(encoding)

margin is the top-1 minus top-2 probability. cross_modal_agreement is the mean cosine similarity between optical_gap and sar_gap:

"Plan section 26 lists cross-modal agreement as one of the four optical-SAR confidence components. This is the cheapest honest reading of it: how similarly do the two encoders describe the same scene? A high value means both modalities point the same way; a low one means the fused decision rests on a disagreement.

It is a MEASUREMENT on the encoded vectors, not a learned quantity, and it is NOT used as a probability — it feeds estimate_confidence as one component among four."

It returns None on a shape mismatch, an empty tensor, or any exception — a missing measurement rather than a fabricated 0.0.

§39.11 build_head_from_config

build_head_from_config(config, *, head_path=None, device="cpu")

Reads fusion.input_dim (2318), fusion.hidden_dim (512), fusion.num_classes (19), fusion.dropout (0.2). Returns None when no head_path is given or the path does not exist, "rather than an untrained head. That distinction is the whole point: build_fusion_head would happily produce a randomly-initialised module, and returning it would put a real tensor behind has_prediction with no learned signal in it."

A head_path that exists but cannot be read raises ModelLoadError: "A corrupt artifact must never be silently downgraded to 'untrained'."

---

§40 The specialist: specialists/optical_sar/specialist.py

997 lines.

§40.1 The frozen contract

exactly 2 assets, one optical and one SAR
optical -> 12 canonical channels, zero-filled, availability mask
SAR     ->  2 canonical channels, zero-filled, availability mask
CROMA(SAR_images, optical_images)  <- never receives a mask (C-1)
concat[optical_GAP, SAR_GAP, joint_GAP, optical_mask, sar_mask] -> (B, 2318)
fusion head -> label
confidence from plan section 26

§40.2 Identity and guards

Attribute	Value
name	"optical_sar"
version	"0.1.0"
capabilities	("optical_sar",)
resolution	120
task_dim	19 (DEFAULT_TASK_DIM)
channel_dropout_rates	(1.0,)

Two constructor guards: task_dim >= 2 ("for a margin to exist") and resolution % 8 == 0 (CROMA asserts it; finding C-7).

§40.3 Two assets, and they must be the right two

validate_request rejects 0, 1, 3, and also two of the same kind. The module explains why the last case deserves its own refusal:

"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, and it names which asset was wrong. The four outcomes:

Outcome	Error context reason	User message
Two optical	"two_optical"	"Both uploaded images look like optical imagery. This workflow needs one optical image and one radar (SAR) image."
Two SAR	"two_sar"	"Both uploaded images look like radar (SAR) imagery. This workflow needs one optical image and one radar (SAR) image."
One of each	—	Succeeds; returns a PairAssessment
Indeterminate	"indeterminate"	"Could not tell which image is optical and which is radar. Please label the images so one is optical and one is SAR."

§40.4 Modality resolution

asset.modality wins when declared; otherwise _infer_modality uses preprocessing.raster.infer_modality(band_count). The declared value wins "because the caller may know something the band count does not — a 2-band Cartosat stack, or a 12-band decomposition product."

The inference always emits a warning, and it is worth quoting because it is the honest framing of a heuristic:

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

When there is no band count either, the asset is treated as UNKNOWN and a warning says so.

§40.5 Descriptor resolution

_descriptor_for(asset, kind, warnings) has three paths:

Path	Condition	Behaviour
Declared	asset.sensor is not None	Used as given. If its canonical_channels disagrees with the expected width (12 optical / 2 SAR), a warning is recorded and the declared layout is still used, zero-filling the remainder.
Optical, no descriptor	—	Bands mapped positionally onto the first n canonical Sentinel-2 channels, with a warning calling it "an ASSUMPTION about band identity, not a measurement". Zero bands raises PairCompatibilityError.
SAR, no descriptor	—	Uses positional_fallback_descriptor, with a warning: "The polarisation IDENTITY of each channel is NOT known from a band count alone — supply a sensor descriptor to state it." More than 2 bands warns that only the first 2 are placed.

The comment on the SAR path records why it does not simply call describe_sar(stem): "Calling describe_sar(stem) alone would rely on the filename being a known sensor name, which it almost never is — and an unknown sensor yields no bands at all, so nothing would be placeable."

§40.6 The confidence derivation

CONFIDENCE_WEIGHTS = {
    "fusion_margin":          0.40,
    "optical_confidence":     0.20,
    "sar_confidence":         0.20,
    "cross_modal_agreement":  0.20,
}
AGREEMENT_FLOOR = -1.0

Component	Derivation	Weight
fusion_margin	clip(inference.margin, 0, 1)	0.40
optical_confidence	The fraction of the 12 optical channels present	0.20
sar_confidence	The fraction of the 2 SAR channels present	0.20
cross_modal_agreement	clip((agreement − (−1)) / (1 − (−1)), 0, 1)	0.20

Plus recorded-but-unweighted components: optical_channels_present, sar_channels_present, has_croma, trained_head, and cross_modal_agreement_raw when it exists.

The docstring justifies the weighting:

"The largest weight is the fusion margin, because it is the only term that reflects what the classifier actually decided. The two availability terms and agreement are corroborating evidence about the INPUT, not about the decision — they can lower a confident prediction, and they cannot raise an unconfident one above it."

AGREEMENT_FLOOR = -1.0 rescales a cosine in [−1, 1] to [0, 1]; "A negative cosine (the two encoders systematically opposite) clamps to 0.0, which is the correct reading: no agreement at all."

§40.7 Why the availability fraction is the modality-confidence reading

The docstring is explicit that this is a deliberate choice, not a proxy:

"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, and a confidence that ignored that would be reporting the model's certainty about a tensor it was mostly fed zeros. The availability fraction is the honest scalar for 'how much real signal is behind this'."

§40.8 The floors

if not inference.has_prediction:
    components["no_prediction"] = 1.0
    return components, 0.0

margin = float(np.clip(inference.margin, 0.0, 1.0))
components["fusion_margin"] = margin

if not self.has_head:
    return components, 0.0

"Both are signal GAPS, not weak signals, so they resolve to 0.0 rather than merely discounting — the same rule Phase 9 applied to a change map with no regions."

And no_prediction is recorded before the early return, "so the trace states every reason the score is zero, not just the first one encountered" — the same ordering discipline the change specialist applies to suppressed_by_registration (§22.8).

§40.9 The answer templates

_compose_answer(label, inference) builds prose from computed facts only. Three branches:

Branch	Answer shape
No CROMA	"No fused prediction was produced: CROMA is not loaded. Sensor-side analysis completed ({availability}); {n} optical channel(s) and {m} SAR channel(s) are absent for these sensors and are zero-filled with the availability mask set false."
No prediction	"No fused prediction was produced: no trained fusion head is loaded. The optical/SAR/joint representation was computed ({availability}), but a label requires a trained head. Absent channels are zero-filled and masked, never invented."
Prediction	"Fused optical-SAR prediction: {label} (margin {m}; {availability})."

_label_for returns "" when there is no prediction, and falls back to f"class_{index}" when the predicted index is outside class_labels.

§40.10 Geospatial: optical's frame, SAR's facts alongside

_geospatial uses the optical asset's georeferencing — "it is the asset a reader can navigate by" — and carries the SAR facts separately:

Extra field	Content
optical_crs, sar_crs	Both CRSs
sar_bounds, sar_resolution	SAR georeferencing
optical_availability, sar_availability	The two masks
optical_sensor, sar_sensor	The sensor identifiers
resolution_ratio_sar_to_optical	When both resolutions are known

"The SAR footprint may differ — RISAT and Cartosat-2S are different missions with different orbits — so the SAR bounds are carried alongside rather than fused into a single claimed footprint."

§40.11 Artifacts: the sibling site of F-16

_write_artifacts renders the optical and SAR canonical tensors as PNG views. _render_view maps (C, H, W) → (H, W, 3) uint8:

"Missing channels are zeros, so the view is dark where the sensor had no band. That is the honest rendering: it shows the gap rather than stretching noise to fill the frame."

The evidence item is emitted either way — rendered or not — with artifact_ref=None and a payload stating rendered, retrievable: False and retrieval: "no artifact-serving endpoint in v1". §4.4 quotes the reasoning; the module adds that the previous shape "put the ABSOLUTE ON-DISK PATH of the PNG into artifact_ref and, when rendering failed, omitted the evidence item entirely — which made 'we rendered nothing' and 'we rendered something you cannot fetch' indistinguishable, and disclosed an internal path in the meantime."

§40.12 Evidence emitted

Order	EvidenceType	Condition	Payload highlights
1	AVAILABILITY_MASK (optical)	always	modality, sensor, canonical_channels, available_bands, band_map, availability_mask, missing_channels, missing_channels_zero_filled, normalization, resolution
2	AVAILABILITY_MASK (SAR)	always	same shape
3	OPTICAL_VIEW	always	sensor, rendered, retrievable: False, retrieval
4	SAR_VIEW	always	same shape
5	JOINT_FEATURE_REGION	when has_encoder	fusion_input_dim, expected_dim: 2318, encoder_dim: 768, modalities, mask_consumed_by: "fusion_head", croma_received_mask: False, n_patches, resolution
6	STATISTIC (decision)	when has_prediction	predicted_label, predicted_index, fusion_margin, class_probabilities
7	STATISTIC (no prediction)	when not	prediction_suppressed: True, reason, has_croma, trained_head — with score=None
8	STATISTIC (confidence)	always	confidence_components, confidence_weights, method: "uncalibrated"

Item 5 is the C-1 evidence: the two boolean fields state, in the published trace, that the mask was consumed by the head and that CROMA never received one. The rule is asserted in the evidence rather than only in the code.

Item 7's comment: "Deliberately a STATISTIC with no score: there is no decision to score, and inventing one would defeat the degradation path."

§40.13 model_refs and the path scrub

model_refs returns two entries — CROMA and FusionHead — and the CROMA revision is passed through core.errors.scrub_paths. The comment explains why this is load-bearing rather than tidying:

"The checkpoint path is a SERVER-SIDE diagnostic: describe() reports it in full so an operator can see exactly which file was loaded. This method does NOT stay server-side — core/controller.py:689 folds these refs into ExecutionTrace.selected_models, which is published, and API_CONTRACT.md section 7 records that v1 has no auth. So only the basename is published; the directory chain is reduced, the filename (the useful provenance) survives.

This is not hypothetical tidying. Before the CROMA checkpoint was reachable by default this field read 'unspecified'; wiring the encoder is what makes it an absolute path, so the scrub is part of that change rather than a follow-up to it."

The FusionHead entry reports f"trained params={n}" when a trained head is loaded, else "no trained artifact".

§40.14 build_optical_sar_specialist

build_optical_sar_specialist(config, *, checkpoint_path=None, vendor_dir=None,
                             head_path=None, artifact_dir=None, device=None,
                             class_labels=None)

Every model artifact is optional, with one exception:

"checkpoint_path that EXISTS but fails to load raises ModelLoadError, because a corrupt artifact must never be silently replaced by a degraded run: that is the difference between 'we do not have this' and 'we have it and it is broken'."

Note the asymmetry: CROMA is only constructed when checkpoint_path is given and exists. The resolve_checkpoint_path helper (§35.7) is the mechanism for supplying one without touching the config.

§40.15 The prompts

specialists/optical_sar/prompts.py (165 lines):

Symbol	Value
PROMPT_VERSION	"optical_sar_v1"
SYSTEM_PROMPT	"You are a remote-sensing analyst assistant. You explain results that have already been computed by measurement models. Do not invent facts, do not estimate confidence, and do not state coordinates or locations. If the supplied facts do not determine the answer, say so."

build_explanation_prompt(*, predicted_label, fusion_margin, optical_available, optical_total, sar_available, sar_total, query="", cross_modal_agreement=None) renders the narration prompt from already-computed facts:

"Every number below was produced by the specialist before this function runs. The prompt restates them; it never asks the model to derive them."

The prompt carries the availability facts explicitly, and the module gives the reason:

"The single most important thing a reader needs to know about an optical-SAR result is which bands were actually measured. 'Classified as urban, optical 4 of 12 channels available' is honest; 'classified as urban' alone invites the reader to assume a full Sentinel-2 scene."

The final instruction to the model is bounded: "Write two or three sentences… Use ONLY the facts above. Do not state a confidence value and do not state any location or coordinates."

build_messages(prompt) wraps it with a {"type": "image"} entry, and render_for_vlm(processor, prompt) delegates to apply_chat_template — raising when the processor lacks it (§5.4).

§40.16 The measured degradation

Driving a real 2-asset request (synthetic Cartosat + RISAT GeoTIFFs) with no checkpoint on disk:

degraded           : True
raw confidence     : 0.0
calibrated         : None
method             : 'uncalibrated'
components         : {optical_confidence: 0.333, sar_confidence: 1.0,
                      cross_modal_agreement: 0.0, has_croma: 0.0,
                      trained_head: 0.0, no_prediction: 1.0}
degradation_reason : 'CROMA is not loaded'

raw = 0.0, not a flattering mid-range value. Note optical_confidence = 0.333 — the synthetic Cartosat asset contributed 4 of 12 channels, which is 0.333, and that number is a measurement rather than a placeholder.

§40.17 The asset-count validation, measured

0 assets -> InvalidRequestError: optical_sar requires exactly 2 assets
                                 (one optical, one SAR); got 0
1 asset  -> ... got 1
3 assets -> ... got 3

§40.18 All seven modules import cleanly

The Phase 14 record notes this as a substantive check, not a formality: "All seven modules import without error under the project interpreter (.venv, torch 2.14.0+cpu) — which matters given that three separate 'written but never executed' import defects were found in earlier phases."

---

§41 Training and the production head

§41.1 The production head's identity

From artifacts/optical_sar/fusion_head_production_v001/production_head_record.json:

Property	Value
Artifact	fusion_head
Version	v001
Phase	12
Designated by	R-14 (owner ruling, 2026-09-21)
Source path	artifacts/optical_sar/fusion_head_v001/armA_seed103/head.pt
Production path	artifacts/optical_sar/fusion_head_production_v001/head.pt
Arm	A
Seed	103
sha256	785815729a3a39fc34dc41894efaf00d8739365d970a3f830a326e68ae888dab
Bytes	14,427,457
config_hash	78f1e3700da15aa1
best_val_accuracy	0.853
test_split_used_for_selection	false

head_config: input_dim 2318, hidden_dim 512, task_dim 19, dropout 0.2, head_parameters 1,201,711.

§41.2 The selection basis, and the rule that is not the deciding statistic

This is the most important part of the record, because the two selection rules are different and only one of them is a valid comparison.

Field	Value
arm_selection	"five-seed MEAN of best_val_accuracy (pre-registered; A_mean=0.837100 vs B_mean=0.839100, delta=+0.002000, floor=0.0285)"
production_head_selection	"highest best_val_accuracy among the RETAINED Arm-A seeds (post-experiment artifact-selection rule only)"
is_ab_deciding_statistic	false

Arm B's five-seed mean (0.839100) is higher than Arm A's (0.837100), and the difference (+0.002000) is far below the pre-registered floor (0.0285). So the A/B comparison is not decided — hence is_ab_deciding_statistic: false — and the production head is chosen by a separate, post-experiment rule among Arm A's retained seeds.

The five retained Arm-A candidates:

Seed	best_val_accuracy	sha256 prefix
100	0.83425	93009c4003eed39b
101	0.8245	24fbfbbaa84dafcf
102	0.8385	befc3588ec477c6e
103	0.853	785815729a3a39fc
104	0.83525	d9778ce9ca796b0d

arm_a_mean_best_val_accuracy is recorded as 0.8371, matching the mean above.

§41.3 The provenance guarantee

"The production head bytes are an unmodified, byte-identical copy (shutil.copyfile) of the trained Arm-A seed-103 artifact; no re-serialisation, re-pickling or tensor round-trip was performed."

Timestamps: created_at 2026-09-20T20:57:43.236778+00:00; source_metadata_mtime 2026-09-20T14:16:18.194491+00:00; source_metadata_created_at 2026-09-20T14:16:18.169577+00:00.

§41.4 What "19 classes" means here

DEFAULT_TASK_DIM = 19, and the 19 classes are the BigEarthNet CLC classes, not the CDVQA answer space. The specialist's constant comment says so: "BigEarthNet CLC class count, from fusion.num_classes." The class labels reach the specialist through the class_labels constructor argument, and _label_for falls back to f"class_{index}" when they are absent — so a deployment without labels still produces an index, and the absence of names is visible in the output rather than silently substituted.

---

§42 The measured result

§42.1 The headline, both numbers together

From artifacts/optical_sar/fusion_head_production_v001/pre_registered_115_metric.json:

Metric	Value
accuracy	0.931
macro F1	0.434161
loss	0.254592
num_classes	19
n_scored	4,000
split	test
head_sha256	785815729a3a39fc34dc41894efaf00d8739365d970a3f830a326e68ae888dab
bytes	14,427,457
cache arm	A
config_hash	78f1e3700da15aa1
is_deciding_statistic	false

The accuracy must never be quoted without the macro F1. docs/DOCS_STYLE_GUIDE.md §3: "Optical-SAR | accuracy 0.931 with macro-F1 0.434161; ruling OPEN. Never accuracy without macro-F1."

§42.2 The macro-F1 denominator is all 19 classes

"macro_f1_denominator": "all 19 classes (absent classes contribute 0.0)"

Property	Value
Classes scored	19
Classes present in the split	14
Classes absent	5

This is the single most important interpretive fact about the pair. A 0.931 accuracy with a 0.434161 macro F1 is not a contradiction — it is the expected shape of a skewed 19-class problem scored over all 19 classes including five with no examples, where those five contribute 0.0 to the macro average by construction. The denominator choice is recorded explicitly so the two numbers can be read together.

§42.3 The advisory and the ruling

The metric file carries an advisory string, and the ruling on this metric is OPEN (docs/DOCS_STYLE_GUIDE.md §3). The artifact also records is_deciding_statistic: false — the same flag the production-head record carries for the A/B comparison. Both flags say the same thing: this number was pre-registered and measured, and it does not, by itself, decide anything.

§42.4 The eval protocol

Property	Value
Metric file	pre_registered_115_metric.json
Pre-registration	Recorded before the measurement (docs/PHASE12_115_METRIC_COMPUTED.md)
n_scored	4,000
Split	test
Class space	BigEarthNet CLC, 19 classes
Cache arm	A (the fusion_features cache, not fusion_features_armB)

The Phase 12 records in the source tree include PHASE12_CURRENCY_CORRECTION.md, PHASE12_R08_TRUTHFUL_BACKFILL.md and PHASE12_LABEL_POLICY_DECISION.md, and a phase12_rerun_verification.json sits beside the production head — evidence that the metric was re-derived and the re-derivation verified. The specific contents of phase12_rerun_verification.json were not read for this chapter — UNKNOWN — not established from the available evidence.

§42.5 The class-label count tension

Two different "19"s appear in this subsystem:

19	Meaning
fusion.num_classes = 19	BigEarthNet CLC classes — the classifier's output width
The CDVQA 19 answers	§27.2 — the change-VQA answer space

They are unrelated. They are also both "19", which makes them easy to conflate in prose. The is_deciding_statistic: false flag and the DEFAULT_TASK_DIM comment are the two places the codebase disambiguates them.

---

§43 Optical-SAR: limitations

#	Limitation	Status
1	The metric ruling is OPEN	OPEN
2	Accuracy 0.931 must always travel with macro F1 0.434161, and the macro F1 is computed over all 19 classes including 5 with no examples	Structural; recorded as macro_f1_denominator
3	is_deciding_statistic: false on the headline metric	Recorded
4	The A/B arm comparison is not decided (+0.002000 against a 0.0285 floor)	Recorded; the production head is chosen by a separate post-experiment rule
5	The conditioning stage (percentile / dB) is NOT IMPLEMENTED, and the five optical.* / sar.* config keys are read by no code	OPEN — the one open item in the Phase 14 table, "not closed cosmetically"
6	The encoder-input transform is not a verified match to CROMA's pretraining distribution, which was never released	Recorded; the gated experiment is the only mechanism that could close it
7	The transform has never been run against the gated experiment's control arm	NOT RUN — the experiment is gated on the artifacts existing
8	mask_gain-style measurement of the mask's contribution	UNKNOWN — not established from the available evidence for this subsystem
9	No evaluation on the hidden Cartosat-2S + RISAT distribution	OPEN — the 4,000 scored records are BigEarthNet-derived
10	optical_view / sar_view are null on every path	By design (F-16)
11	phase12_rerun_verification.json was not read for this chapter	UNKNOWN — not established from the available evidence

---

Part F — Cross-cutting

§44 Evidence emitted, by specialist

core/schemas.py defines 11 EvidenceType members. The table below shows which specialist emits which, so a consumer can know what to expect from a task.

EvidenceType	vlm	grounding	change	change_vqa	optical_sar
BOUNDING_BOX	—	yes	yes	—	—
CHANGE_MAP	—	—	yes	—	—
AVAILABILITY_MASK	—	—	—	—	yes (×2)
OPTICAL_VIEW	—	—	—	—	yes
SAR_VIEW	—	—	—	—	yes
JOINT_FEATURE_REGION	—	—	—	—	yes
GEOLOCATION	—	yes	—	—	—
STATISTIC	yes	yes	yes (×2 or ×3)	yes (×2)	yes (×2 or ×3)
generated-text evidence	yes	—	—	—	—

Two rules every specialist's evidence obeys:

1. A suppressed claim is recorded as a STATISTIC, never as the claim's own type. The change specialist's withheld regions and the grounding specialist's dropped degenerate boxes are both STATISTIC items. "Emitting the boxes would defeat the suppression" (change), and the same reasoning applies to grounding.
2. A no-decision outcome carries score=None. The optical-SAR no-prediction item and the change withheld-region item both set score=None rather than 0.0, "because there is no decision to score, and inventing one would defeat the degradation path."

Three specialists also emit their confidence derivation as evidence, so the number is auditable rather than asserted: change (through the STATISTIC payload), change_vqa (through class_wise_change_estimate), and optical_sar (through the final confidence_components / confidence_weights item).

---

§45 The five confidence derivations, side by side

No specialist uses a fitted calibration. Every one declares method="uncalibrated", and each composes its components differently for a stated reason.

Specialist	Method string	Composition	Floors
vlm	(schema-valid / not-refused based)	(0.5·schema_valid + 0.5·not_refused) × input_usable	An unusable input zeroes the whole score (multiplier, not term)
grounding	uncalibrated	min(weighted_sum, peak_component) over {max_objectness 0.40, top_mean_objectness 0.35, score_contrast 0.25}	No boxes ⇒ no signal
change	uncalibrated	min(weighted_sum, registration_factor) over {registration_quality 0.50, mean_change_probability 0.30, component_stability 0.20}	suppressed / untrained / no regions ⇒ 0.0
change_vqa	uncalibrated	raw = the softmax of the chosen answer	No trained head ⇒ no answer at all
optical_sar	uncalibrated	weighted_sum over {fusion_margin 0.40, optical_confidence 0.20, sar_confidence 0.20, cross_modal_agreement 0.20}	no prediction / untrained head ⇒ 0.0

Three of the five use a min against a gating component rather than a pure weighted sum, and each one documents why:

Specialist	The component that gates	Why a sum alone would be wrong
vlm	input_usable	A fluent sentence about random bytes would retain most of its score
grounding	The peak objectness	One lucky spike would carry a flat score field
change	registration_quality	"an unregistered pair produces edge-change everywhere, which is exactly the bright, stable output that would win the sum"

Calibration status across the project. The style guide's fact table records: "Calibration | ECE went 0.013755 → 0.014929 — worse. Retained only because it is in the frozen config." So the project has a temperature-scaling implementation, it was measured, it made ECE slightly worse, and it is retained only because the frozen config names it. No specialist's method field reads anything other than uncalibrated in the code read for this chapter.

---

§46 The degradation matrix

What each specialist does when each of its artifacts is missing. This is the operational summary of §4.2.

Specialist	Missing artifact	Constructs?	Answers?	What the caller sees
vlm	base model / adapter	no	no	A load error. The adapter path is not silently replaced by the base model.
grounding	trained head	yes	yes, via zero-shot	degraded=True + the reason; boxes come from the zero-shot decode
grounding	head path named but corrupt	yes	yes, via zero-shot	HeadLoadReport.source="invalid" + the reason
change	trained checkpoint	yes	yes, from an untrained detector	degraded=True, trained_checkpoint: 0.0, confidence floored to 0.0, warning naming the untrained state
change_vqa	trained head	yes	no	answer="", degraded=True, method="unavailable", warning naming the missing piece
change_vqa	feature-spec mismatch	yes	no	The mismatch refusal naming both specs
optical_sar	CROMA	yes	no prediction	Sensor-side facts computed; has_croma: 0.0, confidence 0.0
optical_sar	trained head	yes	no prediction	Representation computed; trained_head: 0.0, confidence 0.0
optical_sar	a corrupt checkpoint	no	no	ModelLoadError

Two rows are the interesting ones, because they are the two places where the specialists disagree on purpose:

• change answers from an untrained model; change_vqa does not. The change specialist's output is a map, whose wrongness is visible. The change-VQA specialist's output is a word, whose wrongness is not. §32.5 states this argument in full.
• grounding answers via zero-shot when the head is absent; optical_sar does not answer at all when the head is absent. Grounding has a genuine parameter-free fallback that is worse but real; the optical-SAR fusion head has no such fallback, because a label requires a classifier.

---

§47 What is NOT RUN, OPEN or BLOCKED

Per the style guide's §4, every document ends with an explicit list. This is the specialists' list.

§47.1 NOT RUN

Item	Detail
Optical-SAR gated normalisation experiment	The control arm (normalize_input=False) exists; the head-to-head experiment "cannot run until CROMA weights exist and use_croma.py is vendored" — both now exist, but the experiment itself is not recorded as run
Grounding evaluation on the hidden Cartosat-2S + RISAT distribution	No such evaluation exists
A caption-specific quantitative metric	BLEU / ROUGE were excluded for the VQA endpoint; no caption metric was computed
A GPU latency figure for the VLM specialist	Only CPU figures (caption 11.6 s, VQA 5.5 s) are recorded
A mask_gain-style measurement for optical-SAR	Not established for this subsystem

§47.2 OPEN

#	Item	Owner of the gap
1	Change-VQA metric_ruling	The metric protocol is not finally ruled on
2	Optical-SAR metric ruling	Same
3	Optical-SAR optical.normalization / sar.representation read by no code	The one open Phase 14 table item — "not closed cosmetically"
4	Grounding head_threshold at top_k=20 is a config default, not a validation-selected optimum	Phase 13 calibration may revisit on validation only
5	Grounding max_candidates is 20 in config and 6 in serving	Documented and deliberate; the two produce different numbers
6	Change test number is LEVIR-CD-256, not directly comparable to published 1024-px figures	Documented, not resolved
7	change is VERIFIED and not wired into serving by default	Deliberate; needs the config-hash decision or the registry override
8	Change macro/pooled naming collision (§25.4)	Four distinct quantities, two similar names
9	Change-VQA default serving path may build an untrained feature extractor	Mitigated by the mismatch refusal
10	change_vqa runs the detector twice per change+language request	Needs controller artifact passing, which does not exist
11	The VLM adapter is USABLE_VERIFIED and ACCEPTANCE-REJECTED	Frozen by the forward rule: run 1 is closed, new work needs a new version
12	Optical-SAR A/B arm comparison is not decided (+0.002 vs a 0.0285 floor)	Recorded; is_deciding_statistic: false
13	Grounding's validation IoU (0.0946) is below the zero-shot eval baseline (0.0972), so training_metadata.json says beats_baseline: false	Explained by the val/eval gap (§16.6), not resolved numerically

§47.3 BLOCKED

Item	Blocked on
Anything requiring the hidden ISRO/SAC distribution	The data is not in this repository
The optical-SAR conditioning stage	An upstream source that endorses a percentile stretch or dB clip. None exists in CROMA_NORMALISATION_UPSTREAM_EVIDENCE.md.
A verified match to CROMA's pretraining distribution	The pretraining dataloader "was never released"

§47.4 UNKNOWN — not established from the available evidence

These are the honest gaps in this chapter, listed so they are not mistaken for omissions.

#	Gap
1	The full change-VQA question-type count list (present in run_record.json, not enumerated here)
2	Why change-VQA's two test sets differ by 4.6 accuracy points
3	The contents of artifacts/optical_sar/fusion_head_production_v001/phase12_rerun_verification.json
4	Whether the change-VQA MiniLM path uses the same effective truncation length as the router's encoder
5	A GPU latency figure for the VLM specialist
6	A caption-specific quantitative metric
7	Whether the 448 px resolution helps or hurts any metric other than the ones the rejection was based on

---

§48 Where the evidence lives

Every claim in this chapter is traceable to a file. This is the map.

§48.1 Source code (read in full)

Path	Lines	Subject
specialists/base.py	137	The Specialist ABC and SpecialistRequest
specialists/vqa/model.py	434	SmolVLM wrapper, F5-1..F5-4
specialists/vqa/inference.py	422	VLMSpecialist
specialists/vqa/prompts.py	130	Prompt set, PROMPT_VERSION
preprocessing/quality.py	348	The input-quality gate, F5-5
specialists/grounding/remoteclip.py	356	Frozen RemoteCLIP encoder, P7-1..P7-3
specialists/grounding/inference.py	270	Zero-shot baseline, the single decode
specialists/grounding/head.py	490	GroundingHead, decode, loss
specialists/grounding/specialist.py	853	GroundingSpecialist
specialists/change/stanet.py	694	The Siamese detector
specialists/change/postprocess.py	507	Registration, morphology, regions
specialists/change/specialist.py	916	ChangeSpecialist
specialists/change/vqa_specialist.py	616	ChangeVQASpecialist
specialists/optical_sar/croma.py	673	Frozen CROMA encoder
specialists/optical_sar/sensor_adapter.py	556	Band mapping + zero-fill + mask
specialists/optical_sar/radiometry.py	580	Encoder-input radiometry (DEV-2)
specialists/optical_sar/fusion_head.py	395	The frozen concatenation + head
specialists/optical_sar/inference.py	405	The pipeline
specialists/optical_sar/specialist.py	997	OpticalSarSpecialist
specialists/optical_sar/prompts.py	165	Narration prompts
training/change_vqa/vocab.py	349	The closed answer space
training/change_vqa/model.py	679	The two-stage head, the BCE defect
training/change_vqa/features.py	642	The frozen feature contract
training/change_vqa/prompts.py	225	Canonical query templates
training/change/train.py	—	The leakage guard, the sweep shape
training/change/dataset.py	—	The 7120/1024/2048 split

§48.2 Measured artifacts

Path	Carries
artifacts/vlm/phase6_closure.json	VLM exact_match 0.963 / f1 0.96432; the acceptance rejection; the preserved adjudications
artifacts/vlm/run1_test_recovery/	adapter_verification.json, run_manifest.json, test_adjudication.json
artifacts/grounding/remoteclip_grounding_v001/eval_result_canonical.json	0.2838 / 0.6882 / 0.5047 / 0.2198; top_k 20
artifacts/grounding/remoteclip_grounding_v001/eval_result_matched6.json	0.2566 / 0.6315 / 0.4545 / 0.1938; top_k 6
artifacts/grounding/remoteclip_grounding_v001/training_metadata.json	head_parameters 1,052,677; the 20-epoch history; beats_baseline: false
artifacts/change/levir_change_v001/training_metadata.json	best_val_iou 0.8232; the 20-epoch history; the val aggregate
artifacts/change/eval_test/eval_result.json	pooled IoU 0.8122 / F1 0.8964; macro IoU 0.7180 / mIoU 0.8457; the embedded config
artifacts/change/threshold_sweep_val.json	The threshold sweep (val only) — see 04-router.md §33
artifacts/change_vqa/run/PROMOTION.json	Both test sets; the identity block; the frozen dependency
artifacts/change_vqa/run/run_record.json	The dataset block; the optimization block; the 14-epoch history; the selection
artifacts/change_vqa/run/model_metadata.json	TRAINED_UNVERIFIED; test_splits_used: false; epoch 8
artifacts/optical_sar/fusion_head_production_v001/production_head_record.json	Arm A seed 103; the A/B means and floor; the five retained candidates
artifacts/optical_sar/fusion_head_production_v001/pre_registered_115_metric.json	accuracy 0.931 with macro F1 0.434161; the denominator; 14 present / 5 absent
artifacts/optical_sar/croma_forward.json	225 patches; the GAP and token shapes; 13/13 checks
artifacts/optical_sar/fusion_features/, fusion_features_armB/	The two cache arms

§48.3 Contract and decision records

Path	Subject
docs/PHASE5_VLM_CONTRACT.md	F5-1..F5-5; the 17-image measurement; the gate's measured behaviour
docs/PHASE7_GROUNDING_CONTRACT.md	P7-1..P7-3; the 224/448 contract table
docs/PHASE8_GROUNDING_HEAD_DECISION.md	The decode defect; the candidate-count defect; the matched delta; the val/eval gap
docs/PHASE9_GPU_RUN_RESULTS.md	The change test result and its five limitations
docs/PHASE14_OPTICAL_SAR_DECISIONS.md	DEV-1, DEV-2, DEV-3; the seven contract rows; the six outstanding items
docs/PHASE14_CROMA_NORMALISATION_CHANGE.md	The radiometry ruling; the ordered stages; the gated experiment
docs/CROMA_NORMALISATION_UPSTREAM_EVIDENCE.md	The upstream evidence search; the pretraining-dataloader gap
docs/R02_KAGGLE_TRAINING_GUIDE.md	The change-VQA run configuration and acceptance criteria
docs/ARCHITECTURE_FREEZE.md	§2.4 (registration), §2.5 (optical-SAR), §2.6 (CRS), §5 (prompts, no LLM confidence/coordinates)
docs/PHASE6_CLOSURE.md	The VLM closure narrative

§48.4 Sibling chapters

Chapter	For
04-router.md	How the task is chosen; the router-defect case study; the threshold sweep
06-evidence-and-confidence.md	What the emitted evidence means downstream; the EvidenceEngine
07-configuration-freeze.md	The 78f1e3700da15aa1 hash and why four modules route around it
03-request-lifecycle.md	How a specialist is called and how its result travels

---

Chapter summary

The six specialists, in one paragraph each.

vlm (vqa + caption) wraps SmolVLM-500M-Instruct at revision a7da5b986cb5 with a LoRA adapter that touches only model.text_model (8,683,520 of 516,165,824 parameters). Four Phase-5 findings shape the wrapper: the loader class is resolved by feature detection because AutoModelForVision2Seq is absent rather than deprecated; the processor is pinned to longest_edge=512 because the default produces 17 images and 1,142 tokens instead of one image; prompts are rendered through apply_chat_template because hand-built strings lack the required <image> tokens; and the dtype kwarg is resolved by a call-time fallback because neither from_pretrained signature exposes it. The specialist's confidence is (0.5·schema_valid + 0.5·not_refused) × input_usable — a multiplier, so an unusable input zeroes the score. The input-quality gate in preprocessing/quality.py blocks NOISE and INVALID_VALUES before the model is called, because F5-5 measured the model producing a fluent fabricated scene description from uniform random bytes with the strictest possible system prompt in place. Measured: exact_match 0.963, f1 0.96432 on 1,000 questions; status USABLE_VERIFIED and ACCEPTANCE-REJECTED, because one of 19 classes lost 12.1212 pp against a 2.0 pp ceiling while the aggregate improved by 49.5 pp.

grounding wraps RemoteCLIP ViT-B/32 at bf1d8a3ccf2d (151,277,313 parameters, projected dim 512 not 768 — finding P7-1) at 224 px (448 was rejected on a paired t of −22.63) and adds a 1,052,677-parameter head over 49 frozen patch tokens with a 2048-d per-cell feature concat([p_i, t, p_i·t, global_pool]). It is measured under two protocols — canonical head_threshold 0.2838 at top_k=20, and matched6 0.2566 at top_k=6 — and two decode variants — head_argmax 0.1215 and zero-shot 0.0972 — and the style guide's rule is that no single number may be quoted alone. The decode-matched delta is +0.1594 IoU and +0.1704 Recall@0.50 against a 0.02 bar. max_candidates is 6 in serving and 20 in config, deliberately. Its training_metadata.json says beats_baseline: false because it compares validation IoU (0.0946) against an eval baseline; the val/eval gap is a property of VRSBench, not a bug.

change is a STANet-shaped Siamese detector, reimplemented rather than vendored (finding C-9), with tied encoder weights, PAM spatial attention at layers 2–4 and skipped at layer 1 because 8×4096²×4 = 537 MB exceeds the 256 MB budget, and a composite BCE 0.5 + Dice 0.5 loss on LEVIR-CD-256's frozen 7120/1024/2048 split. It measures pooled IoU 0.8122, pooled F1 0.8964, macro IoU 0.7180, macro mIoU 0.8457 on 2,048 test tiles at threshold 0.5 — the project's only VERIFIED headline — and its checkpoint is deliberately not wired into serving, because adding change.checkpoint_path to base.yaml would move the frozen config hash and detach the benchmark from its own config. Registration is measured with cv2.phaseCorrelate before the map is trusted, and poor registration withholds the spatial claims while still returning the map.

change_vqa answers eight CDVQA question types over a closed 19-answer space with a 1,453,912-parameter two-stage head: stage 1 predicts a 13-value class-wise change estimate, and those 13 values are concatenated into stage 2's input, which is why the head can answer largest_change and smallest_change at all. Features are frozen (change_feat_v1, 1045-d) and cached, so training took 64.278 seconds against a 10,800-second budget and selected epoch 8 on validation answer accuracy 0.700018. Its first real run was killed by a saturated-sigmoid BCE defect — BCE(sigmoid(−30)) backward returns a finite −0.0936 instead of −1.0, which AdamW squares into 1e24 and which produced the measured epoch-1-to-2 collapse from val_acc 0.4388 to 0.2656 at confidence 0.9996; the fix is BCEWithLogits, which changes nothing the model emits. Measured on two test sets: test 0.697626/0.378373 and test2 0.651469/0.372309, ruling OPEN. With no trained head it returns no answer at all — because a wrong change map is visibly wrong and a wrong word is not.

optical_sar fuses CROMA-base (0dd28e3d633b, 194,365,440 parameters, asymmetric with s1_depth=6/s2_depth=12) with a 1,201,711-parameter head over the frozen 2318-wide concatenation 3×768 + 12 + 2. The availability mask is consumed by the head, never by CROMA (finding C-1), because CROMA is a masked autoencoder and handing it the mask would invite it to reconstruct bands no sensor measured. The sensor adapter zero-fills absent channels and records the truth in the mask; it refuses to invent a band, a polarisation or a position. Radiometry implements the encoder-input mean ± 2·std stretch per sample (not per batch, so an image's encoding never depends on its neighbours) and skips zero channels entirely rather than inventing a dynamic range — but the percentile/dB conditioning stage is deliberately not implemented, because no upstream source endorses it, so five config keys remain read by no code. The production head is arm A seed 103, chosen by a post-experiment rule because the A/B comparison (+0.002000 against a 0.0285 floor) is not decided. Measured: accuracy 0.931 with macro F1 0.434161, where the macro F1 denominator is all 19 classes including 5 with no examples — the two numbers must always travel together, and the ruling is OPEN.

What the six have in common. None invents a value: not a band, not a polarisation, not a coordinate, not a confidence, not an answer. Each distinguishes a missing artifact from a corrupt one, and each says which piece is missing rather than degrading silently. Each treats a signal gap as a zero rather than as a weak signal. Each emits evidence that is a projection of what it computed, with a STATISTIC item recording what it withheld and why. And each declares its confidence uncalibrated rather than implying otherwise — which is the honest state of the project's R-03 calibration contract.