@homeflare/alchemy 0.8.0 → 0.10.1

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.8.0",
-  "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy.",
+  "version": "0.10.1",
+  "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

@@ -5,7 +5,7 @@
  * 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 (host-effect.ts adoptEnabled).
+ *   in `Stack.resources` fails here (ownership/adopt.ts adoptEnabled).
  */
 import { afterEach, expect, test } from 'bun:test';
 import { push } from 'alchemy';

package/src/caddy/config-lifecycle.ts

@@ -172,7 +172,7 @@ export type Applied = {
  * What this apply may load over — config.ts decides from the state and the adopt setting:
  *   · `takeOver` — any running config: the state was applied to THIS Caddy (an update, drift
  *     correction, or a create the engine adopted), or adoption is on (`--adopt`, or the
- *     resource's own `adopt(true)` — host-effect.ts adoptEnabled).
+ *     resource's own `adopt(true)` — ownership/adopt.ts adoptEnabled).
  *   · otherwise only a claimable one — plus, as `stored`, the digest the state last recorded: a
  *     Caddy reached at a NEW endpoint that runs exactly that is the same config under another name.
  */

package/src/caddy/config.ts

@@ -27,7 +27,8 @@ import { Unowned } from 'alchemy/AdoptPolicy';
 import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { adoptEnabled, lift, resolvedString } from '../launchd/host-effect.ts';
+import { lift, resolvedString } from '../launchd/host-effect.ts';
+import { adoptEnabled } from '../ownership/adopt.ts';
 import { CaddyAdminService, CaddyUnreachableError } from './admin.ts';
 import type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
 import { diffConfig, probeLive, readLive, reconcileConfig } from './config-lifecycle.ts';

package/src/launchd/adopt-apply.test.ts

@@ -0,0 +1,166 @@
+/**
+ * `--adopt` and `adopt(…)` at APPLY, for HostFile and LaunchdJob — the create Alchemy never probed
+ * (a prop still an Output at plan time). Before 2026-09-21 these reconciles refused a foreign file
+ * or job whatever the deploy said, so the flag the refusal told you to use could not work there.
+ * They now resolve adoption the way the planner does (ownership/adopt.ts adoptEnabled), BOTH ways —
+ * for a CREATE only: the row Apply committed for this instance is `creating`. ⛔ A replace's new
+ * generation (a `replacing` row, `output` undefined all the same) is never adoptable at apply.
+ * ★ Registered through the REAL `Resource` under a Stack, as caddy/adopt-scope.test.ts is, over a
+ *   state store holding the row Apply commits before it calls reconcile.
+ */
+import { describe, expect, test } from 'bun:test';
+import { AdoptPolicy, adopt } from 'alchemy/AdoptPolicy';
+import { Artifacts, makeScopedArtifacts } from 'alchemy/Artifacts';
+import { InMemoryService } from 'alchemy/State/InMemoryState';
+import type { ResourceState } from 'alchemy/State/ResourceState';
+import { State } from 'alchemy/State/State';
+import { Stack } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { noteUnfinished } from '../ownership/resume.ts';
+import { fakeRunner } from './fake-runner.ts';
+import { HostFile, HostFileProvider } from './host-file.ts';
+import { LaunchdJob, LaunchdJobProvider } from './job.ts';
+import type { LaunchdJobAttributes } from './job-form.ts';
+import { hostRunnerLayer } from './runner.ts';
+
+type Scope = 'adopt(true)' | 'adopt(false)' | 'none';
+
+const FOREIGN = new TextEncoder().encode('someone else wrote this\n');
+const PATH = '/etc/example/a.conf';
+const PLIST = '/Library/LaunchDaemons/com.example.job.plist';
+const JOB = { domain: 'system', label: 'com.example.job', programArguments: ['/bin/job'] } as const;
+
+const host = () => {
+  const fake = fakeRunner({ dirs: { '/Library/LaunchDaemons': 0, '/etc/example': 0 }, euid: 0 });
+  for (const path of [PATH, PLIST]) {
+    fake.files.set(path, { bytes: FOREIGN, gid: 0, kind: 'file', mode: 0o644, uid: 0 });
+  }
+  return fake;
+};
+
+const scoped = <A extends Effect.Effect<unknown, unknown, unknown>>(declared: A, scope: Scope) =>
+  scope === 'none' ? declared : (declared.pipe(adopt(scope === 'adopt(true)')) as A);
+
+/** The row Apply commits before reconcile: a create's, or a replace's new generation's. */
+type Generation = 'creating' | 'replacing';
+
+/** Register `family` with `scope` under a deploy whose `--adopt` is `flag`; reconcile it statelessly. */
+const firstApply = (
+  family: 'file' | 'job',
+  scope: Scope,
+  flag: boolean,
+  output?: unknown,
+  generation: Generation = 'creating',
+  /** The plan's diff saw this generation's row with no attributes (ownership/resume.ts). */
+  unfinished = false,
+) => {
+  const fake = host();
+  const fqn = family === 'file' ? 'conf' : 'job';
+  const row = { fqn, instanceId: 'i-1', status: generation } as unknown as ResourceState;
+  const spec = { actions: {}, bindings: {}, name: 'test', resources: {}, stage: 'test' };
+  const call = {
+    bindings: [] as never,
+    instanceId: 'i-1',
+    olds: undefined,
+    session: undefined as never,
+  };
+  const program: Effect.Effect<unknown, unknown, AdoptPolicy | Stack> =
+    family === 'file'
+      ? Effect.gen(function* () {
+          yield* scoped(HostFile('conf', { content: 'x', path: PATH }), scope);
+          const provider = yield* HostFile.Provider;
+          const news = { content: 'x', path: PATH };
+          return yield* provider.reconcile({
+            ...call,
+            fqn: 'conf',
+            id: 'conf',
+            news,
+            output: undefined,
+          });
+        }).pipe(
+          Effect.provide(HostFileProvider().pipe(Layer.provide(hostRunnerLayer(fake.runner)))),
+        )
+      : Effect.gen(function* () {
+          yield* scoped(LaunchdJob('job', JOB), scope);
+          const provider = yield* LaunchdJob.Provider;
+          const prior = output as LaunchdJobAttributes | undefined;
+          return yield* provider.reconcile({
+            ...call,
+            fqn: 'job',
+            id: 'job',
+            news: JOB,
+            output: prior,
+          });
+        }).pipe(
+          Effect.provide(LaunchdJobProvider().pipe(Layer.provide(hostRunnerLayer(fake.runner)))),
+        );
+  const bag = makeScopedArtifacts(new Map(), fqn);
+  const noted = unfinished ? noteUnfinished('i-1') : Effect.void;
+  const applying = Effect.runPromise(
+    Effect.andThen(noted, program).pipe(
+      Effect.provideService(Artifacts, bag),
+      Effect.provideService(AdoptPolicy, flag),
+      Effect.provideService(State, InMemoryService({ test: { test: { [fqn]: row } } })),
+      Effect.provideService(Stack, spec as never),
+    ),
+  );
+  return { applying, fake };
+};
+
+const REFUSED = /already exists and is not this resource|is already on this host/;
+
+describe.each(['file', 'job'] as const)('%s: a first apply over a foreign object', (family) => {
+  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)('with %s', async (_, scope, flag, takesOver) => {
+    const { applying, fake } = firstApply(family, scope, flag);
+    const path = family === 'file' ? PATH : PLIST;
+    if (takesOver) {
+      await applying;
+      expect(fake.files.get(path)?.bytes).not.toEqual(FOREIGN);
+    } else {
+      await expect(applying).rejects.toThrow(REFUSED);
+      expect(fake.files.get(path)?.bytes).toEqual(FOREIGN);
+    }
+  });
+});
+
+test('a LaunchdJob rename onto a foreign job stays refused, --adopt or not', async () => {
+  const old = {
+    domain: 'system',
+    label: 'com.example.old',
+    loaded: false,
+    plistPath: '/Library/LaunchDaemons/com.example.old.plist',
+    plistSha256: '',
+    serviceTarget: 'system/com.example.old',
+  };
+  const { applying, fake } = firstApply('job', 'adopt(true)', true, old);
+  await expect(applying).rejects.toThrow(REFUSED);
+  expect(fake.files.get(PLIST)?.bytes).toEqual(FOREIGN);
+});
+
+describe.each(['file', 'job'] as const)('%s: a replace onto a foreign object', (family) => {
+  test.each([
+    ['--adopt', 'none', true],
+    ['adopt(true)', 'adopt(true)', false],
+  ] as const)(
+    'stays refused under %s: the plan never offered its new generation adoption',
+    async (_, scope, flag) => {
+      const { applying, fake } = firstApply(family, scope, flag, undefined, 'replacing');
+      await expect(applying).rejects.toThrow(REFUSED);
+      expect(fake.files.get(family === 'file' ? PATH : PLIST)?.bytes).toEqual(FOREIGN);
+    },
+  );
+
+  test('an UNFINISHED replace (its row seen by the plan) resumes under --adopt, as a create does', async () => {
+    const refused = firstApply(family, 'none', false, undefined, 'replacing', true);
+    await expect(refused.applying).rejects.toThrow(REFUSED);
+    const { applying, fake } = firstApply(family, 'none', true, undefined, 'replacing', true);
+    await applying;
+    expect(fake.files.get(family === 'file' ? PATH : PLIST)?.bytes).not.toEqual(FOREIGN);
+  });
+});

package/src/launchd/fake-runner.ts

@@ -9,6 +9,8 @@
  *   job exits non-zero; a job can linger after bootout (`lingerPrints`); a gui uid with no login
  *   session answers 112 (`loggedOut`); writes into a root-owned directory, or a chown to another
  *   uid, need root.
+ * ★ Every directory ABOVE a declared one exists, root's and `0755`, as `/`, `/Library` and `/opt`
+ *   are on a Mac; `acls` holds the `ls -lden` entry lines a directory prints (sudo-acl.ts).
  */
 import { LAUNCHCTL, NOT_FOUND, NO_DOMAIN } from './launchctl.ts';
 import type { ExecResult, FileStat, HostRunner, HostUser, WriteOptions } from './runner.ts';
@@ -54,6 +56,16 @@ export const fakeRunner = (options: FakeOptions = {}) => {
   const root = privileged || euid === 0;
   const dirs = new Map(Object.entries(options.dirs ?? {}));
   const files = new Map<string, Entry>();
+  /** Directory → the ACL entry lines `ls -lden` prints under it. */
+  const acls = new Map<string, string[]>();
+  /** The directories above the declared ones, as the host starts: root's, `0755`. */
+  const above = new Set<string>(['/']);
+  for (const dir of dirs.keys()) {
+    const parts = dir.split('/').slice(1, -1);
+    for (const index of parts.keys()) above.add(`/${parts.slice(0, index + 1).join('/')}`);
+  }
+  for (const dir of dirs.keys()) above.delete(dir);
+  const implied = (path: string) => above.has(path);
   const calls: string[][] = [];
   /** target → pid (undefined = loaded, not running). */
   const loaded = new Map<string, number | undefined>();
@@ -128,6 +140,16 @@ export const fakeRunner = (options: FakeOptions = {}) => {
     exec: async (argv) => {
       calls.push([...argv]);
       if (argv[0] === LAUNCHCTL) return launchctl(argv.slice(1));
+      if (argv[0] === '/bin/ls' && argv[1] === '-lden' && argv[2] === '--') {
+        const paths = argv.slice(3);
+        if (paths.some((path) => !dirs.has(path) && !files.has(path) && !implied(path)))
+          return fail(1, 'ls: No such file or directory');
+        const lines = paths.flatMap((path) => [
+          `drwxr-xr-x  2 0  0  64 Sep 21 10:00 ${path}`,
+          ...(acls.get(path) ?? []),
+        ]);
+        return ok(lines.join('\n'));
+      }
       return fail(127, `fake: no program ${String(argv[0])}`);
     },
     lookupGroup: async (nameOrId) => options.groups?.[nameOrId],
@@ -153,9 +175,9 @@ export const fakeRunner = (options: FakeOptions = {}) => {
           size: entry.bytes.length,
           uid: entry.uid,
         };
-      return dirs.has(path)
-        ? { gid: 0, kind: 'directory', mode: 0o755, size: 0, uid: dirs.get(path) ?? 0 }
-        : undefined;
+      if (dirs.has(path) || implied(path))
+        return { gid: 0, kind: 'directory', mode: 0o755, size: 0, uid: dirs.get(path) ?? 0 };
+      return undefined;
     },
     writeFileAtomic: async (path: string, bytes: Uint8Array, write: WriteOptions) => {
       calls.push(['write', path]);
@@ -172,5 +194,5 @@ export const fakeRunner = (options: FakeOptions = {}) => {
       });
     },
   };
-  return { calls, disabled, dirs, files, loaded, runner, state };
+  return { acls, calls, disabled, dirs, files, loaded, runner, state };
 };

package/src/launchd/host-effect.ts

@@ -1,17 +1,13 @@
 /**
  * The one place a HostRunner's promises become Effects — plus the one probe of an unresolved
- * `news` both providers' diffs share, and the engine's adopt setting for a check at apply.
+ * `news` both providers' diffs share. (The engine's adopt setting lives in ownership/adopt.ts.)
  *
  * ★ The lifecycle files are plain async functions over a HostRunner (see runner.ts for why the
  *   runner is promise-based), so each provider handler is a single `lift(() => step(runner, …))`.
  * ⚠️ A thrown Error stays that Error — its message is the refusal a deploy prints. Anything else
  *   thrown is wrapped, so the failure channel is always an Error with a readable message.
  */
-import { AdoptPolicy } from 'alchemy/AdoptPolicy';
-import { AlchemyContext } from 'alchemy/AlchemyContext';
-import { Stack } from 'alchemy/Stack';
 import * as Effect from 'effect/Effect';
-import * as Option from 'effect/Option';
 
 export const lift = <A>(step: () => Promise<A>): Effect.Effect<A, Error> =>
   Effect.tryPromise({
@@ -30,31 +26,3 @@ export const resolvedString = (news: unknown, key: string): string | undefined =
   const value = (news as Record<string, unknown>)[key];
   return typeof value === 'string' ? value : undefined;
 };
-
-/**
- * Whether the resource at `fqn` may be adopted, resolved exactly as the planner resolves it (alchemy
- * beta.79 Plan.ts: `resource.Adopt ?? shouldAdopt`): a resource-scoped `adopt(…)`, else the
- * `AdoptPolicy` service, else `AlchemyContext.adopt`, else off.
- * ★ FOR A CREATE THE ENGINE NEVER PROBED. Alchemy skips the adoption probe while `news` holds an
- *   Output, so an ownership check that must still honour `--adopt` can only run at apply. All three
- *   reach the apply: Alchemist runs plan AND apply under the session context, which provides the
- *   services from the CLI flag and the Stack the resources registered on (Alchemist/Session.ts,
- *   routes/stack.ts; Apply.ts reads the same Stack).
- * ⛔ THE RESOURCE-SCOPED SETTING WINS, BOTH WAYS. The engine captures `adopt(…)` on the resource at
- *   registration (Resource.ts `Adopt`, into `Stack.resources[fqn]`) and never hands it to a
- *   provider. Reading only the deploy-wide flag let `--adopt` take over a resource declared
- *   `.pipe(adopt(false))` — which the planner refuses — and refused one declared `adopt(true)`.
- * ⚠️ `resources` carries an `@internal` comment in Alchemy's source, but it is in the published types
- *   and the planner reads `Adopt` from it. caddy/adopt-scope.test.ts registers through the real
- *   `Resource`, so an upgrade that stops recording it there fails the suite.
- */
-export const adoptEnabled = (fqn: string): Effect.Effect<boolean> =>
-  Effect.gen(function* () {
-    const stack = yield* Effect.serviceOption(Stack);
-    const scoped = Option.isSome(stack) ? stack.value.resources[fqn]?.Adopt : undefined;
-    if (scoped !== undefined) return scoped;
-    const policy = yield* Effect.serviceOption(AdoptPolicy);
-    if (Option.isSome(policy)) return policy.value;
-    const context = yield* Effect.serviceOption(AlchemyContext);
-    return Option.isSome(context) ? context.value.adopt : false;
-  });

package/src/launchd/host-file-lifecycle.ts

@@ -15,7 +15,7 @@ import {
   fileProblems,
 } from './host-file-form.ts';
 import { sha256Hex } from './job-form.ts';
-import { type HostRunner, canActAsRoot } from './runner.ts';
+import { type HostRunner, type WriteOptions, canActAsRoot } from './runner.ts';
 
 type Desired = {
   readonly bytes: Uint8Array;
@@ -72,29 +72,55 @@ export const readFileAttributes = async (
   };
 };
 
+const writeOptionsOf = (want: Desired): WriteOptions => ({
+  mode: want.mode,
+  ...(want.uid === undefined ? {} : { uid: want.uid }),
+  ...(want.gid === undefined ? {} : { gid: want.gid }),
+});
+
 const matches = (live: HostFileAttributes, want: Desired): boolean =>
   live.sha256 === want.sha256 &&
   live.mode === want.mode &&
   (want.uid === undefined || live.uid === want.uid) &&
   (want.gid === undefined || live.gid === want.gid);
 
+/**
+ * ★ A PLAN THAT WILL WRITE ASKS THE RUNNER FIRST (`checkWrite`, when it has one): sudoRunner's
+ *   refusals — a setuid or group-writable root file, a directory under a prefix another user may
+ *   change — then fail the plan, before any resource is applied, instead of halfway through it.
+ */
 export const diffFile = async (
   runner: HostRunner,
   news: HostFileProps,
   output: HostFileAttributes,
 ): Promise<Diff> => {
-  // ★ Create-before-delete: two paths can hold two files at once, so nothing forces deleteFirst.
-  if (news.path !== output.path) return { action: 'replace' };
   const want = await desiredFile(runner, news);
-  if (want.sha256 !== output.sha256) return { action: 'update' };
+  const writes = async (diff: Diff): Promise<Diff> => {
+    await runner.checkWrite?.(news.path, writeOptionsOf(want));
+    return diff;
+  };
+  // ★ Create-before-delete: two paths can hold two files at once, so nothing forces deleteFirst.
+  if (news.path !== output.path) return writes({ action: 'replace' });
+  if (want.sha256 !== output.sha256) return writes({ action: 'update' });
   const live = await readFileAttributes(runner, news.path);
-  return live !== undefined && matches(live, want) ? { action: 'noop' } : { action: 'update' };
+  return live !== undefined && matches(live, want)
+    ? { action: 'noop' }
+    : writes({ action: 'update' });
 };
 
+/**
+ * `adopt` is whether adoption is on AND this apply is a create or an unfinished generation of our
+ * own (ownership/adopt.ts adoptsAtApply). It lets such a generation take over a file already at the
+ * path — the takeover the plan's probe would have allowed, had it run. ⛔ A move onto an occupied
+ *   path stays refused, both ways the engine drives one: an `update` across the move (`moved`,
+ *   below), and a fresh replace's new generation, which the caller never marks adoptable (its
+ *   `output` is undefined too, so this function cannot tell it from a create by itself).
+ */
 export const reconcileFile = async (
   runner: HostRunner,
   props: HostFileProps,
   output?: HostFileAttributes,
+  adopt = false,
 ): Promise<HostFileAttributes> => {
   const want = await desiredFile(runner, props);
   // ⛔ NO SILENT SUDO: handing a file to another user is root's call (chown(2)), so say so up front.
@@ -120,11 +146,14 @@ export const reconcileFile = async (
   const prior = moved ? undefined : output;
   /**
    * ⛔ A FILE THIS RESOURCE DOES NOT OWN IS NEVER OVERWRITTEN. With no prior state for this path,
-   *   the engine's adoption probe has already refused anything it found — except at the new path of
-   *   a replace, where it reads nothing. A path typo there would otherwise overwrite, say, a system
-   *   file that a fresh declaration of the same path would have been refused as `Unowned`.
+   *   the engine's adoption probe has already refused anything it found — except where it never
+   *   looked: the new path of a replace, and a create whose props still held an Output at plan
+   *   time. A path typo there would otherwise overwrite, say, a system file that a fresh
+   *   declaration of the same path would have been refused as `Unowned`. ★ With adoption on, a
+   *   create takes it over, as the probe would have let it (decided 2026-09-21).
    */
-  if (prior === undefined && before !== undefined && !matches(before, want)) {
+  const takeOver = adopt && output === undefined;
+  if (prior === undefined && before !== undefined && !matches(before, want) && !takeOver) {
     throw refuse(
       props.path,
       'already exists and is not this resource. Remove it, or declare it as a new resource and ' +
@@ -132,11 +161,7 @@ export const reconcileFile = async (
     );
   }
   if (before === undefined || !matches(before, want)) {
-    await runner.writeFileAtomic(props.path, want.bytes, {
-      mode: want.mode,
-      ...(want.uid === undefined ? {} : { uid: want.uid }),
-      ...(want.gid === undefined ? {} : { gid: want.gid }),
-    });
+    await runner.writeFileAtomic(props.path, want.bytes, writeOptionsOf(want));
   }
   // ⚠️ READ BACK, never echo the declaration: a umask, an ACL or a runner that ignored `uid` shows
   //   up here as a refusal instead of as a forever-`update`.