@homeflare/alchemy 0.8.0 → 0.10.1

package/dist/verify/spy.d.ts

@@ -0,0 +1,43 @@
+import { type ProviderService } from 'alchemy/Provider';
+import * as Context from 'effect/Context';
+export type ReadAnswer = 'found' | 'unowned' | 'absent' | 'failed' | 'not-read';
+export type DiffAnswer = 'noop' | 'update' | 'replace' | 'none' | 'not-run';
+/** What the diff answered when asked again with the live values as its recorded props (recheck.ts). */
+export type RecheckAnswer = DiffAnswer | 'failed';
+/** Exactly what the planner handed a provider's `diff`. */
+export type DiffInput = Parameters<NonNullable<ProviderService['diff']>>[0];
+/** What one FQN's provider answered during the plan — the LAST answer of each kind. */
+export interface Seen {
+    read?: {
+        readonly answer: ReadAnswer;
+        readonly attributes: unknown;
+    };
+    /**
+     * ★ `input` IS THE WHOLE CALL, NOT ONLY `news`, so recheck.ts can ask the same question again
+     *   with one field changed. In memory only; the report carries field names, never values. An
+     *   observation built by hand without it (rows.ts's tests) is simply never rechecked.
+     */
+    diff?: {
+        readonly answer: DiffAnswer;
+        readonly news: unknown;
+        readonly input?: DiffInput;
+    };
+    recheck?: RecheckAnswer;
+}
+/** Keyed by FQN. Filled while the plan runs; read once it is done. */
+export type Observations = Map<string, Seen>;
+/** The refusal every write path answers with. Exported so a test can match it. */
+export declare const WRITE_REFUSED = "hf-adopt-verify never writes";
+export declare const diffAnswer: (diff: unknown) => DiffAnswer;
+/**
+ * One provider service, watched. ⚠️ The spread keeps `version`, `aliases`, `mode`, `stables`,
+ * `list` and the rest exactly as registered — the planner reads several of them.
+ */
+export declare const spyService: (type: string, service: ProviderService, seen: Observations) => ProviderService<import("alchemy").ResourceLike<string, any, object, any, any>, never, never, never, never, never, never, never, never>;
+/**
+ * The same context with every provider service — direct or inside a `Provider.collection` —
+ * replaced by its watched copy. Everything else (the state store, the stack, credentials) is the
+ * very object the session built.
+ */
+export declare const spyContext: <R>(context: Context.Context<R>, seen: Observations) => Context.Context<R>;
+//# sourceMappingURL=spy.d.ts.map

package/dist/verify/spy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spy.d.ts","sourceRoot":"","sources":["../../src/verify/spy.ts"],"names":[],"mappings":"AAsBA,OAAO,EAEL,KAAK,eAAe,EAGrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAG1C,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAChF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAC5E,uGAAuG;AACvG,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,QAAQ,CAAC;AAElD,2DAA2D;AAC3D,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,WAAW,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE5E,uFAAuF;AACvF,MAAM,WAAW,IAAI;IACnB,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC;IACrE;;;;OAIG;IACH,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAA;KAAE,CAAC;IAC3F,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,sEAAsE;AACtE,MAAM,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAU7C,kFAAkF;AAClF,eAAO,MAAM,aAAa,iCAAiC,CAAC;AAa5D,eAAO,MAAM,UAAU,SAAU,OAAO,KAAG,UAG1C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,UAAU,SAAU,MAAM,WAAW,eAAe,QAAQ,YAAY,2IAsCpF,CAAC;AAeF;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,WACjB,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,QACrB,YAAY,KACjB,OAAO,CAAC,OAAO,CAAC,CAAC,CAanB,CAAC"}

package/dist/verify/verify.d.ts

@@ -0,0 +1,43 @@
+import type { CompiledStack } from 'alchemy/Stack';
+import type * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import { type AdoptRow } from './rows.ts';
+export interface VerifyOptions {
+    /** Report every declared row and every pending deletion, not only rows without state. */
+    readonly all?: boolean;
+}
+export interface AdoptReport {
+    readonly stack: string;
+    readonly stage: string;
+    /** Resources the stack declares. */
+    readonly declared: number;
+    readonly rows: readonly AdoptRow[];
+}
+/** An imported stack and the context it plans under — what `Alchemist.open` returns. */
+export interface VerifySession {
+    readonly stack: CompiledStack<unknown, unknown>;
+    readonly context: Context.Context<unknown>;
+}
+/**
+ * Plan `session.stack` with watched providers and report each row without state (or, with
+ * `all`, every row). Never writes.
+ */
+export declare const verifySession: (session: VerifySession, options?: VerifyOptions) => Effect.Effect<AdoptReport, unknown>;
+/** Where the stack lives — the fields `alchemy plan` takes as flags. */
+export interface VerifyTarget {
+    /** The stack entrypoint, e.g. `alchemy.run.ts`. */
+    readonly entrypoint: string;
+    readonly stage: string;
+    readonly profile?: string;
+    readonly envFile?: string;
+}
+/**
+ * Import the stack the way the Alchemy CLI does and verify it.
+ *
+ * ★ `adopt: true`, ALWAYS, AND IT CANNOT WRITE. Planning is side-effect free (Plan.ts keeps the
+ *   adopted state in memory, alchemy#793), so the flag only lets an `Unowned` row reach its
+ *   `diff` instead of failing the plan — the report marks it, because the real deploy then needs
+ *   `--adopt`. A resource declared `.pipe(adopt(false))` still fails the plan, as it would deploy.
+ */
+export declare const verifyStack: (target: VerifyTarget, options?: VerifyOptions) => Effect.Effect<AdoptReport, unknown>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/verify/verify.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,KAAK,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,EAAE,KAAK,QAAQ,EAAyB,MAAM,WAAW,CAAC;AAGjE,MAAM,WAAW,aAAa;IAC5B,yFAAyF;IACzF,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;CACpC;AAED,wFAAwF;AACxF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5C;AA+DD;;;GAGG;AACH,eAAO,MAAM,aAAa,YACf,aAAa,YACb,aAAa,KACrB,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAyCpC,CAAC;AAEF,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,WACd,YAAY,YACX,aAAa,KACrB,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAIsB,CAAC"}

package/docs/adopt-verify.md

@@ -0,0 +1,119 @@
+# 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.
+
+An adopted `noop` with something under `changed` is asked once more (`src/verify/recheck.ts`).
+Plan.ts hands an adopted row's `diff` the declaration as its recorded props (`olds: news`), so a
+diff that compares recorded props with the declaration answers `noop` whatever the cloud holds.
+Alchemy's own `Cloudflare.R2Bucket` diff has that shape (`olds.domains` against `news.domains`).
+The replay passes the read's values for the changed fields as `olds`. A diff that reads the live
+object ignores them and says `noop` again, so the row passes with a note: the family does not
+manage those fields (CephPool's autoscaled `pg_num`). Anything else fails the row, and the JSON
+report carries the answer as `recheck`. Before this check, such a row passed with its drift
+listed beside the `ok`.
+
+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 not the verdict.** It compares same-named keys, and only decides whether an
+  adopted `noop` is asked again. A drift in a field the attributes rename or normalise shows
+  nothing there, and a diff that ignores the live object then goes unchallenged.
+- ⚠️ **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.