@homeflare/alchemy 0.31.0 → 0.31.2

package/src/proxmox/user.ts

@@ -2,7 +2,7 @@
  * `Proxmox.User` — a PVE account. The identity every other resource in this package borrows.
  *
  * ★ THIS IS THE ONE OBJECT THAT CAN CUT THE BRANCH IT SITS ON. The user the credential mount vends
- *   tokens for, and the group whose members are allowed to mint, are what `src/credentials.ts`
+ *   tokens for, and the group whose members are allowed to mint, are what `credentials.ts`
  *   ultimately asks OpenBao for. A cluster rebuilt without them cannot plan ANY resource here —
  *   including the plan that would recreate them, which needs a credential to run. So this resource
  *   is drift repair for an account that already exists (comment, email, enable, expire, groups),
@@ -18,39 +18,59 @@
  *
  * ⚠️ `groups` COMES BACK AS AN ARRAY AND GOES OUT AS A COMMA STRING, and the asymmetry is the whole
  *   trap. GET answers `["a","b"]`, POST/PUT want `a,b`, and PVE returns the list in ITS order, not
- *   the declared one. Compared naively, `matches` reads ['b','a'] against 'a,b' and every plan for
- *   the rest of time says "1 to update". Both sides are normalised to a sorted, deduplicated set
- *   below. Joining is a safe comparison precisely because a group id cannot contain a comma — the
- *   wire format is comma-separated, so PVE refuses one.
+ *   the declared one. Both sides are normalised to a sorted, deduplicated set — see user-wire.ts.
  *
  * ⚠️ `tokens` IS NESTED AND IS NOT SETTABLE THROUGH THIS ENDPOINT. The read hands back a map of the
  *   account's API tokens; `PUT /access/users/{userid}` has no parameter for them, because they are
- *   their own objects under `.../token/{tokenid}`. So they are reported as an attribute — a plan
- *   can then say what a delete would take with it — and kept OUT of `matches`, exactly like
- *   `pool.members`. Reported, never declared.
+ *   their own objects under `.../token/{tokenid}` (api-token.ts). So they are reported as an
+ *   attribute and kept OUT of `matches`, exactly like `pool.members`. Reported, never declared.
  *
  * ⚠️ RECONCILE NEEDS PRIVILEGES A GUEST-ONLY ROLE DOES NOT HOLD, so they are stated rather than met
- *   as a 403 in the middle of a deploy (pool.ts records how that went the last time).
- *   `PROVISION_PRIVILEGES` (provision-baseline.ts) carries every one of them:
+ *   as a 403 in the middle of a deploy. `PROVISION_PRIVILEGES` (provision-baseline.ts) carries:
  *     · `Realm.AllocateUser` on `/access/realm/<realm>` — create and delete.
  *     · `User.Modify` on `/access/groups`, and on `/access/groups/<group>` for EVERY group named in
  *       `groups` — create, update and delete. PVE checks the groups you are granting, not just the
- *       user, so a role wide enough to edit the account can still be refused for one group in the
- *       list.
+ *       user, so a role wide enough to edit the account can still be refused for one group.
  *     · `Sys.Audit` (or `User.Modify`) for the read, which the `read` role's auditor already has.
- *   `Permissions.Modify` is NOT on this list: that governs ACL entries, which are a different PVE
- *   object and would be a different resource here.
  *
- * ⚠️ A MISSING USER IS A 500, NOT A 404 — "no such user ('x@pve')" — and the factory turns any
- *   failed read into "absent". A 403 therefore also reads as absent, and the honest error arrives
- *   one step later, from the create: "Permission check failed (/access/groups, User.Modify)". That
- *   string is the one to grep for when a plan insists on creating an account that plainly exists.
+ * ⚠️ A MISSING USER IS A 500, NOT A 404 — MEASURED against the live cluster, "no such user
+ *   ('x@pve')". distilled turns that into an `InternalServerError`, with no distinct "not found"
+ *   tag to catch. `user-wire.ts`'s `readUser` (used by `read`/`reconcile`, where the create
+ *   workflow needs "absent" from exactly this failure) still folds it; `readUserOrFail` (used by
+ *   `diff` below) does not — see that function's own header for why folding it there was the
+ *   cries-wolf bug all over again, just for a genuine PVE quirk instead of a permission denial.
+ *
+ * ⚠️ THE WIRE URL FOR THIS FAMILY CHANGED, THOUGH NOTHING A CALLER SEES DID. MEASURED
+ *   (user.test.ts): distilled's `{userid}` label substitution percent-encodes it —
+ *   `iac@pve` -> `.../access/users/iac%40pve` — where `client.ts`'s plain string concatenation
+ *   sent the `@` literally. A real PVE (any HTTP server) decodes both the same way, so this is
+ *   not a behaviour change a stack observes; a fake in a test has to decode it, `client.ts`'s
+ *   own fixtures never had to.
+ *
+ * ★ MIGRATED OFF `client.ts`'s generic `pve()`/`pveHandlers` ONTO `@distilled.cloud/proxmox`'s
+ *   typed `access.getAccessUser`/`createAccessUser`/`putAccessUser`/`deleteAccessUser`
+ *   (2026-09-24, decision 43's proxmox walk-down, access sub-area). `distilled-pve.ts`'s `runPve`
+ *   replaces `pve()` as in acl.ts and group.ts; the cries-wolf fix is wired the same way.
  */
 import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
+import * as access from '@distilled.cloud/proxmox/access';
 import * as Effect from 'effect/Effect';
-import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
-import { bool } from './values.ts';
+import { guardWrite } from './distilled-guard.ts';
+import type { PveRequirements, WithTarget } from './resource-spec.ts';
+import { runPve } from './distilled-pve.ts';
+import { UNREADABLE, unreadableWarning } from './unreadable-read.ts';
+import {
+  USER_CREATE,
+  USER_UPDATE,
+  createForm,
+  dropUnreadable,
+  matches,
+  readUser,
+  readUserOrFail,
+  updateForm,
+} from './user-wire.ts';
 
 export interface UserProps extends WithTarget {
   /**
@@ -103,115 +123,100 @@ export interface ProxmoxUser extends Resource<
 
 export const ProxmoxUser = Resource<ProxmoxUser>('Proxmox.User');
 
-const str = (value: unknown) => (typeof value === 'string' ? value : '');
-
-/**
- * ⚠️ MORE FORGIVING THAN `lxc.ts`'s `num`, ON PURPOSE. PVE's JSON is generated from a Perl schema
- *   and an integer field can arrive as `0` or as `"0"` depending on the release and the endpoint. A
- *   strict `typeof === 'number'` would silently fall back to 0 for the string form, so a declared
- *   `expire` would never equal the live one and the plan would report an update it cannot settle.
- */
-const int = (value: unknown) => {
-  const parsed = typeof value === 'number' ? value : Number(value ?? 0);
-  return Number.isFinite(parsed) ? parsed : 0;
-};
-
-/**
- * An array (what the read returns), a comma string (what older releases and the write side use), or
- * nothing — in; a sorted, deduplicated list out. Both sides of `matches` go through this, which is
- * the only reason the diff ever settles.
- */
-const groupSet = (value: unknown): string[] => {
-  const raw: unknown[] = Array.isArray(value)
-    ? value
-    : typeof value === 'string'
-      ? value.split(',')
-      : [];
-  const names = raw.map((group) => str(group).trim()).filter((group) => group !== '');
-  return [...new Set(names)].sort();
-};
-
-/**
- * ⚠️ THE SHAPE DEPENDS ON WHICH ENDPOINT YOU ASKED. Reading ONE user gives an object keyed by token
- *   name; the collection read gives an array of records. This provider only ever reads the single
- *   user path, so the map is what arrives — anything else is reported as "no tokens" rather than
- *   guessed at, because a wrong guess here would show up as a phantom revocation in a plan.
- */
-const tokenNames = (value: unknown): string[] =>
-  typeof value === 'object' && value !== null && !Array.isArray(value)
-    ? Object.keys(value).sort()
-    : [];
-
-/** Everything mutable, in the form PVE wants. Create adds `userid`; update sends exactly this. */
-const shape = (props: UserProps) => ({
-  comment: props.comment ?? '',
-  email: props.email ?? '',
-  enable: props.enable === false ? '0' : '1',
-  expire: String(props.expire ?? 0),
-  firstname: props.firstname ?? '',
-  /**
-   * ⚠️ ALWAYS SENT, EVEN EMPTY. Omitting `groups` on a PUT leaves the existing memberships in
-   *   place, so a group removed from the declaration would never actually be removed — and
-   *   `matches` would keep reporting an update that the update cannot fix. Same for `email` and
-   *   `comment`: the empty string is how PVE is told to clear a field.
-   * ⚠️ AND `append` IS DELIBERATELY NOT SET. Its default (0) REPLACES the list; setting it to 1
-   *   would turn every reconcile into an add-only merge, which is the same non-settling diff.
-   */
-  groups: groupSet(props.groups).join(','),
-  lastname: props.lastname ?? '',
-});
-
-const handlers = pveHandlers<UserProps, UserAttributes>({
-  attributes: (live, props) => ({
-    comment: str(live['comment']),
-    email: str(live['email']),
-    /**
-     * ⚠️ ABSENT MEANS ENABLED. PVE's schema defaults `enable` to 1 and does not always write the
-     *   key back for an enabled account. Reading absence as `false` would report an update on every
-     *   plan and then DISABLE the account on the deploy that "fixed" it.
-     */
-    enable: bool(live['enable'], true),
-    expire: int(live['expire']),
-    firstname: str(live['firstname']),
-    groups: groupSet(live['groups']),
-    lastname: str(live['lastname']),
-    tokens: tokenNames(live['tokens']),
-    /** ⚠️ FROM PROPS: `GET /access/users/{userid}` does not echo the userid back in its data. */
-    userid: props.userid,
-  }),
-  collection: () => 'access/users',
-  createForm: (props) => ({ ...shape(props), userid: props.userid }),
-  /**
-   * ⚠️ `tokens` IS NOT COMPARED, and neither is anything create-only. What is compared is exactly
-   *   what a PUT can put back; a field that PVE reports but will not accept is drift nobody can
-   *   fix, and diffing it would report an update on every plan forever.
-   */
-  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
-  endpoint: { create: 'pve:POST /access/users', update: 'pve:PUT /access/users/{userid}' },
-  matches: (attributes, props) =>
-    attributes.comment === (props.comment ?? '') &&
-    attributes.email === (props.email ?? '') &&
-    attributes.enable === (props.enable !== false) &&
-    attributes.expire === (props.expire ?? 0) &&
-    attributes.firstname === (props.firstname ?? '') &&
-    attributes.lastname === (props.lastname ?? '') &&
-    attributes.groups.join(',') === groupSet(props.groups).join(','),
-  path: (props) => `access/users/${props.userid}`,
-  updateForm: shape,
-});
-
-/**
-* ⛔ EMPTY, AND MORE POINTEDLY SO HERE THAN ANYWHERE ELSE. `GET /access/users` answers with
-*   every account on the cluster: `root@pam`, every human who logs in, every service
-*   identity someone made years ago. Handing that list to Alchemy would invite it to adopt
-*   — and therefore one day DELETE — people. Adoption is an explicit act.
- 
- *
-* ⛔ DELETING A USER TAKES ITS API TOKENS AND ITS ACL ENTRIES WITH IT, in one call and
-*   without a confirmation. For the identity a credential mount vends from, that revokes
-*   every outstanding lease at once and every plan in this package stops working — this one
-*   included. PVE refuses only for `root@pam`; for everyone else it simply obeys.
- 
- */
 export const ProxmoxUserProvider = () =>
-  Provider.effect(ProxmoxUser, Effect.succeed(ProxmoxUser.Provider.of(handlers)));
+  Provider.effect(
+    ProxmoxUser,
+    Effect.succeed(
+      ProxmoxUser.Provider.of({
+        /**
+         * ⛔ EMPTY, AND MORE POINTEDLY SO HERE THAN ANYWHERE ELSE. `GET /access/users` answers
+         *   with every account on the cluster: `root@pam`, every human who logs in, every service
+         *   identity someone made years ago. Adoption is an explicit act.
+         */
+        list: () => Effect.succeed([]),
+        // ⚠️ FOLDS ONLY WHEN `output` IS `undefined` — MEASURED 2026-09-24, an adversarial review
+        //   of this very fix caught the gap. The engine calls this ONE hook from FOUR places
+        //   (alchemy/src/{Plan,Apply,Drift}.ts), and only `output` tells them apart: Plan.ts's
+        //   cold-start adoption probe and interrupted-create recovery, and Apply.ts's
+        //   delete-recovery, all pass `output: undefined` — nothing is confirmed to exist yet, so
+        //   `readUser`'s fold is still needed there or a brand-new account could never be adopted
+        //   or created. `Drift.ts` (`alchemy drift`/`sync`/`deploy --detect-drift`) is different:
+        //   it calls this on an ALREADY-CONFIRMED row (`output: old.attr`, defined), exactly
+        //   `diff`'s own situation below — a transient failure folded to `undefined` there is
+        //   reported as `{action: 'missing'}` with NO error at all, the cries-wolf bug again, one
+        //   command over. `readUserOrFail` on that branch propagates it instead.
+        read: Effect.fn(function* ({ olds, output }) {
+          return dropUnreadable(
+            yield* output === undefined ? readUser(olds) : readUserOrFail(olds),
+          );
+        }),
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          yield* guardWrite(USER_CREATE, createForm(news), output === undefined);
+          yield* guardWrite(USER_UPDATE, updateForm(news), false);
+          if (output === undefined) return undefined;
+          // ⚠️ `readUserOrFail`, NOT `readUser` — see that function's own header (user-wire.ts).
+          //   A genuine failure here propagates and fails the whole plan loudly instead of
+          //   folding to "absent" and forcing a false update, the cries-wolf class of bug.
+          const live = yield* readUserOrFail(news);
+          // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and force
+          //   `update` on an account that was plainly there — see unreadable-read.ts.
+          if (live === UNREADABLE) {
+            yield* unreadableWarning('Proxmox.User', news.userid);
+            return { action: 'noop' } as const;
+          }
+          if (live === undefined) {
+            yield* guardWrite(USER_CREATE, createForm(news), true);
+            return { action: 'update' } as const;
+          }
+          return matches(live, news)
+            ? ({ action: 'noop' } as const)
+            : ({ action: 'update' } as const);
+        }),
+        reconcile: Effect.fn(function* ({ news }) {
+          // ⚠️ `dropUnreadable`: reconcile only runs once `provision` already minted for the
+          //   write below, so `UNREADABLE` here is a narrow race, not the routine case `diff`
+          //   handles — and a wrongful create in that race fails loudly ("already exists")
+          //   rather than silently duplicating, group.ts's reconcile has the same note.
+          const before = dropUnreadable(yield* readUser(news));
+          yield* guardWrite(USER_CREATE, createForm(news), before === undefined);
+          yield* guardWrite(USER_UPDATE, updateForm(news), false);
+          if (before === undefined) {
+            yield* runPve(
+              news.target,
+              'provision',
+              true,
+              access.createAccessUser(createForm(news)),
+            );
+          } else if (!matches(before, news)) {
+            yield* runPve(news.target, 'provision', true, access.putAccessUser(updateForm(news)));
+          }
+          const after = dropUnreadable(yield* readUser(news));
+          if (after === undefined) {
+            return yield* Effect.die(
+              new Error(
+                `access/users/${news.userid}: the write returned no error but the account 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;
+        }),
+        /**
+         * ⛔ DELETING A USER TAKES ITS API TOKENS AND ITS ACL ENTRIES WITH IT, in one call and
+         *   without a confirmation. For the identity a credential mount vends from, that revokes
+         *   every outstanding lease at once and every plan in this package stops working — this
+         *   one included. PVE refuses only for `root@pam`; for everyone else it simply obeys.
+         */
+        delete: Effect.fn(function* ({ olds }) {
+          yield* runPve(
+            olds.target,
+            'provision',
+            true,
+            access.deleteAccessUser({ userid: olds.userid }),
+          );
+        }),
+      }),
+    ),
+  );

package/src/verify/fake-engine.ts

@@ -125,11 +125,24 @@ export type Body = Effect.Effect<unknown, unknown, unknown>;
 type Compiled = { readonly name: string; readonly stage: string; readonly services: never };
 type PlanView = { readonly resources: Readonly<Record<string, { readonly action: string }>> };
 
+/** One row of `Alchemy.Drift.detect`'s dry-run report — the fields `drift` below asserts on. */
+export type DriftRow = { readonly action: string };
+
 export interface FakeEngine {
   /** Plan and apply `body`, as `alchemy deploy --adopt` would; resolves to the planned actions. */
   readonly deploy: (body: Body) => Promise<Record<string, string>>;
   /** Verify `body` against what the earlier deploys recorded. */
   readonly verify: (body: Body, options?: VerifyOptions) => Promise<AdoptReport>;
+  /**
+   * `alchemy drift`'s own dry-run (`Alchemy.Drift.detect`) over whatever `deploy` already
+   * persisted — `body` is used only to resolve the stack's name/stage/providers, exactly as
+   * `verify` does; drift itself reads the state store, not `body`'s declarations. ⚠️ A DIFFERENT
+   * ENGINE PATH FROM `verify`'s `--all` READ, proxmox/read-failure-propagation.test.ts's own ⛔:
+   * `Drift.ts` calls a provider's `read` with `output` set to the PERSISTED attributes, and folds
+   * a `read` that resolves `undefined` into `{action: 'missing'}` with no error — silent, unlike
+   * `verify.ts`'s `readWithState`, which already wraps that same call in `Effect.catchCause`.
+   */
+  readonly drift: (body: Body) => Promise<Record<string, DriftRow>>;
   /**
    * Every state row the store holds, as JSON — what a Postgres store would persist. ★ For tests
    * that must prove a value NEVER reaches state (proxmox/pbs-notification-target-state.test.ts).
@@ -152,6 +165,10 @@ export const engineOver = <ROut, E, RIn>(layer: Layer.Layer<ROut, E, RIn>): Fake
   ) => Effect.Effect<Compiled, unknown, never>;
   const plan = Alchemy.Plan.make as unknown as (c: Compiled) => Effect.Effect<PlanView, unknown>;
   const apply = Alchemy.apply as unknown as (planned: PlanView) => Effect.Effect<unknown, unknown>;
+  const detectDrift = Alchemy.Drift.detect as unknown as (stack: {
+    name: string;
+    stage: string;
+  }) => Effect.Effect<{ resources: Record<string, DriftRow> }, unknown>;
 
   const run = <A>(body: Body, next: (compiled: Compiled) => Effect.Effect<A, unknown, unknown>) =>
     Effect.runPromise(
@@ -182,6 +199,12 @@ export const engineOver = <ROut, E, RIn>(layer: Layer.Layer<ROut, E, RIn>): Fake
       run(body, (compiled) =>
         verifySession({ context: compiled.services, stack: compiled as never }, options),
       ),
+    drift: (body) =>
+      run(body, (compiled) =>
+        detectDrift({ name: compiled.name, stage: compiled.stage }).pipe(
+          Effect.map((detected) => detected.resources),
+        ),
+      ),
   };
 };