@homeflare/alchemy 0.30.0 → 0.31.1

package/src/discord/resource.ts

@@ -0,0 +1,164 @@
+/**
+ * One shape for every Discord application-command object — global and guild-scoped alike.
+ *
+ * ⛔ THE ALTERNATIVE IS COPYING THE SAME READ/RECONCILE/DELETE PER RESOURCE. `application-command.ts`
+ *   and `guild-application-command.ts` differ only in which distilled operations they call and
+ *   whether `guild_id` is part of identity — so the read/diff/reconcile/delete flow lives here
+ *   once, mirroring `../netbox/resource.ts`'s `netboxOperations`/`netboxHandlers` split.
+ *
+ * ★ UNLIKE NETBOX, THIS FOLLOWS UPSTREAM'S `Snippet.ts` READ/RECONCILE SHAPE EXACTLY (S7–S9), NOT
+ *   netbox's "adopt silently" gap (H1). Discord commands carry no ownership marker of any kind —
+ *   no tags, no metadata field a bot could stamp — so this is precisely the "marker-less API" S8
+ *   describes, and `Snippet.ts@v2.0.0-beta.79#read` is the cited reference: an existing match is
+ *   `Unowned(attrs)` on a cold read (no persisted `output`), and plain attributes on a warm read
+ *   (persisted `output` says we already made or adopted this exact command). `adopt(true)` (H5),
+ *   piped onto each resource by the constructors in the two resource files, is what turns that
+ *   `Unowned` into a silent one-time takeover instead of an `OwnedBySomeoneElse` refusal.
+ *
+ * ★ RECONCILE IS ONE UPSERT CALL, LIKE `Snippet.ts`'s `putSnippet`. Discord's own docs for both
+ *   Create Global/Guild Application Command say a command with the same name (and type) as an
+ *   existing one OVERWRITES it — the create endpoint is a true upsert, not a create-only call that
+ *   409s on a name collision. ⚠️ REASONED NOT MEASURED (no token available to this task; see
+ *   `docs/discord.md`): this is Discord's documented behaviour, unchanged across API v10, but it
+ *   has not been exercised against the real API by this change. One call therefore converges
+ *   greenfield create, routine update AND adoption alike — there is no separate PATCH path, and
+ *   S10's "zero write calls when there is no drift" is still honoured because `reconcile` skips
+ *   the call entirely when `spec.matches` already holds.
+ *
+ * ⚠️ `list` ANSWERS EMPTY, ON PURPOSE, EVEN THOUGH THE DISTILLED LIST OPERATIONS EXIST. A bot's
+ *   guild command set is exactly what `hf-discord-halibut.service` bulk-overwrites at every
+ *   restart (see `docs/discord.md#halibut`); a `nuke` that enumerated and swept every live command
+ *   would fight that ownership, not just this resource's own declarations. Adoption stays
+ *   explicit, the same reasoning netbox's `list` gives for a shared instance predating the kit.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import type { DiscordOpContext } from '@distilled.cloud/discord/Protocol';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { CredentialsFromEnv } from './credentials.ts';
+
+/**
+ * What every stack must still provide after `discordHandlers` bakes in `CredentialsFromEnv`
+ * (below): the transport. `DiscordOpContext` is `Credentials | HttpClient.HttpClient`, so once
+ * `Credentials` is supplied, `HttpClient.HttpClient` is what remains — mirroring
+ * `../netbox/resource.ts#NetboxRequirements`.
+ */
+export type DiscordRequirements = HttpClient.HttpClient;
+
+/** Every Discord command resource's identity key, regardless of scope. */
+export interface DiscordCommandIdentity {
+  readonly name: string;
+}
+
+/**
+ * One Discord command object's distilled calls. `Live` is whatever the SDK decodes
+ * (`ApplicationCommandResponse`); `E` is left to each resource file to declare, so a call site's
+ * precise error union (in practice always `DiscordOpError` — see `protocol.ts` — because every
+ * generated Discord operation shares one error channel) flows straight through.
+ */
+export type DiscordSpec<
+  Props extends DiscordCommandIdentity,
+  Live,
+  Attributes extends object,
+  E,
+> = {
+  /** Locate the live command by its declared name within this spec's scope (app, or app+guild). */
+  readonly fetchByName: (props: Props) => Effect.Effect<Live | undefined, E, DiscordOpContext>;
+  readonly attributes: (live: Live) => Attributes;
+  readonly matches: (attributes: Attributes, props: Props) => boolean;
+  readonly upsertBody: (props: Props) => Record<string, unknown>;
+  /** POST create-or-overwrite — see the upsert note above. */
+  readonly upsert: (
+    props: Props,
+    body: Record<string, unknown>,
+  ) => Effect.Effect<Live, E, DiscordOpContext>;
+  readonly destroy: (props: Props, live: Live) => Effect.Effect<unknown, E, DiscordOpContext>;
+  /** For error messages and test descriptions. */
+  readonly describe: (props: Props) => string;
+};
+
+export const discordOperations = <
+  Props extends DiscordCommandIdentity,
+  Live,
+  Attributes extends object,
+  E,
+>(
+  spec: DiscordSpec<Props, Live, Attributes, E>,
+) => ({
+  read: ({ olds, output }: { olds: Props; output: Attributes | undefined }) =>
+    Effect.gen(function* () {
+      const live = yield* spec.fetchByName(olds);
+      if (live === undefined) return undefined;
+      const attrs = spec.attributes(live);
+      // Warm read: a prior apply already created or adopted this exact command — ours.
+      if (output !== undefined) return attrs;
+      // Cold read (fresh store, or state lost): no ownership marker exists on this vendor,
+      // so any match is `Unowned` until `adopt(true)` (or `--adopt`) says otherwise (S7, S8).
+      return Unowned(attrs);
+    }),
+
+  diff: (news: Input<Props>, output: Attributes | undefined) =>
+    Effect.gen(function* () {
+      if (output === undefined || !isResolved(news)) return undefined;
+      const live = yield* spec.fetchByName(news);
+      if (live === undefined) return { action: 'update' } as const;
+      return spec.matches(spec.attributes(live), news)
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: (news: Props) =>
+    Effect.gen(function* () {
+      const before = yield* spec.fetchByName(news);
+      if (before !== undefined && spec.matches(spec.attributes(before), news)) {
+        // Already exactly what is declared — S10: no write.
+        return spec.attributes(before);
+      }
+      const body = spec.upsertBody(news);
+      const after = yield* spec.upsert(news, body);
+      return spec.attributes(after);
+    }),
+
+  // ⚠️ GAP, NOT SOLVED: a TOCTOU race between the fetch above and the delete call below could
+  //   see Discord answer 404 on a command that vanished between the two — S11 asks that race to
+  //   be treated as success, `catchTag('NotFound', …)`. The SDK's declared error type for every
+  //   operation does not include `NotFound` (see `docs/discord.md#sdk-gaps` — measured, not
+  //   assumed), so there is no typed tag to catch here without an unsafe cast. Left unhandled.
+  destroy: (olds: Props) =>
+    Effect.gen(function* () {
+      const live = yield* spec.fetchByName(olds);
+      if (live === undefined) return;
+      yield* spec.destroy(olds, live);
+    }),
+});
+
+/**
+ * The four provider handlers for a spec'd Discord command, wired once.
+ *
+ * ★ CREDENTIALS ARE PROVIDED HERE, ONCE. `CredentialsFromEnv` resolves `DISCORD_BOT_TOKEN` /
+ *   `DISCORD_TOKEN` on the calling fiber per request (credentials.ts), so this closure keeps that
+ *   laziness — nothing is captured at module load.
+ */
+export const discordHandlers = <
+  Props extends DiscordCommandIdentity,
+  Live,
+  Attributes extends object,
+  E,
+>(
+  spec: DiscordSpec<Props, Live, Attributes, E>,
+) => {
+  const ops = discordOperations(spec);
+  const withCredentials = <A>(effect: Effect.Effect<A, E, DiscordOpContext>) =>
+    Effect.provide(effect, CredentialsFromEnv);
+  return {
+    list: () => Effect.succeed([]),
+    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/discord/retry.test.ts

@@ -0,0 +1,74 @@
+/**
+ * Discord's 429 handling — proving the SDK's OWN default retry policy (`@distilled.cloud/core`'s
+ * `makeDefault`, threaded through every operation via `retry: Retry.Retry` — see `resource.ts`'s
+ * header note and `docs/discord.md#rate-limits`), not a house re-implementation. This file exists
+ * because "respect Discord's rate limits with a bounded retry" is a requirement this task must
+ * satisfy, and the honest way to satisfy it here is to prove the SDK already does — nothing in
+ * `resource.ts` installs a `Discord.Retry.policy` of its own, so if this test ever failed to
+ * retry, or failed to STOP retrying, there would be nothing in this package to fix; the fix would
+ * be in `@distilled.cloud/discord`.
+ *
+ * ⛔ A TEST THAT CANNOT FAIL PROVES NOTHING. Both cases below assert on the fake's own call count
+ *   (`fake.seen.length`), not just on the eventual Effect outcome — a policy that retried once,
+ *   or one that retried forever, would each still "eventually succeed" or "eventually fail" on
+ *   SOME outcome; the call count is what makes "bounded" a real, checkable claim rather than an
+ *   assumption the test's own passing would not have caught.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { spec } from './guild-application-command.ts';
+import type { GuildApplicationCommandProps } from './guild-application-command.ts';
+import { fakeDiscord, fakeDiscordLayer, fakeRateLimited } from './fake-discord.ts';
+
+const APP = '111111111111111111';
+const GUILD = '222222222222222222';
+const CMD_PATH = `/applications/${APP}/guilds/${GUILD}/commands`;
+const PROPS: GuildApplicationCommandProps = { applicationId: APP, guildId: GUILD, name: 'ping' };
+
+const liveCommand = () => ({
+  application_id: APP,
+  default_member_permissions: null,
+  description: '',
+  guild_id: GUILD,
+  id: '999',
+  name: 'ping',
+  nsfw: false,
+  type: 1,
+  version: '1',
+});
+
+describe('the SDK default Retry policy on a 429', () => {
+  test('two 429s (Retry-After: 0) then a 200 — retried, and it converges', async () => {
+    const fake = fakeDiscord((method, url, _body, callNumber) => {
+      if (method !== 'GET' || url.pathname !== CMD_PATH) return new Response(null, { status: 500 });
+      return callNumber <= 2 ? fakeRateLimited(0) : Response.json([liveCommand()]);
+    });
+    const live = await Effect.runPromise(
+      spec.fetchByName(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe('999');
+    expect(fake.seen).toHaveLength(3);
+  }, 15_000);
+
+  /**
+   * ★ THE BOUND ITSELF. `@distilled.cloud/core`'s `makeDefault` caps this at `Schedule.recurs(8)`
+   *   — 8 retries, 9 attempts total — regardless of how long the server keeps answering 429. A
+   *   server that never recovers must still let the caller find out, in bounded time, rather than
+   *   parking the fiber forever; that is the literal meaning of "bounded retry".
+   */
+  test('429 forever is a bounded number of attempts, then a typed failure — never an infinite loop', async () => {
+    const fake = fakeDiscord((method, url) =>
+      method === 'GET' && url.pathname === CMD_PATH
+        ? fakeRateLimited(0)
+        : new Response(null, { status: 500 }),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchByName(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('TooManyRequests');
+    // 1 initial attempt + at most 8 retries. Strictly greater than 1 proves a retry happened at
+    // all; at most 9 proves it stopped rather than continuing past the documented bound.
+    expect(fake.seen.length).toBeGreaterThan(1);
+    expect(fake.seen.length).toBeLessThanOrEqual(9);
+  }, 15_000);
+});

package/src/proxmox/acl-wire.ts

@@ -0,0 +1,83 @@
+/**
+ * `Proxmox.Acl`'s wire shape: PVE's PUT form, identity, and how a live row becomes attributes.
+ * Split out of acl.ts (2026-09-24) to keep that file under the 250-line cap once the cries-wolf
+ * fix needed real space — the api-token.ts/api-token-form.ts seam, same reasoning: this file
+ * answers "what does PVE store", acl.ts answers "when has it changed" and drives the provider.
+ */
+import type * as access from '@distilled.cloud/proxmox/access';
+import { guardForm } from './constraint-guard.ts';
+import type { AclAttributes, AclProps } from './acl.ts';
+
+/** ⚠️ PVE normalises ACL paths (collapses repeated slashes, strips the trailing one, adds a leading one). */
+export const normalize = (raw: string) => `/${raw.split('/').filter(Boolean).join('/')}`;
+
+/** The write names the subject with a plural key that differs per kind; the read answers singular. */
+const SUBJECT_FIELD = { group: 'groups', token: 'tokens', user: 'users' } as const;
+
+/** The vendor endpoint every write and every constraint check runs against. */
+const ENDPOINT = 'pve:PUT /access/acl';
+
+/** The tuple PVE keys a grant by, as PUT's fields. */
+export const tuple = (props: AclProps): access.PutAccessAclRequest => ({
+  path: normalize(props.path),
+  roles: props.roleid,
+  [SUBJECT_FIELD[props.type]]: props.ugid,
+});
+
+/** Create and update are one call: the tuple plus the single mutable field. */
+export const bind = (props: AclProps): access.PutAccessAclRequest => ({
+  ...tuple(props),
+  propagate: props.propagate === false ? '0' : '1',
+});
+
+/** `guardForm` wants a plain string-valued form; distilled's request type carries `?` instead. */
+const asForm = (body: access.PutAccessAclRequest): Record<string, string> =>
+  Object.fromEntries(Object.entries(body).filter((e): e is [string, string] => e[1] !== undefined));
+
+/**
+ * ⚠️ ALWAYS PRESENCE-CHECKED. `bind`'s output IS the create form (there is no separate,
+ *   narrower update form for this family — see acl.ts's header), so the vendor's
+ *   required-parameter check is never wrong to run; the two separate create/update passes the
+ *   generic factory ran elsewhere collapse to one call here without losing coverage.
+ */
+export const guardWrite = (props: AclProps) => guardForm(ENDPOINT, asForm(bind(props)), true);
+
+/** What a change of this string means: not an edit, a different grant. */
+export const identity = (grant: Pick<AclAttributes, 'path' | 'roleid' | 'type' | 'ugid'>) =>
+  [normalize(grant.path), grant.type, grant.ugid, grant.roleid].join(' ');
+
+const find = (rows: readonly access.ListAccessAclResponseBodyItem[], props: AclProps) =>
+  rows.find(
+    (row) =>
+      row.path === normalize(props.path) &&
+      row.type === props.type &&
+      row.ugid === props.ugid &&
+      row.roleid === props.roleid,
+  );
+
+/**
+ * ⚠️ PVE answers `propagate` as 1/0 rather than true/false, and OMITS it when it carries the API
+ *   default, which is ON. distilled's generated schema types it `unknown` for the same reason.
+ */
+const propagates = (row: access.ListAccessAclResponseBodyItem) => {
+  const value = row.propagate;
+  return value === undefined || value === 1 || value === true || value === '1';
+};
+
+export const attributesOf = (
+  rows: readonly access.ListAccessAclResponseBodyItem[],
+  props: AclProps,
+): AclAttributes => {
+  const row = find(rows, props);
+  return {
+    bound: row !== undefined,
+    path: normalize(props.path),
+    propagate: row !== undefined && propagates(row),
+    roleid: props.roleid,
+    type: props.type,
+    ugid: props.ugid,
+  };
+};
+
+export const matches = (attributes: AclAttributes, props: AclProps) =>
+  attributes.bound && attributes.propagate === (props.propagate !== false);

package/src/proxmox/acl.ts

@@ -47,9 +47,15 @@ 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 { guardForm } from './constraint-guard.ts';
+import { attributesOf, bind, guardWrite, identity, matches, tuple } from './acl-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';
 
 /** PVE's three kinds of subject. The read answers this word; the write wants its plural. */
 export type AclSubjectType = 'user' | 'group' | 'token';
@@ -91,91 +97,23 @@ export interface ProxmoxAcl extends Resource<
 
 export const ProxmoxAcl = Resource<ProxmoxAcl>('Proxmox.Acl');
 
-/** ⚠️ PVE normalises ACL paths (collapses repeated slashes, strips the trailing one, adds a leading one). */
-const normalize = (raw: string) => `/${raw.split('/').filter(Boolean).join('/')}`;
-
-/** The write names the subject with a plural key that differs per kind; the read answers singular. */
-const SUBJECT_FIELD = { group: 'groups', token: 'tokens', user: 'users' } as const;
-
-/** The vendor endpoint every write and every constraint check runs against. */
-const ENDPOINT = 'pve:PUT /access/acl';
-
-/** The tuple PVE keys a grant by, as PUT's fields. */
-const tuple = (props: AclProps): access.PutAccessAclRequest => ({
-  path: normalize(props.path),
-  roles: props.roleid,
-  [SUBJECT_FIELD[props.type]]: props.ugid,
-});
-
-/** Create and update are one call: the tuple plus the single mutable field. */
-const bind = (props: AclProps): access.PutAccessAclRequest => ({
-  ...tuple(props),
-  propagate: props.propagate === false ? '0' : '1',
-});
-
-/** `guardForm` wants a plain string-valued form; distilled's request type carries `?` instead. */
-const asForm = (body: access.PutAccessAclRequest): Record<string, string> =>
-  Object.fromEntries(Object.entries(body).filter((e): e is [string, string] => e[1] !== undefined));
-
-/**
- * ⚠️ ALWAYS PRESENCE-CHECKED. `bind`'s output IS the create form (there is no separate,
- *   narrower update form for this family — see the header), so the vendor's required-parameter
- *   check is never wrong to run; the two separate create/update passes the generic factory ran
- *   elsewhere collapse to one call here without losing coverage.
- */
-const guardWrite = (props: AclProps) => guardForm(ENDPOINT, asForm(bind(props)), true);
-
-/** What a change of this string means: not an edit, a different grant. */
-const identity = (grant: Pick<AclAttributes, 'path' | 'roleid' | 'type' | 'ugid'>) =>
-  [normalize(grant.path), grant.type, grant.ugid, grant.roleid].join(' ');
-
-const find = (rows: readonly access.ListAccessAclResponseBodyItem[], props: AclProps) =>
-  rows.find(
-    (row) =>
-      row.path === normalize(props.path) &&
-      row.type === props.type &&
-      row.ugid === props.ugid &&
-      row.roleid === props.roleid,
-  );
-
-/**
- * ⚠️ PVE answers `propagate` as 1/0 rather than true/false, and OMITS it when it carries the API
- *   default, which is ON. distilled's generated schema types it `unknown` for the same reason.
- */
-const propagates = (row: access.ListAccessAclResponseBodyItem) => {
-  const value = row.propagate;
-  return value === undefined || value === 1 || value === true || value === '1';
-};
-
-const attributesOf = (
-  rows: readonly access.ListAccessAclResponseBodyItem[],
-  props: AclProps,
-): AclAttributes => {
-  const row = find(rows, props);
-  return {
-    bound: row !== undefined,
-    path: normalize(props.path),
-    propagate: row !== undefined && propagates(row),
-    roleid: props.roleid,
-    type: props.type,
-    ugid: props.ugid,
-  };
-};
-
-const matches = (attributes: AclAttributes, props: AclProps) =>
-  attributes.bound && attributes.propagate === (props.propagate !== false);
-
 /**
  * ⛔ `readRole: 'provision'`, WITHOUT WHICH EVERY GRANT READS BACK AS ABSENT — see the header's
- *   ⛔ on filtering. `read`/`orElseSucceed` folds ANY failure (network, a genuine permission
- *   error) into "unknown"; a 200 with an empty or non-matching list is a real answer, not folded.
+ *   ⛔ on filtering. `orElseSucceed` still folds every OTHER failure into `undefined`.
+ * ★ `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.
  */
 const readAttributes = (props: AclProps) =>
-  runPve(props.target, 'provision', false, access.listAccessAcl({})).pipe(
-    Effect.map((rows) => attributesOf(rows, props)),
+  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. */
+const dropUnreadable = (live: AclAttributes | Unreadable | undefined) =>
+  live === UNREADABLE ? undefined : live;
+
 export const ProxmoxAclProvider = () =>
   Provider.effect(
     ProxmoxAcl,
@@ -184,7 +122,7 @@ export const ProxmoxAclProvider = () =>
         /** ⛔ EMPTY LIKE EVERY OTHER PVE RESOURCE. Adopting every grant a human ever clicked is not adoption. */
         list: () => Effect.succeed([]),
         read: Effect.fn(function* ({ olds }) {
-          return yield* readAttributes(olds);
+          return dropUnreadable(yield* readAttributes(olds));
         }),
         /**
          * ⛔ AN IDENTITY CHANGE IS A REPLACE. Editing `roleid` (or the subject, or the path) would
@@ -201,6 +139,12 @@ export const ProxmoxAclProvider = () =>
           yield* guardWrite(news);
           if (output === undefined) return undefined;
           const live = yield* readAttributes(news);
+          // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and
+          //   force `update` on a grant that was plainly there — see unreadable-read.ts.
+          if (live === UNREADABLE) {
+            yield* unreadableWarning('Proxmox.Acl', identity(news));
+            return { action: 'noop' } as const;
+          }
           return live !== undefined && matches(live, news)
             ? ({ action: 'noop' } as const)
             : ({ action: 'update' } as const);
@@ -212,12 +156,15 @@ export const ProxmoxAclProvider = () =>
          *   the gap.
          */
         reconcile: Effect.fn(function* ({ news }) {
-          const before = yield* readAttributes(news);
+          // ⚠️ `dropUnreadable`: reconcile only runs once `provision` already minted for the
+          //   write below, so `UNREADABLE` here is a near-impossible race, not the routine case
+          //   `diff` handles — treating it as "not yet bound" costs at most one redundant PUT.
+          const before = dropUnreadable(yield* readAttributes(news));
           yield* guardWrite(news);
           if (before === undefined || !matches(before, news)) {
             yield* runPve(news.target, 'provision', true, access.putAccessAcl(bind(news)));
           }
-          const after = yield* readAttributes(news);
+          const after = dropUnreadable(yield* readAttributes(news));
           if (after === undefined || !after.bound) {
             return yield* Effect.die(
               new Error(

package/src/proxmox/adopt-noop.test.ts

@@ -16,9 +16,11 @@ import { engineOver } from '../verify/fake-engine.ts';
 import { ProxmoxAcl, ProxmoxAclProvider } from './acl.ts';
 import type { PbsTarget } from './credentials.ts';
 import { FAKE_TARGET, fakePve, withoutBao } from './fake-pve.ts';
+import { ProxmoxGroup, ProxmoxGroupProvider } from './group.ts';
 import { PbsDatastore, PbsDatastoreProvider } from './pbs-datastore.ts';
 import { ProxmoxPool, ProxmoxPoolProvider } from './pool.ts';
 import { ProxmoxSdnApply, ProxmoxSdnApplyProvider } from './sdn-apply.ts';
+import { ProxmoxUser, ProxmoxUserProvider } from './user.ts';
 
 const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };
 
@@ -54,6 +56,22 @@ const cases: readonly Case[] = [
     name: 'Proxmox.Acl (wraps the factory reconcile)',
     provider: ProxmoxAclProvider as never,
   },
+  {
+    declare: () =>
+      ProxmoxGroup('mint', { comment: 'fence', groupid: 'hf-mint', target: FAKE_TARGET }) as never,
+    live: { 'access/groups/hf-mint': { comment: 'fence', members: [] } },
+    name: 'Proxmox.Group (its own reconcile, since the distilled migration)',
+    provider: ProxmoxGroupProvider as never,
+  },
+  {
+    // ⚠️ KEY IS PERCENT-ENCODED — user.ts's own ⚠️: distilled's `{userid}` substitution encodes
+    //   the `@`, and `clusterWith` below does no decoding of `call.path`.
+    declare: () =>
+      ProxmoxUser('iac', { comment: 'x', target: FAKE_TARGET, userid: 'iac@pve' }) as never,
+    live: { 'access/users/iac%40pve': { comment: 'x', enable: 1, expire: 0 } },
+    name: 'Proxmox.User (its own reconcile, since the distilled migration)',
+    provider: ProxmoxUserProvider as never,
+  },
   {
     declare: () =>
       PbsDatastore('store1', {

package/src/proxmox/api-token-adopt.test.ts

@@ -17,10 +17,6 @@ import { engineOver } from '../verify/fake-engine.ts';
 import { type ApiTokenProps, ProxmoxApiToken, ProxmoxApiTokenProvider } from './api-token.ts';
 import { shape } from './api-token-form.ts';
 import { FAKE_TARGET, type PveCall, fakePve, withoutBao } from './fake-pve.ts';
-import type {
-  AccessUsersUseridTokenTokenidPostParams,
-  AccessUsersUseridTokenTokenidPutParams,
-} from './generated/pve.ts';
 
 type Live = { comment?: string; expire: number | string; privsep: number };
 
@@ -32,12 +28,19 @@ const tokens = new Map<string, Live>([
   ['access/users/svc@pve/token/lease2', { comment: 'lease', expire: '1789327175', privsep: 0 }],
 ]);
 
+/**
+ * ⚠️ `decodeURIComponent` — user.ts's own ⚠️, and it applies here too: distilled's `{userid}`/
+ *   `{tokenid}` label substitution percent-encodes `iac@pve` to `iac%40pve`, where `client.ts`'s
+ *   plain string concatenation never did. `tokens`'s keys stay literal (`@`); only the lookup
+ *   decodes, so this map does not have to be rewritten for a wire-level detail.
+ */
 const cluster = () =>
   fakePve((call: PveCall) => {
-    if (call.method === 'GET') return tokens.get(call.path);
+    const key = decodeURIComponent(call.path);
+    if (call.method === 'GET') return tokens.get(key);
     if (call.method === 'PUT') {
-      const live = tokens.get(call.path);
-      if (live !== undefined) tokens.set(call.path, { ...live, ...call.form });
+      const live = tokens.get(key);
+      if (live !== undefined) tokens.set(key, { ...live, ...call.form });
       return call.form;
     }
     return undefined;
@@ -125,14 +128,27 @@ describe('adopting a metadata-only ApiToken declaration', () => {
       expect(await engine.deploy(flipped())).toEqual({ 'iac-pve-apply': 'adopted' });
     });
     const put = fake.calls.find((call) => call.method === 'PUT');
-    expect(fake.writes()).toEqual(['PUT access/users/iac@pve/token/apply']);
+    // ⚠️ PERCENT-ENCODED — see the ⚠️ on `cluster` above.
+    expect(fake.writes()).toEqual(['PUT access/users/iac%40pve/token/apply']);
+    // ⛔ `userid`/`tokenid` DO NOT LEAK INTO THE WIRE FORM, even though `shape()` (below) must
+    //   include them for distilled's `putAccessUserToken` call — they are `T.Label()` fields,
+    //   pulled into the URL by the protocol layer and never sent in the body. MEASURED here.
     expect(put?.pairs.map(([name]) => name)).toEqual(['comment', 'expire', 'privsep']);
   });
 
-  test('the form keys typecheck against both generated PVE params, with no cast', () => {
+  // ★ THE OLD PROOF ("typechecks against the generated PVE params, no cast") is now `shape()`'s
+  //   own return type (`access.PutAccessUserTokenRequest`), checked at compile time by every
+  //   caller. This pins the one thing that is not: `userid`/`tokenid` ARE in the object `shape`
+  //   builds (distilled needs them to fill the URL), even though the wire test above proves
+  //   they never reach the actual PUT body.
+  test('shape() carries userid/tokenid for distilled, alongside the three mutable fields', () => {
     const props = propsFor('iac@pve', 'apply', { comment: 'automation' });
-    const post: AccessUsersUseridTokenTokenidPostParams = shape(props);
-    const put: AccessUsersUseridTokenTokenidPutParams = shape(props);
-    expect(post).toEqual(put);
+    expect(shape(props)).toEqual({
+      comment: 'automation',
+      expire: '0',
+      privsep: '0',
+      tokenid: 'apply',
+      userid: 'iac@pve',
+    });
   });
 });