@homeflare/alchemy 0.21.0 → 0.23.0

package/src/proxmox/generated/pve/cluster-sdn-fabrics.ts

@@ -29,7 +29,7 @@ export type ClusterSdnFabricsFabricGetReturn = readonly ({
   'lock-token'?: string;
   persistent_keepalive?: number;
   protocol: 'openfabric' | 'ospf' | 'wireguard' | 'bgp';
-  redistribute: readonly unknown[];
+  redistribute?: readonly string[];
   route_filter?: string;
 } & Record<string, unknown>)[];
 
@@ -45,7 +45,7 @@ export type ClusterSdnFabricsFabricPostParams = {
   'lock-token'?: string;
   persistent_keepalive?: `${number}`;
   protocol: 'openfabric' | 'ospf' | 'wireguard' | 'bgp';
-  redistribute: readonly string[];
+  redistribute?: readonly string[];
   route_filter?: string;
 };
 /** POST /cluster/sdn/fabrics/fabric — `data` payload after client unwrap. */
@@ -63,7 +63,7 @@ export type ClusterSdnFabricsFabricIdGetReturn = {
   'lock-token'?: string;
   persistent_keepalive?: number;
   protocol: 'openfabric' | 'ospf' | 'wireguard' | 'bgp';
-  redistribute: readonly unknown[];
+  redistribute?: readonly string[];
   route_filter?: string;
 } & Record<string, unknown>;
 
@@ -71,7 +71,17 @@ export type ClusterSdnFabricsFabricIdGetReturn = {
 export type ClusterSdnFabricsFabricIdPutParams = {
   area?: string;
   csnp_interval?: `${number}`;
-  delete: readonly string[];
+  delete?: readonly (
+    | 'ip_prefix'
+    | 'ip6_prefix'
+    | 'hello_interval'
+    | 'csnp_interval'
+    | 'route_filter'
+    | 'redistribute'
+    | 'route_map_in'
+    | 'route_map_out'
+    | 'area'
+    | 'persistent_keepalive')[];
   digest?: string;
   hello_interval?: `${number}`;
   ip6_prefix?: string;
@@ -79,7 +89,7 @@ export type ClusterSdnFabricsFabricIdPutParams = {
   'lock-token'?: string;
   persistent_keepalive?: `${number}`;
   protocol: 'openfabric' | 'ospf' | 'wireguard' | 'bgp';
-  redistribute: readonly string[];
+  redistribute?: readonly string[];
   route_filter?: string;
 };
 /** PUT /cluster/sdn/fabrics/fabric/{id} — `data` payload after client unwrap. */
@@ -96,7 +106,7 @@ export type ClusterSdnFabricsNodeGetReturn = readonly ({
   digest?: string;
   endpoint?: string;
   fabric_id: string;
-  interfaces: readonly unknown[];
+  interfaces?: readonly string[];
   ip?: string;
   ip6?: string;
   'lock-token'?: string;
@@ -115,7 +125,7 @@ export type ClusterSdnFabricsNodeFabric_idGetReturn = readonly ({
   digest?: string;
   endpoint?: string;
   fabric_id: string;
-  interfaces: readonly unknown[];
+  interfaces?: readonly string[];
   ip?: string;
   ip6?: string;
   'lock-token'?: string;
@@ -131,7 +141,7 @@ export type ClusterSdnFabricsNodeFabric_idPostParams = {
   allowed_ips?: readonly string[];
   digest?: string;
   endpoint?: string;
-  interfaces: readonly string[];
+  interfaces?: readonly string[];
   ip?: string;
   ip6?: string;
   'lock-token'?: string;
@@ -150,7 +160,7 @@ export type ClusterSdnFabricsNodeFabric_idNode_idGetReturn = {
   digest?: string;
   endpoint?: string;
   fabric_id: string;
-  interfaces: readonly unknown[];
+  interfaces?: readonly string[];
   ip?: string;
   ip6?: string;
   'lock-token'?: string;
@@ -164,10 +174,10 @@ export type ClusterSdnFabricsNodeFabric_idNode_idGetReturn = {
 /** PUT /cluster/sdn/fabrics/node/{fabric_id}/{node_id} — form/query parameters (path segments omitted). */
 export type ClusterSdnFabricsNodeFabric_idNode_idPutParams = {
   allowed_ips?: readonly string[];
-  delete: readonly string[];
+  delete?: readonly ('interfaces' | 'ip' | 'ip6' | 'allowed_ips' | 'endpoint' | 'peers')[];
   digest?: string;
   endpoint?: string;
-  interfaces: readonly string[];
+  interfaces?: readonly string[];
   ip?: string;
   ip6?: string;
   'lock-token'?: string;
@@ -197,7 +207,7 @@ export type ClusterSdnFabricsAllGetReturn = {
     'lock-token'?: string;
     persistent_keepalive?: number;
     protocol: 'openfabric' | 'ospf' | 'wireguard' | 'bgp';
-    redistribute: readonly unknown[];
+    redistribute?: readonly string[];
     route_filter?: string;
   } & Record<string, unknown>)[];
   nodes: readonly ({
@@ -205,7 +215,7 @@ export type ClusterSdnFabricsAllGetReturn = {
     digest?: string;
     endpoint?: string;
     fabric_id: string;
-    interfaces: readonly unknown[];
+    interfaces?: readonly string[];
     ip?: string;
     ip6?: string;
     'lock-token'?: string;

package/src/proxmox/index.test.ts

@@ -7,6 +7,9 @@
  * ★ CephDaemon, CephFs and CephOsd are Resources since 2026-09-22: adopt-only by shape and retain
  *   on destroy (ceph-adopt.test.ts). ⛔ CephFlag stays Provider-only: a declared flag reasserts a
  *   maintenance toggle on every deploy (ceph-flag.ts).
+ * ★ ApiToken and ZfsPool are Resources since 2026-09-23, decision 9: ApiToken metadata-only,
+ *   ZfsPool adopt-only when `devices`/`raidlevel` are left undeclared (api-token-adopt.test.ts,
+ *   zfs-pool-adopt.test.ts).
  */
 import { expect, test } from 'bun:test';
 import { PbsDatastore, ProxmoxStorage } from './index.ts';
@@ -21,6 +24,7 @@ const resourceExports = [
   'PbsSyncJob',
   'PbsVerifyJob',
   'ProxmoxAcl',
+  'ProxmoxApiToken',
   'ProxmoxBackupJob',
   'ProxmoxCephDaemon',
   'ProxmoxCephFs',
@@ -39,6 +43,7 @@ const resourceExports = [
   'ProxmoxSdnZone',
   'ProxmoxStorage',
   'ProxmoxUser',
+  'ProxmoxZfsPool',
 ] as const;
 
 test('control-plane Resource constructors are on the public barrel', () => {
@@ -60,7 +65,5 @@ test('QEMU, NIC apply and the Ceph flag stay Provider-only', () => {
   expect(src).not.toMatch(/export \{ ProxmoxVm[, }]/);
   expect(src).not.toMatch(/export \{ ProxmoxNodeNetwork[, }]/);
   expect(src).not.toMatch(/export \{ ProxmoxNetworkApply[, }]/);
-  expect(src).not.toMatch(/export \{ ProxmoxApiToken[, }]/);
-  expect(src).not.toMatch(/export \{ ProxmoxZfsPool[, }]/);
   expect(src).not.toMatch(/export \{ ProxmoxCephFlag[, }]/);
 });

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