@homeflare/alchemy 0.31.2 → 0.33.0

package/src/proxmox/storage.ts

@@ -12,19 +12,48 @@
  * ⛔ ONE PRIVILEGE COVERS THIS WHOLE FAMILY AND IT IS `Datastore.Allocate` ON `/storage`. Create,
  *   update, delete AND the single-object read all check it — `Datastore.Audit` is not enough for
  *   any of them. MEASURED: `GET /storage/local` under the auditor-scoped `read` lease answers 403
- *   "Permission check failed (/storage/local, Datastore.Allocate)". `pveOperations.read` folds
- *   every failure into `undefined`, i.e. "absent", because a 404 is a legitimate answer there and
- *   it cannot tell the two apart — so under that lease this resource NEVER CONVERGES, in two
- *   directions: reconcile reads "absent" and POSTs a create over a storage that is already defined,
- *   and where a create does land the read-back is 403 too, so reconcile dies with "the write
- *   returned no error but the object is still absent" about an object it has just built. Both
- *   messages point away from the cause.
- *   ★ SO WIDEN OR RE-POINT BEFORE THE FIRST PLAN, outside this file: give the credential mount's
- *     `read` role `Datastore.Allocate` on `/storage`, or read this family with `provision`. The
- *     provision role in the estate this was written for held only `Datastore.AllocateSpace` and
- *     `Datastore.Audit`, and NEITHER IS IT — AllocateSpace writes volumes INTO a storage, Allocate
- *     DEFINES one — so it 403'd here until widened the way `Pool.Allocate` was for `Proxmox.Pool`.
- *     The provisioning baseline (`provision-baseline.ts`) carries `Datastore.Allocate`.
+ *   "Permission check failed (/storage/local, Datastore.Allocate)". So this family reads with
+ *   `provision`, same as acl.ts and unlike group.ts/user.ts — `provision-baseline.ts` carries
+ *   `Datastore.Allocate`.
+ *
+ * ⛔ ON A LANE WHOSE CREDENTIAL CANNOT MINT `provision` (the agent's `read`-role lane), THIS
+ *   FAMILY SHIPPED WITH THE ORIGINAL CRIES-WOLF BUG — measured live, 2026-09-24: `bun run plan`
+ *   showed all 5 storages (`cephfs-tb4`, `cephtb4`, `local`, `local-zfs`, `pbs`) as `update`, with
+ *   no warning, because `client.ts`'s `pveOperations.read` folded the REFUSED mint into `undefined`
+ *   the same way it folds a genuine absence — `unreadable-read.ts`'s own header names this family
+ *   by name as one of the two the fix was written for. Migrated here the way acl.ts/group.ts/
+ *   user.ts were (kit 0.31.1/0.31.2): a refused `provision` mint now reports `noop` with a logged
+ *   warning instead of forcing `update` with nothing compared.
+ *
+ * ⛔ A MISSING STORAGE IS A 500, NOT A 404 — MEASURED against the live cluster (TB4, 2026-09-24,
+ *   admin lane, read-only `GET /storage/hf-measure-nonexistent-probe`): `{"message":"storage
+ *   '...' does not exist\n"}` at HTTP 500. `storage-wire.ts`'s `readStorageOrFail`/`readStorage`
+ *   carry the same dual-path split as user.ts/group.ts for exactly this reason — see that file.
+ *
+ * ⛔ `maxfiles` IS GONE — A MEASURED `@distilled.cloud/proxmox` SDK GAP, NOT A SCOPE TRIM. The
+ *   vendor's generated `CreateStorageRequest`/`PutStorageRequest` (storage-wire.ts's `mutable`)
+ *   have no `maxfiles` field at all — grepped across the whole package, not just this endpoint —
+ *   where `prune-backups`, its documented replacement, is present and correctly wired
+ *   (`T.Body("prune-backups")` on the generated `prune_backups` property). Silently dropping a
+ *   declared `maxfiles` value would have been the same class of bug this whole migration exists to
+ *   close: a write that looks like it landed and did not. So `maxfiles?: never` below, the same
+ *   COMPILE-ERROR treatment `StorageLocator`'s `password`/`keyring`/`encryption-key` already get —
+ *   a declaration that sets it is refused before a plan ever runs, not silently ignored by one.
+ *   None of this cluster's 5 live storages set it (measured, live response bodies below). If a
+ *   consumer genuinely needs it, the fix belongs in `@distilled.cloud/proxmox`'s generator, not a
+ *   hand-rolled bypass here — see the provider-walk-down doctrine on vendor gaps.
+ *
+ * ⛔ EVERY HYPHENATED PVE FIELD NAME BECOMES AN UNDERSCORE IN DISTILLED'S GENERATED TYPESCRIPT —
+ *   MEASURED across the WHOLE generated `CreateStorageRequest`/`PutStorageRequest`, not one field:
+ *   `prune-backups` -> `prune_backups`, `fs-name` -> `fs_name`, `max-protected-backups` ->
+ *   `max_protected_backups`, and so on for every plugin field `StorageLocator`'s free-form bag can
+ *   carry (`cephfs-tb4`'s own live locator uses `fs-name`, measured below). No other family
+ *   migrated so far has a hyphenated field at all, so this is new here. `storage-wire.ts`'s
+ *   `underscored` translates a form BUILT with PVE's own names into distilled's shape, but ONLY
+ *   for the actual SDK call (`toDistilledCreate`/`toDistilledUpdate`) — never for the form
+ *   `guardWrite` checks (`createForm`/`updateForm`), which the generated vendor-constraint tables
+ *   key by PVE's own hyphenated names. Running the translation before that check would make it
+ *   silently stop inspecting the very fields it exists to catch.
  *
  * ⛔ THERE IS NO `password` PROP AND THERE MUST NEVER BE ONE. PBS and CIFS storages take one at
  *   create time, and Alchemy persists attributes UNENCRYPTED — a secret in props is one careless
@@ -33,28 +62,36 @@
  *   a COMPILE ERROR rather than a leak somebody finds in a backup months later. Set it once out of
  *   band (`pvesm set <id> --password`); PVE never returns it on read, so nothing here could diff it
  *   anyway.
+ *
+ * ★ MIGRATED OFF `client.ts`'s generic `pve()`/`pveHandlers` (`resource.ts`) ONTO
+ *   `@distilled.cloud/proxmox`'s typed `storage.getStorage`/`createStorage`/`putStorage`/
+ *   `deleteStorage` (2026-09-24, decision 43's proxmox walk-down, nodes/storage sub-area, first
+ *   resource). `distilled-pve.ts`'s `runPve` replaces `pve()`; the cries-wolf fix is wired the
+ *   same way as acl.ts/group.ts/user.ts.
  */
 import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
+import * as storage from '@distilled.cloud/proxmox/storage';
 import * as Effect from 'effect/Effect';
-import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
-import { bool, flag } from './values.ts';
+import { guardWrite } from './distilled-guard.ts';
+import type { PveRequirements, WithTarget } from './resource-spec.ts';
+import { runPve } from './distilled-pve.ts';
+import {
+  STORAGE_CREATE,
+  STORAGE_UPDATE,
+  createForm,
+  toDistilledCreate,
+  toDistilledUpdate,
+  updateForm,
+} from './storage-form.ts';
+import { dropUnreadable, matches, readStorage, readStorageOrFail } from './storage-wire.ts';
+import { UNREADABLE, unreadableWarning } from './unreadable-read.ts';
+import type { StorageAttributes } from './storage-wire.ts';
+import type { StorageLocator } from './storage-form.ts';
 
-/**
- * The create-time, plugin-specific half of a storage: `dir` wants `path`, `nfs` `server`+`export`,
- * `cifs` `server`+`share`, `pbs` `server`+`datastore`, `rbd` `pool`+`monhost`, `lvmthin`
- * `vgname`+`thinpool`, `zfspool` `pool`. A bag rather than two dozen named fields, because PVE
- * ships about that many plugins and each brings its own locator. ⚠️ Never diffed — see `matches`.
- *
- * ⛔ `password`, `keyring` AND `encryption-key` ARE `never` ON PURPOSE — see the ⛔ in the header.
- *   POSITIVE-CONTROLLED rather than assumed: all three are a compile error, `TS2322: Type 'string'
- *   is not assignable to type 'undefined'`.
- */
-export type StorageLocator = Record<string, string> & {
-  password?: never;
-  keyring?: never;
-  'encryption-key'?: never;
-};
+/** Re-exported so a caller of this file still finds them here, unchanged by the split below. */
+export type { StorageAttributes, StorageLocator };
 
 export interface StorageProps extends WithTarget {
   /** PVE's primary key, cluster-wide — the string an LXC's `storage` and `ostemplate` name. */
@@ -85,26 +122,8 @@ export interface StorageProps extends WithTarget {
    */
   'prune-backups'?: string;
   comment?: string;
-  /**
-   * ⚠️ THE DEPRECATED PREDECESSOR OF `prune-backups`, and the two do not mix — declare one or the
-   *   other. `0` means UNLIMITED to PVE rather than "unset", hence the `-1` in the attribute.
-   */
-  maxfiles?: number;
-}
-
-export interface StorageAttributes {
-  storage: string;
-  /** Reported so a plan can show what it points at; never diffed — see `type` above. */
-  type: string;
-  content: string;
-  nodes: string;
-  disable: boolean;
-  shared: boolean;
-  preallocation: string;
-  'prune-backups': string;
-  comment: string;
-  /** ⚠️ `-1` means "no maxfiles in storage.cfg". `0` is a real setting meaning unlimited. */
-  maxfiles: number;
+  /** ⛔ REMOVED — a measured `@distilled.cloud/proxmox` gap, not a scope trim. See the header. */
+  maxfiles?: never;
 }
 
 export interface ProxmoxStorage extends Resource<
@@ -120,129 +139,100 @@ export const ProxmoxStorage = Resource<ProxmoxStorage>('Proxmox.Storage', {
   defaultRemovalPolicy: 'retain',
 });
 
-const str = (value: unknown, fallback = '') => (typeof value === 'string' ? value : fallback);
-
-const field = (name: string, value: string | undefined): Record<string, string> =>
-  value === undefined ? {} : { [name]: value };
-
-/**
- * ⚠️ THE CAST DROPS THE THREE `never` GUARDS AND NOTHING ELSE, and it is load-bearing rather than
- *   lazy: an intersection carrying OPTIONAL properties is not assignable to `Record<string,string>`
- *   at all, so the guards and the form body cannot both exist without one conversion. At runtime a
- *   locator is a plain string map; the guards only ever existed to fail a declaration.
- */
-const locatorForm = (locator: StorageLocator | undefined) =>
-  ({ ...locator }) as Record<string, string>;
-
-/**
- * ⚠️ PVE RE-SERIALISES ITS LIST FIELDS IN ITS OWN ORDER — `content` and `nodes` are parsed into a
- *   set and written back sorted, `prune-backups` is a property string that comes back in schema
- *   order. Comparing raw strings would report an update for `iso,backup` against `backup,iso` on
- *   every plan, and the PUT would "fix" it into the identical string. Trimming matters too: a
- *   declared `iso, backup` would otherwise never equal what PVE stores.
- */
-const tokens = (value: string) =>
-  value
-    .split(',')
-    .map((part) => part.trim())
-    .filter((part) => part !== '')
-    .sort()
-    .join(',');
-
-const sameList = (declared: string | undefined, live: string) =>
-  declared === undefined || tokens(declared) === tokens(live);
-
-const same = <T>(declared: T | undefined, live: T) => declared === undefined || declared === live;
-
-/**
- * The mutable half, for create and update alike.
- *
- * ⚠️ AN UNDECLARED FIELD IS NEITHER SENT NOR COMPARED: undeclared means UNMANAGED here, unlike
- *   `Proxmox.Pool` where an absent comment means `''`. A storage has no single default to fall back
- *   on — `content` defaults per plugin, and clearing a field needs an explicit `delete=` parameter
- *   rather than an empty value — so a guessed default would rewrite a storage somebody tuned by
- *   hand, and comparing one would report drift nobody declared.
- *
- * ⚠️ RECONCILE PUTs UNCONDITIONALLY whenever the object exists (resource.ts), so this form must be
- *   safe to re-apply to a storage that already matches. It is: the declared set and nothing else,
- *   and PVE leaves absent parameters alone.
- */
-const mutable = (props: StorageProps): Record<string, string> => ({
-  ...field('comment', props.comment),
-  ...field('content', props.content),
-  ...field('disable', flag(props.disable)),
-  ...field('maxfiles', props.maxfiles === undefined ? undefined : String(props.maxfiles)),
-  ...field('nodes', props.nodes),
-  ...field('preallocation', props.preallocation),
-  ...field('prune-backups', props['prune-backups']),
-  ...field('shared', flag(props.shared)),
-});
-
-const handlers = pveHandlers<StorageProps, StorageAttributes>({
-  // ⛔ PVE gates this family's ITEM read on the allocate privilege, not the audit one — see
-  //   `readRole` in resource.ts. The auditor-shaped lease reads 403, which `read` turns into
-  //   "absent", and the plan then says create for an object that is plainly there.
-  readRole: 'provision',
-  /**
-   * ⚠️ `digest` IS DELIBERATELY NOT AN ATTRIBUTE. PVE returns one on every storage read and it
-   *   covers storage.cfg as a FILE, not this section of it, so keeping it would rewrite this
-   *   resource's state whenever an unrelated storage was edited — churn that reads like drift.
-   */
-  attributes: (live, props) => ({
-    comment: str(live['comment']),
-    content: str(live['content']),
-    disable: bool(live['disable']),
-    maxfiles: typeof live['maxfiles'] === 'number' ? live['maxfiles'] : -1,
-    nodes: str(live['nodes']),
-    preallocation: str(live['preallocation']),
-    'prune-backups': str(live['prune-backups']),
-    shared: bool(live['shared']),
-    storage: props.storage,
-    type: str(live['type'], props.type),
-  }),
-  collection: () => 'storage',
-  /**
-   * ⚠️ THE BAG IS SPREAD FIRST SO NOTHING IN IT CAN SHADOW A FIELD THIS RESOURCE MANAGES. A stray
-   *   `storage` or `type` in a locator would otherwise rename the object being created, and PVE
-   *   would build the wrong thing under a name Alchemy then records as the declared one.
-   */
-  createForm: (props) => ({
-    ...locatorForm(props.locator),
-    ...mutable(props),
-    storage: props.storage,
-    type: props.type,
-  }),
-  /**
-   * ⚠️ `type` AND THE LOCATOR ARE NEVER COMPARED, AND AN UNDECLARED FIELD IS NOT COMPARED EITHER.
-   *   PVE returns the create-only fields on read but refuses them on PUT, so diffing one could only
-   *   plan an update that no write can apply: a plan that reports work on every run, forever.
-   */
-  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
-  endpoint: { create: 'pve:POST /storage', update: 'pve:PUT /storage/{storage}' },
-  matches: (attributes, props) =>
-    sameList(props.content, attributes.content) &&
-    sameList(props.nodes, attributes.nodes) &&
-    sameList(props['prune-backups'], attributes['prune-backups']) &&
-    same(props.disable, attributes.disable) &&
-    same(props.shared, attributes.shared) &&
-    same(props.preallocation, attributes.preallocation) &&
-    same(props.comment, attributes.comment) &&
-    same(props.maxfiles, attributes.maxfiles),
-  path: (props) => `storage/${props.storage}`,
-  updateForm: mutable,
-});
-
-/**
-* ⛔ EMPTY, AND HERE IT MATTERS MORE THAN ANYWHERE ELSE IN THIS PACKAGE. `GET /storage`
-*   returns every definition on the cluster, `local` and `local-lvm`/`local-zfs` included:
-*   the installer's own, that every guest's rootfs sits on. Adopting those would put
-*   Alchemy one `delete` away from the cluster's disks. Adoption is explicit, always.
- 
- *
-* ⚠️ THIS REMOVES THE DEFINITION, NOT THE DATA. PVE drops the section from storage.cfg and
-*   leaves the volumes on disk untouched — so the loss is not the bytes, it is that guests
-*   whose config still names this storage can no longer resolve their own disks.
- 
- */
 export const ProxmoxStorageProvider = () =>
-  Provider.effect(ProxmoxStorage, Effect.succeed(ProxmoxStorage.Provider.of(handlers)));
+  Provider.effect(
+    ProxmoxStorage,
+    Effect.succeed(
+      ProxmoxStorage.Provider.of({
+        /**
+         * ⛔ EMPTY, AND HERE IT MATTERS MORE THAN ANYWHERE ELSE IN THIS PACKAGE. `GET /storage`
+         *   returns every definition on the cluster, `local` and `local-lvm`/`local-zfs` included:
+         *   the installer's own, that every guest's rootfs sits on. Adopting those would put
+         *   Alchemy one `delete` away from the cluster's disks. Adoption is explicit, always.
+         */
+        list: () => Effect.succeed([]),
+        // ⚠️ FOLDS ONLY WHEN `output` IS `undefined` — user.ts's/group.ts's own ⚠️, applied here
+        //   from the start rather than found by a later review: the engine calls this hook from
+        //   Plan.ts's adoption probe and interrupted-create recovery and Apply.ts's delete
+        //   recovery (all `output: undefined`, nothing confirmed exists yet — `readStorage`'s fold
+        //   is still needed) as well as Drift.ts (`output: old.attr`, an ALREADY-CONFIRMED row,
+        //   `diff`'s own situation — `readStorageOrFail` there instead, or a transient failure
+        //   reports a silent `{action: 'missing'}` with no error at all).
+        read: Effect.fn(function* ({ olds, output }) {
+          return dropUnreadable(
+            yield* output === undefined ? readStorage(olds) : readStorageOrFail(olds),
+          );
+        }),
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          yield* guardWrite(STORAGE_CREATE, createForm(news), output === undefined);
+          yield* guardWrite(STORAGE_UPDATE, updateForm(news), false);
+          if (output === undefined) return undefined;
+          // ⚠️ `readStorageOrFail`, NOT `readStorage` — see that function's own ⛔ in
+          //   storage-wire.ts. A genuine TRANSIENT failure here propagates and fails the whole
+          //   plan loudly instead of folding to "absent" and forcing a false update.
+          const live = yield* readStorageOrFail(news);
+          // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and force
+          //   `update` on a storage that was plainly there — see unreadable-read.ts.
+          if (live === UNREADABLE) {
+            yield* unreadableWarning('Proxmox.Storage', news.storage);
+            return { action: 'noop' } as const;
+          }
+          if (live === undefined) {
+            yield* guardWrite(STORAGE_CREATE, createForm(news), true);
+            return { action: 'update' } as const;
+          }
+          return matches(live, news)
+            ? ({ action: 'noop' } as const)
+            : ({ action: 'update' } as const);
+        }),
+        reconcile: Effect.fn(function* ({ news }) {
+          // ⚠️ `dropUnreadable`: reconcile only runs once `provision` already minted for the
+          //   write below, so `UNREADABLE` here is a narrow race, not the routine case `diff`
+          //   handles — group.ts's/user.ts's reconcile have the same note.
+          const before = dropUnreadable(yield* readStorage(news));
+          yield* guardWrite(STORAGE_CREATE, createForm(news), before === undefined);
+          yield* guardWrite(STORAGE_UPDATE, updateForm(news), false);
+          if (before === undefined) {
+            yield* runPve(
+              news.target,
+              'provision',
+              true,
+              storage.createStorage(toDistilledCreate(news)),
+            );
+          } else if (!matches(before, news)) {
+            yield* runPve(
+              news.target,
+              'provision',
+              true,
+              storage.putStorage(toDistilledUpdate(news)),
+            );
+          }
+          const after = dropUnreadable(yield* readStorage(news));
+          if (after === undefined) {
+            return yield* Effect.die(
+              new Error(
+                `storage/${news.storage}: the write returned no error but the storage is still ` +
+                  'absent. PVE wraps every answer in {"data":...} and can report success on a ' +
+                  'call that did nothing -- read back rather than trusting the status code.',
+              ),
+            );
+          }
+          return after;
+        }),
+        /**
+         * ⚠️ THIS REMOVES THE DEFINITION, NOT THE DATA. PVE drops the section from storage.cfg and
+         *   leaves the volumes on disk untouched — so the loss is not the bytes, it is that guests
+         *   whose config still names this storage can no longer resolve their own disks.
+         */
+        delete: Effect.fn(function* ({ olds }) {
+          yield* runPve(
+            olds.target,
+            'provision',
+            true,
+            storage.deleteStorage({ storage: olds.storage }),
+          );
+        }),
+      }),
+    ),
+  );

package/src/proxmox/zfs-pool-adopt.test.ts

@@ -138,4 +138,30 @@ describe('adopting an adopt-only ZfsPool declaration', () => {
     const r: ZfsRaidLevel = 'stripe';
     expect(String(r)).toBe('stripe');
   });
+
+  /**
+   * ⛔ FOUND BY ADVERSARIAL REVIEW, 2026-09-24: a genuinely FIRST-EVER declaration never reaches
+   *   `diff` at all (upstream `Plan.ts` routes `oldState === undefined` straight to `create`), so
+   *   the vendor-constraint check `diff` runs had never once protected a brand-new pool's own
+   *   create -- only an ADOPT's later plans. `createPool` (zfs-pool-form.ts) now re-checks before
+   *   its own POST, the same pattern `ceph-pool.ts`'s hand-written `reconcile` already uses.
+   */
+  test('a malformed ashift on a brand-new (non-adopt) declaration is refused before any write', async () => {
+    const fake = cluster(new Set());
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const bad = () =>
+        ProxmoxZfsPool('bad', {
+          // ⛔ PVE's own bound is 9-16 (generated/constraints/pve-nodes-disks.ts) -- 99 is refused.
+          ashift: 99,
+          devices: ['/dev/disk/by-id/fake-0'],
+          name: 'newpool',
+          node: 'node-b',
+          raidlevel: 'single',
+          target: FAKE_TARGET,
+        });
+      await expect(engine.deploy(bad())).rejects.toBeDefined();
+    });
+    expect(fake.writes()).toEqual([]);
+  });
 });

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

@@ -0,0 +1,236 @@
+/**
+ * The create lane for `Proxmox.ZfsPool`: the form PVE wants, and the wait for the worker it forks.
+ * Split out of zfs-pool.ts (2026-09-24, the distilled migration) — same seam as before, now naming
+ * the write side the way storage.ts/storage-form.ts does.
+ *
+ * ⚠️ `createPool` TAKES THE READ AS A PARAMETER, GENERIC IN ITS ERROR AND REQUIREMENT CHANNELS,
+ *   rather than importing the read module and coupling to its exact effect shape here. This file
+ *   answers "how does a declaration become a pool on disks"; zfs-pool-wire.ts answers "what is a
+ *   zpool, and when has it changed" — the caller (zfs-pool.ts) is what ties the two together, so
+ *   this file cannot accidentally read the cluster differently from `diff`.
+ */
+import * as Effect from 'effect/Effect';
+import * as nodes from '@distilled.cloud/proxmox/nodes';
+import { asForm } from './distilled-guard.ts';
+import { guardForm } from './constraint-guard.ts';
+import { runPve } from './distilled-pve.ts';
+import { text } from './values.ts';
+import type { ZfsPoolAttributes, ZfsPoolProps } from './zfs-pool.ts';
+import type { NodesNodeDisksZfsPostParams } from './generated/pve.ts';
+
+export const ZFS_POOL_CREATE = 'pve:POST /nodes/{node}/disks/zfs';
+
+/**
+ * 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` (zfs-pool.ts) 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']>;
+
+/**
+ * ★ CHECKED AGAINST THE VENDOR TABLE ONLY FOR A FULL DECLARATION — decision 9's adopt-only mode.
+ *   `guardCreate` (distilled-guard.ts's `guardWrite`) runs on the FIRST plan of ANY declaration and
+ *   checks the create form's REQUIRED fields whenever this resolves to the real endpoint key — and
+ *   PVE marks both `devices` and `raidlevel` required (codegen/constraints's `pve-nodes-disks`
+ *   row). An adopt-only declaration deliberately omits both, so checking it would refuse a MATCHING
+ *   adoption at plan time, before `read` ever ran. Returning `undefined` (no key) makes the guard a
+ *   no-op for an adopt-only declaration, while a FULL one (`devices` and `raidlevel` both present)
+ *   is checked exactly as before — zfs-pool.ts's `diff` passes this as the `guardWrite` endpoint.
+ * ⚠️ THE RUNTIME BACKSTOP IS `createPool` BELOW, NOT THIS FUNCTION. Skipping the plan-time guard
+ *   for an adopt-only declaration does not skip the check that the pool is actually there —
+ *   `createPool` refuses before any POST when the read comes back absent and either field is
+ *   undefined, which is what a genuinely absent adopt-only declaration hits at apply time.
+ */
+export const zfsPoolCreateEndpoint = (props: ZfsPoolProps) =>
+  props.devices === undefined || props.raidlevel === undefined ? undefined : ZFS_POOL_CREATE;
+
+/**
+ * The wire form, PVE's own field names — what `guardWrite` (zfs-pool.ts) checks.
+ *
+ * ⚠️ `devices` IS JOINED IN DECLARED ORDER AND NOT PUT THROUGH `csv()` FROM values.ts. `csv` sorts,
+ *   and PVE walks this list two at a time to pair `raid10` mirrors — MEASURED in the node's own
+ *   `PVE::API2::Disks::ZFS` — so sorting it builds a different pool from the one declared. The list
+ *   is never compared against anything, so it needs no normalisation, only faithful order.
+ * ⚠️ AN OMITTED OPTIONAL IS NOT SENT. PVE's own defaults (ashift 12, compression on) are then
+ *   applied by the node. Sending a guessed default would be indistinguishable here — the values
+ *   are unreadable afterwards either way — but it would put a number in the request that no
+ *   declaration asked for, and this is the one call that writes to physical disks.
+ * ⚠️ `node` IS NOT IN THE FORM: it is the `nodes/{node}` path label, and a second copy could only
+ *   disagree with it.
+ * ⚠️ EVERY KEY IS OMITTED WHEN ABSENT, `devices` AND `raidlevel` INCLUDED — not just the optional
+ *   ones. An adopt-only declaration (both undefined, decision 9) must produce a form `createPool`'s
+ *   own guard can inspect for their absence, and one this function itself does not throw building.
+ */
+export const createForm = (props: ZfsPoolProps): Record<string, string> => ({
+  ...(props.devices === undefined ? {} : { devices: props.devices.join(',') }),
+  name: props.name,
+  ...(props.raidlevel === undefined ? {} : { raidlevel: props.raidlevel }),
+  ...(props.ashift === undefined ? {} : { ashift: String(props.ashift) }),
+  ...(props.compression === undefined ? {} : { compression: props.compression }),
+  ...(props['draid-config'] === undefined ? {} : { 'draid-config': props['draid-config'] }),
+});
+
+/**
+ * The actual `createNodeDiskZfs` call body — `createForm` plus the `node` label, `draid-config`
+ * renamed to distilled's `draid_config` (`T.Body("draid-config")` on the generated schema; the
+ * ONE hyphenated field this family's create form carries — storage-form.ts's `underscored` has
+ * the fuller measurement, not repeated here for one field).
+ *
+ * ⚠️ `as unknown as` — `devices`/`raidlevel` are REQUIRED in distilled's generated
+ *   `CreateNodeDiskZfsRequest`, so an adopt-only form (both omitted) cannot satisfy it structurally
+ *   even though it is a valid PVE request for `guardWrite`'s purposes. `createPool` below refuses
+ *   before ever reaching this cast when either is genuinely missing, so the cast never carries a
+ *   request distilled's OWN required fields would reject in practice.
+ */
+const toDistilledCreate = (props: ZfsPoolProps): nodes.CreateNodeDiskZfsRequest => {
+  const form = createForm(props);
+  return {
+    ...form,
+    draid_config: form['draid-config'],
+    node: props.node,
+  } as unknown as nodes.CreateNodeDiskZfsRequest;
+};
+
+/** 30 reads, 2s apart. A create that has not landed in a minute has gone wrong, not gone slow. */
+const SETTLE_ATTEMPTS = 30;
+
+/**
+ * Create the pool if it is absent, and otherwise leave it completely alone.
+ *
+ * ⛔ THE POST ONLY FORKS A WORKER. MEASURED in `/usr/share/perl5/PVE/API2/Disks/ZFS.pm` on node-b:
+ *   the create handler ends in `$rpcenv->fork_worker('zfscreate', ...)` and its HTTP answer is a
+ *   UPID returned the instant the worker is forked — before `zpool create` has run, let alone
+ *   finished. A read-back taken immediately would report a successful create as the failure "the
+ *   write returned no error but the object is still absent". THAT is why this function polls.
+ *
+ * ⚠️ THERE IS NO UPDATE BRANCH BECAUSE PVE HAS NO PUT HERE. An existing pool is returned exactly as
+ *   read, unwritten: the only write this resource ever makes is the create of a pool that is not
+ *   there. Do not add a "repair" write; there is no field it could set.
+ *
+ * ⛔ AND IF THE READ IS WRONG, THE POST IS STILL SAFE — measured, not hoped for. `readPool` folds a
+ *   403 or an unreachable node into "absent", so a too-narrow lease would send this down the create
+ *   path over a live pool. PVE's handler calls `get_pool_data()` before it forks anything and dies
+ *   with "pool '<name>' already exists on node '<node>'", and `assert_disk_unused` refuses every
+ *   device that pool is holding. A create aimed at a pool that is really there fails loudly rather
+ *   than wiping it.
+ *
+ * ⚠️ SHORT POLLS WITH A HARD CAP, NOT ONE LONG WAIT, NOT `@distilled.cloud/proxmox`'s `awaitTask`.
+ *   `readPool` cannot tell "not yet" from "forbidden" — both fold to `undefined` — so the loop
+ *   gives up with the UPID rather than retrying forever, and the UPID is the only thing that leads
+ *   to the worker's real error. Distilled's own task-status poller exists (`Task.ts`) and would
+ *   remove this ambiguity, but swapping to it changes this resource's OBSERVABLE behaviour (what a
+ *   caller sees on a slow create) beyond a transport swap — left as a follow-up, not folded into a
+ *   migration PR silently.
+ *
+ * ⛔ THE SAME AMBIGUITY MAKES A RE-RUN AFTER THE GIVE-UP DIE GENUINELY UNSAFE, NOT MERELY SLOW TO
+ *   CONFIRM — FOUND BY ADVERSARIAL REVIEW, 2026-09-24, of THIS migration, though the shape is
+ *   unchanged from before it (`git blame` shows the same settle-poll pre-dates this PR). "If the
+ *   read is wrong, the POST is still safe" above is true for the FIRST call into this function —
+ *   PVE's own `get_pool_data()` refuses a create over a pool it can already see. It is NOT true
+ *   for a SECOND deploy attempt started while the FIRST worker is still mid-`zpool create`: that
+ *   worker has not yet made the pool visible to a read, so `existing = yield* read(props)` at the
+ *   top of THIS call can also fold to `undefined` — not because the pool is gone, but because the
+ *   first attempt has not finished — and this function would POST a SECOND `zpool create` at the
+ *   SAME devices while the first is still writing them. There is no lock or marker anywhere in
+ *   this package that would stop it. The give-up message below says so explicitly and names the
+ *   task log to check FIRST; that message, and an operator reading it, are the only safeguard.
+ *
+ * ⛔ THE ADOPT-ONLY GUARD, RIGHT AFTER THE READ AND BEFORE ANYTHING ELSE. Decision 9 (2026-09-23):
+ *   omitting `devices` and `raidlevel` declares a pool this resource may only ADOPT, for a pool
+ *   PVE's own schema cannot fully describe — n1's `speed` is a stripe, and `raidlevel`'s enum has
+ *   no stripe (zfs-pool.ts). `zfsPoolCreateEndpoint` above already keeps the vendor constraint
+ *   guard from refusing such a declaration at PLAN time; this is the matching refusal at APPLY
+ *   time, for the one case that guard cannot see — the pool genuinely is not there.
+ */
+export const createPool = <E, R>(
+  props: ZfsPoolProps,
+  read: (props: ZfsPoolProps) => Effect.Effect<ZfsPoolAttributes | undefined, E, R>,
+) =>
+  Effect.gen(function* () {
+    const existing = yield* read(props);
+    if (existing !== undefined) return existing;
+
+    if (props.devices === undefined || props.raidlevel === undefined) {
+      return yield* Effect.die(
+        new Error(
+          `${props.node}/${props.name}: this is an adopt-only declaration (no \`devices\` or ` +
+            '`raidlevel`) and the pool is not there to adopt. An adopt-only Proxmox.ZfsPool never ' +
+            'creates -- declare both fields for a pool this resource should build, or point this ' +
+            'declaration at a pool that already exists on this node.',
+        ),
+      );
+    }
+
+    /**
+     * ⛔ FOUND BY ADVERSARIAL REVIEW, 2026-09-24 — `diff` NEVER RUNS FOR A GENUINELY FIRST-EVER
+     *   DECLARATION. Upstream `Plan.ts` routes a brand-new resource (`oldState === undefined`)
+     *   straight to `action: 'create'` without ever calling `provider.diff` — so `zfs-pool.ts`'s
+     *   own `guardForm` call (which checks THIS SAME form) never runs for that plan, and this was
+     *   THE ONLY WRITE PATH IN THE FAMILY WITH NO VENDOR CHECK AT ALL, before or after this
+     *   migration. `ceph-pool.ts`'s own hand-written `reconcile` already re-runs its create guard
+     *   for exactly this reason (an ADOPTED row's `diff` answer is discarded by Plan.ts too); this
+     *   is the same fix for this family. A malformed `ashift` or `draid-config` is now refused
+     *   here, before the POST, rather than reaching the wire and refused only by PVE itself.
+     */
+    yield* guardForm(zfsPoolCreateEndpoint(props), asForm(createForm(props)), true);
+
+    const upid = yield* runPve(
+      props.target,
+      'provision',
+      true,
+      nodes.createNodeDiskZfs(toDistilledCreate(props)),
+    );
+
+    const settle = (attempts: number): Effect.Effect<ZfsPoolAttributes | undefined, E, R> =>
+      Effect.gen(function* () {
+        const live = yield* read(props);
+        if (live !== undefined || attempts <= 0) return live;
+        yield* Effect.sleep('2 seconds');
+        return yield* settle(attempts - 1);
+      });
+
+    const after = yield* settle(SETTLE_ATTEMPTS);
+    if (after === undefined) {
+      return yield* Effect.die(
+        new Error(
+          `nodes/${props.node}/disks/zfs/${props.name}: POST returned ${text(upid, '(no UPID)')} ` +
+            'but the pool has not appeared. That POST only forks a `zfscreate` worker, so the task ' +
+            `holds the real error -- read it with \`pvesh get /nodes/${props.node}/tasks/<upid>/log\`. ` +
+            'NOTHING WAS RETRIED AND NOTHING WAS CLEANED UP: if the worker reached `zpool create`, ' +
+            'the declared devices have already been written to. DO NOT RE-RUN THIS DEPLOY BEFORE ' +
+            'READING THAT LOG: `read` cannot tell "the worker is still running" from "the pool is ' +
+            'genuinely gone", so a re-run this soon can POST a SECOND `zpool create` at the SAME ' +
+            'devices while the first one is still mid-write -- confirm the task finished (one way ' +
+            'or the other) before trying again.',
+        ),
+      );
+    }
+    return after;
+  });
+
+/**
+ * ⛔ `DELETE /nodes/{node}/disks/zfs/{name}` RUNS `zpool destroy` AND THE DATASETS GO WITH IT. Per
+ *   S14 (alchemy-provider-standard), it is implemented rather than stubbed — a `delete` that
+ *   silently does nothing lies to whoever reads the plan — and what keeps an ordinary removed
+ *   declaration from reaching it is the resource's `defaultRemovalPolicy: 'retain'` (zfs-pool.ts):
+ *   an orphaned pool is forgotten, not destroyed, unless a caller opts in with
+ *   `.pipe(RemovalPolicy.destroy())`. See the corrected header in zfs-pool.ts.
+ *
+ * ⚠️ `cleanup-config`/`cleanup-disks` ARE NOT SENT. The first would additionally remove the PVE
+ *   storage entry pointing at this pool, which is a different object with its own resource
+ *   (`Proxmox.Storage`); one resource reaching over to delete another's is how a stack ends up with
+ *   state describing something that is gone. Neither is offered as a prop, for the same reason.
+ */
+export const destroyPool = (props: ZfsPoolProps) =>
+  runPve(
+    props.target,
+    'provision',
+    true,
+    nodes.deleteNodeDiskZfs({ name: props.name, node: props.node }),
+  );