@homeflare/alchemy 0.31.0 → 0.31.1

package/src/proxmox/group.ts

@@ -22,8 +22,9 @@
  *                                     "users":"hf-provision@pve,hf-read@pve"}, …]
  *     GET /access/groups/hf-mint -> {"comment":"…","members":["hf-provision@pve","hf-read@pve"]}
  *   The index says `users` and hands back a COMMA STRING; the item says `members` and hands back an
- *   ARRAY. A reader that looked for `users` on the item path would find nothing, report an empty
- *   group, and quietly show a delete as harmless.
+ *   ARRAY. distilled's generator reflects the SAME split (`GetAccessGroupResponse.members: string[]`
+ *   vs `ListAccessGroupsResponseBodyItem.users?: string`), so reading the item is what keeps this
+ *   file on the array shape it already normalises.
  *
  * ⛔ AND THE ITEM'S ORDER IS NOT STABLE BETWEEN TWO CONSECUTIVE CALLS. MEASURED, seconds apart, on
  *   the same endpoint:
@@ -38,37 +39,56 @@
  *   exactly `comment` and `members`, so the id comes from props — the same arrangement, and the
  *   same reason, as `user.ts`.
  *
- * ★ PRIVILEGES: NOTHING HAD TO BE WIDENED, WHICH MAKES THIS THE FIRST FAMILY HERE THAT COST
- *   NOTHING. Measured with `pveum user permissions`, 2026-09-13:
+ * ★ PRIVILEGES: NOTHING HAD TO BE WIDENED. Measured with `pveum user permissions`, 2026-09-13:
  *     · item GET checks `['perm','/access/groups',['Sys.Audit','Group.Allocate'], any => 1]`, and
- *       `hf-read@pve` already holds `Sys.Audit` there (propagated from `/` by `PVEAuditor`).
- *       So `readRole` is left at the default `read` — unlike storage/sdn-zone/sdn-vnet, whose ITEM
- *       reads PVE gates on an allocate privilege. See the ⛔ on `readRole` in `resource.ts`.
+ *       `hf-read@pve` already holds `Sys.Audit` there. So `readAttributes` below reads with the
+ *       default `read` role — unlike acl.ts, user.ts and api-token.ts, whose item/list reads PVE
+ *       gates on an allocate privilege the 3600s read lease does not hold.
  *     · POST, PUT and DELETE each check `Group.Allocate` on `/access/groups`, and
  *       `hf-provision@pve` holds it via the provision role (`PROVISION_PRIVILEGES`).
  *
  * ⛔ `retain` BY DEFAULT, BECAUSE DELETING A GROUP DESTROYS TWO THINGS THIS FILE CANNOT PUT BACK.
  *   Measured in `PVE::AccessControl` on the node:
- *     · The member list IS the group. `user.cfg` stores it on the GROUP line (`group:<id>:<users>:
- *       <comment>:`) and DERIVES each user's `groups` map from it at parse time. Deleting the group
- *       deletes the list, and this resource has no `members` prop to restore it from.
+ *     · The member list IS the group. `user.cfg` stores it on the GROUP line and DERIVES each
+ *       user's `groups` map from it at parse time. Deleting the group deletes the list, and this
+ *       resource has no `members` prop to restore it from.
  *     · `delete_group_acl` then walks the whole ACL tree and drops every grant where the group is
  *       the SUBJECT. On this cluster that is `admins -> Administrator on /` and
  *       `automation -> PVEAuditor on /`: whole populations of access, gone in one call, with no
  *       confirmation and nothing in the plan to suggest it.
- *   `delete` is FULLY IMPLEMENTED — `DELETE /access/groups/{groupid}` exists, unlike the ACL
- *   family's — so `.pipe(RemovalPolicy.destroy())` really removes the group. See the ★ in
- *   `resource.ts` for why the policy is a guard rather than a stubbed-out operation.
+ *   `delete` is FULLY IMPLEMENTED — `DELETE /access/groups/{groupid}` exists — so
+ *   `.pipe(RemovalPolicy.destroy())` really removes the group.
  *
- * ⛔ NO SECRET REACHES STATE. A group holds a comment and a list of userids; there is no password,
- *   no token and no key anywhere on these endpoints. `user.ts`'s ⛔ about unencrypted state applies
- *   to this package, and this family simply has nothing to trip it.
+ * ★ MIGRATED OFF `client.ts`'s generic `pve()`/`pveHandlers` ONTO `@distilled.cloud/proxmox`'s
+ *   typed `access.getAccessGroup`/`createAccessGroup`/`putAccessGroup`/`deleteAccessGroup`
+ *   (2026-09-24, decision 43's proxmox walk-down, access sub-area, second resource after Acl).
+ *   `distilled-pve.ts`'s `runPve` replaces `pve()` as in acl.ts; the CRIES-WOLF FIX
+ *   (unreadable-read.ts) is wired the same way: a refused `provision` mint on the WRITE-side
+ *   guard, or a refused `read` mint on the plain read, reports `noop` with a warning rather than
+ *   forcing `update` with nothing compared.
  */
 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 { csv, text } from './values.ts';
+import { guardWrite } from './distilled-guard.ts';
+import {
+  GROUP_CREATE,
+  GROUP_UPDATE,
+  attributesOf,
+  createForm,
+  matches,
+  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';
 
 export interface GroupProps extends WithTarget {
   /**
@@ -108,94 +128,104 @@ export const ProxmoxGroup = Resource<ProxmoxGroup>('Proxmox.Group', {
 });
 
 /**
- * The comment PVE will actually END UP HOLDING for a given declaration.
- *
- * ⛔ PVE CANNOT STORE THE COMMENT `'0'`, AND A PROVIDER THAT DOES NOT MODEL THAT DIFFS FOREVER.
- *   Three places in the shipped Perl test the comment for TRUTH rather than for definedness, and
- *   in Perl the one-character string `'0'` is false:
- *     `create_group`:      `$group->{comment} = $param->{comment} if $param->{comment};`
- *     `write_user_config`: `my $comment = $d->{comment} ? encode_text($d->{comment}) : '';`
- *     the config parser:   `$cfg->{groups}->{$g}->{comment} = decode_text($comment) if $comment;`
- *   So a declared `comment: '0'` is accepted by the API, dropped on the way to `user.cfg`, and read
- *   back as absent. Left alone, `matches` would be false on every plan and every deploy would
- *   rewrite the same value into the same hole. Normalising BOTH the comparison and the form is how
- *   `values.ts` already treats `''` as the absence of a boolean rather than as `false`.
- *   ⚠️ MEASURED IN THE SOURCE ON node-b, NOT ON THE WIRE — writing `'0'` to the cluster to watch it
- *     vanish would have been a write, and this agent had read access only.
- *   ⚠️ `pool.ts` HAS THE SAME LATENT HOLE — `pool:$pool:$comment:…` is written by that same
- *     truthiness test and is not guarded. Not fixed from here; flagged so it is fixed on purpose.
- *
- * ⚠️ EVERY OTHER COMMENT ROUND-TRIPS EXACTLY, colons and newlines included: `write_user_config`
- *   runs it through `encode_text` and the parser through `decode_text`, so the field separator in
- *   `user.cfg` cannot be smuggled in.
+ * ★ 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 storedComment = (comment: string | undefined) => {
-  const value = comment ?? '';
-  return value === '0' ? '' : value;
-};
+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),
+  );
 
-/**
- * The item read's `members` array, sorted into something two plans can agree on.
- *
- * ⚠️ `csv` IS REUSED RATHER THAN RE-IMPLEMENTED, AND ITS OWN ⚠️ IS EXACTLY THIS CASE: a list PVE
- *   does not promise to give back in the order it was handed. Going out through the joined form
- *   and back is the price of that reuse, and cheaper than a fourth hand-rolled sorter.
- * ⚠️ THE ARRAY ONLY — THE COMMA STRING IS NOT ACCEPTED HERE, ON PURPOSE. That spelling belongs to
- *   the INDEX (`users`), which this provider never reads, so a branch for it would be a guess at a
- *   shape that cannot arrive. `user.ts` refuses the same guess for `tokens` and for the same
- *   reason: a wrong guess on a reported-only field surfaces in a plan as a phantom membership.
- * ⚠️ NO DEDUPLICATION, UNLIKE `user.ts`'s `groupSet`. These names are Perl HASH KEYS —
- *   `[keys %{ $data->{users} }]` — so a duplicate is not representable. `user.groups` needs the
- *   dedupe because its value also arrives from a hand-written prop; this one never does.
- */
-const memberList = (live: unknown): string[] => {
-  const joined = csv((Array.isArray(live) ? live : []).map((member: unknown) => text(member)));
-  return joined === '' ? [] : joined.split(',');
-};
+/** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */
+const dropUnreadable = (live: GroupAttributes | Unreadable | undefined) =>
+  live === UNREADABLE ? undefined : live;
 
-const handlers = pveHandlers<GroupProps, GroupAttributes>({
-  attributes: (live, props) => ({
-    /**
-     * ⚠️ ABSENT IS EMPTY, NOT MISSING. `read_group` sets `comment` only `if defined(…)`, so a group
-     *   without one answers `{"members":[…]}` and nothing else. THAT ONE IS READ OFF THE HANDLER'S
-     *   SOURCE, not off the wire — every group on this cluster happens to carry a comment, so the
-     *   commentless shape was not there to measure. The empty-MEMBERS shape WAS measured —
-     *   `automation` answers `{"comment":"…","members":[]}`. `''` is what an undeclared
-     *   `comment` prop normalises to, so the two sides meet either way.
-     */
-    comment: text(live['comment']),
-    /** ⚠️ FROM PROPS: the item read's schema is `additionalProperties: 0` over comment/members. */
-    groupid: props.groupid,
-    members: memberList(live['members']),
-  }),
-  collection: () => 'access/groups',
-  createForm: (props) => ({ comment: storedComment(props.comment), groupid: props.groupid }),
-  /**
-   * ⚠️ `members` IS NOT COMPARED, AND NOTHING ELSE IS LEFT TO COMPARE. `comment` is the only field
-   *   a PUT here accepts, so it is the only field whose drift this provider can repair — the rule
-   *   `resource.ts` states once in the ⛔ on adoption: a field deliberately out of `matches` is a
-   *   field this resource does not manage.
-   */
-  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
-  endpoint: { create: 'pve:POST /access/groups', update: 'pve:PUT /access/groups/{groupid}' },
-  matches: (attributes, props) => attributes.comment === storedComment(props.comment),
-  path: (props) => `access/groups/${props.groupid}`,
-  /**
-   * ⚠️ ALWAYS SENT, EVEN EMPTY — that is how a comment is CLEARED. `update_group` assigns
-   *   `if defined($param->{comment})`, so an omitted field leaves the old text in place and a
-   *   declaration that dropped its comment would report an update the update could not settle. The
-   *   empty string then falls out of `user.cfg` on the truthiness test above and reads back as
-   *   `''`, which is what the props side normalises to. The loop closes.
-   */
-  updateForm: (props) => ({ comment: storedComment(props.comment) }),
-});
-
-/**
- * ⛔ THE EMPTY `list` IS INHERITED FROM `pveHandlers` AND IT MATTERS HERE. `GET /access/groups`
- *   answers with every group on the cluster — on this one that is `admins`, which grants
- *   `Administrator` on `/` to every human who logs in. Handing it to Alchemy would invite adoption,
- *   and therefore one day a delete that takes the whole admin group's access with it. Adoption
- *   stays an explicit act, here as everywhere else in this package.
- */
 export const ProxmoxGroupProvider = () =>
-  Provider.effect(ProxmoxGroup, Effect.succeed(ProxmoxGroup.Provider.of(handlers)));
+  Provider.effect(
+    ProxmoxGroup,
+    Effect.succeed(
+      ProxmoxGroup.Provider.of({
+        /**
+         * ⛔ THE EMPTY `list` MATTERS HERE. `GET /access/groups` answers every group on the
+         *   cluster, `admins` (grants `Administrator` on `/`) included. Adoption stays explicit.
+         */
+        list: () => Effect.succeed([]),
+        read: Effect.fn(function* ({ olds }) {
+          return dropUnreadable(yield* readGroup(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);
+          // ⛔ 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) {
+            yield* unreadableWarning('Proxmox.Group', news.groupid);
+            return { action: 'noop' } as const;
+          }
+          if (live === undefined) {
+            // Drift: state says this group exists, the cluster disagrees. reconcile recreates it.
+            yield* guardWrite(GROUP_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 (same lease-cache key), so `UNREADABLE` here is a narrow race, not the
+          //   routine case `diff` handles. ⛔ UNLIKE acl.ts's PUT-only bind, a group's create is
+          //   NOT idempotent the same way: if this narrow race DOES land as `undefined` while the
+          //   group is genuinely already there, PVE answers "group already exists" rather than
+          //   silently converging — a loud failure, not a silent duplicate.
+          const before = dropUnreadable(yield* readGroup(news));
+          yield* guardWrite(GROUP_CREATE, createForm(news), before === undefined);
+          yield* guardWrite(GROUP_UPDATE, updateForm(news), false);
+          if (before === undefined) {
+            yield* runPve(
+              news.target,
+              'provision',
+              true,
+              access.createAccessGroup(createForm(news)),
+            );
+          } else if (!matches(before, news)) {
+            yield* runPve(news.target, 'provision', true, access.putAccessGroup(updateForm(news)));
+          }
+          const after = dropUnreadable(yield* readGroup(news));
+          if (after === undefined) {
+            return yield* Effect.die(
+              new Error(
+                `access/groups/${news.groupid}: the write returned no error but the group 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;
+        }),
+        delete: Effect.fn(function* ({ olds }) {
+          yield* runPve(
+            olds.target,
+            'provision',
+            true,
+            access.deleteAccessGroup({ groupid: olds.groupid }),
+          );
+        }),
+      }),
+    ),
+  );

package/src/proxmox/lease-cache.ts

@@ -47,7 +47,8 @@ import * as Cache from 'effect/Cache';
 import * as Duration from 'effect/Duration';
 import * as Effect from 'effect/Effect';
 import * as Exit from 'effect/Exit';
-import { type ApiTarget, type PveCredential, type PveRole, mint } from './credentials.ts';
+import { type ApiTarget, type PveCredential, type PveRole } from './credentials.ts';
+import { mint } from './mint.ts';
 
 /**
  * Re-mint once a lease is inside this much of its end, in seconds.

package/src/proxmox/lxc-lifecycle.ts

@@ -27,7 +27,8 @@ import * as Effect from 'effect/Effect';
 import { PveError, pve, pveWith } from './client.ts';
 import { guardForm } from './constraint-guard.ts';
 import type { EndpointKey } from './constraints.ts';
-import { type PveTarget, mint } from './credentials.ts';
+import type { PveTarget } from './credentials.ts';
+import { mint } from './mint.ts';
 import { createForm } from './lxc-create-form.ts';
 import { type LxcChange, judge } from './lxc-judge.ts';
 import type { LxcAttributes, LxcProps } from './lxc-props.ts';

package/src/proxmox/mint.ts

@@ -0,0 +1,158 @@
+/**
+ * Minting one PVE/PBS credential from OpenBao: `GET /v1/<mount>/creds/<role>`, alive for five
+ * minutes. Split out of `credentials.ts` (2026-09-24) to keep that file's TYPES under the
+ * 250-line cap once `PveCredentialDenied`'s catchers needed a real header there; the reasoning
+ * for WHY the estate mints rather than stores a token is still credentials.ts's own header.
+ *
+ * ⛔ THE SECRET NEVER TOUCHES DISK, A LOG, OR ALCHEMY STATE — see credentials.ts's ⛔. Nothing
+ *   here returns it to a resource; it is used to build a header and then dropped.
+ */
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import * as Headers from 'effect/unstable/http/Headers';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
+import { PveCredentialDenied } from './credential-errors.ts';
+import type { ApiTarget, BaoEnvironment, PveCredential, PveRole } from './credentials.ts';
+
+/** openbao v2.6.2 api/env.go:22-34 — a present BAO_* wins, even empty; else its VAULT_* twin. */
+const baoVariable = (env: BaoEnvironment, name: string) =>
+  env[`BAO_${name}`] ?? env[`VAULT_${name}`] ?? '';
+
+/**
+ * Mint one credential for `role`: `GET /v1/<mount>/creds/<role>` on OpenBao's HTTP API.
+ *
+ * 🔴 IT SHELLED OUT TO `bao read -format=json` UNTIL 2026-09-14. The case for the CLI was that one
+ *   client could not disagree with `bao kv get` about what this machine may do. <estate>/openbao then
+ *   learned twice what deciding by stderr costs — every failure read as absent, and two commands
+ *   said "absent" in different words — so this reads STATUS CODES: 2xx is a credential, and 403
+ *   (denied), 404 (no such role or mount — a mint has no "absent"), 503 (sealed) all fail.
+ * ★ THE ENVIRONMENT CONTRACT IS STILL THE CLI's, READ THE CLI's WAY, which keeps the case above
+ *   true (openbao v2.6.2 api/client.go:34-66, 370, 503-507, 761-762, 776-785): BAO_AGENT_ADDR over
+ *   BAO_ADDR over https://127.0.0.1:8200; BAO_NAMESPACE as X-Vault-Namespace; BAO_TOKEN as
+ *   X-Vault-Token; X-Vault-Request always. <estate>/openbao/src/bao-address.ts has the long form.
+ * ★ AGENT MODE IS NO BAO_TOKEN AND NO TOKEN HEADER. An Agent or Proxy listener with
+ *   `api_proxy { use_auto_auth_token = true }` (or the older `cache { … }`) substitutes its
+ *   auto-auth token exactly when a request carries none — command/agentproxyshared/cache/handler.go
+ *   :29-38, command/agent.go:517-541, command/agent/config/config.go:288-292, and
+ *   website/content/docs/agent-and-proxy/agent/apiproxy.mdx:57-62. The CLI's token-file fallback
+ *   is deliberately not read. ⚠️ So an unset BAO_TOKEN aimed at a SERVER rather than an agent is a
+ *   403, which reads like a missing grant rather than a missing variable.
+ * ★ UNIX SOCKETS: `unix:///path` is plain HTTP to `localhost` over that socket, as the CLI does it
+ *   (api/client.go:654-667). Bun's fetch takes a `unix` option; `FetchHttpClient.RequestInit` is
+ *   Effect's documented way to pass fetch options, read from the calling fiber (effect
+ *   FetchHttpClient.ts:59-72). Off Bun it REFUSES, rather than reach http://localhost:80.
+ */
+export const mint = (target: ApiTarget, role: PveRole, env: BaoEnvironment = process.env) =>
+  Effect.gen(function* () {
+    const path = `${target.mount}/creds/${role}`;
+    // ⛔ METHOD, PATH AND OpenBao's `errors` ONLY — never a header (the token), never a success
+    //   body (the credential is IN it, so echoing it would print the secret into a log).
+    const refuse = (status: number, detail: string) =>
+      new Error(`OpenBao GET /v1/${path} -> ${status === 0 ? 'no response' : status}: ${detail}`);
+    const address =
+      baoVariable(env, 'AGENT_ADDR') || baoVariable(env, 'ADDR') || 'https://127.0.0.1:8200';
+    const socket = address.startsWith('unix://') ? address.slice('unix://'.length) : undefined;
+    const base = socket === undefined ? address.replace(/\/+$/, '') : 'http://localhost';
+    const headers: Record<string, string> = { 'X-Vault-Request': 'true' };
+    const namespace = baoVariable(env, 'NAMESPACE');
+    if (namespace !== '') headers['X-Vault-Namespace'] = namespace;
+    const token = baoVariable(env, 'TOKEN');
+    if (token !== '') headers['X-Vault-Token'] = token;
+    if (socket !== undefined && !('Bun' in globalThis)) {
+      return yield* Effect.fail(refuse(0, 'a unix:// address needs Bun fetch; this is not Bun'));
+    }
+
+    const client = yield* HttpClient.HttpClient;
+    // ⛔ Effect records request headers on the client span, and its default redaction list does
+    //   not name x-vault-token (effect Headers.ts:753-762). It is added for this call.
+    const redacted = yield* Headers.CurrentRedactedNames;
+    const defaults = Option.getOrElse(
+      yield* Effect.serviceOption(FetchHttpClient.RequestInit),
+      () => ({}),
+    );
+    const request = HttpClientRequest.get(`${base}/v1/${path}`).pipe(
+      HttpClientRequest.setHeaders(headers),
+    );
+    const exchange = client.execute(request).pipe(
+      Effect.flatMap((response) =>
+        Effect.map(response.text, (text) => ({ status: response.status, text })),
+      ),
+      // ⚠️ The CLI's default client timeout (api/client.go:324) — a hung agent must not hang a plan.
+      Effect.timeout('60 seconds'),
+      Effect.provideService(Headers.CurrentRedactedNames, [...redacted, 'x-vault-token']),
+    );
+    // ⚠️ `| undefined` under exactOptionalPropertyTypes: `socket` is narrowed to a string
+    //   only on the branch below, so the object literal genuinely carries
+    //   `unix: string | undefined` and the type must say so. The alternative — building
+    //   the key conditionally — hides that this request is the unix-socket path.
+    const init: RequestInit & { unix?: string | undefined } = { ...defaults, unix: socket };
+    const { status, text } = yield* (
+      socket === undefined
+        ? exchange
+        : Effect.provideService(exchange, FetchHttpClient.RequestInit, init)
+    ).pipe(
+      // ⛔ `.message` only — the error object holds the request, and the request holds the token.
+      Effect.mapError((cause) => refuse(0, cause.message)),
+    );
+
+    let parsed:
+      | {
+          lease_duration?: unknown;
+          data?: { token_id?: unknown; secret?: unknown };
+          errors?: unknown;
+        }
+      | undefined;
+    try {
+      parsed = JSON.parse(text) as typeof parsed;
+    } catch {
+      parsed = undefined;
+    }
+    if (status < 200 || status >= 300) {
+      const errors = parsed?.errors;
+      const isOpenBaoBody = Array.isArray(errors);
+      const detail = isOpenBaoBody ? errors.map(String).join('; ') : 'not an OpenBao error body';
+      /**
+       * ⛔ 403 GETS THE TYPED TAG ONLY WITH A GENUINE OpenBao ERROR BODY — found on adversarial
+       *   review 2026-09-24. Status alone is not enough: a WAF, a proxy in front of OpenBao, or an
+       *   mTLS terminator can answer 403 without OpenBao ever seeing the request, and `parsed` is
+       *   then `undefined`/`errors` is not an array (the `try`/`catch` above, or a body that
+       *   parses but isn't OpenBao's shape). That is an infrastructure fault, not "this identity
+       *   is denied this role" — tagging it `PveCredentialDenied` would fold a REAL outage into
+       *   "unreadable, report noop" exactly as quietly as the bug this fix exists to remove. Only
+       *   a parsed `errors` array is OpenBao's own documented error shape (mint.ts's own header),
+       *   so it is the one signal trusted here.
+       */
+      if (status === 403 && isOpenBaoBody) {
+        return yield* Effect.fail(new PveCredentialDenied({ detail, mount: target.mount, role }));
+      }
+      return yield* Effect.fail(refuse(status, detail || '(no errors given)'));
+    }
+    const tokenId = parsed?.data?.token_id;
+    const secret = parsed?.data?.secret;
+    if (typeof tokenId !== 'string' || typeof secret !== 'string') {
+      // ⛔ REFUSE RATHER THAN RETURN A HALF CREDENTIAL, and again WITHOUT quoting the body.
+      return yield* Effect.fail(
+        new Error(
+          `${target.mount}/creds/${role} returned no token_id/secret. Either this approle lacks ` +
+            `the grant, or the mount is not ${target.mount}. Say which mount and role you needed ` +
+            `than falling back to a stored credential -- every stored PVE token is read-only.`,
+        ),
+      );
+    }
+    const lease = parsed?.lease_duration;
+    const leaseSeconds = typeof lease === 'number' ? lease : 0;
+    return { leaseSeconds, secret, tokenId } satisfies PveCredential;
+  });
+
+/**
+ * The header PVE wants. `PVEAPIToken=<tokenid>=<secret>`.
+ *
+ * ⚠️ THE SEPARATOR IS `=`, NOT `:`. Proxmox rejects the colon form with a 401 that says only
+ *   "authentication failure", which reads as a bad credential rather than as a malformed header.
+ */
+export const authorization = (credential: PveCredential, target: ApiTarget): string =>
+  target.scheme === 'pbs'
+    ? `PBSAPIToken=${credential.tokenId}:${credential.secret}`
+    : `PVEAPIToken=${credential.tokenId}=${credential.secret}`;

package/src/proxmox/network-apply.ts

@@ -52,7 +52,7 @@ import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import { guardNetworkApply } from './apply-endpoints.ts';
 import { pveWith } from './client.ts';
-import { mint } from './credentials.ts';
+import { mint } from './mint.ts';
 import { awaitTask, degradedReason, pendingCount } from './network-apply-read.ts';
 import type { PveRequirements } from './resource.ts';
 import type { WithTarget } from './resource.ts';

package/src/proxmox/provision-cli-fake.ts

@@ -61,6 +61,17 @@ const text = (key: string, value: string) => (value === '' ? {} : { [key]: value
 /** Every item GET the scripts and the providers make, keyed `access/…` without a leading slash. */
 export const apiView = (state: CliState): Record<string, unknown> => {
   const view: Record<string, unknown> = { 'access/acl': state.acl };
+  /**
+   * ★ THE LIST SHAPE, ADDED FOR role.ts's DISTILLED MIGRATION (2026-09-24). `Proxmox.Role` now
+   *   reads `GET /access/roles` (role.ts's header: the item endpoint's generated schema has a
+   *   fixed privilege enumeration this fixture must not rely on). The fake CLI's own `pvesh get
+   *   /access/roles/{id}` calls (provision-bootstrap.ts's script) still use the ITEM entries
+   *   below, so both stay populated from the same `state.roles`.
+   */
+  view['access/roles'] = Object.entries(state.roles).map(([roleid, privs]) => ({
+    privs: privs.join(','),
+    roleid,
+  }));
   for (const [id, privs] of Object.entries(state.roles)) {
     view[`access/roles/${id}`] = Object.fromEntries(privs.map((priv) => [priv, 1]));
   }

package/src/proxmox/provision-declare.test.ts

@@ -37,7 +37,12 @@ const bootstrapped = async (): Promise<CliState> => {
 
 const engineOn = (state: CliState) => {
   const live = apiView(state);
-  const fake = fakePve((call) => (call.method === 'GET' ? live[call.path] : 'UPID:fake'));
+  // ⚠️ `decodeURIComponent` — user.ts's own ⚠️: distilled percent-encodes a `{userid}` label
+  //   substitution (`hf-provision@pve` -> `hf-provision%40pve`), where `apiView`'s keys stay
+  //   literal (it also serves the raw shell-CLI fake, which never sees a URL at all).
+  const fake = fakePve((call) =>
+    call.method === 'GET' ? live[decodeURIComponent(call.path)] : 'UPID:fake',
+  );
   const providers = Layer.mergeAll(
     ProxmoxAclProvider(),
     ProxmoxGroupProvider(),

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([]);
+  });
+});