@homeflare/alchemy 0.10.1 → 0.12.0

package/docs/adopt-verify.md

@@ -9,8 +9,8 @@ bunx --bun hf-adopt-verify --config alchemy.run.ts --stage live          # rows
 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
+Wrap it in the same credential lane the deploy uses (the wrapper that mints
+its OpenBao token): 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
@@ -24,8 +24,8 @@ Measured in alchemy `2.0.0-beta.79`:
 - 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
+Measured on C1, `pvesh get /cluster/tasks`, 2026-09-21: six `cephsetpool` tasks by
+the provision user, 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.
@@ -37,10 +37,26 @@ fixed. [adopted-deploys.md](./adopted-deploys.md) shows what every family does.
 | `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        |
+| `alchemy drift`            | rows **with** state only, against the last deploy; exits `0`    |
 | `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                  |
 
+`alchemy drift` has no dry run to gate on (beta.79, `Cli/commands/drift.ts`, `Drift.ts`). Its
+flags are `--repair`, `--config`, `--env-file`, `--stage` and `--profile`: no `--dry-run`, and no
+`--yes`, although [its page](https://alchemy.run/cli/drift) lists one (measured 2026-09-21:
+`Unrecognized flag: --yes in command alchemy drift`, exit `1`). Without `--repair`, a terminal
+run asks Repair or Cancel (default Cancel). A non-interactive run (no TTY, `CI`, `--no-input`,
+`ALCHEMY_PLAIN=1` or `ALCHEMY_NO_TUI=1`, or an agent such as Claude Code) prints the repair plan
+and exits `0` even when something drifted. It skips a row whose provider has no `read`, or whose
+status is not `created` / `updated`. `--repair` restores the props saved at the last deploy, not
+what the code declares now, and recreates a missing object. `--all` (below) asks each
+provider's `diff` about the declaration, as a deploy does, and reads every row again.
+
+⛔ **Repair is a write outside the deploy gate.** Choosing Repair, or passing `--repair` (which
+never prompts), calls each drifted row's `reconcile` directly (`Drift.ts`): no `hf-adopt-verify`,
+no approved plan of the declaration. A HomeFlare gate never runs it. Deploy the declaration
+through the gate instead.
+
 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,

package/docs/adopted-deploys.md

@@ -57,8 +57,10 @@ 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").
+probe answers `Unowned`, so the deploy needs `--adopt`. An adoption that would write fails the
+plan instead, naming the keys ([proxmox-lxc-adopt.md](./proxmox-lxc-adopt.md)), so only the
+no-write row applies. Pinned by `src/proxmox/lxc-adopt.test.ts` ("deploys with no write") and
+`src/proxmox/lxc-strict-adopt.test.ts`.
 ⁴ `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.
@@ -69,7 +71,7 @@ reported as a diff.
 `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
+still a provision-lease write and a task on the node every time the pool was adopted. C1's task
 list shows six such tasks (2026-09-13 and 2026-09-20), one per declared pool per deploy.
 
 ## How it is pinned

package/docs/ownership.md

@@ -4,7 +4,8 @@ A live object this stack holds **no state for** is never taken over silently. Th
 `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.)
+from its real owner. (Decided 2026-09-21; the Bao families adopted silently until 0.9.0. 0.9.0 was
+never published, so 0.10.0 is the first release with the rule.)
 
 To take an object over, say so:
 
@@ -92,6 +93,30 @@ read, a resume reads as a fresh create and asks for `--adopt`. `alchemy deploy`
 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.
 
+## After a wiped store or `state delete`, it needs `--adopt`
+
+Alchemy's documented repair for a bad record is `alchemy state delete`, then `alchemy deploy`,
+escalating to `--adopt` only on `OwnedBySomeoneElse`
+([inspecting state](https://alchemy.run/cli/inspecting-state#recover-from-bad-state)). For the
+families above that escalation always comes (decided 2026-09-21): an object whose row is gone is
+`Unowned`, so the deploy needs `--adopt`, or `adopt(true)` on its declaration. `MeshNode`
+([mesh-node.md](./mesh-node.md)) and `R2BucketLock` (`src/cloudflare/r2-bucket-lock.ts`) need it
+too. A `CaddyConfig` running the declared config re-imports without it, and so does every family
+whose `read` never answers `Unowned`: the `pveHandlers` resources (Limits), the `forgejoHandlers`
+resources and the Talos resources. Read the takeover first with `hf-adopt-verify`
+([adopt-verify.md](./adopt-verify.md)).
+
+★ This departs from Alchemy's docs, not from its code. The docs say a provider with no ownership
+marker answers plain attributes, so its objects re-import silently (`AdoptPolicy.ts`,
+[adopting resources](https://alchemy.run/cli/adopting-resources),
+[provider](https://alchemy.run/infrastructure-as-code/provider#read)). Many of Alchemy's own
+marker-less providers answer `Unowned` to a read with no state instead, as the kit's families do
+(beta.79: `Cloudflare/Snippets/Snippet.ts`, `Cloudflare/Tunnel/WarpConnector.ts`,
+`Cloudflare/Zone/Hold.ts`). After a wiped store those need `--adopt` too.
+
+⚠️ **That page's `alchemy state delete myapp/pr-42` fails.** A stage or a whole stack is a
+directory, and deleting one needs `-r` (beta.79 `State/Tree.ts`). A single row does not.
+
 ## Limits
 
 - ⚠️ **A check, then a write: not a lock.** Two resources that declare the same name in **one**
@@ -108,6 +133,6 @@ a declaration, so Apply leaves its object in place with a note instead of deleti
 - ⚠️ **`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)).
+  ([proxmox-lxc-adopt.md](./proxmox-lxc-adopt.md)).
 - ⚠️ **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/provision-baseline.md

@@ -0,0 +1,106 @@
+# Provisioning baseline — every cluster, every node
+
+Every `@homeflare/alchemy/proxmox` resource runs as a short-lived PVE token that OpenBao mints for
+a **provision user**. That user, and the access it holds, is the baseline a cluster needs before a
+stack can manage anything on it. This subpath ships it as one description with two readers:
+
+| export                      | what it is                                                                                  |
+| --------------------------- | ------------------------------------------------------------------------------------------- |
+| `PROVISION_PRIVILEGES`      | the provision role's privileges: 27, sorted, the exact set                                  |
+| `PROVISION_DEFAULTS`        | the generic names in the last table, each overridable                                       |
+| `provisionBaseline(names)`  | the resolved baseline both readers use; refuses names that are not PVE-shaped               |
+| `declareProvisionBaseline`  | the baseline as `Proxmox.Role`, `Proxmox.Group`, `Proxmox.User` and `Proxmox.Acl` resources |
+| `provisionBootstrap(names)` | the one-time root commands for a new cluster or node, as a `sh` script                      |
+
+## The chicken and the egg
+
+⛔ **The provision lane cannot create itself.** A plan needs a minted token, and a mint needs the
+provision user to exist, be in the mint group, and hold the role on `/`. On a new cluster none of
+that exists, so no plan can run, including the plan that would create it.
+
+So root makes it once, and the stack takes it over from there:
+
+1. **Bootstrap, as root, once per cluster.** Generate the script and run it on any one node:
+
+   ```sh
+   bun -e "import { provisionBootstrap } from '@homeflare/alchemy/proxmox';
+           process.stdout.write(provisionBootstrap())" | ssh root@node-a sh
+   ```
+
+   Read it first: it is plain text with no secret in it. It checks each object and changes only
+   what differs, naming each step (`role HfProvisioner: adding`, `user hf-read@pve: ok`). It
+   never creates a token and never sets a password.
+
+2. **Point OpenBao at the users.** The proxmox secrets engine mints for them through a
+   `Bao.ProxmoxRole` per lane (`mintUser: PROVISION_DEFAULTS.provisionUser`, and the read user).
+   The engine's own credential, a user allowed to manage tokens for members of the mint group, is
+   set up with the engine. It is not part of this baseline.
+
+3. **Declare the baseline in the stack, and adopt it once:**
+
+   ```ts
+   import * as Effect from 'effect/Effect';
+   import { declareProvisionBaseline } from '@homeflare/alchemy/proxmox';
+
+   export const access = Effect.gen(function* () {
+     return yield* declareProvisionBaseline('pve', target);
+   });
+   ```
+
+   The first deploy finds everything live with no state. Run it with `--adopt`, or pass
+   `{ adopt: true }`. Because the script made exactly what the declaration holds, the plan is a
+   clean adoption and the deploy writes nothing. From then on, a hand edit (a privilege added in
+   the UI, a user dropped from the group) shows up as a diff on the next plan.
+
+## Every cluster, every node
+
+- **A new cluster:** run the bootstrap on one node, then deploy.
+- **A node joining a cluster:** nothing to do. Users, groups, roles and ACLs live in
+  `/etc/pve/user.cfg`, which the cluster shares. Running the script there prints `ok` for every
+  step and writes nothing.
+- **A standalone node:** it is its own cluster. Bootstrap it.
+
+## Your own names
+
+Every name has a generic default, and a site passes its own to both readers:
+
+```ts
+const names = { role: 'Provisioner', mintGroup: 'mint', readUser: null };
+provisionBootstrap(names); // the script
+declareProvisionBaseline('pve', target, names); // the resources
+```
+
+- `readUser: null` gives a baseline with no read lane.
+- `readRole` must already exist (`PVEAuditor` is built in). The script stops before any write if
+  it does not.
+- A name that is not PVE-shaped, or that would need quoting in a shell, is refused by both
+  readers before either one runs.
+
+## What the baseline holds
+
+| object                           | detail                                                     |
+| -------------------------------- | ---------------------------------------------------------- |
+| role `HfProvisioner`             | exactly `PROVISION_PRIVILEGES`, nothing more, nothing less |
+| group `hf-mint`                  | the fence: OpenBao may mint only for its members           |
+| user `hf-provision@pve`          | in `hf-mint` only, enabled, no password, no expiry         |
+| user `hf-read@pve`               | the same, for the read lane                                |
+| `/`, `hf-provision@pve`, role    | `HfProvisioner`, propagated                                |
+| `/`, `hf-read@pve`, `PVEAuditor` | propagated                                                 |
+
+★ **One privilege list for every family.** It is the union of what each resource's reconcile
+needs. That includes managing this baseline itself (`Sys.Modify`, `Realm.AllocateUser`,
+`User.Modify`, `Group.Allocate`, `Permissions.Modify`), so declaring it can never narrow the lane
+out of its own repair. It does not include writes PVE keeps for `root@pam` (device passthrough,
+bind mounts). Those are refused at plan with the command to run instead.
+
+⚠️ **The role is the exact set.** Both the script and `Proxmox.Role` replace the privileges, never
+add to them. A privilege added by hand is removed on the next run or deploy. If you need more,
+declare your own role and grant.
+
+⛔ **Everything retains.** Dropping `declareProvisionBaseline` from a stack drops its state and
+leaves the role, users, group and grants in place. Deleting the provision user would revoke every
+lease at once, including the one the next plan needs.
+
+⚠️ **Adoption today.** `Proxmox.Role`, `Group`, `User` and `Acl` still read a live object with no
+state as their own (the `pveHandlers` limit in [ownership.md](./ownership.md)). The `adopt`
+option says what the stack means, so it keeps holding when those families follow the rule.

package/docs/proxmox-lxc-adopt.md

@@ -0,0 +1,83 @@
+# Proxmox.Lxc — adopting a live guest
+
+The adoption half of [proxmox-lxc.md](./proxmox-lxc.md). Two rules, both decided 2026-09-21:
+
+1. ⛔ **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`.
+2. ⛔ **An adoption never changes a guest.** It is taken over exactly as it runs, or not at all.
+   With adoption on, a declaration that differs from the live config in any key fails the plan:
+
+```
+CT 900 on pve1: adopting it would change memory, net1. An adoption never changes a guest, so
+nothing is written. Declare what is live for these keys (the plan names keys, never values) and
+plan again; change them after the adoption, as an update.
+```
+
+- **Keys are named, values never.** A live config can carry anything (`description` is where
+  people paste credentials), and plan output lands in CI logs.
+- **The fix is the declaration.** Copy the live value for each named key and plan again. A plan
+  that says `adopted` and fails nothing is the zero-change check: the deploy writes nothing (two
+  GETs), and the next plan is `noop`.
+- **To change the guest, adopt it first.** Once state holds it, a changed declaration is an
+  ordinary `update`, and its plan warns with each key the deploy writes:
+
+```
+Proxmox.Lxc pve1/900: live config differs from the declaration in memory -- a deploy writes these.
+```
+
+- **The deploy asks again.** A key edited by hand between the plan and the deploy is refused at
+  apply, with nothing written. The adoption's state row stays, and every plan refuses the same way
+  until the declaration says what is live. Then it adopts with no write.
+- **It comes before the other refusals.** A root@pam-only key, a smaller disk or an unprivileged
+  flip would print a declared value and a `pct set` to run. For an adoption the fix runs the other
+  way, so the adoption refusal is the one you see.
+
+★ **Why it is strict.** Alchemy 2.0.0-beta.79 plans a cold adoption as `adopted` whatever it would
+write, and prints no property diff for it. Until this rule, `diff` only logged the keys, and
+`deploy --adopt --yes` then wrote them: a `net0` pasted without the live `tag=` took the guest off
+its VLAN on the deploy that was meant to change nothing.
+
+⚠️ **`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 the adoption check runs. To read the
+adoption's plan, run `alchemy deploy --adopt --dry-run`, or declare `.pipe(adopt(true))` and run
+`alchemy plan`.
+
+## What counts as an adoption
+
+State says, at plan and at apply alike (`src/ownership/adopting.ts`):
+
+| the guest reached state…                                                        | adoption? |
+| ------------------------------------------------------------------------------- | --------- |
+| through the adoption probe: no state for it, found live                         | yes       |
+| on the deploy after that probe, until the adoption commits                      | yes       |
+| through an interrupted create the plan could not prove its own, under `--adopt` | yes       |
+| through an interrupted create whose guest still matches what it wrote           | no        |
+| through this resource's own create, or an adoption that has committed           | no        |
+
+An interrupted create proven its own is not an adoption. If its declaration changed meanwhile, the
+deploy writes the change.
+
+## Creates that find a guest
+
+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". `--adopt` then adopts it as it now runs: declare what is live first.
+
+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.
+
+## Leases
+
+`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.

package/docs/proxmox-lxc.md

@@ -16,7 +16,7 @@ export const guests = Effect.gen(function* () {
   const ct = yield* ProxmoxLxc('ct', {
     target,
     node: 'pve1',
-    vmid: 100,
+    vmid: 900,
     hostname: 'ct-example',
     cores: 4,
     memory: 8192,
@@ -24,8 +24,8 @@ export const guests = Effect.gen(function* () {
     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',
+    rootfs: 'local-zfs:subvol-900-disk-0,size=40G',
+    mp0: 'tank:subvol-900-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));
@@ -90,7 +90,8 @@ Every prop is the key and spelling PVE uses in `/nodes/{node}/lxc/{vmid}/config`
 
 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.
+is written back to the declaration, even after a plan that warned of nothing. (An adoption
+refuses it instead.)
 
 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.
@@ -128,7 +129,8 @@ guest that needs `/dev/net/tun` (a Mesh door) or `/dev/dri` is created in two st
 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.
+`nesting` on an unprivileged guest is allowed. It needs `VM.Allocate`, which the
+[provisioning baseline](./provision-baseline.md)'s role has.
 
 ### Gaps
 
@@ -141,51 +143,12 @@ guest that needs `/dev/net/tun` (a Mesh door) or `/dev/dri` is created in two st
 - **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
+## Adopting
 
-⛔ **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.
+⛔ **No live guest is adopted without `adopt(true)` or `--adopt`, and an adoption never changes
+a guest.** It is taken over exactly as it runs, or the plan fails naming each key that differs.
+What the plan says, what counts as an adoption, and the leases each step uses:
+[proxmox-lxc-adopt.md](./proxmox-lxc-adopt.md).
 
 ## Removing
 

package/docs/proxmox.md

@@ -8,5 +8,13 @@ or creates one from a template.
   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.
+- ⛔ **An adoption never changes a guest.** Any key that differs from the live config fails the
+  plan, named without its value ([proxmox-lxc-adopt.md](./proxmox-lxc-adopt.md)).
 - ⛔ **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).
+- ★ **One provisioning baseline for every cluster and node**: the privilege list, a helper that
+  declares it, and the one-time root commands that bootstrap it
+  ([provision-baseline.md](./provision-baseline.md)).
+- ★ **Measurements in the source name a reference cluster with placeholders**: `C1`, three nodes
+  `node-b`, `node-c` and `node-d` with Ceph on a Thunderbolt mesh, and documentation addresses
+  (RFC 5737). The shapes and counts are measured; the names and addresses are not the real ones.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",

package/src/caddy/admin-guard.ts

@@ -20,7 +20,7 @@
  *     Refused unless the transport is at that default; declaring `admin <address>` is the fix.
  *   · a Host the new config does not allow: `origins` without it, or — with no `origins` — a Host
  *     outside Caddy's loopback defaults (`localhost`, `[::1]`, `127.0.0.1` at the listen port).
- *     Every later call answers 403 (admin.go allowedOrigins / checkHost; MEASURED on the mini's
+ *     Every later call answers 403 (admin.go allowedOrigins / checkHost; MEASURED on a Mac host's
  *     Caddy 2.11.4 — `host not allowed`). The transport also sends `Origin: http://<Host>`, which
  *     Caddy checks against the same list (originAllowed), so one check covers both.
  *   · `enforce_origin` over a unix socket: this transport, like Caddy's CLI (cmd/commandfuncs.go

package/src/caddy/local-admin.ts

@@ -12,7 +12,7 @@
  * ★ HOST AND ORIGIN, AS CADDY's OWN CLI SENDS THEM (cmd/commandfuncs.go AdminAPIRequest): over
  *   TCP, `Host` and `Origin: http://<host>`; over a socket, `Host: 127.0.0.1` and no Origin, because
  *   Caddy skips the Host check on unix listeners (admin.go allowedOrigins). MEASURED against the
- *   mini's Caddy 2.11.4: any other Host gets 403 `host not allowed`, a forwarded port included —
+ *   a Mac host's Caddy 2.11.4: any other Host gets 403 `host not allowed`, a forwarded port included —
  *   hence `hostHeader`.
  */
 import { request as httpRequest } from 'node:http';

package/src/cloudflare/client.ts

@@ -5,7 +5,7 @@
  * ⛔ THE SDK WAS ALREADY IN THE STORE AND DECLARED BY NOBODY. Measured 2026-09-15:
  *   `node_modules/.pnpm/cloudflare@4.5.0` exists as a transitive dependency of `alchemy`, and
  *   `pnpm ls cloudflare --depth 0` at the root and in every workspace package returns nothing.
- *   `house/local/scripts/vendor-sdk-ratchet.ts` row R2 says exactly that — "not declared anywhere
+ *   `<estate>/local/scripts/vendor-sdk-ratchet.ts` row R2 says exactly that — "not declared anywhere
  *   in the workspace yet … the row adds the dependency once, then converts the TS callers" — so
  *   this package is that row's first half, and the twenty ratcheted offences keep their rows.
  *

package/src/cloudflare/lock-rules.ts

@@ -1,7 +1,7 @@
 /**
  * The vocabulary of an R2 lock rule, and the comparison that decides whether to write one.
  *
- * ★ ITS OWN MODULE FOR THE REASON `house/litellm/src/equal.ts` IS ONE: the comparison is the
+ * ★ ITS OWN MODULE FOR THE REASON `<estate>/litellm/src/equal.ts` IS ONE: the comparison is the
  *   riskiest function in the provider and it deserves to be readable and testable without the
  *   lifecycle around it. An equality that returned true for everything would make every reconcile
  *   a no-op and the resource would silently never write anything — which looks exactly like a

package/src/forgejo/branch-protection-form.ts

@@ -1,7 +1,7 @@
 /**
  * Create/PATCH bodies for `Forgejo.BranchProtection` — extracted for the 250-line cap.
  *
- * ★ READ OFF `house/mcp-servers/docs/api/upstream/forgejo.json` — create posts
+ * ★ READ OFF `<estate>/mcp-servers/docs/api/upstream/forgejo.json` — create posts
  *   `CreateBranchProtectionOption`; update sends `EditBranchProtectionOption` fields only.
  */
 import type { BranchProtectionProps } from './branch-protection.ts';

package/src/forgejo/branch-protection.ts

@@ -1,7 +1,7 @@
 /**
  * `Forgejo.BranchProtection` — one rule at `/repos/{owner}/{repo}/branch_protections/{name}`.
  *
- * ★ READ OFF `house/mcp-servers/docs/api/upstream/forgejo.json`: create is POST collection;
+ * ★ READ OFF `<estate>/mcp-servers/docs/api/upstream/forgejo.json`: create is POST collection;
  *   read/update/delete use the branch/rule name in the path segment `{name}`. Response carries
  *   `rule_name` (preferred) and deprecated `branch_name`.
  *

package/src/forgejo/client.ts

@@ -87,7 +87,7 @@ export const forgejo = <T>(
      *   (src/Hetzner/Providers.ts builds on `FetchHttpClient.layer`; there is no bare fetch in its
      *   Docker, Kubernetes or GitHub providers). It buys a typed error channel, interruption when
      *   a plan is cancelled, the runtime's tracing, and a client a test can replace without
-     *   monkey-patching a global. house/proxmox/src/resource.ts carries the same note.
+     *   monkey-patching a global. <estate>/proxmox/src/resource.ts carries the same note.
      */
     const client = yield* HttpClient.HttpClient;
     /**

package/src/forgejo/org-actions-secrets.ts

@@ -2,7 +2,7 @@
  * `Forgejo.OrgSecret` — org-level Actions secret metadata at `/orgs/{org}/actions/secrets/{name}`.
  *
  * ★ CHOICE: AUTHORED WITH WRITE-ONLY VALUE VIA ENV, NOT REFUSED. The OpenAPI in
- *   `house/mcp-servers/docs/api/upstream/forgejo.json` shows `Secret` returns only `name` and
+ *   `<estate>/mcp-servers/docs/api/upstream/forgejo.json` shows `Secret` returns only `name` and
  *   `created_at` — never the `data` field — so attributes stay metadata-only. Create/update is PUT
  *   with body `{ data }`, which does not fit POST/PATCH; this family uses the `upsert` seam on
  *   `ForgejoSpec` instead of hand-rolling provider handlers.

package/src/forgejo/org-label.ts

@@ -1,7 +1,7 @@
 /**
  * `Forgejo.OrgLabel` — one org-level issue label shared across every repository in the org.
  *
- * ★ RETIRES `house/nix/homeflare-config/hosts/macmini/forgejo/labels-reconcile.sh`, which
+ * ★ RETIRES the estate's hand-run `labels-reconcile.sh`, which
  *   converged the whole `labels.yaml` file in one shot. That script CREATED and PATCHED labels
  *   from the spec and REPORTED `EXTRA` labels present live but absent from the file — it never
  *   deleted them, because removing a label strips it from every issue that carries it.

package/src/forgejo/org-team.ts

@@ -1,7 +1,7 @@
 /**
  * `Forgejo.OrgTeam` — one organization team under `/orgs/{org}/teams`.
  *
- * ★ READ OFF `house/mcp-servers/docs/api/upstream/forgejo.json` (Forgejo 16.x OpenAPI): create is
+ * ★ READ OFF `<estate>/mcp-servers/docs/api/upstream/forgejo.json` (Forgejo 16.x OpenAPI): create is
  *   `POST /orgs/{org}/teams`; read/update/delete use numeric id at `/teams/{id}` — not the name.
  *
  * ⚠️ PATCH AND DELETE USE `/teams/{id}` — same seam as org labels. `locate` lists by name;

package/src/forgejo/repo-webhook.ts

@@ -1,7 +1,7 @@
 /**
  * `Forgejo.RepoWebhook` — one repository webhook under `/repos/{owner}/{repo}/hooks`.
  *
- * ★ READ OFF `house/mcp-servers/docs/api/upstream/forgejo.json`: create is POST collection; read/update/delete
+ * ★ READ OFF `<estate>/mcp-servers/docs/api/upstream/forgejo.json`: create is POST collection; read/update/delete
  *   use numeric hook id at `/repos/{owner}/{repo}/hooks/{id}`. `locate` lists and matches on `name`.
  *
  * ⛔ NO WEBHOOK `secret` IN PROPS OR ATTRIBUTES. Optional HMAC material is env-only at write time

package/src/forgejo/repository.ts

@@ -1,7 +1,7 @@
 /**
  * `Forgejo.Repository` — an organization-owned git repository.
  *
- * ★ MEASURED 2026-09-13 against the live daemon (`GET /api/v1/repos/HomeFlare/homeflare-config`):
+ * ★ MEASURED 2026-09-13 against the live daemon (`GET /api/v1/repos/<org>/<repo>`):
  *   responses are flat JSON with `private`, `has_issues`, `default_branch`, etc. Create is
  *   `POST /orgs/{org}/repos`; read/update/delete use `/repos/{owner}/{repo}`.
  *
@@ -15,7 +15,7 @@ import { type ForgejoRequirements, forgejoHandlers } from './resource.ts';
 import { bool, text } from './values.ts';
 
 export interface RepositoryProps {
-  /** Organization login — the owner segment in `HomeFlare/homeflare-config`. */
+  /** Organization login — the owner segment in `<org>/<repo>`. */
   org: string;
   /** Repository name. Changing it is a replace, not an update. */
   name: string;

package/src/forgejo/resource.ts

@@ -28,7 +28,7 @@ import { ForgejoError, forgejo } from './client.ts';
 /**
  * ★ WHAT EVERY OPERATION HERE NEEDS FROM THE RUNTIME — and it is NOT what the first draft said.
  *
- *   These resources declared `ChildProcessSpawner`, copied from house/proxmox, where it is there
+ *   These resources declared `ChildProcessSpawner`, copied from <estate>/proxmox, where it is there
  *   because a PVE credential is minted by shelling out to `bao`. Nothing in this package shells
  *   out: the token comes from `FORGEJO_TOKEN` in the environment. Declaring a service you never
  *   use is not harmless — it makes a stack provide a layer for nothing, and it hides the one
@@ -152,7 +152,7 @@ export const forgejoOperations = <Props extends object, Attributes>(
  * The five provider handlers for a spec'd Forgejo object, wired once.
  *
  * ⛔ IT STOPS AT THE HANDLERS AND DOES NOT RETURN THE LAYER — same reasoning as pveHandlers in
- *   house/proxmox: wrapping `Provider.effect` here needs casts against Alchemy's `Props<R>`.
+ *   <estate>/proxmox: wrapping `Provider.effect` here needs casts against Alchemy's `Props<R>`.
  *
  * ⚠️ `list` answers empty — Forgejo index endpoints return the whole org; adoption stays explicit.
  */

package/src/forgejo/team-member.ts

@@ -3,7 +3,7 @@
  *
  * ★ WHY IT EXISTS: forgejo-provision, the service account the Forgejo engine mints as, belongs to the
  *   HomeFlare Owners team — Tim, 2026-09-14. Membership is what its tokens can reach; the role's
- *   scopes only cap it (house/openbao/src/forgejo-bootstrap.ts).
+ *   scopes only cap it (<estate>/openbao/src/forgejo-bootstrap.ts).
  *
  * ★ READ OFF THE LIVE 16.0.3 SWAGGER (127.0.0.1:3000/swagger.v1.json, 2026-09-14): GET, PUT and
  *   DELETE `/teams/{id}/members/{username}` answer 200, 204 and 204, and 404 when absent. The team

package/src/openbao/README.md

@@ -17,7 +17,7 @@ plus `FetchHttpClient.layer`.
 - ⛔ A rename or move onto a name or path that already exists fails the plan, before anything is
   written (every family but the mounts, whose moves are below). Move through a free name, in two
   deploys, or remove the target first.
-- ⛔ **Nothing is adopted without `--adopt`** (0.9.0), not even an object identical to the
+- ⛔ **Nothing is adopted without `--adopt`** (0.9.0, first published as 0.10.0), not even an object identical to the
   declaration: a live name with no state fails the plan, or the apply when a prop was an Output.
   Our own interrupted create still resumes when its row can prove it — not one killed while a
   prop was still an Output. [docs/ownership.md](../../docs/ownership.md). Change
@@ -105,10 +105,10 @@ export const machines = Effect.gen(function* () {
   });
   yield* BaoKubernetesRole('pod', {
     aliasNameSource: 'serviceaccount_name',
-    boundServiceAccountNames: ['litellm'],
+    boundServiceAccountNames: ['llm-gateway'],
     boundServiceAccountNamespaces: ['ai'],
-    name: 'ai-litellm',
-    tokenPolicies: ['ai-litellm'],
+    name: 'ai-gateway',
+    tokenPolicies: ['ai-gateway'],
   });
 });
 ```

package/src/openbao/auth-role.ts

@@ -7,7 +7,7 @@
  *
  * ★ `defaultRemovalPolicy: 'retain'` — deleting a role locks out every host that logs in with it:
  *   its secret_ids go with it (the ⚠️ on `delete` below). Opt in with
- *   `.pipe(RemovalPolicy.destroy())`; see resource.ts in house/proxmox.
+ *   `.pipe(RemovalPolicy.destroy())`; see resource.ts in <estate>/proxmox.
  */
 import { Resource } from 'alchemy';
 import { isResolved } from 'alchemy/Diff';