@homeflare/alchemy 0.40.0 → 0.42.0

package/src/proxmox/storage-update.test.ts

@@ -0,0 +1,183 @@
+/**
+ * `Proxmox.Storage`'s partial-update fix. Measured 2026-09-27, `bun run deploy`: PVE's PUT
+ * /storage/{storage} refused `storage-cephfs-tb4`'s update with `unexpected property 'shared'`,
+ * because `reconcile` used to PUT the FULL declared set whenever anything drifted — including a
+ * `shared` that already matched live, which cephfs's own plugin `options()` never accepts at all
+ * (storage-plugin-options.ts has the vendor citation). storage-form.ts's `updateForm` now sends
+ * only the fields that actually differ from a live read; these tests prove the PUT body shape
+ * directly, never touching a real PVE cluster.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { FAKE_TARGET, type PveCall, fakePve, withoutBao } from './fake-pve.ts';
+import { createForm } from './storage-form.ts';
+import { ProxmoxStorage, ProxmoxStorageProvider } from './storage.ts';
+
+type Live = Record<string, string>;
+
+/** `storage` (POST) and `storage/{id}` (GET/PUT), keyed by storage id — group.test.ts's shape. */
+const cluster = (stores: Map<string, Live>) =>
+  fakePve((call: PveCall) => {
+    const match = /^storage(?:\/(.+))?$/.exec(call.path);
+    if (match === null) return undefined;
+    const id = match[1];
+    if (call.method === 'GET' && id !== undefined) return stores.get(id);
+    if (call.method === 'PUT' && id !== undefined) {
+      const live = stores.get(id);
+      if (live !== undefined) stores.set(id, { ...live, ...call.form });
+    }
+    return undefined;
+  });
+
+const engineFor = (fake: ReturnType<typeof cluster>) =>
+  engineOver(ProxmoxStorageProvider().pipe(Layer.provideMerge(fake.layer)));
+
+describe('Proxmox.Storage update: a partial PUT, never a property the type refuses', () => {
+  test('a cephfs storage whose only drift is content: PUT carries content and the id, never shared', async () => {
+    // MEASURED SHAPE: live already reports `shared: '1'` (cephfs is implicitly shared) and the
+    // declaration agrees — only `content` (Talos's `import`, the change that triggered the bug)
+    // actually differs.
+    const stores = new Map<string, Live>([
+      ['cephfs-tb4', { content: 'backup', shared: '1', storage: 'cephfs-tb4', type: 'cephfs' }],
+    ]);
+    const fake = cluster(stores);
+    const declare = () =>
+      ProxmoxStorage('cephfs', {
+        content: 'backup,import',
+        shared: true,
+        storage: 'cephfs-tb4',
+        target: FAKE_TARGET,
+        type: 'cephfs',
+      });
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const report = await engine.verify(declare());
+      expect(report.rows[0]).toMatchObject({ diff: 'update' });
+      expect(await engine.deploy(declare())).toEqual({ cephfs: 'adopted' });
+    });
+    // ⚠️ `storage` NAMES THE OBJECT VIA THE PUT'S OWN PATH (`storage/cephfs-tb4` here), NOT A
+    //   BODY FIELD — distilled routes it as a path label (distilled-doctrine: Label -> path), so
+    //   it never reaches `call.form`. `fake.writes()` is what proves the id.
+    expect(fake.writes()).toEqual(['PUT storage/cephfs-tb4']);
+    // ⛔ THE BUG THIS PROVES FIXED: before this fix the body was the full declared set, `shared`
+    //   included — exactly what PVE refused with "unexpected property 'shared'".
+    expect(fake.calls.find((call) => call.method === 'PUT')?.form).toEqual({
+      content: 'backup,import',
+    });
+  });
+
+  test('no drift at all: no PUT is sent', async () => {
+    const stores = new Map<string, Live>([
+      ['cephfs-tb4', { content: 'backup,import', storage: 'cephfs-tb4', type: 'cephfs' }],
+    ]);
+    const fake = cluster(stores);
+    const declare = () =>
+      ProxmoxStorage('cephfs', {
+        content: 'backup,import',
+        storage: 'cephfs-tb4',
+        target: FAKE_TARGET,
+        type: 'cephfs',
+      });
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const report = await engine.verify(declare());
+      expect(report.rows[0]).toMatchObject({ diff: 'noop' });
+      // ⚠️ `'adopted'`, NOT `'noop'` — a first deploy of a matching object is always reported
+      //   `adopted` (adopt-verify.md's own note on Plan.ts/Apply.ts: "the node is adopted either
+      //   way"). The provider's own `diff` (asserted above) is what proves nothing changed;
+      //   `fake.writes()` below is what proves `reconcile` actually wrote nothing.
+      expect(await engine.deploy(declare())).toEqual({ cephfs: 'adopted' });
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('a dir storage DOES accept `shared` on update: the PUT carries it', async () => {
+    // VENDOR EVIDENCE (storage-plugin-options.ts): `DirPlugin.pm`'s own `options()` names
+    // `shared => { optional => 1 }`, unlike cephfs — this is the "one more type" contrast case.
+    const stores = new Map<string, Live>([
+      ['local-extra', { content: 'iso', shared: '0', storage: 'local-extra', type: 'dir' }],
+    ]);
+    const fake = cluster(stores);
+    const declare = () =>
+      ProxmoxStorage('dir', {
+        content: 'iso',
+        shared: true,
+        storage: 'local-extra',
+        target: FAKE_TARGET,
+        type: 'dir',
+      });
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      expect(await engine.deploy(declare())).toEqual({ dir: 'adopted' });
+    });
+    expect(fake.writes()).toEqual(['PUT storage/local-extra']);
+    expect(fake.calls.find((call) => call.method === 'PUT')?.form).toEqual({ shared: '1' });
+  });
+});
+
+/**
+ * PR 314's own red team (2026-09-27, Important finding): `changedProps` above leaves `shared`
+ * out of its result for any type outside `sharedAccepted`, on purpose — but that means a
+ * genuinely disagreeing declared value would otherwise vanish into an empty diff and report
+ * `noop` forever, with the recorded attribute silently stuck on whatever PVE already has. These
+ * two tests prove `matches` (storage-wire.ts) catches exactly that one case and no other.
+ */
+describe('a declared `shared` a type can never apply dies the plan, never noops forever', () => {
+  test('zfspool (never accepts shared): a genuine disagreement dies rather than reporting noop', async () => {
+    const stores = new Map<string, Live>([
+      ['speed', { content: 'images', shared: '0', storage: 'speed', type: 'zfspool' }],
+    ]);
+    const fake = cluster(stores);
+    const declare = () =>
+      ProxmoxStorage('speed', {
+        content: 'images',
+        shared: true,
+        storage: 'speed',
+        target: FAKE_TARGET,
+        type: 'zfspool',
+      });
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await expect(engine.verify(declare())).rejects.toBeDefined();
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('zfspool: a declared shared that already agrees with live still plans noop, not a die', async () => {
+    const stores = new Map<string, Live>([
+      ['speed', { content: 'images', shared: '0', storage: 'speed', type: 'zfspool' }],
+    ]);
+    const fake = cluster(stores);
+    const declare = () =>
+      ProxmoxStorage('speed', {
+        content: 'images',
+        shared: false,
+        storage: 'speed',
+        target: FAKE_TARGET,
+        type: 'zfspool',
+      });
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const report = await engine.verify(declare());
+      expect(report.rows[0]).toMatchObject({ diff: 'noop' });
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+});
+
+/** PR 314's own red team (Minor finding): the create path's own `shared` gate had no test. */
+describe('createForm: `shared` is gated by type on create too, not only on update', () => {
+  test('a declared shared is dropped for cephfs, rbd and pbs, kept for dir, lvm, btrfs and esxi', () => {
+    for (const type of ['dir', 'lvm', 'btrfs', 'esxi']) {
+      expect(createForm({ shared: true, storage: 's', target: FAKE_TARGET, type })).toMatchObject({
+        shared: '1',
+      });
+    }
+    for (const type of ['cephfs', 'rbd', 'pbs']) {
+      expect(
+        createForm({ shared: true, storage: 's', target: FAKE_TARGET, type }),
+      ).not.toHaveProperty('shared');
+    }
+  });
+});

package/src/proxmox/storage-wire.ts

@@ -7,6 +7,8 @@
 import * as storage from '@distilled.cloud/proxmox/storage';
 import * as Effect from 'effect/Effect';
 import { runPve } from './distilled-pve.ts';
+import { sharedAccepted } from './storage-plugin-options.ts';
+import type { MutableFields } from './storage-form.ts';
 import type { StorageProps } from './storage.ts';
 import { UNREADABLE, type Unreadable, readOrUnreadable } from './unreadable-read.ts';
 import { bool } from './values.ts';
@@ -109,15 +111,60 @@ export const readStorage = (props: StorageProps) =>
 export const dropUnreadable = (live: StorageAttributes | Unreadable | undefined) =>
   live === UNREADABLE ? undefined : live;
 
+/**
+ * The declared fields (of the 7 `mutable()` — storage-form.ts — ever writes) whose value
+ * genuinely differs from what PVE just reported. `matches` below and storage-form.ts's
+ * `updateForm` share this one comparison, so the plan's noop/update verdict and the partial PUT
+ * body it sends can never disagree about what "changed" means for a list, a boolean or `shared`.
+ *
+ * ⛔ `shared` IS SKIPPED ENTIRELY FOR A TYPE THAT DOESN'T ACCEPT IT (storage-plugin-options.ts's
+ *   `sharedAccepted`, vendor-cited there) — the same treatment `type` already gets below
+ *   (create-only, never compared) and for the identical reason: PVE will never apply a `shared`
+ *   PUT for cephfs/rbd/zfspool/… (it 500s, `unexpected property 'shared'` — the bug this family
+ *   shipped with, measured 2026-09-27), so comparing it against a live value that can never move
+ *   to match could only ever report `update` forever. Without this skip, `mutable()`'s own gate
+ *   (storage-form.ts) would still keep `shared` out of the wire body, but `matches` would keep
+ *   reporting drift for a field nothing can ever apply — a plan that never reaches noop.
+ */
+export const changedProps = (
+  live: StorageAttributes,
+  props: StorageProps,
+): Partial<MutableFields> => ({
+  ...(sameList(props.content, live.content) ? {} : { content: props.content }),
+  ...(sameList(props.nodes, live.nodes) ? {} : { nodes: props.nodes }),
+  ...(sameList(props['prune-backups'], live['prune-backups'])
+    ? {}
+    : { 'prune-backups': props['prune-backups'] }),
+  ...(same(props.disable, live.disable) ? {} : { disable: props.disable }),
+  ...(sharedAccepted(props.type) && !same(props.shared, live.shared)
+    ? { shared: props.shared }
+    : {}),
+  ...(same(props.preallocation, live.preallocation) ? {} : { preallocation: props.preallocation }),
+  ...(same(props.comment, live.comment) ? {} : { comment: props.comment }),
+});
+
 /**
  * ⚠️ `type` IS NEVER COMPARED — CREATE-ONLY (`storage.ts`'s own `StorageProps.type` doc), so a
  *   changed declaration plans `noop` on it, same as before the migration.
+ *
+ * ⛔ A DECLARED `shared` A TYPE CAN NEVER APPLY MUST FAIL LOUD, NOT NOOP FOREVER — PR 314's own
+ *   red team, 2026-09-27. `changedProps` above leaves `shared` out of its result whenever the
+ *   type is outside `sharedAccepted`, on purpose (PVE 500s on the PUT otherwise) — but that
+ *   means a genuinely disagreeing declared value would otherwise vanish into an empty diff and
+ *   report `noop` forever, with the recorded attribute silently stuck on whatever PVE already
+ *   has. `maxfiles` (storage.ts's header) refuses that same class of bug at compile time; this is
+ *   the update-time equivalent for a field that can't be typed away. So this checks the ONE case
+ *   `changedProps` deliberately can't see — declared and live actually differ, on a type that can
+ *   never carry the write — and dies with a message naming the fix, before `changedProps` runs.
  */
 export const matches = (attributes: StorageAttributes, props: StorageProps) =>
-  sameList(props.content, attributes.content) &&
-  sameList(props.nodes, attributes.nodes) &&
-  sameList(props['prune-backups'], attributes['prune-backups']) &&
-  same(props.disable, attributes.disable) &&
-  same(props.shared, attributes.shared) &&
-  same(props.preallocation, attributes.preallocation) &&
-  same(props.comment, attributes.comment);
+  !sharedAccepted(props.type) && !same(props.shared, attributes.shared)
+    ? Effect.die(
+        new Error(
+          `storage/${props.storage}: declared shared: ${String(props.shared)}, but PVE reports ` +
+            `${String(attributes.shared)} and '${props.type}' storages never accept a 'shared' ` +
+            'write (storage-plugin-options.ts) -- remove the declared shared or set it to match ' +
+            'what PVE already reports; this value can never be applied.',
+        ),
+      )
+    : Effect.succeed(Object.keys(changedProps(attributes, props)).length === 0);

package/src/proxmox/storage.ts

@@ -86,6 +86,7 @@ import {
   updateForm,
 } from './storage-form.ts';
 import { dropUnreadable, matches, readStorage, readStorageOrFail } from './storage-wire.ts';
+import { mintTier } from './credentials.ts';
 import { UNREADABLE, unreadableWarning } from './unreadable-read.ts';
 import type { StorageAttributes } from './storage-wire.ts';
 import type { StorageLocator } from './storage-form.ts';
@@ -112,7 +113,12 @@ export interface StorageProps extends WithTarget {
   nodes?: string;
   /** Keeps the definition but stops PVE using it. */
   disable?: boolean;
-  /** Tells PVE the same volumes are visible from every node — a claim, not a mechanism. */
+  /**
+   * Tells PVE the same volumes are visible from every node — a claim, not a mechanism.
+   * ⚠️ ONLY SENT WHEN THE TYPE'S OWN PLUGIN ACCEPTS IT (storage-plugin-options.ts, vendor-cited)
+   *   — elsewhere it is dropped from the wire, and a disagreeing declared value dies the plan
+   *   loud (storage-wire.ts's `matches`) rather than PUTting a field PVE would refuse outright.
+   */
   shared?: boolean;
   /** `off` | `metadata` | `falloc` | `full`. File-based plugins only. */
   preallocation?: string;
@@ -166,7 +172,9 @@ export const ProxmoxStorageProvider = () =>
         diff: Effect.fn(function* ({ news, output }) {
           if (!isResolved(news)) return undefined;
           yield* guardWrite(STORAGE_CREATE, createForm(news), output === undefined);
-          yield* guardWrite(STORAGE_UPDATE, updateForm(news), false);
+          // ⚠️ `live: undefined`: no read yet, so this only sanity-checks the FULL declared set
+          //   (storage-form.ts's `updateForm` doc) — `reconcile` builds the actual partial body.
+          yield* guardWrite(STORAGE_UPDATE, updateForm(news, undefined), false);
           if (output === undefined) return undefined;
           // ⚠️ `readStorageOrFail`, NOT `readStorage` — see that function's own ⛔ in
           //   storage-wire.ts. A genuine TRANSIENT failure here propagates and fails the whole
@@ -175,14 +183,19 @@ export const ProxmoxStorageProvider = () =>
           // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and force
           //   `update` on a storage that was plainly there — see unreadable-read.ts.
           if (live === UNREADABLE) {
-            yield* unreadableWarning('Proxmox.Storage', news.storage);
+            yield* unreadableWarning(
+              'Proxmox.Storage',
+              news.storage,
+              news.target.mount,
+              mintTier(news.target, 'provision'),
+            );
             return { action: 'noop' } as const;
           }
           if (live === undefined) {
             yield* guardWrite(STORAGE_CREATE, createForm(news), true);
             return { action: 'update' } as const;
           }
-          return matches(live, news)
+          return (yield* matches(live, news))
             ? ({ action: 'noop' } as const)
             : ({ action: 'update' } as const);
         }),
@@ -192,7 +205,12 @@ export const ProxmoxStorageProvider = () =>
           //   handles — group.ts's/user.ts's reconcile have the same note.
           const before = dropUnreadable(yield* readStorage(news));
           yield* guardWrite(STORAGE_CREATE, createForm(news), before === undefined);
-          yield* guardWrite(STORAGE_UPDATE, updateForm(news), false);
+          // ★ COMPUTED ONCE, THEN REUSED FOR BOTH THE GUARD AND THE WRITE — storage-form.ts's own
+          //   ⚠️ on `toDistilledUpdate`: `update` is the partial body (only fields that differ
+          //   from `before`, and never `shared` for a type that doesn't accept it), so the
+          //   constraint check below inspects exactly what the PUT, if any, will carry.
+          const update = updateForm(news, before);
+          yield* guardWrite(STORAGE_UPDATE, update, false);
           if (before === undefined) {
             yield* runPve(
               news.target,
@@ -200,12 +218,12 @@ export const ProxmoxStorageProvider = () =>
               true,
               storage.createStorage(toDistilledCreate(news)),
             );
-          } else if (!matches(before, news)) {
+          } else if (!(yield* matches(before, news))) {
             yield* runPve(
               news.target,
               'provision',
               true,
-              storage.putStorage(toDistilledUpdate(news)),
+              storage.putStorage(toDistilledUpdate(update)),
             );
           }
           const after = dropUnreadable(yield* readStorage(news));

package/src/proxmox/unreadable-read.ts

@@ -51,10 +51,22 @@ export const readOrUnreadable = <A, E, R>(
  * in `bun run plan`'s own output (Effect's default logger), even though the Diff type has
  * nowhere to carry the distinction through to the printed action. See the header for why a log
  * line, not a failed diff or a fourth Diff action, is what "the plan reports" means here.
+ *
+ * ⛔ M6 (Opus red team, K-T1): NAMES `mount` AND `tier`, NOT JUST THE RESOURCE. Before this, the
+ *   line read "no grant for this credential's role" with nothing to act on — an operator debugging
+ *   a scoped-down `PveTarget.roles` override (the whole point of K-T1) had to go re-derive which
+ *   mount and tier the read actually asked OpenBao for before they could even open that mount's
+ *   policy. `PveCredentialDenied`'s own message already made this exact call — reading `tier`, not
+ *   `role`, per that class's own ⛔ — so this warning takes the same two fields for the same reason.
  */
-export const unreadableWarning = (type: string, identity: string): Effect.Effect<void> =>
+export const unreadableWarning = (
+  type: string,
+  identity: string,
+  mount: string,
+  tier: string,
+): Effect.Effect<void> =>
   Effect.logWarning(
-    `${type} ${identity}: the read was refused (no grant for this credential's role) -- ` +
-      'reporting noop rather than forcing an update with nothing compared. Re-plan on a lane ' +
-      'that can read this object before trusting this row.',
+    `${type} ${identity}: the read of ${mount}/creds/${tier} was refused (no grant for this ` +
+      "credential's role) -- reporting noop rather than forcing an update with nothing compared. " +
+      'Re-plan on a lane that can read this object before trusting this row.',
   );

package/src/proxmox/user.ts

@@ -60,6 +60,7 @@ import * as Effect from 'effect/Effect';
 import { guardWrite } from './distilled-guard.ts';
 import type { PveRequirements, WithTarget } from './resource-spec.ts';
 import { runPve } from './distilled-pve.ts';
+import { mintTier } from './credentials.ts';
 import { UNREADABLE, unreadableWarning } from './unreadable-read.ts';
 import {
   USER_CREATE,
@@ -162,7 +163,12 @@ export const ProxmoxUserProvider = () =>
           // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and force
           //   `update` on an account that was plainly there — see unreadable-read.ts.
           if (live === UNREADABLE) {
-            yield* unreadableWarning('Proxmox.User', news.userid);
+            yield* unreadableWarning(
+              'Proxmox.User',
+              news.userid,
+              news.target.mount,
+              mintTier(news.target, 'read'),
+            );
             return { action: 'noop' } as const;
           }
           if (live === undefined) {

package/src/proxmox/zfs-pool.ts

@@ -78,6 +78,7 @@ import * as Effect from 'effect/Effect';
 import { asForm } from './distilled-guard.ts';
 import { guardForm } from './constraint-guard.ts';
 import type { PveRequirements, WithTarget } from './resource-spec.ts';
+import { mintTier } from './credentials.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';
@@ -202,7 +203,12 @@ export const ProxmoxZfsPoolProvider = () =>
           //   update, the cries-wolf class of bug.
           const live = yield* readPoolOrFail(news);
           if (live === UNREADABLE) {
-            yield* unreadableWarning('Proxmox.ZfsPool', `${news.node}/${news.name}`);
+            yield* unreadableWarning(
+              'Proxmox.ZfsPool',
+              `${news.node}/${news.name}`,
+              news.target.mount,
+              mintTier(news.target, 'read'),
+            );
             return { action: 'noop' } as const;
           }
           // ⛔ FOUND WRITING THIS FILE, 2026-09-24 — an earlier edit that removed the dead

package/src/release/index.ts

@@ -37,6 +37,7 @@ export { VICTORIA_RELEASES } from './victoria.ts';
 export type {
   ExecResult,
   FileStat,
+  HostPlatform,
   HostRunner,
   HostUser,
   WriteOptions,