@homeflare/alchemy 0.7.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/caddy-admin.md

@@ -0,0 +1,24 @@
+# Caddy's admin endpoint — `@homeflare/alchemy/caddy`
+
+How the provider reaches Caddy's admin API, and what it refuses so a Caddyfile cannot cut it off.
+The overview is [caddy.md](./caddy.md).
+
+⛔ The admin API has no authentication. `localCaddyAdmin()` accepts only `http://` loopback
+(`127.0.0.0/8`, `localhost`, `[::1]`) or `unix:///path`; the default is `http://127.0.0.1:2019`.
+
+- **Host and Origin.** Caddy refuses a request whose `Host` is not an allowed origin (DNS-rebinding
+  guard; measured on Caddy 2.11.4: `403 host not allowed`), and checks `Origin` when one is sent or
+  `enforce_origin` is on. The transport sends both as the Caddy CLI does. A unix socket skips the
+  Host check entirely.
+- **`admin { origins … }`** narrowed, or **an SSH-forwarded port** (Caddy checks the Host against
+  ITS port): pass `hostHeader: 'localhost:2019'`.
+- **Another host's Caddy** (SSH later): forward its socket or port to loopback here and point a
+  `localCaddyAdmin()` at it, or implement `CaddyAdmin` over your own route. Never expose :2019.
+- **A Caddyfile cannot strand the provider.** Before loading, the adapted `admin` block is refused
+  if it turns the API off, listens off loopback or somewhere the transport does not reach (another
+  port, socket or loopback address: `[::1]` is not `127.0.0.1`, and `localhost` binds IPv4), allows
+  no Host the transport sends (its `origins`, or Caddy's loopback defaults when there are none), sets
+  `enforce_origin` over a unix socket (no Origin is sent there), enables `remote`, or pulls config.
+- ⛔ **No `admin` address means Caddy's default** (`localhost:2019`, or `$CADDY_ADMIN`) after the
+  load. That is refused unless the transport is at that default: a Caddy reached on a socket or
+  another port declares `admin <address>` in its Caddyfile.

package/docs/caddy.md

@@ -24,10 +24,12 @@ export const edge = Effect.gen(function* () {
   yield* LaunchdJob('caddy-daemon', {
     label: 'com.example.caddy',
     domain: 'system',
+    // --resume: a restart runs the last config Caddy accepted (see Managed Caddies below).
     // --envfile: a file a secret renderer (openbao-agent) writes; {env.CF_API_TOKEN} reads it.
     programArguments: [
       '/usr/local/bin/caddy',
       'run',
+      '--resume',
       '--config',
       file.path,
       '--adapter',
@@ -35,6 +37,8 @@ export const edge = Effect.gen(function* () {
       '--envfile',
       '/usr/local/etc/caddy.env',
     ],
+    // ⛔ Here, not in the envfile: Caddy fixes its autosave path before it reads --envfile.
+    environment: { XDG_CONFIG_HOME: '/usr/local/var/caddy-edge' },
     runAtLoad: true,
     keepAlive: true,
   });
@@ -56,15 +60,15 @@ export const providers = Layer.mergeAll(caddyProviders(), launchdProviders());
 | `endpoint`     | where the admin API was reached                                                      |
 | `sourceFile`   | as applied                                                                           |
 
-| step    | what happens                                                                                                                             |
-| ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| plan    | `POST /adapt` the Caddyfile (side-effect free): a syntax error, a literal secret, no apps or an unsafe `admin` block fails the **plan**  |
-| apply   | `POST /load` with `text/caddyfile`, then `GET /config/` must hash to what `/adapt` produced; skipped when Caddy already runs it          |
-| refused | Caddy keeps the old config (it rolls back itself); the deploy fails with Caddy's reason and says whether the old config is still running |
-| read    | the digest of `GET /config/` — with no state, a running Caddy is **adopted** (its live config becomes the baseline)                      |
-| drift   | live ≠ stored → `update`: a hand `curl` to the API, or a restart that loaded a different file                                            |
-| replace | never — a new Caddyfile is a reload of the same Caddy                                                                                    |
-| delete  | ⛔ nothing. See [Removing it](#removing-it)                                                                                              |
+| step    | what happens                                                                                                                                       |
+| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| plan    | `POST /adapt` the Caddyfile (side-effect free): a syntax error, a literal secret, no apps or an unsafe `admin` block fails the **plan**            |
+| apply   | `POST /load` with `text/caddyfile`, then `GET /config/` must hash to what `/adapt` produced; skipped when Caddy already runs it                    |
+| refused | Caddy keeps the old config (it rolls back itself); the deploy fails with Caddy's reason and says whether the old config is still running           |
+| read    | the digest of `GET /config/`; with no state, the adoption probe — ⛔ a config that is not the declared one needs `--adopt` ([Adoption](#adoption)) |
+| drift   | live ≠ stored → `update`: a hand `curl` to the API, or a restart that loaded a different file                                                      |
+| replace | never — a new Caddyfile is a reload of the same Caddy                                                                                              |
+| delete  | ⛔ nothing. See [Removing it](#removing-it)                                                                                                        |
 
 The digests compare adapted JSON, not bytes: `/adapt` answers Go struct order, `GET /config/` sorted
 keys with `<>&` escaped and a trailing newline. `digest.ts` erases all three. ★ Measured 2026-09-21
@@ -86,31 +90,42 @@ before any admin API exists to load into. What bounds the cost:
   `/adapt` fails the plan. On the very first deploy the path is still an Output, Alchemy skips the
   adoption probe, and the check runs at apply instead.
 - ⚠️ **A Caddyfile that adapts but that Caddy refuses** (a port in use, a missing cert file) is on
-  disk when `/load` fails. Caddy keeps serving the old config — but a **restart before the fix loads
-  the refused file**. Fix and redeploy, or run Caddy with `--resume` (below).
+  disk when `/load` fails. Caddy keeps serving the old config, and a managed Caddy's restart runs its
+  autosave, not the refused file (below). Without `--resume` a **restart before the fix loads the
+  refused file**: fix and redeploy.
 - ⛔ Secrets are refused at declaration, before the HostFile exists (its `content` is a prop too).
 - ★ Both resources retain: removing them from a stack leaves the file a restart needs.
 
-## Autosave and `--resume`
-
-After every successful load (ours included) Caddy writes the config JSON to `autosave.json`
-(`$XDG_CONFIG_HOME/caddy/`, else `~/Library/Application Support/Caddy/` on macOS, `~/.config/caddy/`
-on Linux), unless the Caddyfile says `persist_config off`. ⚠️ A daemon started with no `HOME` and no
-`XDG_CONFIG_HOME` falls back to `./caddy/` under its working directory (storage.go AppConfigDir):
-set `XDG_CONFIG_HOME` in the launchd job so autosave lands where you expect.
-
-- **Without `--resume`** (the mini's Caddy today): a restart loads `--config`. The file and the
-  running config agree after every successful deploy; see the ⚠️ above for a failed one.
-- **With `caddy run --resume --config <file>`**: a restart loads `autosave.json` — the last config
-  Caddy **accepted** — and `--config` only when no autosave exists. A refused file on disk can then
-  never take sites down. The trade: a hand change through the API also survives a restart; the next
-  plan reports it as drift and the deploy puts the declaration back.
-- `--watch` reloads the file on change; our `/load` right after is then a no-op ("config is
-  unchanged").
-- `sourceFile` rides as `Caddy-Config-Source-File`, as `caddy reload` sends it. Without it a load
-  makes Caddy forget its source file, and SIGUSR1 stops reloading from it. The header only KEEPS the
-  file Caddy started with (caddy.go ClearLastConfigIfDifferent); it never sets a new one. ⚠️ Under
-  `--resume` with an autosave, Caddy records no source file at all, so SIGUSR1 has nothing to reload.
+## Managed Caddies: `--resume` and their own config dir
+
+★ **Decision, 2026-09-21.** A Caddy this package manages runs `caddy run --resume --config <file>`
+with `XDG_CONFIG_HOME` set to a directory of its own, so a restart runs the last config Caddy
+**accepted**. After every successful load (ours included) Caddy writes the config JSON to
+`$XDG_CONFIG_HOME/caddy/autosave.json`; `--resume` starts from it, and from `--config` only when no
+autosave exists (cmd/commandfuncs.go cmdRun). Read in caddyserver/caddy v2.11.4:
+
+- ★ **A refused Caddyfile on disk cannot take sites down.** The file is the first-boot fallback: a
+  new host, or an autosave someone deleted.
+- ★ **Its own directory,** so nothing else (a Homebrew service, a person's `caddy run`) writes the
+  autosave it resumes from. With neither `HOME` nor `XDG_CONFIG_HOME` a daemon would use `./caddy/`
+  under its working directory (storage.go AppConfigDir).
+- ⛔ **Set `XDG_CONFIG_HOME` in the job's `environment`, not the envfile.** The autosave path is
+  fixed when the binary starts (storage.go `var ConfigAutosavePath`), before `--envfile` is read.
+- ⛔ **No `persist_config off`** in a managed Caddyfile. It stops the autosave, so `--resume` starts
+  from a stale one (the last config before it) or, with none, from the file.
+- ⚠️ **A hand change through the API survives a restart.** The next plan reports it as drift, and the
+  deploy puts the declaration back.
+- ⚠️ **SIGUSR1 is not a way to change config.** After a resumed start Caddy records no source file
+  (cmdRun calls `SetLastConfig` only after loading `--config`), so SIGUSR1 is ignored with the log
+  line `last config unknown`. Our `Caddy-Config-Source-File` header keeps a source Caddy already
+  has (caddy.go ClearLastConfigIfDifferent) and never sets one. After a first boot from the file,
+  SIGUSR1 still reloads it: the text the deploy wrote. Change config by deploying. Editing the file
+  and running `caddy reload` is a hand `/load`, which the next plan reports as drift.
+- ⛔ **No `--watch`.** After a resumed start it has no file to watch, and falls back to a `Caddyfile`
+  in the working directory (cmd/main.go watchConfigFile).
+
+A Caddy not yet moved over (no `--resume`) restarts from `--config`: see the ⚠️ in
+[Order](#order-file-then-load).
 
 ## Secrets
 
@@ -133,31 +148,33 @@ bcrypt/argon2 hashes). It never echoes what it found. It is a tripwire, not a sc
 
 ## The admin endpoint
 
-⛔ The admin API has no authentication. `localCaddyAdmin()` accepts only `http://` loopback
-(`127.0.0.0/8`, `localhost`, `[::1]`) or `unix:///path`; the default is `http://127.0.0.1:2019`.
-
-- **Host and Origin.** Caddy refuses a request whose `Host` is not an allowed origin (DNS-rebinding
-  guard; measured on Caddy 2.11.4: `403 host not allowed`), and checks `Origin` when one is sent or
-  `enforce_origin` is on. The transport sends both as the Caddy CLI does. A unix socket skips the
-  Host check entirely.
-- **`admin { origins … }`** narrowed, or **an SSH-forwarded port** (Caddy checks the Host against
-  ITS port): pass `hostHeader: 'localhost:2019'`.
-- **Another host's Caddy** (SSH later): forward its socket or port to loopback here and point a
-  `localCaddyAdmin()` at it, or implement `CaddyAdmin` over your own route. Never expose :2019.
-- **A Caddyfile cannot strand the provider.** Before loading, the adapted `admin` block is refused
-  if it turns the API off, listens off loopback or somewhere the transport does not reach (another
-  port, socket or loopback address: `[::1]` is not `127.0.0.1`, and `localhost` binds IPv4), allows
-  no Host the transport sends (its `origins`, or Caddy's loopback defaults when there are none), sets
-  `enforce_origin` over a unix socket (no Origin is sent there), enables `remote`, or pulls config.
-- ⛔ **No `admin` address means Caddy's default** (`localhost:2019`, or `$CADDY_ADMIN`) after the
-  load. That is refused unless the transport is at that default: a Caddy reached on a socket or
-  another port declares `admin <address>` in its Caddyfile.
+⛔ The admin API has no authentication: `localCaddyAdmin()` accepts only `http://` loopback or
+`unix:///path` (default `http://127.0.0.1:2019`), and a Caddyfile whose `admin` block would move,
+expose or lock out the API is refused before it loads. Host/Origin checks, narrowed `origins`, SSH
+forwards and every refusal: [caddy-admin.md](./caddy-admin.md).
 
 ## Adoption
 
-With no state, `read` reports the running Caddy's live config as plain (owned) attributes, so the
-first deploy adopts it silently and its forced update loads the declared Caddyfile — a full replace
-of whatever ran before. ⚠️ Review the plan: the Caddy on this loopback admin API is the one you get.
+★ **Nothing is adopted silently** (decision, 2026-09-21) — the rule `HostFile` and `LaunchdJob` keep.
+With no state, `read` is Alchemy's adoption probe, and what the Caddy runs decides:
+
+| running                             | read      | plan                                                       |
+| ----------------------------------- | --------- | ---------------------------------------------------------- |
+| the declared config (same digest)   | ours      | adopted; the forced update loads nothing                   |
+| nothing (`null`, or no apps)        | absent    | create — nothing to take over, as an empty R2 lock is none |
+| anything else                       | `Unowned` | refused unless the deploy runs with `--adopt`              |
+| a Caddyfile that cannot be compared | `Unowned` | the same, with a warning saying why                        |
+| no Caddy answering                  | absent    | create, with a warning; the apply checks again             |
+
+- ⚠️ **Alchemy skips the probe while the props hold an Output** — always on `caddyWithFile()`'s first
+  deploy, whose `sourceFile` is the HostFile's path. So the apply of a create checks too, and fails
+  before any `/load` unless the deploy runs with `--adopt`. The HostFile is written by then (a file
+  already at the path is the HostFile's own `Unowned`); under `--resume` a restart still runs the
+  autosave.
+- ★ **That apply-time check resolves adoption as the planner does:** a resource-scoped `adopt(…)`,
+  else `--adopt`. So `.pipe(adopt(false))` still refuses under `--adopt`, and `adopt(true)` works.
+- ★ **An uncomparable Caddyfile is `Unowned`, not an error**: the same read recovers an interrupted
+  create with that deploy's props, and a throw would fail every later plan, the fixed one included.
 
 ## Removing it
 
@@ -177,4 +194,6 @@ it by hand at its admin API.
   its launchd job has Caddy listening. The transport retries a refused connection (`retries`,
   `retryDelayMs`; default 2 × 500 ms) — raise them, or rerun the deploy.
 - ⚠️ One `CaddyAdmin` per stack: the transport picks the Caddy, not a prop. Pointing it at another
-  Caddy plans an update that loads there; the old one keeps what it had.
+  Caddy plans an update; the old one keeps what it had. ⛔ State vouches only for the Caddy it was
+  applied to, so the apply loads there only if it serves nothing, runs the declared config or the
+  one last stored — anything else needs `--adopt`.

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

@@ -0,0 +1,147 @@
+# Deploying a Mac host as yourself — `sudoRunner()`
+
+A host stack that declares system daemons needs root for a handful of calls. `sudoRunner()` lets
+the deploy run as you (the operator) and sends **only those calls** through `sudo -n`, in fixed
+argv shapes, logging each one. It is an explicit opt-in: nothing falls back to it, and
+`localRunner()` stays the default and never elevates.
+
+```ts
+import { launchdProviders, sudoRunner } from '@homeflare/alchemy/launchd';
+
+const runner = sudoRunner({
+  // ⛔ 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
+});
+// Provide launchdProviders(runner) alongside the stack's other provider layers.
+```
+
+## What runs as root: the whole list
+
+Each is `/usr/bin/sudo -n -- <argv>`, every program by absolute path, never through a shell.
+
+| when                             | argv                                                                   |
+| -------------------------------- | ---------------------------------------------------------------------- |
+| a system job is bootstrapped     | `/bin/launchctl bootstrap system /Library/LaunchDaemons/<label>.plist` |
+| a system job is booted out       | `/bin/launchctl bootout system/<label>`                                |
+| (your own code, via `exec`)      | `/bin/launchctl kickstart [-k] [-p] system/<label>`                    |
+| a file under a prefix is written | `/usr/bin/install -S -m <0644> [-o <uid>] [-g <gid>] <staged> <path>`  |
+| a file under a prefix is removed | `/bin/rm -f -- <path>`                                                 |
+
+- A file's bytes never reach argv or the log: they are written, as you, to a `0600` file in a
+  fresh `0700` temp directory. `install` copies that file (and only that file) into place, and
+  the temp directory is removed afterwards, whether or not the install succeeded.
+- `install` writes a temp file beside the target and renames it (install(1) on macOS 27.2), so the
+  target is never torn. `-S` adds the fsync.
+- Owner and group are numeric ids, resolved by the provider before the call.
+
+## What stays as you
+
+- `launchctl print` and `print-disabled`. launchctl(1): "Anyone may read or query the system
+  domain"; measured on macOS 27.2, too (see `src/launchd/launchctl.ts`).
+- User and group lookups, `id -G`, every file read and `lstat`.
+- Files outside every prefix, and your own `gui/<uid>` jobs.
+
+★ 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),
+  `bootstrap system <directory>` (which loads every plist in it), a plist anywhere but
+  `/Library/LaunchDaemons/<label>.plist` (the only place launchd loads daemons from at boot),
+  `rm -r`, `install -d`, a label under `org.nixos.`, `com.apple.` or `homebrew.mxcl.`, and any
+  argv whose program is `sudo`.
+- A system job's `bootstrap` or `bootout` when `/Library/LaunchDaemons` is not a prefix. ⚠️ Without
+  it a delete would boot the job out, then fail to remove its plist, which launchd loads again at
+  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
+  the same.
+- A file you could not read back. Both providers read every write back, and read again at every
+  plan, as you. A root-only `0600` would be installed, then fail with `EACCES` and stay on disk
+  with no state. Membership comes from `id -G`, because macOS caps `getgroups()` at 16 (measured
+  2026-09-21: 16 against 18).
+- Another user's `gui/<uid>` or `user/<uid>` domain. Only the system domain is elevated.
+
+Every refusal above throws `SudoRefusedError`: nothing ran as root. A privileged command that ran
+and failed throws a plain `Error` with its exit code.
+
+## When sudo wants a password
+
+`sudo -n` never prompts. It fails at once, and the error says so: `a password is required, and
+this runner never prompts`. The command did not run. You have two options.
+
+1. **`sudo -v` just before the deploy.** This caches a ticket. By default it lasts 5 minutes and
+   is tied to one terminal (sudoers(5): `timestamp_timeout`, `timestamp_type`).
+   ⚠️ A deploy that outlives the ticket fails at its next privileged call. Every step is
+   idempotent (Alchemy requires `delete` to be), so `sudo -v` and deploying again converges. The
+   exception is a `LaunchdJob` label or domain change: it is delete-first, so if it fails between
+   the delete and the create, the job is down until you redeploy.
+2. **A `NOPASSWD` sudoers rule for exactly the shapes above.**
+   - ⛔ **That rule is root-equivalent.** Anyone who may `install` into `/Library/LaunchDaemons`
+     and `launchctl bootstrap system` can run any program as root. The allowlist protects you
+     from mistakes, not from the account that holds the rule.
+   - ⛔ **Never use wildcards in the arguments.** sudoers(5): in arguments, `*` also matches spaces
+     and `/`, so `/bin/rm -f -- /opt/example/*` matches `../../etc/x` and two paths at once. Use
+     `^…$` regular expressions (sudo 1.9.10 and later; macOS 27.2 ships 1.9.17p2) and forbid
+     `..`. Check the file with `visudo -c -f <file>` before you install it.
+   - ⚠️ The kit ships no tested rule. Nothing here has run sudo.
+
+⚠️ The error text sudo prints is **reasoned, not measured**. It comes from sudoers(5) and sudo(8)
+for sudo 1.9.17p2. A sudo refusal the runner does not recognise comes back as a failed command,
+with sudo's own stderr.
+
+## The log
+
+Each privileged call logs one line before it runs:
+
+```text
+homeflare/launchd sudo -n ["/bin/launchctl","bootstrap","system","/Library/LaunchDaemons/com.example.exporter.plist"]
+```
+
+The argv is written as JSON, so a space in a path cannot hide a second argument. The line holds
+the argv only, never file content. ⛔ A custom `log` should keep every line: the log is the only
+record of what ran as root.
+
+## Limits
+
+- ⚠️ **Moving a job from `system` to another user's `gui/<uid>` passes the plan and fails at
+  apply**, after the old job was already removed. The runner reports `privileged: true`, so the
+  plan-time check lets it through, and the refusal only comes at the write. Do that move as a
+  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 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
@@ -112,8 +113,11 @@ The `system` domain, and another user's `gui/<uid>`, need root. The provider ref
 unless the runner is root (`effectiveUid() === 0`) or was deliberately built with
 `privileged: true`. `localRunner()` — the default — is never privileged and never calls `sudo`, so:
 
-- **system daemons:** start the whole deploy as root; or pass `launchdProviders(yourRunner)` where
-  `yourRunner` is a `HostRunner` you wrote that already holds root (a root helper, say).
+- **system daemons, deployed as yourself:** `launchdProviders(sudoRunner({ prefixes }))` sends only
+  the privileged calls through `sudo -n`, from a fixed allowlist, logging each. It never prompts.
+  See [launchd-sudo.md](./launchd-sudo.md).
+- **system daemons, deployed as root:** start the whole deploy as root; or pass
+  `launchdProviders(yourRunner)` where `yourRunner` is a `HostRunner` that already holds root.
 - **your own agents** (`gui/<your uid>`): no root needed.
 
 Reading (`launchctl print`, `print-disabled`) needs no root. ⚠️ A `HostFile` whose mode hides it
@@ -123,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
@@ -163,5 +170,5 @@ Nix job is booted out first. Per job:
 `HostRunner` (see `src/launchd/runner.ts`) is `exec(argv)` (never through a shell), `readFile`,
 `stat` (lstat), `writeFileAtomic`, `removeFile`, `lookupUser`, `lookupGroup`, `sleep`, plus
 `privileged` and `effectiveUid()`. `localRunner()` implements it with `node:fs` and
-`node:child_process`; tests use an in-memory fake, so nothing in the test suite runs `launchctl` or
-writes outside a temp directory.
+`node:child_process`; `sudoRunner()` wraps it and elevates the allowlist. Tests use an in-memory
+fake, so nothing in the test suite runs `launchctl` or `sudo`, or writes outside a temp directory.