@homeflare/alchemy 0.31.2 → 0.33.0

package/src/opnsense/resource.ts

@@ -0,0 +1,146 @@
+/**
+ * One shape for every OPNsense object this family declares — `read`/`diff` mirroring
+ * `../discord/resource.ts`'s marker-less-API posture exactly (S7–S9, H1), and `reconcile`/
+ * `delete` replaced end to end with the read-only refusal `policy.ts` states.
+ *
+ * ★ WHY ONE ENGINE FOR THREE RESOURCES. `alias.ts`, `category.ts` and `group.ts` differ only in
+ *   which `firewall_*` module they call and how a live item maps to attributes — the read/diff/
+ *   reconcile/delete flow is identical, so it lives here once, the way `netbox/resource.ts` and
+ *   `discord/resource.ts` already do for their own families.
+ *
+ * ★ `Unowned(attrs)` ON A COLD READ, PLAIN ATTRIBUTES ON A WARM ONE (S7, S8). None of Alias,
+ *   Category or Group carries an ownership marker OPNsense itself understands — no tag, no
+ *   metadata field a stack could stamp — so this is the same "marker-less API" S8 describes, and
+ *   the same posture `../discord/resource.ts` documents against `Snippet.ts`'s reference read.
+ *   `adopt(true)` (H5), piped on by each resource file's convenience constructor, is what turns
+ *   an `Unowned` first read into a silent one-time takeover instead of an `OwnedBySomeoneElse`
+ *   refusal — exactly what an import script generating `alchemy.run.ts` rows from live reads
+ *   needs: declare what is live, adopt it, change nothing.
+ *
+ * ⛔ `reconcile` AND `delete` NEVER CALL AN SDK OPERATION. `reconcile` still OBSERVES first (one
+ *   GET, via `read`) so the refusal it raises can say whether it would have created or updated —
+ *   S9's "observe before you write" doctrine, kept for the error message even though there is no
+ *   write to guard. `delete` observes nothing: it refuses unconditionally, because under this
+ *   policy a delete never succeeds regardless of whether the object is still live. See policy.ts.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import type { OpnsenseOpContext } from '@distilled.cloud/opnsense/Protocol';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { CredentialsFromEnv } from './credentials.ts';
+import { refuseWrite } from './policy.ts';
+
+/** What every stack must still provide after `opnsenseHandlers` bakes in `CredentialsFromEnv`. */
+export type OpnsenseRequirements = HttpClient.HttpClient;
+
+/** Every resource in this family identifies its live object by OPNsense's own assigned uuid. */
+export interface OpnsenseIdentity {
+  readonly uuid: string;
+}
+
+/**
+ * One OPNsense object's read path. `Live` is whatever the generated `get()` response decodes to
+ * for one item (an `AliasItem`, `CategoryItem`, `GroupItem`); `E` is left to each resource file
+ * to declare — in practice always `OpnsenseOpError`, since every generated operation shares one
+ * error channel (protocol.ts).
+ */
+export type OpnsenseSpec<Props extends OpnsenseIdentity, Live, Attributes extends object, E> = {
+  readonly resourceType: string;
+  /** Absent when `props.uuid` is not a key in the live model's map — see each resource file. */
+  readonly fetchLive: (props: Props) => Effect.Effect<Live | undefined, E, OpnsenseOpContext>;
+  /** Also the declaration renderer (S.T. propsFromLive re-export) — see each `*-form.ts`. */
+  readonly attributes: (uuid: string, live: Live) => Attributes;
+  readonly matches: (attributes: Attributes, props: Props) => boolean;
+};
+
+export const opnsenseOperations = <
+  Props extends OpnsenseIdentity,
+  Live,
+  Attributes extends object,
+  E,
+>(
+  spec: OpnsenseSpec<Props, Live, Attributes, E>,
+) => {
+  const read = (props: Props) =>
+    spec
+      .fetchLive(props)
+      .pipe(
+        Effect.map((live) => (live === undefined ? undefined : spec.attributes(props.uuid, live))),
+      );
+
+  return {
+    read: ({ olds, output }: { olds: Props; output: Attributes | undefined }) =>
+      Effect.gen(function* () {
+        const attrs = yield* read(olds);
+        if (attrs === undefined) return undefined;
+        // Warm read: a prior apply already adopted this exact uuid — ours.
+        if (output !== undefined) return attrs;
+        // Cold read (fresh store, or state lost): no ownership marker exists on this vendor.
+        return 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);
+        return yield* refuseWrite(
+          spec.resourceType,
+          news.uuid,
+          live === undefined ? 'create' : 'update',
+        );
+      }),
+
+    destroy: (olds: Props) => refuseWrite(spec.resourceType, olds.uuid, 'delete'),
+  };
+};
+
+/**
+ * The provider handlers for a spec'd OPNsense object, wired once. `list` answers empty — every
+ * `get()` in this family returns the WHOLE model tree with no per-account/per-scope narrowing,
+ * so a `list` that enumerated it would sweep the estate's entire alias/category/group set into
+ * one plan; adoption stays explicit, one uuid at a time, the same reasoning netbox's and
+ * discord's own `list` give for a shared or marker-less object space (S12).
+ *
+ * `nuke: { skip: true }` — `delete` refuses unconditionally (policy.ts), so `alchemy unsafe
+ * nuke` could never do anything here but fail loudly on every object it found; skipping keeps
+ * that refusal out of a nuke census entirely, matching `postgres/database.ts` and
+ * `github/repository-ruleset.ts`'s own `nuke: { skip: true }` for the same reason.
+ */
+export const opnsenseHandlers = <
+  Props extends OpnsenseIdentity,
+  Live,
+  Attributes extends object,
+  E,
+>(
+  spec: OpnsenseSpec<Props, Live, Attributes, E>,
+) => {
+  const ops = opnsenseOperations(spec);
+  // ⚠️ GENERIC OVER ITS OWN ERROR AND REQUIREMENT CHANNELS, NOT PINNED TO `E`/`OpnsenseOpContext`.
+  //   `read`/`diff` fail with `E` and need `OpnsenseOpContext`; `reconcile` fails with
+  //   `E | OpnsenseWriteRefused` (it observes, then refuses) and still needs `OpnsenseOpContext`
+  //   for that observe; `delete` fails with `OpnsenseWriteRefused` alone and needs NOTHING (it
+  //   never observes) — three different signatures sharing one credentials-providing wrapper.
+  const withCredentials = <A, Err, R>(effect: Effect.Effect<A, Err, R>) =>
+    Effect.provide(effect, CredentialsFromEnv);
+  return {
+    list: () => Effect.succeed([]),
+    nuke: { skip: true },
+    read: ({ olds, output }: { olds: Props; output: Attributes | undefined }) =>
+      withCredentials(ops.read({ olds, output })),
+    diff: ({ news, output }: { news: Input<Props>; output: Attributes | undefined }) =>
+      withCredentials(ops.diff(news, output)),
+    reconcile: ({ news }: { news: Props }) => withCredentials(ops.reconcile(news)),
+    delete: ({ olds }: { olds: Props }) => withCredentials(ops.destroy(olds)),
+  };
+};

package/src/opnsense/wire.ts

@@ -0,0 +1,56 @@
+/**
+ * How OPNsense's MVC model spells a value on the wire, and how to get it back to something
+ * comparable — the `../proxmox/values.ts` idea, scoped to this vendor's own spellings.
+ *
+ * ★ OPNSENSE HAS EXACTLY TWO WIRE SHAPES THIS FAMILY NEEDS. Every `BooleanField` is the string
+ *   `"1"` or `"0"` (never a JSON boolean — `AliasItem.enabled: string`, `GroupItem.nogroup?:
+ *   string`, see `firewall_alias.ts`/`firewall_group.ts`). Every multi-select `OptionField`/
+ *   `ModelRelationField` is a SINGLE comma-joined string, not a JSON array (`AliasItem.categories`,
+ *   `GroupItem.members` — both carry the doc comment "wire value is a single comma-joined string,
+ *   not a JSON array" in the generated SDK). Nothing here is specific to one resource.
+ *
+ * ⚠️ COMMA-LIST ORDER ROUND-TRIP IS NOT ASSUMED STABLE. OPNsense builds these from a PHP
+ *   associative array (`ModelRelationField`/`OptionField::getNodeData()`), and nothing in the
+ *   model XML promises the join order survives a save-then-read unchanged. Sorting and
+ *   deduplicating both sides before comparing is what makes `matches` (alias-form.ts,
+ *   group-form.ts) actually settle instead of reporting drift on a re-ordered list that changed
+ *   nothing — the same reasoning `../proxmox/user-wire.ts`'s `groupSet` documents for PVE's
+ *   `groups` field.
+ */
+
+/** OPNsense's own boolean spelling. Absent takes the caller's stated default — OPNsense's own
+ * default for a `BooleanField` is form-specific, so there is no house-wide fallback here. */
+export const bool01 = (value: string | undefined, fallback: boolean): boolean =>
+  value === undefined ? fallback : value === '1';
+
+/** The write direction, for symmetry — unused today (this family never writes), kept so a form
+ * helper never has to guess the spelling if lifting the read-only policy adds one later. */
+export const toBool01 = (value: boolean): string => (value ? '1' : '0');
+
+/**
+ * A comma-joined multi-select column, normalised to a sorted, deduplicated set — see the module
+ * header's ⚠️ for why normalising (not just splitting) is what makes a diff settle.
+ */
+export const csvSet = (value: string | undefined): readonly string[] => {
+  if (value === undefined || value.trim() === '') return [];
+  const items = value
+    .split(',')
+    .map((item) => item.trim())
+    .filter((item) => item !== '');
+  return [...new Set(items)].sort();
+};
+
+/** A declared array, normalised the SAME way `csvSet` normalises the wire, so `matches` compares
+ * two sets built by one function rather than trusting the caller's array to already be sorted. */
+export const csvSetOf = (value: readonly string[] | undefined): readonly string[] =>
+  csvSet(value === undefined ? undefined : value.join(','));
+
+/**
+ * OPNsense's numeric-as-string fields (`"60"`, `"0"`), tolerant of an already-numeric input the
+ * same way `../proxmox/user-wire.ts`'s `int` is tolerant of PVE's mixed number/string releases.
+ */
+export const numField = (value: string | undefined, fallback: number): number => {
+  if (value === undefined) return fallback;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+};

package/src/opnsense/write-refusal.test.ts

@@ -0,0 +1,148 @@
+/**
+ * THE PROOF: no SDK write operation — `addItem`, `setItem`, `delItem`, `toggleItem`, `set`, or
+ * OPNsense's own POST-shaped search reads — is reachable from ANY handler of ANY resource in this
+ * family, for ANY input. `getOnlyOrFail` (fake-opnsense.ts) fails the test itself the instant a
+ * non-GET request is made, so this does not rely on inspecting what each handler happens to call
+ * — it fails loudly the moment anything but a `get()` reaches the wire.
+ *
+ * `alias.test.ts`, `category.test.ts` and `group.test.ts` already run every scenario through this
+ * same fake and would catch a write there too; this file exists so ONE place in this family
+ * states the guarantee plainly, exercising the public `handlers` object each resource file wires
+ * into its `Provider` (not just the lower-level `opnsenseOperations`), across every lifecycle
+ * method `Provider.of` calls and against both an absent and a drifted live object.
+ *
+ * ⚠️ `handlers.*` BAKES IN `CredentialsFromEnv` (resource.ts's `withCredentials`), unlike
+ *   `opnsenseOperations(spec)` — see fake-opnsense.ts's warning on `fakeOpnsenseLayer`. Providing
+ *   `fakeOpnsenseLayer`'s own `Credentials` layer from here does nothing: the inner `Effect.provide`
+ *   already closed over that tag, so it wins. Left unaddressed, `CredentialsFromEnv` reads real
+ *   `OPNSENSE_*` env vars via `EffectConfig`, finds none in CI, and `Effect.orDie`s before any
+ *   request is built — `fake.seen` stays empty and `.every(...)` on an empty array is vacuously
+ *   `true`. `fakeCredentialsConfigProvider` below fixes this WITHOUT touching real `process.env`
+ *   (which a parallel test file could race on): it overrides the `effect/ConfigProvider` the
+ *   `EffectConfig.String("OPNSENSE_*")` reads inside `CredentialsFromEnv` resolve against, which is
+ *   a different tag CredentialsFromEnv never shadows — proved against this exact fake/real pattern
+ *   before landing here. Every "only GETs" test below also asserts `fake.seen` has exactly the
+ *   one GET `fetchLive` issues, so a run that silently makes zero requests (or a future
+ *   double-GET regression) fails loudly instead of passing on an under-checked `.every()`.
+ *
+ * ⚠️ THIS FIX HAS ONE INVARIANT: `CredentialsFromEnv` (distilled-opnsense's `credentials.ts`) must
+ *   keep resolving `OPNSENSE_*` through the AMBIENT `ConfigProvider` rather than one it pins
+ *   itself. If it ever starts providing its own `ConfigProvider` — the way it already closes over
+ *   the `Credentials` tag via `withCredentials` — this override would be shadowed the same way
+ *   `fakeOpnsenseLayer`'s `Credentials` layer is today, and the vacuous-pass bug this file exists
+ *   to prevent would return silently.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as ConfigProvider from 'effect/ConfigProvider';
+import { handlers as aliasHandlers, spec as aliasSpec } from './alias.ts';
+import { handlers as categoryHandlers, spec as categorySpec } from './category.ts';
+import {
+  FAKE_BASE,
+  FAKE_KEY,
+  FAKE_SECRET,
+  fakeOpnsenseLayer,
+  getOnlyOrFail,
+} from './fake-opnsense.ts';
+import { handlers as groupHandlers, spec as groupSpec } from './group.ts';
+
+/**
+ * Overrides the `ConfigProvider` `CredentialsFromEnv`'s `EffectConfig.String("OPNSENSE_*")`
+ * resolves against, so `handlers.*` (which bakes in real env-var credentials resolution) gets
+ * the same placeholder values `fakeOpnsenseLayer`'s default `Credentials` layer uses — without
+ * ever reading or writing real `process.env`.
+ */
+const fakeCredentialsConfigProvider = ConfigProvider.layer(
+  ConfigProvider.fromUnknown({
+    OPNSENSE_API_KEY: FAKE_KEY,
+    OPNSENSE_API_SECRET: FAKE_SECRET,
+    OPNSENSE_URL: FAKE_BASE,
+  }),
+);
+
+/** `fakeOpnsenseLayer` plus the env override `handlers.*` needs — see the file header. */
+const fakeHandlersLayer = (fetchFn: typeof globalThis.fetch) =>
+  Layer.mergeAll(fakeOpnsenseLayer(fetchFn), fakeCredentialsConfigProvider);
+
+const families = [
+  {
+    empty: Response.json({ alias: {} }),
+    handlers: aliasHandlers,
+    live: Response.json({
+      alias: { aliases: { alias: { u: { content: 'x', enabled: '1', name: 'n', type: 'host' } } } },
+    }),
+    props: { content: 'x', name: 'n', type: 'host', uuid: 'u' },
+    resourceType: aliasSpec.resourceType,
+  },
+  {
+    empty: Response.json({ category: {} }),
+    handlers: categoryHandlers,
+    live: Response.json({ category: { categories: { category: { u: { name: 'n' } } } } }),
+    props: { name: 'n', uuid: 'u' },
+    resourceType: categorySpec.resourceType,
+  },
+  {
+    empty: Response.json({ group: {} }),
+    handlers: groupHandlers,
+    live: Response.json({
+      group: { ifgroupentry: { u: { ifname: 'n', members: '', sequence: '0' } } },
+    }),
+    props: { ifname: 'n', members: [], uuid: 'u' },
+    resourceType: groupSpec.resourceType,
+  },
+];
+
+describe.each(families)(
+  '$resourceType — write-refusal proof',
+  ({ empty, handlers, live, props }) => {
+    test('list() is empty and issues no request', async () => {
+      const fake = getOnlyOrFail(() => {
+        throw new Error('list() must never call the wire at all');
+      });
+      const result = await Effect.runPromise(
+        Effect.provide(handlers.list(), fakeOpnsenseLayer(fake.fetch)),
+      );
+      expect(result).toEqual([]);
+      expect(fake.seen).toHaveLength(0);
+    });
+
+    test('reconcile against a LIVE object still only GETs, then refuses', async () => {
+      const fake = getOnlyOrFail(() => live);
+      const outcome = await Effect.runPromiseExit(
+        Effect.provide(handlers.reconcile({ news: props as never }), fakeHandlersLayer(fake.fetch)),
+      );
+      expect(outcome._tag).toBe('Failure');
+      // ⚠️ Not sufficient alone — `.every()` on an empty array is vacuously true. See the file
+      //   header: without `fakeHandlersLayer`'s ConfigProvider override this assertion never ran
+      //   a single request, because `CredentialsFromEnv` died first. Exactly 1, not just > 0:
+      //   `fetchLive` (alias.ts/category.ts/group.ts) issues one `get()` — matches
+      //   `alias.test.ts`'s own `toHaveLength(1)` and also catches a future double-GET regression.
+      expect(fake.seen).toHaveLength(1);
+      expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+    });
+
+    test('reconcile against an ABSENT object still only GETs, then refuses', async () => {
+      const fake = getOnlyOrFail(() => empty);
+      const outcome = await Effect.runPromiseExit(
+        Effect.provide(handlers.reconcile({ news: props as never }), fakeHandlersLayer(fake.fetch)),
+      );
+      expect(outcome._tag).toBe('Failure');
+      expect(fake.seen).toHaveLength(1);
+      expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+    });
+
+    test('delete makes ZERO requests and refuses', async () => {
+      const fake = getOnlyOrFail(() => live);
+      const outcome = await Effect.runPromiseExit(
+        Effect.provide(handlers.delete({ olds: props as never }), fakeOpnsenseLayer(fake.fetch)),
+      );
+      expect(outcome._tag).toBe('Failure');
+      expect(fake.seen).toHaveLength(0);
+    });
+
+    test('nuke is skipped, so account-wide teardown never even lists this type', () => {
+      expect(handlers.nuke).toEqual({ skip: true });
+    });
+  },
+);

package/src/proxmox/constraints-host-forms.test.ts

@@ -13,7 +13,7 @@ import { constraintsFor, formViolations } from './constraint-guard.ts';
 import type { PbsTarget, PveTarget } from './credentials.ts';
 import { createBody as ifaceCreateForm } from './node-network-form.ts';
 import { resolveGroups, targetForm } from './pbs-notification-target-form.ts';
-import { createForm as zfsCreateForm } from './zfs-pool-write.ts';
+import { createForm as zfsCreateForm } from './zfs-pool-form.ts';
 
 const TARGET: PveTarget = { members: ['pve.test:8006'], mount: 'pve-test', scheme: 'pve' };
 const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };

package/src/proxmox/storage-form.ts

@@ -0,0 +1,144 @@
+/**
+ * `Proxmox.Storage`'s WRITE side: the locator bag, the create/update forms, and the translation
+ * into distilled's own typed request shape. Split out of storage-wire.ts (2026-09-24) to keep
+ * both files under the 250-line cap — the api-token.ts/api-token-form.ts seam, same reasoning.
+ */
+import type * as storage from '@distilled.cloud/proxmox/storage';
+import type { StorageProps } from './storage.ts';
+import { flag } from './values.ts';
+
+export const STORAGE_CREATE = 'pve:POST /storage';
+export const STORAGE_UPDATE = 'pve:PUT /storage/{storage}';
+
+/**
+ * The create-time, plugin-specific half of a storage: `dir` wants `path`, `nfs` `server`+`export`,
+ * `cifs` `server`+`share`, `pbs` `server`+`datastore`, `rbd` `pool`+`monhost`, `lvmthin`
+ * `vgname`+`thinpool`, `zfspool` `pool`. A bag rather than two dozen named fields, because PVE
+ * ships about that many plugins and each brings its own locator. ⚠️ Never diffed — see `matches`
+ * (storage-wire.ts).
+ *
+ * ⛔ `password`, `keyring` AND `encryption-key` ARE `never` ON PURPOSE — see the ⛔ in storage.ts's
+ *   header. POSITIVE-CONTROLLED rather than assumed: all three are a compile error, `TS2322: Type
+ *   'string' is not assignable to type 'undefined'`.
+ * ⚠️ EVERY KEY IN THIS BAG GOES THROUGH `underscored` (below) BEFORE IT REACHES DISTILLED — see
+ *   that function's own header. A caller writes PVE's own field names here (`fs-name`, matching
+ *   `pvesm`/pve-docs), never distilled's renamed ones.
+ */
+export type StorageLocator = Record<string, string> & {
+  password?: never;
+  keyring?: never;
+  'encryption-key'?: never;
+};
+
+const field = (name: string, value: string | undefined): Record<string, string> =>
+  value === undefined ? {} : { [name]: value };
+
+/**
+ * ⚠️ THE CAST DROPS THE THREE `never` GUARDS AND NOTHING ELSE, and it is load-bearing rather than
+ *   lazy: an intersection carrying OPTIONAL properties is not assignable to `Record<string,string>`
+ *   at all, so the guards and the form body cannot both exist without one conversion. At runtime a
+ *   locator is a plain string map; the guards only ever existed to fail a declaration.
+ */
+const locatorForm = (locator: StorageLocator | undefined) =>
+  ({ ...locator }) as Record<string, string>;
+
+/**
+ * ★ ROUTES EVERY OUTGOING FIELD THROUGH DISTILLED'S OWN TYPED PROPERTY, RATHER THAN THROUGH ITS
+ *   "UNKNOWN KEY" FALLBACK — NOT BECAUSE THE WIRE NEEDS THE UNDERSCORED SPELLING. MEASURED both
+ *   ways (`storage-read-failure.test.ts`'s create test, run once with this function and once
+ *   without it): PVE's own hyphenated name (`content-dirs=…`) reaches the wire either way —
+ *   `@distilled.cloud/proxmox`'s generated `T.Body("content-dirs")` annotation re-hyphenates its
+ *   underscored `content_dirs` property on the way out, AND an untranslated hyphenated key also
+ *   passes through unchanged as an "unknown key", form-encoded alongside the recognized ones (the
+ *   GET-request version of that same passthrough is what caused kit 0.31.1's regression — see
+ *   user.ts/group.ts — but a POST/PUT is already body-bearing, so the failure mode there doesn't
+ *   apply). So EITHER path is wire-correct for a plain rename. What `underscored` buys instead:
+ *   distilled's own schema only runs its declared per-field logic (a `T.Body()` rename, but also
+ *   whatever type coercion or list-joining a FUTURE plugin field might carry) for a property it
+ *   recognizes — an unrecognized key gets none of that, silently. `StorageLocator` is free-form
+ *   on purpose (the header's own reasoning), so this file cannot enumerate every field a plugin
+ *   might need; routing through the recognized property is the one way to get distilled's own
+ *   per-field handling for a field this package's author never tried, rather than a bare rename.
+ *   Renamed against every hyphenated field on the generated `CreateStorageRequest`/
+ *   `PutStorageRequest` today (`prune-backups` -> `prune_backups`, `fs-name` -> `fs_name`,
+ *   `max-protected-backups` -> `max_protected_backups`, `zfs-base-path` -> `zfs_base_path`,
+ *   `content-dirs` -> `content_dirs`, `saferemove-stepsize` -> `saferemove_stepsize`, and so on) —
+ *   a generic transform, not a lookup table, for the same free-form reason. No other migrated
+ *   family (acl/group/role/user/api-token) hit any of this: none of their fields are hyphenated.
+ * ⛔ NEVER APPLIED TO THE FORM `guardWrite` CHECKS, REGARDLESS. The generated vendor-constraint
+ *   tables (`generated/constraints/pve-storage.ts`) are keyed by PVE's OWN hyphenated names —
+ *   running this first would make every constraint on `prune-backups`, `fs-name`, etc. silently
+ *   never match, the vendor check passing over a value it never actually inspected. `createForm`/
+ *   `updateForm` stay hyphenated for exactly that reason; only `toDistilledCreate`/
+ *   `toDistilledUpdate` (the actual SDK call, storage.ts's `reconcile`) apply this.
+ */
+const underscored = (form: Record<string, string>): Record<string, string> =>
+  Object.fromEntries(Object.entries(form).map(([key, value]) => [key.replaceAll('-', '_'), value]));
+
+/**
+ * The mutable half, for create and update alike.
+ *
+ * ⚠️ AN UNDECLARED FIELD IS NEITHER SENT NOR COMPARED: undeclared means UNMANAGED here, unlike
+ *   `Proxmox.Pool` where an absent comment means `''`. A storage has no single default to fall back
+ *   on — `content` defaults per plugin, and clearing a field needs an explicit `delete=` parameter
+ *   rather than an empty value — so a guessed default would rewrite a storage somebody tuned by
+ *   hand, and comparing one would report drift nobody declared.
+ *
+ * ⚠️ RECONCILE PUTs UNCONDITIONALLY whenever the object exists (group.ts's own reconcile has the
+ *   same note), so this form must be safe to re-apply to a storage that already matches. It is:
+ *   the declared set and nothing else, and PVE leaves absent parameters alone.
+ *
+ * ★ KEPT HYPHENATED (`'prune-backups'`, PVE's own wire name), NOT DISTILLED'S UNDERSCORED
+ *   `prune_backups` — this form is what `guardWrite` checks (storage.ts), and the generated
+ *   vendor-constraint table is keyed by PVE's own names (`underscored`'s own header has the
+ *   measured evidence). `toDistilledCreate`/`toDistilledUpdate` translate a COPY for the actual
+ *   SDK call; this function and its callers never see the underscored form.
+ */
+const mutable = (props: StorageProps) => ({
+  ...field('comment', props.comment),
+  ...field('content', props.content),
+  ...field('disable', flag(props.disable)),
+  ...field('nodes', props.nodes),
+  ...field('preallocation', props.preallocation),
+  ...field('prune-backups', props['prune-backups']),
+  ...field('shared', flag(props.shared)),
+});
+
+/**
+ * ⚠️ THE BAG IS SPREAD FIRST SO NOTHING IN IT CAN SHADOW A FIELD THIS RESOURCE MANAGES. A stray
+ *   `storage` or `type` in a locator would otherwise rename the object being created, and PVE
+ *   would build the wrong thing under a name Alchemy then records as the declared one.
+ * ★ HYPHENATED, THE WIRE SHAPE — `guardWrite` (storage.ts) checks this form directly; see
+ *   `underscored`'s header for why translating it here would blind that check.
+ */
+export const createForm = (props: StorageProps): Record<string, string> => ({
+  ...locatorForm(props.locator),
+  ...mutable(props),
+  storage: props.storage,
+  type: props.type,
+});
+
+/**
+ * ⚠️ `type` AND THE LOCATOR ARE NEVER SENT ON UPDATE — PVE's PUT refuses the create-only fields
+ *   (`PutStorageRequest` has no `type`, and the plugin locator fields it does carry are for a
+ *   different purpose: moving an existing volume, not re-pointing the definition), and comparing
+ *   either could only plan an update that no write can apply: a plan that reports work forever.
+ */
+export const updateForm = (props: StorageProps): Record<string, string> => ({
+  ...mutable(props),
+  storage: props.storage,
+});
+
+/**
+ * The actual `createStorage` call body — `createForm`, translated once. See `underscored`.
+ * ⚠️ `as unknown as` — same load-bearing cast as `locatorForm`'s own ⚠️: a plain
+ *   `Record<string,string>` does not structurally overlap a named-field interface enough for
+ *   TypeScript to accept a direct cast, even though every field it carries fits one of the
+ *   interface's own (all-optional-but-two) properties.
+ */
+export const toDistilledCreate = (props: StorageProps): storage.CreateStorageRequest =>
+  underscored(createForm(props)) as unknown as storage.CreateStorageRequest;
+
+/** The actual `putStorage` call body — `updateForm`, translated once. See `toDistilledCreate`. */
+export const toDistilledUpdate = (props: StorageProps): storage.PutStorageRequest =>
+  underscored(updateForm(props)) as unknown as storage.PutStorageRequest;