@homeflare/alchemy 0.31.2 → 0.33.0

package/src/unifi/policy.ts

@@ -0,0 +1,37 @@
+/**
+ * The one refusal every `Unifi.*` write handler returns — never an SDK write call.
+ *
+ * ⛔ TIM'S RULE, 2026-09-24: UniFi (and OPNsense) are READ-ONLY FOR NOW. This family has no
+ *   `create`, no `update` body and no delete call anywhere in its source — `reconcile` and
+ *   `delete` both fail with this typed error instead, and `resource.test.ts` proves the point
+ *   with a fake `HttpClient` that fails the test on any request that is not a `GET`. Lifting the
+ *   policy is a kit change (a new PR that adds a write path, reviewed as one), not a flag a stack
+ *   can pass.
+ *
+ * ★ A TYPED TAG, NOT A THROWN STRING (S21). `Effect.catchTag('UnifiWriteRefused', …)` lets a
+ *   caller (a future import script, a test) branch on the refusal without parsing a message.
+ */
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+
+export const UNIFI_READ_ONLY_POLICY =
+  "read-only by Tim's rule, 2026-09-24; lifting it is a kit change";
+
+/** What kind of write was asked for and refused — for the message only, never acted on. */
+export type UnifiWriteAction = 'create' | 'update' | 'delete';
+
+export class UnifiWriteRefused extends Data.TaggedError('UnifiWriteRefused')<{
+  /** The vendor type string, e.g. `Unifi.Network`. */
+  readonly type: string;
+  /** `spec.describe(props)` — the object the write would have touched. */
+  readonly identity: string;
+  readonly action: UnifiWriteAction;
+}> {
+  override get message(): string {
+    return `${this.type} ${this.identity}: refusing to ${this.action} -- ${UNIFI_READ_ONLY_POLICY}.`;
+  }
+}
+
+/** The only thing `reconcile`/`delete` ever return for a write this family cannot make. */
+export const refuseWrite = (type: string, identity: string, action: UnifiWriteAction) =>
+  Effect.fail(new UnifiWriteRefused({ type, identity, action }));

package/src/unifi/providers.ts

@@ -0,0 +1,15 @@
+/**
+ * Every `Unifi.*` provider as one layer for a stack.
+ *
+ *     Layer.mergeAll(unifiProviders(), …the stack's other providers)
+ *       .pipe(Layer.provide(FetchHttpClient.layer))
+ *
+ * S16: a subpath's `providers()` plays the role upstream's own `Providers.ts` does — one minimal
+ * insertion per family. `FetchHttpClient.layer` is the stack's own responsibility to provide,
+ * mirroring `../discord/providers.ts`.
+ */
+import * as Layer from 'effect/Layer';
+import { UnifiFirewallZoneProvider } from './firewall-zone.ts';
+import { UnifiNetworkProvider } from './network.ts';
+
+export const providers = () => Layer.mergeAll(UnifiNetworkProvider(), UnifiFirewallZoneProvider());

package/src/unifi/resource.test.ts

@@ -0,0 +1,133 @@
+/**
+ * `unifiOperations` in isolation, against a synthetic spec — no real UniFi SDK, no HTTP. Proves
+ * the read-only engine's own contract: `Unowned` on a cold read (H1), `noop`/`update` diff,
+ * `reconcile` succeeding with ZERO write calls on an exact match (the H6 forced post-adoption
+ * call this engine has to survive without writing), and a typed `UnifiWriteRefused` — never a
+ * silent success, never a raw SDK write — every other time `reconcile` or `delete` runs.
+ *
+ * `network.test.ts`/`firewall-zone.test.ts` prove the same contract again against the REAL SDK
+ * and a fake HTTP server, and additionally prove that no non-`GET` request is ever sent.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import type { UnifiNetworkOpContext } from '@distilled.cloud/unifi-network/Protocol';
+import * as Effect from 'effect/Effect';
+import { fakeUnifiLayer } from './fake-unifi.ts';
+import { UnifiWriteRefused } from './policy.ts';
+import { type UnifiSpec, unifiOperations } from './resource.ts';
+
+interface WidgetProps {
+  id: string;
+  value: number;
+}
+type WidgetLive = WidgetProps;
+type WidgetAttrs = WidgetProps;
+
+/** `live: undefined` models a declared object nothing on the site matches. */
+const specFor = (
+  live: WidgetLive | undefined,
+): UnifiSpec<WidgetProps, WidgetLive, WidgetAttrs, never> => ({
+  type: 'Test.Widget',
+  describe: (props) => `widgets/${props.id}`,
+  fetchLive: () => Effect.succeed(live),
+  attributes: (l) => l,
+  matches: (attrs, props) => attrs.value === props.value,
+});
+
+const MATCH: WidgetProps = { id: 'w1', value: 1 };
+const DRIFTED_LIVE: WidgetLive = { id: 'w1', value: 99 };
+
+/**
+ * `UnifiSpec`'s `fetchLive` is typed against the real `UnifiNetworkOpContext` (`resource.ts`'s
+ * own header explains why the engine is not generic over it) even though `specFor` above never
+ * touches HTTP — so every run here still needs A layer satisfying that context. This one fails
+ * the test outright if anything ever calls it, which is itself part of the write-refusal proof:
+ * the synthetic spec has no operation that could, but if one ever did, this is not a silent pass.
+ */
+const unreachableFetch = (() => {
+  throw new Error('resource.test.ts: unexpected HTTP call from a spec with no HTTP operations');
+}) as unknown as typeof globalThis.fetch;
+
+const run = <A, E>(effect: Effect.Effect<A, E, UnifiNetworkOpContext>) =>
+  Effect.runPromise(effect.pipe(Effect.provide(fakeUnifiLayer(unreachableFetch))));
+
+const refusal = async (
+  effect: Effect.Effect<unknown, UnifiWriteRefused, UnifiNetworkOpContext>,
+) => {
+  const failure = await run(Effect.flip(effect));
+  expect(failure).toBeInstanceOf(UnifiWriteRefused);
+  return failure;
+};
+
+describe('unifiOperations.readHandler', () => {
+  test('cold read (no persisted output) of a match answers Unowned', async () => {
+    const attrs = await run(
+      unifiOperations(specFor(MATCH)).readHandler({ olds: MATCH, output: undefined }),
+    );
+    expect(Unowned.is(attrs)).toBe(true);
+    expect(attrs).toEqual(MATCH);
+  });
+
+  test('warm read (persisted output says ours already) answers plain attributes', async () => {
+    const attrs = await run(
+      unifiOperations(specFor(MATCH)).readHandler({ olds: MATCH, output: MATCH }),
+    );
+    expect(Unowned.is(attrs)).toBe(false);
+    expect(attrs).toEqual(MATCH);
+  });
+
+  test('a genuinely absent object answers undefined either way', async () => {
+    const attrs = await run(
+      unifiOperations(specFor(undefined)).readHandler({ olds: MATCH, output: MATCH }),
+    );
+    expect(attrs).toBeUndefined();
+  });
+});
+
+describe('unifiOperations.diff', () => {
+  test('no persisted output defers to the engine default (undefined)', async () => {
+    const diff = await run(unifiOperations(specFor(MATCH)).diff(MATCH, undefined));
+    expect(diff).toBeUndefined();
+  });
+
+  test('declared props match live -- noop', async () => {
+    const diff = await run(unifiOperations(specFor(MATCH)).diff(MATCH, MATCH));
+    expect(diff).toEqual({ action: 'noop' });
+  });
+
+  test('live object drifted from the declaration -- update, never silently absorbed', async () => {
+    const diff = await run(unifiOperations(specFor(DRIFTED_LIVE)).diff(MATCH, MATCH));
+    expect(diff).toEqual({ action: 'update' });
+  });
+
+  test('live object vanished since it was adopted -- update, never a quiet noop', async () => {
+    const diff = await run(unifiOperations(specFor(undefined)).diff(MATCH, MATCH));
+    expect(diff).toEqual({ action: 'update' });
+  });
+});
+
+describe('unifiOperations.reconcile', () => {
+  test('exact match: zero write calls (the spec has none), returns live attributes -- H6', async () => {
+    const attrs = await run(unifiOperations(specFor(MATCH)).reconcile(MATCH));
+    expect(attrs).toEqual(MATCH);
+  });
+
+  test('missing live object refuses "create", never fabricates one', async () => {
+    const failure = await refusal(unifiOperations(specFor(undefined)).reconcile(MATCH));
+    expect(failure.action).toBe('create');
+    expect(failure.type).toBe('Test.Widget');
+    expect(failure.identity).toBe('widgets/w1');
+  });
+
+  test('drifted live object refuses "update", never converges by writing', async () => {
+    const failure = await refusal(unifiOperations(specFor(DRIFTED_LIVE)).reconcile(MATCH));
+    expect(failure.action).toBe('update');
+  });
+});
+
+describe('unifiOperations.destroy', () => {
+  test('always refuses "delete" -- the spec has no destroy operation at all', async () => {
+    const failure = await refusal(unifiOperations(specFor(MATCH)).destroy(MATCH));
+    expect(failure.action).toBe('delete');
+  });
+});

package/src/unifi/resource.ts

@@ -0,0 +1,131 @@
+/**
+ * One shape for every UniFi Network read-only object — `Unifi.Network`, `Unifi.FirewallZone`,
+ * and whatever import adds next.
+ *
+ * ★ MIRRORS `../discord/resource.ts` (S7-S10, H1, H5), NOT `../netbox/resource.ts`. Both are
+ *   "marker-less API" families (S8): UniFi Network objects carry no tag or metadata field this
+ *   stack could stamp as ownership, so a cold read of a match is `Unowned(attrs)` exactly like
+ *   `Cloudflare/Snippets/Snippet.ts@v2.0.0-beta.79#read`, the reference implementation S8 and H1
+ *   both cite. `adopt(true)`, piped on by each resource's convenience constructor (H5), turns
+ *   that into a silent one-time bind instead of an `OwnedBySomeoneElse` refusal.
+ *
+ * ⛔ THE DIFFERENCE FROM EVERY OTHER FAMILY HERE: THERE IS NO `create`, `update` OR `destroy` IN
+ *   THIS SPEC AT ALL. Tim's rule, 2026-09-24 (`policy.ts`): UniFi and OPNsense are read-only. So
+ *   `reconcile` below can only ever refuse or report an exact match — it has no write path to
+ *   fall into by accident, and no resource file wired through this engine can reach one either.
+ *
+ * ⚠️ RECONCILE STILL HAS TO SUCCEED ON AN EXACT-MATCH ADOPTION, NOT JUST REFUSE UNCONDITIONALLY.
+ *   Measured against `Plan.ts@v2.0.0-beta.79` (`forceUpdateAfterAdoption`, H6): beta.79 forces
+ *   ONE reconcile call after every cold adoption, whether or not the diff said noop — so a
+ *   resource whose `reconcile` always failed would break the ordinary "adopt an unchanged
+ *   object" deploy, not just a real write. The fix, exactly like `discordOperations.reconcile`:
+ *   read the live object again, and refuse ONLY when it is missing (would need a create) or
+ *   drifted (would need a write to converge). An exact match returns the live attributes and
+ *   calls nothing — S10's "zero write calls when there is no drift" holds even under the forced
+ *   post-adoption call.
+ *
+ * ⚠️ `NotFound` IS FOLDED TO "ABSENT" INSIDE EACH RESOURCE FILE'S OWN `fetchLive`, NOT HERE —
+ *   same split netbox's `resource.ts` uses and for the same reason: `Effect.catchTag`'s
+ *   tag-literal inference needs a concrete error union to resolve `"NotFound"` against, and a
+ *   spec's `E` is only concrete at each resource file's own call site. Every OTHER failure (a
+ *   real 5xx, a network error, `Forbidden`) is NOT folded anywhere — it fails the plan loudly,
+ *   per the task's own rule: only a genuine not-found may mean absent.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import { CredentialsFromEnv } from '@distilled.cloud/unifi-network/Credentials';
+import type { UnifiNetworkOpContext } from '@distilled.cloud/unifi-network/Protocol';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { refuseWrite } from './policy.ts';
+
+/** What every handler needs from the caller's runtime once `CredentialsFromEnv` is baked in. */
+export type UnifiRequirements = HttpClient.HttpClient;
+
+/**
+ * One UniFi Network object's read. `Live` is whatever the SDK decodes (a `NetworkDetails`, a
+ * `FirewallZone`, …); `E` is left to each resource file to declare (its own `fetchLive`'s error
+ * union, with `NotFound` already folded away) so the precise per-operation error union flows
+ * through instead of being widened by hand here.
+ */
+export type UnifiSpec<Props extends object, Live, Attributes extends object, E> = {
+  /** The vendor type string, e.g. `Unifi.Network` — for the refusal message only. */
+  readonly type: string;
+  /** Already folds a genuine not-found to `undefined`; nothing else is folded (see header). */
+  readonly fetchLive: (props: Props) => Effect.Effect<Live | undefined, E, UnifiNetworkOpContext>;
+  readonly attributes: (live: Live, props: Props) => Attributes;
+  readonly matches: (attributes: Attributes, props: Props) => boolean;
+  /** For the refusal message and read-back failures. */
+  readonly describe: (props: Props) => string;
+};
+
+export const unifiOperations = <Props extends object, Live, Attributes extends object, E>(
+  spec: UnifiSpec<Props, Live, Attributes, E>,
+) => {
+  const read = (props: Props) =>
+    spec
+      .fetchLive(props)
+      .pipe(Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))));
+
+  return {
+    read,
+
+    readHandler: ({ olds, output }: { olds: Props; output: Attributes | undefined }) =>
+      Effect.gen(function* () {
+        const attrs = yield* read(olds);
+        if (attrs === undefined) return undefined;
+        // Warm read (persisted `output` says a prior apply already adopted this exact object):
+        // plain attributes. Cold read (fresh store, or state lost): no ownership marker on this
+        // vendor exists to tell "ours" from "someone else's" apart, so Unowned until adopt(true).
+        return output !== undefined ? attrs : Unowned(attrs);
+      }),
+
+    diff: (news: Input<Props>, output: Attributes | undefined) =>
+      Effect.gen(function* () {
+        if (output === undefined || !isResolved(news)) return undefined;
+        const live = yield* read(news);
+        if (live === undefined) return { action: 'update' } as const;
+        return spec.matches(live, news)
+          ? ({ action: 'noop' } as const)
+          : ({ action: 'update' } as const);
+      }),
+
+    reconcile: (news: Props) =>
+      Effect.gen(function* () {
+        const live = yield* read(news);
+        if (live === undefined) return yield* refuseWrite(spec.type, spec.describe(news), 'create');
+        if (!spec.matches(live, news)) {
+          return yield* refuseWrite(spec.type, spec.describe(news), 'update');
+        }
+        // Exact match: the object already is what is declared. Zero write calls (S10), correct
+        // whether this is a routine deploy or beta.79's forced post-adoption reconcile (H6).
+        return live;
+      }),
+
+    destroy: (olds: Props) => refuseWrite(spec.type, spec.describe(olds), 'delete'),
+  };
+};
+
+/**
+ * The four provider handlers for a spec'd read-only UniFi object, wired once.
+ *
+ * ⛔ `list` ANSWERS EMPTY. `GET /v1/sites/{siteId}/networks` answers every network on the site;
+ *   adoption stays explicit, the same reasoning `Proxmox.User`'s and NetBox's `list` give.
+ */
+export const unifiHandlers = <Props extends object, Live, Attributes extends object, E>(
+  spec: UnifiSpec<Props, Live, Attributes, E>,
+) => {
+  const ops = unifiOperations(spec);
+  const withCredentials = <A, Err>(effect: Effect.Effect<A, Err, UnifiNetworkOpContext>) =>
+    Effect.provide(effect, CredentialsFromEnv);
+  return {
+    list: () => Effect.succeed([]),
+    read: (args: { olds: Props; output: Attributes | undefined }) =>
+      withCredentials(ops.readHandler(args)),
+    diff: (args: { news: Input<Props>; output: Attributes | undefined }) =>
+      withCredentials(ops.diff(args.news, args.output)),
+    reconcile: (args: { news: Props }) => withCredentials(ops.reconcile(args.news)),
+    delete: (args: { olds: Props }) => withCredentials(ops.destroy(args.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}`,
-};