@homeflare/alchemy 0.7.0 → 0.10.0

package/docs/ownership.md

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

package/docs/peers.md

@@ -0,0 +1,39 @@
+# Peers — and why each pin exists
+
+The install line for `@homeflare/alchemy`, and why every peer on it and every entry in the
+`overrides` block is required. The block itself, which every consumer copies, is in the
+[README](../README.md#peers--and-one-override-you-need).
+
+```sh
+bun add @homeflare/alchemy alchemy@2.0.0-beta.79 effect@4.0.0-rc.115 \
+        @effect/platform-node@4.0.0-rc.115 cloudflare@4.5.0 mime@4.1.0 \
+        @distilled.cloud/cloudflare@1.0.0-rc.12
+```
+
+🔴 **Why, measured 2026-09-16 on 0.1.0 and re-checked 2026-09-17 against Alchemy 78.**
+Effect's `rc` line is not semver-compatible with itself. Alchemy 78's peer is
+`effect >= 4.0.0-rc.115`; an unlocked `@effect/platform-node-shared` still floats to the
+next rc and breaks at import. Pin the whole set.
+
+| what resolves                                                 | what happens                                           |
+| ------------------------------------------------------------- | ------------------------------------------------------ |
+| Alchemy 77 + `effect` → rc.115 (measured 2026-09-16)          | `TypeError: Config.string is not a function` at import |
+| `@effect/platform-node-shared` newer than the pinned `effect` | `Cannot find module 'effect/ByteSize'`                 |
+| `rolldown` → 1.2.9 via vite's `~1.2.6` (measured 2026-09-16)  | `GET …/rolldown-1.2.9.tgz - 404` at `bun add`          |
+| no `mime` (measured 2026-09-17 against Alchemy 78)            | `Cannot find package 'mime'` from cloudflare-runtime   |
+
+Alchemy 78 adapted to rc.115 — that first row is why we used to pin 112, not a reason to
+stay there. The override is still the only thing that holds the set together.
+
+⚠️ `@effect/platform-node` is **required, not optional**: Alchemy's module graph reaches
+`Cloudflare/Workers/WorkerBridge → @effect/platform-node/NodeServices` even when you only
+import the Proxmox subpath.
+
+⚠️ So is `mime`. Alchemy 78's `@alchemy.run/cloudflare-runtime` imported it without
+declaring it (measured 2026-09-17). 79 declares it; the peer stays so a consumer
+that followed the 78 README does not drop a required line.
+
+⚠️ So is `cloudflare`. It was marked optional in 0.1.1, which claimed the `/cloudflare`
+subpath would degrade without it — measured 2026-09-16, the subpath does not load at all:
+`Cannot find package 'cloudflare'`. An optional peer should mean a feature is absent, not
+that an import fails.

package/docs/proxmox-lxc.md

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

package/docs/proxmox.md

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.7.0",
-  "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy.",
+  "version": "0.10.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",
   "license": "MIT",
@@ -11,6 +11,9 @@
     "url": "git+https://github.com/taslabs-net/homeflare-kit.git",
     "directory": "packages/alchemy"
   },
+  "bin": {
+    "hf-adopt-verify": "./dist/verify/cli.js"
+  },
   "files": [
     "dist",
     "docs",
@@ -53,6 +56,10 @@
       "types": "./dist/caddy/index.d.ts",
       "default": "./dist/caddy/index.js"
     },
+    "./verify": {
+      "types": "./dist/verify/index.d.ts",
+      "default": "./dist/verify/index.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {

package/src/caddy/adopt-scope.test.ts

@@ -0,0 +1,82 @@
+/**
+ * A resource-scoped `adopt(…)` at apply — the create Alchemy never probed (caddyWithFile's first
+ * deploy). The planner resolves adoption as `resource.Adopt ?? --adopt` (alchemy beta.79 Plan.ts);
+ * the apply-time check must resolve it the same way, BOTH ways, or `--adopt` would take over a
+ * Caddy the stack declared `.pipe(adopt(false))`.
+ * ★ Registered through the REAL `Resource` (caddyWithFile under a Stack), not a hand-built map: the
+ *   lookup reads what Alchemy records at registration, so an upgrade that stops recording `Adopt`
+ *   in `Stack.resources` fails here (ownership/adopt.ts adoptEnabled).
+ */
+import { afterEach, expect, test } from 'bun:test';
+import { push } from 'alchemy';
+import { AdoptPolicy, adopt } from 'alchemy/AdoptPolicy';
+import { Stack } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { caddyAdminLayer } from './admin.ts';
+import { CaddyConfig, CaddyConfigProvider } from './config.ts';
+import { type FakeCaddy, fakeDefaultCaddy } from './fake-caddy.ts';
+import { caddyWithFile } from './with-file.ts';
+
+const SITE = 'app.example.com reverse_proxy 127.0.0.1:8080';
+/** A config someone else loaded: it serves a site, and it is not what the stack declares. */
+const FOREIGN = { apps: { http: { servers: { legacy: { listen: [':80'] } } } } };
+
+let fake: FakeCaddy | undefined;
+afterEach(() => {
+  fake?.stop();
+  fake = undefined;
+});
+
+type Scope = 'adopt(true)' | 'adopt(false)' | 'none';
+
+/**
+ * Declare caddyWithFile with `scope` under a deploy whose `--adopt` is `flag` — the session provides
+ * AdoptPolicy to registration AND apply, as Alchemist does — then apply the CaddyConfig with no state.
+ */
+const applyFirstDeploy = (scope: Scope, flag: boolean) => {
+  const made = fakeDefaultCaddy(FOREIGN);
+  fake = made.caddy;
+  const spec = { actions: {}, bindings: {}, name: 'test', resources: {}, stage: 'test' };
+  const declared = caddyWithFile('caddy', { caddyfile: SITE, path: '/usr/local/etc/Caddyfile' });
+  const scoped =
+    scope === 'none'
+      ? declared
+      : (declared.pipe(adopt(scope === 'adopt(true)')) as typeof declared);
+  const program = Effect.gen(function* () {
+    // ★ Under a namespace, so the FQN (`edge/caddy`) differs from the logical id (`caddy`).
+    yield* push('edge', scoped);
+    const provider = yield* CaddyConfig.Provider;
+    return yield* provider.reconcile({
+      bindings: [] as never,
+      fqn: 'edge/caddy',
+      id: 'caddy',
+      instanceId: 'i-1',
+      news: { caddyfile: SITE, sourceFile: '/usr/local/etc/Caddyfile' },
+      olds: undefined,
+      output: undefined,
+      session: undefined as never,
+    });
+  }).pipe(
+    Effect.provide(CaddyConfigProvider().pipe(Layer.provide(caddyAdminLayer(made.admin)))),
+    Effect.provideService(AdoptPolicy, flag),
+    Effect.provideService(Stack, spec as never),
+  );
+  return { applying: Effect.runPromise(program as Effect.Effect<unknown, unknown>), spec };
+};
+
+const loads = () => fake?.seen.filter((call) => call.path === '/load') ?? [];
+
+test.each([
+  ['adopt(false) under --adopt', 'adopt(false)', true, false],
+  ['adopt(true) without --adopt', 'adopt(true)', false, true],
+  ['no scope under --adopt', 'none', true, true],
+  ['no scope without --adopt', 'none', false, false],
+] as const)('a first deploy with %s', async (_, scope, flag, loaded) => {
+  const { applying, spec } = applyFirstDeploy(scope, flag);
+  if (loaded) await applying;
+  else await expect(applying).rejects.toThrow(/which this stack did not load.*--adopt/);
+  // ★ The lookup key is the FQN the engine hands reconcile — the one registration used.
+  expect(Object.keys(spec.resources)).toContain('edge/caddy');
+  expect(loads()).toHaveLength(loaded ? 1 : 0);
+});