@homeflare/alchemy 0.30.0 → 0.31.1

package/src/proxmox/role-wire.ts

@@ -0,0 +1,49 @@
+/**
+ * `Proxmox.Role`'s wire shape: PVE's create/update forms and how a live list row becomes
+ * attributes. Split out of role.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 type { RoleAttributes, RoleProps } from './role.ts';
+
+export const ROLE_CREATE = 'pve:POST /access/roles';
+export const ROLE_UPDATE = 'pve:PUT /access/roles/{roleid}';
+
+/**
+ * The only shape two privilege sets may be compared in: sorted, de-duplicated, blanks dropped.
+ *
+ * ⚠️ THE TRIM AND THE EMPTY FILTER ARE NOT DECORATION. `'A,B,'.split(',')` yields a trailing `''`,
+ *   and a hand-written list is quite likely to carry a stray space after a comma. Either one turns
+ *   into a phantom member that no live answer can contain, so `matches` would be false on every
+ *   plan and the deploy would rewrite the role to exactly what it already was.
+ */
+export const canonical = (privs: readonly string[]): string[] =>
+  [...new Set(privs.map((priv) => priv.trim()).filter((priv) => priv.length > 0))].sort();
+
+export const createForm = (props: RoleProps): access.CreateAccessRoleRequest => ({
+  privs: canonical(props.privs).join(','),
+  roleid: props.roleid,
+});
+
+/**
+ * ⚠️ NO `append` FIELD, DELIBERATELY. Sending `append=1` would make every update additive, so a
+ *   privilege could be granted from here but never taken away — see role.ts's own header.
+ */
+export const updateForm = (props: RoleProps): access.PutAccessRoleRequest => ({
+  privs: canonical(props.privs).join(','),
+  roleid: props.roleid,
+});
+
+export const find = (rows: readonly access.ListAccessRolesResponseBodyItem[], roleid: string) =>
+  rows.find((row) => row.roleid === roleid);
+
+export const attributesOf = (
+  row: access.ListAccessRolesResponseBodyItem,
+  props: RoleProps,
+): RoleAttributes => ({
+  privs: canonical(row.privs === undefined ? [] : row.privs.split(',')),
+  roleid: props.roleid,
+});
+
+export const matches = (attributes: RoleAttributes, props: RoleProps) =>
+  canonical(attributes.privs).join(',') === canonical(props.privs).join(',');

package/src/proxmox/role.test.ts

@@ -0,0 +1,89 @@
+/**
+ * `Proxmox.Role` through Alchemy's own Plan and Apply, over a fake cluster driving the REAL
+ * `@distilled.cloud/proxmox` protocol — create, drift, and delete, reading via the LIST (not the
+ * item) as role.ts's header explains. adopt-noop.test.ts is the cross-family "adopting a
+ * matching object only reads" proof; this file is Role's own write paths.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+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 { ProxmoxRole, ProxmoxRoleProvider } from './role.ts';
+
+type Row = { roleid: string; privs: string | undefined };
+
+/** `GET /access/roles` (list) and `POST`/`PUT`/`DELETE .../roles(/{roleid})`, one flat list. */
+const cluster = (rows: Row[]) =>
+  fakePve((call: PveCall) => {
+    if (call.method === 'GET' && call.path === 'access/roles') return rows;
+    const match = /^access\/roles(?:\/(.+))?$/.exec(call.path);
+    if (match === null) return undefined;
+    const roleid = match[1];
+    if (call.method === 'POST' && roleid === undefined) {
+      rows.push({ privs: call.form['privs'], roleid: call.form['roleid'] ?? '' });
+      return undefined;
+    }
+    if (call.method === 'PUT' && roleid !== undefined) {
+      const idx = rows.findIndex((r) => r.roleid === roleid);
+      if (idx !== -1) rows[idx] = { privs: call.form['privs'], roleid };
+      return undefined;
+    }
+    if (call.method === 'DELETE' && roleid !== undefined) {
+      const idx = rows.findIndex((r) => r.roleid === roleid);
+      if (idx !== -1) rows.splice(idx, 1);
+      return undefined;
+    }
+    return undefined;
+  });
+
+const declare = (privs: string[]) =>
+  ProxmoxRole('mint', { privs, roleid: 'MintTokens', target: FAKE_TARGET });
+
+const engineFor = (fake: ReturnType<typeof cluster>) =>
+  engineOver(ProxmoxRoleProvider().pipe(Layer.provideMerge(fake.layer)));
+
+describe('Proxmox.Role over the distilled protocol', () => {
+  test('creating a role that does not exist yet: one POST, privileges sorted and joined', async () => {
+    const rows: Row[] = [];
+    const fake = cluster(rows);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      expect(await engine.deploy(declare(['User.Modify', 'Sys.Audit']))).toEqual({
+        mint: 'create',
+      });
+    });
+    expect(fake.writes()).toEqual(['POST access/roles']);
+    expect(rows).toEqual([{ privs: 'Sys.Audit,User.Modify', roleid: 'MintTokens' }]);
+  });
+
+  test('a drifted privilege set is corrected with exactly one PUT, no append field', async () => {
+    const rows: Row[] = [{ privs: 'Sys.Audit', roleid: 'MintTokens' }];
+    const fake = cluster(rows);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const declared = () => declare(['Sys.Audit', 'User.Modify']);
+      const report = await engine.verify(declared());
+      expect(report.rows[0]).toMatchObject({ diff: 'update' });
+      expect(await engine.deploy(declared())).toEqual({ mint: 'adopted' });
+    });
+    const put = fake.calls.find((call) => call.method === 'PUT');
+    expect(put?.form['privs']).toBe('Sys.Audit,User.Modify');
+    expect(put?.pairs.some(([name]) => name === 'append')).toBe(false);
+    expect(rows).toEqual([{ privs: 'Sys.Audit,User.Modify', roleid: 'MintTokens' }]);
+  });
+
+  // ⚠️ A role does not protect itself the way `destroy` in resource.ts describes for other
+  //   objects (role.ts's own ⛔) — deleting one always sends the DELETE.
+  test('deleting a role sends the DELETE', async () => {
+    const rows: Row[] = [{ privs: 'Sys.Audit', roleid: 'MintTokens' }];
+    const fake = cluster(rows);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await engine.deploy(declare(['Sys.Audit']));
+      expect(await engine.deploy(Effect.void)).toEqual({});
+    });
+    expect(fake.writes()).toEqual(['DELETE access/roles/MintTokens']);
+    expect(rows).toEqual([]);
+  });
+});

package/src/proxmox/role.ts

@@ -2,54 +2,74 @@
  * `Proxmox.Role` — a PVE role: one name, one set of privileges. The object every other resource
  * in this package stands on, because a role is what the provision credential actually holds.
  *
- * ★ THIS IS WHERE pool.ts's ⚠️ STOPS BEING A MEMORY. That file records, in prose, that the
- *   provision role lacked `Pool.Allocate`, that reconcile answered "Permission check failed", and
- *   that a human widened the role over SSH with `pveum role modify`. Prose cannot be planned
- *   against: it goes stale the first time somebody edits the role in the UI and tells nobody.
- *   Declared here, the same fact is a diff — the privileges the role is SUPPOSED to hold are read
- *   off the cluster on every plan, and a hand edit shows up as `1 to update` rather than as a 403
- *   six weeks later in the middle of something else.
- *
- * ⛔ THE INDEX AND THE ITEM DISAGREE ABOUT WHAT `privs` IS, AND MISSING THAT COSTS A DIFF THAT
- *   NEVER CONVERGES. `GET /access/roles` (the index) reports each role's privileges as a COMMA
- *   STRING. `GET /access/roles/{roleid}` — the path this resource reads — returns a privilege MAP
- *   instead, `{"VM.Allocate":1,"Sys.Audit":1,…}`, and its key order is a Perl hash's order, so it
- *   is not stable between two calls to the same endpoint. Compare the raw string, or the raw
- *   object, or the keys in the order they arrived, and every plan reports an update forever.
- *   `canonical` below is the whole answer: both sides become a sorted, de-duplicated set before
- *   anything is compared, and `attributes` STORES the sorted form so Alchemy's state does not
- *   churn either.
+ * ★ THIS IS WHERE pool.ts's ⚠️ STOPS BEING A MEMORY. Declared here, a hand edit shows up as
+ *   `1 to update` rather than as a 403 six weeks later in the middle of something else.
  *
  * ⚠️ A DECLARATION REPLACES THE PRIVILEGE SET; IT DOES NOT ADD TO IT. `PUT /access/roles/{roleid}`
- *   accepts an `append` flag and this resource deliberately never sends it — with append a role
- *   could only ever grow, so `matches` would report an update forever whenever props were a subset
- *   of live, which is the same perpetual diff by a different road. The consequence is the one that
- *   bites: anything a human added by hand is REVOKED on the next deploy unless it is in `privs`.
- *   Copy the live set out of `pveum role list` before declaring a role that already exists; do not
- *   type it from memory.
+ *   accepts an `append` flag and this resource deliberately never sends it (role-wire.ts) — with
+ *   append a role could only ever grow, the same perpetual diff by a different road. The
+ *   consequence: anything a human added by hand is REVOKED on the next deploy unless it is in
+ *   `privs`. Copy the live set out of `pveum role list` before declaring a role that already
+ *   exists; do not type it from memory.
  *
  * ⛔ A ROLE CAN LOCK ITS OWN PROVIDER OUT, AND NOTHING IN THIS PACKAGE CAN UNDO IT. Reconcile runs
  *   as the provision credential, and that credential holds a role. Declare THAT role without the
  *   privileges the provider needs — `Sys.Modify` on `/access` above all — and the write succeeds,
  *   after which every later plan reads 403 and the repair has to happen out of band as `root@pam`
- *   over SSH. It is a one-way door, which is why the privileges a reconcile needs are written
- *   down at the bottom of this comment rather than left to be rediscovered from an error message.
+ *   over SSH.
  *
  * ⚠️ PVE REFUSES TO EDIT ITS OWN BUILT-IN ROLES (`Administrator`, `NoAccess`, the `PVE*` set), and
- *   the item endpoint gives no sign of which those are — only the index carries the `special`
- *   flag. A declaration aimed at a built-in role therefore READS BACK CLEANLY and fails at write
- *   time, which reads like a broken provider rather than like a refusal. Declare roles you own.
+ *   the LIST read (below) DOES carry the `special` flag that marks them, unlike the item endpoint
+ *   this file used before the distilled migration — `role-wire.ts`'s `attributesOf` does not use
+ *   it, but a caller reading `list`'s own answer could. A declaration aimed at a built-in role
+ *   still reads back cleanly and fails at write time. Declare roles you own.
  *
  * ★ PRIVILEGES A RECONCILE NEEDS: `Sys.Audit` on `/access` to read and diff, `Sys.Modify` on
- *   `/access` to create, update or delete. Not `Permissions.Modify` — binding a role to a user is
- *   `/access/acl`, a different object, and nothing here writes it. An auditor-shaped credential
- *   can already PLAN this resource and cannot DEPLOY it, which is the honest failure: the plan is
- *   true and the deploy says exactly which privilege is missing.
+ *   `/access` to create, update or delete. Not `Permissions.Modify` — that is a different object.
+ *
+ * ★ READ VIA THE LIST, NOT THE ITEM — A DELIBERATE CHANGE FROM THE PRE-MIGRATION CODE, AND THE
+ *   REASON IS THE ITEM'S OWN GENERATED SCHEMA. `access.getAccessRole`'s response
+ *   (`GetAccessRoleResponse`) enumerates a FIXED list of ~47 known privilege field names
+ *   (`Sys_Modify`, `VM_Allocate`, …), each its own optional property — MEASURED in
+ *   `@distilled.cloud/proxmox`'s generated `access.ts`. A privilege this package's generator did
+ *   not know about would silently not appear as a field at all, and this file's old `privs: []`
+ *   reconstruction would drop it from state without a diff ever seeing the loss. The LIST read
+ *   (`access.listAccessRoles`) answers `privs` as the SAME plain comma string PVE's item read
+ *   also disagreed with the index about pre-migration — a shape with no fixed enumeration to fall
+ *   behind. `find` below (role-wire.ts) does the item-read's old job client-side.
+ * ⚠️ REASONED, NOT MEASURED, THAT THE LIST READ NEEDS NO MORE THAN `read`'s AUDITOR SHAPE. The
+ *   item read's own privilege check (`Sys.Audit` on `/access`) was measured; the list's was not
+ *   separately checked, but PVE's own convention is that an index read is never MORE restrictive
+ *   than its item. `readRole` stays at the default `read` on that basis, same as before.
+ *
+ * ★ MIGRATED OFF `client.ts`'s generic `pve()`/`pveHandlers` ONTO `@distilled.cloud/proxmox`'s
+ *   typed `access.listAccessRoles`/`createAccessRole`/`putAccessRole`/`deleteAccessRole`
+ *   (2026-09-24, decision 43's proxmox walk-down). `distilled-pve.ts`'s `runPve` replaces
+ *   `pve()`; the cries-wolf fix is wired the same way as acl.ts, group.ts and user.ts.
  */
 import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
+import * as access from '@distilled.cloud/proxmox/access';
 import * as Effect from 'effect/Effect';
-import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
+import { guardWrite } from './distilled-guard.ts';
+import {
+  ROLE_CREATE,
+  ROLE_UPDATE,
+  attributesOf,
+  createForm,
+  find,
+  matches,
+  updateForm,
+} from './role-wire.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';
 
 export interface RoleProps extends WithTarget {
   /**
@@ -62,13 +82,11 @@ export interface RoleProps extends WithTarget {
   roleid: string;
   /**
    * The COMPLETE privilege set, e.g. `['VM.Allocate', 'VM.Audit', 'Sys.Audit']`. Order and
-   * duplicates do not matter — see the ⛔ in the header — but completeness does: this list is the
+   * duplicates do not matter — see the header — but completeness does: this list is the
    * role, not an addition to it.
    *
    * ⚠️ DECLARE AT LEAST ONE. A role with no privileges grants nothing and reads back as an empty
-   *   document, which is the one shape the factory cannot tell apart from an object that is not
-   *   there — reconcile would then refuse with its "the write returned no error but the object is
-   *   still absent" message, which is true of the read and misleading about the cause.
+   *   document, which reconcile cannot tell apart from an object that is not there.
    */
   privs: string[];
 }
@@ -89,75 +107,98 @@ export interface ProxmoxRole extends Resource<
 
 export const ProxmoxRole = Resource<ProxmoxRole>('Proxmox.Role');
 
-/**
- * The only shape two privilege sets may be compared in: sorted, de-duplicated, blanks dropped.
- *
- * ⚠️ THE TRIM AND THE EMPTY FILTER ARE NOT DECORATION. `'A,B,'.split(',')` yields a trailing `''`,
- *   and a hand-written list is quite likely to carry a stray space after a comma. Either one turns
- *   into a phantom member that no live answer can contain, so `matches` would be false on every
- *   plan and the deploy would rewrite the role to exactly what it already was.
- */
-const canonical = (privs: readonly string[]): string[] =>
-  [...new Set(privs.map((priv) => priv.trim()).filter((priv) => priv.length > 0))].sort();
-
-/**
- * The privileges in a live answer, from EITHER shape PVE uses for them.
- *
- * ⚠️ THE MAP BRANCH IS THE ONE THAT RUNS HERE — the item endpoint answers `{"VM.Allocate":1,…}`,
- *   so the privilege names are the KEYS and the `1`s carry no information. The string branch
- *   exists because the index answers `{"privs":"VM.Allocate,Sys.Audit",…}` for that same role, and
- *   a reader that assumed the map shape for an index entry would compare the words `privs`,
- *   `roleid` and `special` against real privileges and report drift forever.
- *
- * ⚠️ A KEY WITH NO DOT IS NOT A PRIVILEGE. Every PVE privilege is `Category.Name` — VM.Allocate,
- *   Sys.Modify, Datastore.AllocateSpace, Pool.Audit — while the metadata PVE mixes into role
- *   answers (`special`, marking a built-in) is a bare word. Filtering on the dot keeps a flag from
- *   being diffed as though somebody had granted it.
- */
-const livePrivs = (live: Record<string, unknown>): string[] => {
-  const listed = live['privs'];
-  if (typeof listed === 'string') return canonical(listed.split(','));
-  return canonical(Object.keys(live).filter((key) => key.includes('.')));
-};
+/** ★ Default `read` role — see the header's ⚠️ on the list read's privilege requirement. */
+const readRole = (props: RoleProps) =>
+  readOrUnreadable(runPve(props.target, 'read', false, access.listAccessRoles({}))).pipe(
+    Effect.map((rows) => {
+      if (rows === UNREADABLE) return UNREADABLE;
+      const row = find(rows, props.roleid);
+      return row === undefined ? undefined : attributesOf(row, props);
+    }),
+    Effect.orElseSucceed(() => undefined),
+  );
 
-const handlers = pveHandlers<RoleProps, RoleAttributes>({
-  attributes: (live, props) => ({ privs: livePrivs(live), roleid: props.roleid }),
-  collection: () => 'access/roles',
-  /** ⚠️ PVE wants ONE comma string here, not a repeated field — `privs=A,B,C`. */
-  createForm: (props) => ({ privs: canonical(props.privs).join(','), roleid: props.roleid }),
-  /**
-   * ⛔ NORMALISED ON BOTH SIDES, even though `attributes` already arrives sorted. This is a
-   *   predicate, not a fast path: the cost of trusting one side's order is not a slow plan, it is
-   *   a plan that reports an update every single time and a deploy that writes the same role back
-   *   forever. Cheap insurance against the exact trap named in the header.
-   */
-  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
-  endpoint: { create: 'pve:POST /access/roles', update: 'pve:PUT /access/roles/{roleid}' },
-  matches: (attributes, props) =>
-    canonical(attributes.privs).join(',') === canonical(props.privs).join(','),
-  path: (props) => `access/roles/${props.roleid}`,
-  /**
-   * ⚠️ NO `append` FIELD, DELIBERATELY. Sending `append=1` would make every update additive, so a
-   *   privilege could be granted from here but never taken away — and a role that cannot narrow
-   *   is not a declaration. See the ⚠️ in the header for what that means for hand edits.
-   */
-  updateForm: (props) => ({ privs: canonical(props.privs).join(',') }),
-});
+/** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */
+const dropUnreadable = (live: RoleAttributes | Unreadable | undefined) =>
+  live === UNREADABLE ? undefined : live;
 
-/**
-* ⛔ AN EMPTY LIST, AND NOWHERE DOES IT MATTER MORE. `GET /access/roles` returns every
-*   role on the cluster, PVE's own built-ins included. Returning them would invite Alchemy
-*   to adopt `Administrator` — and therefore one day to narrow or delete it. Adoption is
-*   an explicit act, here as everywhere else in this package.
- 
- *
-* ⛔ DO NOT CARRY THE FACTORY'S REASSURANCE OVER TO THIS ONE. `destroy` there notes that
-*   PVE refuses to delete things still in use — a pool holding guests, a storage with
-*   volumes — and a role is NOT protected that way. Whoever is bound to the role loses
-*   those privileges the moment it goes, and the credential this provider runs with is
-*   bound through exactly such a binding. Checking who holds a role before removing it is
-*   an operator's job, and it is not done here on their behalf while they read a diff.
- 
- */
 export const ProxmoxRoleProvider = () =>
-  Provider.effect(ProxmoxRole, Effect.succeed(ProxmoxRole.Provider.of(handlers)));
+  Provider.effect(
+    ProxmoxRole,
+    Effect.succeed(
+      ProxmoxRole.Provider.of({
+        /**
+         * ⛔ AN EMPTY LIST, AND NOWHERE DOES IT MATTER MORE. `GET /access/roles` returns every
+         *   role on the cluster, PVE's own built-ins included. Adoption is an explicit act.
+         */
+        list: () => Effect.succeed([]),
+        read: Effect.fn(function* ({ olds }) {
+          return dropUnreadable(yield* readRole(olds));
+        }),
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          yield* guardWrite(ROLE_CREATE, createForm(news), output === undefined);
+          yield* guardWrite(ROLE_UPDATE, updateForm(news), false);
+          if (output === undefined) return undefined;
+          const live = yield* readRole(news);
+          // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and force
+          //   `update` on a role that was plainly there — see unreadable-read.ts.
+          if (live === UNREADABLE) {
+            yield* unreadableWarning('Proxmox.Role', news.roleid);
+            return { action: 'noop' } as const;
+          }
+          if (live === undefined) {
+            yield* guardWrite(ROLE_CREATE, createForm(news), true);
+            return { action: 'update' } as const;
+          }
+          return matches(live, news)
+            ? ({ action: 'noop' } as const)
+            : ({ action: 'update' } as const);
+        }),
+        reconcile: Effect.fn(function* ({ news }) {
+          // ⚠️ `dropUnreadable`: reconcile only runs once `provision` already minted for the
+          //   write below, so `UNREADABLE` here is a narrow race, not the routine case `diff`
+          //   handles — and a wrongful create in that race fails loudly ("already exists")
+          //   rather than silently duplicating, group.ts's reconcile has the same note.
+          const before = dropUnreadable(yield* readRole(news));
+          yield* guardWrite(ROLE_CREATE, createForm(news), before === undefined);
+          yield* guardWrite(ROLE_UPDATE, updateForm(news), false);
+          if (before === undefined) {
+            yield* runPve(
+              news.target,
+              'provision',
+              true,
+              access.createAccessRole(createForm(news)),
+            );
+          } else if (!matches(before, news)) {
+            yield* runPve(news.target, 'provision', true, access.putAccessRole(updateForm(news)));
+          }
+          const after = dropUnreadable(yield* readRole(news));
+          if (after === undefined) {
+            return yield* Effect.die(
+              new Error(
+                `access/roles/${news.roleid}: the write returned no error but the role is ` +
+                  'still absent. PVE wraps every answer in {"data":...} and can report success ' +
+                  'on a call that did nothing -- read back rather than trusting the status code.',
+              ),
+            );
+          }
+          return after;
+        }),
+        /**
+         * ⛔ DO NOT CARRY resource.ts's DESTROY REASSURANCE OVER TO THIS ONE. PVE does not refuse
+         *   to delete a role still in use — whoever is bound to it loses those privileges the
+         *   moment it goes, and the credential THIS PROVIDER runs with is bound through exactly
+         *   such a binding. Checking who holds a role before removing it is an operator's job.
+         */
+        delete: Effect.fn(function* ({ olds }) {
+          yield* runPve(
+            olds.target,
+            'provision',
+            true,
+            access.deleteAccessRole({ roleid: olds.roleid }),
+          );
+        }),
+      }),
+    ),
+  );

package/src/proxmox/unreadable-read.test.ts

@@ -0,0 +1,83 @@
+/**
+ * The cries-wolf fix (unreadable-read.ts), proved end to end for `Proxmox.Acl` — the reference
+ * migrated family — through Alchemy's own Plan and Apply, over a fake cluster whose OpenBao mint
+ * can be flipped to DENY the `provision` role mid-test, the way the agent lane's policy denies it
+ * for real (measured 2026-09-24, decision doc's "cries wolf" entry: 14 ACLs read back as absent
+ * and forced `update` with nothing compared).
+ *
+ * ★ ONE ENGINE, ONE TRANSPORT, A MUTABLE DENIAL FLAG — not two fakes — because the state row this
+ *   test needs (`output !== undefined`, the exact case the bug forced `update` for) has to
+ *   survive from the first deploy (mint allowed) into the second plan (mint denied);
+ *   fake-engine.ts builds its in-memory state store fresh per `engineOver` call, so the same
+ *   engine instance is reused for both, and only the fake OpenBao's answer to `/creds/provision`
+ *   changes in between. `lease_duration: 0` on every fake mint (both branches) keeps
+ *   lease-cache.ts cold, so the second phase genuinely re-mints and hits the denial.
+ */
+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 { ProxmoxAcl, ProxmoxAclProvider } from './acl.ts';
+import { FAKE_TARGET, withoutBao } from './fake-pve.ts';
+
+type Row = { path: string; type: string; ugid: string; roleid: string; propagate?: number };
+
+/** One ACL row, plus an OpenBao mint the test can deny for `provision` mid-run. */
+const clusterDenyingProvision = (rows: readonly Row[]) => {
+  let denyProvision = 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 });
+    }
+    const path = `${url.pathname.replace(/^\/api2\/json\//, '')}${url.search}`;
+    if (request.method === 'GET' && path === 'access/acl') return Response.json({ data: rows });
+    // ⛔ Any other write is a bug this test would otherwise hide: once denied, `reconcile` must
+    //   never be reached (diff answers noop), so nothing should ever PUT here again.
+    return Response.json({ data: null });
+  };
+  const fetchStub = Object.assign(stub, { preconnect: globalThis.fetch.preconnect });
+  return {
+    deny: () => {
+      denyProvision = true;
+    },
+    layer: FetchHttpClient.layer.pipe(
+      Layer.provideMerge(Layer.succeed(FetchHttpClient.Fetch, fetchStub as typeof fetch)),
+    ),
+  };
+};
+
+const grant = () =>
+  ProxmoxAcl('auditor', {
+    path: '/',
+    roleid: 'PVEAuditor',
+    target: FAKE_TARGET,
+    type: 'user',
+    ugid: 'u@pve',
+  });
+
+describe('the cries-wolf fix: a refused provision mint reports noop, never update', () => {
+  test('an already-correct grant plans noop once the credential is denied, and nothing is written', async () => {
+    const rows: Row[] = [
+      { path: '/', propagate: 1, roleid: 'PVEAuditor', type: 'user', ugid: 'u@pve' },
+    ];
+    const fake = clusterDenyingProvision(rows);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxAclProvider().pipe(Layer.provideMerge(fake.layer)));
+      // First deploy: mint allowed, adopts the matching grant and records a state row.
+      expect(await engine.deploy(grant())).toEqual({ auditor: 'adopted' });
+      // Now the credential's role is denied -- exactly the measured agent-lane scenario.
+      fake.deny();
+      const report = await engine.verify(grant(), { all: true });
+      // ⛔ THE BUG THIS PROVES FIXED: before the fix this row read 'update' with nothing compared.
+      expect(report.rows[0]).toMatchObject({ diff: 'noop' });
+      expect(await engine.deploy(grant())).toEqual({ auditor: 'noop' });
+    });
+  });
+});

package/src/proxmox/unreadable-read.ts

@@ -0,0 +1,60 @@
+/**
+ * The "unreadable" outcome a refused read produces — distinct from `undefined` (genuinely
+ * absent) and from a real attributes object (present) — so `diff` stops treating a REFUSED read
+ * the same as a confirmed-gone one. Fixes the "cries wolf" bug (measured 2026-09-24): on a lane
+ * whose credential cannot mint `provision`, every already-correct ACL and storage row read back
+ * as absent, and `diff` forced `update` for every one of them without comparing a single field,
+ * because `.pipe(Effect.orElseSucceed(() => undefined))` folds every failure — a genuine 404, a
+ * network blip, AND a permission refusal — into the one "absent" value `diff` cannot tell apart.
+ *
+ * ★ WHY A SENTINEL, NOT A FAILED `diff`. Upstream's `Diff` type is exactly
+ *   `NoopDiff | UpdateDiff | ReplaceDiff` (`packages/alchemy/src/Diff.ts@v2.0.0-beta.79`) — there
+ *   is no fourth "unreadable" action to return. And `Plan.ts`'s resource pass runs every
+ *   resource's `diff` under `Effect.exit`, then FAILS THE WHOLE PLAN if even one failed
+ *   (`diffFailures.length > 0` -> `Effect.failCause`, `Plan.ts@v2.0.0-beta.79` ~lines 1711-1731).
+ *   So making `diff` FAIL on a refused read would not report one honest row — it would abort
+ *   `bun run plan` for every OTHER resource in the stack too, worse than today's false "update".
+ *   `{ action: 'noop' }` plus a logged warning is the only outcome that (a) never forces a write
+ *   on a lane that cannot prove one is needed and (b) never takes the rest of the plan down with
+ *   it — the "noop-with-warning" reading of the fix, over the alternative of a typed plan error.
+ *
+ * ⛔ ONLY THE CREDENTIAL DENIAL IS CAUGHT HERE. Every other read failure (a genuine
+ *   `Cause.TimeoutError`, `PveClusterExhausted`, a network error) keeps folding into `undefined`
+ *   exactly as it always has — this narrows ONE typed tag out of that fold, via `catchTag`, and
+ *   changes nothing else about it. See credential-errors.ts's own ⛔ for why 403 alone qualifies.
+ */
+import * as Effect from 'effect/Effect';
+import type { PveCredentialDenied } from './credential-errors.ts';
+
+/** Distinct from `undefined` (absent) and from a real attributes object (present). */
+export const UNREADABLE = Symbol('pve-unreadable');
+export type Unreadable = typeof UNREADABLE;
+
+/**
+ * Catches ONLY `PveCredentialDenied` and turns it into the sentinel, so a caller that also
+ * `.pipe(Effect.orElseSucceed(() => undefined))` for every OTHER failure never conflates a
+ * refusal with a genuine absence. Compose this INSIDE that fold, never after it.
+ *
+ * ⚠️ `E | PveCredentialDenied` IN, `E` OUT — not a generic `E` narrowed by `Exclude`. `catchTag`
+ *   needs the tag to be STATICALLY present in the error union to typecheck at all; a bare
+ *   unconstrained `E` gives it nothing to match against. Every caller's `runPve` already carries
+ *   `PveCredentialDenied` explicitly (distilled-pve.ts's own ★ on why), so this signature costs
+ *   nothing at the call site.
+ */
+export const readOrUnreadable = <A, E, R>(
+  effect: Effect.Effect<A, E | PveCredentialDenied, R>,
+): Effect.Effect<A | Unreadable, E, R> =>
+  effect.pipe(Effect.catchTag('PveCredentialDenied', () => Effect.succeed(UNREADABLE)));
+
+/**
+ * The warning `diff` logs when it reports `noop` for a row it could not actually read — visible
+ * 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.
+ */
+export const unreadableWarning = (type: string, identity: 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.',
+  );