@homeflare/alchemy 0.11.0 → 0.12.0

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

@@ -71,9 +71,9 @@ 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;
@@ -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

package/src/proxmox/sdn-apply-read.test.ts

@@ -2,7 +2,7 @@
  * The fabric comparison, which is what decides whether `Proxmox.SdnApply` publishes.
  *
  * ⛔ IT IS TESTED HERE RATHER THAN AGAINST THE CLUSTER BECAUSE STAGING A REAL FABRIC CHANGE MEANS
- *   TOUCHING CEPH'S CLUSTER NETWORK. TB4's OSPF fabric pins 10.100.0.102/103/104 to en05 and en06,
+ *   TOUCHING CEPH'S CLUSTER NETWORK. C1's OSPF fabric pins 203.0.113.102/103/104 to tb0 and tb1,
  *   and those are the addresses `cluster_network` runs over. The staged-zone path IS proven end to
  *   end against the live cluster (plan noop -> stage a zone -> plan update -> remove -> plan noop);
  *   the fabric path is proven by construction, with the two ways it could lie pinned below.
@@ -20,20 +20,20 @@ import { UNDIFFABLE, canonical, fabricStaged, subsystemAbsent } from './sdn-appl
 
 /** The shape `cluster/sdn/fabrics/all` actually returns, trimmed to what matters. */
 const N2 = {
-  fabric_id: 'tb4',
-  interfaces: ['name=en05', 'name=en06'],
-  ip: '10.100.0.102',
-  node_id: 'n2',
+  fabric_id: 'c1',
+  interfaces: ['name=tb0', 'name=tb1'],
+  ip: '203.0.113.102',
+  node_id: 'node-b',
 };
 const N3 = {
-  fabric_id: 'tb4',
-  interfaces: ['name=en05', 'name=en06'],
-  ip: '10.100.0.103',
-  node_id: 'n3',
+  fabric_id: 'c1',
+  interfaces: ['name=tb0', 'name=tb1'],
+  ip: '203.0.113.103',
+  node_id: 'node-c',
 };
 
 const running = {
-  fabrics: [{ area: '1', id: 'tb4', ip_prefix: '10.100.0.0/24', protocol: 'ospf' }],
+  fabrics: [{ area: '1', id: 'c1', ip_prefix: '203.0.113.0/24', protocol: 'ospf' }],
   nodes: [N2, N3],
 };
 
@@ -44,8 +44,8 @@ describe('fabric canonicalisation', () => {
         {
           area: '1',
           digest: '7b94d363ff69',
-          id: 'tb4',
-          ip_prefix: '10.100.0.0/24',
+          id: 'c1',
+          ip_prefix: '203.0.113.0/24',
           protocol: 'ospf',
         },
       ],
@@ -76,7 +76,7 @@ describe('fabric canonicalisation', () => {
   it('sees a changed node address', () => {
     const moved = {
       ...running,
-      nodes: [{ ...N2, ip: '10.100.0.199' }, N3],
+      nodes: [{ ...N2, ip: '203.0.113.199' }, N3],
     };
     assert.notEqual(canonical(moved), canonical(running));
   });
@@ -86,7 +86,7 @@ describe('fabric canonicalisation', () => {
       ...running,
       nodes: [
         ...running.nodes,
-        { fabric_id: 'tb4', interfaces: ['name=en05'], ip: '10.100.0.104', node_id: 'n4' },
+        { fabric_id: 'c1', interfaces: ['name=tb0'], ip: '203.0.113.104', node_id: 'node-d' },
       ],
     };
     assert.notEqual(canonical(added), canonical(running));
@@ -95,7 +95,7 @@ describe('fabric canonicalisation', () => {
   it('sees a changed interface list, which is what decides where the address lands', () => {
     const rewired = {
       ...running,
-      nodes: [{ ...N2, interfaces: ['name=en05'] }, N3],
+      nodes: [{ ...N2, interfaces: ['name=tb0'] }, N3],
     };
     assert.notEqual(canonical(rewired), canonical(running));
   });
@@ -135,7 +135,7 @@ describe('what a failed read is allowed to mean', () => {
   });
 
   it('counts an unchanged fabric as nothing staged and a moved node as staged', () => {
-    const moved = { ...running, nodes: [{ ...N2, ip: '10.100.0.199' }, N3] };
+    const moved = { ...running, nodes: [{ ...N2, ip: '203.0.113.199' }, N3] };
     assert.equal(fabricStaged(canonical(running), canonical(running)), 0);
     assert.equal(fabricStaged(canonical(moved), canonical(running)), 1);
   });

package/src/proxmox/sdn-apply-read.ts

@@ -3,12 +3,12 @@
  * collections this package declares resources for.
  *
  * 🔴 THE GAP THIS FILE CLOSES, AND IT WAS FOUND BY ALMOST DECLARING THE APPLY. `pendingCount` in
- *   sdn-apply.ts counted `cluster/sdn/zones` and `cluster/sdn/vnets`. TB4 has zero of each — and a
- *   staged OSPF FABRIC that nothing counted. MEASURED 2026-09-13 on n2:
+ *   sdn-apply.ts counted `cluster/sdn/zones` and `cluster/sdn/vnets`. C1 has zero of each — and a
+ *   staged OSPF FABRIC that nothing counted. MEASURED 2026-09-13 on node-b:
  *
- *     /etc/pve/sdn/fabrics.cfg   ospf_fabric: tb4, area 1, ip_prefix 10.100.0.0/24
- *                                ospf_node: tb4_n2/n3/n4, interfaces en05 + en06,
- *                                ip 10.100.0.102 / .103 / .104
+ *     /etc/pve/sdn/fabrics.cfg   ospf_fabric: c1, area 1, ip_prefix 203.0.113.0/24
+ *                                ospf_node: c1_n2/node-c/node-d, interfaces tb0 + tb1,
+ *                                ip 203.0.113.102 / .103 / .104
  *     /etc/network/interfaces.d/sdn   the file PVE GENERATES from it, carrying those /32s
  *
  *   Those addresses are Ceph's `cluster_network`. So `diff` would have answered `noop` for ever
@@ -62,7 +62,7 @@ const MARKED = [
  *
  * ⚠️ NAMED RATHER THAN SILENTLY SKIPPED. `ipams` and `dns` answer HTTP 400 to both `?pending=1` and
  *   `?running=1`, so there is no way to ask them what is staged. They are a REAL blind spot: an
- *   ipam edited by hand is published by the apply and cannot be seen from here. TB4 has one ipam
+ *   ipam edited by hand is published by the apply and cannot be seen from here. C1 has one ipam
  *   (`pve`, the built-in) and zero dns entries, so the blind spot is currently empty — which is a
  *   fact about today, not a property of the design.
  */
@@ -181,7 +181,7 @@ const sortDeep = (value: unknown): unknown => {
  *
  * ⛔ ZERO HERE IS THE ONLY THING THAT MAKES DECLARING THE APPLY SAFE. `reconcile` runs on CREATE —
  *   Alchemy always calls it the first time a resource appears — and `PUT /cluster/sdn` regenerates
- *   `/etc/network/interfaces.d/sdn` on every node. On TB4 that file carries Ceph's cluster network.
+ *   `/etc/network/interfaces.d/sdn` on every node. On C1 that file carries Ceph's cluster network.
  */
 export const sdnPendingCount = (target: PveTarget) =>
   Effect.all([markedPending(target), fabricPending(target)], { concurrency: 'unbounded' }).pipe(

package/src/proxmox/sdn-apply.ts

@@ -6,7 +6,7 @@
  *   is the apply, and it is CLUSTER-WIDE — it publishes every staged object at once, not the one
  *   that happened to reconcile.
  *
- * ★ MEASURED ON TB4 ON 2026-09-13, NOT INFERRED. A probe zone was created, inspected and removed:
+ * ★ MEASURED ON C1 ON 2026-09-13, NOT INFERRED. A probe zone was created, inspected and removed:
  *
  *     pvesh create /cluster/sdn/zones --zone zzprobe --type simple
  *     GET /cluster/sdn/zones/zzprobe              -> {"digest":"c438…","type":"simple","zone":"zzprobe"}
@@ -109,8 +109,8 @@ export const ProxmoxSdnApplyProvider = () =>
            *
            * 🔴 WHAT IT PREVENTS. `reconcile` runs on CREATE, the first time this resource appears
            *   in a stack, before `diff` has ever been consulted. `PUT /cluster/sdn` regenerates
-           *   `/etc/network/interfaces.d/sdn` on EVERY node at once — and on TB4 that file carries
-           *   the OSPF fabric holding Ceph's `cluster_network` on en05/en06. Without this branch,
+           *   `/etc/network/interfaces.d/sdn` on EVERY node at once — and on C1 that file carries
+           *   the OSPF fabric holding Ceph's `cluster_network` on tb0/tb1. Without this branch,
            *   adding one line to a stack file reloads networking on all three nodes simultaneously,
            *   which is precisely what the serialised NetworkApply chain exists to prevent.
            *

package/src/proxmox/sdn-subnet-form.ts

@@ -22,7 +22,7 @@ export type DhcpRange = { start: string; end: string };
  *
  * ⛔ MEASURED from `/usr/share/perl5/PVE/API2/Network/SDN/Subnets.pm` on pve-manager 9.2.11, in
  *   the create handler: `my $id = $cidr =~ s/\//-/r; $id = "$zoneid-$id";`. So `subnet=10.0.0.0/24`
- *   goes out and `house-10.0.0.0-24` is what exists afterwards. A CIDR cannot be a path segment
+ *   goes out and `lab-10.0.0.0-24` is what exists afterwards. A CIDR cannot be a path segment
  *   anyway — it carries a slash — so there is no spelling of this endpoint that takes the CIDR.
  *
  * ⚠️ `.replace`, NOT `.replaceAll`, AND THE PARITY IS DELIBERATE. Perl's `s/\//-/r` has no `/g`, so

package/src/proxmox/sdn-subnet.ts

@@ -11,7 +11,7 @@
  *   `vnet`; a literal buys no ordering, and here it also buys a wrong path.
  *
  * ⛔ THE ID PVE FILES A SUBNET UNDER IS NOT THE ONE YOU WRITE, AND IT IS THIS FAMILY'S SHARPEST
- *   EDGE. `POST` takes `subnet=10.0.0.0/24` while GET, PUT and DELETE address `house-10.0.0.0-24`.
+ *   EDGE. `POST` takes `subnet=10.0.0.0/24` while GET, PUT and DELETE address `lab-10.0.0.0-24`.
  *   One PVE parameter name, `subnet`, carrying two different values — so they are named APART here,
  *   `cidr` for the declared one and `subnetId` for the derived one, for the reason values.ts gives
  *   about `flag`: a name that means two things is a bug waiting for whoever reads one meaning. The
@@ -50,11 +50,11 @@
  *   seven privileges include SDN.Audit — at `/` with propagate=1. So the default 3600s auditor
  *   lease reads this family, and a `readRole: 'provision'` here would be privilege nobody needed.
  *   Writes are a different answer: POST, PUT and DELETE all require SDN.Allocate on
- *   `/sdn/zones/<zone>/<vnet>`, which `LXCProvisioner` gained on 2026-09-13.
+ *   `/sdn/zones/<zone>/<vnet>`, which the provision role gained on 2026-09-13 (`PROVISION_PRIVILEGES`).
  *
- * ⚠️ NO LIVE SUBNET EXISTS ON TB4 TO ROUND-TRIP AGAINST — there are no SDN zones and no vnets, so
+ * ⚠️ NO LIVE SUBNET EXISTS ON C1 TO ROUND-TRIP AGAINST — there are no SDN zones and no vnets, so
  *   there can be no subnets. Every claim above is read off PVE 9.2.11's own schema and Perl sources
- *   on n2, and the noop argument below rests on those rather than on a plan this file has watched.
+ *   on node-b, and the noop argument below rests on those rather than on a plan this file has watched.
  *
  * ⚠️ TWO REFUSALS TO EXPECT, both from `SubnetPlugin::on_update_hook`: PVE will not put a subnet on
  *   a vnet with `vlanaware` set ("you can't add a subnet on a vlanaware vnet"), and it rejects a
@@ -98,7 +98,7 @@ export interface SdnSubnetProps extends WithTarget {
   gateway?: string;
   /**
    * Masquerade this subnet. ⚠️ INERT UNTIL THE CLUSTER FIREWALL IS ON — PVE's own description is
-   *   "enable masquerade for this subnet if pve-firewall", and TB4's cluster firewall was empty and
+   *   "enable masquerade for this subnet if pve-firewall", and C1's cluster firewall was empty and
    *   disabled when this was written. It still round-trips, so declaring it does not diff.
    */
   snat?: boolean;

package/src/proxmox/sdn-vnet.ts

@@ -35,12 +35,11 @@
  *   than an error — see the ⛔ in sdn-zone.ts and docs/privileges.md.
  *
  * ⚠️ PRIVILEGES, AND THE ESTATE'S CREDENTIAL HELD NONE OF THEM UNTIL 2026-09-13. reconcile and
- *   delete mint `provision` and need SDN.Allocate on `/sdn/zones`, or on the one zone if scoped. `LXCProvisioner` grants
- *   SDN.Use, which is what a GUEST needs in order to attach to a vnet and NOT what creating one
- *   needs, so a container declared on this vnet works today while the vnet itself 403s. Widen
- *   deliberately, the way Pool.Allocate was:
- *   `pveum role modify LXCProvisioner --privs "<existing>,SDN.Allocate,SDN.Audit"` over SSH,
- *   preserving every existing privilege.
+ *   delete mint `provision` and need SDN.Allocate on `/sdn/zones`, or on the one zone if scoped. The provision role granted
+ *   only SDN.Use then, which is what a GUEST needs in order to attach to a vnet and NOT what
+ *   creating one needs, so a container on a vnet worked while the vnet itself 403'd. It was widened
+ *   the way Pool.Allocate was, and `PROVISION_PRIVILEGES` (provision-baseline.ts) now carries
+ *   SDN.Allocate and SDN.Audit.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';

package/src/proxmox/storage.ts

@@ -21,9 +21,10 @@
  *   messages point away from the cause.
  *   ★ SO WIDEN OR RE-POINT BEFORE THE FIRST PLAN, outside this file: give the credential mount's
  *     `read` role `Datastore.Allocate` on `/storage`, or read this family with `provision`. The
- *     provision role in the estate this was written for holds `Datastore.AllocateSpace` and
+ *     provision role in the estate this was written for held only `Datastore.AllocateSpace` and
  *     `Datastore.Audit`, and NEITHER IS IT — AllocateSpace writes volumes INTO a storage, Allocate
- *     DEFINES one — so it 403s here until widened the way `Pool.Allocate` was for `Proxmox.Pool`.
+ *     DEFINES one — so it 403'd here until widened the way `Pool.Allocate` was for `Proxmox.Pool`.
+ *     The provisioning baseline (`provision-baseline.ts`) carries `Datastore.Allocate`.
  *
  * ⛔ THERE IS NO `password` PROP AND THERE MUST NEVER BE ONE. PBS and CIFS storages take one at
  *   create time, and Alchemy persists attributes UNENCRYPTED — a secret in props is one careless
@@ -68,7 +69,7 @@ export interface StorageProps extends WithTarget {
   /** `images,rootdir,vztmpl,iso,backup,snippets`. PVE reports `none` for an empty set. */
   content?: string;
   /**
-   * Node restriction, e.g. `n1,n2`. ⚠️ A STORAGE WITH A `nodes` LIST DOES NOT EXIST ANYWHERE ELSE:
+   * Node restriction, e.g. `node-a,node-b`. ⚠️ A STORAGE WITH A `nodes` LIST DOES NOT EXIST ANYWHERE ELSE:
    * an LXC declared on a node outside it fails at create with "storage not available on node".
    */
   nodes?: string;

package/src/proxmox/user.ts

@@ -29,8 +29,9 @@
  *   can then say what a delete would take with it — and kept OUT of `matches`, exactly like
  *   `pool.members`. Reported, never declared.
  *
- * ⚠️ RECONCILE NEEDS PRIVILEGES `LXCProvisioner` DOES NOT HOLD, so state them rather than meet a
- *   403 in the middle of a deploy (pool.ts records how that went the last time):
+ * ⚠️ 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:
  *     · `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

package/src/proxmox/values.test.ts

@@ -99,11 +99,11 @@ describe('num and text', () => {
 
 describe('csv — a set PVE does not give back in the order it was handed', () => {
   it('is order insensitive, so two orderings compare equal', () => {
-    assert.equal(csv(['n3', 'n2']), csv('n2,n3'));
+    assert.equal(csv(['node-c', 'node-b']), csv('node-b,node-c'));
   });
 
   it('trims and drops empties, so a trailing comma is not a phantom member', () => {
-    assert.equal(csv('n2, n3,'), 'n2,n3');
+    assert.equal(csv('node-b, node-c,'), 'node-b,node-c');
   });
 });
 

package/src/proxmox/values.ts

@@ -168,7 +168,7 @@ export const int = (value: unknown, fallback: number) => {
  * A PVE update form with its clear-list attached, and the two guaranteed not to overlap.
  *
  * ⛔ PVE DIES IF A KEY IS SET AND DELETED IN ONE CALL, AND SIX FAMILIES HERE BUILT THAT FORM BY
- *   HAND. Measured in the shipped Perl on n2 — `PVE::SectionConfig::delete_from_config`, line 1860:
+ *   HAND. Measured in the shipped Perl on node-b — `PVE::SectionConfig::delete_from_config`, line 1860:
  *
  *     die "cannot set and delete property '$k' at the same time!\n"
  *         if defined($new_options->{$k});

package/src/proxmox/zfs-pool-write.ts

@@ -51,7 +51,7 @@ const SETTLE_ATTEMPTS = 30;
 /**
  * Create the pool if it is absent, and otherwise leave it completely alone.
  *
- * ⛔ THE POST ONLY FORKS A WORKER. MEASURED in `/usr/share/perl5/PVE/API2/Disks/ZFS.pm` on n2: the
+ * ⛔ THE POST ONLY FORKS A WORKER. MEASURED in `/usr/share/perl5/PVE/API2/Disks/ZFS.pm` on node-b: the
  *   create handler ends in `$rpcenv->fork_worker('zfscreate', ...)` and its HTTP answer is a UPID
  *   returned the instant the worker is forked — before `zpool create` has run, let alone finished.
  *   A read-back taken immediately, as `pveOperations.reconcile` takes it, finds nothing and would

package/src/proxmox/zfs-pool.ts

@@ -22,22 +22,22 @@
  *     that one line turns a text edit into an unrecoverable one.
  *
  * ⛔ THERE IS NO PUT ON THIS FAMILY AT ALL. MEASURED from the cluster's own published schema
- *   (`/usr/share/pve-docs/api-viewer/apidoc.js`, read on n2 2026-09-13): `/nodes/{node}/disks/zfs`
+ *   (`/usr/share/pve-docs/api-viewer/apidoc.js`, read on node-b 2026-09-13): `/nodes/{node}/disks/zfs`
  *   has GET and POST, `/nodes/{node}/disks/zfs/{name}` has GET and DELETE, and that is the whole
  *   surface. So `updateForm` is omitted — which, per `resource.ts`, makes any `matches` = false a
  *   REPLACE. A replace is a delete followed by a create, and on this family the delete is the
  *   thing above. Read the ⛔ on `matches` before adding anything to it.
  *
  * ⛔ NOT ONE CREATE PARAMETER COMES BACK ON READ, SO `matches` COMPARES NOTHING. MEASURED against
- *   the live cluster: `GET /nodes/n2/disks/zfs/rpool` answers exactly
+ *   the live cluster: `GET /nodes/node-b/disks/zfs/rpool` answers exactly
  *   `{action, children, errors, leaf, name, scan, state, status}` — no `ashift`, no `compression`,
  *   no `raidlevel`, no `devices`, no `add_storage`. Every create parameter is write-only. There is
  *   therefore no field a declaration and a live pool can both be asked about, and a `matches` that
  *   invented one would plan a replace — i.e. a `zpool destroy` — over a difference it could never
  *   verify in the first place.
  *
- * ⚠️ AND WHAT THE INDEX RETURNS IS LIVE TELEMETRY, NOT CONFIGURATION. `GET /nodes/n2/disks/zfs`
- *   gives `alloc`, `free`, `frag`, `dedup`, `size`, `health`. MEASURED: two reads of n2 seconds
+ * ⚠️ AND WHAT THE INDEX RETURNS IS LIVE TELEMETRY, NOT CONFIGURATION. `GET /nodes/node-b/disks/zfs`
+ *   gives `alloc`, `free`, `frag`, `dedup`, `size`, `health`. MEASURED: two reads of node-b seconds
  *   apart returned `alloc` 14474944512 then 14472740864 — it moves on its own, with no declaration
  *   anywhere near it. `scan` in the detail read moves the same way (it carries the last scrub), and
  *   `status`/`action` appear and vanish as ZFS feature flags and faults come and go. None of them
@@ -155,7 +155,7 @@ export interface ZfsPoolAttributes {
    *
    * ⚠️ THIS IS WHAT ZFS RESOLVED, NOT WHAT WAS DECLARED, and the two normally differ: PVE rewrites
    *   a `/dev/sdb` into a by-id link before creating, and ZFS reports partition paths (`…-part3`)
-   *   for a pool built on partitions — MEASURED, that is exactly what n2's `rpool` reports. Never
+   *   for a pool built on partitions — MEASURED, that is exactly what node-b's `rpool` reports. Never
    *   compare it with `props.devices`.
    */
   devices: string;
@@ -219,7 +219,7 @@ const spec: PveSpec<ZfsPoolProps, ZfsPoolAttributes> = {
    *   can be compared on: every create parameter is write-only (see the ⛔ in the header) and
    *   everything the read does return is telemetry that moves by itself. So declaring what is live
    *   plans as `noop` — the only honest answer available, and the one the live cluster needs:
-   *   `rpool` exists on n2, n3 and n4 with nothing about its construction readable.
+   *   `rpool` exists on node-b, node-c and node-d with nothing about its construction readable.
    *   ⛔ ANYTHING ADDED HERE IS A REPLACE, NOT AN UPDATE. `updateForm` is omitted because PVE has
    *     no PUT, so `resource.ts` turns a false into `{action:'replace'}` — delete then create — on
    *     a family whose delete is `zpool destroy`. A comparison added here would be one plan away

package/src/talos/credentials.ts

@@ -4,9 +4,9 @@
  * ⛔ TALOSCONFIG AND secrets.yaml HOLD CLIENT CERTIFICATES AND CLUSTER CA PRIVATE KEYS. Alchemy
  *   persists resource attributes WITHOUT encryption — StateEncoding.ts writes `Redacted` as
  *   `{"@redacted": <plaintext>}` — and this estate's state store is the `alchemy` Postgres that
- *   pg-backup.sh dumps nightly. Neither file may be a prop, an attribute, or a log line.
+ *   a nightly job dumps. Neither file may be a prop, an attribute, or a log line.
  *
- * ★ MODELED ON house/proxmox/src/credentials.ts: mint at call time through `ChildProcessSpawner`,
+ * ★ MODELED ON <estate>/proxmox/src/credentials.ts: mint at call time through `ChildProcessSpawner`,
  *   use the material to build a client, drop it when the scope ends. The difference is Talos wants a
  *   FILE (`--talosconfig` / `TALOSCONFIG`), so mint writes a temp path and registers cleanup.
  *
@@ -21,7 +21,7 @@ import * as ChildProcessSpawner from 'effect/unstable/process/ChildProcessSpawne
 
 /** Where credentials come from. HomeFlare-specific mount names live in the stack, not here. */
 export type TalosTarget = {
-  /** OpenBao KV mount holding Talos material, e.g. `talos-tb4`. */
+  /** OpenBao KV mount holding Talos material, e.g. `talos-c1`. */
   readonly mount: string;
   /** Logical cluster name — safe to persist and log. */
   readonly cluster: string;