@homeflare/alchemy 0.8.0 → 0.10.1

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

@@ -0,0 +1,170 @@
+/**
+ * The adoption gate, through Alchemy's real plan and apply over a fake PVE holding a
+ * production-shaped guest (placeholders only).
+ *
+ * ⛔ 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.
+ */
+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 { 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;
+afterEach(() => {
+  fake?.stop();
+  fake = undefined;
+});
+const live = () => {
+  fake = fakePve();
+  seed(fake, NODE, VMID);
+  return fake;
+};
+
+describe('adopting a live container', () => {
+  test('the pasted config plans adopted, deploys with no write, and then plans noop', async () => {
+    const pve = live();
+    const stack = lxcEngine(pve);
+    const first = await stack.plan(ct(pasted()));
+    expect(first).toEqual({ actions: { ct: 'adopted' }, failure: '', warnings: [] });
+    const deployed = await stack.deploy(ct(pasted()));
+    expect(deployed.failure).toBe('');
+    expect(writesOf(pve)).toEqual([]);
+    expect(stack.status('ct')).toBe('updated');
+    expect(await stack.plan(ct(pasted()))).toEqual({
+      actions: { ct: 'noop' },
+      failure: '',
+      warnings: [],
+    });
+  });
+
+  test('create spellings and PVE defaults compare equal to the live config', async () => {
+    const stack = lxcEngine(live());
+    const props: LxcProps = {
+      ...pasted(),
+      mp0: 'tank:200,mp=/data',
+      net0: 'bridge=vmbr0,name=eth0,gw=192.0.2.1,ip=192.0.2.10/24,mtu=1500,tag=42',
+      net1: 'name=eth1,bridge=vmbr1,ip=198.51.100.4/24,mtu=1500,firewall=0',
+      onboot: true,
+      rootfs: 'local-zfs:40',
+      tags: 'WEB',
+      unprivileged: true,
+    };
+    expect(await stack.plan(ct(props))).toEqual({
+      actions: { ct: 'adopted' },
+      failure: '',
+      warnings: [],
+    });
+  });
+
+  test('a declaration naming only node and vmid adopts without touching anything', async () => {
+    const pve = live();
+    const stack = lxcEngine(pve);
+    const deployed = await stack.deploy(ct({ node: NODE, target: TARGET, vmid: VMID }));
+    expect(deployed.failure).toBe('');
+    expect(writesOf(pve)).toEqual([]);
+  });
+});
+
+describe('drift at 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 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.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`]);
+    const put = pve.seen.find((call) => call.method === 'PUT')?.form;
+    expect(put?.get('memory')).toBe('4096');
+    expect(put?.get('net1')).toContain('hwaddr=00:00:5E:00:53:02');
+    expect(put?.get('digest')).toBe('digest-live');
+    expect((await stack.plan(ct(props))).actions).toEqual({ ct: 'noop' });
+  });
+
+  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' };
+    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');
+  });
+});
+
+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 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 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));
+    expect(run.failure).toMatch(reason);
+    expect(writesOf(pve)).toEqual([]);
+  });
+
+  test('a vmid held elsewhere in the cluster fails the plan instead of planning a create', async () => {
+    const pve = live();
+    pve.others.push({ node: 'pve2', type: 'qemu', vmid: 101 });
+    const run = await lxcEngine(pve).plan(ct({ ...pasted(), vmid: 101 }));
+    expect(run.failure).toContain('vmid 101 is a qemu on pve2');
+    expect(writesOf(pve)).toEqual([]);
+  });
+});
+
+describe('a guest another tool moved', () => {
+  const migrate = (pve: FakePve, to: string) => {
+    const config = pve.guests.get(`${NODE}/${String(VMID)}`) ?? {};
+    pve.guests.delete(`${NODE}/${String(VMID)}`);
+    pve.guests.set(`${to}/${String(VMID)}`, config);
+  };
+
+  test('after HA moves it, the old node fails the plan; the new node is a write-free update', async () => {
+    const pve = live();
+    const stack = lxcEngine(pve);
+    await stack.deploy(ct(pasted()));
+    migrate(pve, 'pve2');
+    expect((await stack.plan(ct(pasted()))).failure).toContain('is a lxc on pve2');
+    const follow = await stack.deploy(ct({ ...pasted(), node: 'pve2' }));
+    expect(follow.actions).toEqual({ ct: 'update' });
+    expect(follow.warnings.join('\n')).toContain('on pve2 now, not pve1');
+    expect(writesOf(pve)).toEqual([]);
+    expect((await stack.plan(ct({ ...pasted(), node: 'pve2' }))).actions).toEqual({ ct: 'noop' });
+  });
+
+  test('naming another node the guest is not on is refused, never a second guest', async () => {
+    const pve = live();
+    const stack = lxcEngine(pve);
+    await stack.deploy(ct(pasted()));
+    const run = await stack.deploy(ct({ ...pasted(), node: 'pve2' }));
+    expect(run.failure).toContain('is a lxc on pve1, not a container on pve2');
+    expect(writesOf(pve)).toEqual([]);
+  });
+});

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

@@ -0,0 +1,76 @@
+/**
+ * Creating a container: what an API token may create, and the body it POSTs.
+ *
+ * ★ SPLIT FROM lxc-judge.ts AT A REAL SEAM: the judge compares a declaration with a guest that
+ *   exists; this file answers for a guest that does not, where there is nothing to compare with
+ *   and the only safe answer to a doubtful key is to refuse it before the POST.
+ * ⛔ THE ROOT@PAM RULES ARE THE JUDGE'S OWN (`rootOnly`, `featuresNeedRoot`), imported rather than
+ *   restated, so the create and the update cannot disagree about what a token may write.
+ */
+import { featureWhy, featuresNeedRoot, rootOnly } from './lxc-judge.ts';
+import {
+  type LxcProps,
+  declaredKeys,
+  declaredValue,
+  indexedKey,
+  isManagedKey,
+  wireValue,
+} from './lxc-props.ts';
+import { isHostPath, parseVolume } from './lxc-volume.ts';
+import { scalarForm } from './lxc-wire.ts';
+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
+ *   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.
+ */
+const existingVolume = (key: string, value: string) =>
+  `${key}: ${value} names an existing volume, and PVE would unpack the template onto it. A ` +
+  'create allocates new volumes only: declare `storage:GiB`, and attach an existing volume by ' +
+  'hand after the create.';
+
+/** Why this declaration cannot be CREATED by an API token, if it cannot. */
+export const createRefusals = (props: LxcProps): string[] => {
+  const refuse: string[] = [];
+  if (props.ostemplate === undefined || props.ostemplate === '') {
+    refuse.push(
+      `CT ${String(props.vmid)} does not exist on ${props.node}, and without \`ostemplate\` ` +
+        'there is nothing to create it from. To adopt a guest, declare the node it is on.',
+    );
+  }
+  const unprivileged = props.unprivileged === undefined ? true : bool(props.unprivileged);
+  for (const key of declaredKeys(props)) {
+    const value = wireValue(declaredValue(props, key));
+    const family = indexedKey(key)?.[0];
+    // ⛔ THE SAME RULE AS `judge`: createForm sends every declared key, so an unmanaged one (a
+    //   cast-in `password`, `restore`/`force`, `hookscript`) is refused here or it is POSTed.
+    if (!isManagedKey(key)) refuse.push(`${key}: not a config key this resource manages.`);
+    if (value === '') continue;
+    if (family === 'dev') refuse.push(rootOnly(props.vmid, key, value, 'Device passthrough.'));
+    const volume = family === 'mp' || key === 'rootfs' ? parseVolume(value) : undefined;
+    if (volume !== undefined && isHostPath(volume)) {
+      refuse.push(rootOnly(props.vmid, key, value, 'A bind or device mount point.'));
+    }
+    if (volume?.kind === 'volume') refuse.push(existingVolume(key, value));
+    if (key === 'features' && featuresNeedRoot('', value, unprivileged)) {
+      refuse.push(rootOnly(props.vmid, key, value, featureWhy(unprivileged)));
+    }
+  }
+  return refuse;
+};
+
+/** The create body: every declared key with a value, plus the create-time instructions. */
+export const createForm = (props: LxcProps): Record<string, string> => {
+  const form: Record<string, string> = { vmid: String(props.vmid) };
+  if (props.ostemplate !== undefined) form['ostemplate'] = props.ostemplate;
+  if (props.start !== undefined) form['start'] = wireValue(props.start);
+  for (const key of declaredKeys(props)) {
+    const value = wireValue(declaredValue(props, key));
+    if (value === '') continue;
+    form[key] = key === 'features' ? scalarForm(key, value) : value;
+  }
+  return form;
+};

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

@@ -0,0 +1,126 @@
+/**
+ * Declaring a NEW container, and removing one, through the real engine over fake-pve-lxc.ts.
+ *
+ * ⛔ WHAT THESE PIN: a create POSTs once, waits for its task, reads back what PVE allocated and
+ *   then plans `noop` against it; a create an API token cannot finish (no template, device
+ *   passthrough, a bind mount) fails before any write; dropping the declaration retains the guest;
+ *   and only `RemovalPolicy.destroy()` sends the DELETE.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as Effect from 'effect/Effect';
+import { type FakePve, fakePve, writesOf } from './fake-pve-lxc.ts';
+import { TARGET, lxcEngine } from './lxc-harness.ts';
+import { ProxmoxLxc } from './lxc.ts';
+import type { LxcProps } from './lxc-props.ts';
+
+const NODE = 'pve1';
+const VMID = 150;
+
+const door = (over: Partial<LxcProps> = {}): LxcProps => ({
+  cores: 1,
+  features: 'nesting=1',
+  hostname: 'door-example',
+  memory: 512,
+  net0: 'name=eth0,bridge=vmbr0,ip=192.0.2.20/24,gw=192.0.2.1',
+  node: NODE,
+  onboot: 1,
+  ostemplate: 'local:vztmpl/debian-13-standard_13.1-2_amd64.tar.zst',
+  rootfs: 'local-zfs:8',
+  start: 1,
+  tags: 'Vault;door',
+  target: TARGET,
+  vmid: VMID,
+  ...over,
+});
+
+let fake: FakePve | undefined;
+afterEach(() => {
+  fake?.stop();
+  fake = undefined;
+});
+const empty = () => {
+  fake = fakePve();
+  return fake;
+};
+
+describe('creating a container', () => {
+  test('one POST, then the next plan is noop against what PVE allocated', async () => {
+    const pve = empty();
+    const stack = lxcEngine(pve);
+    const created = await stack.deploy(ProxmoxLxc('door', door()));
+    expect(created.actions).toEqual({ door: 'create' });
+    expect(created.failure).toBe('');
+    expect(writesOf(pve)).toEqual([`POST nodes/${NODE}/lxc`]);
+    const post = pve.seen.find((call) => call.method === 'POST')?.form;
+    expect(post?.get('rootfs')).toBe('local-zfs:8');
+    expect(post?.get('start')).toBe('1');
+    expect(post?.get('password')).toBeNull();
+    const live = pve.guests.get(`${NODE}/${String(VMID)}`);
+    expect(live?.['rootfs']).toBe(`local-zfs:subvol-${String(VMID)}-disk-0,size=8G`);
+    expect(live?.['net0']).toContain('hwaddr=');
+    expect((await stack.plan(ProxmoxLxc('door', door()))).actions).toEqual({ door: 'noop' });
+  });
+
+  test.each([
+    ['no template', { ostemplate: '' }, /nothing to create it from/],
+    ['device passthrough', { dev0: '/dev/net/tun' }, /pct set 150 --dev0/],
+    ['a bind mount', { mp0: '/srv/share,mp=/share' }, /bind or device mount point/],
+    ['a feature beyond nesting', { features: 'nesting=1,keyctl=1' }, /other than nesting/],
+  ])('refused before any write: %s', async (_, over, reason) => {
+    const pve = empty();
+    const run = await lxcEngine(pve).deploy(ProxmoxLxc('door', door(over as Partial<LxcProps>)));
+    expect(run.failure).toMatch(reason);
+    expect(writesOf(pve)).toEqual([]);
+  });
+});
+
+describe('removing a container', () => {
+  test('retain is the default: dropping the declaration sends no DELETE', async () => {
+    const pve = empty();
+    const stack = lxcEngine(pve);
+    await stack.deploy(ProxmoxLxc('door', door()));
+    expect((await stack.deploy(Effect.void)).failure).toBe('');
+    expect(stack.status('door')).toBeUndefined();
+    expect(pve.guests.has(`${NODE}/${String(VMID)}`)).toBe(true);
+    expect(writesOf(pve)).toEqual([`POST nodes/${NODE}/lxc`]);
+  });
+
+  test('RemovalPolicy.destroy() reaches the DELETE, and waits for its task', async () => {
+    const pve = empty();
+    const stack = lxcEngine(pve);
+    await stack.deploy(ProxmoxLxc('door', door()).pipe(RemovalPolicy.destroy()));
+    expect((await stack.deploy(Effect.void)).failure).toBe('');
+    expect(pve.guests.has(`${NODE}/${String(VMID)}`)).toBe(false);
+    expect(writesOf(pve)).toEqual([
+      `POST nodes/${NODE}/lxc`,
+      `DELETE nodes/${NODE}/lxc/${String(VMID)}`,
+    ]);
+    expect(pve.seen.some((call) => /\/tasks\/UPID:.*vzdestroy/.test(call.path))).toBe(true);
+    // ⛔ No `force` (stops a running guest), `purge` (drops it from HA and backup jobs) or
+    //   `destroy-unreferenced-disks` (deletes volumes the config does not even name).
+    const del = pve.seen.find((call) => call.method === 'DELETE');
+    expect(del?.form.toString()).toBe('');
+  });
+
+  test('destroy() refuses a guest that no longer matches: the vmid may be somebody else’s', async () => {
+    const pve = empty();
+    const stack = lxcEngine(pve);
+    await stack.deploy(ProxmoxLxc('door', door()).pipe(RemovalPolicy.destroy()));
+    const live = pve.guests.get(`${NODE}/${String(VMID)}`) ?? {};
+    live['hostname'] = 'someone-else';
+    const run = await stack.deploy(Effect.void);
+    expect(run.failure).toContain('no longer matches its last declaration (hostname)');
+    expect(pve.guests.has(`${NODE}/${String(VMID)}`)).toBe(true);
+    expect(writesOf(pve)).toEqual([`POST nodes/${NODE}/lxc`]);
+  });
+
+  test('a changed vmid is refused, never a second guest', async () => {
+    const pve = empty();
+    const stack = lxcEngine(pve);
+    await stack.deploy(ProxmoxLxc('door', door()));
+    const run = await stack.plan(ProxmoxLxc('door', door({ vmid: VMID + 1 })));
+    expect(run.failure).toContain('is a different guest');
+    expect(writesOf(pve)).toEqual([`POST nodes/${NODE}/lxc`]);
+  });
+});

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

@@ -0,0 +1,158 @@
+/**
+ * The guards an adversarial review found untested or missing, through the real engine over
+ * fake-pve-lxc.ts: each test here failed against a mutant of the guard it names (2026-09-21).
+ *
+ * ⛔ WHAT THESE PIN: a guest the cluster lost is named at plan before a deploy rebuilds it; a task
+ *   that fails, or answers no UPID, is a failed deploy; a write PVE accepted but did not store is
+ *   caught by the read-back; a new template is refused; an options change on a volume that also
+ *   grows keeps the live size in the PUT and resizes after it; and a vmid PVE spells as a string
+ *   is still "listed". Whose guest it is: lxc-ownership.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 { 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 };
+};
+
+let fake: FakePve | undefined;
+afterEach(() => {
+  fake?.stop();
+  fake = undefined;
+});
+const cluster = () => {
+  fake = fakePve();
+  return fake;
+};
+
+describe('a guest the cluster no longer lists, with state still held', () => {
+  test('with a template: the plan warns it will be created again, and the deploy does', async () => {
+    const pve = cluster();
+    seed(pve, NODE, VMID);
+    const stack = lxcEngine(pve);
+    // ⚠️ Without the devices (a token cannot create passthrough), and with the NEW-disk
+    //   spellings, which compare equal to the live volumes but can only allocate fresh ones.
+    const rebuildable = pasted({
+      dev0: undefined,
+      dev1: undefined,
+      mp0: 'tank:200,mp=/data',
+      ostemplate: TEMPLATE,
+      rootfs: 'local-zfs:40',
+    });
+    const declared = () => ProxmoxLxc('ct', rebuildable).pipe(adopt(true));
+    expect((await stack.deploy(declared())).failure).toBe('');
+    pve.guests.delete(KEY);
+    const planned = await stack.plan(declared());
+    expect(planned.actions).toEqual({ ct: 'update' });
+    expect(planned.warnings.join('\n')).toContain('CREATES it again from ostemplate');
+    expect((await stack.deploy(declared())).failure).toBe('');
+    expect(writesOf(pve)).toEqual([`POST nodes/${NODE}/lxc`]);
+  });
+
+  test('declared by live volume ids: refused, never a template unpacked onto them', async () => {
+    const pve = cluster();
+    seed(pve, NODE, VMID);
+    const stack = lxcEngine(pve);
+    const declared = () =>
+      ProxmoxLxc('ct', pasted({ dev0: undefined, dev1: undefined, ostemplate: TEMPLATE })).pipe(
+        adopt(true),
+      );
+    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(writesOf(pve)).toEqual([]);
+  });
+
+  test('without one: the plan fails, rather than planning an update the deploy cannot make', async () => {
+    const pve = cluster();
+    seed(pve, NODE, VMID);
+    const stack = lxcEngine(pve);
+    expect((await stack.deploy(ProxmoxLxc('ct', pasted()).pipe(adopt(true)))).failure).toBe('');
+    pve.guests.delete(KEY);
+    expect((await stack.plan(ProxmoxLxc('ct', pasted()))).failure).toContain(
+      'nothing to create it from',
+    );
+  });
+});
+
+describe('a write is claimed only when PVE says it finished', () => {
+  const door = () =>
+    ProxmoxLxc('door', {
+      node: NODE,
+      ostemplate: TEMPLATE,
+      rootfs: 'local-zfs:8',
+      target: TARGET,
+      vmid: 150,
+    });
+
+  test('a create task that ends in an error fails the deploy, naming the task', async () => {
+    const pve = cluster();
+    pve.task.exit = 'unable to create CT 150 - command failed';
+    const run = await lxcEngine(pve).deploy(door());
+    expect(run.failure).toContain('ended "unable to create CT 150 - command failed"');
+  });
+
+  test('a create answered with no UPID fails the deploy', async () => {
+    const pve = cluster();
+    pve.task.noUpid = true;
+    expect((await lxcEngine(pve).deploy(door())).failure).toContain('returned no task id');
+  });
+
+  test('a config write PVE accepted but did not store fails the read-back', async () => {
+    const pve = cluster();
+    seed(pve, NODE, VMID);
+    pve.ignore.add('memory');
+    const run = await lxcEngine(pve).deploy(
+      ProxmoxLxc('ct', pasted({ memory: 4096 })).pipe(adopt(true)),
+    );
+    expect(run.failure).toContain('memory still differ');
+  });
+});
+
+describe('identity and volumes', () => {
+  test('another template for a guest that exists is refused at plan', async () => {
+    const pve = cluster();
+    seed(pve, NODE, VMID);
+    const stack = lxcEngine(pve);
+    await stack.deploy(ProxmoxLxc('ct', pasted({ ostemplate: TEMPLATE })).pipe(adopt(true)));
+    const run = await stack.plan(
+      ProxmoxLxc('ct', pasted({ ostemplate: 'local:vztmpl/other.tar.zst' })),
+    );
+    expect(run.failure).toContain('a template is consumed at create');
+    expect(writesOf(pve)).toEqual([]);
+  });
+
+  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)));
+    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(pve.guests.get(KEY)?.['mp0']).toContain('size=300G');
+  });
+
+  test('a vmid the cluster spells as a string is still listed, never absent', async () => {
+    const pve = cluster();
+    pve.others.push({ node: 'pve2', type: 'qemu', vmid: '101' });
+    const run = await lxcEngine(pve).plan(
+      ProxmoxLxc('ct', pasted({ ostemplate: TEMPLATE, vmid: 101 })),
+    );
+    expect(run.failure).toContain('vmid 101 is a qemu on pve2');
+  });
+});

package/src/proxmox/lxc-harness.ts

@@ -0,0 +1,150 @@
+/**
+ * Alchemy's real `Plan.make` and `apply` over fake-pve-lxc.ts, for the `Proxmox.Lxc` tests — the
+ * mesh-node-harness.ts composition, with plan-only runs added because the adoption gate is a PLAN.
+ *
+ * ⛔ TEST-ONLY. No provider imports this file and it is not on the barrel.
+ * ⛔ THE SHELL'S OPENBAO VARIABLES ARE REPLACED FOR THE LIFE OF EACH RUN. `mint` reads
+ *   `BAO_AGENT_ADDR` before `BAO_ADDR`, and `BAO_TOKEN` rides every mint as a header; a developer
+ *   shell with either set would otherwise send its real token to the fake, or its mint to a real
+ *   agent. fake-bao-env.ts clears every BAO_* / VAULT_*, points BAO_ADDR at the fake, and
+ *   restores them afterwards.
+ * ★ WARNINGS ARE CAPTURED, because the drift warning in lxc.ts is the only thing a cold adoption
+ *   plan says about a declaration that does not match yet (the plan itself reads `adopted`).
+ * ★ 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 { apply } from 'alchemy/Apply';
+import { provideFreshArtifactStore } from 'alchemy/Artifacts';
+import * as Plan from 'alchemy/Plan';
+import { type CompiledStack, make as makeStack } from 'alchemy/Stack';
+import { Stage } from 'alchemy/Stage';
+import * as State from 'alchemy/State';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Layer from 'effect/Layer';
+import * as Logger from 'effect/Logger';
+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';
+
+export const TARGET: PveTarget = {
+  members: [FAKE_MEMBER],
+  mount: 'proxmox-lxc-test',
+  scheme: 'pve',
+};
+
+/**
+ * A PRODUCTION-SHAPED config — the same keys and the same spellings pvesh printed, PVE's defaults
+ * written out — with every VALUE a placeholder: TEST-NET addresses, RFC 7042 documentation MACs,
+ * and a made-up pool, VLAN, mount path, gid and sizes.
+ * ⛔ SHAPE ONLY. This file ships in the npm tarball (`files` includes `src`), so nothing here may be
+ *   the estate's real topology — sizes, VLANs and bridges included, not only addresses.
+ */
+export const LIVE: Readonly<Record<string, unknown>> = {
+  arch: 'amd64',
+  cores: 4,
+  dev0: '/dev/dri/renderD128,uid=0,gid=44,mode=0660',
+  dev1: '/dev/net/tun,uid=0,gid=0,mode=0666',
+  features: 'nesting=1',
+  hostname: 'ct-example',
+  lxc: [['lxc.prlimit.memlock', 'unlimited']],
+  memory: 8192,
+  mp0: 'tank:subvol-100-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,' +
+    'ip=192.0.2.10/24,mtu=1500,tag=42,type=veth',
+  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',
+  searchdomain: 'example.com',
+  swap: 0,
+  tags: 'web',
+  unprivileged: 1,
+};
+
+/** 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' });
+};
+
+type Planned = { readonly action: string };
+type PlanView = {
+  readonly resources: Readonly<Record<string, Planned>>;
+  readonly deletions: Readonly<Record<string, Planned | undefined>>;
+};
+
+/** What the CLI would set for one run: `adopt` is `--adopt`. */
+export type RunOptions = { readonly adopt?: boolean };
+
+export type Run = {
+  /** Planned action per FQN, deletions included; empty when the plan itself failed. */
+  readonly actions: Readonly<Record<string, string>>;
+  /** The failure sentence, or `''`. */
+  readonly failure: string;
+  readonly warnings: readonly string[];
+};
+
+const withBaoEnv = <A>(body: () => Promise<A>): Promise<A> => withFakeBao(FAKE_BAO, body);
+
+export const lxcEngine = (fake: FakePve) => {
+  const rows: Record<string, Record<string, Record<string, State.ResourceState>>> = {};
+  const state = Layer.succeed(State.State, State.InMemoryService(rows));
+  const providers = ProxmoxLxcProvider().pipe(Layer.provideMerge(FetchHttpClient.layer));
+  const run = (
+    declare: Effect.Effect<unknown, unknown, unknown>,
+    write: boolean,
+    options: RunOptions,
+  ) =>
+    withBaoEnv(async (): Promise<Run> => {
+      const warnings: string[] = [];
+      const collect = Logger.make((options) => {
+        if (options.logLevel === 'Warn') warnings.push(String(options.message));
+      });
+      const exit = await Effect.runPromiseExit(
+        declare.pipe(
+          makeStack({ name: 'lxc', providers, state }) as never,
+          Effect.flatMap((compiled: CompiledStack) =>
+            Plan.make(compiled).pipe(
+              Effect.tap((planned) => (write ? apply(planned) : Effect.void)),
+              provideFreshArtifactStore,
+              Effect.provide(compiled.services),
+            ),
+          ),
+          options.adopt === undefined
+            ? (e) => e
+            : Effect.provideService(AdoptPolicy, options.adopt),
+          Effect.provide(Layer.succeed(Stage, 'test')),
+          Effect.provide(Logger.layer([collect])),
+          Effect.scoped,
+          Effect.provideService(FetchHttpClient.Fetch, fake.fetch),
+          // ⚠️ THE CAST IS AT THE ENGINE'S TYPED BOUNDARY (fake-stack.ts says why): the stack body
+          //   is typed against every service a CLI run provides, and this run provides the few it uses.
+        ) as unknown as Effect.Effect<PlanView, unknown>,
+      );
+      const actions: Record<string, string> = {};
+      if (Exit.isSuccess(exit)) {
+        for (const [fqn, node] of Object.entries(exit.value.resources)) actions[fqn] = node.action;
+        for (const [fqn, node] of Object.entries(exit.value.deletions)) {
+          if (node !== undefined) actions[fqn] = node.action;
+        }
+      }
+      const failure = Exit.isFailure(exit) ? String(Cause.squash(exit.cause)) : '';
+      return { actions, failure, warnings };
+    });
+  return {
+    /** Plan only — what `alchemy plan` shows. Nothing is applied and no state is written. */
+    plan: (declare: Effect.Effect<unknown, unknown, unknown>, options: RunOptions = {}) =>
+      run(declare, false, options),
+    /** Plan, then apply. */
+    deploy: (declare: Effect.Effect<unknown, unknown, unknown>, options: RunOptions = {}) =>
+      run(declare, true, options),
+    /** The stored row's status, or undefined when there is none. */
+    status: (fqn: string) => rows['lxc']?.['test']?.[fqn]?.status,
+  };
+};