feat(adr-102): add kg admin verify-backup — validate a backup without restoring

[aaronsb]

What

A first-class CLI command to validate a kg-backup/2 file without restoring it, backed by a new server-side endpoint. Implements the maintainer-chosen architecture (Option A): the validation rules live once, in Python (scripts/development/lint/lint_backup.py); the CLI does zero validation logic — it uploads the file and renders the server's report. No cross-language drift.

$ kg admin verify-backup backup_full_20260601_231935.tar.gz
🔎 Verify Backup
  Format:   kg-backup/2
  Contents: 3994 concepts, 313 sources, 7108 instances, 8705 relationships, 68 vocabulary
  ✓ Valid backup (0 warning(s), 0 notice(s))

Pieces

Layer	Change
Image	api/Dockerfile + Dockerfile.rocm-host: COPY scripts/development/lint/ into the image. The oracle was only present in dev via the repo mount; this ships it so the endpoint works in production. Oracle stays stdlib-only / standalone.
Adapter	api/app/lib/backup_oracle.py (new): loads lint_backup by path (cached importlib), exposes validate_backup_object() → {ok, format_version, errors, warnings, notices, issues}.
Route	POST /admin/backup/verify: accepts .tar.gz/.json upload (same containers as /restore), runs the oracle + best-effort de-interned statistics, returns the report. Read-only — no graph access, nothing queued.
CLI	client.verifyBackup() + kg admin verify-backup [file] (positional path / --file from backup dir / interactive pick). Renders issues with codes + JSON-path locations, record counts, pass/fail verdict; exits nonzero on errors.

Permissions

Gated by backups:read — admin-default (migration 028/037 grant it to admin + platform_admin), and an admin can grant backups:read to any other role to delegate verification. Verify is read-only and strictly less privileged than restore, so it intentionally does not reuse backups:restore. (If you'd prefer a distinct backups:verify action, that's a small migration — flagged, not done.)

Naming

verify-backup is a clean sibling of backup/restore/backups (which are flat under admin). Converting backup into a subcommand group would have risked the existing leaf command, so a sibling was the low-risk choice closest to the requested kg admin backup verify.

Tests

tests/api/test_backup_verify.py (5): valid → ok; dimension-mismatch surfaced (E_CONCEPT_EMBEDDING_DIM); bad extension → 400; invalid JSON → 400; legacy format refused (E_LOWER_MAJOR). Live end-to-end verified against a real 16 MB archive. CLI builds clean.

⚠️ Deployment note

The COPY scripts/development/lint/ line is new, so the API image must be rebuilt/republished for verify to work in production (./publish.sh images). Not published from here — needs maintainer approval.

Follow-on (parked)

"Pick one ontology to restore out of a full backup" — a filtered restore that builds on this inspect/verify flow. Deserves its own design/ADR.

🤖 Generated with Claude Code