@homeflare/alchemy 0.31.2 → 0.33.0

package/src/proxmox/zfs-pool-read-failure.test.ts

@@ -0,0 +1,118 @@
+/**
+ * `Proxmox.ZfsPool`'s own cries-wolf fix, PLUS the request-shape and transient-failure fixes
+ * kit 0.31.2/0.31.3 (PR 239/243) found for User/Group/Storage — all apply here too, this time on
+ * a `read`-role read (this family never needed `provision` for GETs). Real-shaped fixtures (live
+ * TB4 `n2` response bodies, measured 2026-09-24, nothing secret): `GET /nodes/n2/disks/zfs/rpool`
+ * -> `{"data":{"name":"rpool","state":"ONLINE","errors":"No known data errors","children":[...]}}`,
+ * and a missing pool -> a generic shelled-out `zpool status` failure at HTTP 500, the same class
+ * of measured 500 as every other family this package has migrated.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { engineOver } from '../verify/fake-engine.ts';
+import { FAKE_TARGET, withoutBao } from './fake-pve.ts';
+import { ProxmoxZfsPool, ProxmoxZfsPoolProvider } from './zfs-pool.ts';
+
+/**
+ * One pool, an OpenBao mint the test can deny for `read` mid-run (the cries-wolf case), and a
+ * cluster answer the test can break into a transient 500 mid-run (the request-shape regression's
+ * own case) — never both at once, so one fixture serves every test below.
+ */
+const clusterOverPool = (node: string, name: string, live: Record<string, unknown>) => {
+  let denyRead = false;
+  let transient = false;
+  const stub = async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    if (url.pathname.includes('/creds/')) {
+      if (denyRead && url.pathname.endsWith('/creds/read')) {
+        return Response.json({ errors: ['permission denied'] }, { status: 403 });
+      }
+      const data = { secret: 'fake-secret-not-real', token_id: 'hf-test@pve!fake' };
+      return Response.json({ data, lease_duration: 0 });
+    }
+    if (request.method === 'GET') {
+      // ⛔ THE REQUEST-SHAPE REGRESSION'S OWN SIGNATURE (user.ts/group.ts/storage.ts): a real
+      //   fetch client refuses a GET carrying a body outright.
+      expect(await request.text()).toBe('');
+    }
+    const wire = decodeURIComponent(url.pathname.replace(/^\/api2\/json\//, ''));
+    if (wire !== `nodes/${node}/disks/zfs/${name}`) return Response.json({ data: null });
+    if (transient) {
+      // MEASURED 2026-09-24, live TB4: a missing pool answers exactly this shape.
+      return Response.json(
+        { data: null, message: `command '/sbin/zpool status -P ${name}' failed: exit code 1\n` },
+        { status: 500 },
+      );
+    }
+    return Response.json({ data: live });
+  };
+  const fetchStub = Object.assign(stub, { preconnect: globalThis.fetch.preconnect });
+  return {
+    breakReads: () => {
+      transient = true;
+    },
+    denyRead: () => {
+      denyRead = true;
+    },
+    layer: FetchHttpClient.layer.pipe(
+      Layer.provideMerge(Layer.succeed(FetchHttpClient.Fetch, fetchStub as typeof fetch)),
+    ),
+  };
+};
+
+// MEASURED 2026-09-24, live TB4 `GET /nodes/n2/disks/zfs/rpool`.
+const live = {
+  children: [
+    { children: [{ name: 'nvme-part3', state: 'ONLINE' }], name: 'rpool', state: 'ONLINE' },
+  ],
+  errors: 'No known data errors',
+  name: 'rpool',
+  state: 'ONLINE',
+};
+// ⚠️ ADOPT-ONLY (no `devices`/`raidlevel`, decision 9) — the pool is not one this test creates.
+const declare = () =>
+  ProxmoxZfsPool('n2-rpool', { name: 'rpool', node: 'n2', target: FAKE_TARGET });
+
+describe("Proxmox.ZfsPool's own cries-wolf fix: a refused read mint reports noop, never update", () => {
+  test('an already-adopted pool plans noop once the credential is denied, and nothing is written', async () => {
+    const fake = clusterOverPool('n2', 'rpool', live);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxZfsPoolProvider().pipe(Layer.provideMerge(fake.layer)));
+      expect(await engine.deploy(declare())).toEqual({ 'n2-rpool': 'adopted' });
+      fake.denyRead();
+      const report = await engine.verify(declare(), { all: true });
+      // ⛔ THE BUG THIS PROVES FIXED — same class as storage.ts's, measured for that family
+      //   2026-09-24: before the dual-path fix this row read `update` with nothing compared.
+      expect(report.rows[0]).toMatchObject({ diff: 'noop' });
+      expect(await engine.deploy(declare())).toEqual({ 'n2-rpool': 'noop' });
+    });
+  });
+});
+
+describe('the same request-shape and transient-failure fixes, once for Proxmox.ZfsPool', () => {
+  test('diff() propagates a transient read failure once a state row exists', async () => {
+    const fake = clusterOverPool('n2', 'rpool', live);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxZfsPoolProvider().pipe(Layer.provideMerge(fake.layer)));
+      expect(await engine.deploy(declare())).toEqual({ 'n2-rpool': 'adopted' });
+      fake.breakReads();
+      // ⛔ THE FIX: this must REJECT, never resolve with a false 'update'.
+      await expect(engine.verify(declare(), { all: true })).rejects.toBeDefined();
+    });
+  });
+
+  test('alchemy drift never reports a transient failure as missing', async () => {
+    const fake = clusterOverPool('n2', 'rpool', live);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxZfsPoolProvider().pipe(Layer.provideMerge(fake.layer)));
+      expect(await engine.deploy(declare())).toEqual({ 'n2-rpool': 'adopted' });
+      fake.breakReads();
+      // ⛔ THE FIX: this must REJECT. Without `read`'s `output` branch it resolved with
+      //   `{ 'n2-rpool': { action: 'missing' } }` and no error anywhere.
+      await expect(engine.drift(declare())).rejects.toBeDefined();
+    });
+  });
+});

package/src/proxmox/zfs-pool-wire.ts

@@ -0,0 +1,132 @@
+/**
+ * `Proxmox.ZfsPool`'s READ side: the live-to-attributes shape, the read itself, and `matches`.
+ * Split out of zfs-pool.ts (2026-09-24, the distilled migration) — the storage.ts/storage-wire.ts
+ * seam; the write side is zfs-pool-form.ts.
+ */
+import * as nodes from '@distilled.cloud/proxmox/nodes';
+import * as Effect from 'effect/Effect';
+import { runPve } from './distilled-pve.ts';
+import type { ZfsPoolProps } from './zfs-pool.ts';
+import { UNREADABLE, type Unreadable, readOrUnreadable } from './unreadable-read.ts';
+import { text } from './values.ts';
+
+/**
+ * ⚠️ EVERYTHING HERE IS REPORTED, NOTHING HERE IS COMPARED — see the ⛔ on `matches` below. These
+ *   exist so a plan and the state store can say what the pool actually is, on a family where the
+ *   declaration and the live object share no comparable field at all.
+ */
+export interface ZfsPoolAttributes {
+  /** ★ The value a `Proxmox.Storage` should read to order itself after this pool. */
+  name: string;
+  node: string;
+  /** `ONLINE` | `DEGRADED` | `FAULTED` | … Health, not configuration. */
+  state: string;
+  /** ZFS's own error summary, e.g. `No known data errors`. */
+  errors: string;
+  /**
+   * The leaf devices ZFS reports, in vdev order, comma-joined.
+   *
+   * ⚠️ THIS IS WHAT ZFS RESOLVED, NOT WHAT WAS DECLARED, and the two normally differ: PVE rewrites
+   *   a `/dev/sdb` into a by-id link before creating, and ZFS reports partition paths (`…-part3`)
+   *   for a pool built on partitions — MEASURED, that is exactly what node-b's `rpool` reports.
+   *   Never compare it with `props.devices`.
+   */
+  devices: string;
+}
+
+/**
+ * The device paths at the bottom of PVE's vdev tree, in the order ZFS reports them.
+ *
+ * ⚠️ "NO CHILDREN" IS THE LEAF TEST, AND IT IS NOT A GUESS — MEASURED in the node's `preparetree`,
+ *   which sets `leaf` to 0 when there are children and 1 otherwise. Reading the flag would work
+ *   equally well; recursing on `children` needs no second field to be present and is what makes
+ *   nested sections (mirrors inside a raid10, `spares`, `cache`) flatten correctly.
+ */
+export const leafDevices = (children: unknown): string[] =>
+  Array.isArray(children)
+    ? children.flatMap((entry: unknown) => {
+        const vdev = entry as { children?: unknown; name?: unknown };
+        const nested = leafDevices(vdev.children);
+        return nested.length > 0 ? nested : [text(vdev.name)].filter((name) => name !== '');
+      })
+    : [];
+
+/**
+ * ⚠️ `scan`, `status` AND `action` ARE DELIBERATELY NOT ATTRIBUTES. All three are advisory strings
+ *   ZFS rewrites on its own — `scan` on every scrub, the other two as feature flags and faults come
+ *   and go — so keeping them would rewrite this resource's state row for reasons no declaration
+ *   caused. Same reasoning as `digest` in storage.ts.
+ */
+const attributesOf = (
+  live: nodes.GetNodeDiskZfsResponse,
+  props: ZfsPoolProps,
+): ZfsPoolAttributes => ({
+  devices: leafDevices(live.children).join(','),
+  errors: text(live.errors, 'unknown'),
+  name: props.name,
+  node: props.node,
+  state: text(live.state, 'unknown'),
+});
+
+/**
+ * ★ Default `read` role — `Sys.Audit` on `/` is all this GET checks (zfs-pool.ts's header).
+ * ⛔ `{ node: props.node, name: props.name }`, NEVER THE WHOLE `props` — storage.ts's/user.ts's own
+ *   ⛔, the kit 0.31.1 regression: `GetNodeDiskZfsRequest`'s schema declares only `node` and `name`
+ *   (both path labels); any OTHER key on the object passed to `nodes.getNodeDiskZfs` is treated by
+ *   distilled's `buildRequest` as an "unknown key" and JSON-encoded onto this bodyless GET, which a
+ *   stricter fetch client refuses outright.
+ * ⛔ A MISSING POOL IS A 500, NOT A 404 — MEASURED against the live cluster (TB4 n2, 2026-09-24,
+ *   read-role, read-only probe): `GET /nodes/n2/disks/zfs/hf-measure-nonexistent-pool` answers
+ *   `{"message":"command '/sbin/zpool status -P hf-measure-nonexistent-pool' failed: exit code
+ *   1\n","data":null}` at HTTP 500 — PVE shells out to `zpool status` and reports its exit code
+ *   as a generic command failure, not a typed "not found". The same shape as user.ts's/group.ts's/
+ *   storage.ts's own measured 500s. `readPool` below (used by `createPool`'s settle-poll and by
+ *   `reconcile`/`read`) still folds it, exactly as `readUser`/`readGroup`/`readStorage` do — the
+ *   whole reason `createPool` can tell "not built yet" from "forbidden" only by giving up after
+ *   `SETTLE_ATTEMPTS` (zfs-pool-form.ts's own ⚠️ on that); `readPoolOrFail` (used by `diff`) does
+ *   not fold it, so a genuine transient failure there propagates and fails the plan loudly instead.
+ */
+export const readPoolOrFail = (props: ZfsPoolProps) =>
+  readOrUnreadable(
+    runPve(
+      props.target,
+      'read',
+      false,
+      nodes.getNodeDiskZfs({ name: props.name, node: props.node }),
+    ),
+  ).pipe(
+    Effect.map((live) => {
+      if (live === UNREADABLE) return UNREADABLE;
+      // ⚠️ A detail answer with no `name` is not a pool — same shape check zfs-pool-spec.ts made,
+      //   kept as a defensive fallback now that the 500 above is the measured absence signal.
+      return text(live.name) === '' ? undefined : attributesOf(live, props);
+    }),
+  );
+
+/**
+ * ⛔ FOLDS A GENUINE READ FAILURE TO `undefined` TOO, AND ONLY `createPool`'s settle-poll AND
+ *   `read`/`reconcile` MAY USE IT — user.ts's `readUser` has the full reasoning. Safe here because
+ *   a wrongful fold during create costs at most a redundant `createNodeDiskZfs` POST, which PVE
+ *   refuses loudly ("pool already exists") rather than silently corrupting anything — zfs-pool.ts's
+ *   own header, measured.
+ * ⛔ `zfs-pool.ts`'s `diff` does **NOT** use this — the same bug class as the credential denial fix:
+ *   folding a TRANSIENT failure into "absent" at PLAN TIME would force a false `update` with
+ *   nothing compared. `diff` calls `readPoolOrFail` directly, so a genuine failure there propagates
+ *   and fails the whole plan loudly instead.
+ */
+export const readPool = (props: ZfsPoolProps) =>
+  readPoolOrFail(props).pipe(Effect.orElseSucceed(() => undefined));
+
+/** `read`/`reconcile`/`createPool` return `Attributes | undefined`; only `diff` sees `UNREADABLE`. */
+export const dropUnreadable = (live: ZfsPoolAttributes | Unreadable | undefined) =>
+  live === UNREADABLE ? undefined : live;
+
+/**
+ * ⛔ THERE IS NO `matches` FUNCTION HERE — UNLIKE EVERY OTHER MIGRATED FAMILY, AND DELIBERATELY.
+ *   Every create parameter on this family is write-only (this file's own `attributesOf`), so
+ *   there is nothing a declaration and a live pool can ever be compared on — a `matches` that
+ *   invented one would plan a replace (`zpool destroy`, since this family has no PUT) over a
+ *   difference it could never verify. `zfs-pool.ts`'s `diff` returns `noop` unconditionally once a
+ *   pool is found, rather than calling a function that would only ever return `true` — found by
+ *   adversarial review that an earlier draft exported one here anyway, unused by anything.
+ */

package/src/proxmox/zfs-pool.ts

@@ -26,14 +26,14 @@
  * ⛔ THERE IS NO PUT ON THIS FAMILY AT ALL. MEASURED from the cluster's own published schema
  *   (`/usr/share/pve-docs/api-viewer/apidoc.js`, read on node-b 2026-09-13): `/nodes/{node}/disks/zfs`
  *   has GET and POST, `/nodes/{node}/disks/zfs/{name}` has GET and DELETE, and that is the whole
- *   surface. So `updateForm` is omitted — which, per `resource.ts`, makes any `matches` = false a
- *   REPLACE. A replace is a delete followed by a create, and on this family the delete is the
- *   thing above. Read the ⛔ on `matches` before adding anything to it.
+ *   surface — CONFIRMED again in `@distilled.cloud/proxmox`'s generated `nodes.ts`, which declares
+ *   no `putNodeDiskZfs` at all. So `matches` (zfs-pool-wire.ts) always answers `true`: there is
+ *   nothing to plan a replace over, and the family's one write is the create below.
  *
  * ⛔ NOT ONE CREATE PARAMETER COMES BACK ON READ, SO `matches` COMPARES NOTHING. MEASURED against
- *   the live cluster: `GET /nodes/node-b/disks/zfs/rpool` answers exactly
- *   `{action, children, errors, leaf, name, scan, state, status}` — no `ashift`, no `compression`,
- *   no `raidlevel`, no `devices`, no `add_storage`. Every create parameter is write-only. There is
+ *   the live cluster: `GET /nodes/n2/disks/zfs/rpool` answers exactly
+ *   `{action?, children, errors, name, scan?, state, status?}` — no `ashift`, no `compression`, no
+ *   `raidlevel`, no `devices`, no `add_storage`. Every create parameter is write-only. There is
  *   therefore no field a declaration and a live pool can both be asked about, and a `matches` that
  *   invented one would plan a replace — i.e. a `zpool destroy` — over a difference it could never
  *   verify in the first place.
@@ -46,11 +46,20 @@
  *   is compared, and the three churning strings are kept out of the state store entirely rather
  *   than rewriting this resource's row every time somebody writes a file.
  *
- * ⚠️ TWO HANDLERS ARE OVERRIDDEN AND THE OTHER THREE COME FROM THE FACTORY — see the ★ above
- *   `handlers`. `delete` is the ⛔ above. `reconcile` is because the create is a FORKED WORKER, so
- *   the factory's immediate read-back would report a successful create as a failure; the measured
- *   detail, and the adopt-only refusal decision 9 adds, are both in `createPool` in
- *   zfs-pool-write.ts.
+ * ⛔ A MISSING POOL IS A 500, NOT A 404 — MEASURED against the live cluster (TB4 n2, 2026-09-24,
+ *   read-role, read-only probe): `GET /nodes/n2/disks/zfs/hf-measure-nonexistent-pool` answers a
+ *   generic shelled-out command failure at HTTP 500, the same shape as every other family this
+ *   package has migrated. `zfs-pool-wire.ts` carries the same dual-path read PR 239/243
+ *   established: `readPoolOrFail` (non-folding, used by `diff`) and `readPool` (folding, used by
+ *   `createPool`'s settle-poll and by `read`/`reconcile`).
+ *
+ * ★ MIGRATED OFF `client.ts`'s generic `pve()`/`pveOperations` ONTO `@distilled.cloud/proxmox`'s
+ *   typed `nodes.getNodeDiskZfs`/`createNodeDiskZfs`/`deleteNodeDiskZfs` (2026-09-24, decision
+ *   43's proxmox walk-down, nodes/storage sub-area). `distilled-pve.ts`'s `runPve` replaces
+ *   `pve()`; the cries-wolf fix is wired the same way as every other migrated family. `reconcile`
+ *   and `delete` are still hand-written (never the factory) for the SAME two reasons as before the
+ *   migration — the forked-worker settle-poll, and a DELETE that destroys data — now calling
+ *   `zfs-pool-form.ts`'s `createPool`/`destroyPool` directly instead of through `pveHandlers`.
  *
  * ⚠️ PRIVILEGES, FROM THE SCHEMA. Read and diff need `Sys.Audit` on `/` — both GETs check it.
  *   Reconcile needs `Sys.Modify` on `/` for the POST. `Datastore.Allocate` on `/storage` is NOT
@@ -60,31 +69,23 @@
  *   family checks it, not only the POST. MEASURED the same day as the rest of this paragraph:
  *   `ceph-osd.ts`'s own privilege comparison names `disks/zfs` as one of the sibling families
  *   whose write verbs DO carry a `Sys.Modify` check, unlike `ceph/osd`'s create and delete, which
- *   carry no permissions block at all and 403 for any identity but `root@pam`. This line
- *   previously said delete "needs nothing at all, since it calls nothing", which repeated the same
- *   mistake the header above corrects: `delete` calls the DELETE endpoint, so it needs whatever
- *   that endpoint checks.
+ *   carry no permissions block at all and 403 for any identity but `root@pam`.
  */
 import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import type { NodesNodeDisksZfsPostParams } from './generated/pve.ts';
-import { type PveRequirements, type WithTarget, pveHandlers, pveOperations } from './resource.ts';
-import { spec } from './zfs-pool-spec.ts';
-import { createPool, destroyPool } from './zfs-pool-write.ts';
+import { asForm } from './distilled-guard.ts';
+import { guardForm } from './constraint-guard.ts';
+import type { PveRequirements, WithTarget } from './resource-spec.ts';
+import { UNREADABLE, unreadableWarning } from './unreadable-read.ts';
+import { dropUnreadable, readPool, readPoolOrFail } from './zfs-pool-wire.ts';
+import type { ZfsPoolAttributes } from './zfs-pool-wire.ts';
+import { createForm, createPool, destroyPool, zfsPoolCreateEndpoint } from './zfs-pool-form.ts';
+import type { ZfsCompression, ZfsRaidLevel } from './zfs-pool-form.ts';
 
-/**
- * PVE's layouts, generated (2026-09-23) from `NodesNodeDisksZfsPostParams['raidlevel']`
- * (`generated/pve.ts`, manifest `pve-apidoc` pve-manager 9.2.11 sha256 9def8f13…) rather than
- * hand-typed, per decision 9. ⚠️ Each has a minimum disk count PVE enforces, and `raid10` needs an
- * even one. ⛔ THERE IS NO `stripe` IN THIS ENUM. n1's `speed` pool is one (decision 14 accepts it
- * as-is): `ZfsPoolProps` below is why a stripe pool is declarable at all — as an ADOPT-ONLY
- * declaration with no `raidlevel`, never as a full one.
- */
-export type ZfsRaidLevel = NonNullable<NodesNodeDisksZfsPostParams['raidlevel']>;
-
-/** Generated the same way, from `NodesNodeDisksZfsPostParams['compression']`. */
-export type ZfsCompression = NonNullable<NodesNodeDisksZfsPostParams['compression']>;
+export type { ZfsPoolAttributes } from './zfs-pool-wire.ts';
+export type { ZfsCompression, ZfsRaidLevel } from './zfs-pool-form.ts';
 
 /**
  * ⛔ THERE IS NO `add_storage`, `cleanup-config` OR `cleanup-disks` PROP, AND THAT IS NOT AN
@@ -122,7 +123,7 @@ export interface ZfsPoolProps extends WithTarget {
    *   both this and `raidlevel` undeclared declares an ADOPT-ONLY pool — one this resource may
    *   read and report but never build. That is the only shape available for a pool PVE's own POST
    *   schema cannot fully describe, such as n1's `speed`, whose layout is a stripe and whose
-   *   `raidlevel` enum (above) has no stripe to declare. `createForm` (zfs-pool-write.ts) omits
+   *   `raidlevel` enum (above) has no stripe to declare. `createForm` (zfs-pool-form.ts) omits
    *   both keys when they are absent, and `createPool` refuses before any POST if the pool it
    *   would need to build is not already there — an adopt-only declaration never creates. Declare
    *   both fields together for a pool this resource should build from scratch; declaring only one
@@ -152,30 +153,6 @@ export interface ZfsPoolProps extends WithTarget {
   'draid-config'?: string;
 }
 
-/**
- * ⚠️ EVERYTHING HERE IS REPORTED, NOTHING HERE IS COMPARED — see the ⛔ on `matches`. These exist
- *   so a plan and the state store can say what the pool actually is, on a family where the
- *   declaration and the live object share no comparable field at all.
- */
-export interface ZfsPoolAttributes {
-  /** ★ The value a `Proxmox.Storage` should read to order itself after this pool. */
-  name: string;
-  node: string;
-  /** `ONLINE` | `DEGRADED` | `FAULTED` | … Health, not configuration. */
-  state: string;
-  /** ZFS's own error summary, e.g. `No known data errors`. */
-  errors: string;
-  /**
-   * The leaf devices ZFS reports, in vdev order, comma-joined.
-   *
-   * ⚠️ THIS IS WHAT ZFS RESOLVED, NOT WHAT WAS DECLARED, and the two normally differ: PVE rewrites
-   *   a `/dev/sdb` into a by-id link before creating, and ZFS reports partition paths (`…-part3`)
-   *   for a pool built on partitions — MEASURED, that is exactly what node-b's `rpool` reports. Never
-   *   compare it with `props.devices`.
-   */
-  devices: string;
-}
-
 export interface ProxmoxZfsPool extends Resource<
   'Proxmox.ZfsPool',
   ZfsPoolProps,
@@ -189,24 +166,77 @@ export const ProxmoxZfsPool = Resource<ProxmoxZfsPool>('Proxmox.ZfsPool', {
   defaultRemovalPolicy: 'retain',
 });
 
-const ops = pveOperations(spec);
-
-/**
- * ★ THREE HANDLERS COME FROM THE FACTORY AND TWO DO NOT, SO THE TWO ARE THE ONLY ONES WRITTEN OUT.
- *   `list`, `read` and `diff` are the factory's, unchanged — the spread is what proves it, rather
- *   than three re-typed delegations nobody rereads. `reconcile` and `delete` are the two the header
- *   explains, and they are the only places this family departs from every other resource here.
- *   This is the acl.ts precedent, for a different reason: there the factory's delete hits an
- *   endpoint PVE does not implement, here it hits one that works and destroys the data.
- */
-const handlers = {
-  ...pveHandlers(spec),
-  delete: Effect.fn(function* ({ olds }: { olds: ZfsPoolProps }) {
-    yield* destroyPool(olds, spec.path(olds));
-  }),
-  reconcile: ({ news }: { news: ZfsPoolProps }) =>
-    createPool(news, spec.collection(news), spec.path(news), ops.read),
-};
-
 export const ProxmoxZfsPoolProvider = () =>
-  Provider.effect(ProxmoxZfsPool, Effect.succeed(ProxmoxZfsPool.Provider.of(handlers)));
+  Provider.effect(
+    ProxmoxZfsPool,
+    Effect.succeed(
+      ProxmoxZfsPool.Provider.of({
+        /** ⛔ EMPTY — `GET /nodes/{node}/disks/zfs` returns telemetry for every pool on the node,
+         *   `rpool` included. Adoption stays explicit. */
+        list: () => Effect.succeed([]),
+        // ⚠️ FOLDS ONLY WHEN `output` IS `undefined` — storage.ts's own ⚠️, applied here from the
+        //   start: `output === undefined` (Plan.ts's adoption probe, Apply.ts's delete recovery)
+        //   keeps `readPool`'s fold; `output !== undefined` (Drift.ts's already-confirmed row)
+        //   uses `readPoolOrFail` instead, so `alchemy drift` never reports a transient failure as
+        //   a silent `{action: 'missing'}`.
+        read: Effect.fn(function* ({ olds, output }) {
+          return dropUnreadable(
+            yield* output === undefined ? readPool(olds) : readPoolOrFail(olds),
+          );
+        }),
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          // ⚠️ `guardForm`, NOT `guardWrite` — the only migrated family whose create-guard is
+          //   CONDITIONAL. `guardWrite`'s own signature requires a real `EndpointKey`, but decision
+          //   9's adopt-only mode needs `undefined` some of the time (`zfsPoolCreateEndpoint`'s own
+          //   header) — `guardForm` (constraint-guard.ts) is the one `distilled-guard.ts`'s
+          //   `guardWrite` itself calls, and it already accepts `EndpointKey | undefined`.
+          yield* guardForm(
+            zfsPoolCreateEndpoint(news),
+            asForm(createForm(news)),
+            output === undefined,
+          );
+          if (output === undefined) return undefined;
+          // ⚠️ `readPoolOrFail`, NOT `readPool` — a genuine TRANSIENT failure here propagates and
+          //   fails the whole plan loudly instead of folding to "absent" and forcing a false
+          //   update, the cries-wolf class of bug.
+          const live = yield* readPoolOrFail(news);
+          if (live === UNREADABLE) {
+            yield* unreadableWarning('Proxmox.ZfsPool', `${news.node}/${news.name}`);
+            return { action: 'noop' } as const;
+          }
+          // ⛔ FOUND WRITING THIS FILE, 2026-09-24 — an earlier edit that removed the dead
+          //   `matches()` call (zfs-pool-wire.ts's own ⛔) took this whole branch out with it,
+          //   leaving a genuinely-absent pool planning `noop` unconditionally instead of `update`
+          //   — a silent no-op on a state row Alchemy still holds, caught by
+          //   zfs-pool-adopt.test.ts's own "an adopted pool that vanishes" case rejecting the plan
+          //   loudly rather than resolving. Restored before this PR opened.
+          if (live === undefined) {
+            yield* guardForm(zfsPoolCreateEndpoint(news), asForm(createForm(news)), true);
+            return { action: 'update' } as const;
+          }
+          // A live pool means `noop`, unconditionally — `matches` (zfs-pool-wire.ts's own ⛔)
+          // always answers `true`, since every create parameter is write-only: there is nothing a
+          // declaration and a live pool can be compared on, so nothing here can ever be a replace.
+          return { action: 'noop' } as const;
+        }),
+        /**
+         * ⛔ THE ONLY WRITE THIS FAMILY EVER MAKES IS `createPool`'s create — see zfs-pool-form.ts.
+         *   An existing pool is returned exactly as read, unwritten.
+         * ⚠️ `readPool` PIPED THROUGH `dropUnreadable` — `createPool`'s settle-poll treats a
+         *   refused mid-poll credential exactly like "not found yet" (its own header), so its own
+         *   `read` parameter is typed `Attributes | undefined`, never `Unreadable`; folding here is
+         *   what keeps that true rather than leaking the sentinel into `reconcile`'s own return
+         *   value, which the engine expects to be real attributes or nothing.
+         */
+        reconcile: Effect.fn(function* ({ news }) {
+          return yield* createPool(news, (props) =>
+            readPool(props).pipe(Effect.map(dropUnreadable)),
+          );
+        }),
+        delete: Effect.fn(function* ({ olds }) {
+          yield* destroyPool(olds);
+        }),
+      }),
+    ),
+  );

package/src/unifi/fake-unifi.ts

@@ -0,0 +1,60 @@
+/**
+ * A minimal in-memory UniFi Network API for this family's tests — an in-memory `fetch` handed to
+ * Effect's real `FetchHttpClient` through its `Fetch` reference, mirroring `../netbox/fake-netbox.ts`
+ * (itself mirroring `../forgejo/fake-forgejo.ts`). Tests exercise distilled's REAL path assembly,
+ * JSON encode/decode and status→typed-error matching — nothing about that matching is
+ * re-implemented here, only the wire responses a scenario needs.
+ *
+ * ⛔ TEST-ONLY, AND NO NETWORK. No provider imports this file. The base URL is RFC 2606
+ *   `unifi.example.com` and the key is a placeholder — never a real console address: a cloud
+ *   connector's base URL embeds the account's Console ID, which must never appear in this repo
+ *   (`docs/unifi.md`).
+ */
+import { type Credentials, credentials } from '@distilled.cloud/unifi-network/Credentials';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+
+export const FAKE_BASE = 'https://unifi.example.com/proxy/network/integration';
+export const FAKE_KEY = 'placeholder-unifi-key';
+
+export type Seen = { readonly method: string; readonly path: string };
+
+/** No documented failure envelope (see `protocol.ts`) — plain text is all a failure needs. */
+export const fakeFailure = (status: number, detail: string) => new Response(detail, { status });
+
+/**
+ * `route` decides every response; this wrapper only records what was sent and adapts to
+ * `globalThis.fetch`'s signature.
+ *
+ * ★ THE WRITE-REFUSAL PROOF USES `seen` DIRECTLY, NOT A THROWING ROUTE. `resource.test.ts`'s
+ *   "no SDK write operation is reachable" test asserts `seen.every(s => s.method === 'GET')`
+ *   after driving every handler — a request this family's engine was never supposed to send
+ *   shows up in `seen` as a fact, rather than depending on an exception surviving Effect's own
+ *   error handling on its way back out of a fake `fetch`.
+ */
+export const fakeUnifi = (route: (method: string, url: URL) => Response) => {
+  const seen: Seen[] = [];
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    seen.push({ method: request.method, path: `${url.pathname}${url.search}` });
+    return route(request.method, url);
+  }) as typeof globalThis.fetch;
+  return { fetch, seen };
+};
+
+/**
+ * distilled Credentials + the real FetchHttpClient over the fake — `UnifiNetworkOpContext`, what
+ * every resource file's exported `spec.fetchLive` needs.
+ *
+ * ⚠️ NOT PAIRED WITH `handlers`. `handlers` (each resource file's `unifiHandlers(spec)` export)
+ *   bakes in `CredentialsFromEnv`, which resolves `UNIFI_NETWORK_API_KEY`/`_API_BASE_URL` through
+ *   Effect's `Config` — whose default provider snapshots `process.env` once and never re-reads it
+ *   (the same seam `netbox/fake-netbox.ts` documents). Tests call `spec.fetchLive`/`spec.attributes`
+ *   directly instead, with this explicit layer.
+ */
+export const fakeUnifiLayer = (
+  fetchFn: typeof globalThis.fetch,
+  creds: Layer.Layer<Credentials> = credentials({ apiBaseUrl: FAKE_BASE, apiKey: FAKE_KEY }),
+) => Layer.mergeAll(creds, FetchHttpClient.layer, Layer.succeed(FetchHttpClient.Fetch, fetchFn));

package/src/unifi/firewall-zone-form.ts

@@ -0,0 +1,65 @@
+/**
+ * `Unifi.FirewallZone`'s wire shape — the declarable subset of `FirewallZone`, and how a live
+ * read becomes both plan attributes and a rendered declaration.
+ *
+ * ⚠️ ONLY `name` AND `networkIds` ARE DECLARABLE. `CreateFirewallZoneRequest`
+ *   (`firewall.ts`) accepts exactly those two beyond `siteId`; `metadata` (origin/source) and
+ *   `id` are server-derived, so — same split as `network-form.ts`'s `default`/`metadata` —
+ *   they are attributes-only, reported but never compared or declared.
+ *
+ * ⛔ `networkIds` ORDER IS NOT PART OF IDENTITY. The vendor document gives no indication the
+ *   list is ordered (it is a set of attached networks, not a sequence like the ordering
+ *   endpoints' rule lists), so `matches` compares it as a set — sorted before comparing —
+ *   the same reasoning `proxmox/user-wire.ts`'s `groupSet` gives for PVE's `groups`.
+ */
+import type * as firewall from '@distilled.cloud/unifi-network/firewall';
+
+export interface FirewallZoneProps {
+  siteId: string;
+  firewallZoneId: string;
+  /** Name of a firewall zone. */
+  name: string;
+  /** Network IDs attached to this zone — compared as a set, see the header. */
+  networkIds: string[];
+}
+
+export interface FirewallZoneAttributes {
+  siteId: string;
+  firewallZoneId: string;
+  name: string;
+  networkIds: string[];
+  /** `origin`/`source` (e.g. `SDWAN`) — server-derived, never declared. */
+  metadataOrigin: string;
+}
+
+const sortedSet = (values: readonly string[]): string[] => [...new Set(values)].sort();
+
+export const attributesOf = (
+  live: firewall.FirewallZone,
+  props: FirewallZoneProps,
+): FirewallZoneAttributes => ({
+  siteId: props.siteId,
+  firewallZoneId: live.id,
+  name: live.name,
+  networkIds: sortedSet(live.networkIds),
+  metadataOrigin: live.metadata.origin,
+});
+
+export const matches = (attributes: FirewallZoneAttributes, props: FirewallZoneProps): boolean =>
+  attributes.name === props.name &&
+  attributes.networkIds.join(',') === sortedSet(props.networkIds).join(',');
+
+/**
+ * The declaration renderer (task spec: "given one live object, return the props a declaration
+ * needs so its plan is noop"). `matches(attributesOf(live, props), declareFirewallZone(live,
+ * siteId))` is `true` by construction (`firewall-zone.test.ts` proves it).
+ */
+export const declareFirewallZone = (
+  live: firewall.FirewallZone,
+  siteId: string,
+): FirewallZoneProps => ({
+  siteId,
+  firewallZoneId: live.id,
+  name: live.name,
+  networkIds: sortedSet(live.networkIds),
+});