release: add HF_RELEASE_VERIFICATION.md

HF_RELEASE_VERIFICATION.md

@@ -0,0 +1,142 @@
+# Hugging Face Release Verification
+
+**Phase:** 4 · **Date:** 2026-09-25 · **Repo:** https://huggingface.co/thundercode/SatQuery
+**Result:** **VERIFIED — all 6 artifacts byte-identical, all 4 support files present.**
+
+---
+
+## 1. What was released
+
+| Item | Detail |
+|---|---|
+| Repository | `thundercode/SatQuery` (model repo) |
+| Visibility | **public** (`private: false`) |
+| HEAD after release | **`55681e0cddb91a4a5655da98a49bc025e537b657`** |
+| `lastModified` | `2026-09-25T18:21:52Z` |
+| Files on Hub | **22** |
+
+## 2. Pre-flight inspection (what was already there, and what was done with it)
+
+| Existing file | Content found | Action |
+|---|---|---|
+| `README.md` | a **25-byte stub** — literally `---\nlicense: unknown\n---`, no content | **replaced** with the model card (nothing of value lost) |
+| `.gitattributes` | the standard Hugging Face **LFS routing template** — already routes `*.pt`, `*.safetensors`, `*.bin` through LFS | **left untouched** (it was already correct and is required for LFS) |
+
+**No useful content was overwritten.** The stub README contained no project information.
+
+## 3. Write permission
+
+Verified **before** uploading, by reading the token's own scopes from `GET /api/whoami-v2`:
+
+```
+auth.type                      : access_token
+auth.accessToken.displayName   : Workbuddy
+auth.accessToken.role          : fineGrained
+scoped[0].entity               : user thundercode
+scoped[0].permissions          : repo.content.read, repo.access.read, repo.write, …
+```
+
+`repo.write` is present, scoped to the `thundercode` user. This **closes** the earlier
+"write permission unproven" note from Phase 0.
+
+## 4. Uploaded contents
+
+| # | Path on Hub | Bytes |
+|---|---|---|
+| 1 | `README.md` (model card) | 26,767 |
+| 2 | `MODEL_CARD.md` | 7,002 |
+| 3 | `models/manifest.json` | 4,458 |
+| 4 | `models/checksums.sha256` | 642 |
+| 5–15 | `docs/*.md` (11 files) | ~84,000 total |
+| 16 | `change/head.pt` | 63,231,009 |
+| 17 | `change_vqa/head.pt` | 5,822,809 |
+| 18 | `optical_sar/head.pt` | 14,427,457 |
+| 19 | `grounding/head.pt` | 12,639,041 |
+| 20 | `router/adapter.pt` | 211,961 |
+| 21 | `vlm/adapter_model.safetensors` | 34,798,048 |
+
+Total released weight payload: **131,130,325 bytes (~125 MiB)** across the six trained artifacts.
+**No backbone weights are redistributed.**
+
+## 5. Independent verification (re-downloaded, not trusted)
+
+`release/tools/hf_verify.py` **re-downloads each artifact over direct HTTPS** and hashes the bytes it
+receives, comparing against the locally-computed sha256. It does **not** trust the upload step.
+
+| STATUS | hf_path | remote bytes | local bytes |
+|---|---|---|---|
+| **MATCH** | `change/head.pt` | 63,231,009 | 63,231,009 |
+| **MATCH** | `change_vqa/head.pt` | 5,822,809 | 5,822,809 |
+| **MATCH** | `optical_sar/head.pt` | 14,427,457 | 14,427,457 |
+| **MATCH** | `grounding/head.pt` | 12,639,041 | 12,639,041 |
+| **MATCH** | `router/adapter.pt` | 211,961 | 211,961 |
+| **MATCH** | `vlm/adapter_model.safetensors` | 34,798,048 | 34,798,048 |
+
+```
+artifacts verified : 6
+artifacts failed   : 0
+```
+
+Support files confirmed present: `README.md`, `MODEL_CARD.md`, `models/manifest.json`,
+`models/checksums.sha256` — all `OK`.
+
+### 5.1 A verification method that was itself wrong (recorded)
+
+The **first** verification attempt reported all six artifacts `DIFFER`, with every remote hash equal
+to `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855` — the sha256 of **empty
+content**. The cause was not the upload: `hf_hub_download` returned an empty file in this
+environment (a download-path problem), so the verifier hashed nothing.
+
+This was caught by a **second, independent method** (a direct `curl` download), which produced the
+correct hash `8527c3ed28a293e13293d48601d48e3ceafa137b9acabddaf5de31a58a509b5c` for
+`router/adapter.pt` — byte-identical to the local file, and confirmed to be a real PyTorch zip
+(`PK\x03\x04`, containing `adapter/data.pkl`).
+
+The verifier was then rewritten to use **direct HTTPS with proxies disabled**. It now reports
+6/6 MATCH. The failed first attempt is recorded because a verifier that silently hashes an empty
+file would have produced a **false failure** — and, with a different bug, could just as easily have
+produced a **false pass**.
+
+## 6. Cross-checks against independently-recorded hashes
+
+Two of the six hashes can be checked against values recorded elsewhere in the project, independent
+of this release:
+
+| Artifact | Recorded elsewhere | Computed here | Agree |
+|---|---|---|---|
+| `change_vqa_head` | `cfae5e43…d63a82a` (`artifacts/change_vqa/run/PROMOTION.json`) | `cfae5e43…d63a82a` | **yes** |
+| `vlm_lora_adapter` | `07c76a75…a5adf5e` (adapter provenance) | `07c76a75…a5adf5e` | **yes** |
+
+## 7. Access verification
+
+- The repository is **public** — the URLs resolve without a token.
+- `GET /api/models/thundercode/SatQuery` returns the repo with `private: false`, `gated: false`,
+  `disabled: false`.
+- Every artifact is retrievable at
+  `https://huggingface.co/thundercode/SatQuery/resolve/main/<path>`.
+
+## 8. Secrets
+
+**No secret was uploaded.** The uploaded set is: the model card, the manifest, the checksums, the 11
+docs, and the six weight files. No tokens, keys, environment files, or credentials exist in any
+uploaded file. The token used for the upload is **not** written into any released file.
+
+## 9. Reproduce this verification
+
+```bash
+export HF_TOKEN=...            # token with repo.content.read
+python release/tools/hf_verify.py
+```
+
+Exit code 0 with `artifacts failed : 0` means the release is intact. Committed output:
+`release/tools/hf_verify_report.txt`.
+
+## 10. Notes and caveats
+
+- The Hub's own **README metadata validator** emitted a warning during upload
+  (`empty or missing yaml metadata in repo card`) for one intermediate commit. The final README
+  carries full YAML frontmatter (`license: other`, tags, `pipeline_tag: image-to-text`).
+- The released docs are the **detailed** versions; the model card's relative links
+  (`docs/LIMITATIONS.md`, `models/manifest.json`) resolve because both are uploaded.
+- **The six artifacts are small trained modules over frozen backbones.** Anyone using them must also
+  fetch the pinned backbones listed in `models/manifest.json` / `docs/MODELS.md`.