@homeflare/alchemy 0.31.1 → 0.32.0

package/src/proxmox/read-failure-propagation.test.ts

@@ -0,0 +1,183 @@
+/**
+ * The 0.31.1 regression (measured live 2026-09-24, homeflare-proxmox `bun run plan`): every
+ * `Proxmox.User`/`Proxmox.Group` row planned `update` with no warning, because their reads were
+ * silently folding EVERY failure — not only a refused credential — into "absent". Two fixes,
+ * both pinned here with REAL-SHAPED fixtures (live response bodies, nothing secret):
+ *
+ *  1. `access.getAccessUser`/`getAccessGroup` must be called with ONLY the schema's own label
+ *     field, never the whole declared props object — the root cause: distilled's `buildRequest`
+ *     treats every OTHER key as an "unknown key" and attaches it as a JSON body to what must stay
+ *     a bodyless GET, which a stricter fetch client refuses outright.
+ *  2. `diff` must never fold a genuine (non-credential-denial) read failure into "absent" — only
+ *     `read`/`reconcile` may, where a wrongful fold costs at most a redundant, loudly-refused
+ *     create, never a silent wrong write.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { engineOver } from '../verify/fake-engine.ts';
+import { FAKE_TARGET, withoutBao } from './fake-pve.ts';
+import { ProxmoxGroup, ProxmoxGroupProvider } from './group.ts';
+import { ProxmoxUser, ProxmoxUserProvider } from './user.ts';
+
+/**
+ * A fake cluster whose GET on `path` answers 200 with `live`, but REFUSES (500, mimicking PVE's
+ * real "InternalServerError" shape) once `transientFrom` is `true` — and asserts no request ever
+ * carries a body on a GET, the request-shape regression's own signature.
+ */
+const clusterWithTransientFailure = (path: string, live: unknown) => {
+  let transient = false;
+  const stub = async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    if (url.pathname.includes('/creds/')) {
+      const data = { secret: 'fake-secret-not-real', token_id: 'hf-test@pve!fake' };
+      return Response.json({ data, lease_duration: 0 });
+    }
+    if (request.method === 'GET') {
+      const body = await request.text();
+      // ⛔ THE REQUEST-SHAPE REGRESSION'S OWN SIGNATURE: a real fetch client refuses this outright.
+      expect(body).toBe('');
+    }
+    // ⚠️ `decodeURIComponent` — user.ts's own ⚠️: distilled percent-encodes a `{userid}`/
+    //   `{groupid}` label substitution (`tim@pve` -> `tim%40pve`), which a literal `path` compare
+    //   would silently never match, turning every case below into a no-op stub.
+    const wire = decodeURIComponent(url.pathname.replace(/^\/api2\/json\//, ''));
+    if (wire !== path) return Response.json({ data: null });
+    if (transient) {
+      // MEASURED 2026-09-24, live TB4: a missing user/group answers exactly this shape.
+      return Response.json({ data: null, message: `no such object (${path})` }, { status: 500 });
+    }
+    return Response.json({ data: live });
+  };
+  const fetchStub = Object.assign(stub, { preconnect: globalThis.fetch.preconnect });
+  return {
+    breakReads: () => {
+      transient = true;
+    },
+    layer: FetchHttpClient.layer.pipe(
+      Layer.provideMerge(Layer.succeed(FetchHttpClient.Fetch, fetchStub as typeof fetch)),
+    ),
+  };
+};
+
+describe('a transient read failure fails the plan loudly, never a silent false update', () => {
+  test('Proxmox.User: diff() propagates a transient read failure once a state row exists', async () => {
+    // MEASURED 2026-09-24, live TB4 `GET /access/users/tim@pve`.
+    const live = {
+      comment: 'Primary admin — PVE fallback',
+      email: 'tim@schenanigans.com',
+      enable: 1,
+      expire: 0,
+      firstname: 'Timothy',
+      groups: ['Schenanigans'],
+      lastname: 'Schneider',
+      tokens: null,
+    };
+    const declare = () =>
+      ProxmoxUser('tim', {
+        comment: 'Primary admin — PVE fallback',
+        email: 'tim@schenanigans.com',
+        firstname: 'Timothy',
+        groups: ['Schenanigans'],
+        lastname: 'Schneider',
+        target: FAKE_TARGET,
+        userid: 'tim@pve',
+      });
+    const fake = clusterWithTransientFailure('access/users/tim@pve', live);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxUserProvider().pipe(Layer.provideMerge(fake.layer)));
+      // First deploy: adopts the matching account, records a state row.
+      expect(await engine.deploy(declare())).toEqual({ tim: 'adopted' });
+      // Now every read of this account fails the way the live regression measured.
+      fake.breakReads();
+      // ⛔ THE FIX: this must REJECT (fail the plan), never resolve with a false 'update'.
+      await expect(engine.verify(declare(), { all: true })).rejects.toBeDefined();
+    });
+  });
+
+  test('Proxmox.Group: diff() propagates a transient read failure once a state row exists', async () => {
+    // MEASURED 2026-09-24, live TB4 `GET /access/groups/HomeAssistant`.
+    const live = { comment: 'Home Assistant service group', members: [] };
+    const declare = () =>
+      ProxmoxGroup('ha', {
+        comment: 'Home Assistant service group',
+        groupid: 'HomeAssistant',
+        target: FAKE_TARGET,
+      });
+    const fake = clusterWithTransientFailure('access/groups/HomeAssistant', live);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxGroupProvider().pipe(Layer.provideMerge(fake.layer)));
+      expect(await engine.deploy(declare())).toEqual({ ha: 'adopted' });
+      fake.breakReads();
+      await expect(engine.verify(declare(), { all: true })).rejects.toBeDefined();
+    });
+  });
+
+  // ★ A brand-new declaration's own create-from-a-500 path is already covered end to end by
+  //   user.test.ts's `missingAs500` fixture — `readUser`/`readGroup` (used by `reconcile`) kept
+  //   their fold on purpose, exactly so that path stays unaffected by this fix.
+});
+
+describe('the same fix, one command over: alchemy drift never reports a transient failure as missing', () => {
+  // ⛔ FOUND BY ADVERSARIAL REVIEW OF THIS VERY FIX, 2026-09-24 — NOT part of the live-measured
+  //   regression above, but the SAME bug class one layer deeper. `alchemy/src/Drift.ts` (`alchemy
+  //   drift`/`sync`/`deploy --detect-drift`) calls a provider's `read` hook DIRECTLY on an
+  //   already-confirmed row (`output: old.attr`, defined — Drift.ts:239-292), the same situation
+  //   `diff` handles above. Before `user.ts`/`group.ts`'s `read` hook learned to branch on
+  //   `output` (this fix's second half), it ALWAYS called the folding `readUser`/`readGroup` —
+  //   so a transient failure here folded to `undefined`, and Drift.ts's own dry-run branch
+  //   reports that as `{action: 'missing'}` with NO error surfaced at all: a silent false "this
+  //   account is gone" report, worse than the false `update` `diff` used to produce because
+  //   nothing here even logs a warning. `engineOver`'s new `drift` capability
+  //   (verify/fake-engine.ts) drives the real `Alchemy.Drift.detect` over the same fake cluster.
+  test('Proxmox.User: a confirmed row propagates instead of reporting missing', async () => {
+    const live = {
+      comment: 'Primary admin — PVE fallback',
+      email: 'tim@schenanigans.com',
+      enable: 1,
+      expire: 0,
+      firstname: 'Timothy',
+      groups: ['Schenanigans'],
+      lastname: 'Schneider',
+      tokens: null,
+    };
+    const declare = () =>
+      ProxmoxUser('tim', {
+        comment: 'Primary admin — PVE fallback',
+        email: 'tim@schenanigans.com',
+        firstname: 'Timothy',
+        groups: ['Schenanigans'],
+        lastname: 'Schneider',
+        target: FAKE_TARGET,
+        userid: 'tim@pve',
+      });
+    const fake = clusterWithTransientFailure('access/users/tim@pve', live);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxUserProvider().pipe(Layer.provideMerge(fake.layer)));
+      expect(await engine.deploy(declare())).toEqual({ tim: 'adopted' });
+      fake.breakReads();
+      // ⛔ THE FIX: this must REJECT. Before `read`'s `output` branch, it resolved with
+      //   `{ tim: { action: 'missing' } }` and no error anywhere.
+      await expect(engine.drift(declare())).rejects.toBeDefined();
+    });
+  });
+
+  test('Proxmox.Group: a confirmed row propagates instead of reporting missing', async () => {
+    const live = { comment: 'Home Assistant service group', members: [] };
+    const declare = () =>
+      ProxmoxGroup('ha', {
+        comment: 'Home Assistant service group',
+        groupid: 'HomeAssistant',
+        target: FAKE_TARGET,
+      });
+    const fake = clusterWithTransientFailure('access/groups/HomeAssistant', live);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxGroupProvider().pipe(Layer.provideMerge(fake.layer)));
+      expect(await engine.deploy(declare())).toEqual({ ha: 'adopted' });
+      fake.breakReads();
+      await expect(engine.drift(declare())).rejects.toBeDefined();
+    });
+  });
+});

package/src/proxmox/role.ts

@@ -107,7 +107,15 @@ export interface ProxmoxRole extends Resource<
 
 export const ProxmoxRole = Resource<ProxmoxRole>('Proxmox.Role');
 
-/** ★ Default `read` role — see the header's ⚠️ on the list read's privilege requirement. */
+/**
+ * ★ Default `read` role — see the header's ⚠️ on the list read's privilege requirement.
+ * ⛔ NO `orElseSucceed` — found 2026-09-24, the same bug class as the credential denial fix. A
+ *   role's absence is ALWAYS a SUCCESSFUL read (the list comes back and the role is not in it —
+ *   `access.listAccessRoles` never 404s/500s per-role the way `getAccessUser`/`getAccessGroup`
+ *   do, MEASURED), so this family never needed a folding/non-folding split the way user.ts and
+ *   group.ts do: any THROWN failure here is genuinely unexpected and must propagate and fail the
+ *   whole plan loudly, in `diff`, `read` and `reconcile` alike — never fold to "absent → update".
+ */
 const readRole = (props: RoleProps) =>
   readOrUnreadable(runPve(props.target, 'read', false, access.listAccessRoles({}))).pipe(
     Effect.map((rows) => {
@@ -115,7 +123,6 @@ const readRole = (props: RoleProps) =>
       const row = find(rows, props.roleid);
       return row === undefined ? undefined : attributesOf(row, props);
     }),
-    Effect.orElseSucceed(() => undefined),
   );
 
 /** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */

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;

package/src/proxmox/storage-read-failure.test.ts

@@ -0,0 +1,214 @@
+/**
+ * `Proxmox.Storage`'s own cries-wolf fix, PLUS the request-shape and transient-failure fixes
+ * kit 0.31.2 (PR 239) found for User/Group — all three apply here for the first time on a
+ * `provision`-role read, not a `read`-role one. Real-shaped fixtures (live TB4 response bodies,
+ * measured 2026-09-24, nothing secret): `GET /storage/local` -> `{"data":{"storage":"local",
+ * "type":"dir","content":"backup,vztmpl,iso","path":"/var/lib/vz","digest":"..."}}`, and a
+ * missing storage -> `{"message":"storage '...' does not exist\n"}` at HTTP 500, the same shape
+ * user.ts/group.ts measured for a missing user/group.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { engineOver } from '../verify/fake-engine.ts';
+import { FAKE_TARGET, withoutBao } from './fake-pve.ts';
+import { ProxmoxStorage, ProxmoxStorageProvider } from './storage.ts';
+
+/**
+ * One storage row, an OpenBao mint the test can deny for `provision` mid-run (the cries-wolf
+ * case), and a cluster answer the test can break into a transient 500 mid-run (the request-shape
+ * regression's own case) — never both at once, so one fixture serves every test below.
+ */
+const clusterOverStorage = (id: string, live: Record<string, unknown>) => {
+  let denyProvision = false;
+  let transient = false;
+  const stub = async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    if (url.pathname.includes('/creds/')) {
+      if (denyProvision && url.pathname.endsWith('/creds/provision')) {
+        return Response.json({ errors: ['permission denied'] }, { status: 403 });
+      }
+      const data = { secret: 'fake-secret-not-real', token_id: 'hf-test@pve!fake' };
+      return Response.json({ data, lease_duration: 0 });
+    }
+    if (request.method === 'GET') {
+      // ⛔ THE REQUEST-SHAPE REGRESSION'S OWN SIGNATURE (user.ts/group.ts): a real fetch client
+      //   refuses a GET carrying a body outright.
+      expect(await request.text()).toBe('');
+    }
+    const wire = decodeURIComponent(url.pathname.replace(/^\/api2\/json\//, ''));
+    if (wire !== `storage/${id}`) return Response.json({ data: null });
+    if (transient) {
+      // MEASURED 2026-09-24, live TB4: a missing storage answers exactly this shape.
+      return Response.json(
+        { message: `storage '${id}' does not exist\n`, data: null },
+        { status: 500 },
+      );
+    }
+    return Response.json({ data: live });
+  };
+  const fetchStub = Object.assign(stub, { preconnect: globalThis.fetch.preconnect });
+  return {
+    breakReads: () => {
+      transient = true;
+    },
+    denyProvision: () => {
+      denyProvision = true;
+    },
+    layer: FetchHttpClient.layer.pipe(
+      Layer.provideMerge(Layer.succeed(FetchHttpClient.Fetch, fetchStub as typeof fetch)),
+    ),
+  };
+};
+
+// MEASURED 2026-09-24, live TB4 `GET /storage/local`.
+const live = { content: 'backup,vztmpl,iso', storage: 'local', type: 'dir' };
+const declare = () =>
+  ProxmoxStorage('local', {
+    content: 'backup,vztmpl,iso',
+    storage: 'local',
+    target: FAKE_TARGET,
+    type: 'dir',
+  });
+
+describe("Proxmox.Storage's own cries-wolf fix: a refused provision mint reports noop, never update", () => {
+  test('an already-correct storage plans noop once the credential is denied, and nothing is written', async () => {
+    const fake = clusterOverStorage('local', live);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxStorageProvider().pipe(Layer.provideMerge(fake.layer)));
+      expect(await engine.deploy(declare())).toEqual({ local: 'adopted' });
+      fake.denyProvision();
+      const report = await engine.verify(declare(), { all: true });
+      // ⛔ THE BUG THIS PROVES FIXED — MEASURED live 2026-09-24: before this migration this row
+      //   read `update` with nothing compared, the same as every other family before its fix.
+      expect(report.rows[0]).toMatchObject({ diff: 'noop' });
+      expect(await engine.deploy(declare())).toEqual({ local: 'noop' });
+    });
+  });
+});
+
+describe('the same request-shape and transient-failure fixes, once for Proxmox.Storage', () => {
+  test('diff() propagates a transient read failure once a state row exists', async () => {
+    const fake = clusterOverStorage('local', live);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxStorageProvider().pipe(Layer.provideMerge(fake.layer)));
+      expect(await engine.deploy(declare())).toEqual({ local: 'adopted' });
+      fake.breakReads();
+      // ⛔ THE FIX: this must REJECT, never resolve with a false 'update'.
+      await expect(engine.verify(declare(), { all: true })).rejects.toBeDefined();
+    });
+  });
+
+  test('alchemy drift never reports a transient failure as missing', async () => {
+    const fake = clusterOverStorage('local', live);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxStorageProvider().pipe(Layer.provideMerge(fake.layer)));
+      expect(await engine.deploy(declare())).toEqual({ local: 'adopted' });
+      fake.breakReads();
+      // ⛔ THE FIX: this must REJECT. Without `read`'s `output` branch it resolved with
+      //   `{ local: { action: 'missing' } }` and no error anywhere — user.ts's/group.ts's own gap.
+      await expect(engine.drift(declare())).rejects.toBeDefined();
+    });
+  });
+});
+
+/**
+ * A fake cluster for a storage that does NOT exist yet: every GET is a 500 ("does not exist",
+ * the measured shape) until `create()` fires, which records the POST body and starts answering
+ * `live` afterward — so `reconcile`'s `before === undefined` branch, untouched by every test
+ * above, actually runs.
+ */
+const clusterCreatingStorage = (id: string, live: Record<string, unknown>) => {
+  let created = false;
+  const posted: string[] = [];
+  const stub = async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    if (url.pathname.includes('/creds/')) {
+      const data = { secret: 'fake-secret-not-real', token_id: 'hf-test@pve!fake' };
+      return Response.json({ data, lease_duration: 0 });
+    }
+    const wire = decodeURIComponent(url.pathname.replace(/^\/api2\/json\//, ''));
+    if (request.method === 'POST' && wire === 'storage') {
+      posted.push(await request.text());
+      created = true;
+      return Response.json({ data: null });
+    }
+    if (wire !== `storage/${id}`) return Response.json({ data: null });
+    if (!created) {
+      return Response.json(
+        { message: `storage '${id}' does not exist\n`, data: null },
+        { status: 500 },
+      );
+    }
+    return Response.json({ data: live });
+  };
+  const fetchStub = Object.assign(stub, { preconnect: globalThis.fetch.preconnect });
+  return {
+    posted,
+    layer: FetchHttpClient.layer.pipe(
+      Layer.provideMerge(Layer.succeed(FetchHttpClient.Fetch, fetchStub as typeof fetch)),
+    ),
+  };
+};
+
+describe('reconcile creating a brand-new storage — the before === undefined branch', () => {
+  // ⛔ FOUND BY ADVERSARIAL REVIEW OF THIS PR: every test above adopts an EXISTING storage, so
+  //   `reconcile`'s create branch (`toDistilledCreate`, the hyphen -> underscore translation) was
+  //   never actually exercised — "correct by reading the generated SDK source", not by a test.
+  test('translates a hyphenated locator field for the actual SDK call, not the vendor-check form', async () => {
+    const newLive = {
+      content: 'iso',
+      'content-dirs': 'iso=/mnt/hf-test-new/iso',
+      storage: 'hf-test-new',
+      type: 'dir',
+    };
+    const fake = clusterCreatingStorage('hf-test-new', newLive);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxStorageProvider().pipe(Layer.provideMerge(fake.layer)));
+      const declareNew = () =>
+        ProxmoxStorage('newone', {
+          content: 'iso',
+          locator: { 'content-dirs': 'iso=/mnt/hf-test-new/iso', path: '/mnt/hf-test-new' },
+          storage: 'hf-test-new',
+          target: FAKE_TARGET,
+          type: 'dir',
+        });
+      expect(await engine.deploy(declareNew())).toEqual({ newone: 'create' });
+      expect(fake.posted).toHaveLength(1);
+      // ★ MEASURED, NOT ASSUMED: the wire itself carries PVE's own hyphenated `content-dirs=`
+      //   either way — distilled's generated `T.Body("content-dirs")` annotation re-hyphenates
+      //   its underscored `content_dirs` property on the way out, and (confirmed by temporarily
+      //   removing `underscored()` and re-running this exact test) an untranslated hyphenated key
+      //   also reaches the wire unchanged as a passthrough "unknown key". `underscored()` is not
+      //   about THIS field's own wire spelling, then — it is about routing every locator field
+      //   through distilled's typed, declared property (comment further up `toDistilledCreate`),
+      //   rather than the weaker unknown-key fallback, for whatever OTHER per-field wire logic a
+      //   future plugin field might carry beyond a plain rename (a type coercion, a list join) —
+      //   which this test cannot rule out for every field distilled might ever add.
+      expect(fake.posted[0]).toContain('content-dirs=iso');
+    });
+  });
+
+  test('a vendor-constraint violation on a hyphenated field is refused before any write', async () => {
+    const fake = clusterCreatingStorage('hf-test-bad', {});
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxStorageProvider().pipe(Layer.provideMerge(fake.layer)));
+      const declareBad = () =>
+        ProxmoxStorage('bad', {
+          // ⛔ `saferemove-stepsize` only allows 1/2/4/8/16/32 (generated/constraints/pve-storage.ts)
+          //   — '99' must be refused by `guardWrite`, which proves it inspected the HYPHENATED
+          //   key `createForm` builds, not the underscored one only the SDK call ever sees.
+          locator: { path: '/mnt/hf-test-bad', 'saferemove-stepsize': '99' },
+          storage: 'hf-test-bad',
+          target: FAKE_TARGET,
+          type: 'dir',
+        });
+      await expect(engine.deploy(declareBad())).rejects.toBeDefined();
+      expect(fake.posted).toHaveLength(0);
+    });
+  });
+});