# Plan: Provider blueprint (docs/providers.md)
**Created:** 2026-09-16 08:41

## Context

The provider contract is spread across `docs/prompts/__initial-prompt.md` §5,
the comments in `internal/provider/{provider,errors,check}.go`, `docs/architecture.md`
§5 and §11, `docs/kvm-provider.md`, and plan Step 2/3/8. Many rules exist only in
code: providerID must be self-contained, UID/CreatedAt must be read back, Create
must survive a crash partway through, calls must stop when ctx is cancelled,
decorators are wired in `cmd/main.go`, and so on. With "~5 providers soon", the
next provider author needs one blueprint. It should say what a provider MUST,
SHOULD or MAY do, show which features each existing provider (kubernetes, gcp,
kvm) actually implements (with file:line evidence), give a checklist for adding
one, and list the gaps.

Decisions (user): store in `docs/providers.md`; scope = current state plus a
separate "Gaps and proposed features" section (nothing implemented); wait for
`feat/provider-health` to merge, then branch off `main`.

## Step 0 — Save the plan; wait for the merge

- Right after ExitPlanMode, copy this plan to `docs/plans/2026-09-16-0841-provider-blueprint.md`
  and commit it on its own. The current branch is `feat/provider-health`, so the
  plan reaches `main` with that merge. CLAUDE.md requires the plan commit to
  come before any branching.
- Stop and wait for the user to confirm that `feat/provider-health` is merged.
  Then `git switch main && git pull`, and `git switch -c feat/provider-blueprint`.

## Step 1 — Collect evidence (read-only, in parallel)

Run 3 Explore agents at the same time, one each for `internal/provider/kubernetes`,
`internal/provider/gcp` and `internal/provider/kvm`, including their tests. Each
answers the **same questionnaire**, citing `file:line` for every answer and writing
"not implemented" explicitly when that's the case:

1. **Identity**: providerID format and parsing; what it carries (zone, host, namespace).
2. **Create**: how it stays idempotent (name lookup, 409, DomainLookupByName);
   whether it returns before the VM is up or waits; what happens when an earlier
   attempt crashed partway; which Placement fields are used or ignored; how
   cloud-init is delivered; how the port is used; how GC labels/UID are attached.
3. **Get**: native state → InstanceState mapping; IP discovery rules; UID and
   CreatedAt readback; how NotFound is detected.
4. **Delete**: idempotency; what gets removed (disks, volumes, seeds); returns
   before or after the resource is gone; unknown/malformed providerID behaviour.
5. **ListByTag**: scope (namespaces, zones, hosts); partial-failure behaviour; how
   managed resources are recognised.
6. **Error classification**: table of backend error → NotFound/Quota/Transient/
   Permanent; whether quota is detected at all.
7. **Health check** (`Checker`): targets, provider-specific Reasons, Details keys.
8. **Config**: YAML section, defaults, validation (`internal/provider/config*.go`),
   credentials/Secrets, which settings are read once per process.
9. **Connections and cancellation**: pooling, reconnects, timeouts, ctx honouring.
10. **Observability**: log keys and verbosity levels, spans (`kvm/trace.go`, gcp
    `wirelog.go`), anything beyond the shared metrics/tracing decorators.
11. **Testing**: fakes, envtest/kind, `//go:build integration` tests, what is
    not covered.
12. **Known gaps**: TODOs, stale comments, documented limitations.

Meanwhile, read the shared layer myself: `internal/provider/{provider,errors,check,
name,config,metrics,tracing}.go`, `internal/provider/registry/registry.go`,
`cmd/main.go` (registry wiring, decorator order, Checker collection), and the
places that consume the contract, so every MUST rule traces to a caller that depends on it:
`internal/controller` (error-class branching, ErrNotFound → replace/adopt),
`internal/gc` (UID, CreatedAt age skip, ListByTag errors),
`internal/providerhealth`. Then cross-check against the existing docs listed in Context.

## Step 2 — Write `docs/providers.md`

Sections:

1. **What a provider is**: a few sentences plus links to architecture.md §5/§11.
2. **The contract**: per method (Create/Get/Delete/ListByTag), MUST/SHOULD/MAY
   rules, each followed by *why*: the reconciler or GC behaviour it protects,
   linked to code.
3. **Error taxonomy**: what each class makes the reconciler do; how to map backend
   errors; "unclassified = transient" pitfall.
4. **Identity and GC labels**: providerID guidance, `LabelManaged`/`LabelUID`,
   CreatedAt, deterministic `NameFromUID`.
5. **Optional interfaces**: `Checker` (shared reasons, never fails as a whole,
   collected before decorators).
6. **Feature matrix**: one row per questionnaire item, columns kubernetes/gcp/kvm,
   cells `yes`/`partial`/`no` plus a short note. Put the file:line evidence in a
   compact per-provider notes subsection under the table, not in the cells.
7. **Adding a provider: checklist**: package layout, config section and validation,
   registry constructor, `cmd/main.go` wiring, Checker, error mapping with tests,
   `name`/label tests, integration test behind a build tag, provider doc page,
   architecture.md rows, demo script (optional).
8. **Gaps and proposed features**: current-state gaps per provider (e.g. no kvm
   quota detection, orphan volumes invisible to GC, Secret rotation needs a
   restart, ListByTag partial-failure inconsistency, stale `mock` references in
   `provider.go` comments), plus proposals that are clearly marked as not
   implemented. Only list them; don't design them.

Also: link it from `docs/architecture.md` (Components table → provider contract row)
and from the CLAUDE.md "Architecture" section. Leave per-provider docs where they are.

Follow the plan-execution convention: create `docs/plans-executions/2026-09-16-0841-provider-blueprint.md`
with the status checklist and step entries, and commit it with each step.

## Step 3 — Verify, then open the MR

- A verification agent (Explore) re-checks each matrix cell and each MUST rule
  against the cited file:line and reports any mismatch. Fix what it finds.
- Check that every relative link in the new and edited docs resolves (grep the
  `](` targets and `ls` each one).
- `go build ./... && go test -short ./...` as a sanity check (docs-only change,
  expected no-op).
- Push `feat/provider-blueprint` and open the MR against `main` via the Gitea API,
  following the project's push/MR memory note. After the user confirms, add a CHANGELOG.md entry.

## Critical files

- New: `docs/providers.md`, `docs/plans/2026-09-16-0841-provider-blueprint.md`,
  `docs/plans-executions/2026-09-16-0841-provider-blueprint.md`
- Edited: `docs/architecture.md` (link), `CLAUDE.md` (link)
- Read-only sources: `internal/provider/**`, `cmd/main.go`, `internal/controller`,
  `internal/gc`, `internal/providerhealth`, `docs/prompts/__initial-prompt.md`,
  `docs/kvm-provider.md`, `docs/gcp-vm-validation.md`