Write the kvm2 provider spec from the template

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-16 13:38:29 +00:00
parent 854856cf0f
commit 4bd9aae03b
2 changed files with 680 additions and 0 deletions
@@ -0,0 +1,55 @@
+# Execution: kvm2, a clean-room libvirt/KVM provider built from the provider contract
+
+Plan: [docs/plans/2026-09-16-1333-kvm2-provider.md](../plans/2026-09-16-1333-kvm2-provider.md)
+
+- [x] Step 0 — Plan file and branch
+- [x] Step 1 — The spec, `docs/kvm2-provider-spec.md`
+- [ ] Step 2 — Config wiring, IDs, state mapping, classify
+- [ ] Step 3 — Pure builders: domain and volume XML, metadata, seed
+- [ ] Step 4 — Transport, seam, decorator, fakes
+- [ ] Step 5 — Image cache and pool-space precheck
+- [ ] Step 6 — The four contract methods
+- [ ] Step 7 — Checker and the CRD comment
+- [ ] Step 8 — Deployment files, Makefile, integration test
+- [ ] Step 9 — Documentation
+- [ ] Step 10 — Milestone review
+- [ ] Step 11 — Real-host validation, changelog, MR
+
+## Step 0 — Plan file and branch
+
+`main` was fast-forwarded to the merge of PR #7 (`0dc25a1`), which carries the
+three provider documents, and `feat/kvm2-provider` was cut from it. The plan
+was committed alone as `854856c`. The pre-existing local modification of
+`.claude/settings.json` stays uncommitted throughout.
+
+## Step 1 — The spec, `docs/kvm2-provider-spec.md`
+
+2026-09-16 13:37. Written by the orchestrator, not a subagent, since the spec
+is the "specifics" a user hands to the implementer. All 24 entries answered;
+every Evidence line cites the v1 user guide, the 2026-09-04 execution log, a
+go-libvirt symbol, or the contract. Nothing was taken from
+`internal/provider/kvm/`.
+
+Design choices that go beyond the user's profile answers, all recorded in the
+spec: an adoption guard on `Create` (foreign UID is Permanent), a pool-space
+precheck mapped to `ErrQuotaExceeded`, a dedicated connection for image
+downloads so a cancelled poll cannot cut one off, the Checker on fresh
+connections rather than the pool, SSH authentication and host-key failures
+classified Permanent (v1 retried them forever), SSH material re-read on every
+dial so rotation needs no restart, kvm2's own metadata namespace (no adoption
+of v1 domains), and the shared `validateKVM` refactored to take the block name
+so messages say `kvm2.`.
+
+Checks run on the spec:
+
+```sh
+grep -c '^\*\*Answer:\*\*$' docs/kvm2-provider-spec.md      # 0 blank answers
+grep -n 'internal/provider/kvm/' docs/kvm2-provider-spec.md   # empty
+```
+
+plus the axis-code check against contract §4 headings and the path-existence
+loop from the docs-split log. All clean.
+
+Worth noting: the spec's entry 21 lists the concrete test name for every
+contract §11 item, so the later steps' briefs can quote it rather than
+re-derive the mapping.