@homeflare/alchemy 0.31.1 → 0.32.0

package/src/opnsense/resource.ts

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

package/src/opnsense/wire.ts

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

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

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

package/src/proxmox/acl.ts

@@ -99,15 +99,21 @@ export const ProxmoxAcl = Resource<ProxmoxAcl>('Proxmox.Acl');
 
 /**
  * ⛔ `readRole: 'provision'`, WITHOUT WHICH EVERY GRANT READS BACK AS ABSENT — see the header's
- *   ⛔ on filtering. `orElseSucceed` still folds every OTHER failure into `undefined`.
+ *   ⛔ on filtering.
  * ★ `readOrUnreadable` (unreadable-read.ts) runs first: a REFUSED mint of `provision` — the
- *   "cries wolf" bug — comes back `UNREADABLE` instead of the same `undefined` a genuine
- *   absence produces, so `diff` below can tell them apart.
+ *   "cries wolf" bug — comes back `UNREADABLE` instead of the `undefined` a genuine, SUCCESSFUL
+ *   read (the row simply not being in the list) produces, so `diff` below can tell them apart.
+ * ⛔ NO `orElseSucceed` HERE ANY MORE — found on 2026-09-24, the SAME bug class as the credential
+ *   denial: it used to fold EVERY OTHER failure (a transport error, `PveClusterExhausted`, a
+ *   decode failure) into `undefined` too, which then read exactly like a genuine absence and
+ *   forced the same false `update`. Only a read that actually SUCCEEDS (and the grant is not in
+ *   the list it returns) may mean absent now; every other failure propagates and fails the whole
+ *   plan loudly — the engine's own contract for a failed `read`/`diff` (verify.ts's `readWithState`
+ *   already expects and reports it as `'failed'`).
  */
 const readAttributes = (props: AclProps) =>
   readOrUnreadable(runPve(props.target, 'provision', false, access.listAccessAcl({}))).pipe(
     Effect.map((rows) => (rows === UNREADABLE ? UNREADABLE : attributesOf(rows, props))),
-    Effect.orElseSucceed(() => undefined),
   );
 
 /** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */

package/src/proxmox/api-token.ts

@@ -141,12 +141,22 @@ export const ProxmoxApiToken = Resource<ProxmoxApiToken>('Proxmox.ApiToken', {
   defaultRemovalPolicy: 'retain',
 });
 
-/** ⛔ `readRole: 'provision'` — see the header's ⚠️ on privileges. */
-const readToken = (props: ApiTokenProps) =>
-  readOrUnreadable(runPve(props.target, 'provision', false, access.getAccessUserToken(props))).pipe(
-    Effect.map((live) => (live === UNREADABLE ? UNREADABLE : attributesOf(live, props))),
-    Effect.orElseSucceed(() => undefined),
-  );
+/**
+ * ⛔ `readRole: 'provision'` — see the header's ⚠️ on privileges.
+ * ⛔ `{ userid, tokenid }`, NEVER THE WHOLE `props` — group.ts's readGroup has the full measured
+ *   mechanism (kit 0.31.1's regression): an extra key beyond the schema's own path labels gets
+ *   encoded onto this GET as a body, which a stricter fetch client refuses outright.
+ * ⛔ NO `orElseSucceed` — a MISSING token's absence signal is a SUCCESSFUL read with `expire`/
+ *   `privsep` both absent (`attributesOf`/api-token-form.ts, MEASURED pre-migration), unlike
+ *   user.ts/group.ts's missing-object 500 — so this family never needed their folding split. A
+ *   THROWN failure here is genuinely unexpected and must propagate and fail the plan loudly.
+ */
+const readToken = (props: ApiTokenProps) => {
+  const label = { tokenid: props.tokenid, userid: props.userid };
+  return readOrUnreadable(
+    runPve(props.target, 'provision', false, access.getAccessUserToken(label)),
+  ).pipe(Effect.map((live) => (live === UNREADABLE ? UNREADABLE : attributesOf(live, props))));
+};
 
 /** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */
 const dropUnreadable = (live: ApiTokenAttributes | Unreadable | undefined) =>
@@ -193,12 +203,10 @@ export const ProxmoxApiTokenProvider = () =>
         }),
         reconcile: Effect.fn(function* ({ news }) {
           // ⚠️ `dropUnreadable`: reconcile only runs once `provision` already minted for the
-          //   read that fed `diff`'s `update` verdict, so `UNREADABLE` here is a narrow race —
-          //   but UNLIKE group/role/user, the message below assumes genuine absence and would
-          //   misname a transient credential refusal as "this resource does not create tokens".
-          //   Rare (the SAME role must mint twice, once for diff/once for reconcile, and only the
-          //   second is denied) and not silently wrong — the operator still sees a die() and goes
-          //   looking — but named here rather than left for the next reader to assume away.
+          //   read that fed `diff`'s `update` verdict, so `UNREADABLE` here is a narrow race, not
+          //   the routine case `diff` handles. Any OTHER read failure now propagates on its own
+          //   (readToken no longer folds it), so the die() message below is reached only on a
+          //   genuinely absent token, never on a transient failure wearing that message.
           const before = dropUnreadable(yield* readToken(news));
           if (before === undefined) {
             return yield* Effect.die(

package/src/proxmox/group-wire.ts

@@ -1,10 +1,13 @@
 /**
- * `Proxmox.Group`'s wire shape: PVE's create/update forms and how a live item becomes
- * attributes. Split out of group.ts (2026-09-24) to keep that file under the 250-line cap —
- * the api-token.ts/api-token-form.ts seam, same reasoning as acl.ts/acl-wire.ts.
+ * `Proxmox.Group`'s wire shape: PVE's create/update forms, how a live item becomes attributes,
+ * and the read itself. Split out of group.ts (2026-09-24) to keep that file under the 250-line
+ * cap — the api-token.ts/api-token-form.ts seam, same reasoning as acl.ts/acl-wire.ts.
  */
-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 { GroupAttributes, GroupProps } from './group.ts';
+import { UNREADABLE, type Unreadable, readOrUnreadable } from './unreadable-read.ts';
 import { csv, text } from './values.ts';
 
 export const GROUP_CREATE = 'pve:POST /access/groups';
@@ -41,10 +44,7 @@ export const updateForm = (props: GroupProps): access.PutAccessGroupRequest => (
   groupid: props.groupid,
 });
 
-export const attributesOf = (
-  live: access.GetAccessGroupResponse,
-  props: GroupProps,
-): GroupAttributes => ({
+const attributesOf = (live: access.GetAccessGroupResponse, props: GroupProps): GroupAttributes => ({
   /**
    * ⚠️ ABSENT IS EMPTY, NOT MISSING — `read_group` sets `comment` only `if defined(…)`. distilled
    *   types it `comment?: string`, so `text()`'s `''` fallback meets the same normalisation.
@@ -61,3 +61,57 @@ export const attributesOf = (
  */
 export const matches = (attributes: GroupAttributes, props: GroupProps) =>
   attributes.comment === storedComment(props.comment);
+
+/**
+ * ★ Default `read` role — nothing widened for this family, see group.ts's header privileges note.
+ * ⛔ `{ groupid: props.groupid }`, NEVER THE WHOLE `props` — MEASURED 2026-09-24, the regression
+ *   in kit 0.31.1. `GetAccessGroupRequest`'s schema declares only `groupid` (a path label); any
+ *   OTHER key on the object passed to `access.getAccessGroup` — `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 group. `role.ts`'s list call and acl.ts's `listAccessAcl({})` were
+ *   never at risk: both are always called with a literal `{}`.
+ * ⛔ `live.members === undefined` IS DEFENSIVE, NOT THE ABSENCE SIGNAL — CORRECTED 2026-09-24.
+ *   This file previously claimed a missing group answers 200 with `{"data":null}`, unwrapped to
+ *   `{}`. MEASURED against the live cluster: `GET /access/groups/{missing}` answers a genuine 500
+ *   ("group '…' does not exist"), the SAME shape as user.ts's own measured 500 — there is no
+ *   success-path absence signal here at all. The check stays as insurance against a future PVE
+ *   release that does answer `{}`, but this function is what actually carries the "not found"
+ *   case, as a thrown error — `readGroup` below is the one that folds it.
+ */
+export const readGroupOrFail = (props: GroupProps) =>
+  readOrUnreadable(
+    runPve(props.target, 'read', false, access.getAccessGroup({ groupid: props.groupid })),
+  ).pipe(
+    Effect.map((live) =>
+      live === UNREADABLE
+        ? UNREADABLE
+        : live.members === undefined
+          ? undefined
+          : attributesOf(live, props),
+    ),
+  );
+
+/**
+ * ⛔ FOLDS A GENUINE READ FAILURE TO `undefined` TOO, AND ONLY `read`/`reconcile` MAY USE IT.
+ *   PVE's OWN missing-group answer is a thrown 500 (the ⛔ above), so `reconcile`'s create branch
+ *   NEEDS "absent" from a failure to ever run at all — without this fold, a brand-new group could
+ *   never be created, because its very-first read would always fail loudly. Safe here because a
+ *   wrongful fold costs at most a redundant `createAccessGroup` POST, which PVE refuses loudly
+ *   ("group already exists") rather than silently corrupting anything.
+ * ⛔ `group.ts`'s `diff` does **NOT** use this — found 2026-09-24, the SAME bug class as the
+ *   credential denial fix: folding a TRANSIENT failure (a `PveClusterExhausted`, the encoding bug
+ *   above) into "absent" at PLAN TIME is exactly what forced a false `update` with nothing
+ *   compared. `diff` calls `readGroupOrFail` directly instead, so a genuine failure there
+ *   propagates and fails the whole plan loudly — never silently misreports one row.
+ */
+export const readGroup = (props: GroupProps) =>
+  readGroupOrFail(props).pipe(Effect.orElseSucceed(() => undefined));
+
+/** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */
+export const dropUnreadable = (live: GroupAttributes | Unreadable | undefined) =>
+  live === UNREADABLE ? undefined : live;

package/src/proxmox/group.ts

@@ -76,19 +76,16 @@ import { guardWrite } from './distilled-guard.ts';
 import {
   GROUP_CREATE,
   GROUP_UPDATE,
-  attributesOf,
   createForm,
+  dropUnreadable,
   matches,
+  readGroup,
+  readGroupOrFail,
   updateForm,
 } from './group-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';
+import { UNREADABLE, unreadableWarning } from './unreadable-read.ts';
 
 export interface GroupProps extends WithTarget {
   /**
@@ -127,31 +124,6 @@ export const ProxmoxGroup = Resource<ProxmoxGroup>('Proxmox.Group', {
   defaultRemovalPolicy: 'retain',
 });
 
-/**
- * ★ Default `read` role — nothing widened for this family, see the header's privileges note.
- * ⛔ `live.members === undefined` MEANS ABSENT, NOT AN EMPTY GROUP. `@distilled.cloud/core`'s
- *   REST protocol unwraps PVE's `{"data": null}` (a genuinely missing object — MEASURED in
- *   `protocol.ts`: "a Unit-output endpoint... `data` is null/absent") to `{}` BEFORE the
- *   schema-driven decode, not to a decode failure. `members` is the one REQUIRED field on this
- *   response, so its absence is the only signal that the group was never there — the same trap
- *   api-token-form.ts's `attributes` guards with its own required-field check.
- */
-const readGroup = (props: GroupProps) =>
-  readOrUnreadable(runPve(props.target, 'read', false, access.getAccessGroup(props))).pipe(
-    Effect.map((live) =>
-      live === UNREADABLE
-        ? UNREADABLE
-        : live.members === undefined
-          ? undefined
-          : attributesOf(live, props),
-    ),
-    Effect.orElseSucceed(() => undefined),
-  );
-
-/** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */
-const dropUnreadable = (live: GroupAttributes | Unreadable | undefined) =>
-  live === UNREADABLE ? undefined : live;
-
 export const ProxmoxGroupProvider = () =>
   Provider.effect(
     ProxmoxGroup,
@@ -162,15 +134,31 @@ export const ProxmoxGroupProvider = () =>
          *   cluster, `admins` (grants `Administrator` on `/`) included. Adoption stays explicit.
          */
         list: () => Effect.succeed([]),
-        read: Effect.fn(function* ({ olds }) {
-          return dropUnreadable(yield* readGroup(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
+        //   `readGroup`'s fold is still needed there or a brand-new group 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. `readGroupOrFail` on that branch propagates it instead.
+        read: Effect.fn(function* ({ olds, output }) {
+          return dropUnreadable(
+            yield* output === undefined ? readGroup(olds) : readGroupOrFail(olds),
+          );
         }),
         diff: Effect.fn(function* ({ news, output }) {
           if (!isResolved(news)) return undefined;
           yield* guardWrite(GROUP_CREATE, createForm(news), output === undefined);
           yield* guardWrite(GROUP_UPDATE, updateForm(news), false);
           if (output === undefined) return undefined;
-          const live = yield* readGroup(news);
+          // ⚠️ `readGroupOrFail`, NOT `readGroup` — see that function's own ⛔. A genuine
+          //   TRANSIENT 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* readGroupOrFail(news);
           // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and force
           //   `update` on a group that was plainly there — see unreadable-read.ts.
           if (live === UNREADABLE) {