@homeflare/alchemy 0.11.0 → 0.13.0

package/src/proxmox/pbs-notifications-stack.test.ts

@@ -0,0 +1,94 @@
+/**
+ * A target and the matcher that routes to it, declared together the way docs/pbs-notifications.md
+ * shows — with the matcher naming the target through its OUTPUT, not a string.
+ *
+ * ★ WHY THE OUTPUT: PBS refuses to create a matcher naming a target that does not exist, and
+ *   refuses to delete a target a matcher still names. `targets: [hook.name]` gives Alchemy the
+ *   dependency edge that orders both; a bare `'alertmanager'` string gives it nothing, and the
+ *   order is then whatever the engine picks. This pins that the Output resolves inside the list
+ *   (the matcher's `isResolved` guard) and that the target is written first.
+ */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { alertmanagerAlertBody } from './alertmanager-body.ts';
+import type { PbsTarget } from './credentials.ts';
+import { fakeNotify } from './fake-pbs-notify.ts';
+import { withoutBao } from './fake-pve.ts';
+import {
+  PbsNotificationMatcher,
+  PbsNotificationMatcherProvider,
+} from './pbs-notification-matcher.ts';
+import { PbsNotificationTarget, PbsNotificationTargetProvider } from './pbs-notification-target.ts';
+
+const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };
+
+const stack = Effect.gen(function* () {
+  const hook = yield* PbsNotificationTarget('alertmanager', {
+    body: alertmanagerAlertBody(),
+    header: { 'Content-Type': 'application/json' },
+    method: 'post',
+    name: 'alertmanager',
+    target: PBS,
+    type: 'webhook',
+    url: 'https://alertmanager.example.com/api/v2/alerts',
+  });
+  yield* PbsNotificationMatcher('page-on-failure', {
+    'match-field': ['exact:type=gc,prune,sync,verify'],
+    'match-severity': ['error'],
+    name: 'page-on-failure',
+    target: PBS,
+    targets: [hook.name],
+  });
+});
+
+test('the matcher resolves the target by Output and is written after it', async () => {
+  const fake = fakeNotify();
+  const providers = Layer.mergeAll(
+    PbsNotificationTargetProvider(),
+    PbsNotificationMatcherProvider(),
+  );
+  await withoutBao(async () => {
+    const engine = engineOver(providers.pipe(Layer.provideMerge(fake.layer)));
+    await engine.deploy(stack);
+    const again = await engine.verify(stack, { all: true });
+    expect(again.rows.map((row) => row.diff)).toEqual(['noop', 'noop']);
+  });
+  expect(fake.writes()).toEqual([
+    'POST config/notifications/endpoints/webhook',
+    'POST config/notifications/matchers',
+  ]);
+  expect(fake.objects.get('config/notifications/matchers/page-on-failure')?.['target']).toEqual([
+    'alertmanager',
+  ]);
+});
+
+test('a new type under the same name replaces delete-first — names are unique across families', async () => {
+  const fake = fakeNotify();
+  const declare = (type: 'sendmail' | 'webhook') =>
+    type === 'webhook'
+      ? PbsNotificationTarget('pager', {
+          method: 'post',
+          name: 'pager',
+          target: PBS,
+          type,
+          url: 'https://alertmanager.example.com/api/v2/alerts',
+        })
+      : PbsNotificationTarget('pager', {
+          mailto: ['ops@example.com'],
+          name: 'pager',
+          target: PBS,
+          type,
+        });
+  await withoutBao(async () => {
+    const engine = engineOver(PbsNotificationTargetProvider().pipe(Layer.provideMerge(fake.layer)));
+    await engine.deploy(declare('webhook'));
+    await engine.deploy(declare('sendmail'));
+  });
+  expect(fake.writes()).toEqual([
+    'POST config/notifications/endpoints/webhook',
+    'DELETE config/notifications/endpoints/webhook/pager',
+    'POST config/notifications/endpoints/sendmail',
+  ]);
+});

package/src/proxmox/pbs-prune-job.ts

@@ -37,10 +37,10 @@
  *   answers 401 "authentication failure", which reads as a bad credential rather than as a
  *   malformed header — the same trap credentials.ts already records for PVE's colon form.
  *   ⛔ AND THERE IS NO MOUNT TO MINT FROM. `mint()` runs `bao read <mount>/creds/<role>`; no
- *     OpenBao mount vends PBS tokens — `proxmox-tb4` and `proxmox-ops` vend PVE ones. The
+ *     OpenBao mount vends PBS tokens — `proxmox-c1` and `proxmox-c2` vend PVE ones. The
  *     `kv/infra/proxmox` shelf holds a READ-ONLY `Audit` token for PBS, and a read-only token
  *     cannot create a prune job. I could not confirm that shelf's contents: this machine's
- *     claude-code approle answers 403 on `sys/mounts` AND on `kv/metadata/infra/proxmox`
+ *     agent approle answers 403 on `sys/mounts` AND on `kv/metadata/infra/proxmox`
  *     (MEASURED). What is needed is a dynamic PBS mount vending a `provision` role with
  *     `Datastore.Modify` — say that, rather than reaching for the stored auditor token.
  *

package/src/proxmox/pbs-sync-job.ts

@@ -12,14 +12,14 @@
  *
  * ⛔ THE CREDENTIAL IS A PBS TOKEN AND IT DOES NOT EXIST YET; NO MOUNT NAME IS INVENTED IN THIS
  *   FILE. PBS wants `user@realm!tokenname` plus a UUID secret, issued by PBS — a PVE token is not
- *   one, whatever it is spelled like. MEASURED from this machine on 2026-09-13: the `claude-code`
+ *   one, whatever it is spelled like. MEASURED from this machine on 2026-09-13: the agent's
  *   approle cannot enumerate mounts (`bao secrets list` -> 403) and
  *   `bao token capabilities kv/infra/proxmox/pbs` -> `deny`, so I could not confirm from here what
  *   does or does not exist. What credentials.ts records is that every PBS token on the kv shelf is
- *   READ-ONLY (`Audit`, as `monitoring@pve`) and STATIC — too narrow to create a sync job, and
+ *   READ-ONLY (`Audit`, as `metrics@pve`) and STATIC — too narrow to create a sync job, and
  *   exactly the kind of credential this provider exists to avoid writing with.
  *   ★ SO THE MOUNT IS A `PbsTarget.mount` THE STACK SUPPLIES, and somebody has to build it first:
- *     a dynamic PBS mount with `read` and `provision` roles mirroring `proxmox-tb4`. Until it
+ *     a dynamic PBS mount with `read` and `provision` roles mirroring `proxmox-c1`. Until it
  *     exists this family can be declared and cannot be deployed. `permission denied` means the
  *     grant is missing — say which mount and role you needed; do not fall back to the shelf token.
  *
@@ -83,7 +83,7 @@ export interface SyncJobProps extends WithPbsTarget {
    *   `Pbs.Remote` family is OUT OF SCOPE for this package rather than merely unwritten:
    *   `POST /config/remote` requires `password`, and Alchemy persists props and attributes to its
    *   state store UNENCRYPTED (StateEncoding.ts tags Redacted values rather than encrypting them),
-   *   which here is the `alchemy` Postgres that pg-backup.sh dumps nightly to CT100. A remote's
+   *   which here is the `alchemy` Postgres that a nightly job dumps to a backup guest. A remote's
    *   password in a prop is that password in four places, for months. The only Remote resource that
    *   could exist would refuse `password` the way storage.ts refuses it — as a `never` — and could
    *   therefore never CREATE a remote, which is a resource that cannot do what its name promises.

package/src/proxmox/pbs-verify-job.ts

@@ -11,7 +11,7 @@
  *
  * ⛔ THIS FILE CANNOT AUTHENTICATE UNTIL TWO THINGS OUTSIDE IT CHANGE, AND IT IS SHIPPED SAYING SO
  *   RATHER THAN SHIPPED LOOKING FINISHED. Both are recorded on `PbsTarget` below:
- *     1. `credentials.ts` has no PBS mint. MEASURED 2026-09-13 from this Mac: the `claude-code`
+ *     1. `credentials.ts` has no PBS mint. MEASURED 2026-09-13 from this Mac: the agent's
  *        approle is refused `sys/mounts`, `kv/infra/proxmox` and `proxmox-pbs/creds/read` alike —
  *        403 permission denied on all three — so there is no mount to name and none is invented.
  *     2. `client.ts`'s `authorization()` builds a PVE header, and PBS will not accept it. See the

package/src/proxmox/pool.test.ts

@@ -17,14 +17,14 @@ const target: PoolProps['target'] = {
 
 const props = (over: Partial<PoolProps> = {}): PoolProps => ({
   target,
-  poolid: 'house',
+  poolid: 'lab',
   ...over,
 });
 
 describe('pool forms match generated POST/PUT parameters', () => {
   it('createForm sends exactly poolid and comment', () => {
     const form: PoolsPostParams = poolCreateForm(props({ comment: 'estate' }));
-    assert.deepEqual(form, { poolid: 'house', comment: 'estate' });
+    assert.deepEqual(form, { poolid: 'lab', comment: 'estate' });
     assert.deepEqual(Object.keys(form).sort(), ['comment', 'poolid']);
   });
 

package/src/proxmox/pool.ts

@@ -8,11 +8,11 @@
  *   its own state would have reported noop straight past a hand-edit in the UI.
  *
  * ⚠️ IT 403'd UNTIL THE ROLE WAS WIDENED, AND THE HISTORY IS WORTH KEEPING. `hf-provision@pve`
- *   held `LXCProvisioner` on `/` with no `Pool.Allocate`, so reconcile answered
- *   "Permission check failed (/pool/house, Pool.Allocate)". The credential could not widen itself
+ *   held the provision role on `/` with no `Pool.Allocate`, so reconcile answered
+ *   "Permission check failed (/pool/lab, Pool.Allocate)". The credential could not widen itself
  *   — `PUT /access/roles` is 403 for it too — so the role was extended over SSH with
- *   `pveum role modify LXCProvisioner --privs "<existing>,Pool.Allocate,Pool.Audit"`, preserving
- *   every existing privilege. Each new resource in this package should state the privileges its
+ *   `pveum role modify <role> --privs "<existing>,Pool.Allocate,Pool.Audit"`, preserving every
+ *   existing privilege. `PROVISION_PRIVILEGES` (provision-baseline.ts) carries both now. Each new resource in this package should state the privileges its
  *   reconcile needs, so widening stays a deliberate act rather than a reaction to a 403.
  */
 import { Resource } from 'alchemy';

package/src/proxmox/provision-baseline.test.ts

@@ -0,0 +1,87 @@
+/**
+ * The baseline itself: the one privilege list, the generic defaults, and the names both halves
+ * refuse before either can paste them into a root shell or a declaration.
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+  PROVISION_DEFAULTS,
+  PROVISION_PRIVILEGES,
+  provisionBaseline,
+} from './provision-baseline.ts';
+
+describe('PROVISION_PRIVILEGES', () => {
+  test('is 27 privileges, sorted, unique and frozen', () => {
+    expect(PROVISION_PRIVILEGES).toHaveLength(27);
+    expect([...PROVISION_PRIVILEGES].sort()).toEqual([...PROVISION_PRIVILEGES]);
+    expect(new Set(PROVISION_PRIVILEGES).size).toBe(27);
+    expect(Object.isFrozen(PROVISION_PRIVILEGES)).toBe(true);
+  });
+
+  test('holds what the lane needs to repair its own baseline (role.ts: no lock-out)', () => {
+    for (const needed of [
+      'Sys.Modify', // the role
+      'Realm.AllocateUser', // the users
+      'User.Modify',
+      'Group.Allocate', // the mint group
+      'Permissions.Modify', // the grants, and reading them at all (acl.ts)
+    ]) {
+      expect(PROVISION_PRIVILEGES).toContain(needed);
+    }
+  });
+});
+
+describe('provisionBaseline', () => {
+  test('defaults: one role, one mint group, two lanes bound on /', () => {
+    const baseline = provisionBaseline();
+    expect(baseline.role).toEqual({ privs: PROVISION_PRIVILEGES, roleid: 'HfProvisioner' });
+    expect(baseline.group).toEqual({ comment: PROVISION_DEFAULTS.comment, groupid: 'hf-mint' });
+    expect(baseline.users.map((u) => [u.lane, u.userid, u.groups])).toEqual([
+      ['provision', 'hf-provision@pve', ['hf-mint']],
+      ['read', 'hf-read@pve', ['hf-mint']],
+    ]);
+    expect(baseline.grants).toEqual([
+      { lane: 'provision', roleid: 'HfProvisioner', userid: 'hf-provision@pve' },
+      { lane: 'read', roleid: 'PVEAuditor', userid: 'hf-read@pve' },
+    ]);
+  });
+
+  test('a site passes its own names; an explicit undefined is the default', () => {
+    const baseline = provisionBaseline({
+      mintGroup: 'mint',
+      provisionUser: 'provisioner@pve',
+      readRole: 'Auditor',
+      readUser: 'auditor@pve',
+      role: undefined,
+    });
+    expect(baseline.role.roleid).toBe('HfProvisioner');
+    expect(baseline.grants.map((g) => `${g.userid} ${g.roleid}`)).toEqual([
+      'provisioner@pve HfProvisioner',
+      'auditor@pve Auditor',
+    ]);
+    expect(baseline.users.every((u) => u.groups.join() === 'mint')).toBe(true);
+  });
+
+  test('readUser null is a baseline with no read lane', () => {
+    const baseline = provisionBaseline({ readUser: null });
+    expect(baseline.users.map((u) => u.lane)).toEqual(['provision']);
+    expect(baseline.grants.map((g) => g.lane)).toEqual(['provision']);
+  });
+
+  test('refuses, all at once, every name that would need quoting or is not PVE-shaped', () => {
+    const attempt = () =>
+      provisionBaseline({
+        comment: "it's",
+        mintGroup: 'a b',
+        provisionUser: 'no-realm',
+        readRole: 'x;rm',
+        readUser: 'q{}@pve',
+        role: '$(id)',
+      });
+    expect(attempt).toThrow(/role `\$\(id\)`.*mintGroup `a b`.*readRole `x;rm`/);
+    expect(attempt).toThrow(/provisionUser `no-realm`.*readUser `q\{\}@pve`.*comment/);
+  });
+
+  test('refuses one user for both lanes', () => {
+    expect(() => provisionBaseline({ readUser: 'hf-provision@pve' })).toThrow(/one user/);
+  });
+});

package/src/proxmox/provision-baseline.ts

@@ -0,0 +1,162 @@
+/**
+ * The provisioning baseline: the access every PVE cluster and node needs before a stack built on
+ * this package can manage it — one role, the users OpenBao mints tokens for, the group that fences
+ * the mint, and the grants that bind them. ONE description, read by both halves:
+ *   · provision-declare.ts turns it into `Proxmox.Role`/`Group`/`User`/`Acl` resources, so a stack
+ *     adopts the baseline and keeps it (drift is a plan, not a 403 weeks later);
+ *   · provision-bootstrap.ts turns it into the one-time root commands for a NEW cluster or node.
+ * The two cannot drift apart because neither holds a name or a privilege of its own.
+ *
+ * ⛔ THE PROVISION LANE CANNOT CREATE ITSELF. Every write here runs as a token OpenBao mints for the
+ *   provision user, and minting needs that user to exist, in the mint group, bound to this role.
+ *   So a new cluster is bootstrapped ONCE by root@pam with the generated commands, and the stack
+ *   then adopts what they made (docs/provision-baseline.md).
+ *
+ * ★ ONE PRIVILEGE LIST FOR EVERY FAMILY, NOT A ROLE PER RESOURCE. The list is what the families'
+ *   reconciles need, unioned — the set a hand-kept provision role reached one 403 at a time, each
+ *   step recorded where it was hit (pool.ts, sdn-vnet.ts, ha-rule.ts). It includes what the lane needs
+ *   to manage THIS baseline (`Sys.Modify` for the role, `Realm.AllocateUser`/`User.Modify` for the
+ *   users, `Group.Allocate`, `Permissions.Modify` for the grants), so declaring it can never narrow
+ *   the lane out of its own repair (role.ts: "A ROLE CAN LOCK ITS OWN PROVIDER OUT").
+ * ⚠️ NOT EVERY FAMILY: root@pam-only writes (device passthrough, bind mounts — lxc-judge.ts) and
+ *   privileges a family names as still missing (`VM.Replicate`, replication-job.ts) are outside it.
+ */
+
+/** The provision role's privileges, sorted — the exact set, never an addition to a live one. */
+export const PROVISION_PRIVILEGES: readonly string[] = Object.freeze([
+  'Datastore.Allocate',
+  'Datastore.AllocateSpace',
+  'Datastore.Audit',
+  'Group.Allocate',
+  'Mapping.Audit',
+  'Mapping.Modify',
+  'Permissions.Modify',
+  'Pool.Allocate',
+  'Pool.Audit',
+  'Realm.AllocateUser',
+  'SDN.Allocate',
+  'SDN.Audit',
+  'SDN.Use',
+  'Sys.Audit',
+  'Sys.Console',
+  'Sys.Modify',
+  'User.Modify',
+  'VM.Allocate',
+  'VM.Audit',
+  'VM.Backup',
+  'VM.Config.CPU',
+  'VM.Config.Disk',
+  'VM.Config.HWType',
+  'VM.Config.Memory',
+  'VM.Config.Network',
+  'VM.Config.Options',
+  'VM.PowerMgmt',
+]);
+
+/** The names a baseline uses. Every field has a generic default (`PROVISION_DEFAULTS`). */
+export interface ProvisionNames {
+  /** The role holding `PROVISION_PRIVILEGES` on `/`. */
+  readonly role?: string | undefined;
+  /** The user OpenBao's `provision` role mints tokens for, realm-qualified. */
+  readonly provisionUser?: string | undefined;
+  /** The group whose members OpenBao may mint for — the fence around the mint. */
+  readonly mintGroup?: string | undefined;
+  /** The user OpenBao's `read` role mints for, or `null` for a baseline with no read lane. */
+  readonly readUser?: string | null | undefined;
+  /** The role the read user holds on `/`. ⛔ It must already exist: a built-in, or one you declare. */
+  readonly readRole?: string | undefined;
+  /** The comment on the group and both users — how a person on the node learns what they are. */
+  readonly comment?: string | undefined;
+}
+
+/** Every name, resolved: what `PROVISION_DEFAULTS` holds and what a baseline is built from. */
+export type ResolvedProvisionNames = {
+  readonly [K in keyof ProvisionNames]-?: Exclude<ProvisionNames[K], undefined>;
+};
+
+/** ★ Generic, kit-prefixed names: nothing here is any one estate's. */
+export const PROVISION_DEFAULTS: ResolvedProvisionNames = Object.freeze({
+  comment:
+    'provision baseline from @homeflare/alchemy - OpenBao mints short-lived tokens for members',
+  mintGroup: 'hf-mint',
+  provisionUser: 'hf-provision@pve',
+  readRole: 'PVEAuditor',
+  readUser: 'hf-read@pve',
+  role: 'HfProvisioner',
+});
+
+/** Which credential lane a user or a grant belongs to — the OpenBao role that mints for it. */
+export type ProvisionLane = 'provision' | 'read';
+
+/** A baseline, resolved: exactly what the declaration holds and the bootstrap makes. */
+export interface ProvisionBaseline {
+  readonly role: { readonly roleid: string; readonly privs: readonly string[] };
+  readonly group: { readonly groupid: string; readonly comment: string };
+  readonly users: readonly {
+    readonly lane: ProvisionLane;
+    readonly userid: string;
+    readonly comment: string;
+    readonly groups: readonly string[];
+  }[];
+  /** Each binds one user to one role on `/`, with propagate — the only shape the lanes need. */
+  readonly grants: readonly {
+    readonly lane: ProvisionLane;
+    readonly userid: string;
+    readonly roleid: string;
+  }[];
+}
+
+/**
+ * ⛔ NAMES ARE CHECKED HERE, ONCE, FOR BOTH HALVES — and conservatively. The bootstrap pastes them
+ *   into a root shell, so a name that would need quoting is refused rather than quoted: PVE's own
+ *   ids (`pve-roleid`, `pve-groupid`, `pve-userid`) are narrower than what a shell tolerates.
+ */
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const USERID = /^[A-Za-z0-9][A-Za-z0-9._-]*@[A-Za-z][A-Za-z0-9._-]*$/;
+const COMMENT = /^[A-Za-z0-9 ._,()@/+-]*$/;
+
+const problems = (names: ResolvedProvisionNames): string[] => {
+  const found: string[] = [];
+  if (!ID.test(names.role)) found.push(`role \`${names.role}\` is not a PVE role id`);
+  if (!ID.test(names.mintGroup)) found.push(`mintGroup \`${names.mintGroup}\` is not a group id`);
+  if (!ID.test(names.readRole)) found.push(`readRole \`${names.readRole}\` is not a PVE role id`);
+  for (const [field, userid] of [
+    ['provisionUser', names.provisionUser],
+    ['readUser', names.readUser],
+  ] as const) {
+    if (userid !== null && !USERID.test(userid)) {
+      found.push(`${field} \`${userid}\` is not a realm-qualified user id (name@realm)`);
+    }
+  }
+  if (names.readUser === names.provisionUser) found.push('readUser and provisionUser are one user');
+  if (!COMMENT.test(names.comment))
+    found.push('comment holds a character the bootstrap will not quote');
+  return found;
+};
+
+/** Resolve `names` over the defaults and check them. Throws with every problem at once. */
+export const provisionBaseline = (names: ProvisionNames = {}): ProvisionBaseline => {
+  // ⚠️ An explicit `undefined` means "the default", not "blank": spread alone would keep it.
+  const given = Object.entries(names).filter(([, value]) => value !== undefined);
+  const resolved: ResolvedProvisionNames = {
+    ...PROVISION_DEFAULTS,
+    ...Object.fromEntries(given),
+  };
+  const found = problems(resolved);
+  if (found.length > 0) throw new Error(`provision baseline: ${found.join('; ')}`);
+  const lanes: [ProvisionLane, string, string][] = [
+    ['provision', resolved.provisionUser, resolved.role],
+  ];
+  if (resolved.readUser !== null) lanes.push(['read', resolved.readUser, resolved.readRole]);
+  return {
+    grants: lanes.map(([lane, userid, roleid]) => ({ lane, roleid, userid })),
+    group: { comment: resolved.comment, groupid: resolved.mintGroup },
+    role: { privs: PROVISION_PRIVILEGES, roleid: resolved.role },
+    users: lanes.map(([lane, userid]) => ({
+      comment: resolved.comment,
+      groups: [resolved.mintGroup],
+      lane,
+      userid,
+    })),
+  };
+};

package/src/proxmox/provision-bootstrap.test.ts

@@ -0,0 +1,132 @@
+/**
+ * The generated bootstrap, RUN: under `sh`, with real Perl, against provision-cli-fake.ts's
+ * `pvesh`/`pveum`. What these pin: a fresh cluster gets exactly the baseline in an order PVE accepts;
+ * a second run (or a node joining a cluster that has it) writes nothing; drift converges with only
+ * the writes it needs; a read role that is missing stops the script before any write; and the
+ * script never makes a token or sets a password.
+ */
+import { describe, expect, test } from 'bun:test';
+import { type CliState, freshCluster, runScript } from './provision-cli-fake.ts';
+import { PROVISION_DEFAULTS, PROVISION_PRIVILEGES } from './provision-baseline.ts';
+import { provisionBootstrap } from './provision-bootstrap.ts';
+
+const COMMENT = PROVISION_DEFAULTS.comment;
+const lane = (groups: string[]) => ({
+  comment: COMMENT,
+  email: '',
+  enable: 1,
+  expire: 0,
+  firstname: '',
+  groups,
+  lastname: '',
+});
+
+/** What a fresh cluster holds after the default script: the baseline, and nothing else. */
+const BOOTSTRAPPED: CliState = {
+  acl: [
+    { path: '/', propagate: 1, roleid: 'HfProvisioner', type: 'user', ugid: 'hf-provision@pve' },
+    { path: '/', propagate: 1, roleid: 'PVEAuditor', type: 'user', ugid: 'hf-read@pve' },
+  ],
+  groups: { 'hf-mint': { comment: COMMENT } },
+  roles: { ...freshCluster().roles, HfProvisioner: [...PROVISION_PRIVILEGES] },
+  users: { 'hf-provision@pve': lane(['hf-mint']), 'hf-read@pve': lane(['hf-mint']) },
+};
+
+describe('the script as text', () => {
+  const script = provisionBootstrap();
+
+  test('never makes a token or sets a password: its only writes are add/modify of the four', () => {
+    const calls = new Set(script.match(/pveum \w+ \w+/g));
+    expect([...calls].sort()).toEqual([
+      'pveum acl modify',
+      'pveum group add',
+      'pveum group modify',
+      'pveum role add',
+      'pveum role modify',
+      'pveum user add',
+      'pveum user modify',
+    ]);
+    expect(script).not.toMatch(/--password|passwd|user token/);
+    expect(script).toStartWith('#!/bin/sh\n');
+    expect(script).toContain('\nset -eu\n');
+  });
+
+  test('carries the one privilege list, sorted, as the role it adds', () => {
+    expect(script).toContain(`want='${PROVISION_PRIVILEGES.join(',')}'`);
+    expect(script).toContain('pveum role add HfProvisioner --privs "$want"');
+  });
+});
+
+describe('run against a cluster', () => {
+  test('a fresh cluster gets exactly the baseline, role and group before what needs them', async () => {
+    const run = await runScript(provisionBootstrap(), freshCluster());
+    expect(run.stderr).toBe('');
+    expect(run.code).toBe(0);
+    expect(run.writes.map((w) => w.split(' --')[0])).toEqual([
+      'pveum role add HfProvisioner',
+      'pveum group add hf-mint',
+      'pveum user add hf-provision@pve',
+      'pveum user add hf-read@pve',
+      'pveum acl modify /',
+      'pveum acl modify /',
+    ]);
+    expect(run.state).toEqual(BOOTSTRAPPED);
+  });
+
+  test('a second run, or a node joining a cluster that has it, writes nothing', async () => {
+    const run = await runScript(provisionBootstrap(), structuredClone(BOOTSTRAPPED));
+    expect(run.code).toBe(0);
+    expect(run.writes).toEqual([]);
+    expect(run.stdout.split('\n').filter((line) => line.endsWith(': ok'))).toHaveLength(6);
+  });
+
+  test('drift converges with only the writes it needs', async () => {
+    const drifted = structuredClone(BOOTSTRAPPED);
+    drifted.roles['HfProvisioner'] = [...PROVISION_PRIVILEGES.slice(1), 'VM.Console'];
+    drifted.groups['admins'] = { comment: '' };
+    drifted.users['hf-read@pve'] = { ...lane(['admins', 'hf-mint']), email: 'x@example.com' };
+    drifted.acl = drifted.acl.slice(0, 1);
+    const run = await runScript(provisionBootstrap(), drifted);
+    expect(run.code).toBe(0);
+    expect(run.writes.map((w) => w.split(' --')[0])).toEqual([
+      'pveum role modify HfProvisioner',
+      'pveum user modify hf-read@pve',
+      'pveum acl modify /',
+    ]);
+    expect(run.state).toEqual({ ...BOOTSTRAPPED, groups: drifted.groups });
+  });
+
+  test('a read role that does not exist stops the script before any write', async () => {
+    const run = await runScript(provisionBootstrap({ readRole: 'Auditor' }), freshCluster());
+    expect(run.code).toBe(1);
+    expect(run.stderr).toContain('role Auditor does not exist');
+    expect(run.writes).toEqual([]);
+  });
+
+  test('no read lane: one user, one grant, no read role needed', async () => {
+    const run = await runScript(provisionBootstrap({ readUser: null }), {
+      ...freshCluster(),
+      roles: {},
+    });
+    expect(run.code).toBe(0);
+    expect(Object.keys(run.state.users)).toEqual(['hf-provision@pve']);
+    expect(run.state.acl.map((g) => g.ugid)).toEqual(['hf-provision@pve']);
+  });
+
+  test("a site's own names flow through every step", async () => {
+    const names = {
+      mintGroup: 'mint',
+      provisionUser: 'provisioner@pve',
+      readUser: 'auditor@pve',
+      role: 'Provisioner',
+    };
+    const run = await runScript(provisionBootstrap(names), freshCluster());
+    expect(run.code).toBe(0);
+    expect(Object.keys(run.state.roles).sort()).toEqual(['PVEAuditor', 'Provisioner']);
+    expect(run.state.users['provisioner@pve']?.groups).toEqual(['mint']);
+    expect(run.state.acl.map((g) => `${g.ugid} ${g.roleid}`)).toEqual([
+      'provisioner@pve Provisioner',
+      'auditor@pve PVEAuditor',
+    ]);
+  });
+});