@homeflare/alchemy 0.31.1 → 0.31.2

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/user-wire.ts

@@ -1,10 +1,13 @@
 /**
- * `Proxmox.User`'s wire shape: PVE's create/update forms and how a live item becomes
- * attributes. Split out of user.ts (2026-09-24, the distilled migration) to keep that file
- * under the 250-line cap — the api-token.ts/api-token-form.ts seam.
+ * `Proxmox.User`'s wire shape: PVE's create/update forms, how a live item becomes attributes,
+ * and the read itself. Split out of user.ts (2026-09-24, the distilled migration) to keep that
+ * file under the 250-line cap — the api-token.ts/api-token-form.ts seam.
  */
-import type * as access from '@distilled.cloud/proxmox/access';
+import * as access from '@distilled.cloud/proxmox/access';
+import * as Effect from 'effect/Effect';
+import { runPve } from './distilled-pve.ts';
 import type { UserAttributes, UserProps } from './user.ts';
+import { UNREADABLE, type Unreadable, readOrUnreadable } from './unreadable-read.ts';
 import { bool, text } from './values.ts';
 
 export const USER_CREATE = 'pve:POST /access/users';
@@ -77,10 +80,7 @@ export const updateForm = (props: UserProps): access.PutAccessUserRequest => ({
   userid: props.userid,
 });
 
-export const attributesOf = (
-  live: access.GetAccessUserResponse,
-  props: UserProps,
-): UserAttributes => ({
+const attributesOf = (live: access.GetAccessUserResponse, props: UserProps): UserAttributes => ({
   comment: text(live.comment),
   email: text(live.email),
   /**
@@ -110,3 +110,39 @@ export const matches = (attributes: UserAttributes, props: UserProps) =>
   attributes.firstname === (props.firstname ?? '') &&
   attributes.lastname === (props.lastname ?? '') &&
   attributes.groups.join(',') === groupSet(props.groups).join(',');
+
+/**
+ * ★ Default `read` role for this family — only the write side needs `provision`.
+ * ⛔ `{ userid: props.userid }`, NEVER THE WHOLE `props` — MEASURED 2026-09-24, the regression in
+ *   kit 0.31.1. `GetAccessUserRequest`'s schema declares only `userid` (a path label); any OTHER
+ *   key on the object passed to `access.getAccessUser` — `target`, `comment`, every field this
+ *   family's own props carry — is treated by distilled's `buildRequest` as an "unknown key" and
+ *   JSON-encoded onto the request as a BODY, on every one of these bodyless GETs. A stricter
+ *   fetch client than a bare `bun run` of this file refuses a GET carrying any body at all
+ *   (`TypeError [ERR_INVALID_ARG_VALUE]: fetch() request with GET/HEAD method cannot have body`),
+ *   which `runPveWith` retries across every member and exhausts identically —
+ *   `PveClusterExhausted`, then silently folded to "absent" by the old `orElseSucceed`, forcing a
+ *   false `update` on every account.
+ */
+export const readUserOrFail = (props: UserProps) =>
+  readOrUnreadable(
+    runPve(props.target, 'read', false, access.getAccessUser({ userid: props.userid })),
+  ).pipe(Effect.map((live) => (live === UNREADABLE ? UNREADABLE : attributesOf(live, props))));
+
+/**
+ * ⛔ FOLDS A GENUINE READ FAILURE TO `undefined` TOO, AND ONLY `read`/`reconcile` MAY USE IT. A
+ *   missing user is a thrown 500 (user.ts's own header), so `reconcile`'s create branch NEEDS
+ *   "absent" from a failure to ever run — without this fold, a brand-new account could never be
+ *   created. Safe here because a wrongful fold costs at most a redundant `createAccessUser` POST,
+ *   which PVE refuses loudly rather than silently corrupting anything.
+ * ⛔ `user.ts`'s `diff` does **NOT** use this — the SAME bug class as the credential denial fix:
+ *   folding a TRANSIENT failure into "absent" at PLAN TIME is what forced a false `update` with
+ *   nothing compared. `diff` calls `readUserOrFail` directly, so a genuine failure there
+ *   propagates and fails the whole plan loudly instead.
+ */
+export const readUser = (props: UserProps) =>
+  readUserOrFail(props).pipe(Effect.orElseSucceed(() => undefined));
+
+/** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */
+export const dropUnreadable = (live: UserAttributes | Unreadable | undefined) =>
+  live === UNREADABLE ? undefined : live;

package/src/proxmox/user.ts

@@ -33,12 +33,12 @@
  *       user, so a role wide enough to edit the account can still be refused for one group.
  *     · `Sys.Audit` (or `User.Modify`) for the read, which the `read` role's auditor already has.
  *
- * ⚠️ A MISSING USER IS A 500, NOT A 404 — "no such user ('x@pve')". distilled turns that into an
- *   `UnknownProxmoxError` (protocol.ts), and `readOrUnreadable`'s own `orElseSucceed` folds it
- *   into "absent" same as the old hand-rolled client did. A 403 therefore also reads as absent
- *   UNLESS it is the one refusal `readOrUnreadable` catches (unreadable-read.ts): a REFUSED
- *   `provision` mint, the cries-wolf case. Any other refusal still reads as absent, and the
- *   honest error arrives one step later, from the create.
+ * ⚠️ A MISSING USER IS A 500, NOT A 404 — MEASURED against the live cluster, "no such user
+ *   ('x@pve')". distilled turns that into an `InternalServerError`, with no distinct "not found"
+ *   tag to catch. `user-wire.ts`'s `readUser` (used by `read`/`reconcile`, where the create
+ *   workflow needs "absent" from exactly this failure) still folds it; `readUserOrFail` (used by
+ *   `diff` below) does not — see that function's own header for why folding it there was the
+ *   cries-wolf bug all over again, just for a genuine PVE quirk instead of a permission denial.
  *
  * ⚠️ THE WIRE URL FOR THIS FAMILY CHANGED, THOUGH NOTHING A CALLER SEES DID. MEASURED
  *   (user.test.ts): distilled's `{userid}` label substitution percent-encodes it —
@@ -60,18 +60,15 @@ 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 {
-  UNREADABLE,
-  type Unreadable,
-  readOrUnreadable,
-  unreadableWarning,
-} from './unreadable-read.ts';
+import { UNREADABLE, unreadableWarning } from './unreadable-read.ts';
 import {
   USER_CREATE,
   USER_UPDATE,
-  attributesOf,
   createForm,
+  dropUnreadable,
   matches,
+  readUser,
+  readUserOrFail,
   updateForm,
 } from './user-wire.ts';
 
@@ -126,17 +123,6 @@ export interface ProxmoxUser extends Resource<
 
 export const ProxmoxUser = Resource<ProxmoxUser>('Proxmox.User');
 
-/** ★ Default `read` role for this family — only the write side needs `provision`. */
-const readUser = (props: UserProps) =>
-  readOrUnreadable(runPve(props.target, 'read', false, access.getAccessUser(props))).pipe(
-    Effect.map((live) => (live === UNREADABLE ? UNREADABLE : attributesOf(live, props))),
-    Effect.orElseSucceed(() => undefined),
-  );
-
-/** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */
-const dropUnreadable = (live: UserAttributes | Unreadable | undefined) =>
-  live === UNREADABLE ? undefined : live;
-
 export const ProxmoxUserProvider = () =>
   Provider.effect(
     ProxmoxUser,
@@ -148,15 +134,31 @@ export const ProxmoxUserProvider = () =>
          *   identity someone made years ago. Adoption is an explicit act.
          */
         list: () => Effect.succeed([]),
-        read: Effect.fn(function* ({ olds }) {
-          return dropUnreadable(yield* readUser(olds));
+        // ⚠️ FOLDS ONLY WHEN `output` IS `undefined` — MEASURED 2026-09-24, an adversarial review
+        //   of this very fix caught the gap. The engine calls this ONE hook from FOUR places
+        //   (alchemy/src/{Plan,Apply,Drift}.ts), and only `output` tells them apart: Plan.ts's
+        //   cold-start adoption probe and interrupted-create recovery, and Apply.ts's
+        //   delete-recovery, all pass `output: undefined` — nothing is confirmed to exist yet, so
+        //   `readUser`'s fold is still needed there or a brand-new account could never be adopted
+        //   or created. `Drift.ts` (`alchemy drift`/`sync`/`deploy --detect-drift`) is different:
+        //   it calls this on an ALREADY-CONFIRMED row (`output: old.attr`, defined), exactly
+        //   `diff`'s own situation below — a transient failure folded to `undefined` there is
+        //   reported as `{action: 'missing'}` with NO error at all, the cries-wolf bug again, one
+        //   command over. `readUserOrFail` on that branch propagates it instead.
+        read: Effect.fn(function* ({ olds, output }) {
+          return dropUnreadable(
+            yield* output === undefined ? readUser(olds) : readUserOrFail(olds),
+          );
         }),
         diff: Effect.fn(function* ({ news, output }) {
           if (!isResolved(news)) return undefined;
           yield* guardWrite(USER_CREATE, createForm(news), output === undefined);
           yield* guardWrite(USER_UPDATE, updateForm(news), false);
           if (output === undefined) return undefined;
-          const live = yield* readUser(news);
+          // ⚠️ `readUserOrFail`, NOT `readUser` — see that function's own header (user-wire.ts).
+          //   A genuine failure here propagates and fails the whole plan loudly instead of
+          //   folding to "absent" and forcing a false update, the cries-wolf class of bug.
+          const live = yield* readUserOrFail(news);
           // ⛔ 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) {

package/src/verify/fake-engine.ts

@@ -125,11 +125,24 @@ export type Body = Effect.Effect<unknown, unknown, unknown>;
 type Compiled = { readonly name: string; readonly stage: string; readonly services: never };
 type PlanView = { readonly resources: Readonly<Record<string, { readonly action: string }>> };
 
+/** One row of `Alchemy.Drift.detect`'s dry-run report — the fields `drift` below asserts on. */
+export type DriftRow = { readonly action: string };
+
 export interface FakeEngine {
   /** Plan and apply `body`, as `alchemy deploy --adopt` would; resolves to the planned actions. */
   readonly deploy: (body: Body) => Promise<Record<string, string>>;
   /** Verify `body` against what the earlier deploys recorded. */
   readonly verify: (body: Body, options?: VerifyOptions) => Promise<AdoptReport>;
+  /**
+   * `alchemy drift`'s own dry-run (`Alchemy.Drift.detect`) over whatever `deploy` already
+   * persisted — `body` is used only to resolve the stack's name/stage/providers, exactly as
+   * `verify` does; drift itself reads the state store, not `body`'s declarations. ⚠️ A DIFFERENT
+   * ENGINE PATH FROM `verify`'s `--all` READ, proxmox/read-failure-propagation.test.ts's own ⛔:
+   * `Drift.ts` calls a provider's `read` with `output` set to the PERSISTED attributes, and folds
+   * a `read` that resolves `undefined` into `{action: 'missing'}` with no error — silent, unlike
+   * `verify.ts`'s `readWithState`, which already wraps that same call in `Effect.catchCause`.
+   */
+  readonly drift: (body: Body) => Promise<Record<string, DriftRow>>;
   /**
    * Every state row the store holds, as JSON — what a Postgres store would persist. ★ For tests
    * that must prove a value NEVER reaches state (proxmox/pbs-notification-target-state.test.ts).
@@ -152,6 +165,10 @@ export const engineOver = <ROut, E, RIn>(layer: Layer.Layer<ROut, E, RIn>): Fake
   ) => Effect.Effect<Compiled, unknown, never>;
   const plan = Alchemy.Plan.make as unknown as (c: Compiled) => Effect.Effect<PlanView, unknown>;
   const apply = Alchemy.apply as unknown as (planned: PlanView) => Effect.Effect<unknown, unknown>;
+  const detectDrift = Alchemy.Drift.detect as unknown as (stack: {
+    name: string;
+    stage: string;
+  }) => Effect.Effect<{ resources: Record<string, DriftRow> }, unknown>;
 
   const run = <A>(body: Body, next: (compiled: Compiled) => Effect.Effect<A, unknown, unknown>) =>
     Effect.runPromise(
@@ -182,6 +199,12 @@ export const engineOver = <ROut, E, RIn>(layer: Layer.Layer<ROut, E, RIn>): Fake
       run(body, (compiled) =>
         verifySession({ context: compiled.services, stack: compiled as never }, options),
       ),
+    drift: (body) =>
+      run(body, (compiled) =>
+        detectDrift({ name: compiled.name, stage: compiled.stage }).pipe(
+          Effect.map((detected) => detected.resources),
+        ),
+      ),
   };
 };