@homeflare/alchemy 0.10.1 → 0.12.0

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

package/src/proxmox/provision-bootstrap.ts

@@ -0,0 +1,135 @@
+/**
+ * `provisionBootstrap` — the provisioning baseline (provision-baseline.ts) as the one-time root
+ * commands for a NEW cluster or node: a POSIX `sh` script, printed, never run from here.
+ *
+ *     bun -e "import { provisionBootstrap } from '@homeflare/alchemy/proxmox';
+ *             process.stdout.write(provisionBootstrap())" | ssh root@<node> sh
+ *
+ * ⛔ WHY IT EXISTS: THE PROVISION LANE CANNOT CREATE ITSELF. Every resource in this package runs as a
+ *   token OpenBao mints for the provision user, and a cluster without that user, its group and its
+ *   grant has nothing to mint for — the plan that would create them cannot authenticate. So root
+ *   makes them once, and the stack adopts and keeps them (provision-declare.ts). This is the only
+ *   hand step, and it is generated from the same baseline the stack declares.
+ * ⛔ NEVER A TOKEN, NEVER A PASSWORD. The users are created with neither: OpenBao mints short-lived
+ *   tokens for them later, and an `@pve` user with no password cannot log in to the UI. Nothing
+ *   secret is in the script, so it can be read, reviewed and pasted.
+ * ★ CHECK, THEN CHANGE — IDEMPOTENT BY CONSTRUCTION. Each object is read first (`pvesh get … json`,
+ *   parsed with Perl's core JSON::PP, which every PVE node has), compared with the baseline, and
+ *   written only when it differs, naming what it does. A second run prints `ok` for everything and
+ *   writes nothing. It also CONVERGES: a role with other privileges is set to exactly the baseline,
+ *   as the stack's `Proxmox.Role` would set it (role.ts: a declaration replaces the set).
+ * ★ ONE NODE PER CLUSTER. Users, groups, roles and ACLs live in `/etc/pve/user.cfg`, which pmxcfs
+ *   shares across the cluster: a node joining a cluster that has the baseline needs nothing, and a
+ *   run there is all `ok`. A new standalone node or a new cluster is where it creates.
+ * ⚠️ NAMES ARE NOT QUOTED INTO SAFETY, THEY ARE REFUSED INTO IT: provision-baseline.ts admits only
+ *   characters that need no quoting in `sh` or in a Perl `q{}`.
+ */
+import {
+  type ProvisionBaseline,
+  type ProvisionNames,
+  provisionBaseline,
+} from './provision-baseline.ts';
+
+const HEADER = `#!/bin/sh
+# Provisioning baseline bootstrap, generated by @homeflare/alchemy (provisionBootstrap).
+# Run ONCE, as root, on one node of a NEW cluster (or a new standalone node). Every step reads
+# first and writes only what differs; a second run changes nothing. No token, no password.
+set -eu
+[ "$(id -u)" -eq 0 ] || { echo 'bootstrap: run this as root' >&2; exit 1; }
+command -v pvesh >/dev/null 2>&1 || { echo 'bootstrap: no pvesh; run this on a PVE node' >&2; exit 1; }
+perl -MJSON::PP -e 1 || { echo 'bootstrap: perl cannot load JSON::PP' >&2; exit 1; }
+
+# get <api-path> <perl>: print <perl> evaluated over the object at <api-path> (as $d).
+# Fails, silently, when the object does not exist: the empty input is not JSON.
+get() {
+  pvesh get "$1" --output-format json 2>/dev/null | perl -MJSON::PP -0777 -ne "\\$d = decode_json(\\$_); $2" 2>/dev/null
+}
+`;
+
+/** A Perl string literal with no interpolation — `@pve` in a double-quoted one is an array. */
+const perlText = (text: string) => `q{${text}}`;
+
+/** The user fields `Proxmox.User` compares, as one line both sides can produce. */
+const USER_STATE =
+  'my $g = $d->{groups} // []; $g = [split /,/, $g] unless ref $g; ' +
+  'print join(";", "groups=" . join(",", sort @$g), "enable=" . (($d->{enable} // 1) ? 1 : 0), ' +
+  '"expire=" . ($d->{expire} // 0), "email=" . ($d->{email} // ""), ' +
+  '"firstname=" . ($d->{firstname} // ""), "lastname=" . ($d->{lastname} // ""), ' +
+  '"comment=" . ($d->{comment} // ""))';
+
+const roleStep = ({ role }: ProvisionBaseline): string => {
+  const privs = [...role.privs].sort().join(',');
+  return `
+# Role ${role.roleid}: exactly the provision privileges, on no path yet.
+want='${privs}'
+if have=$(get /access/roles/${role.roleid} 'print join(",", sort grep { /\\./ } keys %$d)'); then
+  if [ "$have" = "$want" ]; then echo 'role ${role.roleid}: ok'
+  else echo 'role ${role.roleid}: setting the baseline privileges'; pveum role modify ${role.roleid} --privs "$want"; fi
+else
+  echo 'role ${role.roleid}: adding'; pveum role add ${role.roleid} --privs "$want"
+fi
+`;
+};
+
+const groupStep = ({ group }: ProvisionBaseline): string => `
+# Group ${group.groupid}: OpenBao may mint only for its members.
+if have=$(get /access/groups/${group.groupid} 'print $d->{comment} // ""'); then
+  if [ "$have" = '${group.comment}' ]; then echo 'group ${group.groupid}: ok'
+  else echo 'group ${group.groupid}: setting the comment'; pveum group modify ${group.groupid} --comment '${group.comment}'; fi
+else
+  echo 'group ${group.groupid}: adding'; pveum group add ${group.groupid} --comment '${group.comment}'
+fi
+`;
+
+const userStep = (user: ProvisionBaseline['users'][number]): string => {
+  const groups = [...user.groups].sort().join(',');
+  const want = `groups=${groups};enable=1;expire=0;email=;firstname=;lastname=;comment=${user.comment}`;
+  const fields = `--groups ${groups} --comment '${user.comment}'`;
+  return `
+# User ${user.userid} (the ${user.lane} lane): in ${groups}, enabled, no password.
+if have=$(get /access/users/${user.userid} '${USER_STATE}'); then
+  if [ "$have" = '${want}' ]; then echo 'user ${user.userid}: ok'
+  else echo 'user ${user.userid}: setting groups, comment and account fields'
+    pveum user modify ${user.userid} ${fields} --enable 1 --expire 0 --email '' --firstname '' --lastname ''; fi
+else
+  echo 'user ${user.userid}: adding'; pveum user add ${user.userid} ${fields}
+fi
+`;
+};
+
+const grantStep = (grant: ProvisionBaseline['grants'][number]): string => {
+  const match =
+    `print scalar grep { $_->{path} eq "/" && $_->{type} eq "user" && ` +
+    `$_->{ugid} eq ${perlText(grant.userid)} && $_->{roleid} eq ${perlText(grant.roleid)} && ` +
+    `($_->{propagate} // 1) } @$d`;
+  return `
+# Grant: ${grant.userid} holds ${grant.roleid} on /, propagated (the ${grant.lane} lane).
+if [ "$(get /access/acl '${match}')" = 1 ]; then echo 'grant ${grant.userid} ${grant.roleid} /: ok'
+else echo 'grant ${grant.userid} ${grant.roleid} /: adding'; pveum acl modify / --users ${grant.userid} --roles ${grant.roleid} --propagate 1; fi
+`;
+};
+
+/** A role the baseline binds but does not own — the read lane's — must already exist. */
+const requireRole = (roleid: string): string => `
+get /access/roles/${roleid} 'print 1' >/dev/null || { echo 'bootstrap: role ${roleid} does not exist; create it, or name another readRole' >&2; exit 1; }
+`;
+
+/**
+ * The script for `names` (defaults: `PROVISION_DEFAULTS`). Pure: it reads nothing and runs nothing.
+ * Throws, like `provisionBaseline`, on a name the baseline refuses.
+ */
+export const provisionBootstrap = (names: ProvisionNames = {}): string => {
+  const baseline = provisionBaseline(names);
+  const borrowed = baseline.grants
+    .map((grant) => grant.roleid)
+    .filter((roleid) => roleid !== baseline.role.roleid);
+  return [
+    HEADER,
+    ...[...new Set(borrowed)].map(requireRole),
+    roleStep(baseline),
+    groupStep(baseline),
+    ...baseline.users.map(userStep),
+    ...baseline.grants.map(grantStep),
+    `\necho 'provision baseline: done. Next: point the OpenBao proxmox mount at these users, then deploy the stack that declares this baseline with --adopt.'\n`,
+  ].join('');
+};

package/src/proxmox/provision-cli-fake.ts

@@ -0,0 +1,217 @@
+/**
+ * A fake `pvesh` / `pveum` / `id` for the bootstrap tests: the generated script runs for real, under
+ * `sh`, with real Perl parsing the JSON, against an access config held in one JSON file — so what is
+ * tested is the script a person pipes to a node, not a model of it.
+ *
+ * ⛔ TEST-ONLY. No provider imports this file. Run as a program (`import.meta.main`), it IS the fake
+ *   CLI; imported, it is the harness that writes the wrappers and runs a script against them.
+ * ★ IT REFUSES WHAT PVE REFUSES WHERE ORDER MATTERS: adding an object that exists, modifying one
+ *   that does not, a user in a group that does not exist, a grant of a role that does not exist.
+ *   A script that runs its steps in the wrong order fails here as it would on a node.
+ * ★ READS ANSWER IN THE ITEM SHAPES access/*.ts DOCUMENT: a role is a privilege map, a user's
+ *   groups an array, empty strings omitted. `apiView` is also what the engine test's fake PVE
+ *   serves, so the bootstrap's result and the declaration are compared on one picture.
+ */
+import { appendFileSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export type CliUser = {
+  comment: string;
+  email: string;
+  enable: number;
+  expire: number;
+  firstname: string;
+  lastname: string;
+  groups: string[];
+};
+export type CliGrant = {
+  path: string;
+  type: string;
+  ugid: string;
+  roleid: string;
+  propagate: number;
+};
+export type CliState = {
+  roles: Record<string, string[]>;
+  groups: Record<string, { comment: string }>;
+  users: Record<string, CliUser>;
+  acl: CliGrant[];
+};
+
+/** A cluster as PVE installs it: the built-in auditor role, and nothing of the baseline. */
+export const freshCluster = (): CliState => ({
+  acl: [],
+  groups: {},
+  roles: {
+    PVEAuditor: [
+      'Datastore.Audit',
+      'Mapping.Audit',
+      'Pool.Audit',
+      'SDN.Audit',
+      'Sys.Audit',
+      'VM.Audit',
+    ],
+  },
+  users: {},
+});
+
+const text = (key: string, value: string) => (value === '' ? {} : { [key]: value });
+
+/** Every item GET the scripts and the providers make, keyed `access/…` without a leading slash. */
+export const apiView = (state: CliState): Record<string, unknown> => {
+  const view: Record<string, unknown> = { 'access/acl': state.acl };
+  for (const [id, privs] of Object.entries(state.roles)) {
+    view[`access/roles/${id}`] = Object.fromEntries(privs.map((priv) => [priv, 1]));
+  }
+  for (const [id, group] of Object.entries(state.groups)) {
+    const members = Object.keys(state.users).filter((u) => state.users[u]?.groups.includes(id));
+    view[`access/groups/${id}`] = { ...text('comment', group.comment), members };
+  }
+  for (const [id, user] of Object.entries(state.users)) {
+    view[`access/users/${id}`] = {
+      ...text('comment', user.comment),
+      ...text('email', user.email),
+      ...text('firstname', user.firstname),
+      ...text('lastname', user.lastname),
+      enable: user.enable,
+      expire: user.expire,
+      groups: user.groups,
+      tokens: {},
+    };
+  }
+  return view;
+};
+
+const flags = (args: string[]) => {
+  const out: Record<string, string> = {};
+  for (let i = 0; i < args.length; i += 2)
+    out[(args[i] ?? '').replace(/^--/, '')] = args[i + 1] ?? '';
+  return out;
+};
+
+/** One pveum call against `state`; returns the refusal PVE would print, or undefined. */
+const pveum = (state: CliState, [kind, verb, id = '', ...rest]: string[]): string | undefined => {
+  const f = flags(rest);
+  const list = (csv: string | undefined) => (csv ?? '').split(',').filter((s) => s !== '');
+  if (kind === 'role') {
+    if ((verb === 'add') === id in state.roles) return `role '${id}': wrong state for ${verb}`;
+    state.roles[id] = list(f['privs']);
+  } else if (kind === 'group') {
+    if ((verb === 'add') === id in state.groups) return `group '${id}': wrong state for ${verb}`;
+    state.groups[id] = { comment: f['comment'] ?? '' };
+  } else if (kind === 'user') {
+    const had = state.users[id];
+    if ((verb === 'add') === (had !== undefined)) return `user '${id}': wrong state for ${verb}`;
+    const groups = f['groups'] === undefined ? (had?.groups ?? []) : list(f['groups']);
+    const missing = groups.find((g) => !(g in state.groups));
+    if (missing !== undefined) return `no such group '${missing}'`;
+    const base: CliUser = had ?? {
+      comment: '',
+      email: '',
+      enable: 1,
+      expire: 0,
+      firstname: '',
+      lastname: '',
+      groups: [],
+    };
+    state.users[id] = {
+      comment: f['comment'] ?? base.comment,
+      email: f['email'] ?? base.email,
+      enable: f['enable'] === undefined ? base.enable : Number(f['enable']),
+      expire: f['expire'] === undefined ? base.expire : Number(f['expire']),
+      firstname: f['firstname'] ?? base.firstname,
+      groups,
+      lastname: f['lastname'] ?? base.lastname,
+    };
+  } else if (kind === 'acl' && verb === 'modify') {
+    const roleid = f['roles'] ?? '';
+    if (!(roleid in state.roles)) return `role '${roleid}' does not exist`;
+    const grant = {
+      path: id,
+      propagate: Number(f['propagate'] ?? 1),
+      roleid,
+      type: 'user',
+      ugid: f['users'] ?? '',
+    };
+    state.acl = state.acl.filter(
+      (g) => !(g.path === id && g.ugid === grant.ugid && g.roleid === roleid),
+    );
+    state.acl.push(grant);
+  } else return `unknown pveum call: ${kind} ${verb}`;
+  return undefined;
+};
+
+/** The fake CLI's entry point: `<tool> <args…>`, with FAKE_PVE_STATE and FAKE_PVE_LOG set. */
+const runCli = ([tool, ...args]: string[]): number => {
+  if (tool === 'id') {
+    process.stdout.write('0\n');
+    return 0;
+  }
+  const file = process.env['FAKE_PVE_STATE'] ?? '';
+  const state = JSON.parse(readFileSync(file, 'utf8')) as CliState;
+  if (tool === 'pvesh') {
+    const found = apiView(state)[(args[1] ?? '').replace(/^\//, '')];
+    if (found === undefined) {
+      process.stderr.write(`no such object ${args[1] ?? ''}\n`);
+      return 2;
+    }
+    process.stdout.write(JSON.stringify(found));
+    return 0;
+  }
+  appendFileSync(process.env['FAKE_PVE_LOG'] ?? '', `pveum ${args.join(' ')}\n`);
+  const refused = pveum(state, args);
+  if (refused !== undefined) {
+    process.stderr.write(`${refused}\n`);
+    return 255;
+  }
+  writeFileSync(file, JSON.stringify(state));
+  return 0;
+};
+
+if (import.meta.main) process.exit(runCli(process.argv.slice(2)));
+
+export type ScriptRun = {
+  code: number;
+  stdout: string;
+  stderr: string;
+  writes: string[];
+  state: CliState;
+};
+
+/** Run `script` under `sh` against `state`, with the fakes first on PATH. */
+export const runScript = async (script: string, state: CliState): Promise<ScriptRun> => {
+  const dir = mkdtempSync(join(tmpdir(), 'hf-bootstrap-'));
+  for (const tool of ['id', 'pvesh', 'pveum']) {
+    const wrapper = `#!/bin/sh\nexec '${process.execPath}' '${import.meta.path}' ${tool} "$@"\n`;
+    writeFileSync(join(dir, tool), wrapper, { mode: 0o755 });
+  }
+  const stateFile = join(dir, 'state.json');
+  const log = join(dir, 'pveum.log');
+  writeFileSync(stateFile, JSON.stringify(state));
+  writeFileSync(log, '');
+  try {
+    const child = Bun.spawn(['sh', '-s'], {
+      env: {
+        FAKE_PVE_LOG: log,
+        FAKE_PVE_STATE: stateFile,
+        PATH: `${dir}:${process.env['PATH'] ?? ''}`,
+      },
+      stderr: 'pipe',
+      stdin: new TextEncoder().encode(script),
+      stdout: 'pipe',
+    });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ]);
+    const writes = readFileSync(log, 'utf8')
+      .split('\n')
+      .filter((line) => line !== '');
+    const after = JSON.parse(readFileSync(stateFile, 'utf8')) as CliState;
+    return { code, state: after, stderr, stdout, writes };
+  } finally {
+    rmSync(dir, { force: true, recursive: true });
+  }
+};

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

@@ -0,0 +1,111 @@
+/**
+ * `declareProvisionBaseline` through Alchemy's real plan and apply, over a fake PVE serving what the
+ * generated bootstrap made (provision-cli-fake.ts `apiView`) — the proof that the two halves are
+ * one baseline: after the bootstrap, the declaration adopts every object and writes NOTHING.
+ * Also pinned: a hand edit shows up as a diff; every resource retains; `adopt` is piped only when
+ * asked; and a refused name fails before anything is declared.
+ */
+import { describe, expect, test } from 'bun:test';
+import { push } from 'alchemy';
+import { Stack } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { ProxmoxAclProvider } from './acl.ts';
+import { FAKE_TARGET, fakePve, withoutBao } from './fake-pve.ts';
+import { ProxmoxGroupProvider } from './group.ts';
+import { type CliState, apiView, freshCluster, runScript } from './provision-cli-fake.ts';
+import { provisionBootstrap } from './provision-bootstrap.ts';
+import { type DeclareProvisionOptions, declareProvisionBaseline } from './provision-declare.ts';
+import { ProxmoxRoleProvider } from './role.ts';
+import { ProxmoxUserProvider } from './user.ts';
+
+const ALL = [
+  'pve-role',
+  'pve-mint-group',
+  'pve-provision-user',
+  'pve-read-user',
+  'pve-provision-grant',
+  'pve-read-grant',
+];
+
+const bootstrapped = async (): Promise<CliState> => {
+  const run = await runScript(provisionBootstrap(), freshCluster());
+  if (run.code !== 0) throw new Error(`bootstrap failed: ${run.stderr}`);
+  return run.state;
+};
+
+const engineOn = (state: CliState) => {
+  const live = apiView(state);
+  const fake = fakePve((call) => (call.method === 'GET' ? live[call.path] : 'UPID:fake'));
+  const providers = Layer.mergeAll(
+    ProxmoxAclProvider(),
+    ProxmoxGroupProvider(),
+    ProxmoxRoleProvider(),
+    ProxmoxUserProvider(),
+  );
+  return { engine: engineOver(providers.pipe(Layer.provideMerge(fake.layer))), fake };
+};
+
+describe('after the bootstrap, the declaration is a clean adoption', () => {
+  test('every object is adopted, and nothing is written', async () => {
+    const { engine, fake } = engineOn(await bootstrapped());
+    await withoutBao(async () => {
+      const report = await engine.verify(declareProvisionBaseline('pve', FAKE_TARGET));
+      expect(report.rows.map((row) => [row.fqn, row.diff, row.ok])).toEqual(
+        [...ALL].sort().map((fqn) => [fqn, 'noop', true]),
+      );
+      const deployed = await engine.deploy(declareProvisionBaseline('pve', FAKE_TARGET));
+      expect(deployed).toEqual(Object.fromEntries(ALL.map((fqn) => [fqn, 'adopted'])));
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('a privilege added by hand is a diff on the role, and nothing else', async () => {
+    const state = await bootstrapped();
+    state.roles['HfProvisioner']?.push('VM.Console');
+    const { engine } = engineOn(state);
+    await withoutBao(async () => {
+      const report = await engine.verify(declareProvisionBaseline('pve', FAKE_TARGET));
+      const changed = report.rows.filter((row) => row.diff !== 'noop');
+      expect(changed).toEqual([expect.objectContaining({ changed: ['privs'], fqn: 'pve-role' })]);
+    });
+  });
+});
+
+/** Register the declaration under a bare Stack and read back what Alchemy recorded per resource. */
+const registered = async (options?: DeclareProvisionOptions) => {
+  const spec = { actions: {}, bindings: {}, name: 'test', resources: {}, stage: 'test' };
+  await Effect.runPromise(
+    push('lab', declareProvisionBaseline('pve', FAKE_TARGET, {}, options)).pipe(
+      Effect.provideService(Stack, spec as never),
+    ) as Effect.Effect<unknown>,
+  );
+  return spec.resources as Record<string, { Adopt?: boolean; RemovalPolicy?: string }>;
+};
+
+describe('what the helper registers', () => {
+  test('every resource retains, whatever the family default', async () => {
+    const resources = await registered();
+    expect(Object.keys(resources).sort()).toEqual(ALL.map((id) => `lab/${id}`).sort());
+    for (const each of Object.values(resources)) expect(each.RemovalPolicy).toBe('retain');
+  });
+
+  test.each([
+    [{ adopt: true }, true],
+    [{ adopt: false }, false],
+    [{}, undefined],
+  ] as const)('adopt %o is recorded as %p on every resource', async (options, expected) => {
+    for (const each of Object.values(await registered(options))) expect(each.Adopt).toBe(expected);
+  });
+
+  test('a refused name fails before anything is declared', async () => {
+    const spec = { actions: {}, bindings: {}, name: 'test', resources: {}, stage: 'test' };
+    const declared = declareProvisionBaseline('pve', FAKE_TARGET, { role: 'bad role' });
+    const exit = await Effect.runPromiseExit(
+      declared.pipe(Effect.provideService(Stack, spec as never)) as Effect.Effect<unknown, unknown>,
+    );
+    expect(String(exit)).toContain('role `bad role` is not a PVE role id');
+    expect(spec.resources).toEqual({});
+  });
+});