@homeflare/alchemy 0.32.0 → 0.34.0

package/src/proxmox/zfs-pool.ts

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

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

@@ -1,27 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,128 +0,0 @@
-/**
- * The create lane for `Proxmox.ZfsPool`: the form PVE wants, and the wait for the worker it forks.
- *
- * ★ SPLIT OUT OF zfs-pool.ts TO KEEP BOTH FILES UNDER THE 250-LINE CAP, and the seam is a real one
- *   rather than a convenient line number. This file answers "how does a declaration become a pool
- *   on disks, and how do we know it landed". zfs-pool.ts answers "what is a zpool, what can be
- *   said about a live one, and when has it changed" — and on this family the answer to the last of
- *   those is "never", which is why the two halves have so little to say to each other.
- *
- * ⚠️ THE `import type` BACK TO zfs-pool.ts IS A CYCLE ON PAPER ONLY — it is type-only, so it is
- *   erased before anything runs, and the resource's public shape stays in the file that declares
- *   the resource rather than being moved somewhere odd to dodge the arrow. Same as
- *   metric-server-form.ts.
- *
- * ⚠️ `createPool` TAKES THE READ AS A PARAMETER, GENERIC IN ITS ERROR AND REQUIREMENT CHANNELS,
- *   rather than importing `pveOperations` and rebuilding the spec here. Two `pveOperations` over
- *   one spec would be two closures nobody can prove are the same; passing the one the resource
- *   already built means this file cannot accidentally read the cluster differently from `diff`.
- */
-import * as Effect from 'effect/Effect';
-import type { EndpointPair } from './resource-spec.ts';
-import type { ZfsPoolAttributes, ZfsPoolProps } from './zfs-pool.ts';
-/**
- * The POST body. Every field in it is write-only — nothing here is ever read back.
- *
- * ⚠️ `node` IS NOT IN THE BODY: it is already the `nodes/{node}` segment of the URL being POSTed
- *   to, and a second copy can only disagree with it. Same reasoning as `id` in metric-server.ts.
- * ⚠️ `devices` IS JOINED IN DECLARED ORDER AND NOT PUT THROUGH `csv()` FROM values.ts. `csv` sorts,
- *   and PVE walks this list two at a time to pair `raid10` mirrors — MEASURED in the node's own
- *   `PVE::API2::Disks::ZFS` — so sorting it builds a different pool from the one declared. The
- *   list is never compared against anything, so it needs no normalisation, only faithful order.
- * ⚠️ AN OMITTED OPTIONAL IS NOT SENT. PVE's own defaults (ashift 12, compression on) are then
- *   applied by the node. Sending a guessed default would be indistinguishable here — the values
- *   are unreadable afterwards either way — but it would put a number in the request that no
- *   declaration asked for, and this is the one call that writes to physical disks.
- */
-/**
- * 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. 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.
- *
- * ⛔ THE POST ONLY FORKS A WORKER. MEASURED in `/usr/share/perl5/PVE/API2/Disks/ZFS.pm` on node-b: the
- *   create handler ends in `$rpcenv->fork_worker('zfscreate', ...)` and its HTTP answer is a UPID
- *   returned the instant the worker is forked — before `zpool create` has run, let alone finished.
- *   A read-back taken immediately, as `pveOperations.reconcile` takes it, finds nothing and would
- *   report a successful create as the failure "the write returned no error but the object is still
- *   absent". THAT is why this function exists instead of the factory's reconcile.
- *
- * ⚠️ THERE IS NO UPDATE BRANCH BECAUSE PVE HAS NO PUT HERE. An existing pool is returned exactly as
- *   read, unwritten: the only write this resource ever makes is the create of a pool that is not
- *   there. Do not add a "repair" write; there is no field it could set.
- *
- * ⛔ AND IF THE READ IS WRONG, THE POST IS STILL SAFE — measured, not hoped for. `read` folds a 403
- *   or an unreachable node into "absent", so a too-narrow lease would send this down the create
- *   path over a live pool. PVE's handler calls `get_pool_data()` before it forks anything and dies
- *   with "pool '<name>' already exists on node '<node>'", and `assert_disk_unused` refuses every
- *   device that pool is holding. A create aimed at a pool that is really there fails loudly rather
- *   than wiping it.
- *
- * ⚠️ SHORT POLLS WITH A HARD CAP, NOT ONE LONG WAIT. `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 | import("./credential-errors.ts").PveCredentialDenied, R | import("effect/unstable/http/HttpClient").HttpClient>;
-/**
- * ⛔ `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
- *   resource reaching over to delete another's is how a stack ends up with state describing
- *   something that is gone.
- */
-export declare const destroyPool: (olds: ZfsPoolProps, path: string) => Effect.Effect<unknown, Error | import("./credential-errors.ts").PveCredentialDenied, import("effect/unstable/http/HttpClient").HttpClient>;
-//# sourceMappingURL=zfs-pool-write.d.ts.map

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

@@ -1 +0,0 @@
-{"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,iKA8C/E,CAAC;AAEL;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,SAAU,YAAY,QAAQ,MAAM,+IACb,CAAC"}

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

@@ -1,76 +0,0 @@
-/**
- * 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}`,
-};