@homeflare/alchemy 0.31.0 → 0.31.1

package/dist/proxmox/zfs-pool-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zfs-pool-write.d.ts","sourceRoot":"","sources":["../../src/proxmox/zfs-pool-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAA6D,CAAC;AAE9F;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe,UAAW,YAAY,KAAG,YACiC,CAAC;AAExF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,UAAW,YAAY,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAOpE,CAAC;AAKH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,SACtB,YAAY,cACP,MAAM,QACZ,MAAM,QACN,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC,MAAM,CAAC,iBAAiB,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,0GA8C/E,CAAC;AAEL;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,SAAU,YAAY,QAAQ,MAAM,wFACb,CAAC"}
+{"version":3,"file":"zfs-pool-write.d.ts","sourceRoot":"","sources":["../../src/proxmox/zfs-pool-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAA6D,CAAC;AAE9F;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe,UAAW,YAAY,KAAG,YACiC,CAAC;AAExF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,UAAW,YAAY,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAOpE,CAAC;AAKH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,SACtB,YAAY,cACP,MAAM,QACZ,MAAM,QACN,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC,MAAM,CAAC,iBAAiB,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,iKA8C/E,CAAC;AAEL;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,SAAU,YAAY,QAAQ,MAAM,+IACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",

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',
+    });
   });
 });

package/src/proxmox/api-token-form.ts

@@ -15,14 +15,17 @@ import type { ApiTokenAttributes, ApiTokenProps } from './api-token.ts';
  *   `update_token_info`, read over SSH on node-b on 2026-09-13. The two disagree in exactly the place
  *   that costs a forever-diff: the schema gives `expire` the default "same as user", and the code
  *   never implements it. api-token.ts records what that means.
+ *
+ * ★ MIGRATED OFF THE GENERATED `generated/pve.ts` PARAM TYPES ONTO `@distilled.cloud/proxmox`'s
+ *   typed `access.PutAccessUserTokenRequest`/`access.GetAccessUserTokenResponse` (2026-09-24) —
+ *   the same three fields, still form-urlencoded strings on the wire; distilled's generator
+ *   reads the identical vendor schema `generated/pve.ts` came from.
  */
-import type {
-  AccessUsersUseridTokenTokenidPostParams,
-  AccessUsersUseridTokenTokenidPutParams,
-} from './generated/pve.ts';
-import type { PveSpec } from './resource.ts';
+import type * as access from '@distilled.cloud/proxmox/access';
 import { bool, int, text } from './values.ts';
 
+export const API_TOKEN_UPDATE = 'pve:PUT /access/users/{userid}/token/{tokenid}';
+
 /**
  * `<userid>!<tokenid>` — the name the rest of PVE calls this object by.
  *
@@ -38,12 +41,8 @@ import { bool, int, text } from './values.ts';
 export const fullTokenid = (props: ApiTokenProps) => `${props.userid}!${props.tokenid}`;
 
 /**
- * Everything a token has, in the form PVE wants. Create and update send exactly this.
- *
- * ⛔ `userid` AND `tokenid` ARE NOT IN IT, and that is not an omission. Both are path segments of
- *   `access/users/{userid}/token/{tokenid}` — which is the path the POST goes to as well as the
- *   PUT — so a second copy in the body can only ever disagree with the path it was sent to.
- *   metric-server.ts omits its `id` for the same reason and says so there.
+ * Everything a token has, in the form PVE wants. Update sends exactly this (this family never
+ * creates — see api-token.ts's header).
  *
  * ⚠️ EVERY FIELD IS SENT ON EVERY WRITE, THE EMPTY COMMENT INCLUDED, BECAUSE A PUT MERGES.
  *   MEASURED in `update_token_info`: `$token->{comment} = $param->{comment} if defined(...)`
@@ -54,91 +53,49 @@ export const fullTokenid = (props: ApiTokenProps) => `${props.userid}!${props.to
  *     literally `my $deletable = { comment => 1 };`, and anything else answers
  *     "unknown option '<k>'" — so `expire` and `privsep` have no clear path at all, which is the
  *     other half of why both are required props rather than optional ones.
- *
- * ⚠️ `flag()` FROM values.ts IS DELIBERATELY NOT USED FOR `privsep`. Its entire job is turning an
- *   UNDECLARED boolean into `undefined` so the field is omitted from the form; `privsep` is a
- *   required prop precisely so that it is never undeclared, so there is nothing for it to do and
- *   its `string | undefined` return would have to be asserted away to fit `Record<string,string>`.
- *   An assertion here would be a claim about the prop that the type already makes properly.
- *
- * ★ TYPED AGAINST THE GENERATED PUT AND POST PARAMS, NOT `Record<string, string>`, since
- *   2026-09-23 — the `notification-matcher-form.ts` pattern: `Pick` rather than the whole type,
- *   because neither `AccessUsersUseridTokenTokenidPutParams` nor …`PostParams` (generated/pve.ts)
- *   carries `userid`/`tokenid` (they are path segments — see the ⛔ above) and Put alone also
- *   carries `delete`/`regenerate`, which this family never sends. A schema drift on any of the
- *   three fields this function DOES send fails `tsc` here rather than surfacing as a 400 on a live
- *   cluster; api-token.test.ts pins the assignment both ways (Put and Post) without a cast.
- *   `expire` is written as a template literal, not `String(...)`, because the generated type is
- *   `` `${number}` ``, not `string` — `String(n)` widens to plain `string` and would not typecheck.
  */
-export const shape = (
-  props: ApiTokenProps,
-): Pick<AccessUsersUseridTokenTokenidPutParams, 'comment' | 'expire' | 'privsep'> &
-  Pick<AccessUsersUseridTokenTokenidPostParams, 'comment' | 'expire' | 'privsep'> => ({
+export const shape = (props: ApiTokenProps): access.PutAccessUserTokenRequest => ({
   comment: props.comment ?? '',
-  expire: `${props.expire}`,
+  expire: String(props.expire),
   privsep: props.privsep ? '1' : '0',
+  tokenid: props.tokenid,
+  userid: props.userid,
 });
 
-export const apiTokenSpec: PveSpec<ApiTokenProps, ApiTokenAttributes> = {
-  // ⛔ THE ITEM READ NEEDS `User.Modify`, WHICH THE AUDITOR-SHAPED READ LEASE DOES NOT HAVE. The
-  //   measurement and the consequence are in the header's last ⚠️; the mechanism — a silent
-  //   "absent" rather than a 403 — is the ⛔ on `readRole` in resource.ts.
-  readRole: 'provision',
-  /**
-   * ★ NOTHING PVE REPORTS HERE IS UNWRITABLE, WHICH IS UNUSUAL IN THIS PACKAGE AND IS WHY
-   *   `matches` can compare everything it reads. The GET returns exactly `comment`, `expire` and
-   *   `privsep`; PUT accepts exactly those three. There is no autoscaled field, no server-assigned
-   *   id, no set whose order PVE reshuffles — the three killers the neighbouring files carry
-   *   ⚠️s about do not arise. The two identity fields and `fullTokenid` come from props and are
-   *   true by construction, so comparing them would be theatre.
-   * ⚠️ `undefined` WHEN NEITHER FLAG IS THERE, BECAUSE BOTH ARE ALWAYS THERE. `user.cfg`
-   *   materialises `expire` and `privsep` for every token it stores, so an answer carrying neither
-   *   is not a token — and without this guard `bool`/`int` would invent one out of their fallbacks
-   *   and the read-back guard in `reconcile` could never fire.
-   */
-  attributes: (live, props) => {
-    const expire = live['expire'];
-    const privsep = live['privsep'];
-    if (expire === undefined && privsep === undefined) return undefined;
-    return {
-      comment: text(live['comment']),
-      expire: int(expire, 0),
-      fullTokenid: fullTokenid(props),
-      /** ⚠️ FALLBACK `true`, MATCHING PVE'S API DEFAULT — unreachable given the guard above, but
-       *   wrong in the safe direction if a future release stops emitting the field. */
-      privsep: bool(privsep, true),
-      tokenid: props.tokenid,
-      userid: props.userid,
-    };
-  },
-  /**
-   * ⛔ THE SAME STRING AS `path`, AND NOT A TYPO. A token is POSTed to its OWN url, not to the
-   *   collection: MEASURED, `/access/users/{userid}/token` carries a GET and nothing else, while
-   *   POST lives on `{tokenid}`. metric-server.ts has the identical shape for the identical
-   *   reason and records the experiment there.
-   */
-  collection: (props) => `access/users/${props.userid}/token/${props.tokenid}`,
-  createForm: shape,
-  /** The vendor rules both forms are checked against at plan time — resource-spec.ts. */
-  endpoint: {
-    create: 'pve:POST /access/users/{userid}/token/{tokenid}',
-    update: 'pve:PUT /access/users/{userid}/token/{tokenid}',
-  },
-  /**
-   * ⚠️ EXACTLY THE THREE FIELDS A PUT CAN PUT BACK, WHICH IS ALSO EXACTLY WHAT THE GET REPORTS.
-   *   MEASURED, by replaying these two functions over the live GET bodies of all four token
-   *   shapes this cluster has: `metrics@pve!exporter` (no comment), `iac@pve!apply` and
-   *   `app@pve!app` (commented), and a live OpenBao lease under `hf-read@pve` (a real
-   *   non-zero `expire`, offered as both `1789327175` and `"1789327175"` since `int` must not care
-   *   which). All four answer noop; flipping `privsep` answers update; an empty body answers
-   *   absent. ⚠️ THAT IS THE COMPARISON, NOT THE ENGINE — no `alchemy plan` was run against this
-   *   family, and nothing here was written to the cluster.
-   */
-  matches: (attributes, props) =>
-    attributes.comment === (props.comment ?? '') &&
-    attributes.expire === props.expire &&
-    attributes.privsep === props.privsep,
-  path: (props) => `access/users/${props.userid}/token/${props.tokenid}`,
-  updateForm: shape,
+/**
+ * ★ NOTHING PVE REPORTS HERE IS UNWRITABLE, WHICH IS UNUSUAL IN THIS PACKAGE. The GET returns
+ *   exactly `comment`, `expire` and `privsep`; PUT accepts exactly those three.
+ * ⛔ `undefined` WHEN NEITHER FLAG IS THERE, BECAUSE BOTH ARE ALWAYS THERE FOR A REAL TOKEN.
+ *   `user.cfg` materialises `expire` and `privsep` for every token it stores, so an answer
+ *   carrying neither is not a token — the same "distilled unwraps a missing object's `{"data":
+ *   null}` to `{}`" trap group.ts's header measures, checked here the way this guard already was
+ *   before the distilled migration (api-token.ts's ⛔ on the create refusal cites the same
+ *   MEASURED schema). Without this guard `bool`/`int` would invent one out of their fallbacks and
+ *   the read-back guard in `reconcile` could never fire.
+ */
+export const attributesOf = (
+  live: access.GetAccessUserTokenResponse,
+  props: ApiTokenProps,
+): ApiTokenAttributes | undefined => {
+  if (live.expire === undefined && live.privsep === undefined) return undefined;
+  return {
+    comment: text(live.comment),
+    expire: int(live.expire, 0),
+    fullTokenid: fullTokenid(props),
+    /** ⚠️ FALLBACK `true`, MATCHING PVE'S API DEFAULT — unreachable given the guard above, but
+     *   wrong in the safe direction if a future release stops emitting the field. */
+    privsep: bool(live.privsep, true),
+    tokenid: props.tokenid,
+    userid: props.userid,
+  };
 };
+
+/**
+ * ⚠️ EXACTLY THE THREE FIELDS A PUT CAN PUT BACK, WHICH IS ALSO EXACTLY WHAT THE GET REPORTS.
+ *   MEASURED (pre-migration, replaying against four live token shapes — see the old PR): all
+ *   answer noop; flipping `privsep` answers update; an empty body answers absent.
+ */
+export const matches = (attributes: ApiTokenAttributes, props: ApiTokenProps) =>
+  attributes.comment === (props.comment ?? '') &&
+  attributes.expire === props.expire &&
+  attributes.privsep === props.privsep;