@homeflare/alchemy 0.30.0 → 0.31.1

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;

package/src/proxmox/api-token.ts

@@ -2,17 +2,15 @@
  * `Proxmox.ApiToken` — a PVE API token: the thing a service actually authenticates as.
  *
  * ⛔ THE SECRET EXISTS FOR ONE HTTP RESPONSE AND THEN NOWHERE. MEASURED from the cluster's own
- *   schema (`/usr/share/pve-docs/api-viewer/apidoc.js` on node-b, 2026-09-13): POST returns
- *   `["full-tokenid","info","value"]`; PUT returns `["comment","expire","full-tokenid","privsep",
- *   "value"]` with `value` present ONLY when `regenerate` was set; GET returns
- *   `["comment","expire","privsep"]` and never the secret. A live token agrees —
- *   `GET /access/users/metrics@pve/token/exporter` answers `{"expire":0,"privsep":0}`. PVE says
- *   it plainly on the POST: the value "needs to be stored as it cannot be retrieved afterwards".
+ *   schema: POST returns `["full-tokenid","info","value"]`; PUT returns `["comment","expire",
+ *   "full-tokenid","privsep","value"]` with `value` present ONLY when `regenerate` was set; GET
+ *   returns `["comment","expire","privsep"]` and never the secret. PVE says it plainly on the
+ *   POST: the value "needs to be stored as it cannot be retrieved afterwards".
  *
  * ⛔ SO A TOKEN THIS RESOURCE CREATES IS UNUSABLE, AND SAYING SO IS THE POINT OF THIS BLOCK. The
  *   secret may not become an attribute: Alchemy persists attributes UNENCRYPTED, and this estate's
- *   state store is a Postgres dumped nightly (the ⛔ in credentials.ts). So `reconcile` drops the
- *   value on the floor, and what lands is a live credential in `/etc/pve/user.cfg` whose secret
+ *   state store is a Postgres dumped nightly (the ⛔ in credentials.ts). So `reconcile` refuses
+ *   before any POST, and what would land is a live credential in `/etc/pve/user.cfg` whose secret
  *   nobody holds. No `regenerate` rescues it, because a regenerated value is discarded the same
  *   way. The only escape is an operator who captured the value out of band — which this provider
  *   gives them no way to do.
@@ -20,50 +18,49 @@
  *     whole of a token's policy, and declaring them is real work: it is how `expire` stops being
  *     whatever somebody typed in 2024. Mint NEW tokens where the secret can be caught — OpenBao's
  *     `proxmox-c1` mount, or a human at `pveum user token add`.
- *   ⛔ ★ CORRECTED 2026-09-23 — THIS PARAGRAPH PREVIOUSLY SAID "THE CREATE PATH IS LEFT REACHABLE
- *     RATHER THAN STUBBED… the honest arrangement is a create that works". THAT CONTRADICTED THE
- *     `reconcile` BELOW, WHICH REFUSES: `handlers.reconcile` calls `Effect.die` by name when `read`
- *     answers absent, before any POST — metadata-only per decision 9 (2026-09-23), exported on the
- *     barrel as an adopt-and-manage-only Resource. A create that silently did nothing WOULD be the
- *     lie resource.ts's ★ describes for a stubbed delete; refusing loudly, by name, with the two
- *     ways to get a usable token, is the honest arrangement instead — see the ★ further down and
- *     api-token-adopt.test.ts's absent-token row, which pins the refusal and zero writes.
  *
  * ⛔ THERE IS NO `regenerate` PROP, AND IT IS NOT AN OVERSIGHT. PVE's own description: "All users
  *   of the previous secret will lose access after this operation." A prop for it would revoke a
  *   live credential during a deploy whose plan said `update`, and hand back a replacement this
- *   provider is obliged to throw away — breakage with no recovery. Rotation belongs to the mount
- *   that owns the lease, or to a human who is watching.
+ *   provider is obliged to throw away — breakage with no recovery.
  *
  * ⚠️ THERE IS A SECOND WRITER TO THESE OBJECTS AND IT IS THE ONE THIS PROVIDER RUNS ON. OpenBao's
- *   `proxmox-c1` engine mints PVE tokens under `hf-read@pve` and `hf-provision@pve` — read from
- *   `<estate>/platform/secrets/vault/plugin-proxmox/proxmox/`: `privsep=0` (client.go), `expire` set
- *   to the lease deadline, and an id the plugin CHOOSES,
- *   `hf-<role>-<actor>-<entity6>-<stamp>-<nonce>` (tokenname.go). Revocation and WAL rollback look
- *   up that one exact id (wal.go); neither sweeps a prefix. So the two systems cannot collide on
- *   one object by accident — but they share the USER: `hf-read@pve` held three live leases when
- *   this was written, and `Proxmox.User` deleting that account takes every one of them with it.
- *   ⛔ DO NOT DECLARE A TOKEN UNDER A MINT USER. `expire` is what makes that dangerous rather than
- *     untidy: point this resource at a lease token with the wrong expire and a 300-second
- *     credential becomes a permanent one — and on `hf-provision@pve` that credential carries
- *     `Permissions.Modify` at `/`. docs/privileges.md records what those 27 privileges buy.
+ *   `proxmox-c1` engine mints PVE tokens under `hf-read@pve` and `hf-provision@pve` with an id it
+ *   CHOOSES (`hf-<role>-<actor>-<entity6>-<stamp>-<nonce>`), so the two systems cannot collide on
+ *   one object by accident — but they share the USER, and `Proxmox.User` deleting that account
+ *   takes every one of its tokens with it. ⛔ DO NOT DECLARE A TOKEN UNDER A MINT USER: `expire`
+ *   is what makes that dangerous — a 300-second lease token becomes a permanent one.
  *
  * ⚠️ PRIVILEGES, AND THE READ LANE CANNOT DO IT. MEASURED: all four methods on this path check
  *   `['or', ['userid-param','self'], ['userid-group', ['User.Modify']]]` — with no `Sys.Audit`
- *   alternative, unlike `GET /access/users/{userid}`, which has one. And
- *   `pvesh get /access/permissions --userid hf-read@pve --path /access/groups` answers the seven
- *   PVEAuditor audit privileges and no `User.Modify`, while `hf-provision@pve` has it. So the
- *   3600s read lease reaches at most its OWN account's tokens and is refused for every other
- *   userid — which `read` in resource.ts folds into "absent", so the plan says create and the POST
- *   then fails with "Token already exists". Hence `readRole: 'provision'` below, for the same
- *   reason storage.ts, sdn-zone.ts and sdn-vnet.ts set it, at the same cost: every plan mints a
- *   300s non-renewable provision lease just to read.
+ *   alternative — so the 3600s read lease reaches at most its OWN account's tokens and is refused
+ *   for every other userid. `readRole: 'provision'` below, for the same reason storage.ts,
+ *   sdn-zone.ts and sdn-vnet.ts set it, at the same cost: every plan mints a 300s non-renewable
+ *   provision lease just to read.
+ *
+ * ★ MIGRATED OFF `client.ts`'s generic `pve()`/`pveHandlers`/`pveOperations` ONTO
+ *   `@distilled.cloud/proxmox`'s typed `access.getAccessUserToken`/`putAccessUserToken`/
+ *   `deleteAccessUserToken` (2026-09-24, decision 43's proxmox walk-down, the last access-family
+ *   resource). There is no `createAccessUserToken` call anywhere in this file — the create branch
+ *   was already provably unreachable before the migration (`reconcile` dies on an absent read
+ *   before any create path runs), so nothing calls distilled's POST-shaped `updateAccessUserToken`
+ *   operation either; see api-token-form.ts for why the generator gave it that name.
  */
 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 { apiTokenSpec } from './api-token-form.ts';
-import { type PveRequirements, type WithTarget, pveHandlers, pveOperations } from './resource.ts';
+import { API_TOKEN_UPDATE, attributesOf, matches, shape } from './api-token-form.ts';
+import { guardWrite } from './distilled-guard.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 ApiTokenProps extends WithTarget {
   /**
@@ -78,57 +75,36 @@ export interface ApiTokenProps extends WithTarget {
   /**
    * The token's own name, unique within the account. Identity.
    *
-   * ⚠️ PVE HAS NO RENAME, AND HERE THAT COSTS MORE THAN IT DOES FOR A USER. Editing this prop (or
-   *   `userid`) points `path` at a DIFFERENT token, which reads as absent and is then created —
-   *   leaving the old token LIVE, with its secret still working, invisible to the plan, while the
-   *   new one is the unusable kind described at the top. Rename by declaring a delete and a
-   *   create, the way user.ts says for an account.
-   *   ⛔ `diff` IS NOT OVERRIDDEN TO SAY `replace` THE WAY acl.ts DOES, AND THE DIFFERENCE IS THE
-   *     OBJECT. There, replace removes a grant that can be rebuilt from its own tuple; here it
-   *     would DELETE a live token — destroying an irrecoverable secret, and everything using it —
-   *     to tidy up a name. Leaving the old token standing is the lesser harm, and saying so here
-   *     is what keeps it from looking like an omission.
-   * ⚠️ PATTERN `[A-Za-z][A-Za-z0-9.\-_]+`: a letter first, two characters minimum. The schema
-   *   declares no maxLength; the OpenBao plugin assumes a conservative 64 rather than finding the
-   *   real limit in production, and so should anything else.
+   * ⚠️ PVE HAS NO RENAME. Editing this prop (or `userid`) points `path` at a DIFFERENT token,
+   *   which reads as absent and is then created — leaving the old token LIVE, invisible to the
+   *   plan, while the new one is the unusable kind described at the top. Rename by declaring a
+   *   delete and a create.
+   *   ⛔ `diff` IS NOT OVERRIDDEN TO SAY `replace` THE WAY acl.ts DOES: there, replace removes a
+   *     grant that can be rebuilt from its own tuple; here it would DELETE a live token —
+   *     destroying an irrecoverable secret — to tidy up a name. Leaving the old token standing is
+   *     the lesser harm.
+   * ⚠️ PATTERN `[A-Za-z][A-Za-z0-9.\-_]+`: a letter first, two characters minimum.
    */
   tokenid: string;
-  /**
-   * Free text in `pveum user token list` and the UI. Empty is how it is cleared — see `shape`.
-   * ⚠️ ANY CHARACTER IS SAFE HERE, MEASURED, and it was worth checking: `user.cfg` is a
-   *   colon-delimited line, so a comment holding a colon or a newline is the obvious place for a
-   *   round-trip to lose a character and diff forever. PVE escapes it — `encode_text` turns
-   *   `a:b\nc%d` into `a%3Ab%0Ac%25d` and `decode_text` gives it back byte for byte.
-   */
+  /** Free text in `pveum user token list` and the UI. Empty is how it is cleared — see `shape`. */
   comment?: string;
   /**
    * Seconds since the epoch, or 0 for "never expires".
    *
    * ⛔ REQUIRED, AND THE SCHEMA WILL TELL YOU IT NEED NOT BE. It declares the default "same as
    *   user", and the code never implements it: `generate_token` writes `expire` only when the
-   *   parameter is defined, `user.cfg` stores a token as `token:<id>:<expire>:<privsep>:<comment>:`
-   *   with no absent state, and the parser does `$expire = 0 if !$expire` (AccessControl.pm:1624).
-   *   MEASURED end to end: every token on this cluster that was created without an expire reads
-   *   back `"expire":0`. So "same as user" is documentation of an intention, not behaviour.
-   * ⛔ WHICH IS WHY IT IS NOT OPTIONAL-DEFAULTING-TO-0. That spelling reads identically and is far
-   *   worse: an omitted `expire` would then quietly WRITE 0 over a live deadline, turning an
-   *   expiring credential into a permanent one, and the plan would call it an update. Requiring
-   *   the field makes "this token never expires" a sentence somebody had to type.
+   *   parameter is defined, and the parser does `$expire = 0 if !$expire`. Required, so "this
+   *   token never expires" is a sentence somebody had to type, rather than an omission that would
+   *   quietly WRITE 0 over a live deadline.
    */
   expire: number;
   /**
    * True keeps the token's privileges separate from its owner's — it gets NOTHING until an ACL
    *   names `fullTokenid`. False gives it the owner's privileges entire.
    *
-   * ⛔ REQUIRED FOR THE SAME REASON AS `expire`, AND THE BLAST RADIUS IS LARGER. PVE's API default
-   *   is 1, every token on this cluster is 0 (measured), and `user.cfg` materialises it either way
-   *   — `$privsep = $privsep ? 1 : 0` (AccessControl.pm:1622), so there is no unset state to
-   *   preserve. Were this optional, adopting a live token without mentioning `privsep` would plan
-   *   an update to 1 and STRIP a working credential of every privilege it has, silently: PVE
-   *   returns 401/403 to the service, nothing errors here, and `iac@pve!apply` simply stops
-   *   working. Required, so adopting a token is a sentence that states what it is.
-   * ⚠️ AND `false` IS NOT A SHRUG. It is a token with its owner's whole privilege set; under a
-   *   provisioning account that is the account's full authority with a separate secret.
+   * ⛔ REQUIRED FOR THE SAME REASON AS `expire`, AND THE BLAST RADIUS IS LARGER. Were this
+   *   optional, adopting a live token without mentioning `privsep` would plan an update to 1 and
+   *   STRIP a working credential of every privilege it has, silently.
    */
   privsep: boolean;
 }
@@ -143,9 +119,7 @@ export interface ApiTokenAttributes {
   privsep: boolean;
   /**
    * ⛔ THERE IS NO `value` FIELD HERE AND THERE NEVER MAY BE. Adding one would write a working PVE
-   *   credential, in clear, into the state Postgres and into every nightly dump of it — the exact
-   *   leak metric-server.ts types its `token` as `never` to prevent. The read cannot supply one
-   *   anyway; only create and regenerate can, and both of those responses are dropped.
+   *   credential, in clear, into the state Postgres and into every nightly dump of it.
    */
 }
 
@@ -159,69 +133,109 @@ export interface ProxmoxApiToken extends Resource<
 
 /**
  * ★ `retain` BY DEFAULT, AND THIS IS THE PLAINEST CASE FOR IT IN THE PACKAGE. A token's contents
- *   are one irreplaceable secret: delete it and the value is gone, a replacement is a DIFFERENT
- *   value, and every holder loses access the instant `cfs_write_file` returns — with no error
- *   raised anywhere near them. The live cluster's tokens are `metrics@pve!exporter` (the PVE
- *   exporter feeding VictoriaMetrics), `agent@pve!executor`, `iac@pve!apply`, `iac@pve!ro`,
- *   `app@pve!app` and `mint@pve!engine` — the last being the parent credential the
- *   OpenBao mount itself authenticates with, so orphaning that one would stop every plan in this
- *   package, this resource included. `delete` is FULLY IMPLEMENTED (DELETE is a real method on
- *   this path, measured) and runs the moment a caller opts in with `.pipe(RemovalPolicy.destroy())`.
- *   See the ★ in resource.ts, which explains the convention once.
+ *   are one irreplaceable secret: delete it and the value is gone, and every holder loses access
+ *   the instant `cfs_write_file` returns — with no error raised anywhere near them. `delete` is
+ *   FULLY IMPLEMENTED and runs the moment a caller opts in with `.pipe(RemovalPolicy.destroy())`.
  */
 export const ProxmoxApiToken = Resource<ProxmoxApiToken>('Proxmox.ApiToken', {
   defaultRemovalPolicy: 'retain',
 });
 
-const ops = pveOperations(apiTokenSpec);
+/** ⛔ `readRole: 'provision'` — see the header's ⚠️ on privileges. */
+const readToken = (props: ApiTokenProps) =>
+  readOrUnreadable(runPve(props.target, 'provision', false, access.getAccessUserToken(props))).pipe(
+    Effect.map((live) => (live === UNREADABLE ? UNREADABLE : attributesOf(live, props))),
+    Effect.orElseSucceed(() => undefined),
+  );
 
-/**
- * ⛔ THIS FAMILY ADOPTS AND MANAGES TOKENS; IT REFUSES TO MINT ONE, AND THAT IS A DECISION RATHER
- *   THAN A GAP. The secret exists ONLY in the create response — MEASURED from the schema: `POST`
- *   returns `["full-tokenid","info","value"]`, where `value` is "API token value used for
- *   authentication", while `GET` returns `["comment","expire","privsep"]` and never the secret.
- *   It may not become an attribute, because Alchemy writes attributes to its state store
- *   UNENCRYPTED into a Postgres that is dumped nightly.
- *
- *   So a token created here would be A LIVE CREDENTIAL ON THE CLUSTER THAT NOBODY HOLDS: valid,
- *   privileged, unusable, and indistinguishable from one somebody meant to keep. Regenerating does
- *   not rescue it — a `regenerate` PUT returns the new value down the same discarded path. So
- *   `reconcile` refuses by name and says what to do instead.
- *
- * ★ EVERYTHING ELSE STILL WORKS, AND IT IS THE HALF WORTH HAVING. Adopting an existing token and
- *   converging its `comment`, `expire` and `privsep` are real operations: C1 carries SEVEN tokens
- *   with `expire=0` and `privsep=0` made by clicks nobody recorded. Declaring those freezes the
- *   set, and an eighth appearing shows up as drift.
- *
- * ⚠️ IF DECLARATIVE MINTING IS EVER WANTED, the missing piece is a secret SINK — write the value
- *   straight into an OpenBao kv path and return only its address. That is a different resource
- *   with a different contract; it must not be bolted onto this one.
- */
-const handlers = {
-  ...pveHandlers(apiTokenSpec),
-  reconcile: Effect.fn(function* ({ news }: { news: ApiTokenProps }) {
-    const live = yield* ops.read(news);
-    if (live === undefined) {
-      return yield* Effect.die(
-        new Error(
-          `${news.userid}!${news.tokenid}: this resource does not create API tokens. PVE returns ` +
-            'the secret only in the create response and it cannot be stored, so a token made here ' +
-            'would be a live credential nobody holds. Create it with `pveum user token add` and ' +
-            'capture the value, or mint a short-lived one from the OpenBao proxmox mount ' +
-            '(`bao read proxmox-c1/creds/<role>`) -- then declare it here to manage it.',
-        ),
-      );
-    }
-    return yield* ops.reconcile(news);
-  }),
-};
+/** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */
+const dropUnreadable = (live: ApiTokenAttributes | Unreadable | undefined) =>
+  live === UNREADABLE ? undefined : live;
 
 /**
- * ⛔ `list` IS EMPTY, AND FOR THIS FAMILY THAT MATTERS MORE THAN THE GENERIC ARGUMENT IN
- *   resource.ts. A token index handed to Alchemy would offer up `mint@pve!engine` and every
- *   live OpenBao lease for adoption — and adoption is what makes a later plan willing to delete.
- *   The mount's leases in particular appear and vanish on their own; anything that adopted one
- *   would report drift against a credential that was never its to hold.
+ * ⛔ THIS FAMILY ADOPTS AND MANAGES TOKENS; IT REFUSES TO MINT ONE — see the header. `reconcile`
+ *   refuses by name before any write when the read finds nothing, so the create path this
+ *   family's spec would otherwise need never runs, and no `createAccessUserToken`-shaped call
+ *   exists in this file at all.
  */
 export const ProxmoxApiTokenProvider = () =>
-  Provider.effect(ProxmoxApiToken, Effect.succeed(ProxmoxApiToken.Provider.of(handlers)));
+  Provider.effect(
+    ProxmoxApiToken,
+    Effect.succeed(
+      ProxmoxApiToken.Provider.of({
+        /**
+         * ⛔ `list` IS EMPTY, AND FOR THIS FAMILY THAT MATTERS MORE THAN THE GENERIC ARGUMENT.
+         *   A token index handed to Alchemy would offer up `mint@pve!engine` and every live
+         *   OpenBao lease for adoption — and adoption is what makes a later plan willing to delete.
+         */
+        list: () => Effect.succeed([]),
+        read: Effect.fn(function* ({ olds }) {
+          return dropUnreadable(yield* readToken(olds));
+        }),
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          yield* guardWrite(API_TOKEN_UPDATE, shape(news), false);
+          if (output === undefined) return undefined;
+          const live = yield* readToken(news);
+          // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and force
+          //   `update` on a token that was plainly there — see unreadable-read.ts.
+          if (live === UNREADABLE) {
+            yield* unreadableWarning('Proxmox.ApiToken', `${news.userid}!${news.tokenid}`);
+            return { action: 'noop' } as const;
+          }
+          // ⚠️ NO GUARDED-CREATE BRANCH HERE, UNLIKE EVERY OTHER FAMILY IN THIS SUB-AREA. There
+          //   is nothing to guard a create form for — `reconcile` refuses instead, and `diff`
+          //   answering `update` for an absent token is what routes a real deploy into that
+          //   refusal rather than silently reporting `noop` over a token that never landed.
+          return live !== undefined && 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
+          //   read that fed `diff`'s `update` verdict, so `UNREADABLE` here is a narrow race —
+          //   but UNLIKE group/role/user, the message below assumes genuine absence and would
+          //   misname a transient credential refusal as "this resource does not create tokens".
+          //   Rare (the SAME role must mint twice, once for diff/once for reconcile, and only the
+          //   second is denied) and not silently wrong — the operator still sees a die() and goes
+          //   looking — but named here rather than left for the next reader to assume away.
+          const before = dropUnreadable(yield* readToken(news));
+          if (before === undefined) {
+            return yield* Effect.die(
+              new Error(
+                `${news.userid}!${news.tokenid}: this resource does not create API tokens. PVE ` +
+                  'returns the secret only in the create response and it cannot be stored, so a ' +
+                  'token made here would be a live credential nobody holds. Create it with ' +
+                  '`pveum user token add` and capture the value, or mint a short-lived one from ' +
+                  'the OpenBao proxmox mount (`bao read proxmox-c1/creds/<role>`) -- then declare ' +
+                  'it here to manage it.',
+              ),
+            );
+          }
+          yield* guardWrite(API_TOKEN_UPDATE, shape(news), false);
+          if (!matches(before, news)) {
+            yield* runPve(news.target, 'provision', true, access.putAccessUserToken(shape(news)));
+          }
+          const after = dropUnreadable(yield* readToken(news));
+          if (after === undefined) {
+            return yield* Effect.die(
+              new Error(
+                `${news.userid}!${news.tokenid}: the write returned no error but the token 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.deleteAccessUserToken({ tokenid: olds.tokenid, userid: olds.userid }),
+          );
+        }),
+      }),
+    ),
+  );

package/src/proxmox/client.ts

@@ -15,14 +15,9 @@
 import * as Effect from 'effect/Effect';
 import * as HttpClient from 'effect/unstable/http/HttpClient';
 import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
-import {
-  type ApiTarget,
-  type PveCredential,
-  type PveRole,
-  type PveTarget,
-  authorization,
-} from './credentials.ts';
+import type { ApiTarget, PveCredential, PveRole, PveTarget } from './credentials.ts';
 import { leased } from './lease-cache.ts';
+import { authorization } from './mint.ts';
 import { executeOnCluster } from './members.ts';
 
 export class PveError extends Error {

package/src/proxmox/constraints-forms.test.ts

@@ -16,7 +16,6 @@
  *   there).
  */
 import { describe, expect, test } from 'bun:test';
-import { shape as apiTokenForm } from './api-token-form.ts';
 import { NETWORK_APPLY_ENDPOINT, SDN_APPLY_ENDPOINT } from './apply-endpoints.ts';
 import { constraintsFor, formViolations } from './constraint-guard.ts';
 import type { PveTarget } from './credentials.ts';
@@ -30,32 +29,13 @@ const TARGET: PveTarget = { members: ['pve.test:8006'], mount: 'pve-test', schem
 const onCreate = (key: string, form: Record<string, string | readonly string[]>) =>
   formViolations(key, form, true);
 
-describe('Proxmox.ApiToken plans clean against POST /access/users/{userid}/token/{tokenid}', () => {
-  /** ⚠️ `expire: 0` is "never", and PVE's `minimum: 0` accepts it — the bound the table carries. */
-  test('the estate-shaped token declaration has no violations', () => {
-    expect(
-      onCreate(
-        'pve:POST /access/users/{userid}/token/{tokenid}',
-        apiTokenForm({
-          comment: 'Declared by Alchemy',
-          expire: 0,
-          privsep: false,
-          target: TARGET,
-          tokenid: 'apply',
-          userid: 'iac@pve',
-        }),
-      ),
-    ).toEqual([]);
-  });
-
-  /** ⛔ `{userid}` AND `{tokenid}` ARE PATH SEGMENTS. A table that kept them would refuse every
-   *   create for a "missing" parameter that was never missing (codegen/emit.ts). */
-  test('neither path parameter is in the table', () => {
-    const table = constraintsFor('pve:POST /access/users/{userid}/token/{tokenid}');
-    expect(table['userid']).toBeUndefined();
-    expect(table['tokenid']).toBeUndefined();
-  });
-});
+// ⛔ Proxmox.ApiToken's own create-endpoint check was REMOVED HERE 2026-09-24, not merely
+//   updated: the distilled migration (api-token.ts) confirmed the create path was already
+//   unreachable (reconcile refuses before any POST — see that file's header) and stopped
+//   guarding a create form at all, so `'pve:POST /access/users/{userid}/token/{tokenid}'` is no
+//   longer named anywhere in this package's source. `codegen/constraints.ts` (its own `keysFromSource`)
+//   dropped the table for it on the next regeneration — there is nothing left here to test
+//   against, and keeping this block would fail with "no vendor constraint table" forever.
 
 describe('Proxmox.MetricServer plans clean against POST /cluster/metrics/server/{id}', () => {
   /**