@homeflare/alchemy 0.31.0 → 0.31.1

package/src/proxmox/credentials.ts

@@ -28,13 +28,6 @@
  *   secret that reached an attribute would outlive its 300s lease by months, in four places.
  *   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';
-
 /**
  * ★ NO SESSION, ON PURPOSE, AND THIS IS WHAT UNBLOCKED `wip/bao-policy`.
  *   `CommandExecutor.run` requires a `ScopedPlanStatusSession`, and Alchemy gives one to
@@ -125,130 +118,7 @@ export type PveCredential = {
 /** The environment `mint` resolves OpenBao from — `process.env` unless a test passes its own. */
 export type BaoEnvironment = Readonly<Record<string, string | undefined>>;
 
-/** 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 detail = Array.isArray(errors)
-        ? errors.map(String).join('; ')
-        : 'not an OpenBao error body';
-      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}`;
+// ★ `mint` and `authorization` live in mint.ts (2026-09-24) — this file is types only now, to
+//   stay under the 250-line cap once `PveCredentialDenied`'s catchers needed a real header. See
+//   mint.ts's own header. Importers: mint.ts, client.ts, lease-cache.ts, lxc-lifecycle.ts,
+//   network-apply.ts, credentials.test.ts.

package/src/proxmox/distilled-guard.ts

@@ -0,0 +1,42 @@
+/**
+ * Vendor-constraint guards (constraint-guard.ts) for a distilled-backed family — the seam
+ * acl.ts's own local `guardWrite` established (acl-wire.ts), generalized once a second family
+ * (Group) needed the SAME create/update split `resource.ts`'s `specGuards` (resource-guard.ts)
+ * gives every family still on `client.ts`. `codegen/constraints.ts` scans this package's SOURCE
+ * TEXT for the endpoint-key strings a caller passes here, so a family switching to this helper
+ * changes nothing about which vendor rules apply — same keys, same generated tables.
+ *
+ * ★ WHY `asForm` IS THE ONLY TRANSLATION NEEDED. Distilled's generated request types for every
+ *   PVE form-urlencoded operation are already `Record<string, string | undefined>` — the SAME
+ *   shape `PveForm`/`guardForm` want, minus the `?`. There is no JSON vs form-encoding gap to
+ *   bridge here the way client.ts's `pve()` had to.
+ */
+import type * as Effect from 'effect/Effect';
+import { guardForm } from './constraint-guard.ts';
+import type { EndpointKey } from './constraints.ts';
+
+/**
+ * Drops non-string fields — distilled's request type carries `?`, `guardForm` wants a plain
+ * form. ⚠️ `body: object`, NOT `Record<string, string | undefined>`: distilled's generated
+ * request types are `interface`s with no index signature, so TypeScript refuses that stricter
+ * parameter type for every one of them ("index signature ... is missing") even though every
+ * field they declare fits it. `object` accepts any of them; the cast below is where the shape
+ * is actually asserted, once, rather than at every call site.
+ */
+export const asForm = (body: object): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(body as Record<string, unknown>).filter(
+      (e): e is [string, string] => typeof e[1] === 'string',
+    ),
+  );
+
+/**
+ * `presence`: whether a CREATE is really about to happen (required fields are enforced) or the
+ * form is only being value-checked in passing — see resource-guard.ts's own header on why this
+ * is not "this is the create form" but "a create is really about to happen".
+ */
+export const guardWrite = (
+  endpoint: EndpointKey,
+  body: object,
+  presence: boolean,
+): Effect.Effect<void> => guardForm(endpoint, asForm(body), presence);

package/src/proxmox/distilled-pve.ts

@@ -58,6 +58,7 @@ import type * as HttpClient from 'effect/unstable/http/HttpClient';
 import { credentials as distilledPveCredentials } from '@distilled.cloud/proxmox/Credentials';
 import type { ProxmoxOpContext } from '@distilled.cloud/proxmox/Protocol';
 import * as ProxmoxRetry from '@distilled.cloud/proxmox/Retry';
+import type { PveCredentialDenied } from './credential-errors.ts';
 import type { PveCredential, PveRole, PveTarget } from './credentials.ts';
 import { leased } from './lease-cache.ts';
 import {
@@ -131,16 +132,26 @@ export const runPveWith = <A, E>(
  * resource file calls.
  *
  * ⚠️ `| Error` IN THE RETURN TYPE IS `leased()`'s OWN FAILURE, NOT A NEW ONE THIS FILE ADDS.
- *   `credentials.ts`'s `mint` fails with a plain `Error` (an OpenBao refusal — sealed, denied, no
- *   such role) and was never typed more narrowly there; `pve()` carried the same untyped
- *   possibility before this file existed, just without a signature that said so.
+ *   `mint.ts`'s `mint` fails with a plain `Error` for most refusals (sealed, no such role) and
+ *   was never typed more narrowly there; `pve()` carried the same untyped possibility before
+ *   this file existed, just without a signature that said so.
+ *
+ * ★ `| PveCredentialDenied` IS SPELLED OUT HERE, NOT LEFT TO COLLAPSE INTO `Error`. It IS an
+ *   `Error` subtype (Data.TaggedError), so leaving it out of this union would still typecheck —
+ *   but `Effect.catchTag('PveCredentialDenied', …)` downstream (unreadable-read.ts) needs the
+ *   tag to be STATICALLY visible in the error channel to compile at all, not merely true at
+ *   runtime. Naming it here is what lets a migrated family's `readOrUnreadable` catch it.
  */
 export const runPve = <A, E>(
   target: PveTarget,
   role: PveRole,
   isWrite: boolean,
   op: Effect.Effect<A, E, ProxmoxOpContext>,
-): Effect.Effect<A, E | Cause.TimeoutError | PveClusterExhausted | Error, HttpClient.HttpClient> =>
+): Effect.Effect<
+  A,
+  E | Cause.TimeoutError | PveClusterExhausted | PveCredentialDenied | Error,
+  HttpClient.HttpClient
+> =>
   Effect.gen(function* () {
     const credential = yield* leased(target, role);
     return yield* runPveWith(target, credential, isWrite, op);

package/src/proxmox/generated/constraints/index.ts

@@ -52,4 +52,4 @@ export const PROXMOX_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>>
  * ★ A DIGEST OF THE DATA, NOT OF THE FILE TEXT, so reformatting is not a stale generation while
  *   changing a 128 to a 129 by hand is. `tests/schema-manifest.test.ts` recomputes it.
  */
-export const PROXMOX_CONSTRAINTS_DIGEST = '33b42b52d396c9e0';
+export const PROXMOX_CONSTRAINTS_DIGEST = '56eba80750ddb1d2';

package/src/proxmox/generated/constraints/pve-access.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *
@@ -39,9 +39,6 @@ export const PVE_ACCESS_CONSTRAINTS: Readonly<Record<string, EndpointConstraints
     "password": {"maxLength":64,"minLength":8,"type":"string"},
     "userid": {"format":"pve-userid","maxLength":64,"required":true,"type":"string"},
   },
-  "pve:POST /access/users/{userid}/token/{tokenid}": {
-    "expire": {"default":"same as user","minimum":0,"type":"integer"},
-  },
   "pve:PUT /access/acl": {
     "groups": {"format":"pve-groupid-list","type":"string"},
     "path": {"required":true,"type":"string"},

package/src/proxmox/generated/constraints/pve-cluster-backup.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-ceph.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-firewall.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-ha.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-metrics.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-notifications.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-replication.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-sdn.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-ceph.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-disks.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-lxc.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-network.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-qemu.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-pools.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-storage.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/group-wire.ts

@@ -0,0 +1,63 @@
+/**
+ * `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.
+ */
+import type * as access from '@distilled.cloud/proxmox/access';
+import type { GroupAttributes, GroupProps } from './group.ts';
+import { csv, text } from './values.ts';
+
+export const GROUP_CREATE = 'pve:POST /access/groups';
+export const GROUP_UPDATE = 'pve:PUT /access/groups/{groupid}';
+
+/**
+ * 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.
+ *   `create_group`/`write_user_config`/the config parser all test the comment for TRUTH, and in
+ *   Perl the one-character string `'0'` is false. So a declared `comment: '0'` is accepted by the
+ *   API, dropped on the way to `user.cfg`, and read back as absent. Normalising BOTH sides is how
+ *   `values.ts` already treats `''` as the absence of a boolean rather than as `false`.
+ */
+export const storedComment = (comment: string | undefined) => {
+  const value = comment ?? '';
+  return value === '0' ? '' : value;
+};
+
+/** The item read's `members` array, sorted into something two plans can agree on — group.ts's header. */
+const memberList = (live: readonly string[]): string[] => {
+  const joined = csv(live.map((member) => text(member)));
+  return joined === '' ? [] : joined.split(',');
+};
+
+export const createForm = (props: GroupProps): access.CreateAccessGroupRequest => ({
+  comment: storedComment(props.comment),
+  groupid: props.groupid,
+});
+
+/** ⚠️ ALWAYS SENT, EVEN EMPTY — that is how a comment is CLEARED (see group.ts's own header). */
+export const updateForm = (props: GroupProps): access.PutAccessGroupRequest => ({
+  comment: storedComment(props.comment),
+  groupid: props.groupid,
+});
+
+export 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.
+   */
+  comment: text(live.comment),
+  /** ⚠️ FROM PROPS — the item read never echoes the id back. */
+  groupid: props.groupid,
+  members: memberList(live.members),
+});
+
+/**
+ * ⚠️ `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.
+ */
+export const matches = (attributes: GroupAttributes, props: GroupProps) =>
+  attributes.comment === storedComment(props.comment);

package/src/proxmox/group.test.ts

@@ -0,0 +1,110 @@
+/**
+ * `Proxmox.Group` through Alchemy's own Plan and Apply, over a fake cluster driving the REAL
+ * `@distilled.cloud/proxmox` protocol — the family's own create/drift/retain/destroy paths;
+ * adopt-noop.test.ts owns the cross-family "adopting a matching object only reads" proof.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+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 { ProxmoxGroup, ProxmoxGroupProvider } from './group.ts';
+
+type Live = { comment: string | undefined; members: string[] };
+
+/** `access/groups` (POST) and `access/groups/{groupid}` (GET/PUT/DELETE), keyed by groupid. */
+const cluster = (groups: Map<string, Live>) =>
+  fakePve((call: PveCall) => {
+    const match = /^access\/groups(?:\/(.+))?$/.exec(call.path);
+    if (match === null) return undefined;
+    const groupid = match[1];
+    if (call.method === 'GET' && groupid !== undefined) return groups.get(groupid);
+    if (call.method === 'POST' && groupid === undefined) {
+      groups.set(call.form['groupid'] ?? '', { comment: call.form['comment'], members: [] });
+      return undefined;
+    }
+    if (call.method === 'PUT' && groupid !== undefined) {
+      const live = groups.get(groupid);
+      if (live !== undefined) groups.set(groupid, { ...live, comment: call.form['comment'] });
+      return undefined;
+    }
+    if (call.method === 'DELETE' && groupid !== undefined) {
+      groups.delete(groupid);
+      return undefined;
+    }
+    return undefined;
+  });
+
+const declare = (comment?: string) =>
+  ProxmoxGroup('mint', {
+    groupid: 'hf-mint',
+    target: FAKE_TARGET,
+    ...(comment === undefined ? {} : { comment }),
+  });
+
+const engineFor = (fake: ReturnType<typeof cluster>) =>
+  engineOver(ProxmoxGroupProvider().pipe(Layer.provideMerge(fake.layer)));
+
+describe('Proxmox.Group over the distilled protocol', () => {
+  test('creating a group that does not exist yet: one POST', async () => {
+    const groups = new Map<string, Live>();
+    const fake = cluster(groups);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      expect(await engine.deploy(declare('fence'))).toEqual({ mint: 'create' });
+    });
+    expect(fake.writes()).toEqual(['POST access/groups']);
+    expect(groups.get('hf-mint')).toEqual({ comment: 'fence', members: [] });
+  });
+
+  test('a drifted comment is corrected with exactly one PUT', async () => {
+    const groups = new Map<string, Live>([['hf-mint', { comment: 'old', members: [] }]]);
+    const fake = cluster(groups);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const report = await engine.verify(declare('fence'));
+      expect(report.rows[0]).toMatchObject({ diff: 'update' });
+      expect(await engine.deploy(declare('fence'))).toEqual({ mint: 'adopted' });
+    });
+    expect(fake.writes()).toEqual(['PUT access/groups/hf-mint']);
+    expect(groups.get('hf-mint')?.comment).toBe('fence');
+  });
+
+  // ⛔ PVE cannot store the literal comment '0' (group.ts's header) — a declared '0' must read
+  //   back as noop against a live '' rather than diffing forever.
+  test("a declared comment of '0' matches a live empty comment (PVE's own truthiness trap)", async () => {
+    const groups = new Map<string, Live>([['hf-mint', { comment: '', members: [] }]]);
+    const fake = cluster(groups);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const report = await engine.verify(declare('0'));
+      expect(report.rows[0]).toMatchObject({ diff: 'noop' });
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('undeclaring sends no DELETE (retain is the default)', async () => {
+    const groups = new Map<string, Live>();
+    const fake = cluster(groups);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await engine.deploy(declare('fence'));
+      expect(await engine.deploy(Effect.void)).toEqual({});
+    });
+    expect(fake.writes()).toEqual(['POST access/groups']);
+    expect(groups.has('hf-mint')).toBe(true);
+  });
+
+  test('RemovalPolicy.destroy() sends the DELETE', async () => {
+    const groups = new Map<string, Live>();
+    const fake = cluster(groups);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await engine.deploy(declare('fence').pipe(RemovalPolicy.destroy()));
+      expect(await engine.deploy(Effect.void)).toEqual({});
+    });
+    expect(fake.writes()).toEqual(['POST access/groups', 'DELETE access/groups/hf-mint']);
+    expect(groups.has('hf-mint')).toBe(false);
+  });
+});