@homeflare/alchemy 0.11.0 → 0.13.0

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({});
+  });
+});

package/src/proxmox/provision-declare.ts

@@ -0,0 +1,103 @@
+/**
+ * `declareProvisionBaseline` — the provisioning baseline (provision-baseline.ts) as resources, so a
+ * stack adopts what the bootstrap made and keeps it: the role, the mint group, one user per lane
+ * (its group membership included) and the grant binding each user to its role on `/`.
+ *
+ *     const lane = yield* declareProvisionBaseline('pve', target);
+ *     // names are generic by default; a site passes its own:
+ *     const lane = yield* declareProvisionBaseline('pve', target, { role: 'Provisioner' });
+ *
+ * Provide `ProxmoxRoleProvider()`, `ProxmoxGroupProvider()`, `ProxmoxUserProvider()` and
+ * `ProxmoxAclProvider()` with `FetchHttpClient.layer`.
+ *
+ * ⛔ EVERY RESOURCE HERE RETAINS. This is the branch the whole package sits on (user.ts): dropping
+ *   the call from a stack must drop state, never the role, the users or their grants — deleting the
+ *   provision user revokes every lease at once, the plan that would recreate it included.
+ * ⛔ ADOPTION IS THE OPERATOR'S TO STATE, AS EVERYWHERE IN THE KIT (docs/ownership.md). The first
+ *   deploy after the bootstrap finds all of this live with no state: run it with `--adopt`, or pass
+ *   `{ adopt: true }`, which pipes `adopt(true)` onto each resource. `{ adopt: false }` pins them
+ *   refused under a deploy-wide `--adopt`. Left out, the deploy's own policy decides.
+ *   ⚠️ TODAY THE FOUR FAMILIES STILL READ A LIVE OBJECT WITH NO STATE AS OURS (the `pveHandlers`
+ *     limit in ownership.md), so the flag is not yet what stops a claim. It is stated here so that
+ *     when they follow the rule, a stack built on this helper already says what it means.
+ * ★ THE BOOTSTRAP MAKES EXACTLY THIS, so a clean adoption writes nothing: the same privileges, the
+ *   same comment, the same single group per user (provision-bootstrap.ts reads the same baseline).
+ * ★ PLAIN NAMES, NOT ONE RESOURCE'S OUTPUT IN ANOTHER'S PROPS. An Output would order the creates,
+ *   but Alchemy skips the adoption probe while any prop is one (Plan.ts), so the first deploy after
+ *   the bootstrap would plan `create` for objects that are all there. Order never matters here:
+ *   nothing in this package can run before the bootstrap, and after it everything exists.
+ */
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as Effect from 'effect/Effect';
+import { ProxmoxAcl } from './acl.ts';
+import type { PveTarget } from './credentials.ts';
+import { ProxmoxGroup } from './group.ts';
+import { type ProvisionNames, provisionBaseline } from './provision-baseline.ts';
+import { ProxmoxRole } from './role.ts';
+import { ProxmoxUser } from './user.ts';
+
+export interface DeclareProvisionOptions {
+  /** `true`/`false` pipe `adopt(…)` onto every resource; omitted, the deploy's policy decides. */
+  readonly adopt?: boolean;
+}
+
+/**
+ * The baseline for one cluster. `id` prefixes every logical id (`<id>-role`, `<id>-mint-group`,
+ * `<id>-provision-user`, `<id>-provision-grant`, and the `read` pair), so one stack can declare a
+ * baseline per cluster. `users` and `grants` come back in `baseline.users` / `baseline.grants`
+ * order: provision, then read. Fails, before declaring anything, on a name the baseline refuses.
+ */
+export const declareProvisionBaseline = (
+  id: string,
+  target: PveTarget,
+  names: ProvisionNames = {},
+  options: DeclareProvisionOptions = {},
+) =>
+  Effect.gen(function* () {
+    const baseline = yield* Effect.try({
+      catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
+      try: () => provisionBaseline(names),
+    });
+    const owned = <A, R>(resource: Effect.Effect<A, never, R>) => {
+      const kept = resource.pipe(RemovalPolicy.retain());
+      return options.adopt === undefined ? kept : kept.pipe(adopt(options.adopt));
+    };
+    const role = yield* owned(
+      ProxmoxRole(`${id}-role`, {
+        privs: [...baseline.role.privs],
+        roleid: baseline.role.roleid,
+        target,
+      }),
+    );
+    const group = yield* owned(ProxmoxGroup(`${id}-mint-group`, { ...baseline.group, target }));
+    // ★ `Effect.all` over mapped declarations (sequential), as cloudflare-permission-groups.ts does:
+    //   oxlint's unicorn/no-array-for-each cannot tell `Effect.forEach` from `Array#forEach`.
+    const users = yield* Effect.all(
+      baseline.users.map((user) =>
+        owned(
+          ProxmoxUser(`${id}-${user.lane}-user`, {
+            comment: user.comment,
+            groups: [...user.groups],
+            target,
+            userid: user.userid,
+          }),
+        ),
+      ),
+    );
+    const grants = yield* Effect.all(
+      baseline.grants.map((grant) =>
+        owned(
+          ProxmoxAcl(`${id}-${grant.lane}-grant`, {
+            path: '/',
+            propagate: true,
+            roleid: grant.roleid,
+            target,
+            type: 'user',
+            ugid: grant.userid,
+          }),
+        ),
+      ),
+    );
+    return { baseline, grants, group, role, users };
+  });

package/src/proxmox/replication-job.ts

@@ -1,15 +1,15 @@
 /**
  * `Proxmox.ReplicationJob` — a guest's ZFS storage replication to a second node, declared.
  *
- * ⛔ NOTHING ON TB4 CAN USE THIS FAMILY, AND THAT IS SAID HERE RATHER THAN FOUND OUT LATER. PVE
+ * ⛔ NOTHING ON C1 CAN USE THIS FAMILY, AND THAT IS SAID HERE RATHER THAN FOUND OUT LATER. PVE
  *   storage replication is ZFS-only: `POST /cluster/replication` calls `get_replicatable_volumes`
- *   and refuses a guest whose disks are anywhere else with "No replicatable volumes found". TB4 is
+ *   and refuses a guest whose disks are anywhere else with "No replicatable volumes found". C1 is
  *   Ceph/RBD-backed — shared storage, where replication means nothing because every node already
- *   sees the volume — so `GET /cluster/replication` answers `[]` (MEASURED on n2, 2026-09-13) and
- *   on this cluster always will. The file is written for a ZFS cluster; against TB4 a declaration
+ *   sees the volume — so `GET /cluster/replication` answers `[]` (MEASURED on node-b, 2026-09-13) and
+ *   on this cluster always will. The file is written for a ZFS cluster; against C1 a declaration
  *   is a create that fails with PVE's own sentence, not a plan that quietly does nothing.
  *
- * ★ WHAT IS MEASURED HERE AND WHAT IS REASONED. Measured on n2 (pve-manager 9.2.11), read-only:
+ * ★ WHAT IS MEASURED HERE AND WHAT IS REASONED. Measured on node-b (pve-manager 9.2.11), read-only:
  *   the published schema for all five methods; `PVE/ReplicationConfig.pm` and
  *   `PVE/API2/ReplicationConfig.pm` line by line; `GET /cluster/replication` -> `[]`; and the ACL
  *   row `{"path":"/","propagate":1,"roleid":"PVEAuditor","ugid":"hf-read@pve"}`. NOT measured: any
@@ -45,12 +45,13 @@
  *   declarations differing only in `jobnum` but naming the same target are not two jobs; the second
  *   is a create that fails.
  *
- * ⚠️ RECONCILE NEEDS `VM.Replicate` ON `/vms/<guest>`, WHICH `LXCProvisioner` DOES NOT HOLD. All
+ * ⚠️ RECONCILE NEEDS `VM.Replicate` ON `/vms/<guest>`, WHICH THE PROVISION ROLE DOES NOT HOLD. All
  *   three writes check it (MEASURED in API2/ReplicationConfig.pm: create, update and delete each
  *   call `$rpcenv->check($authuser, "/vms/$vmid", ['VM.Replicate'])`), and the role's 27 privileges
  *   include `VM.Allocate`, `VM.Audit`, `VM.Backup`, `VM.Config.*` and `VM.PowerMgmt` but not
- *   `VM.Replicate`. Widen it deliberately over SSH, preserving what is there, as `pool.ts` records:
- *   `pveum role modify LXCProvisioner --privs "<existing>,VM.Replicate"`.
+ *   `VM.Replicate` (`PROVISION_PRIVILEGES`). Do NOT widen it by hand: the baseline declares the
+ *   role's exact set, so a hand-added privilege is removed on the next deploy. Grant a second role
+ *   holding `VM.Replicate` on `/vms/<guest>` instead.
  *   ★ THE READ LANE NEEDS NOTHING EXTRA, which is why there is no `readRole` below. The ITEM read
  *     checks `VM.Audit` on `/vms/<guest>`, `hf-read@pve` holds the built-in `PVEAuditor` at `/`
  *     with propagate — both MEASURED — and `PVEAuditor` carries `VM.Audit`. This family is not a

package/src/proxmox/resource.ts

@@ -20,7 +20,7 @@ import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
 import * as Effect from 'effect/Effect';
 import type * as HttpClient from 'effect/unstable/http/HttpClient';
-import { pve } from './client.ts';
+import { type PveForm, pve } from './client.ts';
 import type { ApiTarget, PbsTarget, PveRole, PveTarget } from './credentials.ts';
 import { formToSend } from './update-guard.ts';
 
@@ -71,21 +71,21 @@ export type WithPbsTarget = { target: PbsTarget };
 export type WithApiTarget = { target: ApiTarget };
 
 export type PveSpec<Props extends WithApiTarget, Attributes> = {
-  /** `pools/house`, `nodes/n2/lxc/101` — where ONE object is read, updated and deleted. */
+  /** `pools/lab`, `nodes/node-b/lxc/101` — where ONE object is read, updated and deleted. */
   readonly path: (props: Props) => string;
-  /** `pools`, `nodes/n2/lxc` — where a NEW one is POSTed. */
+  /** `pools`, `nodes/node-b/lxc` — where a NEW one is POSTed. */
   readonly collection: (props: Props) => string;
   /** Live JSON to attributes. Returning undefined means "this is not really there". */
   readonly attributes: (live: Record<string, unknown>, props: Props) => Attributes | undefined;
-  /** The form PVE wants on create. ⚠️ PVE takes form encoding, not JSON. */
-  readonly createForm: (props: Props) => Record<string, string>;
+  /** The form PVE wants on create. ⚠️ PVE takes form encoding, not JSON. Arrays: client.ts. */
+  readonly createForm: (props: Props) => PveForm;
   /**
    * The form for an update, or undefined when the object has no mutable fields.
    *
    * ⚠️ SOME PVE OBJECTS CANNOT BE UPDATED AT ALL. Returning undefined makes a changed prop a
    *   REPLACE rather than a silent no-op, which is the honest answer for an immutable object.
    */
-  readonly updateForm?: (props: Props) => Record<string, string>;
+  readonly updateForm?: (props: Props) => PveForm;
   /** True when live already matches props. Decides noop vs update. */
   readonly matches: (attributes: Attributes, props: Props) => boolean;
   /**
@@ -105,7 +105,7 @@ export type PveSpec<Props extends WithApiTarget, Attributes> = {
 export const pveOperations = <Props extends WithApiTarget, Attributes>(
   spec: PveSpec<Props, Attributes>,
 ) => {
-  /** The live object, or undefined. ⚠️ A 404 is an ANSWER here, not a failure. */
+  /** The live object, or undefined. ⚠️ A 404 and `{"data": null}` are ANSWERS, not failures. */
   const read = (props: Props) =>
     pve<Record<string, unknown>>(
       props.target,
@@ -113,7 +113,7 @@ export const pveOperations = <Props extends WithApiTarget, Attributes>(
       'GET',
       spec.path(props),
     ).pipe(
-      Effect.map((data) => (data === undefined ? undefined : spec.attributes(data, props))),
+      Effect.map((data) => (data == null ? undefined : spec.attributes(data, props))),
       Effect.orElseSucceed(() => undefined),
     );
 
@@ -164,7 +164,7 @@ export const pveOperations = <Props extends WithApiTarget, Attributes>(
            *   `Proxmox.NodeNetwork` it is worse than pointless: a PUT under `/nodes/{node}/network`
            *   STAGES a change into `/etc/network/interfaces.new`, so merely adopting the interface
            *   a node already has would leave that node with a pending network change waiting for an
-           *   apply — on a cluster whose Ceph traffic rides vmbr1.11. Adoption has to be free.
+           *   apply — on a cluster whose Ceph traffic rides vmbr1.42. Adoption has to be free.
            *
            * ★ SO THE CONDITION IS THE SAME PREDICATE `diff` USES. If `matches` is true the object
            *   already says what the declaration says, and there is nothing to write — by