@homeflare/alchemy 0.5.0 → 0.7.0

package/src/cloudflare/mesh-node-token.ts

@@ -0,0 +1,125 @@
+/**
+ * `fetchMeshNodeToken` — a Mesh node's enrolment token, fetched on demand for a one-off Bun
+ * `mesh-enroll` step. ⛔ Not a Resource, and never an attribute: see mesh-node-form.ts for why
+ * the token must stay out of Alchemy state.
+ *
+ * ⛔ WHERE THE VALUE MAY GO. Straight into a root-owned `0600` file on the node's host, which the
+ *   enrolment reads (`warp-cli --accept-tos connector new <token>`, per the Mesh get-started page,
+ *   read 2026-09-21). Nowhere else: not Alchemy state, not a secrets store (a runtime credential
+ *   belongs to the host that runs it), not a log line, not a CI variable. It is returned
+ *   `Redacted`, so an accidental `console.log` or `Effect.log` prints `<redacted>`; call
+ *   `Redacted.value` only at the write.
+ * ⚠️ `warp-cli` takes the token as an ARGUMENT, so it is visible in the host's process list for
+ *   the life of that command. Run the enrolment as root on the node itself, never over a shell
+ *   whose history is kept.
+ * ⚠️ THE ENDPOINT NEEDS A WRITE PERMISSION. Its API reference (read 2026-09-21) accepts
+ *   "Cloudflare One Connectors Write", "Cloudflare One Connector: cloudflared Write" or
+ *   "Cloudflare Tunnel Write"; the Mesh get-started guide also names "Cloudflare One Connector:
+ *   WARP Write". Connectors Write is in both lists. Mint a short-lived token for this step alone;
+ *   a read-only plan token gets a 403 here.
+ *
+ * ★ Requires distilled `Credentials` and an `HttpClient`, not Alchemy's CloudflareEnvironment: a
+ *   Bun script has no Alchemy profile, so the account id is an argument. Provide
+ *   `Credentials.fromApiToken({ apiToken })` (from `@distilled.cloud/cloudflare/Credentials`) and
+ *   `FetchHttpClient.layer`. ⛔ Not `Credentials.fromEnv()`: it falls back to the Global API Key
+ *   (`CLOUDFLARE_API_KEY` + `CLOUDFLARE_EMAIL`) when no token is set — and `refuseUnsafe` below
+ *   refuses that key rather than trusting the caller to have read this.
+ */
+import { Credentials } from '@distilled.cloud/cloudflare/Credentials';
+import * as zeroTrust from '@distilled.cloud/cloudflare/zero-trust';
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+import { MeshNodeError, findNodeByName } from './mesh-node-api.ts';
+
+/** Which node: by id (the `MeshNode` attribute) or by its exact name. */
+export type MeshNodeRef = { readonly accountId: string } & (
+  | { readonly id: string; readonly name?: undefined }
+  | { readonly name: string; readonly id?: undefined }
+);
+
+/**
+ * ⛔ REFUSED BEFORE ANY REQUEST IS SENT:
+ * - `DISTILLED_DEBUG_HTTP` set. distilled's Cloudflare protocol then `console.error`s the first
+ *   400 characters of EVERY response body (protocol.ts, measured in 1.0.0-rc.12) — the token
+ *   response is `{"success":true,…,"result":"<token>"}`, so the whole token lands on stderr and in
+ *   whatever captures it. The check reads `process.env` because that is what distilled reads.
+ * - The Global API Key (`apiKey` credentials). Account-wide and long-lived: the one credential a
+ *   one-off enrolment must never use.
+ * - An EMPTY API token. A denied secrets-store grant renders empty, and Cloudflare then answers
+ *   like a bad permission — which would send the operator to widen a grant that was fine
+ *   (client.ts says the same for `CLOUDFLARE_API_TOKEN`).
+ */
+const refuseUnsafe = Effect.gen(function* () {
+  if ((globalThis.process?.env?.['DISTILLED_DEBUG_HTTP'] ?? '') !== '') {
+    return yield* Effect.fail(
+      new MeshNodeError({
+        message:
+          'Refusing to fetch a Mesh node token while DISTILLED_DEBUG_HTTP is set: the SDK would print the token to stderr. Unset it and run again.',
+      }),
+    );
+  }
+  const credentials = yield* yield* Credentials;
+  if (credentials.type === 'apiKey') {
+    return yield* Effect.fail(
+      new MeshNodeError({
+        message:
+          'Refusing the Global API Key for a Mesh node token. Mint a short-lived API token with "Cloudflare One Connectors Write" and pass it with fromApiToken.',
+      }),
+    );
+  }
+  if (credentials.type === 'apiToken' && Redacted.value(credentials.apiToken).length === 0) {
+    return yield* Effect.fail(
+      new MeshNodeError({
+        message:
+          'The Cloudflare API token is EMPTY. That is a missing or denied secrets grant, not a Cloudflare permission: re-mint the token before changing any grant.',
+      }),
+    );
+  }
+});
+
+const resolveId = (ref: MeshNodeRef) => {
+  if (ref.id !== undefined) return Effect.succeed(ref.id);
+  const name = ref.name;
+  return Effect.flatMap(findNodeByName(ref.accountId, name), (node) =>
+    node === undefined
+      ? Effect.fail(new MeshNodeError({ message: `No live Mesh node named "${name}".` }))
+      : Effect.succeed(node.id),
+  );
+};
+
+/**
+ * ⛔ An EMPTY token fails closed: `warp-cli connector new ""` would not enrol, and a script that
+ *   wrote an empty file would report success over a host that never joined.
+ * ⛔ The failures made here name the node and account and quote no response body, because the
+ *   success body IS the token. Other SDK errors pass through; they come only from non-2xx
+ *   responses, which carry an error envelope, not a token.
+ */
+export const fetchMeshNodeToken = (ref: MeshNodeRef) =>
+  Effect.gen(function* () {
+    yield* refuseUnsafe;
+    const nodeId = yield* resolveId(ref);
+    const token = yield* zeroTrust
+      .getTunnelWarpConnectorToken({ accountId: ref.accountId, tunnelId: nodeId })
+      .pipe(
+        Effect.catchTag('TunnelNotFound', () =>
+          Effect.fail(
+            new MeshNodeError({
+              message: `Mesh node ${nodeId} does not exist in account ${ref.accountId}.`,
+            }),
+          ),
+        ),
+        Effect.catchTag('Forbidden', () =>
+          Effect.fail(
+            new MeshNodeError({
+              message: `Reading Mesh node ${nodeId}'s token was refused (403). The endpoint needs a Write permission such as "Cloudflare One Connectors Write", on a token scoped to account ${ref.accountId}.`,
+            }),
+          ),
+        ),
+      );
+    if (typeof token !== 'string' || token.length === 0) {
+      return yield* Effect.fail(
+        new MeshNodeError({ message: `Mesh node ${nodeId} returned an empty token.` }),
+      );
+    }
+    return Redacted.make(token);
+  });

package/src/cloudflare/mesh-node.test.ts

@@ -0,0 +1,172 @@
+/**
+ * MeshNodeProvider against a fake Cloudflare (fake-mesh.ts), its handlers called the way the
+ * engine calls them.
+ *
+ * ⛔ THE ASSERTION THAT MATTERS MOST: no lifecycle handler ever requests `/token`, and nothing
+ *   the provider returns contains the node token — even though the fake's create response carries
+ *   one, as Cloudflare's HA page says the real one does.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import type { StackServices } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import type * as Layer from 'effect/Layer';
+import { FAKE_ACCOUNT, FAKE_API_TOKEN, fakeMesh } from './fake-mesh.ts';
+import { diff, extra, ids, read, reconcile, run, stored, tokenReads } from './mesh-node-harness.ts';
+import { providers } from './providers.ts';
+
+// ⛔ Compile-time: a stack's `providers` must be `Layer<…, never, StackServices>`. Adding MeshNode
+//   first leaked Alchemy's auth errors into the error channel; `bun run types` now catches that.
+type Built = Layer.Success<ReturnType<typeof providers>>;
+const _stackShaped: Layer.Layer<Built, never, StackServices> = providers();
+void _stackShaped;
+
+describe('MeshNodeProvider', () => {
+  test('create sends ha, and the attributes carry no token', async () => {
+    const fake = fakeMesh();
+    const out = await run(fake, (p) => reconcile(p, { name: 'door-a', ha: true }));
+    const post = fake.seen.find((s) => s.method === 'POST');
+    expect(post?.body).toEqual({ name: 'door-a', ha: true });
+    expect(out).toMatchObject({
+      name: 'door-a',
+      ha: true,
+      accountId: FAKE_ACCOUNT,
+      status: 'inactive',
+    });
+    expect(Object.keys(out).sort()).toEqual(['accountId', 'ha', 'id', 'name', 'status']);
+    expect(JSON.stringify(out)).not.toContain('fake-node-token');
+    expect(tokenReads(fake)).toBe(0);
+    expect(new Set(fake.auth)).toEqual(new Set([`Bearer ${FAKE_API_TOKEN}`]));
+  });
+
+  test('read with state refreshes by id; without state it adopts by exact name, Unowned', async () => {
+    const fake = fakeMesh();
+    fake.seed({ name: 'door-a-old' });
+    fake.seed({ name: 'door-a-older' });
+    const node = fake.seed({ name: 'door-a', status: 'healthy' });
+    const props = { name: 'door-a', ha: false };
+    const [owned, probe] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const output = stored(FAKE_ACCOUNT, { id: node.id });
+        return [yield* read(p, props, output), yield* read(p, props)] as const;
+      }),
+    );
+    expect(Unowned.is(owned)).toBe(false);
+    expect(owned).toMatchObject({ id: node.id, status: 'healthy' });
+    expect(Unowned.is(probe)).toBe(true);
+    expect(probe).toMatchObject({ id: node.id, name: 'door-a', ha: false });
+    expect(tokenReads(fake)).toBe(0);
+  });
+
+  test('a prefix-only match or a deleted node is not adopted', async () => {
+    const fake = fakeMesh();
+    fake.seed({ name: 'door-a-2' });
+    fake.seed({ name: 'door-a', deleted_at: '2026-09-20T00:00:00Z' });
+    const probe = await run(fake, (p) => read(p, { name: 'door-a', ha: false }));
+    expect(probe).toBeUndefined();
+  });
+
+  test('a rename is a PATCH on the same id', async () => {
+    const fake = fakeMesh();
+    const [first, second] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const first = yield* reconcile(p, { name: 'door-a', ha: false });
+        return [first, yield* reconcile(p, { name: 'door-b', ha: false }, first)] as const;
+      }),
+    );
+    expect(second.id).toBe(first.id);
+    expect(second.name).toBe('door-b');
+    expect(fake.seen.filter((s) => s.method === 'POST')).toHaveLength(1);
+    expect(fake.seen.find((s) => s.method === 'PATCH')?.body).toEqual({ name: 'door-b' });
+  });
+
+  test('an unchanged node costs no write', async () => {
+    const fake = fakeMesh();
+    await run(fake, (p) =>
+      Effect.flatMap(reconcile(p, { name: 'door-a', ha: false }), (out) =>
+        reconcile(p, { name: 'door-a', ha: false }, out),
+      ),
+    );
+    expect(fake.seen.filter((s) => s.method !== 'GET').map((s) => s.method)).toEqual(['POST']);
+  });
+
+  test('reconcile refuses an ha change that reached it as an update', async () => {
+    const fake = fakeMesh();
+    const failure = await run(fake, (p) =>
+      Effect.flip(
+        Effect.flatMap(reconcile(p, { name: 'door-a', ha: false }), (out) =>
+          reconcile(p, { name: 'door-a', ha: true }, out),
+        ),
+      ),
+    );
+    expect(String(failure)).toContain('create-only');
+  });
+
+  test('create never converges on a node it did not create (a retained old generation)', async () => {
+    const fake = fakeMesh();
+    fake.seed({ name: 'door-a', ha: false });
+    const failure = await run(fake, (p) => Effect.flip(reconcile(p, { name: 'door-a', ha: true })));
+    expect(String(failure)).toContain('already exists');
+    expect(fake.seen.some((s) => s.method === 'POST')).toBe(false);
+  });
+
+  test('a node deleted out of band is created again', async () => {
+    const fake = fakeMesh();
+    const [first, second] = await run(fake, (p) =>
+      Effect.gen(function* () {
+        const first = yield* reconcile(p, { name: 'door-a', ha: false });
+        const node = fake.nodes.get(first.id);
+        if (node !== undefined) node.deleted_at = '2026-09-21T02:00:00Z';
+        return [first, yield* reconcile(p, { name: 'door-a', ha: false }, first)] as const;
+      }),
+    );
+    expect(second.id).not.toBe(first.id);
+    expect(fake.live()).toHaveLength(1);
+  });
+
+  test('delete removes the node, and deleting it again succeeds', async () => {
+    const fake = fakeMesh();
+    await run(fake, (p) =>
+      Effect.gen(function* () {
+        const output = yield* reconcile(p, { name: 'door-a', ha: false });
+        const olds = { name: 'door-a', ha: false };
+        yield* p.delete({ ...ids, ...extra, olds, output });
+        yield* p.delete({ ...ids, ...extra, olds, output });
+      }),
+    );
+    expect(fake.live()).toHaveLength(0);
+    expect(fake.seen.filter((s) => s.method === 'DELETE')).toHaveLength(2);
+  });
+
+  test('diff reads the account from the provider environment', async () => {
+    const fake = fakeMesh();
+    const props = { name: 'door-a', ha: false };
+    const plan = (p: Parameters<typeof diff>[0]) => diff(p, props, props, stored(FAKE_ACCOUNT));
+    expect(await run(fake, plan)).toBeUndefined();
+    expect(await run(fake, plan, '00000000000000000000000000000002')).toEqual({
+      action: 'replace',
+    });
+  });
+
+  test('an invalid declaration fails the PLAN, before a delete-first replace tears anything down', async () => {
+    const fake = fakeMesh();
+    const failure = await run(fake, (p) =>
+      Effect.flip(
+        diff(p, { name: 'door-a ', ha: true }, { name: 'door-a', ha: false }, stored(FAKE_ACCOUNT)),
+      ),
+    );
+    expect(String(failure)).toContain('whitespace');
+    expect(fake.seen).toHaveLength(0);
+  });
+
+  test('list is empty and nuke skips it: Alchemy WarpConnector already enumerates these', async () => {
+    const fake = fakeMesh();
+    fake.seed({ name: 'door-a' });
+    const [listed, nuke] = await run(fake, (p) =>
+      Effect.map(p.list(), (rows) => [rows, p.nuke] as const),
+    );
+    expect(listed).toEqual([]);
+    expect(nuke).toEqual({ skip: true });
+    expect(fake.seen).toHaveLength(0);
+  });
+});

package/src/cloudflare/mesh-node.ts

@@ -0,0 +1,120 @@
+/**
+ * `Cloudflare.MeshNode` — a Cloudflare Mesh node (a `warp_connector` object), declared without
+ * its token ever touching Alchemy state. Usage and the enrolment step: docs/mesh-node.md.
+ *
+ * 🔴 WHY THIS EXISTS ALONGSIDE `Cloudflare.Tunnel.WarpConnector`. A Mesh node that fronts a
+ *   private service needs a node record in the graph, so the Gateway rules and DNS records that
+ *   name it deploy together. Alchemy beta.79's WarpConnector would put the node token — the
+ *   credential that lets any Linux host join the account's Mesh as that node — into plaintext
+ *   state on every read, and it cannot create an HA node. See mesh-node-form.ts.
+ *
+ * ★ REMOVAL POLICY: `retain` BY DEFAULT — see the ★ on `MeshNode` below, and what it does to an
+ *   `ha` replace in mesh-node-lifecycle.ts.
+ */
+import { Credentials } from '@distilled.cloud/cloudflare/Credentials';
+import * as Cloudflare from 'alchemy/Cloudflare';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import { Resource, type ResourceClass } from 'alchemy/Resource';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import {
+  type MeshNodeAttributes,
+  type MeshNodeProps,
+  diffMeshNode,
+  validateMeshNode,
+} from './mesh-node-form.ts';
+import { deleteMeshNode, readMeshNode, reconcileMeshNode } from './mesh-node-lifecycle.ts';
+import type { Providers } from './providers.ts';
+
+export interface MeshNode extends Resource<
+  'Cloudflare.MeshNode',
+  MeshNodeProps,
+  MeshNodeAttributes,
+  never,
+  Providers
+> {}
+
+/**
+ * ★ `defaultRemovalPolicy: 'retain'`, LIKE EVERY KIT RESOURCE WHOSE DELETION BREAKS ITS CONSUMERS
+ *   (the `Bao.*` families, `R2BucketLock`, the Proxmox storage families; the reasoning is written
+ *   once in proxmox/resource.ts). Deleting a node cuts every enrolled replica off the Mesh, and
+ *   nothing brings it back: a new node has a new id, a new token and a new Mesh IP per replica, so
+ *   each host must be re-enrolled by hand and every Gateway rule or allow-list that pins the old
+ *   Mesh IP breaks. So dropping the declaration, or `alchemy destroy`, leaves the node live.
+ * ⚠️ IT ALSO SKIPS THE OLD NODE'S DELETE IN A REPLACE (Apply.ts, `deleteOldGenerations` and the
+ *   GC's `retainOldGeneration`, beta.79). A same-name `ha` change therefore REFUSES, deleting
+ *   nothing, until that deploy opts in with `.pipe(RemovalPolicy.destroy())`; a create-first
+ *   replace leaves the old node live and unmanaged. Both measured in mesh-node-policy.test.ts.
+ * ⛔ `delete` STAYS FULLY IMPLEMENTED. Retain is Terraform's `prevent_destroy`, not a stub: it runs
+ *   the moment a declaration opts in with `.pipe(RemovalPolicy.destroy())`.
+ */
+export const MeshNode: ResourceClass<MeshNode> = Resource<MeshNode>('Cloudflare.MeshNode', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** What every call below needs: the account, credentials and HTTP — Alchemy's own trio. */
+export type MeshNodeServices =
+  | Cloudflare.CloudflareEnvironment
+  | Credentials
+  | HttpClient.HttpClient;
+
+/** The account id, resolved the way every `alchemy/Cloudflare` provider resolves it. */
+const accountId = Effect.gen(function* () {
+  const resolved = yield* yield* Cloudflare.CloudflareEnvironment;
+  return resolved.accountId;
+});
+
+/**
+ * ★ `Provider.effect`, CAPTURING THE THREE SERVICES AT BUILD. `Provider.succeed` (what Alchemy's
+ *   own providers use) leaves each handler to find CloudflareEnvironment and Credentials in the
+ *   engine's context at call time — which works for `Cloudflare.providers()` only because it
+ *   `provideMerge`s them into the stack. Capturing them here keeps this provider correct whether
+ *   or not the stack also merges `Cloudflare.providers()`.
+ */
+export const MeshNodeProvider = () =>
+  Provider.effect(
+    MeshNode,
+    Effect.gen(function* () {
+      const services = Context.make(
+        Cloudflare.CloudflareEnvironment,
+        yield* Cloudflare.CloudflareEnvironment,
+      ).pipe(
+        Context.add(Credentials, yield* Credentials),
+        Context.add(HttpClient.HttpClient, yield* HttpClient.HttpClient),
+      );
+      const run = <A, E>(effect: Effect.Effect<A, E, MeshNodeServices>) =>
+        Effect.provideContext(effect, services);
+
+      return MeshNode.Provider.of({
+        stables: ['id', 'accountId', 'ha'],
+        /**
+         * ⛔ EMPTY, AND `nuke.skip`. Alchemy's own `Cloudflare.Tunnel.WarpConnector` already lists
+         *   every `warp_connector` in the account for `alchemy unsafe nuke`; a second listing here
+         *   would make nuke delete each node twice. `read` does not depend on this.
+         */
+        list: () => Effect.succeed([]),
+        nuke: { skip: true },
+        /**
+         * ⛔ VALIDATE AT PLAN TIME, NOT ONLY IN `reconcile`. An `ha` replace is delete-first: the
+         *   engine deletes the old node BEFORE the new generation's reconcile runs, so a
+         *   declaration refused there would leave no node at all. launchd's job-preflight.ts
+         *   refuses at plan time for the same reason.
+         */
+        diff: ({ news, output }) =>
+          run(
+            Effect.gen(function* () {
+              const invalid = isResolved(news) ? validateMeshNode(news) : undefined;
+              if (invalid !== undefined) return yield* Effect.fail(invalid);
+              return diffMeshNode(news, output, yield* accountId);
+            }),
+          ),
+        read: ({ olds, output }) =>
+          run(Effect.flatMap(accountId, (account) => readMeshNode(account, olds, output))),
+        reconcile: ({ news, output }) =>
+          run(Effect.flatMap(accountId, (account) => reconcileMeshNode(account, news, output))),
+        delete: ({ output }) => run(deleteMeshNode(output)),
+      });
+    }),
+  );

package/src/cloudflare/providers.ts

@@ -8,16 +8,34 @@
  *   both a `Cloudflare.R2.Bucket` and this lock merges the two:
  *   `Layer.mergeAll(Cloudflare.providers(), HomeflareCloudflare.providers())` — the shape
  *   a consuming stack names for one talking to more than one account.
+ *
+ * ★ TWO CREDENTIAL PATHS, ONE PER SDK. `R2BucketLock` uses the `cloudflare` SDK through
+ *   `CloudflareApiLive` (`CLOUDFLARE_API_TOKEN`, fail-closed). `MeshNode` uses Alchemy's own SDK
+ *   and resolves credentials and the account through `Cloudflare.CloudflareApiLive()` — the same
+ *   source `Cloudflare.providers()` uses (an Alchemy profile, or `CLOUDFLARE_API_TOKEN` +
+ *   `CLOUDFLARE_ACCOUNT_ID` in CI), so a node lands in the account its Gateway rules do.
+ * ⚠️ That second layer is built again here even when the stack also merges
+ *   `Cloudflare.providers()`. `Layer.provide`, not `provideMerge`: it feeds MeshNode only and adds
+ *   nothing to the stack's context.
  */
+import * as Cloudflare from 'alchemy/Cloudflare';
 import * as Provider from 'alchemy/Provider';
 import * as Layer from 'effect/Layer';
 import { CloudflareApiLive } from './client.ts';
+import { MeshNode, MeshNodeProvider } from './mesh-node.ts';
 import { R2BucketLock, R2BucketLockProvider } from './r2-bucket-lock.ts';
 
 export class Providers extends Provider.ProviderCollection<Providers>()('HomeflareCloudflare') {}
 
 export const providers = () =>
-  Layer.effect(Providers, Provider.collection([R2BucketLock])).pipe(
-    Layer.provide(R2BucketLockProvider()),
+  Layer.effect(Providers, Provider.collection([R2BucketLock, MeshNode])).pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        R2BucketLockProvider(),
+        // ⛔ `orDie`, as `Cloudflare.providers()` ends with: a stack's providers layer must not
+        //   fail, and a profile that cannot resolve is a defect carrying Alchemy's own sentence.
+        MeshNodeProvider().pipe(Layer.provide(Cloudflare.CloudflareApiLive()), Layer.orDie),
+      ),
+    ),
     Layer.provideMerge(CloudflareApiLive),
   );

package/src/index.ts

@@ -9,6 +9,8 @@
  *     import { BaoMount } from '@homeflare/alchemy/openbao';
  *     import { TalosCluster } from '@homeflare/alchemy/talos';
  *     import { ProxmoxAcl } from '@homeflare/alchemy/proxmox';
+ *     import { LaunchdJob } from '@homeflare/alchemy/launchd';
+ *     import { CaddyConfig } from '@homeflare/alchemy/caddy';
  *
  * ★ WHY THESE EXIST AT ALL. When Alchemy has no resource for something, the alternative
  *   is a runbook step a human runs once — and a plan can never show a missing runbook

package/src/launchd/fake-runner.ts

@@ -0,0 +1,176 @@
+/**
+ * An in-memory host for the tests beside it: a filesystem in a Map and a scripted launchd.
+ *
+ * ⛔ TEST-ONLY. No provider imports this file, it is not on the barrel, and it never touches the
+ *   real filesystem or runs a real program — which is the only way the lifecycle tests can prove
+ *   "bootout before bootstrap" without writing /Library or loading a job.
+ * ★ IT MODELS THE BEHAVIOURS THE PROVIDER DEPENDS ON, as launchctl.ts documents them: `print` of an
+ *   unknown target exits 113; bootstrap of a loaded or disabled label fails; bootout of an absent
+ *   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.
+ */
+import { LAUNCHCTL, NOT_FOUND, NO_DOMAIN } from './launchctl.ts';
+import type { ExecResult, FileStat, HostRunner, HostUser, WriteOptions } from './runner.ts';
+
+type Entry = { bytes: Uint8Array; mode: number; uid: number; gid: number; kind: FileStat['kind'] };
+
+export type FakeOptions = {
+  euid?: number;
+  privileged?: boolean;
+  /** Directories that exist, and their owner uid. */
+  dirs?: Record<string, number>;
+  users?: Record<string, HostUser>;
+  groups?: Record<string, number>;
+};
+
+const ok = (stdout = ''): ExecResult => ({ exitCode: 0, stderr: '', stdout });
+const fail = (exitCode: number, stderr: string): ExecResult => ({ exitCode, stderr, stdout: '' });
+const errno = (code: string, path: string) =>
+  Object.assign(new Error(`${code}: ${path}`), { code });
+const parent = (path: string) => path.slice(0, path.lastIndexOf('/')) || '/';
+
+/** The shape `launchctl print` produced on macOS 27.2 (see launchctl.ts), trimmed. */
+const printBlock = (target: string, pid: number | undefined, lastExit: string) =>
+  [
+    `${target} = {`,
+    '\tactive count = 1',
+    `\tstate = ${pid === undefined ? 'not running' : 'running'}`,
+    '\targuments = {',
+    '\t\t/bin/sh',
+    '}',
+    '\t}',
+    '\tresource coalition = {',
+    '\t\tstate = active',
+    '\t}',
+    ...(pid === undefined ? [] : [`\tpid = ${String(pid)}`]),
+    `\tlast exit code = ${lastExit}`,
+    '}',
+  ].join('\n');
+
+export const fakeRunner = (options: FakeOptions = {}) => {
+  const euid = options.euid ?? 501;
+  const privileged = options.privileged ?? false;
+  const root = privileged || euid === 0;
+  const dirs = new Map(Object.entries(options.dirs ?? {}));
+  const files = new Map<string, Entry>();
+  const calls: string[][] = [];
+  /** target → pid (undefined = loaded, not running). */
+  const loaded = new Map<string, number | undefined>();
+  const disabled = new Set<string>();
+  const state = {
+    lingerPrints: 0,
+    nextPid: 4000,
+    bootstrapFailure: undefined as ExecResult | undefined,
+    /** Returned by bootout in place of success. The job still goes, unless `bootoutKeepsJob`. */
+    bootoutFailure: undefined as ExecResult | undefined,
+    bootoutKeepsJob: false,
+    /** gui uids with no login session: every launchctl call into `gui/<uid>` exits 112. */
+    loggedOut: new Set<number>(),
+  };
+  /** Booted-out targets launchd has not let go of yet → prints left before they vanish. */
+  const lingering = new Map<string, number>();
+
+  const labelIn = (path: string) =>
+    /<key>Label<\/key>\s*<string>([^<]*)<\/string>/.exec(
+      new TextDecoder().decode(files.get(path)?.bytes),
+    )?.[1];
+
+  const launchctl = (args: readonly string[]): ExecResult => {
+    const [sub, first, second] = args;
+    const gui = /^gui\/(\d+)(?:\/|$)/.exec(first ?? '')?.[1];
+    if (gui !== undefined && state.loggedOut.has(Number(gui))) {
+      // The measured shape (launchctl.ts): 112, "Bad request." then the domain line.
+      return fail(NO_DOMAIN, `Bad request.\nCould not find domain for user gui: ${gui}`);
+    }
+    if (sub === 'print' && first !== undefined) {
+      const left = lingering.get(first);
+      if (left !== undefined) {
+        if (left <= 0) {
+          lingering.delete(first);
+          loaded.delete(first);
+        } else lingering.set(first, left - 1);
+      }
+      if (!loaded.has(first)) return fail(NOT_FOUND, `Could not find service "${first}"`);
+      return ok(printBlock(first, loaded.get(first), '(never exited)'));
+    }
+    if (sub === 'print-disabled' && first !== undefined) {
+      const lines = [...disabled]
+        .filter((target) => target.startsWith(`${first}/`))
+        .map((target) => `\t\t"${target.slice(first.length + 1)}" => disabled`);
+      return ok(['\tdisabled services = {', ...lines, '\t}'].join('\n'));
+    }
+    if (sub === 'bootstrap' && first !== undefined && second !== undefined) {
+      if (state.bootstrapFailure !== undefined) return state.bootstrapFailure;
+      const label = labelIn(second);
+      if (label === undefined) return fail(5, 'Bootstrap failed: 5: Input/output error');
+      const target = `${first}/${label}`;
+      if (loaded.has(target) || disabled.has(target))
+        return fail(5, 'Bootstrap failed: 5: Input/output error');
+      state.nextPid += 1;
+      loaded.set(target, state.nextPid);
+      return ok();
+    }
+    if (sub === 'bootout' && first !== undefined) {
+      if (!loaded.has(first) || lingering.has(first))
+        return fail(3, 'Boot-out failed: 3: No such process');
+      if (state.bootoutKeepsJob) return state.bootoutFailure ?? fail(5, 'Boot-out failed: 5');
+      // ⚠️ Model launchd letting go late: the job stays visible for `lingerPrints` more prints.
+      if (state.lingerPrints === 0) loaded.delete(first);
+      else lingering.set(first, state.lingerPrints);
+      return state.bootoutFailure ?? ok();
+    }
+    return fail(64, `fake launchctl: unsupported ${args.join(' ')}`);
+  };
+
+  const runner: HostRunner = {
+    effectiveUid: () => euid,
+    exec: async (argv) => {
+      calls.push([...argv]);
+      if (argv[0] === LAUNCHCTL) return launchctl(argv.slice(1));
+      return fail(127, `fake: no program ${String(argv[0])}`);
+    },
+    lookupGroup: async (nameOrId) => options.groups?.[nameOrId],
+    lookupUser: async (nameOrId) =>
+      options.users?.[nameOrId] ??
+      Object.values(options.users ?? {}).find((user) => String(user.uid) === nameOrId),
+    privileged,
+    readFile: async (path) => files.get(path)?.bytes,
+    removeFile: async (path) => {
+      if (files.has(path) && (dirs.get(parent(path)) ?? 0) !== euid && !root)
+        throw errno('EACCES', path);
+      files.delete(path);
+    },
+    // ★ No real waiting: a lingering job drains one `print` per poll instead.
+    sleep: async () => undefined,
+    stat: async (path) => {
+      const entry = files.get(path);
+      if (entry !== undefined)
+        return {
+          gid: entry.gid,
+          kind: entry.kind,
+          mode: entry.mode,
+          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;
+    },
+    writeFileAtomic: async (path: string, bytes: Uint8Array, write: WriteOptions) => {
+      calls.push(['write', path]);
+      const owner = dirs.get(parent(path));
+      if (owner === undefined) throw errno('ENOENT', parent(path));
+      if (owner !== euid && !root) throw errno('EACCES', path);
+      if (write.uid !== undefined && write.uid !== euid && !root) throw errno('EPERM', path);
+      files.set(path, {
+        bytes,
+        gid: write.gid ?? 20,
+        kind: 'file',
+        mode: write.mode,
+        uid: write.uid ?? euid,
+      });
+    },
+  };
+  return { calls, disabled, dirs, files, loaded, runner, state };
+};

package/src/launchd/host-effect.ts

@@ -0,0 +1,28 @@
+/**
+ * The one place a HostRunner's promises become Effects — plus the one probe of an unresolved
+ * `news` both providers' diffs share.
+ *
+ * ★ 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 * as Effect from 'effect/Effect';
+
+export const lift = <A>(step: () => Promise<A>): Effect.Effect<A, Error> =>
+  Effect.tryPromise({
+    catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
+    try: step,
+  });
+
+/**
+ * A string prop of a diff's `news`, when that one prop is already resolved; `undefined` while it
+ * is still an Output (a function-typed proxy), an Effect or a Config.
+ * ★ For the identity props a diff must see even when the rest of `news` is unresolved — a plain
+ *   string is resolved by definition, so `typeof` is the whole test.
+ */
+export const resolvedString = (news: unknown, key: string): string | undefined => {
+  if (typeof news !== 'object' || news === null) return undefined;
+  const value = (news as Record<string, unknown>)[key];
+  return typeof value === 'string' ? value : undefined;
+};