docs/CHANGELOG.md

Changelog

All notable changes to SatQuery AI. Dates are ISO-8601. This changelog records what changed and what was verified, and marks unresolved items honestly rather than omitting them. It follows the same no-fabrication rule as the rest of the documentation set: an item that is NOT RUN stays NOT RUN, a REJECTED verdict is never softened, and a negative result is reported as one.

Status tags: RESOLVED · OPEN · CLOSED · DEFERRED · REJECTED · NOT RUN · BLOCKED · VERIFIED · MEASURED.

Conventions. Versions are the project's own release line, not the plan's phase numbers (owner decision D-5: the master plan's numbering is authoritative for phases; this changelog's numbering is the release line). Where an earlier statement in a linked document was later found wrong, the original is retained and a dated correction is appended — a retained-and-corrected record is more useful than a silently overwritten one (docs/OWNER_DECISIONS_2026-09-23.md, convention).

Related documents. ../MODEL_CARD.md · MODELS.md · BENCHMARKS.md · TRAINING.md · EVALUATION.md · LIMITATIONS.md · RESEARCH_NOTES.md · ARCHITECTURE.md.

---

[1.0.0] — 2026-09-25 — Final documentation, model release and archival freeze

The release that makes the project legible, citable and reproducible: repository documentation, a deep research/engineering documentation set, model documentation, a Hugging Face model release, a curated public repository, and a verified evidence archive.

Added

Repository documentation

• Repository README — 27 sections, from motivation through citation: the deployed topology, the six supported tasks, routing, the eight execution events, measured results, live validation, and known limitations. All 20 quoted metrics were verified against their source artifacts at the README's printed precision (release/tools/readme_metrics_report.txt → ALL CLAIMS VERIFIED).
• Eight real screenshots captured from the post-fix live run (release/repo/screenshots/), each confirmed to show a live run (run id + config hash 78f1e3700da15aa1 + specialist evidence), not a mock.

Deep architecture reference (hub + 10 chapters)

Chapter	Topic
docs/architecture/README.md	hub: thesis, sub-document index, cross-cutting principles
docs/architecture/01-system-overview.md	thesis, component inventory, frozen-backbone strategy
docs/architecture/02-deployment-topology.md	four tiers, gateway, tunnel, wake flow, cold start
docs/architecture/03-request-lifecycle.md	the nine-state controller, validation, tiling
docs/architecture/04-router.md	frozen MiniLM, the 5-head adapter, interpret() vs chooseTask(), lexical fallback
docs/architecture/05-specialists.md	all six tasks in depth
docs/architecture/06-evidence-and-confidence.md	evidence aggregation, temperature scaling, the eight events
docs/architecture/07-configuration-freeze.md	the registry, enforced invariants, the config hash
docs/architecture/08-api-contract.md	the four endpoints, envelopes, error codes
docs/architecture/09-frontend.md	the static pages, real-vs-preview, platform traps
docs/architecture/10-observability-and-ops.md	health, counters, traces, what is not observed

Research documentation — MODELS.md, BENCHMARKS.md, DATASETS.md, TRAINING.md, EVALUATION.md, DEPLOYMENT.md, REPRODUCIBILITY.md, LIMITATIONS.md, RESEARCH_NOTES.md, CHANGELOG.md.

Extended engineering-documentation set (added in the same release, deep-reference depth):

SECURITY.md, TESTING.md, GEOSPATIAL.md, DATA_PIPELINE.md, OPERATIONS.md, DEVELOPMENT.md, PERFORMANCE.md, GLOSSARY.md, FRONTEND.md, SERVING.md. See the complete documentation inventory below.

Model documentation

• MODEL_CARD.md — the Hugging Face model card, expanded to deep-reference depth in this pass: an overview; the six-artifact table with byte counts and full sha256; backbone dependencies with pinned revisions; intended and out-of-scope use; a per-artifact section (architecture, hyperparameters, training data, evaluation protocol, measured numbers, acceptance status, limitations) for each of the six artifacts; the full measured-performance table; the calibration negative result; the acceptance-status table; the evaluation gaps; the limitations; a training summary; provenance and verification; licence; and citation. Retains its YAML frontmatter (license: other, tags, pipeline_tag: image-to-text, config_hash: 78f1e3700da15aa1).
• models/manifest.json and models/checksums.sha256 — generated by reading the files (release/tools/generate_model_manifest.py), never typed by hand. Six artifacts, each with status: "PRESENT" and the frozen config hash. Two digests (change_vqa, vlm) agree exactly with values recorded independently at promotion/fit time — an external cross-check, not a self-consistency claim.

Metric verification tooling

• release/tools/verify_readme_metrics.py — walks every quoted metric to its source artifact and the exact key path inside it. Result: ALL CLAIMS VERIFIED (20/20), plus status assertions (VLM headline contains ACCEPTANCE-REJECTED; router corpus_limited with n_val 86; calibration ece_improvement negative). Output committed as release/tools/readme_metrics_report.txt.

Release

• Hugging Face release of the six trained artifacts to thundercode/SatQuery (public), with a verification record (../HF_RELEASE_VERIFICATION.md). Independent re-download over direct HTTPS confirmed 6/6 artifacts byte-identical, 0 failed. Total released weight payload 131,130,325 bytes (~125 MiB); no backbone weights are redistributed.
• Curated public repository target Anish-lab-blip/SatQuery-AI, with ../RELEASE_MANIFEST.md (42 files, 8,401,031 bytes, each with size and sha256, generated from disk).
• Evidence archive — scope set by owner decision G3 (artifacts/ verbatim, ~3.7 GB, requiring ZIP64), with an integrity-verified extraction and a documented remote location (owner decision G2: Hugging Face Hub).

This pass (documentation depth)

• MODEL_CARD.md expanded in place to deep-reference depth (see Model documentation above).
• CHANGELOG.md expanded in place — the full 1.0.0 entry, the earlier version entries (0.9.0 → 0.1.0), an Unreleased/Open section, and the complete documentation inventory below.

Changed

• The monorepo README.md was materially stale and is superseded by this release's README. The stale version called the frontend "hermetic — no backend calls", put Render/Codespace as "in progress", described a /v1/* contract, and pointed at the untracked deploy/ as the deployment source. All four were wrong.
• hf/ documentation was stale — it asserted the project "does not own any model weights … ships no weights, no binaries, and no large artifacts" and "has no Hugging Face credentials". Both were false at release time and are corrected.
• Documentation set expanded. Ten new deep-reference docs were added after RELEASE_MANIFEST.md and the Hugging Face upload were generated. Consequence, stated plainly: the release manifest (42 files) and the Hub's 26 markdown files do not yet include those ten documents. The manifest and the Hub listing are therefore stale relative to the local release tree and must be regenerated / re-uploaded before they can be treated as authoritative. See the inventory.

Fixed

• Router defect — "Where are the built-up areas in this image?" collapsed to vqa and answered "River". Fixed in the dispatch path and validated across three independent live passes (8/8 each). RESOLVED. (Details in 0.9.0.)
• Live-validation harness false positive — synthetic CDP key events were silently dropped when the window lacked OS focus, so the harness dispatched the page's default query and recorded a false pass. Fixed with pre-dispatch form-state assertions (q_ok, obs_ok, t0_ok). RESOLVED.
• Bundled EO change pair — the demo pair differed in shape (726² vs 736²) and errored (T1 and T2 must have the same shape). Replaced with a same-shape pair (both 720×720). RESOLVED (supersedes docs/FINAL_DELIVERY_REPORT.md §6).
• B-01 (Hugging Face header link) — previously BLOCKED; the link is now live on all 11 pages. CLOSED.
• Metric-verifier dotted-path bug — the resolver split the artifact key "0.50" on its own dot, producing a false NOKEY for the two grounding recall claims. Fixed to prefer the longest matching key at each step. RESOLVED.

Known issues at this release

• B-07 — transient tunnel-agent gaps; a request can hang or return 504. Patch prepared, NOT deployed. OPEN.
• B-02 — /api/health codespace_name carries a trailing \n. Cosmetic; the wake path strips it. OPEN.
• No LICENSE file exists in the source repository. OPEN.
• No system-level end-to-end benchmark exists. NOT RUN.
• Router test split never scored. NOT RUN.
• Calibration worsened ECE (0.013755 → 0.014929). Retained as part of the frozen config only.
• VLM adapter is ACCEPTANCE-REJECTED despite usable metrics (exact_match 0.963, F1 0.96432); the deployed path uses the unadapted model.
• optical-SAR and change-VQA rulings remain OPEN.
• GitHub push — at the time of release/RELEASE_EXECUTION_CHECKLIST.md Phase 5 the push to Anish-lab-blip/SatQuery-AI was BLOCKED (403 Resource not accessible by personal access token; the token was read-only for repository contents). Owner action.
• Release manifest / Hub doc set stale relative to the ten new deep docs (see Changed).

Deployment revisions at this release

Component	Revision
Frontend	2d7ae53b482d
Backend	89d80eaddec5
Inference	5a0936ace491
Public umbrella	3dcabd32da41

Live validation. 3 passes × 8 cases, 8/8 each, 24 live runs, 24 correct dispatches, 0 mock nodes, trace fill 94.4444 %. Representative real run ids: vqa run_ddf81a1c3871, caption run_15d7b9ecf594, grounding run_d124d8b9adea (3 regions, calibrated 0.52), change run_c6249437253d, optical_sar run_028b200fb710 (docs/FINAL_DELIVERY_REPORT.md §4).

The six released artifacts at this release

Generated identities from ../models/manifest.json; see ../MODEL_CARD.md §3 for the full table with source paths and cross-checks.

Task	Kind	File	Bytes	sha256 (full)
change	trained head	change/head.pt	63,231,009	c5ef31277b67aa01a593aec0eac503eeaccc6d674349fda20ca44c9cc6f8e9fa
change_vqa	trained head	change_vqa/head.pt	5,822,809	cfae5e43b97ca930f568dc5b8ae4f36b24e9ff717af226159802206ffd63a82a
optical_sar	trained head	optical_sar/head.pt	14,427,457	785815729a3a39fc34dc41894efaf00d8739365d970a3f830a326e68ae888dab
grounding	trained head	grounding/head.pt	12,639,041	93432f7034be91a8ffd9c1a84e3eeec00bed7832c043fe7f83d2be230284c6bb
router	trained adapter	router/adapter.pt	211,961	8527c3ed28a293e13293d48601d48e3ceafa137b9acabddaf5de31a58a509b5c
vlm	LoRA adapter	vlm/adapter_model.safetensors	34,798,048	07c76a75fa04624880ed7730590f5fdd7b145a8232e3c0af411c3c545a5adf5e

Every digest above is copied from ../models/manifest.json; consult the manifest, which wins over any hand-typed copy.

Total released weight payload: 131,130,325 bytes (~125 MiB). No backbone weights are redistributed.

Measured results at this release

Every row names its source artifact; all 20 numeric claims are checked by release/tools/verify_readme_metrics.py (ALL CLAIMS VERIFIED). The full annotated version is ../MODEL_CARD.md §8 and BENCHMARKS.md §1.

Capability	Metric	Value	Split / protocol	n	Status
Change	pooled IoU / macro IoU / pooled F1	0.8122 / 0.8457 / 0.8964	LEVIR-CD-256 test, thr 0.50	2,048	VERIFIED
Grounding	mean best IoU / recall@0.5	0.2838 / 0.2198 (canonical); 0.2566 / 0.1938 (matched6)	VRSBench	16,159	MEASURED (2 protocols)
Grounding	head-argmax / zero-shot IoU	0.1215 / 0.0972	canonical	16,159	MEASURED
Optical-SAR	accuracy / macro-F1	0.931 / 0.434161	held-out test, 19 classes	4,000	MEASURED, ruling OPEN
Change-VQA	accuracy / macro-F1	0.697626 / 0.378373 (test); 0.651469 / 0.372309 (test2)	two test sets	39,686 / 31,036	MEASURED, ruling OPEN
VLM (adapted)	exact_match / F1	0.963 / 0.96432	frozen 1,000-question subset	1,000	ACCEPTANCE-REJECTED
Router	overall ungated accuracy	0.965116	val, corpus-limited	86	MEASURED — TEST NOT RUN
Calibration	ECE before → after	0.013755 → 0.014929	val, T = 0.9773	16,441	MEASURED — worse
System	end-to-end accuracy	—	—	—	NOT RUN — none exists

Status of every claim at this release

The facts most likely to be misstated, and their correct form. These are the same statements the release README, the model card and the benchmark doc carry; they are repeated here so a reader of the changelog alone cannot misread the release.

Fact	Correct statement	Never say
Grounding	two protocols and two decode variants: canonical 0.2838/0.2198, matched6 0.2566/0.1938, head_argmax 0.1215, zero-shot 0.0972	"grounding is 0.28"
Calibration	ECE worsened 0.013755 → 0.014929; retained only because it is in the frozen config	"calibration improved confidence"
VLM adapter	metrics usable, status ACCEPTANCE-REJECTED; deployed path uses the unadapted model	"the VLM is accepted" / "the VLM is broken"
Optical-SAR	accuracy 0.931 always with macro-F1 0.434161; ruling OPEN; single-label subset only	"0.931 accuracy" alone
Change-VQA	two test sets, both quoted; ruling OPEN	"change-VQA is 0.70"
Router	0.965116 is validation, ungated, n = 86; test NOT RUN	"router test accuracy"
End-to-end	no system-level benchmark exists; none is claimed	any end-to-end accuracy
Change	pooled IoU 0.8122 / macro IoU 0.8457 / pooled F1 0.8964 — the only VERIFIED headline	treating it as system-level

Verification and reproduction at this release

# 1. Verify every quoted metric against its source artifact  (cheap, no GPU)
python release/tools/verify_readme_metrics.py
#    -> STATUS ... MATCH ... / RESULT: ALL CLAIMS VERIFIED

# 2. Verify the released artifact identities
sha256sum -c models/checksums.sha256
#    -> change/head.pt: OK  ... vlm/adapter_model.safetensors: OK

# 3. Re-download and re-hash the Hugging Face release (independent of the upload step)
python release/tools/hf_verify.py
#    -> artifacts verified : 6 / artifacts failed : 0

# 4. Regenerate the artifact manifest from disk (must not change any value)
python release/tools/generate_model_manifest.py

release/tools/readme_metrics_report.txt and release/tools/hf_verify_report.txt are the committed outputs of steps 1 and 3.

Compatibility and migration notes

• Frozen config hash. 78f1e3700da15aa1 is the sha256 of configs/base.yaml truncated to 16 characters. Every artifact records it. Editing the registry moves the hash and detaches every published number from its configuration — new defaults therefore live in code (e.g. DEFAULT_HEAD_PATH), not in base.yaml (owner decision D-4). A test (test_the_frozen_config_hash_has_not_moved) pins this.
• Grounding default semantics changed. head_path = None no longer means "no head" — it now means "use the shipped head if present." An explicit head_path still wins. Any caller that relied on None meaning "disable the head" must now pass a path that does not resolve (D-4).
• VLM adapter opt-in. The Phase 6 adapter is attached only when the SATQUERY_VLM_ADAPTER environment variable (or an explicit adapter_path argument) is set. It is not the deployed default.
• optical_sar capability reporting. /api/capabilities keeps available = false for optical_sar even though the capability is locally executable — the under-report is a statement about deployment certification, not about code, and two tests pin it (owner decision D-7).
• Phase numbering. The master plan's numbering is authoritative for phases; the repository's historical numbering is retained as history with a mapping (docs/PHASE_NUMBERING_MAP.md). This changelog's version numbers are the release line, independent of both (D-5).

---

[0.9.0] — 2026-09-25 — Router-defect sprint

The defect

Two functions with different information:

• interpret() — produces the console's reading; asset-count-blind (text only).
• chooseTask() — performs dispatch; asset-count-aware.

"Where are the built-up areas in this image?" collapsed to vqa and answered "River" instead of routing to grounding; "Where is the new airport?" behaved the same way. The defect was in the dispatch path's handling of spatial/lexical cues, so region queries fell through to the generic VQA specialist.

The fix

• The temporal slot in interpret() now derives from changeStem / pairWording / newAsChange.
• built was dropped as a change marker.
• The quantifier area was tightened to \barea\b.

Verification

Three commits deployed to the frontend; 3 independent live validation passes, 8/8 each — 24 live runs, 24 correct dispatches, 0 mock nodes, trace fill 94.4444 %.

Pass	Deployed HEAD	Result
1	ff46eba42b18 + d413d3672311	8/8
2	2d7ae53b482d	8/8
3	2d7ae53b482d	8/8

Both defect queries now dispatch to grounding:

Query	Run id	Dispatched
Where are the built-up areas in this image?	run_467ffa406f22	grounding
Where is the new airport?	run_46980ba55c62	grounding

Harness false positive — caught before it could lie

An earlier live-validation harness typed queries with synthetic CDP key events, which Chrome silently drops when the window lacks OS focus. The harness therefore dispatched the page's default query and still recorded a "result" — a false pass. Fixed by asserting form state before dispatch (q_ok, obs_ok, t0_ok) and using deterministic query entry (a js() value-set plus type_text() via CDP Input.insertText). The earlier 8/8 run was re-examined and confirmed not infected — its answers were query-specific and the query text was embedded in the answers.

Also in this sprint

• Wrote the delivery report and the handoff.
• Prepared (but did not deploy) the B-07 backend patch: it adds forward_unavailable (503) and upstream_timeout (504) codes plus the codespace_name .strip() fix; verified py_compile clean. Status: OPEN — prepared, NOT deployed.

RESOLVED for the router defect and the harness bug. Root cause and lessons recorded in RESEARCH_NOTES.md §3–§4.

---

[0.8.0] — 2026-09-24/25 — Deployment hardening

Topology settled

Browser → Cloudflare Pages (satquery.pages.dev)
        → Render hub (satquery-orchestrator)
        → outbound TUNNEL (/tunnel/agent long-poll)
        → GitHub Codespace (FastAPI inference, CPU)
        → models (change · change_vqa · optical_sar fusion · grounding · VLM/CROMA)
        → real ResultEnvelope → Render → browser

The tunnel exists because a forwarded Codespace port on a private repo returns 302. Deploy sources are three private repositories; the local deploy/ is stale/untracked and is not the deployed source.

The five historical backend blockers — closed

1. ASGI stack present in requirements;
2. $PORT read;
3. OPTIONS preflight handled;
4. fail-fast app construction;
5. adapter integrity compared against an expected digest.

Live topology verification (probed, not asserted)

Probe	Result
GET /api/health	200, agent_connected: true
GET /api/capabilities	200, six tasks each available: true
POST /api/infer {}	422 invalid_request
response header	x-satquery-transport: tunnel

Behaviour recorded (not fixed, because it is not a defect)

• Cold start is tens of seconds; the Render free tier sleeps and the Codespace may be stopped.
• transport_mode: auto fallthrough — in auto mode a tunnel timeout falls through to the forward path, burning wake_timeout_s (120 s) on a 302; worst case ≈ 249 s (150 + 120). Measured. This is the root shape of B-07 (OPEN).

RESOLVED for the five blockers; the auto fallthrough is documented and carried forward.

---

[0.7.0] — Grounding and change heads

Grounding — resolution frozen at 224

Trainable head over frozen RemoteCLIP ViT-B/32. 224 chosen, 448 REJECTED by a pre-registered paired test over all 16,159 VRSBench eval records: mean best IoU −0.0147, recall@0.5 −0.0022, recall@0.10 −0.0699, recall@0.25 −0.0243, at 1.59× the latency; paired 95 % CI [−0.0160, −0.0134], t = −22.63; 448 better on 8.5 %, worse on 20.9 % of records. The pre-registered rule and the paired test agree on 224, and the artifact records rule_changed_since_preregistration: false. RESOLVED. Evidence: docs/PHASE7_RESOLUTION_DECISION.md.

Head design: per-cell feature concat([patch, text, patch*text, global_pool]) = 4 × 512 = 2048; cell-relative (YOLO-style) boxes; exactly one positive cell per target (the one containing the ground-truth box centre); positive_confidence_weight: 20.0 to stop the 1-of-49 objectness collapse.

Change — the only VERIFIED headline

STANet-style Siamese detector on LEVIR-CD-256 (train 7,120 / val 1,024 / test 2,048), ResNet-18 + PAM, tile 256, threshold 0.50. Measured on the held-out test split (n = 2048): pooled IoU 0.8122 / macro IoU 0.8457 / pooled F1 0.8964 — the only headline in the project carrying the VERIFIED tag.

Optical-SAR — measured, ruling OPEN

CROMA-base fusion head (2318 → 512 → 19), mandatory channel/band dropout, availability mask consumed by the head (not CROMA). Sweep: 10 runs × 2 arms × seeds 100–104. Arm decision on best_val_accuracy: A 0.837100 vs B 0.839100, floor 0.0285 → Arm A retained (owner ruling R-14). Pre-registered 115-class metric on the held-out split (n = 4,000): accuracy 0.931 / macro-F1 0.434161, ruling OPEN. The 224 localisation floor for zero-shot grounding is 1/7 of image width per token, documented as a known limitation.

---

[0.6.0] — VLM adaptation

Training

SmolVLM-500M LoRA adapter (PEFT, r = 16, alpha = 32, dropout = 0.05, fp16; 224 target modules across q/k/v/o/gate/up/down_proj, all inside model.text_model; 8,683,520 trainable params = 1.6823 % of the 516,165,824-param base; seed 42). The vision tower was left untouched (trainable_subtrees = {"model.text_model": 8683520}; the 86,433,024-param vision model and the 11,796,480-param connector are in frozen_params).

Metrics usable, artifact REJECTED

Adapted exact_match 0.963, F1 0.96432, aggregate test delta +49.50 pp (46.80 → 96.30). But the pre-registered rule v002 passes V1 and fails its V2 per-class guardrail on the independent test split: class Mixed forest (n = 33) drops 12.1212 pp with lost_questions 4, z 2.1335 — failing both halves of v002. Per item V, a complete run that fails V2 is REJECTED.

Both rejection records are preserved (Run 1's own manifest under v001 on val; the test-split adjudication under v002 on test); the val-split ACCEPTED under v002 is recorded for completeness only and is not final acceptance — it decides on the same val subset that motivated v002.

Findings

• F5-1 — AutoModelForVision2Seq does not exist in transformers 5.17.0 (not merely deprecated); the loader class is resolved by feature detection over ("AutoModelForImageTextToText", "AutoModelForVision2Seq", "AutoModelForMultimodalLM").
• F5-2 — the processor's default longest_edge is 2048, which upscales a 512-px tile 4× and then splits it into 17 sub-images and 1142 prompt tokens. The plan estimated a 4× cost overrun; the real figure is ~17×. processor_longest_edge is pinned to 512 and enforced at config load.
• F5-3 — SmolVLM requires one <image> token per image; hand-written prompt strings raise ValueError, so prompts are always built through processor.apply_chat_template().

Closure

Phase 6 closed without retraining or modifying the adapter. Evidence: artifacts/vlm/phase6_closure.json, docs/PHASE6_CLOSURE.md. Two traps recorded: adapter_sha256 names a tree hash (5c6b8631…) and a file sha256 (07c76a75…), which are not interchangeable; and the promoted adapter is not checkpoint-2000.

---

[0.5.0] — Router

Architecture

A 50,822-parameter five-head adapter over frozen MiniLM embeddings (router/adapter.py): LayerNorm → Linear(384 → 128) → GELU → Dropout(0.10), then task_head (→6), modality_head (→4) and three binary heads temporal/spatial/language (each →1 logit). Heads use small-std init (std 0.02, zero bias) so the initial sigmoid sits near 0.5. The adapter does not back-propagate into MiniLM.

Training

Encoder frozen ⇒ embeddings cached ⇒ CPU-only training. Measured: 20 epochs over 4,096 × 384 vectors in 0.28 s. Config: 60 epochs, batch 64, lr 0.001, weight decay 0.01; loss weights task 1.0 / modality 0.3 / binary 0.5; val_ratio 0.15; hard_negatives_to_test: true.

Data and splits

A synthetic query corpus: 576 queries in 54 groups, split train 410 / val 86 / test 80. Splits are by group (template / hard-negative family), never by example, so template variants cannot leak across the boundary (finding F4-3). Hard-negative families are placed in the test split so their accuracy measures generalisation, not memorisation.

Validation-only threshold sweep

50 thresholds 0.50 … 0.99, select_by: covered_accuracy. Shipped threshold 0.70 (coverage 0.848837, covered accuracy 0.972603, fallback 0.151163, n_covered 73); the sweep's selected row is threshold 0.76 (coverage 0.790698, covered accuracy 1.0, n_covered 68). Overall ungated accuracy 0.965116 on val n = 86 — corpus-limited (plan minimum 500 val queries, 100 hard negatives; val carries 0 hard negatives by design). Test split NOT RUN (test_split_touched: false).

Deterministic fallback

A lexical fallback with ordered precedence and a self_check() against curated hard negatives, so the router degrades to a deterministic rule rather than to an arbitrary class when the adapter is low-confidence.

---

[0.1.0] — Foundation

• Monorepo; frozen configuration registry (configs/base.yaml); config-hash freeze (78f1e3700da15aa1); nine-state controller (RECEIVE → PARSE → VALIDATE → PLAN → PREPROCESS → EXECUTE → AGGREGATE → VERIFY → RESPOND); four-endpoint inference contract; evidence schema (Region / ChangeRegion / Evidence, max_items 32, coordinate system normalized_0_1); eight frontend execution events.
• Enforced invariants established at load time: fusion width 3 × 768 + 12 + 2 = 2318; grounding head feature 4 × 512 = 2048; CROMA image_resolution % 8 == 0 (native 120 → 225 patches); router max_length ≤ 256; VLM processor_longest_edge ≤ image.tile_size; change tile 256; VLM prompt_must_use_chat_template: true.
• Input geometry and normalisation frozen: image.max_pixels 25,000,000; tile_size 512; tile_overlap 128; max_tiles 64; top_k_tiles 4. Optical percentile 2–98; SAR dB clip [−30, 5].
• The rule that shaped every later decision: "no magic numbers anywhere in Python; everything tunable lives here" — and, from the outset, the no-fabrication rule that a missing dependency, corpus or checkpoint produces a diagnosable error, never a plausible number.

---

Unreleased / open

Item	State
Deploy the B-07 tunnel-fallthrough fix	prepared, NOT deployed
Score the router test split	NOT RUN
Build a system-level end-to-end benchmark	NOT RUN
Select a licence	OPEN
Resolve the optical-SAR and change-VQA rulings	OPEN
Plot the calibrated reliability curve	NOT RUN
Replace the illustrative benchmark adapter numbers with real runs	NOT RUN
Regenerate RELEASE_MANIFEST.md and re-upload the ten new deep docs to the Hub	NOT RUN
Push the curated release to Anish-lab-blip/SatQuery-AI (token scope)	BLOCKED — owner action
Fix B-02 (codespace_name trailing newline)	OPEN (cosmetic)
Cross-dataset, human, robustness and adversarial evaluation	NOT RUN

---

Documentation inventory shipped in 1.0.0

Every documentation file in the release tree. Sizes are the measured byte counts in release/repo/, as of the 2026-09-26 documentation pass. The "in manifest / Hub" column records whether the file was included in RELEASE_MANIFEST.md and the Hugging Face upload — the ten newest deep docs were written after both were generated, so they are present locally but not yet in the manifest or on the Hub.

Root-level documents

File	Purpose	Bytes	In manifest / Hub
README.md	repository front page (27 sections)	86,336	yes
MODEL_CARD.md	model card for the six trained artifacts (Hugging Face card)	57,166	yes (previous revision; expanded in this pass)
RELEASE_MANIFEST.md	every released file with size + sha256	10,402	yes
HF_RELEASE_VERIFICATION.md	independent HF re-download verification (6/6 MATCH)	6,443	yes

Research and engineering documents (docs/)

File	Purpose	Bytes	In manifest / Hub
docs/architecture/README.md	architecture hub: thesis, sub-document index, cross-cutting principles	7,672	yes
docs/MODELS.md	per-model detail: hyperparameters, acceptance status, measured params	103,145	yes
docs/BENCHMARKS.md	every measured metric with its artifact and protocol	55,999	yes
docs/DATASETS.md	dataset provenance, splits, leakage controls	67,723	yes
docs/TRAINING.md	training procedures and hyperparameters	90,697	yes
docs/EVALUATION.md	evaluation protocols and honesty rules	111,672	yes
docs/DEPLOYMENT.md	live topology, env vars, mechanics, traps	16,041	yes
docs/REPRODUCIBILITY.md	what can and cannot be reproduced	65,200	yes
docs/LIMITATIONS.md	the full limitation catalogue	8,356	yes
docs/RESEARCH_NOTES.md	engineering findings and negative results	11,513	yes
docs/CHANGELOG.md	this file	(this file)	yes (previous revision; expanded in this pass)
docs/MASTER_ARCHITECTURE_PLAN.md	the original master plan, included as a historical document	65,304	yes
docs/SECURITY.md	security posture, trust boundaries, rate limiting, secrets hygiene	114,342	no — new
docs/TESTING.md	the test suites, guards, and what is not covered	96,897	no — new
docs/GEOSPATIAL.md	CRS, transforms, alignment, coordinate systems	92,888	no — new
docs/DATA_PIPELINE.md	ingestion, extraction, feature caches, split policy	66,285	no — new
docs/OPERATIONS.md	running the system: health, counters, traces, runbooks	62,277	no — new
docs/DEVELOPMENT.md	local development, invariants, contribution mechanics	69,367	no — new
docs/PERFORMANCE.md	latency, memory, throughput, cost notes	52,946	no — new
docs/GLOSSARY.md	terms, abbreviations, status vocabulary	40,998	no — new
docs/FRONTEND.md	the static frontend: pages, real-vs-preview, platform traps	73,926	no — new
docs/SERVING.md	the serving path: endpoints, envelopes, error codes, wiring	75,797	no — new

Architecture reference (docs/architecture/)

File	Topic	Bytes	In manifest / Hub
docs/architecture/01-system-overview.md	thesis, component inventory, frozen-backbone strategy	8,376	yes
docs/architecture/02-deployment-topology.md	four tiers, gateway, tunnel, wake flow, cold start	85,979	yes
docs/architecture/03-request-lifecycle.md	the nine-state controller, validation, tiling	130,175	yes
docs/architecture/04-router.md	frozen MiniLM, the 5-head adapter, interpret() vs chooseTask()	262,652	yes
docs/architecture/05-specialists.md	all six tasks in depth	252,171	yes
docs/architecture/06-evidence-and-confidence.md	evidence aggregation, temperature scaling, the eight events	108,044	yes
docs/architecture/07-configuration-freeze.md	the registry, enforced invariants, the config hash	106,023	yes
docs/architecture/08-api-contract.md	the four endpoints, envelopes, error codes	127,341	yes
docs/architecture/09-frontend.md	the static pages, real-vs-preview, platform traps	78,287	yes
docs/architecture/10-observability-and-ops.md	health, counters, traces, what is not observed	104,695	yes

Generated artifacts and tooling

File	Purpose	Bytes	In manifest / Hub
models/manifest.json	generated manifest of the six trained artifacts (bytes + sha256)	4,458	yes
models/checksums.sha256	generated checksums, keyed by repository path	642	yes
tools/verify_readme_metrics.py	walks every quoted metric to its source artifact	6,911	yes
tools/readme_metrics_report.txt	its output (ALL CLAIMS VERIFIED)	4,027	yes
tools/generate_model_manifest.py	generates models/manifest.json + checksums.sha256 from disk	6,868	yes
tools/generate_release_manifest.py	generates RELEASE_MANIFEST.md from disk	4,100	yes
tools/hf_verify.py	re-downloads and re-hashes the released artifacts	3,878	yes
tools/verify_archive.py	verifies the evidence archive extraction	4,946	yes
tools/build_archive.py	builds the ZIP64 evidence archive	8,351	yes

Inventory totals. 4 root-level documents · 22 documents in docs/ · 10 architecture chapters · 9 generated-artifact / tooling files. 45 files. The ten newest deep docs (SECURITY.md, TESTING.md, GEOSPATIAL.md, DATA_PIPELINE.md, OPERATIONS.md, DEVELOPMENT.md, PERFORMANCE.md, GLOSSARY.md, FRONTEND.md, SERVING.md) are the only ones not yet reflected in RELEASE_MANIFEST.md / the Hub; regenerating the manifest and re-uploading is an Unreleased item above.

---

Where the evidence lives

Topic	Evidence
All measured metrics	artifacts/**/*.json, verified by release/tools/verify_readme_metrics.py
Release identity and byte counts	models/manifest.json, models/checksums.sha256, RELEASE_MANIFEST.md
Hugging Face release integrity	../HF_RELEASE_VERIFICATION.md, release/tools/hf_verify_report.txt
Router defect + 3 live passes	RESEARCH_NOTES.md §3–§4
Grounding resolution rejection	docs/PHASE7_RESOLUTION_DECISION.md
VLM rejection / Phase 6 closure	artifacts/vlm/phase6_closure.json, docs/PHASE6_CLOSURE.md
Optical-SAR metric	docs/PHASE12_115_METRIC_COMPUTED.md, artifacts/optical_sar/fusion_head_production_v001/pre_registered_115_metric.json
Owner decisions	docs/OWNER_DECISIONS_2026-09-23.md
Documentation reconciliation	docs/DOCUMENTATION_RECONCILIATION.md
Release execution state	release/RELEASE_EXECUTION_CHECKLIST.md, release/CURRENT_RELEASE_STATE.md