feat(migrations): 0068 guarded drop of build_assets_legacy (#114)

[TennyZhuang]

What

Removes build_assets_legacy — the credential-bearing full copy 0062 left behind (renamed the old build_assets → build_assets_legacy, copied every row into the new table by id, and deliberately did not drop it). That copy holds r2_key, signature, signing_credential_id, metadata_json and is maintained by nothing.

How — guarded, not a bare drop

An in-migration ⊇ assert runs BEFORE the DROP and aborts the whole migration if it fails, via a CHECK(ok=1) violation (portable; no RAISE/trigger, no TEMP table). It proves every legacy row has a live row with the same id and the same immutable columns — r2_key, file_hash, signature, signing_credential_id (IFNULL-compared). If any legacy row is not preserved, the migration aborts and build_assets_legacy is left intact. No export — the drop is provably lossless. (No-export is deliberate and authorized: an export would copy the credential material to a looser location; artin rejected it as a contradiction — prove-redundant-then-delete, don't pre-copy.)

metadata_json is excluded from the match: it is live-mutable derived data (delta from_version_code, download_count), so comparing it exactly would false-abort — the kind of false red that pushes an on-call to disable the guard.

Design (ruled by @gogo, #114 owner)

• Strict ⊇ + abort, whitelist mechanism retained but currently empty.
• Prod --remote COUNT (2026-08-18, read-only): 0 legacy rows unmatched in live (of 286 legacy / 321 live), 0 of them credential-bearing → no whitelist needed today.
• That count only proved id-match on a snapshot; it does not pre-green the per-column check, and new orphans could appear before this runs — so the strict abort stays unconditionally. A future red is a real signal, not noise.

Verification

• wrangler d1 execute --local: RED dataset aborts on CHECK constraint failed: ok = 1, build_assets_legacy survives (DROP never runs); GREEN dataset drops it (5 statements OK).
• worker/test/build_assets_legacy_drop_migration.test.ts (node:sqlite, stop-on-error matching D1) — 5/5: RED missing-row + RED mutation abort & preserve; GREEN ⊇, metadata-divergence, empty-legacy drop.
• Worker tsc --noEmit clean.

Operational note (must be known before deploying): if the assert ever goes red, the migration aborts and is not recorded in the ledger, so it re-runs and re-fails on every subsequent deploy — halting the entire Hands deploy pipeline, not just this drop — until the offending rows are triaged. That is correct (loud failure, not a silent drop). The diagnostic query in the file header lists offending rows using locator columns only (id, created_at) — never SELECT *, which would print credential columns.

Gates

• ✅ artin authorization — obtained (2026-08-18, this work's channel): artin authorized dropping this copy directly in the next migration and rejected retention/export. Not to be re-asked.
• ⬜ Security criteria review (@sentinel) — ⊇ semantics, the metadata_json exclusion, and the diagnostic credential scope. The one substantive design gate outstanding.
• ⬜ Migration watch-gate — deploy runs through the existing watch-gate (human-present at migration deploy). Merge/deploy execution is @gogo's lane (fix(docs): serve /docs/electron-sdk/ (worker allowlist) #114 owner / prod infra); this PR is the guarded migration + tests only.

🤖 Generated with Claude Code