@homeflare/alchemy 0.22.0 → 0.23.0

package/dist/proxmox/zfs-pool-spec.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 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 declare const leafDevices: (children: unknown) => string[];
+export declare const spec: PveSpec<ZfsPoolProps, ZfsPoolAttributes>;
+//# sourceMappingURL=zfs-pool-spec.d.ts.map

package/dist/proxmox/zfs-pool-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zfs-pool-spec.d.ts","sourceRoot":"","sources":["../../src/proxmox/zfs-pool-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,aAAc,OAAO,KAAG,MAAM,EAO9C,CAAC;AAET,eAAO,MAAM,IAAI,EAAE,OAAO,CAAC,YAAY,EAAE,iBAAiB,CAuCzD,CAAC"}

package/dist/proxmox/zfs-pool-write.d.ts

@@ -35,15 +35,44 @@ 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 declare const ZFS_POOL_ENDPOINT: EndpointPair;
+/**
+ * ★ `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 declare const zfsPoolEndpoint: (props: ZfsPoolProps) => EndpointPair;
+/**
+ * ⚠️ 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 declare const createForm: (props: ZfsPoolProps) => Record<string, string>;
 /**
  * Create the pool if it is absent, and otherwise leave it completely alone.
@@ -69,14 +98,26 @@ export declare const createForm: (props: ZfsPoolProps) => Record<string, string>
  * ⚠️ 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 declare const createPool: <E, R>(props: ZfsPoolProps, collection: string, path: string, read: (props: ZfsPoolProps) => Effect.Effect<ZfsPoolAttributes | undefined, E, R>) => Effect.Effect<ZfsPoolAttributes, E | Error, R | import("effect/unstable/http/HttpClient").HttpClient>;
 /**
- * ⛔ `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/dist/proxmox/zfs-pool-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zfs-pool-write.d.ts","sourceRoot":"","sources":["../../src/proxmox/zfs-pool-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAA6D,CAAC;AAE9F,eAAO,MAAM,UAAU,UAAW,YAAY,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAOpE,CAAC;AAKH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,SACtB,YAAY,cACP,MAAM,QACZ,MAAM,QACN,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC,MAAM,CAAC,iBAAiB,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,0GAmC/E,CAAC;AAEL;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,SAAU,YAAY,QAAQ,MAAM,wFACb,CAAC"}
+{"version":3,"file":"zfs-pool-write.d.ts","sourceRoot":"","sources":["../../src/proxmox/zfs-pool-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAA6D,CAAC;AAE9F;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe,UAAW,YAAY,KAAG,YACiC,CAAC;AAExF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,UAAW,YAAY,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAOpE,CAAC;AAKH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,SACtB,YAAY,cACP,MAAM,QACZ,MAAM,QACN,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC,MAAM,CAAC,iBAAiB,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,0GA8C/E,CAAC;AAEL;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,SAAU,YAAY,QAAQ,MAAM,wFACb,CAAC"}

package/dist/proxmox/zfs-pool.d.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
@@ -56,10 +59,19 @@
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
+import type { NodesNodeDisksZfsPostParams } from './generated/pve.ts';
 import { type PveRequirements, type WithTarget } from './resource.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';
-export type ZfsCompression = 'on' | 'off' | 'gzip' | 'lz4' | 'lzjb' | 'zle' | 'zstd';
+/**
+ * PVE's layouts, generated (2026-09-23) from `NodesNodeDisksZfsPostParams['raidlevel']`
+ * (`generated/pve.ts`, manifest `pve-apidoc` pve-manager 9.2.11 sha256 9def8f13…) rather than
+ * hand-typed, per decision 9. ⚠️ Each has a minimum disk count PVE enforces, and `raid10` needs an
+ * even one. ⛔ THERE IS NO `stripe` IN THIS ENUM. n1's `speed` pool is one (decision 14 accepts it
+ * as-is): `ZfsPoolProps` below is why a stripe pool is declarable at all — as an ADOPT-ONLY
+ * declaration with no `raidlevel`, never as a full one.
+ */
+export type ZfsRaidLevel = NonNullable<NodesNodeDisksZfsPostParams['raidlevel']>;
+/** Generated the same way, from `NodesNodeDisksZfsPostParams['compression']`. */
+export type ZfsCompression = NonNullable<NodesNodeDisksZfsPostParams['compression']>;
 /**
  * ⛔ THERE IS NO `add_storage`, `cleanup-config` OR `cleanup-disks` PROP, AND THAT IS NOT AN
  *   OVERSIGHT. The last two belong to the DELETE this resource refuses to make. `add_storage=1`
@@ -91,9 +103,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.
      *

package/dist/proxmox/zfs-pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zfs-pool.d.ts","sourceRoot":"","sources":["../../src/proxmox/zfs-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EACL,KAAK,eAAe,EAEpB,KAAK,UAAU,EAGhB,MAAM,eAAe,CAAC;AAIvB,oGAAoG;AACpG,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,QAAQ,CAAC;AAEb,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,+FAA+F;IAC/F,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;;OAYG;IACH,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,SAAS,EAAE,YAAY,CAAC;IACxB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAe,SAAQ,QAAQ,CAC9C,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,KAAK,EACL,eAAe,CAChB;CAAG;AAEJ,mGAAmG;AACnG,eAAO,MAAM,cAAc,iDAEzB,CAAC;AA8EH,eAAO,MAAM,sBAAsB,oIACoD,CAAC"}
+{"version":3,"file":"zfs-pool.d.ts","sourceRoot":"","sources":["../../src/proxmox/zfs-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAA8B,MAAM,eAAe,CAAC;AAIlG;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,2BAA2B,CAAC,WAAW,CAAC,CAAC,CAAC;AAEjF,iFAAiF;AACjF,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,2BAA2B,CAAC,aAAa,CAAC,CAAC,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,+FAA+F;IAC/F,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAe,SAAQ,QAAQ,CAC9C,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,KAAK,EACL,eAAe,CAChB;CAAG;AAEJ,mGAAmG;AACnG,eAAO,MAAM,cAAc,iDAEzB,CAAC;AAqBH,eAAO,MAAM,sBAAsB,oIACoD,CAAC"}

package/docs/adopted-deploys.md

@@ -57,6 +57,8 @@ API token on the cluster, just as it does for `alchemy plan`.
 | `Proxmox.CephDaemon` ⁶         | `nodes/{node}/ceph/{mon,mgr,mds}` (whole list, by `name`)       | read        | shared path, and no `updateForm`: GET, GET — no write                                                |
 | `Proxmox.CephFs` ⁶             | `nodes/{node}/ceph/fs` (whole list, by `name`)                  | read        | own: GET, present so returned untouched — no write                                                   |
 | `Proxmox.CephOsd` ⁶            | `nodes/{node}/ceph/osd` (the CRUSH tree)                        | read        | own: GET, host/class asserted; POSTs only with `dev` declared — no write                             |
+| `Proxmox.ApiToken` ⁷           | `access/users/{userid}/token/{tokenid}`                         | provision ¹ | shared path — PUT skipped on `matches`; POST refused (`reconcile` dies rather than mint one)         |
+| `Proxmox.ZfsPool` ⁷            | `nodes/{node}/disks/zfs/{name}`                                 | read        | own: GET; no PUT exists on this family; POST only with `devices` AND `raidlevel` both declared       |
 
 ¹ These object reads are gated on an allocate privilege, so the family reads with the provision
 lease (`readRole`, resource.ts). That is still a read.
@@ -83,6 +85,13 @@ declared flag reasserts a maintenance toggle on every deploy). Pinned by
 `src/proxmox/ceph-adopt.test.ts`, whose mutation check (retain flipped to destroy) shows nine
 DELETEs, one per mon, mgr and mds.
 
+⁷ Exported from the barrel 2026-09-23, decision 9. Both refuse to CREATE what they do not already
+have: ApiToken's `reconcile` dies by name rather than mint a secret it cannot store (api-token.ts);
+ZfsPool's `createPool` dies by name when `devices`/`raidlevel` are undeclared and the pool is not
+already there (zfs-pool-write.ts) — the adopt-only shape a stripe pool such as n1's `speed` needs,
+since PVE's own `raidlevel` enum has none. Pinned by `src/proxmox/api-token-adopt.test.ts` and
+`src/proxmox/zfs-pool-adopt.test.ts`, whose mutation rows show one PUT and one DELETE respectively.
+
 ## Before the fix: `Proxmox.CephPool`
 
 `reconcile` read the pool and, whenever it existed, PUT the declared `size`, `min_size`,
@@ -103,6 +112,11 @@ list shows six such tasks (2026-09-13 and 2026-09-20), one per declared pool per
 - `src/proxmox/ceph-adopt.test.ts` adopts a reference cluster's nine daemons, one CephFS and six
   OSDs (GETs only), undeclares all sixteen (no DELETE), and refuses an OSD on the wrong host
   without a write.
+- `src/proxmox/api-token-adopt.test.ts` adopts four token shapes read-only, refuses an absent
+  token, and shows a `privsep` flip PUTs exactly `comment`/`expire`/`privsep` once.
+- `src/proxmox/zfs-pool-adopt.test.ts` adopts five adopt-only pools read-only, refuses an absent
+  or vanished one before any POST, and shows `RemovalPolicy.destroy()` then undeclaring sends
+  exactly one DELETE.
 - `src/verify/verify.test.ts` pins Alchemy's own behaviour: `adopted` for a match and for a
   drift, and a reconcile for both. If an Alchemy upgrade changes that, the test fails and this
   page needs re-reading.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",

package/src/proxmox/api-token-adopt.test.ts

@@ -0,0 +1,138 @@
+/**
+ * `Proxmox.ApiToken` adopted, undeclared and drifted through Alchemy's own Plan and Apply, over a
+ * fake cluster — pinning the metadata-only shape decision 9 (2026-09-23) builds: adopt and manage
+ * `comment`/`expire`/`privsep`, never mint a token this resource cannot hand anybody the secret
+ * for (api-token.ts's header).
+ *
+ * ★ FOUR LIVE SHAPES: `metrics@pve!exporter` and `iac@pve!apply` are the no-comment / commented
+ *   shapes named in api-token.ts's own header; `svc@pve!lease1` and `svc@pve!lease2` are
+ *   PLACEHOLDERS (never an estate mint-user account — see the ⛔ on declaring under one in
+ *   api-token.ts's header) exercising a real non-zero `expire` offered as BOTH a JSON number and
+ *   a JSON string, which PVE does depending on path — `int()` (values.ts) must not care which.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { type ApiTokenProps, ProxmoxApiToken, ProxmoxApiTokenProvider } from './api-token.ts';
+import { shape } from './api-token-form.ts';
+import { FAKE_TARGET, type PveCall, fakePve, withoutBao } from './fake-pve.ts';
+import type {
+  AccessUsersUseridTokenTokenidPostParams,
+  AccessUsersUseridTokenTokenidPutParams,
+} from './generated/pve.ts';
+
+type Live = { comment?: string; expire: number | string; privsep: number };
+
+/** `access/users/{userid}/token/{tokenid}`, mutable so the PUT test can watch it change. */
+const tokens = new Map<string, Live>([
+  ['access/users/metrics@pve/token/exporter', { expire: 0, privsep: 0 }],
+  ['access/users/iac@pve/token/apply', { comment: 'automation', expire: 0, privsep: 0 }],
+  ['access/users/svc@pve/token/lease1', { expire: 1789327175, privsep: 0 }],
+  ['access/users/svc@pve/token/lease2', { comment: 'lease', expire: '1789327175', privsep: 0 }],
+]);
+
+const cluster = () =>
+  fakePve((call: PveCall) => {
+    if (call.method === 'GET') return tokens.get(call.path);
+    if (call.method === 'PUT') {
+      const live = tokens.get(call.path);
+      if (live !== undefined) tokens.set(call.path, { ...live, ...call.form });
+      return call.form;
+    }
+    return undefined;
+  });
+
+/** The declared props matching a live fixture exactly — `expire` always as a `number` prop. */
+const propsFor = (
+  userid: string,
+  tokenid: string,
+  over: { comment?: string; privsep?: boolean },
+): ApiTokenProps => ({
+  expire: Number(tokens.get(`access/users/${userid}/token/${tokenid}`)?.expire ?? 0),
+  privsep: over.privsep ?? false,
+  target: FAKE_TARGET,
+  tokenid,
+  userid,
+  ...(over.comment === undefined ? {} : { comment: over.comment }),
+});
+
+const token = (userid: string, tokenid: string, over: { comment?: string; privsep?: boolean }) =>
+  ProxmoxApiToken(`${userid.replace('@', '-')}-${tokenid}`, propsFor(userid, tokenid, over));
+
+const engineFor = (fake: ReturnType<typeof cluster>) =>
+  engineOver(ProxmoxApiTokenProvider().pipe(Layer.provideMerge(fake.layer)));
+
+const declared = () =>
+  Effect.all([
+    token('metrics@pve', 'exporter', {}),
+    token('iac@pve', 'apply', { comment: 'automation' }),
+    token('svc@pve', 'lease1', {}),
+    token('svc@pve', 'lease2', { comment: 'lease' }),
+  ]);
+
+describe('adopting a metadata-only ApiToken declaration', () => {
+  test('no comment, commented, and a real expire as both a number and a string: noop, adopted, no writes', async () => {
+    const fake = cluster();
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const report = await engine.verify(declared());
+      expect(report.rows).toHaveLength(4);
+      for (const row of report.rows) {
+        expect(row).toMatchObject({ changed: [], diff: 'noop', ok: true, planned: 'adopted' });
+      }
+      const planned = await engine.deploy(declared());
+      expect(new Set(Object.values(planned))).toEqual(new Set(['adopted']));
+      expect(Object.keys(planned)).toHaveLength(4);
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('undeclaring all four sends no DELETE (retain is the default)', async () => {
+    const fake = cluster();
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await engine.deploy(declared());
+      expect(await engine.deploy(Effect.void)).toEqual({});
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('an absent token: the deploy refuses with the mint-elsewhere message, and writes nothing', async () => {
+    const fake = cluster();
+    const gone = () =>
+      ProxmoxApiToken('gone', {
+        expire: 0,
+        privsep: false,
+        target: FAKE_TARGET,
+        tokenid: 'missing',
+        userid: 'nope@pve',
+      });
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await expect(engine.deploy(gone())).rejects.toBeDefined();
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('a privsep flip: verify shows changed, and the deploy sends exactly one PUT of comment/expire/privsep', async () => {
+    const fake = cluster();
+    const flipped = () => token('iac@pve', 'apply', { comment: 'automation', privsep: true });
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const report = await engine.verify(flipped());
+      expect(report.rows[0]).toMatchObject({ changed: ['privsep'], diff: 'update', ok: false });
+      expect(await engine.deploy(flipped())).toEqual({ 'iac-pve-apply': 'adopted' });
+    });
+    const put = fake.calls.find((call) => call.method === 'PUT');
+    expect(fake.writes()).toEqual(['PUT access/users/iac@pve/token/apply']);
+    expect(put?.pairs.map(([name]) => name)).toEqual(['comment', 'expire', 'privsep']);
+  });
+
+  test('the form keys typecheck against both generated PVE params, with no cast', () => {
+    const props = propsFor('iac@pve', 'apply', { comment: 'automation' });
+    const post: AccessUsersUseridTokenTokenidPostParams = shape(props);
+    const put: AccessUsersUseridTokenTokenidPutParams = shape(props);
+    expect(post).toEqual(put);
+  });
+});

package/src/proxmox/api-token-form.ts

@@ -16,6 +16,10 @@ import type { ApiTokenAttributes, ApiTokenProps } from './api-token.ts';
  *   that costs a forever-diff: the schema gives `expire` the default "same as user", and the code
  *   never implements it. api-token.ts records what that means.
  */
+import type {
+  AccessUsersUseridTokenTokenidPostParams,
+  AccessUsersUseridTokenTokenidPutParams,
+} from './generated/pve.ts';
 import type { PveSpec } from './resource.ts';
 import { bool, int, text } from './values.ts';
 
@@ -56,10 +60,23 @@ export const fullTokenid = (props: ApiTokenProps) => `${props.userid}!${props.to
  *   required prop precisely so that it is never undeclared, so there is nothing for it to do and
  *   its `string | undefined` return would have to be asserted away to fit `Record<string,string>`.
  *   An assertion here would be a claim about the prop that the type already makes properly.
+ *
+ * ★ TYPED AGAINST THE GENERATED PUT AND POST PARAMS, NOT `Record<string, string>`, since
+ *   2026-09-23 — the `notification-matcher-form.ts` pattern: `Pick` rather than the whole type,
+ *   because neither `AccessUsersUseridTokenTokenidPutParams` nor …`PostParams` (generated/pve.ts)
+ *   carries `userid`/`tokenid` (they are path segments — see the ⛔ above) and Put alone also
+ *   carries `delete`/`regenerate`, which this family never sends. A schema drift on any of the
+ *   three fields this function DOES send fails `tsc` here rather than surfacing as a 400 on a live
+ *   cluster; api-token.test.ts pins the assignment both ways (Put and Post) without a cast.
+ *   `expire` is written as a template literal, not `String(...)`, because the generated type is
+ *   `` `${number}` ``, not `string` — `String(n)` widens to plain `string` and would not typecheck.
  */
-export const shape = (props: ApiTokenProps): Record<string, string> => ({
+export const shape = (
+  props: ApiTokenProps,
+): Pick<AccessUsersUseridTokenTokenidPutParams, 'comment' | 'expire' | 'privsep'> &
+  Pick<AccessUsersUseridTokenTokenidPostParams, 'comment' | 'expire' | 'privsep'> => ({
   comment: props.comment ?? '',
-  expire: String(props.expire),
+  expire: `${props.expire}`,
   privsep: props.privsep ? '1' : '0',
 });
 

package/src/proxmox/api-token.ts

@@ -20,9 +20,14 @@
  *     whole of a token's policy, and declaring them is real work: it is how `expire` stops being
  *     whatever somebody typed in 2024. Mint NEW tokens where the secret can be caught — OpenBao's
  *     `proxmox-c1` mount, or a human at `pveum user token add`.
- *   ⚠️ THE CREATE PATH IS LEFT REACHABLE RATHER THAN STUBBED. A create that silently did nothing
- *     would be the same lie as the stubbed delete resource.ts's ★ refuses; the honest arrangement
- *     is a create that works and a header that says what it produces.
+ *   ⛔ ★ CORRECTED 2026-09-23 — THIS PARAGRAPH PREVIOUSLY SAID "THE CREATE PATH IS LEFT REACHABLE
+ *     RATHER THAN STUBBED… the honest arrangement is a create that works". THAT CONTRADICTED THE
+ *     `reconcile` BELOW, WHICH REFUSES: `handlers.reconcile` calls `Effect.die` by name when `read`
+ *     answers absent, before any POST — metadata-only per decision 9 (2026-09-23), exported on the
+ *     barrel as an adopt-and-manage-only Resource. A create that silently did nothing WOULD be the
+ *     lie resource.ts's ★ describes for a stubbed delete; refusing loudly, by name, with the two
+ *     ways to get a usable token, is the honest arrangement instead — see the ★ further down and
+ *     api-token-adopt.test.ts's absent-token row, which pins the refusal and zero writes.
  *
  * ⛔ THERE IS NO `regenerate` PROP, AND IT IS NOT AN OVERSIGHT. PVE's own description: "All users
  *   of the previous secret will lose access after this operation." A prop for it would revoke a

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[, }]/);
 });