@homeflare/alchemy 0.8.0 → 0.10.0

package/docs/adopt-verify.md

@@ -0,0 +1,108 @@
+# Adopt verifier — `adopted` must mean no-op
+
+`hf-adopt-verify` plans a stack with Alchemy's own planner, never writes, and reports for each row
+**without a state row** what the provider's `read` and its own `diff` said. It exits `0` only
+when every such row is a no-op. Run it before any gated deploy that adopts.
+
+```sh
+bunx --bun hf-adopt-verify --config alchemy.run.ts --stage live          # rows without state
+bunx --bun hf-adopt-verify --config alchemy.pbs.ts --stage live --all    # every row + deletions
+```
+
+Wrap it in the same credential lane the deploy uses (`bun ./scripts/with-mini-bao.ts --admin …`
+in the Proxmox stacks): a lane that cannot read an object sees it as absent, and the verifier
+then reports `create` for something that exists.
+
+## Why a plan line is not enough
+
+Measured in alchemy `2.0.0-beta.79`:
+
+- `Plan.ts`: when a row has no state, the engine calls `read` (the adoption probe). If the object
+  exists it sets `forceUpdateAfterAdoption`, calls `diff`, and turns a `noop` into `update`. The
+  node is `adopted` either way. Nothing is logged.
+- `Apply.ts`: `adopted` goes down the `update` branch and calls `reconcile` with `olds: undefined`.
+- So `alchemy plan` prints `(+) adopted` for a matching object **and** for a drifting one, and
+  the deploy reconciles both. Whether that writes is up to each family's `reconcile`.
+
+Measured on TB4, `pvesh get /cluster/tasks`, 2026-09-21: six `cephsetpool` tasks by
+`hf-provision@pve`, one per pool, on 2026-09-13 and again on 2026-09-20 — the deploys that
+adopted the three Ceph pools. `Proxmox.CephPool` sent `setpool` whenever the pool existed,
+whatever its diff said. It was the one PVE/PBS family that wrote on a no-op adoption, and it is
+fixed. [adopted-deploys.md](./adopted-deploys.md) shows what every family does.
+
+## Where the answer is taken from
+
+| looked at                  | what it offers                                                  |
+| -------------------------- | --------------------------------------------------------------- |
+| `alchemy plan` (CLI)       | the forced action only; `--detailed` is declared YAML, no JSON  |
+| `Plan.describePlan`        | serializable rows, again only the forced action                 |
+| `forceUpdateAfterAdoption` | a local variable; no log, no warning, no field on the node      |
+| `alchemy drift`            | rows **with** state only, and its non-dry run reconciles        |
+| `deploy --adopt --dry-run` | the adoption plan (`plan` has no `--adopt`), same forced action |
+| **the provider service**   | the raw `read` / `diff` answer, per FQN — used                  |
+
+The engine finds every provider in the Effect context by resource type. The verifier opens the
+stack the way `alchemy plan` does (`Alchemist.open`). It swaps each provider for a watched copy
+(`src/verify/spy.ts`) and runs `Plan.make` itself, so output resolution, state lookup, renames,
+the adoption probe and `adopt(…)` are all still Alchemy's. The copy records what `read` and
+`diff` answered. `reconcile`, `delete` and `precreate` are replaced with a refusal, so a
+verification cannot write even by accident.
+
+## The report
+
+```text
+      planned  diff      read       type        fqn
+FAIL  adopted  update    found      Test.Thing  drifted  changed: comment
+      the provider's diff says update: the deploy writes
+ok    adopted  noop      found      Test.Thing  same
+```
+
+| column    | meaning                                                                                  |
+| --------- | ---------------------------------------------------------------------------------------- |
+| `planned` | the engine's action — what `alchemy plan` prints                                         |
+| `diff`    | the provider's own answer before Plan.ts forced it; `none` = no diff; `not-run`          |
+| `read`    | `found`, `unowned` (the deploy needs `--adopt`), `absent`, `failed`, `not-read`          |
+| `changed` | declared fields whose live value differs, **names only**, same-named keys of props/attrs |
+
+A row is a no-op when `planned` is `adopted` or `noop`, the provider said `noop`, **and** no
+binding changes (Plan.ts diffs bindings separately and `reconcile` applies them anyway). An
+adopted row whose provider has no `diff` is not proven: the engine compared the declaration with
+itself. A row with state and no diff is trusted at `noop`, as `alchemy plan` trusts it. A stack
+task (an Alchemy action) that will `run` is always a failing row: no provider sees it.
+
+Exit codes: `0` all no-op (or nothing to verify), `1` any row is not, `2` the plan could not be
+computed (a provider died, an `adopt(false)` row is not ours, state unreadable). A gate should stop
+on anything but `0`.
+
+## Flags and API
+
+`--config` / `-c`, `--stage`, `--profile`, `--env-file` behave as in `alchemy plan`. The
+difference is that `--stage` is never guessed: it comes from the flag or `$ALCHEMY_STAGE`, or the
+run stops. `--all` adds every row with state (read again) and every pending delete. `--json`
+prints the report.
+
+```ts
+import { verifyStack, formatReport, exitCodeOf } from '@homeflare/alchemy/verify';
+
+const report = await Effect.runPromise(
+  verifyStack({ entrypoint: 'alchemy.run.ts', stage: 'live' }),
+);
+```
+
+`verifySession({ stack, context })` takes an already-opened session. The kit's own tests pass it
+a compiled stack (`src/verify/fake-engine.ts`).
+
+## Limits
+
+- ⚠️ **`noop` covers what the family compares.** A family's `diff` and its `reconcile` guard share
+  one predicate (`matches`). A field that `matches` leaves out is never written on a no-op
+  adoption and never reported. `Proxmox.CephPool` `target_size_ratio` is the known case.
+- ⚠️ **`changed` is a hint, not the verdict.** It compares same-named keys. A family whose
+  attributes rename or normalise a field shows nothing there, and its `diff` still decides.
+- ⚠️ **Reads are what `alchemy plan` does.** A kit PVE/PBS read mints a lease through OpenBao,
+  which creates a short-lived API token on the cluster. `--all` adds one read per row with state.
+- ⚠️ **Outside the kit, `noop` is only the diff's word.** For a kit PVE/PBS family, `noop` means
+  the deploy writes nothing ([adopted-deploys.md](./adopted-deploys.md)). For any other provider,
+  `noop` means its diff found nothing. Whether its `reconcile` still PUTs is up to that provider.
+- It runs where `alchemy` runs: under bun it needs `@effect/platform-bun`, as the Alchemy CLI
+  does. Like `alchemy plan`, it writes a run log under `.alchemy/log/` in the working directory.

package/docs/adopted-deploys.md

@@ -0,0 +1,85 @@
+# What a deploy does to an adopted PVE/PBS row
+
+Traced through the source on 2026-09-21, for every family the Proxmox and PBS stacks use. A row
+**without state** that the adoption probe finds is planned `adopted` and reconciled, even when
+its diff said `noop` (alchemy beta.79 `Plan.ts` `forceUpdateAfterAdoption`, then `Apply.ts`).
+This page answers one question: does that reconcile write when live already equals declared?
+
+**Answer: no, for every family below. `Proxmox.CephPool` did until this change.** Its
+hand-written reconcile PUT `setpool` whenever the pool existed. It now skips the PUT when its own
+`matches` holds. `src/proxmox/update-guard.ts` is the one predicate that `resource.ts`,
+`ceph-pool.ts` and `pbs-datastore.ts` share. `hf-adopt-verify` ([adopt-verify.md](./adopt-verify.md))
+reports the diff that decides it, before the deploy.
+
+## The shared path — every `pveHandlers` family
+
+One `alchemy deploy` plans, then applies, in one process. For a row with no state:
+
+| step                 | calls (path is the family's `path`)                                                              |
+| -------------------- | ------------------------------------------------------------------------------------------------ |
+| plan: adoption probe | `GET path`                                                                                       |
+| plan: `diff`         | `GET path`; `matches` → `noop` or `update` (printed `adopted`)                                   |
+| apply: `reconcile`   | `GET path`; **PUT only when `matches` is false** and the form is non-empty; `GET path` read-back |
+
+So a matching adoption costs **four GETs and no write**. A drifting one adds exactly one
+`PUT path` carrying the family's `updateForm`. Each GET goes out on a lease, and each role's lease
+is minted once per run (`lease-cache.ts`). The mint is an OpenBao call that creates a short-lived
+API token on the cluster, just as it does for `alchemy plan`.
+
+## Per family
+
+| family                         | read path                                                       | lease       | reconcile on a no-op adoption                                                                        |
+| ------------------------------ | --------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------- |
+| `Proxmox.Pool`                 | `pools/{poolid}`                                                | read        | shared path: GET, GET — no write                                                                     |
+| `Proxmox.Storage`              | `storage/{storage}`                                             | provision ¹ | shared path — no write                                                                               |
+| `Proxmox.Role`                 | `access/roles/{roleid}`                                         | read        | shared path — no write                                                                               |
+| `Proxmox.Group`                | `access/groups/{groupid}`                                       | read        | shared path — no write                                                                               |
+| `Proxmox.User`                 | `access/users/{userid}`                                         | read        | shared path — no write                                                                               |
+| `Proxmox.BackupJob`            | `cluster/backup/{id}`                                           | read        | shared path — no write                                                                               |
+| `Proxmox.MetricServer`         | `cluster/metrics/server/{id}`                                   | read        | shared path — no write                                                                               |
+| `Proxmox.NotificationTarget` ² | `cluster/notifications/endpoints/{type}/{name}`                 | read        | shared path — no write                                                                               |
+| `Proxmox.HaResource`           | `cluster/ha/resources/{sid}`                                    | read        | shared path — no write                                                                               |
+| `Proxmox.HaRule`               | `cluster/ha/rules/{rule}`                                       | read        | shared path — no write                                                                               |
+| `Proxmox.SdnZone`              | `cluster/sdn/zones/{zone}`                                      | provision ¹ | shared path — no write                                                                               |
+| `Proxmox.SdnVnet`              | `cluster/sdn/vnets/{vnet}`                                      | provision ¹ | shared path — no write                                                                               |
+| `Proxmox.SdnSubnet`            | `cluster/sdn/vnets/{vnet}/subnets/{id}`                         | read        | shared path — no write                                                                               |
+| `Proxmox.Lxc` ³                | `nodes/{node}/lxc/{vmid}/config`                                | read        | own: GET, `judge` finds no drift so no `PUT …/config`, GET — no write                                |
+| `Pbs.PruneJob`                 | `config/prune/{id}`                                             | read (PBS)  | shared path — no write                                                                               |
+| `Pbs.SyncJob`                  | `config/sync/{id}`                                              | read (PBS)  | shared path — no write                                                                               |
+| `Pbs.VerifyJob`                | `config/verify/{id}`                                            | read (PBS)  | shared path — no write                                                                               |
+| `Proxmox.Acl`                  | `access/acl` (whole list, filtered)                             | provision ¹ | shared path, then its own `bound` check — no write                                                   |
+| `Pbs.Datastore`                | `config/datastore/{name}`                                       | read (PBS)  | own: GET, path/backend guards, PUT skipped on `matches`, settle GET — no write                       |
+| `Proxmox.SdnApply`             | 5 × `cluster/sdn/*?pending=1` + fabrics `?pending` / `?running` | read        | own: counts staged objects; zero returns at once — **no `PUT /cluster/sdn`**                         |
+| `Proxmox.CephPool` ⁴           | `nodes/{node}/ceph/pool/{name}/status?verbose=1`                | read        | own: GET, **PUT skipped on `matches` (was: always `PUT nodes/{node}/ceph/pool/{name}`)**, settle GET |
+
+¹ These object reads are gated on an allocate privilege, so the family reads with the provision
+lease (`readRole`, resource.ts). That is still a read.
+² The PVE notification endpoints: `smtp` (the mail target), `sendmail`, `gotify`, `webhook`. The
+secrets are never props (notification-target.ts), so no write is ever needed to "reset" them.
+³ Rewritten 2026-09-21 (PR 80, [proxmox-lxc.md](./proxmox-lxc.md)): its own reconcile, and its
+probe answers `Unowned`, so the deploy needs `--adopt`. Its `diff` also logs the keys a deploy
+would write, by name. Pinned by `src/proxmox/lxc-adopt.test.ts` ("deploys with no write").
+⁴ `updateBody` sends `target_size_ratio`, but `matches` does not compare it (float equality). A
+declared ratio that differs from the live one is never written on a no-op adoption and never
+reported as a diff.
+
+## Before the fix: `Proxmox.CephPool`
+
+`reconcile` read the pool and, whenever it existed, PUT the declared `size`, `min_size`,
+`pg_autoscale_mode`, `crush_rule` (and any declared hints) to `nodes/{node}/ceph/pool/{name}`.
+That PUT forks a `cephsetpool` worker under the provision token. PVE's `set_pool` skips each
+setting whose value is unchanged (Tools.pm:293-300), so a matching pool was not re-tuned. It was
+still a provision-lease write and a task on the node every time the pool was adopted. TB4's task
+list shows six such tasks (2026-09-13 and 2026-09-20), one per declared pool per deploy.
+
+## How it is pinned
+
+- `src/proxmox/ceph-pool-adopt.test.ts` runs the real CephPool provider through Alchemy's Plan
+  and Apply over a fake cluster. A matching pool gets GETs only. A drifted one gets exactly one PUT.
+  On the old reconcile the first test fails with that PUT.
+- `src/proxmox/adopt-noop.test.ts` does the same for each reconcile shape: the shared path
+  (`Proxmox.Pool`), the wrapper (`Proxmox.Acl`), and the two hand-written ones (`Pbs.Datastore`,
+  `Proxmox.SdnApply`). A drifted Pool row proves the harness sees a write when there is one.
+- `src/verify/verify.test.ts` pins Alchemy's own behaviour: `adopted` for a match and for a
+  drift, and a reconcile for both. If an Alchemy upgrade changes that, the test fails and this
+  page needs re-reading.

package/docs/credentials.md

@@ -0,0 +1,15 @@
+# Credentials
+
+Moved out of the README (2026-09-21) to make room under its 200-line cap; the text is unchanged.
+
+`CLOUDFLARE_API_TOKEN` is read from the environment at call time, never at module scope.
+`MeshNode` instead resolves credentials and the account the way `Cloudflare.providers()` does
+(an Alchemy profile, or `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` in CI).
+
+⛔ **Mint a short-lived, scoped token** — do not reuse a long-lived one, and never a Global
+API Key. An empty value fails closed with a message saying so, because an empty render is
+a denied grant rather than a missing file, and `Bearer ` + nothing 401s in a way that reads
+like a bad credential.
+
+The Proxmox subpath mints every call's token from an OpenBao mount instead; see
+[proxmox.md](./proxmox.md).

package/docs/launchd-sudo.md

@@ -9,8 +9,9 @@ argv shapes, logging each one. It is an explicit opt-in: nothing falls back to i
 import { launchdProviders, sudoRunner } from '@homeflare/alchemy/launchd';
 
 const runner = sudoRunner({
-  // ⛔ Required: the directories root may write. Each must be a real directory that root owns
-  //   and only root may write; that is checked at every privileged call.
+  // ⛔ Required: the directories root may write. Each — every directory above it, and every
+  //   directory below it on the way to a file — must be one that root owns and only root may
+  //   write, by mode bits and by ACL; that is checked at every privileged call.
   prefixes: ['/Library/LaunchDaemons', '/opt/example'],
   // log: (line) => …, // default: one line on stderr per privileged call
 });
@@ -45,6 +46,12 @@ Each is `/usr/bin/sudo -n -- <argv>`, every program by absolute path, never thro
 
 ★ So **a plan never calls sudo.** `read` and `diff` are reads; only an apply elevates.
 
+★ **A plan that will write runs the checks below first** (`HostRunner.checkWrite`): a `HostFile`
+or `LaunchdJob` diff that plans an update or a replace asks the runner, as you, whether it would
+refuse that write. A refusal then fails the plan before any resource is applied, instead of the
+apply halfway through. A create has no diff, so its refusal still comes at the write — before
+sudo.
+
 ## Refused before sudo is asked
 
 - Any other argv. That includes a bare `bootout system` (which removes the whole system domain),
@@ -57,6 +64,24 @@ Each is `/usr/bin/sudo -n -- <argv>`, every program by absolute path, never thro
   the next boot.
 - A prefix that is missing, a symlink, not owned by root, or writable by group or other. ⛔ A
   symlinked prefix makes root write wherever it points, a path the log never names.
+- **A directory between the prefix and the file** that is not owned by root, or that group or
+  other may write (checked since 0.9.0). ⛔ Its owner, or anyone who may write it, could swap
+  what lies under it for a symlink between the check and the call.
+- **A directory above the prefix**, from `/` down, that is not owned by root or that group or other
+  may write (red team, 2026-09-21). ⛔ Whoever may change the prefix's parent may rename the prefix
+  away and put a symlink in its place: the same swap, one level up. A root-owned symlink among them
+  (`/etc` -> `private/etc`) is root's own and is followed.
+- **An ACL from `/` down to the file that grants a write right** (`add_file`, `add_subdirectory`,
+  `delete_child`, `delete`, `write`, `append`, `writesecurity`, `chown`), read with `ls -lden` as
+  you. ⛔ On macOS an ACL entry can hand another user exactly the swap the mode bits forbid, and an
+  inheritable `allow write` hands them every file root installs there. Deny entries (a home
+  folder's `everyone deny delete`) and read-only rights refuse nothing; ACLs that cannot be read
+  refuse. Measured 2026-09-21: `/Library/LaunchDaemons`, `/private/etc`, `/opt` and `/usr/local`,
+  and everything above them, carry none.
+- **A root-owned file that would be group- or world-writable, setuid or setgid** (`mode & 0o6022`;
+  an omitted owner is root). ⛔ Anyone in that class could rewrite a file root installed (a
+  daemon's config, a script it runs), and a setuid root file runs as root for whoever executes it.
+  A file handed to another user (`owner`) is theirs to change, so its mode is theirs too.
 - A path outside every prefix that needs root: another user as the owner, say.
 - A symlink or missing directory between the prefix and the file, or anything but a regular file
   at the path. ⚠️ `install src <directory>` copies _into_ the directory, and a symlink to one does
@@ -115,8 +140,8 @@ record of what ran as root.
   remove, then an add.
 - ⚠️ **Under a prefix, the runner writes as root.** An omitted owner is root, and an omitted group
   is the directory's group (a new file's group on macOS).
-- ⚠️ **The checks guard against a mistaken declaration, not against a hostile one.** They run as
-  you, just before the call. The prefix itself must be root-only, but a directory _below_ it that
-  another user owns is not checked for that, and that user could swap what lies under it in
-  between. Keep every directory under a prefix root-owned, too. ACLs are not read, only mode bits.
+- ⚠️ **The checks run as you, just before the call.** Every directory from `/` down to the file
+  must be root-only, by mode bits and by ACL, so no other user can swap a path in between; root
+  itself still could. The target of a root-owned symlink above the prefix is root's choice and is
+  not walked.
 - ⛔ **macOS hosts.** Every argv shape was checked against macOS 27.2 man pages.

package/docs/launchd.md

@@ -87,8 +87,9 @@ The plist path is derived, never declared: `/Library/LaunchDaemons/<label>.plist
 it becomes visible — then renamed over the path. Read back after every write. Diffed by SHA-256,
 mode and owner. A new `path` is a create-before-delete replace. Delete removes the file.
 
-- ⛔ A different file already at a new `path` is refused, not overwritten: the adoption probe
-  never looks at a replace's new path, so a typo there would otherwise overwrite a system file.
+- ⛔ A different file already at a new `path` is refused, not overwritten, `--adopt` or not: the
+  adoption probe never looks at a replace's new path, so a typo there would otherwise overwrite a
+  system file.
 
 - ⛔ A symlink or directory at the path is refused, never replaced: rename over a symlink replaces
   the link, which takes the path from whatever tool owns it (nix-darwin's `/etc` entries point
@@ -126,7 +127,10 @@ you deploy as.
 ## Adoption: nothing is taken over silently
 
 `read` with no prior state reports anything it finds — a loaded label, a plist, a file — as
-`Unowned`, so Alchemy refuses to take it over without `--adopt`.
+`Unowned`, so Alchemy refuses to take it over without `--adopt`. Where the plan never asked (a prop
+still an `Output`), `reconcile` refuses the same takeover, and `--adopt` or the resource's own
+`adopt(true)` lets a create (or an interrupted generation) through there too — never a fresh
+replace's new path or label. The whole rule: [ownership.md](./ownership.md).
 
 Labels under `org.nixos.`, `com.apple.` and `homebrew.mxcl.` are **refused outright**. nix-darwin
 rewrites its plists on every activation and unloads any it no longer lists, macOS owns

package/docs/ownership.md

@@ -0,0 +1,113 @@
+# Ownership — nothing is adopted without `--adopt`
+
+A live object this stack holds **no state for** is never taken over silently. That holds for every
+`Bao.*` family, `HostFile`, `LaunchdJob`, `CaddyConfig` and `ProxmoxLxc`, and it holds even when the
+live object is **identical** to the declaration: identical is not ours. Another stack, a person or an old
+script put it there, and once state claims it, a delete under `RemovalPolicy.destroy()` removes it
+from its real owner. (Decided 2026-09-21; the Bao families adopted silently until 0.9.0.)
+
+To take an object over, say so:
+
+```sh
+alchemy deploy --adopt --dry-run  # read it first: `alchemy plan` has no --adopt (beta.79)
+alchemy deploy --adopt            # every resource in this deploy
+```
+
+⚠️ Only `deploy` declares `--adopt` in alchemy 2.0.0-beta.79, so `alchemy plan` fails "Cannot
+adopt" before any resource can say what taking the object over would write. `--dry-run` shows it.
+★ Even then every adoption prints `adopted`, drift or not. `hf-adopt-verify` plans with adoption on,
+never writes, and prints each row's own diff and an exit code: [adopt-verify.md](./adopt-verify.md).
+
+```ts
+import { adopt } from 'alchemy/AdoptPolicy';
+
+// this resource only
+export const app = BaoPolicy('app', { fragments: './policies/app', name: 'app' }).pipe(adopt(true));
+```
+
+A resource-scoped `adopt(…)` wins over the flag, both ways: `.pipe(adopt(false))` stays refused
+under `--adopt`.
+
+## Where it is checked
+
+| when                                | what happens to a live object with no state                                              |
+| ----------------------------------- | ---------------------------------------------------------------------------------------- |
+| **plan** — Alchemy's adoption probe | `read` answers `Unowned`; the plan fails with `OwnedBySomeoneElse` unless adoption is on |
+| **apply** — the probe never ran     | `reconcile` refuses before any write unless adoption is on                               |
+
+Alchemy skips the probe while a prop is still an `Output` (it comes from a resource created in the
+same deploy), and it never probes the new generation of a replace. An object can also appear
+between plan and apply. So each family checks again in `reconcile`, reading the object before it
+writes, and resolves `--adopt` / `adopt(…)` exactly as the planner does
+(`src/ownership/adopt.ts`).
+
+- A refused create also **forgets the `creating` row** Apply wrote for it, so the next plan probes
+  again and refuses again. Left behind, that row's recovery read could have adopted the very object
+  the apply refused (measured: `Bao.Mount` and `Bao.AuthMethod`, whose omitted props are not managed).
+- `Bao.Mount` / `Bao.AuthMethod`: a create with `remountFrom` moves a live mount that this stack
+  holds no state for. That move is a takeover too, and it is refused the same way.
+- **Adoption at apply is for a create, or an unfinished generation.** The planner offers `--adopt`
+  to a resource with no state, and Alchemy offers it to resume an interrupted create; so at apply
+  it lets through a `creating` row, or a generation whose row the plan's `diff` saw with no
+  attributes (an interrupted create or replace). A **fresh** replace's new generation that finds
+  its new identity taken is refused, `--adopt` or not: the plan never asked about that identity
+  (measured 2026-09-21: a `HostFile` whose path changed onto a file it did not own overwrote it
+  under a deploy-wide `--adopt`). For the Bao families a rename onto a taken identity already fails
+  the plan; this keeps the apply to the same answer.
+
+## Crash recovery still works — when the row can prove it
+
+A deploy that dies after its write and before its commit leaves a `creating` (or `replacing`) row
+and a live object. The next deploy finishes it **without** `--adopt`:
+
+- **An interrupted create.** Alchemy's recovery read passes the row's own instance id, which the
+  state store records (a probe's id is freshly minted, so no row holds it). The object is ours when
+  it also matches that row's props. If it does not, it may have lost a race to someone else, so it
+  is `Unowned`: the plan says `Cannot resume creating`, and `--adopt` resumes it.
+- **An interrupted replace.** Alchemy never probes a `replacing` row; it calls `diff`. For a row
+  with no attributes, every Bao family's and `ProxmoxLxc`'s `diff` first asks its own `read` the
+  recovery question —
+  recorded instance, whole row, matching object (`provingResumes`, `src/ownership/resume.ts`) — and
+  only a "yes" leaves a note in Alchemy's per-deploy `Artifacts` bag that lets the apply's own
+  object through.
+
+⛔ **A row proves nothing by itself.** Apply commits it **before** reconcile runs, so a deploy killed
+before the claim (an upstream that failed, a Ctrl-C) leaves a row whose create never asked whose
+object sat at its identity. Found by the red team on 2026-09-21 (`openbao/adopt-holes.test.ts`):
+
+- **A row missing part of its declaration proves nothing.** Apply strips a prop that was still an
+  `Output` from the row, and most families read an absent prop as "not managed". So the row must
+  carry every value the declaration names (`src/ownership/whole.ts`); one with a hole is `Unowned`.
+  Measured: a `Bao.Mount` whose `defaultLeaseTtl` was an Output adopted, and tuned, another owner's
+  mount; with the name an Output, every role family resumed onto another owner's role.
+- **So a create or replace interrupted while a prop was still an Output resumes with `--adopt`.**
+  Its row cannot say what it wrote, and that deploy's plan never asked whose object was there.
+
+⚠️ **A multi-step create interrupted halfway is not proven ours.** `Bao.Mount` enables, then tunes.
+If the deploy dies between the two, the mount does not match its props, and the resume needs
+`--adopt`. That is the safe direction.
+
+⚠️ **It fails closed.** If plan and apply do not share an `Artifacts` bag, or the store cannot be
+read, a resume reads as a fresh create and asks for `--adopt`. `alchemy deploy` and the Alchemist
+session both share one. An orphan's interrupted create (no longer declared) cannot be compared with
+a declaration, so Apply leaves its object in place with a note instead of deleting it.
+
+## Limits
+
+- ⚠️ **A check, then a write: not a lock.** Two resources that declare the same name in **one**
+  deploy create concurrently. Both read nothing, and both write (measured with the fakes). Declare
+  each name once.
+- ⚠️ **Proven at plan, written at apply.** A resume is proven against the object the plan read.
+  One swapped for another between that read and the apply is written over. That takes a race.
+- ⚠️ **Identical is still ours to a recovery read.** A foreign object identical to a whole row's
+  props, at the identity an interrupted create or replace was going to write, reads as ours — the
+  rule Plan.ts itself applies to a recovery read.
+- ⚠️ **`HostFile` and `LaunchdJob` answer `Unowned` to the recovery read too.** A create of theirs
+  interrupted after its write needs `--adopt` on the next deploy. Both remove what a failed create
+  wrote, so this needs a kill between the write and the commit.
+- ⚠️ **`CaddyConfig` keeps its own probe.** A running config identical to the declaration reads as
+  ours, because adopting it changes nothing Caddy serves ([caddy.md](./caddy.md#adoption)).
+  `ProxmoxLxc` does not share that exception: its delete removes a guest and its volumes
+  ([proxmox-lxc.md](./proxmox-lxc.md#adopting-what-the-plan-says)).
+- ⚠️ **The other `@homeflare/alchemy/proxmox` resources do not follow this rule yet.** Those built
+  on `pveHandlers` (`src/proxmox/resource.ts`) still read a live object with no state as ours.

package/docs/proxmox-lxc.md

@@ -0,0 +1,196 @@
+# Proxmox.Lxc
+
+A Proxmox VE container as an Alchemy resource: adopt one that runs today, or create one from a
+template. It uses the same PVE client and OpenBao-minted tokens as every other
+`@homeflare/alchemy/proxmox` resource. Nothing reads a stored credential.
+
+```ts
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as Effect from 'effect/Effect';
+import { ProxmoxLxc } from '@homeflare/alchemy/proxmox';
+
+export const guests = Effect.gen(function* () {
+  // Adopt: paste `pvesh get /nodes/<node>/lxc/<vmid>/config --output-format json`,
+  // minus `digest`, `lxc`, `lock`, `parent` and `unusedN`, and add where it lives.
+  // adopt(true) (or one deploy with --adopt) says the claim is meant; without it, nothing is.
+  const ct = yield* ProxmoxLxc('ct', {
+    target,
+    node: 'pve1',
+    vmid: 100,
+    hostname: 'ct-example',
+    cores: 4,
+    memory: 8192,
+    swap: 0,
+    onboot: 1,
+    unprivileged: 1,
+    features: 'nesting=1',
+    rootfs: 'local-zfs:subvol-100-disk-0,size=40G',
+    mp0: 'tank:subvol-100-disk-0,mp=/data,backup=0,size=200G',
+    net0: 'name=eth0,bridge=vmbr0,hwaddr=00:00:5E:00:53:01,ip=192.0.2.10/24,type=veth',
+    dev0: '/dev/dri/renderD128,uid=0,gid=44,mode=0660',
+  }).pipe(adopt(true));
+
+  // Create: a template, a new volume as `storage:GiB`, and `start` for the first boot only.
+  const door = yield* ProxmoxLxc('door', {
+    target,
+    node: 'pve1',
+    vmid: 150,
+    ostemplate: 'local:vztmpl/debian-13-standard_13.1-2_amd64.tar.zst',
+    rootfs: 'local-zfs:8',
+    net0: 'name=eth0,bridge=vmbr0,ip=dhcp',
+    features: 'nesting=1',
+    onboot: 1,
+    start: 1,
+  });
+  return { ct, door };
+});
+```
+
+Provide `ProxmoxLxcProvider()` with the other providers, plus `FetchHttpClient.layer`.
+
+## The props are PVE's keys
+
+Every prop is the key and spelling PVE uses in `/nodes/{node}/lxc/{vmid}/config`: `mp0`, `net1`,
+`dev0` and `rootfs` are property strings, and booleans may be `1`/`0` or `true`/`false`.
+
+- ⛔ **An undeclared key is unmanaged.** It is never sent, compared or deleted, including the keys
+  PVE fills in itself (`arch`, `ostype`, a NIC's `hwaddr`).
+- **To remove a key, declare it as `''`.** This works for `description`, `tags`, `startup`,
+  `features`, `nameserver`, `searchdomain`, `timezone` and `netN`. It is refused for a mount point.
+- ⛔ `password`, `ssh-public-keys` and `env` are typed `never`, because state is stored
+  unencrypted. A container created here has no root password. Use `pct enter` on its node.
+- ⛔ A key the resource does not manage (`hookscript`, `lock`, `force`, …) fails the plan, and
+  the create too: it is never sent.
+- ⛔ The `config` attribute keeps only keys this resource manages (an allowlist, so a new PVE key
+  such as `entrypoint` is not stored). Never `description` (the UI's Notes panel, where people
+  paste credentials), `env`, `digest` or raw `lxc.*` values. A declared description is in props.
+
+**Values are compared as PVE stores them, not as strings:**
+
+- A property string is compared as a map. Key order does not matter. A default written out
+  (`backup=0`, `firewall=0`, `type=veth`, `deny-write=0`, `keyctl=0`) equals the key being absent.
+- An undeclared `hwaddr` is ignored, and a NIC write keeps the live MAC. A new MAC would mean a
+  new DHCP lease.
+- `rootfs: 'local-zfs:40'` equals `local-zfs:subvol-…,size=40G`: the storage and the size are
+  compared. An existing volume is always written back with its live volume id, never with the
+  new-disk spelling, which would allocate a new volume and detach the old one.
+- Tags are compared as a lower-cased set, as PVE stores them by default. ⚠️ If your cluster sets
+  `tag-style case-sensitive=1`, a change of case is not seen.
+- `nameserver` and `searchdomain` are compared in order. `description` ignores the trailing
+  newline PVE adds to it.
+
+## What a change does
+
+| Change                                                             | What happens                                                        |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| cores, memory, swap, hostname, onboot, tags, NIC, mount options, … | `PUT …/config`, carrying the config `digest`                        |
+| A larger `rootfs` / `mpN`                                          | `PUT …/resize` after the config write, then wait for the task       |
+| A new `mpN` (`storage:GiB`) or `netN`                              | `PUT …/config`                                                      |
+| Nothing differs                                                    | Nothing is written, including on the first deploy after an adoption |
+
+The `digest` makes PVE refuse the write if the config changed since the deploy read it. ⚠️ That
+read is the deploy's, not the plan's: a declared key edited by hand between `plan` and `deploy`
+is written back to the declaration, even after a plan that warned of nothing.
+
+On a running guest, PVE may keep a change as pending until the next restart. A read returns the
+pending value, so the plan still converges.
+
+## What is refused, and why
+
+The plan fails with a sentence, and nothing is written. Nothing here plans a replace, because a
+replace of a guest deletes a running machine and its disks.
+
+| Change                                                                                            | Why                                                                    |
+| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `vmid`                                                                                            | A new vmid is a different guest.                                       |
+| `node`, while the guest is on another node                                                        | This resource never migrates.                                          |
+| `ostemplate`                                                                                      | The template is used up at create. Another template means a new guest. |
+| `unprivileged`                                                                                    | PVE: "unable to modify read-only option"                               |
+| A smaller `rootfs` / `mpN`                                                                        | PVE: "unable to shrink disk size"                                      |
+| Another storage                                                                                   | Use `pct move-volume`, which copies. It is not a config edit.          |
+| Another volume, or `mpN: ''`                                                                      | The live volume would be detached to `unusedN`.                        |
+| A create naming an existing volume id (not `storage:GiB`)                                         | PVE would unpack the template onto that volume.                        |
+| `devN`, a bind or device mount, a feature other than `nesting`, any feature on a privileged guest | Only root@pam can write these (see below)                              |
+
+A vmid that belongs to another node, or to a QEMU VM, fails the plan and says where it is. It
+does not plan a create. After HA or `pct migrate` has moved a guest, set `node` to where it is
+now: the plan is an update that writes nothing and records the new node.
+
+### root@pam only: device passthrough, bind mounts, most features
+
+PVE's `check_ct_modify_config_perm` (pve-container 6.1.14) lets only `root@pam` write these. An
+API token's user is always `user@realm!token`, never `root@pam`, so no minted token can write them.
+
+For these, the plan refuses and prints the exact `pct set <vmid> --<key> '<value>'` to run on the
+node. After you run it, declare the value, and the next plan compares it like any other key. A
+guest that needs `/dev/net/tun` (a Mesh door) or `/dev/dri` is created in two steps:
+
+1. Declare the guest without the device, and deploy.
+2. Run the `pct set` on the node, then add `dev0` to the declaration.
+
+`nesting` on an unprivileged guest is allowed. It needs `VM.Allocate`, which `LXCProvisioner` has.
+
+### Gaps
+
+- **Raw `lxc.*` lines** (`lxc.prlimit.memlock`, `lxc.cgroup2.devices.allow`, `lxc.mount.entry`)
+  can be read through the API but not set. They are edited in `/etc/pve/lxc/<vmid>.conf` on the
+  node. The attribute `rawKeys` lists their names only. Values are never stored, because
+  `lxc.environment` can hold anything.
+- **Power state is not declared.** `start: 1` boots the guest once, after its create. After
+  that, `onboot` is the setting, and starting or stopping is an operator's job.
+- **Pool membership, HA, firewall rules, snapshots, replication** are not declared here. Use their
+  own resources, or manage them by hand.
+
+## Adopting: what the plan says
+
+⛔ **No live guest is adopted without `adopt(true)` or `--adopt`, not even one that matches the
+declaration** — the kit-wide rule in [ownership.md](./ownership.md). Without either, the plan fails
+with "Cannot adopt" and nothing is written. Matching is not proof the guest is yours: a pasted
+config or a mistyped vmid reads the same, and once state claims a guest, `RemovalPolicy.destroy()`
+deletes it and its volumes. `.pipe(adopt(false))` stays refused under `--adopt`.
+
+With adoption on, a cold adoption plans **`adopted`** even when the deploy would write. Alchemy
+2.0.0-beta.79 forces an update after it adopts, and prints no property diff for that update. So
+`diff` logs a warning naming each key a deploy would write:
+
+```
+Proxmox.Lxc pve1/100: live config differs from the declaration in memory, net1 -- a deploy writes these.
+```
+
+- **No warning** means the declaration is the live config. The deploy writes nothing (two GETs),
+  and the next plan is `noop`. ★ That is the zero-change adoption check: read the plan first.
+- **A warning** means fix the declaration, or accept the named writes. Keys are named, values are
+  not.
+
+⛔ **A warning does not stop the deploy.** `deploy --adopt --yes` writes each named key onto the
+live guest. A `net0` declared without the live `tag=` is written without it, and the guest leaves
+its VLAN. Only the plan you read makes an adoption zero-change.
+
+⚠️ **`alchemy plan` has no `--adopt` flag** (2.0.0-beta.79: only `deploy` declares it). Without
+adoption on, the plan stops at "Cannot adopt" before `diff` can warn. To read the adoption's plan,
+run `alchemy deploy --adopt --dry-run`, or declare `.pipe(adopt(true))` and run `alchemy plan`.
+
+A deploy that planned a **create** never takes over a guest it then finds at that vmid (the plan
+skips its adoption read while a prop is an unresolved Output, and a guest can appear after the
+plan). Without adoption on, the deploy fails and forgets its `creating` row, so the next plan asks.
+With it on, a matching guest is recorded with no write; any other fails until a plan can show it.
+
+A create interrupted after its POST resumes on the next deploy **without** `--adopt` when the guest
+still matches what it declared. If someone changed it meanwhile, the plan says "Cannot resume
+creating", and `--adopt` resumes it (the warning names the keys it writes back).
+
+A guest the cluster no longer lists at all, with state still held, plans `update` and warns that
+the deploy **creates it again** from `ostemplate`, with new volumes. The plan fails instead when
+there is no `ostemplate`, or when `rootfs`/`mpN` are declared by live volume id (as a paste is):
+a create never reuses a volume.
+
+`GET …/config` needs `VM.Audit`, which the `read` lease has. A config PUT uses the cached
+`provision` lease. A create, resize or delete mints a fresh one and polls its task with it.
+
+## Removing
+
+`defaultRemovalPolicy: 'retain'`. If you drop the declaration, the state row is dropped and the
+guest keeps running. Only `.pipe(RemovalPolicy.destroy())` reaches the delete. That delete never
+forces, purges or stops the guest first: PVE refuses to delete a running or protected guest, and
+that refusal is kept. It also deletes only a guest that still matches its last declaration: a
+vmid is reusable, so one that differs may be somebody else's, and the delete is refused.

package/docs/proxmox.md

@@ -0,0 +1,12 @@
+# Proxmox — `@homeflare/alchemy/proxmox`
+
+PVE and PBS objects over the PVE API, each call on a short-lived token minted from an OpenBao
+mount. `ProxmoxLxc` adopts a live container from its own config (a paste of `pvesh get …/config`)
+or creates one from a template.
+
+- ⛔ **It never replaces or destroys a guest by default.** A move, a smaller disk, an unprivileged
+  flip or another template fails the plan. Destroy retains unless `RemovalPolicy.destroy()`.
+- ⛔ **It adopts nothing without `--adopt` or `adopt(true)`**, a matching guest included
+  ([ownership.md](./ownership.md)): under `destroy`, a claimed guest's disks go with it.
+- ⛔ **root@pam-only keys** (`devN`, bind mounts, features beyond `nesting`) are refused at plan,
+  with the `pct set` to run instead. Guide: [proxmox-lxc.md](./proxmox-lxc.md).