@homeflare/alchemy 0.8.0 → 0.10.0

package/src/proxmox/fake-pve-lxc.ts

@@ -0,0 +1,210 @@
+/**
+ * A fake PVE cluster for `Proxmox.Lxc`: containers in memory, tasks that finish at once, and the
+ * OpenBao creds endpoint the mint reads — one Bun server, reached through `FetchHttpClient.Fetch`.
+ *
+ * ⛔ TEST-ONLY, AND NEVER A REAL HOST. No provider imports this file and it is not on the barrel.
+ *   Hostnames are `.test` (RFC 2606) and are remapped to the loopback server; any other host is
+ *   refused with ENOTFOUND rather than resolved (client.test.ts has the incident behind that).
+ * ★ IT ANSWERS THE WAY PVE 9 DOES WHERE THE PROVIDER DEPENDS ON IT, and each shape is a measured
+ *   one: a missing config is HTTP 500 with `message` in the JSON body (pve-http-server
+ *   `Formatter/Standard.pm`); a PUT with a stale `digest` is refused; a create allocates
+ *   `<storage>:subvol-<vmid>-disk-<n>,size=<n>G` and generates `hwaddr` and `type=veth`, as a live
+ *   guest's own config shows; tags come back sorted and lower-cased (`get_unique_tags`).
+ * ⚠️ EVERY MAC HERE IS FROM THE RFC 7042 DOCUMENTATION BLOCK (`00:00:5E:00:53:xx`), as every
+ *   address is TEST-NET: PVE's own prefix is `BC:24:11`, but no value in this package may be one a
+ *   real NIC could carry.
+ */
+import { pairs } from './lxc-wire.ts';
+
+export type Seen = {
+  readonly method: string;
+  readonly path: string;
+  readonly form: URLSearchParams;
+};
+
+export type FakePve = {
+  /** Live configs, keyed `node/vmid`. Mutate freely between deploys to simulate hand edits. */
+  readonly guests: Map<string, Record<string, unknown>>;
+  /** Extra `GET /cluster/resources` rows — a QEMU VM, or a guest on another node. */
+  readonly others: { vmid: number | string; node: string; type: string }[];
+  /** Forced answers for `GET …/config`, keyed `node/vmid`: an HTTP status and a JSON body. */
+  readonly configErrors: Map<string, { status: number; body: unknown }>;
+  /**
+   * Guests that read as ABSENT for the next N cluster listings (their config GET 500s meanwhile),
+   * keyed `node/vmid` — a guest that appears between a plan and its deploy.
+   */
+  readonly vanish: Map<string, number>;
+  /** Config keys a `PUT …/config` accepts with 200 and then does not store. */
+  readonly ignore: Set<string>;
+  /** How every task ends, and whether a task-starting call answers with no UPID at all. */
+  readonly task: { exit: string; noUpid: boolean };
+  readonly seen: Seen[];
+  readonly fetch: typeof fetch;
+  readonly stop: () => void;
+};
+
+/** The member hostname a test target names, and the OpenBao address the mint is pointed at. */
+export const FAKE_MEMBER = 'pve-a.test';
+export const FAKE_BAO = 'http://bao.test:8200';
+
+const json = (body: unknown, status = 200) => Response.json(body, { status });
+
+let digestCounter = 0;
+const nextDigest = () => {
+  digestCounter += 1;
+  return `digest-${String(digestCounter)}`;
+};
+
+/** What PVE's create does to the declared form: allocate volumes, fill NIC defaults, sort tags. */
+const created = (vmid: string, form: URLSearchParams): Record<string, unknown> => {
+  const config: Record<string, unknown> = { arch: 'amd64', ostype: 'debian', unprivileged: 1 };
+  let disk = 0;
+  for (const [key, value] of form) {
+    if (['ostemplate', 'start', 'vmid'].includes(key)) continue;
+    if (key === 'rootfs' || /^mp\d+$/.test(key)) {
+      const [first, ...rest] = value.split(',');
+      const fresh = /^([^:]+):(\d+)$/.exec(first ?? '');
+      config[key] =
+        fresh === null
+          ? value
+          : [
+              `${fresh[1] ?? ''}:subvol-${vmid}-disk-${String(disk++)}`,
+              ...rest,
+              `size=${fresh[2] ?? '0'}G`,
+            ].join(',');
+    } else if (/^net\d+$/.test(key)) {
+      const map = new Map(pairs(value));
+      if (!map.has('hwaddr'))
+        map.set('hwaddr', `00:00:5E:00:53:${vmid.slice(-2).padStart(2, '0')}`);
+      if (!map.has('type')) map.set('type', 'veth');
+      config[key] = [...map].map(([k, v]) => `${k}=${v}`).join(',');
+    } else if (key === 'tags') {
+      config[key] = [...new Set(value.toLowerCase().split(/[;,\s]+/))].sort().join(';');
+    } else config[key] = /^\d+$/.test(value) ? Number(value) : value;
+  }
+  return config;
+};
+
+export const fakePve = (): FakePve => {
+  const guests = new Map<string, Record<string, unknown>>();
+  const others: { vmid: number | string; node: string; type: string }[] = [];
+  const configErrors = new Map<string, { status: number; body: unknown }>();
+  const vanish = new Map<string, number>();
+  const ignore = new Set<string>();
+  const task = { exit: 'OK', noUpid: false };
+  const seen: Seen[] = [];
+  let upids = 0;
+  const upid = (node: string, kind: string, vmid: string) => {
+    upids += 1;
+    if (task.noUpid) return null;
+    return `UPID:${node}:${String(upids).padStart(8, '0')}:0:0:${kind}:${vmid}:hf-test@pve!fake:`;
+  };
+
+  const handle = async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    // ⚠️ QUERY AND BODY BOTH: a DELETE carries its parameters in the query, and a `force=1` there
+    //   must be visible to the test that says there is none.
+    const form = new URLSearchParams(url.search);
+    if (request.method !== 'GET')
+      for (const pair of new URLSearchParams(await request.text())) form.append(...pair);
+    seen.push({ form, method: request.method, path: url.pathname });
+    if (url.pathname.startsWith('/v1/') && url.pathname.includes('/creds/')) {
+      return json({
+        data: { secret: 'not-a-secret', token_id: 'hf-test@pve!fake' },
+        lease_duration: 300,
+      });
+    }
+    const path = url.pathname.replace(/^\/api2\/json\//, '');
+    if (path === 'cluster/resources') {
+      const rows = [...guests.keys()]
+        .filter((key) => (vanish.get(key) ?? 0) <= 0)
+        .map((key) => {
+          const [node, vmid] = key.split('/');
+          return { node, type: 'lxc', vmid: Number(vmid) };
+        });
+      for (const [key, left] of vanish) vanish.set(key, left - 1);
+      return json({ data: [...rows, ...others] });
+    }
+    if (/^nodes\/[^/]+\/tasks\/.+\/status$/.test(path)) {
+      return json({ data: { exitstatus: task.exit, status: 'stopped' } });
+    }
+    const create = /^nodes\/([^/]+)\/lxc$/.exec(path);
+    if (create !== null && request.method === 'POST') {
+      const node = create[1] ?? '';
+      const vmid = form.get('vmid') ?? '';
+      guests.set(`${node}/${vmid}`, { ...created(vmid, form), digest: nextDigest() });
+      return json({ data: upid(node, 'vzcreate', vmid) });
+    }
+    const guest = /^nodes\/([^/]+)\/lxc\/(\d+)(\/config|\/resize)?$/.exec(path);
+    if (guest === null) return json({ data: null, message: `no such path ${path}\n` }, 501);
+    const [, node = '', vmid = '', tail] = guest;
+    const forced = configErrors.get(`${node}/${vmid}`);
+    if (forced !== undefined && tail === '/config' && request.method === 'GET') {
+      return json(forced.body, forced.status);
+    }
+    const config =
+      (vanish.get(`${node}/${vmid}`) ?? 0) > 0 ? undefined : guests.get(`${node}/${vmid}`);
+    if (config === undefined) {
+      const message = `Configuration file 'nodes/${node}/lxc/${vmid}.conf' does not exist\n`;
+      return json({ data: null, message }, 500);
+    }
+    if (tail === '/config' && request.method === 'GET') return json({ data: config });
+    if (tail === '/config' && request.method === 'PUT') {
+      const digest = form.get('digest');
+      if (digest !== null && digest !== config['digest']) {
+        return json({ data: null, message: 'detected modified configuration\n' }, 500);
+      }
+      for (const [key, value] of form)
+        if (key !== 'digest' && key !== 'delete' && !ignore.has(key)) config[key] = value;
+      for (const key of (form.get('delete') ?? '').split(',')) if (key !== '') delete config[key];
+      config['digest'] = nextDigest();
+      return json({ data: null });
+    }
+    if (tail === '/resize' && request.method === 'PUT') {
+      const disk = form.get('disk') ?? '';
+      const current = String(config[disk] ?? '');
+      config[disk] = current.replace(/size=[^,]+/, `size=${form.get('size') ?? ''}`);
+      config['digest'] = nextDigest();
+      return json({ data: upid(node, 'resize', vmid) });
+    }
+    if (tail === undefined && request.method === 'DELETE') {
+      guests.delete(`${node}/${vmid}`);
+      return json({ data: upid(node, 'vzdestroy', vmid) });
+    }
+    return json({ data: null, message: 'unhandled\n' }, 501);
+  };
+
+  const server = Bun.serve({ fetch: handle, port: 0 });
+  const port = String(server.port);
+  const remapped = (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    const url = new URL(input instanceof Request ? input.url : String(input));
+    if (url.hostname !== FAKE_MEMBER && url.hostname !== new URL(FAKE_BAO).hostname) {
+      return Promise.reject(
+        Object.assign(new Error(`getaddrinfo ENOTFOUND ${url.hostname}`), {
+          code: 'ENOTFOUND',
+        }),
+      );
+    }
+    url.protocol = 'http:';
+    url.hostname = '127.0.0.1';
+    url.port = port;
+    return globalThis.fetch(url, init);
+  };
+  return {
+    configErrors,
+    fetch: Object.assign(remapped, { preconnect: globalThis.fetch.preconnect }),
+    guests,
+    ignore,
+    others,
+    seen,
+    stop: () => server.stop(true),
+    task,
+    vanish,
+  };
+};
+
+/** Every call that changed something, as `METHOD path`, in order — OpenBao mints excluded. */
+export const writesOf = (fake: FakePve) =>
+  fake.seen
+    .filter((call) => call.method !== 'GET')
+    .map((call) => `${call.method} ${call.path.replace(/^\/api2\/json\//, '')}`);

package/src/proxmox/fake-pve.ts

@@ -0,0 +1,75 @@
+/**
+ * A PVE cluster and the OpenBao that mints for it, both answered in-process by one stub `fetch` —
+ * so a family's REAL provider can run through Alchemy's engine with every call recorded.
+ *
+ * ★ A STUB `fetch`, NOT A SERVER. client.test.ts remaps hosts onto Bun.serve to test failover;
+ *   here the question is only which calls a lifecycle makes, and a stub answers every URL without
+ *   a socket, so nothing can reach a real host whatever the environment says.
+ * ⛔ AND THE ENVIRONMENT IS EMPTIED ANYWAY (`withoutBao`, fake-bao-env.ts), so a token in the
+ *   shell running the tests is never read.
+ * ⚠️ `lease_duration: 0` KEEPS THE LEASE CACHE COLD (lease-cache.ts `timeToLive`), so no fake
+ *   credential outlives the test that minted it.
+ * ⛔ TEST-ONLY. No provider imports this file.
+ */
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import type { PveTarget } from './credentials.ts';
+import { withFakeBao } from './fake-bao-env.ts';
+import { resetLastGoodForTest } from './members.ts';
+
+export const FAKE_TARGET: PveTarget = {
+  members: ['pve.test'],
+  mount: 'proxmox-test',
+  scheme: 'pve',
+};
+
+export interface PveCall {
+  readonly method: string;
+  /** Relative to `/api2/json/`, query included — the string a family passes to `pve()`. */
+  readonly path: string;
+  readonly form: Readonly<Record<string, string>>;
+}
+
+/** Answers one call with its `data`; `undefined` is PVE's `{"data": null}`. */
+export type PveAnswer = (call: PveCall) => unknown;
+
+export interface FakePve {
+  readonly calls: PveCall[];
+  /** Every call that is not a GET, as `METHOD path`. */
+  readonly writes: () => string[];
+  /** Provide over a provider layer: `Provider().pipe(Layer.provideMerge(fake.layer))`. */
+  readonly layer: ReturnType<typeof transport>;
+}
+
+/** Effect's own fetch client over a stub — client.test.ts wires failover the same way. */
+const transport = (stub: typeof fetch) =>
+  FetchHttpClient.layer.pipe(Layer.provideMerge(Layer.succeed(FetchHttpClient.Fetch, stub)));
+
+export const fakePve = (answer: PveAnswer): FakePve => {
+  const calls: PveCall[] = [];
+  const stub = async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    if (url.pathname.includes('/creds/')) {
+      const data = { secret: 'fake-secret-not-real', token_id: 'hf-test@pve!fake' };
+      return Response.json({ data, lease_duration: 0 });
+    }
+    const path = `${url.pathname.replace(/^\/api2\/json\//, '')}${url.search}`;
+    const form = Object.fromEntries(new URLSearchParams(await request.text()));
+    const call = { form, method: request.method, path };
+    calls.push(call);
+    return Response.json({ data: answer(call) ?? null });
+  };
+  // ⚠️ `typeof fetch` carries `preconnect` on bun's lib — client.test.ts has the note.
+  const fetchStub = Object.assign(stub, { preconnect: globalThis.fetch.preconnect });
+  return {
+    calls,
+    layer: transport(fetchStub as typeof fetch),
+    writes: () => calls.filter((c) => c.method !== 'GET').map((c) => `${c.method} ${c.path}`),
+  };
+};
+
+/** Run `body` against the stub's OpenBao (fake-bao-env.ts), then forget the member failover state. */
+export const withoutBao = <A>(body: () => Promise<A>): Promise<A> =>
+  withFakeBao('http://bao.invalid', body).finally(resetLastGoodForTest);

package/src/proxmox/index.test.ts

@@ -1,9 +1,9 @@
 /**
- * Public barrel: control-plane Resource constructors, not guests or NIC apply.
+ * Public barrel: control-plane Resource constructors and `ProxmoxLxc`, not QEMU or NIC apply.
  *
- * ⛔ Lxc/Vm stay Provider-only. A Resource export would let a stack declare
- *   guests before storage/SDN exist. NodeNetwork/NetworkApply stay off the
- *   barrel for the same reason — they stage interfaces.new.
+ * ⛔ Vm stays Provider-only. NodeNetwork/NetworkApply stay off the barrel — they stage
+ *   interfaces.new. ★ Lxc is a Resource since 2026-09-21: adopt-first, refuse-not-replace,
+ *   retain on destroy (lxc.ts).
  */
 import { expect, test } from 'bun:test';
 import { PbsDatastore, ProxmoxStorage } from './index.ts';
@@ -20,6 +20,7 @@ const resourceExports = [
   'ProxmoxGroup',
   'ProxmoxHaResource',
   'ProxmoxHaRule',
+  'ProxmoxLxc',
   'ProxmoxMetricServer',
   'ProxmoxNotificationTarget',
   'ProxmoxRole',
@@ -39,8 +40,7 @@ test('control-plane Resource constructors are on the public barrel', () => {
   }
 });
 
-test('guests and NIC apply stay Provider-only', () => {
-  expect(src).not.toMatch(/export \{ ProxmoxLxc[, }]/);
+test('QEMU and NIC apply stay Provider-only', () => {
   expect(src).not.toMatch(/export \{ ProxmoxVm[, }]/);
   expect(src).not.toMatch(/export \{ ProxmoxNodeNetwork[, }]/);
   expect(src).not.toMatch(/export \{ ProxmoxNetworkApply[, }]/);

package/src/proxmox/index.ts

@@ -6,8 +6,12 @@
  *   provider needs but a consumer should not depend on. An `export *` here would publish
  *   every helper as API and make the next refactor a breaking change.
  * ★ Control-plane Resource constructors (Storage, SDN, access, HA, backup,
- *   metrics, PBS) sit next to their Providers. Guests and NIC apply stay
+ *   metrics, PBS) sit next to their Providers. NIC apply and QEMU stay
  *   Provider-only so a stack cannot declare them by accident.
+ * ★ `ProxmoxLxc` JOINED THEM 2026-09-21, AND IT WAS KEPT OFF UNTIL IT COULD NOT HURT A GUEST.
+ *   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).
  * ★ 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.
  */
@@ -23,7 +27,7 @@ export { ProxmoxFirewallAliasProvider } from './firewall-alias.ts';
 export { ProxmoxGroup, ProxmoxGroupProvider } from './group.ts';
 export { ProxmoxHaResource, ProxmoxHaResourceProvider } from './ha-resource.ts';
 export { ProxmoxHaRule, ProxmoxHaRuleProvider } from './ha-rule.ts';
-export { ProxmoxLxcProvider } from './lxc.ts';
+export { type LxcAttributes, type LxcProps, ProxmoxLxc, ProxmoxLxcProvider } from './lxc.ts';
 export { ProxmoxMetricServer, ProxmoxMetricServerProvider } from './metric-server.ts';
 export { ProxmoxNetworkApplyProvider } from './network-apply.ts';
 export { ProxmoxNodeNetworkProvider } from './node-network.ts';

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;
+};