@homeflare/alchemy 0.22.0 → 0.23.0

package/src/proxmox/index.ts

@@ -33,12 +33,19 @@
  *   including one run for an unrelated resource in the middle of a maintenance window
  *   (ceph-flag.ts has the whole argument). A stack that wants a flag set must reach for the
  *   Provider deliberately; the barrel does not offer the sentence by default.
+ * ★ `ProxmoxApiToken` AND `ProxmoxZfsPool` JOINED 2026-09-23, PER TIM'S DECISION 9: the kit builds
+ *   an ApiToken export that is metadata-only (`comment`/`expire`/`privsep` — `reconcile` refuses
+ *   to mint a secret it cannot store, api-token.ts) and a ZfsPool export that is adopt-only when
+ *   `devices`/`raidlevel` are left undeclared (for a pool PVE's own schema cannot fully describe,
+ *   such as a stripe — zfs-pool.ts). Neither can CREATE what it does not already have devices and
+ *   a raidlevel, or a live token, to build from. Pinned by api-token-adopt.test.ts and
+ *   zfs-pool-adopt.test.ts.
  * ★ Anything else unlisted is still reachable by path if you genuinely need
  *   it — that is a deliberate, visible act rather than an accident of barrelling.
  */
 export { ProxmoxAcl, ProxmoxAclProvider } from './acl.ts';
 export { type AlertmanagerBodyOptions, alertmanagerAlertBody } from './alertmanager-body.ts';
-export { ProxmoxApiTokenProvider } from './api-token.ts';
+export { ProxmoxApiToken, ProxmoxApiTokenProvider } from './api-token.ts';
 export { ProxmoxBackupJob, ProxmoxBackupJobProvider } from './backup-job.ts';
 export { ProxmoxCephDaemon, ProxmoxCephDaemonProvider } from './ceph-daemon.ts';
 export { ProxmoxCephFlagProvider } from './ceph-flag.ts';
@@ -105,4 +112,4 @@ export { ProxmoxSdnZone, ProxmoxSdnZoneProvider } from './sdn-zone.ts';
 export { ProxmoxStorage, ProxmoxStorageProvider } from './storage.ts';
 export { ProxmoxUser, ProxmoxUserProvider } from './user.ts';
 export { type FromEnv } from '../secrets/write-only.ts';
-export { ProxmoxZfsPoolProvider } from './zfs-pool.ts';
+export { ProxmoxZfsPool, ProxmoxZfsPoolProvider } from './zfs-pool.ts';

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

@@ -0,0 +1,141 @@
+/**
+ * `Proxmox.ZfsPool` adopt-only mode (decision 9, 2026-09-23) through Alchemy's own Plan and
+ * Apply, over a fake cluster. Adopt-only means `devices` and `raidlevel` are both left
+ * undeclared — 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 (decision 14 accepts it as-is).
+ *
+ * 🔴 THE BUG THIS PINS (measured 2026-09-23, before this change). `createForm` called
+ *   `props.devices.join(',')` unconditionally, so the plan-time create guard — which evaluates
+ *   `spec.createForm(props)` eagerly, before it even looks at `presence` (resource-guard.ts) —
+ *   threw `TypeError: Cannot read properties of undefined (reading 'join')` for every adopt-only
+ *   declaration, before the pool was ever read. Reverting `createForm`/`zfsPoolEndpoint` in
+ *   zfs-pool-write.ts locally reproduces it: the first test below dies with that TypeError
+ *   instead of adopting.
+ * ⛔ WHAT A MISTAKE HERE WOULD COST ON A REAL CLUSTER: a POST that reached the wire without
+ *   `devices`/`raidlevel` would be refused by PVE's own schema, but only after leaving this
+ *   process; a DELETE reaching the wire on an undeclared line would run `zpool destroy`. So the
+ *   no-create and no-delete tests both end on `fake.writes()` empty, and the mutation row proves
+ *   the harness can still see a write when one is meant to happen.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { FAKE_TARGET, type PveCall, fakePve, withoutBao } from './fake-pve.ts';
+import { ProxmoxZfsPool, ProxmoxZfsPoolProvider, type ZfsRaidLevel } from './zfs-pool.ts';
+
+/** rpool on three nodes, plus rpool and a stripe `speed` on a fourth — n1's shape, placeholders. */
+const FIVE: readonly (readonly [string, string])[] = [
+  ['node-b', 'rpool'],
+  ['node-c', 'rpool'],
+  ['node-d', 'rpool'],
+  ['node-e', 'rpool'],
+  ['node-e', 'speed'],
+];
+
+const key = (node: string, name: string) => `${node}/${name}`;
+
+/** Only the fields `zfs-pool-spec.ts`'s `attributes` reads; `name` non-empty is what "found" means. */
+const poolAnswer = (name: string): Record<string, unknown> => ({
+  children: [],
+  errors: 'No known data errors',
+  name,
+  state: 'ONLINE',
+});
+
+/** A cluster holding exactly `present`; a DELETE removes its key, as `zpool destroy` would. */
+const cluster = (present: Set<string>) =>
+  fakePve((call: PveCall) => {
+    const hit = /^nodes\/([^/]+)\/disks\/zfs\/([^/]+)$/.exec(call.path);
+    if (hit === null) return undefined;
+    const [, node = '', name = ''] = hit;
+    if (call.method === 'GET') return present.has(key(node, name)) ? poolAnswer(name) : undefined;
+    if (call.method === 'DELETE') {
+      present.delete(key(node, name));
+      return null;
+    }
+    return undefined;
+  });
+
+/** ⚠️ NO `devices`/`raidlevel` — the whole point of this file. */
+const adoptOnly = (node: string, name: string) =>
+  ProxmoxZfsPool(`${node}-${name}`, { name, node, target: FAKE_TARGET });
+
+const allFive = () => Effect.all(FIVE.map(([node, name]) => adoptOnly(node, name)));
+const presentFive = () => new Set(FIVE.map(([node, name]) => key(node, name)));
+
+const engineFor = (fake: ReturnType<typeof cluster>) =>
+  engineOver(ProxmoxZfsPoolProvider().pipe(Layer.provideMerge(fake.layer)));
+
+describe('adopting an adopt-only ZfsPool declaration', () => {
+  test('rpool on three nodes, plus rpool and a stripe speed on a fourth: noop, adopted, no writes', async () => {
+    const fake = cluster(presentFive());
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const report = await engine.verify(allFive());
+      expect(report.rows).toHaveLength(5);
+      for (const row of report.rows) {
+        expect(row).toMatchObject({ changed: [], diff: 'noop', ok: true, planned: 'adopted' });
+      }
+      const planned = await engine.deploy(allFive());
+      expect(new Set(Object.values(planned))).toEqual(new Set(['adopted']));
+      expect(Object.keys(planned)).toHaveLength(5);
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('undeclaring all five drops the state rows and sends no DELETE (retain is the default)', async () => {
+    const fake = cluster(presentFive());
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await engine.deploy(allFive());
+      expect(engine.stored()).toContain('node-b-rpool');
+      expect(await engine.deploy(Effect.void)).toEqual({});
+      expect(engine.stored()).not.toContain('"node-b-rpool"');
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('an adopt-only pool that is absent: the deploy refuses, and writes nothing', async () => {
+    const fake = cluster(new Set());
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await expect(engine.deploy(adoptOnly('node-b', 'rpool'))).rejects.toBeDefined();
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('an adopted pool that vanishes: the next plan refuses at the create guard, no writes', async () => {
+    const present = new Set([key('node-b', 'rpool')]);
+    const fake = cluster(present);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await engine.deploy(adoptOnly('node-b', 'rpool'));
+      present.delete(key('node-b', 'rpool')); // the pool is gone by the next deploy
+      await expect(engine.deploy(adoptOnly('node-b', 'rpool'))).rejects.toBeDefined();
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  /**
+   * ⛔ THE ONE THAT MATTERS MOST — the corrected header in zfs-pool.ts, proved. `retain` is why a
+   *   dropped declaration above sent no DELETE; this shows the harness still sees a write when
+   *   one is meant to happen, the way ceph-adopt.test.ts's mutation row does.
+   */
+  test('RemovalPolicy.destroy() then undeclaring sends exactly one DELETE', async () => {
+    const fake = cluster(new Set([key('node-b', 'rpool')]));
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await engine.deploy(adoptOnly('node-b', 'rpool').pipe(RemovalPolicy.destroy()));
+      await engine.deploy(Effect.void);
+    });
+    expect(fake.writes()).toEqual(['DELETE nodes/node-b/disks/zfs/rpool']);
+  });
+
+  test('ZfsRaidLevel has no stripe: rejected at compile time, not just at runtime', () => {
+    // @ts-expect-error 'stripe' is not in PVE's raidlevel enum (generated/pve.ts, decision 9)
+    const r: ZfsRaidLevel = 'stripe';
+    expect(String(r)).toBe('stripe');
+  });
+});

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

@@ -0,0 +1,76 @@
+/**
+ * The `PveSpec` for `Proxmox.ZfsPool`: where a pool lives, what its GET reports, and the vendor
+ * endpoint its create form is checked against.
+ *
+ * ★ SPLIT OUT OF zfs-pool.ts TO KEEP THAT FILE UNDER THE 250-LINE CAP, and the seam is the same
+ *   one metric-server-form.ts and zfs-pool-write.ts already cut on: zfs-pool.ts answers "what is
+ *   a zpool and when has it changed", this file answers "what PVE's own GET/{node}/disks/zfs
+ *   collection and item say, read into that shape". `leafDevices` moved with `spec` because it
+ *   exists for exactly one field of `spec.attributes` and nothing else in this package calls it.
+ *
+ * ⚠️ THE `import type` BACK TO zfs-pool.ts IS A CYCLE ON PAPER ONLY — type-only, erased before
+ *   anything runs, so the resource's public shape stays in the file that declares the resource.
+ *   Same reasoning as zfs-pool-write.ts.
+ */
+import type { PveSpec } from './resource.ts';
+import { text } from './values.ts';
+import { createForm, zfsPoolEndpoint } from './zfs-pool-write.ts';
+import type { ZfsPoolAttributes, ZfsPoolProps } from './zfs-pool.ts';
+
+/**
+ * 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 !== '');
+      })
+    : [];
+
+export const spec: PveSpec<ZfsPoolProps, ZfsPoolAttributes> = {
+  /**
+   * ⚠️ `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.
+   */
+  attributes: (live, props) => {
+    // ⚠️ A detail answer with no `name` is not a pool. `name` is non-optional in PVE's schema, so
+    //   this is a shape check rather than a default — and "absent" is the honest reading of a
+    //   reply that does not describe the object that was asked for.
+    if (text(live['name']) === '') return undefined;
+    return {
+      devices: leafDevices(live['children']).join(','),
+      errors: text(live['errors'], 'unknown'),
+      name: props.name,
+      node: props.node,
+      state: text(live['state'], 'unknown'),
+    };
+  },
+  collection: (props) => `nodes/${props.node}/disks/zfs`,
+  createForm,
+  /** ★ A function of props, not the constant — see the ★ on `zfsPoolEndpoint` (zfs-pool-write.ts). */
+  endpoint: zfsPoolEndpoint,
+  /**
+   * ⛔ IT ALWAYS ANSWERS TRUE, AND THAT IS THE POINT OF THIS FILE. A pool that is there under the
+   *   declared name on the declared node IS the declaration, because there is nothing else the two
+   *   can be compared on: every create parameter is write-only (see the ⛔ in zfs-pool.ts's header)
+   *   and everything the read does return is telemetry that moves by itself. So declaring what is
+   *   live plans as `noop` — the only honest answer available, and the one the live cluster needs:
+   *   `rpool` exists on node-b, node-c and node-d with nothing about its construction readable.
+   *   ⛔ ANYTHING ADDED HERE IS A REPLACE, NOT AN UPDATE. `updateForm` is omitted because PVE has
+   *     no PUT, so `resource.ts` turns a false into `{action:'replace'}` — delete then create — on
+   *     a family whose delete is `zpool destroy`. A comparison added here would be one plan away
+   *     from destroying a pool over a field it cannot even read back. If a future PVE grows a PUT,
+   *     add `updateForm` FIRST and only then consider comparing what that PUT accepts.
+   */
+  matches: () => true,
+  path: (props) => `nodes/${props.node}/disks/zfs/${props.name}`,
+};

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

@@ -38,20 +38,51 @@ import type { ZfsPoolAttributes, ZfsPoolProps } from './zfs-pool.ts';
  *   declaration asked for, and this is the one call that writes to physical disks.
  */
 /**
- * The vendor rules the create form is checked against at plan time.
+ * The vendor rules a FULL declaration's create form is checked against at plan time.
  *
  * ⛔ HERE RATHER THAN INLINE IN zfs-pool.ts BECAUSE THAT FILE IS ALREADY OVER THE 250-LINE CAP,
  *   and a `pve:POST …` literal has to live in a non-test source file for the generator to table
- *   it at all. The spec imports it on the line it already imports `createForm` from.
+ *   it at all. zfs-pool-spec.ts imports it on the line it already imports `createForm` from.
  * ⚠️ NO UPDATE KEY: PVE registers no PUT under `/nodes/{node}/disks/zfs`, which is exactly why
  *   the spec declares no `updateForm` and a changed prop is a REPLACE.
+ * ⚠️ `spec.endpoint` DOES NOT RETURN THIS CONSTANT DIRECTLY — see the ★ on `zfsPoolEndpoint`
+ *   below, and the ⛔ on `devices`/`raidlevel` in zfs-pool.ts (decision 9, 2026-09-23).
  */
 export const ZFS_POOL_ENDPOINT: EndpointPair = { create: 'pve:POST /nodes/{node}/disks/zfs' };
 
+/**
+ * ★ `PveSpec['endpoint']` AS A FUNCTION OF PROPS, THE WAY notification-target.ts AND
+ *   ceph-daemon.ts ALREADY DO IT FOR A DIFFERENT REASON (resource-spec.ts's ⚠️ on that field).
+ *   Here the reason is decision 9's adopt-only mode: `guardCreate` runs on the FIRST plan of
+ *   ANY declaration (resource.ts `ops.diff`, `output === undefined` branch) and checks the
+ *   create form's REQUIRED fields whenever `endpoint.create` resolves to a key — and PVE marks
+ *   both `devices` and `raidlevel` required (measured, codegen/constraints's `pve-nodes-disks`
+ *   row). An adopt-only declaration deliberately omits both, so returning the real key there
+ *   would refuse a MATCHING adoption at plan time, before `read` ever ran — exactly the gap
+ *   `guardCreate`/`guardUpdate` being exported (resource.ts's ★) says this family must not fall
+ *   through. Returning `{}` (no `create` key) makes `guardCreate` a no-op (`constraint-guard.ts`:
+ *   `create === undefined ? Effect.void : …`) for an adopt-only declaration, while a FULL one
+ *   (`devices` and `raidlevel` both present) is checked exactly as before.
+ * ⚠️ 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 zfsPoolEndpoint = (props: ZfsPoolProps): EndpointPair =>
+  props.devices === undefined || props.raidlevel === undefined ? {} : ZFS_POOL_ENDPOINT;
+
+/**
+ * ⚠️ 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: `props.devices.join(',')` on an undefined `devices` is exactly the
+ *   `TypeError` the plan-time guard hit before this change, because `guardCreate` evaluates
+ *   `spec.createForm(props)` eagerly (resource-guard.ts) — before it even looks at `presence`.
+ */
 export const createForm = (props: ZfsPoolProps): Record<string, string> => ({
-  devices: props.devices.join(','),
+  ...(props.devices === undefined ? {} : { devices: props.devices.join(',') }),
   name: props.name,
-  raidlevel: props.raidlevel,
+  ...(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'] }),
@@ -84,6 +115,17 @@ const SETTLE_ATTEMPTS = 30;
  * ⚠️ SHORT POLLS WITH A HARD CAP, NOT ONE LONG WAIT. `read` cannot tell "not yet" from "forbidden"
  *   — both are `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.
+ *
+ * ⛔ 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). `zfsPoolEndpoint` 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. MEASURED without it: a
+ *   tolerant `createForm` sends `POST … {name: "rpool"}` with no `devices`/`raidlevel`, which PVE's
+ *   own schema would 400 on eventually, but only after the request left this process; refusing
+ *   here is the same `Effect.die` idiom as every other refusal in this package, and it costs
+ *   nothing this pool did not already lack.
  */
 export const createPool = <E, R>(
   props: ZfsPoolProps,
@@ -95,6 +137,17 @@ export const createPool = <E, R>(
     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.',
+        ),
+      );
+    }
+
     const upid = yield* pve<string>(
       props.target,
       'provision',
@@ -127,11 +180,12 @@ export const createPool = <E, R>(
   });
 
 /**
- * ⛔ `DELETE /nodes/{node}/disks/zfs/{name}` RUNS `zpool destroy` AND THE DATASETS GO WITH IT.
- *   It is implemented rather than stubbed, because a `delete` that silently does nothing lies to
- *   whoever reads the plan. What keeps a deleted line from destroying a pool is the resource's
- *   `defaultRemovalPolicy: 'retain'` above — an orphaned pool is forgotten, not destroyed, and a
- *   caller who means it says `.pipe(RemovalPolicy.destroy())`.
+ * ⛔ `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` IS NOT SENT. It would additionally remove the PVE storage entry pointing
  *   at this pool, which is a different object with its own resource (`Proxmox.Storage`); one

package/src/proxmox/zfs-pool.ts

@@ -6,20 +6,22 @@
  *   moment the worker runs. Every other decision in this file follows from that one sentence, and
  *   each of them is written out below rather than left to be inferred.
  *
- * ⛔ DESTROY IS REFUSED. `delete` MAKES NO API CALL — removing this resource from a stack leaves
- *   the zpool and its data exactly where they are, and Alchemy simply forgets about them. The
- *   asymmetry is the whole argument: an ORPHANED pool is recoverable (declare it again, or destroy
- *   it by hand once a human has looked at which disks are in it), a DESTROYED pool is not. Alchemy
- *   deletes for reasons that have nothing to do with anybody intending it — a line removed from a
- *   stack file, a resource renamed so the old id is dropped, a whole stack torn down by the wrong
- *   command, a replace triggered by a prop nobody meant to touch. Handing `zpool destroy` to any
- *   of those is not a feature. MEASURED in the node's own source: the DELETE handler forks
- *   `zfsremove`, which runs `zpool destroy <name>` unconditionally, and with `cleanup-disks` then
- *   calls `wipe_blockdev` on every member. Neither flag is offered as a prop, because there is no
- *   call here for them to reach.
- *   ★ THE OPERATOR'S PATH IS `pvesh delete /nodes/<node>/disks/zfs/<name>`, typed by a person who
- *     has just looked at the pool. Do not "complete the CRUD" by wiring `delete` to `ops.destroy`:
- *     that one line turns a text edit into an unrecoverable one.
+ * ⛔ ★ CORRECTED 2026-09-23 — THIS PARAGRAPH PREVIOUSLY SAID "DESTROY IS REFUSED" AND "`delete`
+ *   MAKES NO API CALL". THAT WAS FALSE: MEASURED against this file's own `handlers.delete` below,
+ *   which calls `destroyPool`, which sends `DELETE /nodes/{node}/disks/zfs/{name}` — the node's
+ *   own source forks `zfsremove`, which runs `zpool destroy <name>` unconditionally, and with
+ *   `cleanup-disks` then calls `wipe_blockdev` on every member (neither flag is offered as a prop,
+ *   because there is no call here for them to reach). `delete` is FULLY IMPLEMENTED, per S14
+ *   (alchemy-provider-standard): a `delete` that silently does nothing lies to whoever reads the
+ *   plan. What actually keeps an ordinary removed declaration from reaching it is
+ *   `defaultRemovalPolicy: 'retain'` below — Alchemy SKIPS `provider.delete` entirely for an
+ *   orphaned or destroyed resource under `retain`, so the state row drops and the zpool and its
+ *   data are left exactly where they are. The asymmetry is still the whole argument: an ORPHANED
+ *   pool is recoverable (declare it again, or destroy it by hand once a human has looked at which
+ *   disks are in it), a DESTROYED pool is not — which is why `retain` is the default rather than a
+ *   documented caution, and why `delete` runs only for a caller who opts in by name with
+ *   `.pipe(RemovalPolicy.destroy())`. See the ★ on `defaultRemovalPolicy` in resource-spec.ts, and
+ *   zfs-pool-adopt.test.ts's mutation row, which pins exactly one DELETE reaching the fake cluster.
  *
  * ⛔ 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`
@@ -47,7 +49,8 @@
  * ⚠️ 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 is in the ⛔ on `createPool` in zfs-pool-create.ts.
+ *   detail, and the adopt-only refusal decision 9 adds, are both in `createPool` in
+ *   zfs-pool-write.ts.
  *
  * ⚠️ 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
@@ -57,29 +60,23 @@
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import {
-  type PveRequirements,
-  type PveSpec,
-  type WithTarget,
-  pveHandlers,
-  pveOperations,
-} from './resource.ts';
-import { text } from './values.ts';
-import { ZFS_POOL_ENDPOINT, createForm, createPool, destroyPool } from './zfs-pool-write.ts';
+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';
 
-/** PVE's layouts. ⚠️ Each has a minimum disk count PVE enforces, and `raid10` needs an even one. */
-export type ZfsRaidLevel =
-  | 'single'
-  | 'mirror'
-  | 'raid10'
-  | 'raidz'
-  | 'raidz2'
-  | 'raidz3'
-  | 'draid'
-  | 'draid2'
-  | 'draid3';
+/**
+ * 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']>;
 
-export type ZfsCompression = 'on' | 'off' | 'gzip' | 'lz4' | 'lzjb' | 'zle' | 'zstd';
+/** Generated the same way, from `NodesNodeDisksZfsPostParams['compression']`. */
+export type ZfsCompression = NonNullable<NodesNodeDisksZfsPostParams['compression']>;
 
 /**
  * ⛔ THERE IS NO `add_storage`, `cleanup-config` OR `cleanup-disks` PROP, AND THAT IS NOT AN
@@ -112,9 +109,19 @@ export interface ZfsPoolProps extends WithTarget {
    *   `csv` sorts, and sorting this list silently re-pairs the mirrors into a different pool.
    * ⚠️ PVE's only guard is `assert_disk_unused`, i.e. its own `disk_is_used` over the same `used`
    *   column the Disks view shows. A blank disk it considers free is wiped with no confirmation.
+   *
+   * ⛔ OPTIONAL SINCE DECISION 9 (2026-09-23), AND OMITTING IT MEANS SOMETHING SPECIFIC: leaving
+   *   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
+   *   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
+   *   of the two is refused the same way, since PVE's POST requires both.
    */
-  devices: readonly string[];
-  raidlevel: ZfsRaidLevel;
+  devices?: readonly string[];
+  raidlevel?: ZfsRaidLevel;
   /**
    * Sector size exponent, 9–16, PVE default 12.
    *
@@ -174,63 +181,6 @@ export const ProxmoxZfsPool = Resource<ProxmoxZfsPool>('Proxmox.ZfsPool', {
   defaultRemovalPolicy: 'retain',
 });
 
-/**
- * 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.
- */
-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 !== '');
-      })
-    : [];
-
-const spec: PveSpec<ZfsPoolProps, ZfsPoolAttributes> = {
-  /**
-   * ⚠️ `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.
-   */
-  attributes: (live, props) => {
-    // ⚠️ A detail answer with no `name` is not a pool. `name` is non-optional in PVE's schema, so
-    //   this is a shape check rather than a default — and "absent" is the honest reading of a
-    //   reply that does not describe the object that was asked for.
-    if (text(live['name']) === '') return undefined;
-    return {
-      devices: leafDevices(live['children']).join(','),
-      errors: text(live['errors'], 'unknown'),
-      name: props.name,
-      node: props.node,
-      state: text(live['state'], 'unknown'),
-    };
-  },
-  collection: (props) => `nodes/${props.node}/disks/zfs`,
-  createForm,
-  endpoint: ZFS_POOL_ENDPOINT,
-  /**
-   * ⛔ IT ALWAYS ANSWERS TRUE, AND THAT IS THE POINT OF THIS FILE. A pool that is there under the
-   *   declared name on the declared node IS the declaration, because there is nothing else the two
-   *   can be compared on: every create parameter is write-only (see the ⛔ in the header) and
-   *   everything the read does return is telemetry that moves by itself. So declaring what is live
-   *   plans as `noop` — the only honest answer available, and the one the live cluster needs:
-   *   `rpool` exists on node-b, node-c and node-d with nothing about its construction readable.
-   *   ⛔ ANYTHING ADDED HERE IS A REPLACE, NOT AN UPDATE. `updateForm` is omitted because PVE has
-   *     no PUT, so `resource.ts` turns a false into `{action:'replace'}` — delete then create — on
-   *     a family whose delete is `zpool destroy`. A comparison added here would be one plan away
-   *     from destroying a pool over a field it cannot even read back. If a future PVE grows a PUT,
-   *     add `updateForm` FIRST and only then consider comparing what that PUT accepts.
-   */
-  matches: () => true,
-  path: (props) => `nodes/${props.node}/disks/zfs/${props.name}`,
-};
-
 const ops = pveOperations(spec);
 
 /**