@homeflare/alchemy 0.8.0 → 0.10.1

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

@@ -0,0 +1,159 @@
+/**
+ * Whose guest it is — docs/ownership.md applied to `Proxmox.Lxc`, through the real engine over
+ * fake-pve-lxc.ts (placeholders only).
+ *
+ * ⛔ WHAT THESE PIN: with no state, no live guest is adopted without `--adopt` or `adopt(true)`,
+ *   not even one that matches the declaration; `adopt(false)` wins over the flag; a deploy that
+ *   planned a create refuses a guest it then finds, and forgets its `creating` row; under
+ *   `--adopt` it records a matching one with no write and still refuses one that differs; and a
+ *   create interrupted after its POST resumes WITHOUT `--adopt` when the guest is what it wrote,
+ *   and asks for `--adopt` when someone changed it meanwhile.
+ * ★ THE INTERRUPTION IS A CREATE TASK THAT ENDS IN AN ERROR AFTER THE FAKE BUILT THE GUEST — to the
+ *   engine the same as a deploy killed while it waited on the task: a live guest, and a
+ *   `creating` row with no attributes.
+ */
+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 TAKEOVER = 'already exists, and this stack holds no state for it';
+
+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;
+};
+const live = () => {
+  const pve = cluster();
+  seed(pve, NODE, VMID);
+  return pve;
+};
+
+describe('with no state, a live guest is never adopted silently', () => {
+  test.each([
+    ['one that matches', 'ct-example'],
+    ['one that differs', 'somebody-else'],
+  ])('%s: the plan fails "Cannot adopt" and nothing is written', async (_, hostname) => {
+    const pve = live();
+    const run = await lxcEngine(pve).deploy(
+      ProxmoxLxc('ct', { hostname, node: NODE, target: TARGET, vmid: VMID }),
+    );
+    expect(run.failure).toContain('Cannot adopt');
+    expect(writesOf(pve)).toEqual([]);
+  });
+
+  test('--adopt takes a matching guest over with no write; the next plan is noop', async () => {
+    const pve = live();
+    const stack = lxcEngine(pve);
+    const run = await stack.deploy(ProxmoxLxc('ct', pasted()), { adopt: true });
+    expect(run).toMatchObject({ actions: { ct: 'adopted' }, failure: '' });
+    expect(writesOf(pve)).toEqual([]);
+    expect((await stack.plan(ProxmoxLxc('ct', pasted()))).actions).toEqual({ ct: 'noop' });
+  });
+
+  test('adopt(false) wins over --adopt', async () => {
+    const pve = live();
+    const declared = ProxmoxLxc('ct', pasted()).pipe(adopt(false));
+    const run = await lxcEngine(pve).deploy(declared, { adopt: true });
+    expect(run.failure).toContain('Cannot adopt');
+    expect(writesOf(pve)).toEqual([]);
+  });
+});
+
+describe('a create never takes over a guest it finds at apply', () => {
+  test('one that appears after the plan is refused, matching or not, and its row forgotten', async () => {
+    const pve = live();
+    pve.vanish.set(KEY, 2);
+    const stack = lxcEngine(pve);
+    expect((await stack.plan(ProxmoxLxc('ct', pasted()))).actions).toEqual({ ct: 'create' });
+    const run = await stack.deploy(ProxmoxLxc('ct', pasted()));
+    expect(run.failure).toContain(TAKEOVER);
+    expect(writesOf(pve)).toEqual([]);
+    expect(stack.status('ct')).toBeUndefined();
+    expect((await stack.plan(ProxmoxLxc('ct', pasted()))).failure).toContain('Cannot adopt');
+  });
+
+  test('under --adopt, one that matches is recorded with no write', async () => {
+    const pve = live();
+    pve.vanish.set(KEY, 1);
+    const stack = lxcEngine(pve);
+    const run = await stack.deploy(ProxmoxLxc('ct', pasted()), { adopt: true });
+    expect(run).toMatchObject({ actions: { ct: 'create' }, failure: '' });
+    expect(writesOf(pve)).toEqual([]);
+    expect((await stack.plan(ProxmoxLxc('ct', pasted()))).actions).toEqual({ ct: 'noop' });
+  });
+
+  test('under --adopt, one that differs is still refused until a plan can show it', async () => {
+    const pve = live();
+    pve.vanish.set(KEY, 2);
+    const stack = lxcEngine(pve);
+    const declared = () => ProxmoxLxc('ct', pasted({ memory: 1024 }));
+    expect((await stack.plan(declared())).actions).toEqual({ ct: 'create' });
+    const run = await stack.deploy(declared(), { adopt: true });
+    expect(run.failure).toContain('already exists on pve1 and differs in memory');
+    expect(writesOf(pve)).toEqual([]);
+  });
+});
+
+describe('an interrupted create', () => {
+  const door = (over: Partial<LxcProps> = {}) =>
+    ProxmoxLxc('door', {
+      hostname: 'door-example',
+      node: NODE,
+      ostemplate: 'local:vztmpl/debian-13-standard_13.1-2_amd64.tar.zst',
+      rootfs: 'local-zfs:8',
+      target: TARGET,
+      vmid: 150,
+      ...over,
+    });
+  const interrupted = async () => {
+    const pve = cluster();
+    const stack = lxcEngine(pve);
+    pve.task.exit = 'interrupted';
+    expect((await stack.deploy(door())).failure).toContain('ended "interrupted"');
+    expect(stack.status('door')).toBe('creating');
+    pve.task.exit = 'OK';
+    return { pve, stack };
+  };
+
+  test('resumes without --adopt when the guest is what it wrote, and writes nothing more', async () => {
+    const { pve, stack } = await interrupted();
+    expect((await stack.deploy(door())).failure).toBe('');
+    expect(writesOf(pve)).toEqual([`POST nodes/${NODE}/lxc`]);
+    expect((await stack.plan(door())).actions).toEqual({ door: 'noop' });
+  });
+
+  test('resumes when the plan reads no guest and the apply then finds it (diff noted it)', async () => {
+    const { pve, stack } = await interrupted();
+    pve.vanish.set(`${NODE}/150`, 1);
+    expect((await stack.deploy(door())).failure).toBe('');
+    expect(writesOf(pve)).toEqual([`POST nodes/${NODE}/lxc`]);
+    expect(stack.status('door')).toBe('created');
+  });
+
+  test('asks for --adopt when the guest changed meanwhile, and resumes with it', async () => {
+    const { pve, stack } = await interrupted();
+    const guest = pve.guests.get(`${NODE}/150`) ?? {};
+    guest['hostname'] = 'someone-else';
+    expect((await stack.deploy(door())).failure).toContain('Cannot resume creating');
+    const resumed = await stack.deploy(door(), { adopt: true });
+    expect(resumed.failure).toBe('');
+    expect(resumed.warnings.join('\n')).toContain('differs from the declaration in hostname');
+    expect(pve.guests.get(`${NODE}/150`)?.['hostname']).toBe('door-example');
+  });
+});

package/src/proxmox/lxc-props.ts

@@ -0,0 +1,215 @@
+/**
+ * What a `Proxmox.Lxc` declaration says, and what its state keeps.
+ *
+ * ★ THE PROPS ARE PVE'S OWN KEYS, SPELLED THE WAY `pvesh get /nodes/{node}/lxc/{vmid}/config`
+ *   PRINTS THEM — `mp0`, `net1`, `dev0`, `rootfs` as property strings, `onboot` as `1`. Adopting a
+ *   live container is then a paste of its config, not a translation of it, and a translation is
+ *   where an adoption goes wrong: one mistyped key and the first deploy writes it. The generated
+ *   `NodesNodeLxcVmidConfigGetReturn` (pve-manager 9.2.11 schema) names the same keys.
+ *
+ * ⛔ AN UNDECLARED KEY IS UNMANAGED: never sent, never compared, never deleted. A guest carries
+ *   keys PVE fills in on its own (`arch`, `ostype`, `digest`, a NIC's `hwaddr`) and keys somebody
+ *   set by hand; guessing a default for either would turn an omission into a write on a running
+ *   guest. To REMOVE a key, declare it empty (`''`) where lxc-judge.ts allows that.
+ *
+ * ⛔ NO SECRET IS A PROP, AND THE THREE THAT PVE ACCEPTS ARE TYPED `never`. `password` and
+ *   `ssh-public-keys` are create parameters; `env` (PVE 9 application containers) holds runtime
+ *   environment that can carry anything. Alchemy stores props unencrypted and this estate's state
+ *   store is dumped nightly, so declaring one is a compile error rather than a leak found in a
+ *   backup. A container created here has no root password: reach it with `pct enter` on its node.
+ */
+import { SCALAR_KINDS } from './lxc-wire.ts';
+import type { WithTarget } from './resource.ts';
+
+/** A PVE boolean as pvesh prints it (`1`) or as TypeScript writes it (`true`). The same value. */
+export type PveFlag = boolean | 0 | 1;
+
+export interface LxcProps extends WithTarget {
+  /**
+   * The node that hosts it. ⛔ This resource never migrates: naming another node plans only when
+   * the guest is already there (after HA or `pct migrate`), and then writes nothing.
+   */
+  node: string;
+  /** ⛔ CLUSTER-WIDE primary key, shared with QEMU VMs. Required, never allocated here. */
+  vmid: number;
+  /**
+   * `local:vztmpl/debian-13-standard_13.1-2_amd64.tar.zst`. ⚠️ CREATE-ONLY AND NOT READABLE BACK:
+   * PVE consumes it while unpacking the rootfs. Optional, because an adopted guest was built from a
+   * template nobody recorded; required only when this resource has to create the guest.
+   */
+  ostemplate?: string;
+  /** Start the guest once, after its create finishes (PVE's create `start`). ⚠️ Never compared. */
+  start?: PveFlag;
+  /**
+   * ⛔ READ-ONLY AFTER CREATE. PVE refuses to change it ("unable to modify read-only option"), so a
+   * differing value is refused at plan. Absent from a live config means `0`: privileged. On create,
+   * PVE's own default is `1`.
+   */
+  unprivileged?: PveFlag;
+  hostname?: string;
+  arch?: string;
+  ostype?: string;
+  cores?: number;
+  /** `0` means no limit. May be fractional (`1.5`). */
+  cpulimit?: number;
+  cpuunits?: number;
+  /** MiB. */
+  memory?: number;
+  /** MiB. */
+  swap?: number;
+  /**
+   * `local-zfs:subvol-100-disk-0,size=40G` as read, or `local-zfs:40` (40 GiB, new volume) to
+   * create. See lxc-volume.ts for what may change: options in place, size up only.
+   */
+  rootfs?: string;
+  /** `nesting=1,keyctl=1`. ⛔ Only `nesting` is writable by an API token — see lxc-judge.ts. */
+  features?: string;
+  onboot?: PveFlag;
+  /** `order=1,up=30,down=60`. */
+  startup?: string;
+  protection?: PveFlag;
+  /** Free text. ⚠️ PVE stores it as `#` comment lines and hands it back with a trailing newline. */
+  description?: string;
+  /** `a;b`. ⚠️ Compared as a set; PVE sorts and, by default, lowercases them. */
+  tags?: string;
+  /** Space-separated. Order is meaningful to a resolver, so it is compared in order. */
+  nameserver?: string;
+  searchdomain?: string;
+  timezone?: string;
+  console?: PveFlag;
+  tty?: number;
+  cmode?: string;
+  /** `tank:subvol-100-disk-1,mp=/data,backup=1,size=100G`, or `tank:100,mp=/data` to create. */
+  [mount: `mp${number}`]: string | undefined;
+  /** `name=eth0,bridge=vmbr0,ip=dhcp`. ⚠️ An undeclared `hwaddr` keeps the live MAC. */
+  [nic: `net${number}`]: string | undefined;
+  /** `/dev/net/tun`, `/dev/dri/renderD128,gid=44,mode=0660`. ⛔ root@pam only — see lxc-judge.ts. */
+  [device: `dev${number}`]: string | undefined;
+  /** ⛔ A secret. See the header. */
+  password?: never;
+  /** ⛔ Treated as a secret here. See the header. */
+  'ssh-public-keys'?: never;
+  /** ⛔ Can carry anything, and a read token cannot even see it. See the header. */
+  env?: never;
+}
+
+export interface LxcAttributes {
+  node: string;
+  vmid: number;
+  /**
+   * The live config, each value as PVE's own string: every key this resource MANAGES
+   * (`isManagedKey`), declared or not, minus the keys in `UNSTORED`.
+   * ★ A MAP RATHER THAN TYPED FIELDS so a plan can show whatever managed key the guest carries.
+   * ⛔ AN ALLOWLIST, NOT "EVERYTHING BUT A DENYLIST" — see `storedConfig`.
+   */
+  config: Record<string, string>;
+  /**
+   * The raw `lxc.*` lines in the guest's config file — NAMES ONLY.
+   * ⚠️ A GAP, NOT A FEATURE: PVE's API returns these but cannot set them (`lxc.prlimit.memlock`,
+   *   `lxc.cgroup2.devices.allow`, `lxc.mount.entry`). They are edited in `/etc/pve/lxc/<vmid>.conf`
+   *   on the node, so this resource reports that they exist and never compares them. ⛔ Values are
+   *   not stored: `lxc.environment` is one of the keys PVE allows there.
+   */
+  rawKeys: string[];
+}
+
+/**
+ * Keys a read returns that state never keeps.
+ * ⚠️ `digest` covers the whole file and `lock` is transient (a running backup), so either would
+ *   rewrite state on every read; `env` and `lxc` are the secret risks in the header and above.
+ * ⛔ `description` IS THE GUEST'S "NOTES" PANEL IN THE PVE UI, where people paste credentials. A
+ *   declared one is already in props; an undeclared one is not this resource's to copy into an
+ *   unencrypted state store.
+ */
+export const UNSTORED: ReadonlySet<string> = new Set([
+  'description',
+  'digest',
+  'env',
+  'lock',
+  'lxc',
+  'pending',
+]);
+
+/** The indexed families, with PVE's own limits (pve-container `$MAX_*`, 6.1.14). */
+export const INDEXED = {
+  dev: 256,
+  mp: 256,
+  net: 32,
+} as const;
+
+export type IndexedFamily = keyof typeof INDEXED;
+
+/** `mp3` → `['mp', 3]`; anything else → undefined. ⚠️ `mp03` is not a PVE key. */
+export const indexedKey = (key: string): readonly [IndexedFamily, number] | undefined => {
+  const match = /^(mp|net|dev)(0|[1-9]\d*)$/.exec(key);
+  if (match === null) return undefined;
+  const family = match[1] as IndexedFamily;
+  const index = Number(match[2]);
+  return index < INDEXED[family] ? [family, index] : undefined;
+};
+
+/** Props that are not config keys: where the guest lives, and create-time instructions. */
+export const NOT_CONFIG: ReadonlySet<string> = new Set([
+  'node',
+  'ostemplate',
+  'start',
+  'target',
+  'vmid',
+]);
+
+/**
+ * A declaration read by key. ⚠️ The cast is the one place the three template-literal index
+ * signatures meet a plain string key; every reader goes through here rather than casting again.
+ */
+export const declaredValue = (props: LxcProps, key: string): unknown =>
+  (props as unknown as Record<string, unknown>)[key];
+
+/** The declared config keys with a value, in a stable order. `''` counts: it means "absent". */
+export const declaredKeys = (props: LxcProps): string[] =>
+  Object.keys(props)
+    .filter((key) => !NOT_CONFIG.has(key) && declaredValue(props, key) !== undefined)
+    .sort();
+
+/** One declared value as PVE's wire string. Booleans go as `1`/`0`, numbers as their decimal. */
+export const wireValue = (value: unknown): string =>
+  value === true ? '1' : value === false ? '0' : String(value);
+
+/**
+ * A key this resource compares and may write: a scalar lxc-wire.ts knows, `unprivileged`, `rootfs`,
+ * or an indexed `mpN`/`netN`/`devN`. ★ ONE PREDICATE FOR THE THREE PLACES THAT ASK: `judge` refuses
+ * any other declared key, `createRefusals` refuses it before a POST, and `storedConfig` keeps
+ * nothing else. ⛔ Without the create half, a key smuggled past the types (a cast, a JS caller:
+ * `password`, `force`, `restore`, `hookscript`) went into the create body verbatim.
+ */
+export const isManagedKey = (key: string): boolean =>
+  SCALAR_KINDS[key] !== undefined ||
+  key === 'unprivileged' ||
+  key === 'rootfs' ||
+  indexedKey(key) !== undefined;
+
+/**
+ * The live config as strings: managed keys only, the unstored ones dropped.
+ * ⛔ AN ALLOWLIST, BECAUSE A DENYLIST IS SURPRISED BY THE NEXT PVE RELEASE. `env` joined the config
+ *   in PVE 9 with application containers, and `entrypoint` with it — a command line, which can
+ *   carry a token as an argument. Under "store everything except UNSTORED" each new key lands in
+ *   the unencrypted state store until somebody notices; under this, it is not stored until this
+ *   resource manages it. `hookscript`, `unusedN`, `parent` and `lock` are dropped the same way.
+ */
+export const storedConfig = (live: Record<string, unknown>): Record<string, string> => {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(live)) {
+    if (!isManagedKey(key) || UNSTORED.has(key)) continue;
+    if (value === null || value === undefined || typeof value === 'object') continue;
+    out[key] = wireValue(value);
+  }
+  return out;
+};
+
+/** `[["lxc.prlimit.memlock","unlimited"]]` → `['lxc.prlimit.memlock']`. Values are dropped. */
+export const rawKeysOf = (live: Record<string, unknown>): string[] => {
+  const raw = live['lxc'];
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((pair: unknown) => (Array.isArray(pair) ? String(pair[0]) : ''))
+    .filter((key) => key !== '');
+};

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

@@ -0,0 +1,60 @@
+/**
+ * When a container read counts as "absent" — the question that decides between adopt and create.
+ *
+ * ⛔ WHAT THESE PIN: only a 500 whose vmid the cluster does not list anywhere is absent, whatever
+ *   the message says; a 403 or a 500 for a guest the cluster lists on the declared node FAILS the
+ *   plan with PVE's own error; nothing is written in any case. resource.ts's fold of every error
+ *   into "absent" is exactly what this resource must not inherit — under it, a lease without
+ *   VM.Audit plans a CREATE over a running guest.
+ */
+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';
+
+const NODE = 'pve1';
+
+let fake: FakePve | undefined;
+afterEach(() => {
+  fake?.stop();
+  fake = undefined;
+});
+
+const declared = (vmid: number) =>
+  ProxmoxLxc('ct', {
+    hostname: 'ct-example',
+    node: NODE,
+    ostemplate: 'local:vztmpl/t.tar.zst',
+    target: TARGET,
+    vmid,
+  }).pipe(adopt(true));
+
+describe('absent means the cluster does not list the vmid', () => {
+  test('a 500 with no message, for a vmid nowhere in the cluster, plans a create', async () => {
+    fake = fakePve();
+    fake.configErrors.set(`${NODE}/150`, { body: { data: null }, status: 500 });
+    const run = await lxcEngine(fake).plan(declared(150));
+    expect(run).toMatchObject({ actions: { ct: 'create' }, failure: '' });
+  });
+
+  test('a 500 for a guest the cluster lists on this node fails with PVE’s error', async () => {
+    fake = fakePve();
+    seed(fake, NODE, 100, LIVE);
+    const message = 'got timeout\n';
+    fake.configErrors.set(`${NODE}/100`, { body: { data: null, message }, status: 500 });
+    const run = await lxcEngine(fake).plan(declared(100));
+    expect(run.failure).toContain('got timeout');
+    expect(run.actions).toEqual({});
+    expect(writesOf(fake)).toEqual([]);
+  });
+
+  test('a 403 is never absent: the plan fails instead of planning a create', async () => {
+    fake = fakePve();
+    const message = 'Permission check failed (/vms/150, VM.Audit)\n';
+    fake.configErrors.set(`${NODE}/150`, { body: { data: null, message }, status: 403 });
+    const run = await lxcEngine(fake).plan(declared(150));
+    expect(run.failure).toContain('-> 403');
+    expect(run.actions).toEqual({});
+  });
+});

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

@@ -0,0 +1,96 @@
+/**
+ * The mount-point and key-set rules an adversarial review found unpinned (2026-09-21): each test
+ * here failed against a mutant of the rule it names.
+ *
+ * ⛔ WHAT THESE PIN: another volume on the same storage is refused (a PUT of it would detach the
+ *   live one to unusedN); a bind or device mount is root@pam's whether new or changed; `replicate`
+ *   defaults ON; an options change that also grows writes the LIVE size; a key the resource does
+ *   not manage never reaches a create body; and state keeps managed keys only.
+ */
+import { describe, expect, test } from 'bun:test';
+import { TARGET } from './lxc-harness.ts';
+import { createRefusals } from './lxc-create-form.ts';
+import { judge } from './lxc-judge.ts';
+import { type LxcProps, storedConfig } from './lxc-props.ts';
+import { judgeVolume } from './lxc-volume.ts';
+
+const LIVE_MP = 'tank:subvol-100-disk-0,mp=/data,size=200G';
+const props = (over: Record<string, unknown>): LxcProps =>
+  ({ node: 'pve1', target: TARGET, vmid: 100, ...over }) as unknown as LxcProps;
+const live = (config: Record<string, unknown>) => ({ unprivileged: 1, ...config });
+
+describe('mount points', () => {
+  test('another volume on the same storage is refused, never written', () => {
+    const verdict = judgeVolume('mp0', 'tank:subvol-100-disk-7,mp=/data,size=200G', LIVE_MP);
+    expect(verdict.refuse).toMatch(/detach the live volume to unusedN/);
+    expect(verdict.put).toBeUndefined();
+    const change = judge(props({ mp0: 'tank:subvol-100-disk-7,mp=/data' }), live({ mp0: LIVE_MP }));
+    expect(change.put).toEqual({});
+    expect(change.refuse[0]).toMatch(/unusedN/);
+  });
+
+  test('a bind mount is root@pam only, new or changed', () => {
+    const added = judge(props({ mp1: '/srv/share,mp=/share' }), live({}));
+    expect(added.put).toEqual({});
+    expect(added.refuse[0]).toMatch(/pct set 100 --mp1/);
+    const bind = '/srv/share,mp=/share';
+    expect(judgeVolume('mp1', `${bind},ro=1`, bind)).toEqual({ rootOnly: true });
+    expect(judgeVolume('mp1', bind, bind)).toEqual({});
+  });
+
+  test('replicate defaults ON: an explicit replicate=0 is a value, replicate=1 is not', () => {
+    expect(judgeVolume('mp0', `${LIVE_MP},replicate=1`, LIVE_MP)).toEqual({});
+    const off = judgeVolume('mp0', LIVE_MP, `${LIVE_MP},replicate=0`);
+    expect(off.put).toBe('tank:subvol-100-disk-0,mp=/data,size=200G');
+  });
+
+  test('options and growth together: the PUT carries the live size, the resize the new one', () => {
+    const verdict = judgeVolume('mp0', 'tank:300,mp=/data,backup=1', LIVE_MP);
+    expect(verdict).toEqual({
+      put: 'tank:subvol-100-disk-0,mp=/data,backup=1,size=200G',
+      resize: '300G',
+    });
+  });
+});
+
+describe('a create allocates new volumes only', () => {
+  test('an existing volume id in a create is refused; the new-disk spelling is not', () => {
+    const base = { ostemplate: 'local:vztmpl/t.tar.zst' };
+    const existing = createRefusals(
+      props({ ...base, rootfs: 'local-zfs:subvol-100-disk-0,size=8G' }),
+    );
+    expect(existing.join('\n')).toMatch(/rootfs: .* names an existing volume/);
+    expect(
+      createRefusals(props({ ...base, mp0: 'tank:8,mp=/data', rootfs: 'local-zfs:8' })),
+    ).toEqual([]);
+  });
+});
+
+describe('keys the resource does not manage', () => {
+  test.each([['password'], ['force'], ['restore'], ['hookscript']])(
+    '%s is refused at create, so it is never POSTed',
+    (key) => {
+      const refusals = createRefusals(props({ [key]: '1', ostemplate: 'local:vztmpl/t.tar.zst' }));
+      expect(refusals.join('\n')).toContain(`${key}: not a config key this resource manages`);
+    },
+  );
+
+  test('state keeps managed keys only: a new PVE key is not stored until it is managed', () => {
+    const read = {
+      entrypoint: '/usr/bin/app --token=placeholder',
+      hookscript: 'local:snippets/x.sh',
+      hostname: 'x',
+      memory: 512,
+      mp0: LIVE_MP,
+      parent: 'snap1',
+      unprivileged: 1,
+      unused0: 'tank:subvol-100-disk-9',
+    };
+    expect(storedConfig(read)).toEqual({
+      hostname: 'x',
+      memory: '512',
+      mp0: LIVE_MP,
+      unprivileged: '1',
+    });
+  });
+});

package/src/proxmox/lxc-volume.ts

@@ -0,0 +1,153 @@
+/**
+ * `rootfs` and `mpN`: what a declared mount point may change on a live guest, and how.
+ *
+ * ★ FOUR ANSWERS, AND ONLY ONE OF THEM IS A CONFIG WRITE. Options (`mp=`, `backup`, `acl`, …)
+ *   change in place with `PUT …/config`. A size INCREASE goes through `PUT …/resize`. Everything
+ *   else is refused with a sentence, because the only way PVE offers to get there loses the guest
+ *   or its data:
+ *   - a size DECREASE — `resize_vm` dies "unable to shrink disk size" (pve-container 6.1.14);
+ *   - a storage MOVE — that is `pct move-volume`, a copy, not a config edit;
+ *   - a DIFFERENT volume on the same storage — writing it would detach the live one to `unusedN`;
+ *   - a bind or device mount — `check_ct_modify_config_perm` lets only `root@pam` write one, and an
+ *     API token's user is `user@realm!token`, never `root@pam` (pve-access-control `verify_token`).
+ *
+ * ⛔ AN EXISTING VOLUME IS NEVER WRITTEN WITH THE NEW-DISK SPELLING. `tank:100` in a PUT means
+ *   "allocate a fresh 100 GiB volume", and PVE then moves the volume the guest was using to
+ *   `unusedN`. So a declared `tank:100,mp=/data` that matches a live
+ *   `tank:subvol-100-disk-1,mp=/data,size=100G` compares EQUAL, and an options change on it is
+ *   written with the LIVE volume id — the declaration's spelling is never sent back for a volume
+ *   that exists.
+ */
+import { optionMap, pairs, sameMap } from './lxc-wire.ts';
+
+/** PVE's `$NEW_DISK_RE`: `storage:SIZE`, SIZE in GiB, fractional allowed. */
+const NEW_DISK = /^([^:\s]+):(\d+(?:\.\d+)?)$/;
+
+const UNITS: Readonly<Record<string, number>> = {
+  G: 1024 ** 3,
+  K: 1024,
+  M: 1024 ** 2,
+  T: 1024 ** 4,
+};
+
+/** PVE's `parse_size`: `\d+(\.\d+)?[KMGT]?`, binary units, bare means bytes. */
+export const sizeBytes = (text: string): number | undefined => {
+  const match = /^(\d+(?:\.\d+)?)([KMGT])?$/.exec(text.trim());
+  if (match === null) return undefined;
+  return Math.trunc(Number(match[1]) * (match[2] === undefined ? 1 : (UNITS[match[2]] ?? 1)));
+};
+
+export type Volume = {
+  readonly kind: 'new' | 'volume' | 'bind' | 'device';
+  /** `new`/`volume`: the storage id. `bind`/`device`: the host path. */
+  readonly source: string;
+  /** `volume` only: the name after `storage:`. */
+  readonly volname: string;
+  /** From `size=`, or the new-disk GiB. Undefined when neither says. */
+  readonly size: number | undefined;
+  /** The size as written, for a resize request. */
+  readonly sizeText: string | undefined;
+  /** Every other option, comparable. */
+  readonly options: Map<string, string>;
+};
+
+/** PVE's `classify_mountpoint`, plus the new-disk spelling a declaration may use. */
+export const parseVolume = (text: string): Volume => {
+  const [first] = pairs(text, 'volume');
+  const spec = first?.[0] === 'volume' ? first[1] : '';
+  const options = optionMap(text, 'volume', 'volume');
+  options.delete('volume');
+  const sizeText = options.get('size');
+  options.delete('size');
+  const fresh = NEW_DISK.exec(spec);
+  if (fresh !== null) {
+    const gib = `${fresh[2] ?? '0'}G`;
+    return {
+      kind: 'new',
+      options,
+      size: sizeBytes(gib),
+      sizeText: gib,
+      source: fresh[1] ?? '',
+      volname: '',
+    };
+  }
+  const size = sizeText === undefined ? undefined : sizeBytes(sizeText);
+  if (spec.startsWith('/')) {
+    const kind = spec.startsWith('/dev/') ? 'device' : 'bind';
+    return { kind, options, size, sizeText, source: spec, volname: '' };
+  }
+  const at = spec.indexOf(':');
+  return {
+    kind: 'volume',
+    options,
+    size,
+    sizeText,
+    source: at === -1 ? spec : spec.slice(0, at),
+    volname: at === -1 ? '' : spec.slice(at + 1),
+  };
+};
+
+/** What one mount point needs. At most one of `refuse` / `rootOnly` is set, and then nothing else. */
+export type VolumeVerdict = {
+  readonly refuse?: string;
+  readonly rootOnly?: boolean;
+  /** The value to PUT, built on the LIVE volume id. */
+  readonly put?: string;
+  /** An absolute size to hand `PUT …/resize`, which only ever grows. */
+  readonly resize?: string;
+};
+
+export const isHostPath = (volume: Volume) => volume.kind === 'bind' || volume.kind === 'device';
+
+/**
+ * The value to PUT for an options change: live volume, declared options, LIVE size.
+ * ⚠️ THE LIVE SIZE, NOT THE DECLARED ONE: `size=` is written by the resize call itself, and a PUT
+ *   that sent the declared size ahead of the resize would record a size the volume does not have.
+ */
+const rewrite = (live: Volume, declared: Volume) => {
+  const parts = [`${live.source}:${live.volname}`];
+  for (const [key, value] of declared.options) parts.push(`${key}=${value}`);
+  if (live.sizeText !== undefined) parts.push(`size=${live.sizeText}`);
+  return parts.join(',');
+};
+
+export const judgeVolume = (key: string, declared: string, live: string): VolumeVerdict => {
+  const want = parseVolume(declared);
+  const have = parseVolume(live);
+  if (isHostPath(want) || isHostPath(have)) {
+    const same =
+      want.kind === have.kind && want.source === have.source && sameMap(want.options, have.options);
+    return same ? {} : { rootOnly: true };
+  }
+  if (want.source !== have.source) {
+    return {
+      refuse:
+        `${key}: the volume is on ${have.source}, declared on ${want.source}. Moving it is ` +
+        '`pct move-volume` (a copy), not a config update -- move it by hand, then declare it.',
+    };
+  }
+  if (want.kind === 'volume' && want.volname !== have.volname) {
+    return {
+      refuse:
+        `${key}: declared volume ${want.volname} is not the live ${have.volname}. Writing it would ` +
+        'detach the live volume to unusedN; attach or swap volumes by hand.',
+    };
+  }
+  let resize: string | undefined;
+  if (want.size !== undefined && have.size !== undefined && want.size !== have.size) {
+    if (want.size < have.size) {
+      return {
+        refuse:
+          `${key}: declared ${want.sizeText ?? '?'} is smaller than the live ` +
+          `${have.sizeText ?? '?'}. PVE cannot shrink a container volume ("unable to shrink disk ` +
+          'size"), and replacing the guest to get there is not an update this resource makes.',
+      };
+    }
+    resize = want.sizeText;
+  }
+  const put = sameMap(want.options, have.options) ? undefined : rewrite(have, want);
+  return {
+    ...(put === undefined ? {} : { put }),
+    ...(resize === undefined ? {} : { resize }),
+  };
+};