@homeflare/alchemy 0.10.1 → 0.12.0

package/src/proxmox/firewall-alias.ts

@@ -61,7 +61,7 @@
  * ⚠️ PRIVILEGES, AND FOR ONCE NOTHING NEEDS WIDENING. MEASURED 2026-09-13 from the cluster's own
  *   schema and its live ACL: the item GET checks `["perm","/",["Sys.Audit"]]`, POST/PUT/DELETE
  *   check `["perm","/",["Sys.Modify"]]`, `hf-read@pve` holds `PVEAuditor` at `/` with propagate and
- *   `hf-provision@pve` holds `LXCProvisioner` at `/` with propagate. Both privileges are already
+ *   `hf-provision@pve` holds the provision role (provision-baseline.ts) at `/` with propagate. Both privileges are already
  *   held, so `readRole` stays the default `read` lane — unlike storage/sdn-zone/sdn-vnet, whose
  *   ITEM reads are gated on an allocate privilege the auditor cannot have.
  *   ⚠️ `Sys.Modify` ON `/` IS STILL A BIG HAMMER — it is the same grant `metric-server.ts` warns

package/src/proxmox/generated/pbs.ts

@@ -2,7 +2,7 @@
  * Generated PBS API types — DO NOT EDIT BY HAND.
  *
  * Run: bun codegen/generate.ts
- * Source: house/proxmox/apidoc/ — see README there for provenance.
+ * Source: the cluster's own `apidoc.js` (pve-docs), extracted outside this repo.
  */
 
 /** GET /config/datastore — `data` payload after client unwrap. */

package/src/proxmox/generated/pve.ts

@@ -2,7 +2,7 @@
  * Generated PVE API types — DO NOT EDIT BY HAND.
  *
  * Run: bun codegen/generate.ts
- * Source: house/proxmox/apidoc/ — see README there for provenance.
+ * Source: the cluster's own `apidoc.js` (pve-docs), extracted outside this repo.
  */
 
 /** GET /cluster/replication — `data` payload after client unwrap. */

package/src/proxmox/group.ts

@@ -1,7 +1,7 @@
 /**
  * `Proxmox.Group` — a PVE group: a name, a comment, and the set of users PVE hangs off it.
  *
- * ★ DECLARING `hf-mint` IS THE WHOLE POINT OF THIS FAMILY. `vaultmint@pve` holds the `HFMint` role
+ * ★ DECLARING `hf-mint` IS THE WHOLE POINT OF THIS FAMILY. `mint@pve` holds the `MintTokens` role
  *   ON THE PATH `/access/groups/hf-mint` — measured from `GET /access/acl`, 2026-09-13 — which is
  *   what confines the OpenBao proxmox engine to minting inside that one group. The group is the
  *   fence around the credential every other resource in this package runs on, and until now it was
@@ -17,7 +17,7 @@
  *   in this file could ever settle.
  *
  * ⛔ THE INDEX AND THE ITEM DISAGREE ABOUT BOTH THE NAME AND THE TYPE, and this file reads only the
- *   item. MEASURED against n2, 2026-09-13:
+ *   item. MEASURED against node-b, 2026-09-13:
  *     GET /access/groups         -> [{"groupid":"hf-mint","comment":"…",
  *                                     "users":"hf-provision@pve,hf-read@pve"}, …]
  *     GET /access/groups/hf-mint -> {"comment":"…","members":["hf-provision@pve","hf-read@pve"]}
@@ -27,8 +27,8 @@
  *
  * ⛔ AND THE ITEM'S ORDER IS NOT STABLE BETWEEN TWO CONSECUTIVE CALLS. MEASURED, seconds apart, on
  *   the same endpoint:
- *     ["root@pam","tim@pve","tim@pam","tim@<account>.com@Schenanigans"]
- *     ["tim@pam","tim@pve","tim@<account>.com@Schenanigans","root@pam"]
+ *     ["root@pam","alice@pve","alice@pam","alice@example.com@corp"]
+ *     ["alice@pam","alice@pve","alice@example.com@corp","root@pam"]
  *   `read_group` builds it as `[keys %{ $data->{users} }]` — a bare Perl hash key list, whose order
  *   is randomised per process — while the INDEX sorts (`join(',', sort keys …)`). So the array is
  *   sorted on the way into `attributes` as well as being kept out of `matches`: unsorted, Alchemy's
@@ -45,7 +45,7 @@
  *       So `readRole` is left at the default `read` — unlike storage/sdn-zone/sdn-vnet, whose ITEM
  *       reads PVE gates on an allocate privilege. See the ⛔ on `readRole` in `resource.ts`.
  *     · POST, PUT and DELETE each check `Group.Allocate` on `/access/groups`, and
- *       `hf-provision@pve` holds it via `LXCProvisioner`.
+ *       `hf-provision@pve` holds it via the provision role (`PROVISION_PRIVILEGES`).
  *
  * ⛔ `retain` BY DEFAULT, BECAUSE DELETING A GROUP DESTROYS TWO THINGS THIS FILE CANNOT PUT BACK.
  *   Measured in `PVE::AccessControl` on the node:
@@ -53,8 +53,8 @@
  *       <comment>:`) and DERIVES each user's `groups` map from it at parse time. Deleting the group
  *       deletes the list, and this resource has no `members` prop to restore it from.
  *     · `delete_group_acl` then walks the whole ACL tree and drops every grant where the group is
- *       the SUBJECT. On this cluster that is `Schenanigans -> Administrator on /` and
- *       `HomeAssistant -> PVEAuditor on /`: whole populations of access, gone in one call, with no
+ *       the SUBJECT. On this cluster that is `admins -> Administrator on /` and
+ *       `automation -> PVEAuditor on /`: whole populations of access, gone in one call, with no
  *       confirmation and nothing in the plan to suggest it.
  *   `delete` is FULLY IMPLEMENTED — `DELETE /access/groups/{groupid}` exists, unlike the ACL
  *   family's — so `.pipe(RemovalPolicy.destroy())` really removes the group. See the ★ in
@@ -120,7 +120,7 @@ export const ProxmoxGroup = Resource<ProxmoxGroup>('Proxmox.Group', {
  *   back as absent. Left alone, `matches` would be false on every plan and every deploy would
  *   rewrite the same value into the same hole. Normalising BOTH the comparison and the form is how
  *   `values.ts` already treats `''` as the absence of a boolean rather than as `false`.
- *   ⚠️ MEASURED IN THE SOURCE ON n2, NOT ON THE WIRE — writing `'0'` to the cluster to watch it
+ *   ⚠️ MEASURED IN THE SOURCE ON node-b, NOT ON THE WIRE — writing `'0'` to the cluster to watch it
  *     vanish would have been a write, and this agent had read access only.
  *   ⚠️ `pool.ts` HAS THE SAME LATENT HOLE — `pool:$pool:$comment:…` is written by that same
  *     truthiness test and is not guarded. Not fixed from here; flagged so it is fixed on purpose.
@@ -160,7 +160,7 @@ const handlers = pveHandlers<GroupProps, GroupAttributes>({
      *   without one answers `{"members":[…]}` and nothing else. THAT ONE IS READ OFF THE HANDLER'S
      *   SOURCE, not off the wire — every group on this cluster happens to carry a comment, so the
      *   commentless shape was not there to measure. The empty-MEMBERS shape WAS measured —
-     *   `HomeAssistant` answers `{"comment":"…","members":[]}`. `''` is what an undeclared
+     *   `automation` answers `{"comment":"…","members":[]}`. `''` is what an undeclared
      *   `comment` prop normalises to, so the two sides meet either way.
      */
     comment: text(live['comment']),
@@ -190,7 +190,7 @@ const handlers = pveHandlers<GroupProps, GroupAttributes>({
 
 /**
  * ⛔ THE EMPTY `list` IS INHERITED FROM `pveHandlers` AND IT MATTERS HERE. `GET /access/groups`
- *   answers with every group on the cluster — on this one that is `Schenanigans`, which grants
+ *   answers with every group on the cluster — on this one that is `admins`, which grants
  *   `Administrator` on `/` to every human who logs in. Handing it to Alchemy would invite adoption,
  *   and therefore one day a delete that takes the whole admin group's access with it. Adoption
  *   stays an explicit act, here as everywhere else in this package.

package/src/proxmox/ha-resource.ts

@@ -35,10 +35,11 @@
  *   (node-affinity and resource-affinity) and that is the next family to add; do not port the old
  *   groups endpoint back just because the docs still describe it.
  *
- * ⚠️ RECONCILE NEEDS `Sys.Console` ON `/`, WHICH `LXCProvisioner` DOES NOT HOLD. Read and diff are
+ * ⚠️ RECONCILE NEEDS `Sys.Console` ON `/`, WHICH THE PROVISION ROLE LACKED WHEN THIS WAS WRITTEN
+ *   (`PROVISION_PRIVILEGES` carries it now — ha-rule.ts has the measurement). Read and diff are
  *   fine — `GET /cluster/ha/resources/{sid}` checks `Sys.Audit`, which the role already has — while
  *   POST, PUT and DELETE all check `Sys.Console` on `/` and will answer "Permission check failed
- *   (/, Sys.Console)" until the role is widened. Widen it knowingly: `Sys.Console` is also what
+ *   (/, Sys.Console)" on a role without it. Widen it knowingly: `Sys.Console` is also what
  *   opens a root shell on every node (`/nodes/{node}/vncshell`, `termproxy`), so granting it to the
  *   provision credential buys HA membership at the price of node console access. A separate role
  *   for HA writes is the narrower answer if that trade is not wanted.

package/src/proxmox/ha-rule-form.ts

@@ -16,21 +16,21 @@ import { csv } from './values.ts';
  * A `<node>[:<pri>]` list, spelled the way PVE gives it back.
  *
  * ⛔ THIS IS NOT `csv`, AND THE DIFFERENCE IS A FOREVER-DIFF. MEASURED by reading
- *   `/usr/share/perl5/PVE/HA/Rules/NodeAffinity.pm` on n2 (2026-09-13): `decode_plugin_value`
+ *   `/usr/share/perl5/PVE/HA/Rules/NodeAffinity.pm` on node-b (2026-09-13): `decode_plugin_value`
  *   turns the list into a HASH keyed by node name, and `encode_plugin_value` rebuilds it with
  *   `for my $node (sort keys %$value)` — sorted by NODE NAME, never by the token — emitting the
  *   bare name whenever the priority is falsy, because `PVE::HA::Tools::parse_node_priority` reads
- *   a missing priority as 0. So a declared `n3:1,n2:0` is handed back as `n2,n3:1`: re-ordered AND
+ *   a missing priority as 0. So a declared `node-c:1,node-b:0` is handed back as `node-b,node-c:1`: re-ordered AND
  *   re-spelled. Compare the raw strings and every plan reports an update, forever.
  *
  * ⚠️ SORTED BY NAME, NOT BY TOKEN, AND THE TWO GENUINELY DIVERGE. `csv` sorts whole tokens. Node
  *   names may contain `-` — `parse_node_priority`'s own regex is
- *   `[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?` — and `-` (0x2D) sorts before `:` (0x3A), so `n2-a`
- *   and `n2:5` come out in one order by token and the other by name. PVE sorts by the name, so
+ *   `[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?` — and `-` (0x2D) sorts before `:` (0x3A), so `node-b-a`
+ *   and `node-b:5` come out in one order by token and the other by name. PVE sorts by the name, so
  *   this does too.
  *
  * ⚠️ LAST ENTRY WINS FOR A REPEATED NODE, because PVE's decode is a hash assignment and a hash
- *   keeps one value per key. A declaration saying `n2:1,n2:5` is stored as `n2:5`; matching that
+ *   keeps one value per key. A declaration saying `node-b:1,node-b:5` is stored as `node-b:5`; matching that
  *   is what a Map gives for free.
  */
 export const nodeList = (value: readonly string[] | string | undefined) => {

package/src/proxmox/ha-rule.ts

@@ -1,7 +1,7 @@
 /**
  * `Proxmox.HaRule` — where the CRM may place a guest, and which guests must not share a node.
  *
- * ★ THIS IS THE PVE 9 SUCCESSOR TO HA GROUPS, AND THE GROUPS ENDPOINT IS GONE. MEASURED on n2
+ * ★ THIS IS THE PVE 9 SUCCESSOR TO HA GROUPS, AND THE GROUPS ENDPOINT IS GONE. MEASURED on node-b
  *   (pve-manager/9.2.11, 2026-09-13): `pvesh get /cluster/ha/groups` answers `cannot index groups:
  *   ha groups have been migrated to rules`, and `/etc/pve/ha/` holds `rules.cfg` with no
  *   `groups.cfg` beside it. The published schema still documents groups and still offers a `group`
@@ -48,8 +48,8 @@
  * ⚠️ BOTH LANES ALREADY HAVE THE PRIVILEGES, WHICH IS NEW. MEASURED 2026-09-13:
  *   GET (collection and item) checks `Sys.Audit` on `/` and the built-in `PVEAuditor` holds it, so
  *   `readRole` stays the default `read` lease — unlike storage.ts and the SDN families. POST, PUT
- *   and DELETE all check `Sys.Console` on `/`, and `pvesh get /access/roles/LXCProvisioner` now
- *   returns `Sys.Console` among its 27 privileges. The warning in ha-resource.ts's header — that
+ *   and DELETE all check `Sys.Console` on `/`, and the provision role now returns `Sys.Console` among
+ *   its 27 privileges (`PROVISION_PRIVILEGES`, provision-baseline.ts). The warning in ha-resource.ts's header — that
  *   `Sys.Console` is missing — is stale; the role was widened, and the price it named still stands:
  *   `Sys.Console` is also what opens a root shell on every node.
  *

package/src/proxmox/index.test.ts

@@ -40,6 +40,13 @@ test('control-plane Resource constructors are on the public barrel', () => {
   }
 });
 
+test('the provisioning baseline is on the barrel: the list, the declaration, the bootstrap', async () => {
+  const barrel = await import('./index.ts');
+  expect(barrel.PROVISION_PRIVILEGES).toHaveLength(27);
+  expect(typeof barrel.declareProvisionBaseline).toBe('function');
+  expect(barrel.provisionBootstrap()).toStartWith('#!/bin/sh\n');
+});
+
 test('QEMU and NIC apply stay Provider-only', () => {
   expect(src).not.toMatch(/export \{ ProxmoxVm[, }]/);
   expect(src).not.toMatch(/export \{ ProxmoxNodeNetwork[, }]/);

package/src/proxmox/index.ts

@@ -12,6 +12,9 @@
  *   The provider-only version diffed four fields and would have planned a create over any read
  *   failure. The Resource now adopts from the live config, refuses every change PVE cannot make
  *   in place, and retains on destroy (lxc.ts).
+ * ★ THE PROVISIONING BASELINE JOINED 2026-09-21: one privilege list (`PROVISION_PRIVILEGES`), the
+ *   helper that declares it (`declareProvisionBaseline`) and the pure generator of the one-time
+ *   root commands that bootstrap it (`provisionBootstrap`) — docs/provision-baseline.md.
  * ★ Anything else unlisted is still reachable by path if you genuinely need
  *   it — that is a deliberate, visible act rather than an accident of barrelling.
  */
@@ -40,6 +43,17 @@ export { PbsPruneJob, PbsPruneJobProvider } from './pbs-prune-job.ts';
 export { PbsSyncJob, PbsSyncJobProvider } from './pbs-sync-job.ts';
 export { PbsVerifyJob, PbsVerifyJobProvider } from './pbs-verify-job.ts';
 export { ProxmoxPool, ProxmoxPoolProvider } from './pool.ts';
+export {
+  PROVISION_DEFAULTS,
+  PROVISION_PRIVILEGES,
+  type ProvisionBaseline,
+  type ProvisionLane,
+  type ProvisionNames,
+  type ResolvedProvisionNames,
+  provisionBaseline,
+} from './provision-baseline.ts';
+export { provisionBootstrap } from './provision-bootstrap.ts';
+export { type DeclareProvisionOptions, declareProvisionBaseline } from './provision-declare.ts';
 export { ProxmoxVmProvider } from './qemu.ts';
 export { ProxmoxReplicationJobProvider } from './replication-job.ts';
 export { ProxmoxRole, ProxmoxRoleProvider } from './role.ts';

package/src/proxmox/lease-cache.test.ts

@@ -17,13 +17,13 @@ import * as Exit from 'effect/Exit';
 import type { PveCredential } from './credentials.ts';
 import { type LeaseKey, makeLeases, timeToLive } from './lease-cache.ts';
 
-const TB4: LeaseKey = {
-  mount: 'proxmox-tb4',
+const C1: LeaseKey = {
+  mount: 'proxmox-c1',
   role: 'read',
   scheme: 'pve',
 };
-/** ⚠️ Same role as TB4, DIFFERENT mount — the collision the key has to survive. */
-const OPS: LeaseKey = { ...TB4, mount: 'proxmox-ops' };
+/** ⚠️ Same role as C1, DIFFERENT mount — the collision the key has to survive. */
+const C2: LeaseKey = { ...C1, mount: 'proxmox-c2' };
 
 const cred = (tokenId: string, leaseSeconds: number): PveCredential => ({
   leaseSeconds,
@@ -85,10 +85,10 @@ describe('lease cache under concurrency', () => {
     await Effect.runPromise(
       Effect.gen(function* () {
         const leases = yield* makeLeases(mint.mintFor);
-        const exits = yield* concurrently(20, Cache.get(leases, TB4));
+        const exits = yield* concurrently(20, Cache.get(leases, C1));
         assert.equal(exits.filter(Exit.isSuccess).length, 20);
         // An equal but separately built key is the same entry.
-        yield* Cache.get(leases, { ...TB4 });
+        yield* Cache.get(leases, { ...C1 });
       }),
     );
     assert.equal(mint.calls(), 1);
@@ -102,9 +102,9 @@ describe('lease cache under concurrency', () => {
     await Effect.runPromise(
       Effect.gen(function* () {
         const leases = yield* makeLeases(mint.mintFor);
-        const first = yield* concurrently(20, Cache.get(leases, TB4));
+        const first = yield* concurrently(20, Cache.get(leases, C1));
         assert.equal(first.filter(Exit.isFailure).length, 20, 'the waiters share the failure');
-        const second = yield* concurrently(20, Cache.get(leases, TB4));
+        const second = yield* concurrently(20, Cache.get(leases, C1));
         assert.equal(second.filter(Exit.isSuccess).length, 20);
       }),
     );
@@ -116,8 +116,8 @@ describe('lease cache under concurrency', () => {
     await Effect.runPromise(
       Effect.gen(function* () {
         const leases = yield* makeLeases(mint.mintFor);
-        yield* concurrently(20, Cache.get(leases, TB4));
-        yield* Cache.get(leases, TB4);
+        yield* concurrently(20, Cache.get(leases, C1));
+        yield* Cache.get(leases, C1);
       }),
     );
     assert.equal(mint.calls(), 2);
@@ -125,25 +125,25 @@ describe('lease cache under concurrency', () => {
 
   it('does not serve one cluster the credential of another with the same mount and role', async () => {
     const mint = countingMint((call) => cred(`hf-read@pve!${String(call)}`, 3600));
-    const [tb4, ops] = await Effect.runPromise(
+    const [c1, c2] = await Effect.runPromise(
       Effect.gen(function* () {
         const leases = yield* makeLeases(mint.mintFor);
-        return [yield* Cache.get(leases, TB4), yield* Cache.get(leases, OPS)] as const;
+        return [yield* Cache.get(leases, C1), yield* Cache.get(leases, C2)] as const;
       }),
     );
-    assert.notEqual(tb4.tokenId, ops.tokenId);
+    assert.notEqual(c1.tokenId, c2.tokenId);
     assert.equal(mint.calls(), 2);
   });
 
   it('shares one lease across two members of the same cluster mount', async () => {
     const mint = countingMint((call) => cred(`hf-read@pve!${String(call)}`, 3600));
-    const N2: LeaseKey = { mount: 'proxmox-tb4', role: 'read', scheme: 'pve' };
-    const N3: LeaseKey = { mount: 'proxmox-tb4', role: 'read', scheme: 'pve' };
+    const NODE_B: LeaseKey = { mount: 'proxmox-c1', role: 'read', scheme: 'pve' };
+    const NODE_C: LeaseKey = { mount: 'proxmox-c1', role: 'read', scheme: 'pve' };
     await Effect.runPromise(
       Effect.gen(function* () {
         const leases = yield* makeLeases(mint.mintFor);
-        yield* Cache.get(leases, N2);
-        yield* Cache.get(leases, N3);
+        yield* Cache.get(leases, NODE_B);
+        yield* Cache.get(leases, NODE_C);
       }),
     );
     assert.equal(mint.calls(), 1);
@@ -151,11 +151,11 @@ describe('lease cache under concurrency', () => {
 
   it('keeps read and provision apart', async () => {
     const mint = countingMint((call) => cred(`hf@pve!${String(call)}`, 3600));
-    const PROVISION: LeaseKey = { ...TB4, role: 'provision' };
+    const PROVISION: LeaseKey = { ...C1, role: 'provision' };
     const [read, provision] = await Effect.runPromise(
       Effect.gen(function* () {
         const leases = yield* makeLeases(mint.mintFor);
-        return [yield* Cache.get(leases, TB4), yield* Cache.get(leases, PROVISION)] as const;
+        return [yield* Cache.get(leases, C1), yield* Cache.get(leases, PROVISION)] as const;
       }),
     );
     assert.notEqual(read.tokenId, provision.tokenId);

package/src/proxmox/lease-cache.ts

@@ -1,8 +1,8 @@
 /**
  * One credential per (target, role) for the life of a run, instead of one per API call.
  *
- * 🔴 THE MEASUREMENT THAT MADE THIS NECESSARY. A single `alchemy plan` plus `deploy` of the TB4
- *   stack — 98 resources — left **760 API token entries in `/etc/pve/user.cfg`**, counted on n2
+ * 🔴 THE MEASUREMENT THAT MADE THIS NECESSARY. A single `alchemy plan` plus `deploy` of the C1
+ *   stack — 98 resources — left **760 API token entries in `/etc/pve/user.cfg`**, counted on node-b
  *   immediately afterwards. `mint()` asked OpenBao for a new credential on EVERY call, and each
  *   mint creates a real Proxmox token: read, diff, reconcile and read-back each got their own. They
  *   drain as the leases expire (760 down to 712 over five minutes), so nothing was broken — but
@@ -66,9 +66,9 @@ const REMINT_MARGIN_SECONDS = 60;
  * What a credential is cached under.
  *
  * ⛔ KEYED ON THE OPENBAO MOUNT AND ROLE, NOT ON A MEMBER HOSTNAME. A PVE API token is
- *   cluster-wide — `user.cfg` is replicated — so n2, n3 and n4 share one credential. Keying on
+ *   cluster-wide — `user.cfg` is replicated — so node-b, node-c and node-d share one credential. Keying on
  *   `api` would mint three identical tokens when failover rotates members.
- * ★ THE MOUNT CANNOT COLLIDE ACROSS CLUSTERS: `proxmox-tb4`, `proxmox-ops` and `pbs-tb4` are
+ * ★ THE MOUNT CANNOT COLLIDE ACROSS CLUSTERS: `proxmox-c1`, `proxmox-c2` and `pbs-c1` are
  *   distinct OpenBao mounts with distinct policies; two estates never share a mount name.
  * ★ A PLAIN OBJECT IS A SAFE KEY BECAUSE EFFECT COMPARES KEYS STRUCTURALLY — two separately built
  *   literals with the same fields are one entry, which the probe above measured.

package/src/proxmox/lxc-adopt.test.ts

@@ -4,28 +4,20 @@
  *
  * ⛔ WHAT THESE PIN: a declaration pasted from the live config plans `adopted` with no warning,
  *   its deploy writes NOTHING, and the next plan is `noop`; the create spellings (`storage:size`,
- *   a NIC without its MAC) adopt as cleanly; drift is named at plan and written as one PUT that
- *   keeps the live MAC and carries the digest; and every change PVE cannot make in place fails the
- *   plan with nothing written. Deleting both empty-change guards (reconcile's in lxc.ts and
- *   `updateGuest`'s in lxc-lifecycle.ts), or the hwaddr carry in lxc-wire.ts, fails a test here —
- *   each MEASURED by making that edit and running this file, 2026-09-21.
+ *   a NIC without its MAC) adopt as cleanly; after that adoption, drift is named at plan and
+ *   written as one PUT that keeps the live MAC and carries the digest; and every change PVE cannot
+ *   make in place fails the plan with nothing written. Deleting both empty-change guards
+ *   (reconcile's in lxc.ts and `updateGuest`'s in lxc-lifecycle.ts), or the hwaddr carry in
+ *   lxc-wire.ts, fails a test here — each MEASURED by making that edit and running this file,
+ *   2026-09-21. An adoption that WOULD write fails instead: lxc-strict-adopt.test.ts.
  */
 import { afterEach, describe, expect, test } from 'bun:test';
 import { adopt } from 'alchemy/AdoptPolicy';
 import { type FakePve, fakePve, writesOf } from './fake-pve-lxc.ts';
-import { LIVE, TARGET, lxcEngine, seed } from './lxc-harness.ts';
+import { NODE, TARGET, VMID, adoptedAsIs, lxcEngine, pasted, seed } from './lxc-harness.ts';
 import { ProxmoxLxc } from './lxc.ts';
 import type { LxcProps } from './lxc-props.ts';
 
-const NODE = 'pve1';
-const VMID = 100;
-
-/** The live config as a declaration: every key, minus what pvesh adds that is not a prop. */
-const pasted = (): LxcProps => {
-  const { lxc: _raw, ...config } = LIVE;
-  return { ...(config as Partial<LxcProps>), node: NODE, target: TARGET, vmid: VMID };
-};
-
 const ct = (props: LxcProps) => ProxmoxLxc('ct', props).pipe(adopt(true));
 
 let fake: FakePve | undefined;
@@ -84,17 +76,17 @@ describe('adopting a live container', () => {
   });
 });
 
-describe('drift at adoption is named at plan and written once', () => {
+describe('drift after the adoption is named at plan and written once', () => {
   test('memory and an MTU change: one PUT, the live MAC kept, the digest carried', async () => {
     const pve = live();
-    const stack = lxcEngine(pve);
+    const stack = await adoptedAsIs(pve);
     const props: LxcProps = {
       ...pasted(),
       memory: 4096,
       net1: 'name=eth1,bridge=vmbr1,ip=198.51.100.4/24,mtu=9000',
     };
     const planned = await stack.plan(ct(props));
-    expect(planned.actions).toEqual({ ct: 'adopted' });
+    expect(planned.actions).toEqual({ ct: 'update' });
     expect(planned.warnings.join('\n')).toContain('differs from the declaration in memory, net1');
     expect((await stack.deploy(ct(props))).failure).toBe('');
     expect(writesOf(pve)).toEqual([`PUT nodes/${NODE}/lxc/${String(VMID)}/config`]);
@@ -107,8 +99,8 @@ describe('drift at adoption is named at plan and written once', () => {
 
   test('a larger rootfs is a resize after the config, never a new volume', async () => {
     const pve = live();
-    const stack = lxcEngine(pve);
-    const props: LxcProps = { ...pasted(), rootfs: 'local-zfs:subvol-100-disk-0,size=64G' };
+    const stack = await adoptedAsIs(pve);
+    const props: LxcProps = { ...pasted(), rootfs: 'local-zfs:subvol-900-disk-0,size=64G' };
     expect((await stack.deploy(ct(props))).failure).toBe('');
     expect(writesOf(pve)).toEqual([`PUT nodes/${NODE}/lxc/${String(VMID)}/resize`]);
     expect(pve.guests.get(`${NODE}/${String(VMID)}`)?.['rootfs']).toContain('size=64G');
@@ -117,15 +109,16 @@ describe('drift at adoption is named at plan and written once', () => {
 
 describe('changes PVE cannot make in place fail the plan and write nothing', () => {
   test.each([
-    ['a smaller mount point', { mp0: 'tank:subvol-100-disk-0,mp=/data,size=100G' }, /shrink/],
+    ['a smaller mount point', { mp0: 'tank:subvol-900-disk-0,mp=/data,size=100G' }, /shrink/],
     ['a storage move', { rootfs: 'other:40' }, /pct move-volume/],
     ['an unprivileged flip', { unprivileged: 0 as const }, /read-only option/],
-    ['a device passthrough change', { dev1: '/dev/fuse' }, /pct set 100 --dev1/],
+    ['a device passthrough change', { dev1: '/dev/fuse' }, /pct set 900 --dev1/],
     ['a feature beyond nesting', { features: 'nesting=1,keyctl=1' }, /root@pam/],
     ['detaching a mount point', { mp0: '' }, /unusedN/],
   ])('%s', async (_, change, reason) => {
     const pve = live();
-    const run = await lxcEngine(pve).deploy(ct({ ...pasted(), ...change } as LxcProps));
+    const stack = await adoptedAsIs(pve);
+    const run = await stack.deploy(ct({ ...pasted(), ...change } as LxcProps));
     expect(run.failure).toMatch(reason);
     expect(writesOf(pve)).toEqual([]);
   });

package/src/proxmox/lxc-adoption.ts

@@ -0,0 +1,50 @@
+/**
+ * The strict adoption gate for `Proxmox.Lxc`: AN ADOPTION NEVER CHANGES A GUEST (decided
+ * 2026-09-21). A guest this stack adopts — no recorded instance, or one the plan only kept because
+ * `--adopt` said so (ownership/adopting.ts) — is taken over exactly as it runs, or not at all.
+ *
+ * ⛔ ANY DIFFERENCE FAILS, AT PLAN AND AGAIN AT APPLY. Before this, a cold adoption planned `adopted`
+ *   whatever it would write (alchemy beta.79 prints no property diff for it) and only LOGGED the
+ *   keys; `deploy --adopt --yes` then wrote them. A `net0` pasted without the live `tag=` moved the
+ *   guest off its VLAN on the deploy that was meant to change nothing. Now the plan fails naming
+ *   the keys, and reconcile re-asks against a fresh read, so a hand edit between plan and deploy
+ *   is refused too rather than written back.
+ * ⛔ KEYS ONLY, NEVER VALUES. The refusal names what differs and nothing it differs by: a live
+ *   config can carry anything (`description` is where people paste credentials), and plan output
+ *   lands in CI logs.
+ * ★ ASKED BEFORE `judge`'s OWN REFUSALS. Those name a declared value (the `pct set` to run), and
+ *   for an adoption the fix is the other direction: declare what is live.
+ * ★ THE STORE IS READ ONLY WHEN SOMETHING DIFFERS. A clean adoption — the only kind that proceeds
+ *   — costs nothing here.
+ */
+import * as Effect from 'effect/Effect';
+import type { Owner } from '../ownership/adopt.ts';
+import { adopting } from '../ownership/adopting.ts';
+import { type LxcChange, judge } from './lxc-judge.ts';
+import { LxcRefusedError } from './lxc-lifecycle.ts';
+import type { LxcProps } from './lxc-props.ts';
+
+/** The refusal: keys, where, and what to do — never a value. */
+export const adoptionRefusal = (props: LxcProps, drift: readonly string[]): string =>
+  `CT ${String(props.vmid)} on ${props.node}: adopting it would change ${drift.join(', ')}. An ` +
+  'adoption never changes a guest, so nothing is written. Declare what is live for these keys ' +
+  '(the plan names keys, never values) and plan again; change them after the adoption, as an ' +
+  'update.';
+
+/**
+ * Fails with `adoptionRefusal` when `change` would write to a guest `owner`'s call adopts.
+ * `settled` for a recovered create is the same judge, of the recording row's props against `live`.
+ */
+export const refuseAdoptedDrift = (
+  owner: Owner,
+  props: LxcProps,
+  live: Record<string, unknown>,
+  change: LxcChange,
+): Effect.Effect<void, LxcRefusedError> =>
+  Effect.gen(function* () {
+    if (change.drift.length === 0) return;
+    const settled = (recorded: unknown) =>
+      Effect.sync(() => judge(recorded as LxcProps, live).drift.length === 0);
+    if (!(yield* adopting(owner, settled))) return;
+    return yield* Effect.fail(new LxcRefusedError(adoptionRefusal(props, change.drift)));
+  });

package/src/proxmox/lxc-create-form.ts

@@ -23,7 +23,7 @@ import { bool } from './values.ts';
 /**
  * ⛔ A CREATE ALLOCATES NEW VOLUMES ONLY. pve-container's `create_disks` allocates `storage:GiB`
  *   and takes anything else as "use specified/existing volid", then `restore_archive` unpacks the
- *   template into the mounted rootfs. So a create naming `local-zfs:subvol-100-disk-0` — a pasted
+ *   template into the mounted rootfs. So a create naming `local-zfs:subvol-900-disk-0` — a pasted
  *   adoption, re-created after its config vanished while the volume survived (a `pct destroy`
  *   only WARNS when a volume will not delete) — unpacks a template over the data on it.
  */

package/src/proxmox/lxc-guards.test.ts

@@ -11,19 +11,12 @@
 import { afterEach, describe, expect, test } from 'bun:test';
 import { adopt } from 'alchemy/AdoptPolicy';
 import { type FakePve, fakePve, writesOf } from './fake-pve-lxc.ts';
-import { LIVE, TARGET, lxcEngine, seed } from './lxc-harness.ts';
+import { KEY, NODE, TARGET, VMID, adoptedAsIs, lxcEngine, pasted, seed } from './lxc-harness.ts';
 import { ProxmoxLxc } from './lxc.ts';
 import type { LxcProps } from './lxc-props.ts';
 
-const NODE = 'pve1';
-const VMID = 100;
-const KEY = `${NODE}/${String(VMID)}`;
 const TEMPLATE = 'local:vztmpl/debian-13-standard_13.1-2_amd64.tar.zst';
-
-const pasted = (over: Partial<LxcProps> = {}): LxcProps => {
-  const { lxc: _raw, ...config } = LIVE;
-  return { ...(config as Partial<LxcProps>), node: NODE, target: TARGET, vmid: VMID, ...over };
-};
+const ct = (props: LxcProps) => ProxmoxLxc('ct', props).pipe(adopt(true));
 
 let fake: FakePve | undefined;
 afterEach(() => {
@@ -70,8 +63,8 @@ describe('a guest the cluster no longer lists, with state still held', () => {
     expect((await stack.deploy(declared())).failure).toBe('');
     pve.guests.delete(KEY);
     const run = await stack.deploy(declared());
-    expect(run.failure).toContain('rootfs: local-zfs:subvol-100-disk-0,size=40G names an existing');
-    expect(run.failure).toContain('mp0: tank:subvol-100-disk-0');
+    expect(run.failure).toContain('rootfs: local-zfs:subvol-900-disk-0,size=40G names an existing');
+    expect(run.failure).toContain('mp0: tank:subvol-900-disk-0');
     expect(writesOf(pve)).toEqual([]);
   });
 
@@ -113,10 +106,9 @@ describe('a write is claimed only when PVE says it finished', () => {
   test('a config write PVE accepted but did not store fails the read-back', async () => {
     const pve = cluster();
     seed(pve, NODE, VMID);
+    const stack = await adoptedAsIs(pve);
     pve.ignore.add('memory');
-    const run = await lxcEngine(pve).deploy(
-      ProxmoxLxc('ct', pasted({ memory: 4096 })).pipe(adopt(true)),
-    );
+    const run = await stack.deploy(ct(pasted({ memory: 4096 })));
     expect(run.failure).toContain('memory still differ');
   });
 });
@@ -137,13 +129,14 @@ describe('identity and volumes', () => {
   test('options and growth on one volume: the PUT keeps the live size, the resize follows', async () => {
     const pve = cluster();
     seed(pve, NODE, VMID);
-    const mp0 = 'tank:subvol-100-disk-0,mp=/data,backup=1,size=300G';
-    const run = await lxcEngine(pve).deploy(ProxmoxLxc('ct', pasted({ mp0 })).pipe(adopt(true)));
+    const stack = await adoptedAsIs(pve);
+    const mp0 = 'tank:subvol-900-disk-0,mp=/data,backup=1,size=300G';
+    const run = await stack.deploy(ct(pasted({ mp0 })));
     expect(run.failure).toBe('');
     const path = `nodes/${NODE}/lxc/${String(VMID)}`;
     expect(writesOf(pve)).toEqual([`PUT ${path}/config`, `PUT ${path}/resize`]);
     const put = pve.seen.find((call) => call.path.endsWith('/config') && call.method === 'PUT');
-    expect(put?.form.get('mp0')).toBe('tank:subvol-100-disk-0,mp=/data,backup=1,size=200G');
+    expect(put?.form.get('mp0')).toBe('tank:subvol-900-disk-0,mp=/data,backup=1,size=200G');
     expect(pve.guests.get(KEY)?.['mp0']).toContain('size=300G');
   });
 

package/src/proxmox/lxc-harness.ts

@@ -13,7 +13,7 @@
  * ★ ONE ARTIFACT STORE ACROSS A PLAN AND ITS APPLY, and `--adopt` as the AdoptPolicy service, as
  *   openbao/fake-stack.ts provides them: the ownership rule reads both (src/ownership/).
  */
-import { AdoptPolicy } from 'alchemy/AdoptPolicy';
+import { AdoptPolicy, adopt } from 'alchemy/AdoptPolicy';
 import { apply } from 'alchemy/Apply';
 import { provideFreshArtifactStore } from 'alchemy/Artifacts';
 import * as Plan from 'alchemy/Plan';
@@ -29,7 +29,8 @@ import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
 import type { PveTarget } from './credentials.ts';
 import { withFakeBao } from './fake-bao-env.ts';
 import { FAKE_BAO, FAKE_MEMBER, type FakePve } from './fake-pve-lxc.ts';
-import { ProxmoxLxcProvider } from './lxc.ts';
+import type { LxcProps } from './lxc-props.ts';
+import { ProxmoxLxc, ProxmoxLxcProvider } from './lxc.ts';
 
 export const TARGET: PveTarget = {
   members: [FAKE_MEMBER],
@@ -53,7 +54,7 @@ export const LIVE: Readonly<Record<string, unknown>> = {
   hostname: 'ct-example',
   lxc: [['lxc.prlimit.memlock', 'unlimited']],
   memory: 8192,
-  mp0: 'tank:subvol-100-disk-0,mp=/data,backup=0,size=200G',
+  mp0: 'tank:subvol-900-disk-0,mp=/data,backup=0,size=200G',
   nameserver: '192.0.2.254',
   net0:
     'name=eth0,bridge=vmbr0,firewall=0,gw=192.0.2.1,hwaddr=00:00:5E:00:53:01,' +
@@ -61,13 +62,24 @@ export const LIVE: Readonly<Record<string, unknown>> = {
   net1: 'name=eth1,bridge=vmbr1,hwaddr=00:00:5E:00:53:02,ip=198.51.100.4/24,mtu=1500,type=veth',
   onboot: 1,
   ostype: 'debian',
-  rootfs: 'local-zfs:subvol-100-disk-0,size=40G',
+  rootfs: 'local-zfs:subvol-900-disk-0,size=40G',
   searchdomain: 'example.com',
   swap: 0,
   tags: 'web',
   unprivileged: 1,
 };
 
+/** Where `seed` puts the production-shaped guest by default, and its `node/vmid` key. */
+export const NODE = 'pve1';
+export const VMID = 900;
+export const KEY = `${NODE}/${String(VMID)}`;
+
+/** The live config as a declaration: every key, minus what pvesh adds that is not a prop. */
+export const pasted = (over: Partial<LxcProps> = {}): LxcProps => {
+  const { lxc: _raw, ...config } = LIVE;
+  return { ...(config as Partial<LxcProps>), node: NODE, target: TARGET, vmid: VMID, ...over };
+};
+
 /** Put `config` live on the fake as `node/vmid`, with a digest as PVE would add. */
 export const seed = (fake: FakePve, node: string, vmid: number, config = LIVE) => {
   fake.guests.set(`${node}/${String(vmid)}`, { ...config, digest: 'digest-live' });
@@ -148,3 +160,14 @@ export const lxcEngine = (fake: FakePve) => {
     status: (fqn: string) => rows['lxc']?.['test']?.[fqn]?.status,
   };
 };
+
+/**
+ * The engine, with the guest `seed` put at NODE/VMID adopted exactly as it runs — the only adoption
+ * that proceeds (lxc-adoption.ts) — so a test can go on to change it, as an ordinary update.
+ */
+export const adoptedAsIs = async (pve: FakePve): Promise<ReturnType<typeof lxcEngine>> => {
+  const stack = lxcEngine(pve);
+  const run = await stack.deploy(ProxmoxLxc('ct', pasted()).pipe(adopt(true)));
+  if (run.failure !== '') throw new Error(`the clean adoption failed: ${run.failure}`);
+  return stack;
+};