@homeflare/alchemy 0.38.0 → 0.40.0

package/src/proxmox/qemu-props.ts

@@ -0,0 +1,157 @@
+/**
+ * What a `Proxmox.Vm` declaration says, and what its state keeps.
+ *
+ * ★ THE SAME "DECLARED KEYS" MODEL AS `Proxmox.Lxc` (lxc-props.ts, joined 2026-09-21): an
+ *   undeclared key is UNMANAGED — never sent, never compared, never overwritten. Adopting a live
+ *   VM is then a paste of its config, not a translation of it, and the wire spelling is PVE's own
+ *   (`scsi0`, `net0`, `ipconfig0`, as `pvesh get .../qemu/{vmid}/config` prints them).
+ *
+ * ⛔ THIS REPLACES THE "5-DEFAULT PUT". Before 2026-09-26, `qemu-form.ts`'s `shape()` sent
+ *   `cores`/`memory`/`name`/`onboot`/`sockets` on EVERY write with a hard default substituted for
+ *   whichever of the five was left undeclared, so declaring only `memory: 4096` on an adopted VM
+ *   still PUT `name: 'vm101'` and `sockets: '1'` over whatever the guest actually had. Harmless
+ *   while `ProxmoxVm` stayed Provider-only (nothing declared it), load-bearing the moment Talos
+ *   does. `declaredKeys` below is the fix: a field absent from the declaration is never read,
+ *   never compared and never written — see qemu-form.ts's `form()`.
+ *
+ * ⛔ NO SECRET IS A PROP. `cipassword` (cloud-init's password) is write-only and Alchemy persists
+ *   props in plaintext (this estate's state store is dumped nightly) — typed `never`, exactly
+ *   like lxc-props.ts's `password`. A VM that needs a login uses `sshkeys`-free image defaults or
+ *   an out-of-band secret; this resource never carries one.
+ * ⛔ `machine` IS NEVER A PROP EITHER. It pins the emulated chipset/firmware revision a guest boots
+ *   against; PVE already resolves it from the node's installed QEMU version, and declaring it here
+ *   would fight every future node upgrade instead of tracking it. Typed `never` for the same
+ *   reason `cipassword` is: a cast is the only way in, and this file's helpers below never read
+ *   an unmanaged key onto the wire regardless.
+ */
+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 VmProps extends WithTarget {
+  /** ⛔ This resource never migrates: qemu-read.ts refuses a VM found on another node. */
+  node: string;
+  /** ⛔ Cluster-wide, and shared with LXC. See qemu.ts's header. */
+  vmid: number;
+  name?: string;
+  /** MiB. */
+  memory?: number;
+  cores?: number;
+  sockets?: number;
+  /** Emulated CPU type, e.g. `host`. */
+  cpu?: string;
+  onboot?: PveFlag;
+  /** The QEMU guest agent. Talos reports its addresses through it once this is enabled. */
+  agent?: PveFlag;
+  /** `order=scsi0;ide2;net0`. */
+  boot?: string;
+  /** e.g. `virtio-scsi-single`. */
+  scsihw?: string;
+  /**
+   * `local-zfs:32` to create a new volume, or the live volume string as adopted —
+   * `cephtb4:vm-101-disk-0,size=32G` (n is 0 to 30, pve-qemu-server's own `$MAX_SCSI_DISKS`).
+   */
+  [scsi: `scsi${number}`]: string | undefined;
+  /**
+   * `virtio=<mac>,bridge=vmbr0,tag=<vlan>` — a VLAN-aware bridge with an 802.1q tag is a bridge
+   * plus this one sub-property; PVE's SDN stays out of it entirely (n is 0 to 31).
+   */
+  [nic: `net${number}`]: string | undefined;
+  /**
+   * The cloud-init drive, e.g. `cephtb4:cloudinit`. PVE's own web UI puts it on `ide2`, but any
+   * free `ide`/`sata`/`scsi` slot works; declaring one is what gives `ipconfig0` below somewhere
+   * to write the generated seed image (n is 0 to 3).
+   */
+  [cloudinit: `ide${number}`]: string | undefined;
+  /** cloud-init network config: `ip=dhcp`, or `ip=<cidr>,gw=<gw>` (n is 0 to 31). */
+  [ipconfig: `ipconfig${number}`]: string | undefined;
+  /** `socket` — a serial console, the way Talos exposes its own (n is 0 to 3). */
+  [serial: `serial${number}`]: string | undefined;
+  /** ⛔ A secret. See the header. */
+  cipassword?: never;
+  /** ⛔ Machine config. See the header. */
+  machine?: never;
+}
+
+export interface VmAttributes {
+  node: string;
+  vmid: number;
+  /** The live config, MANAGED keys only — see `storedConfig`. An allowlist, not a mirror. */
+  config: Record<string, string>;
+}
+
+/** Props that identify the object rather than configure it: never sent, never compared. */
+const NOT_CONFIG: ReadonlySet<string> = new Set(['node', 'target', 'vmid']);
+
+/** The indexed families this resource manages, with pve-qemu-server's own published range. */
+export const INDEXED = {
+  ide: 4,
+  ipconfig: 32,
+  net: 32,
+  scsi: 31,
+  serial: 4,
+} as const;
+export type IndexedFamily = keyof typeof INDEXED;
+
+/** `scsi3` → `['scsi', 3]`; anything else, including an out-of-range index, → undefined. */
+export const indexedKey = (key: string): readonly [IndexedFamily, number] | undefined => {
+  const match = /^(ide|ipconfig|net|scsi|serial)(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;
+};
+
+/** The scalar (non-indexed) keys this resource manages. */
+const SCALAR_KEYS: ReadonlySet<string> = new Set([
+  'agent',
+  'boot',
+  'cores',
+  'cpu',
+  'memory',
+  'name',
+  'onboot',
+  'scsihw',
+  'sockets',
+]);
+
+/**
+ * A key this resource compares and may write. ⛔ EVERYTHING ELSE IS REFUSED, NEVER SILENTLY
+ *   DROPPED OR SILENTLY SENT — `qemu-form.ts`'s `formRefusals` is what a declared key smuggled
+ *   past the types (a cast, a JS caller: `cipassword`, `machine`, `hookscript`) meets before any
+ *   write, the same rule `lxc-create-form.ts` enforces for `Proxmox.Lxc`.
+ */
+export const isManagedKey = (key: string): boolean =>
+  SCALAR_KEYS.has(key) || indexedKey(key) !== undefined;
+
+/** A declaration read by key. ⚠️ The cast is the one place a template-literal index meets a plain string. */
+export const declaredValue = (props: VmProps, key: string): unknown =>
+  (props as unknown as Record<string, unknown>)[key];
+
+/** The declared keys with a value, in a stable order — never `node`/`target`/`vmid`. */
+export const declaredKeys = (props: VmProps): 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);
+
+/**
+ * The live config as strings: managed keys only.
+ * ⛔ AN ALLOWLIST, NOT "EVERYTHING BUT A DENYLIST" — same reasoning as `lxc-props.ts`'s
+ *   `storedConfig`. `digest` covers the whole file, `lock`/`pending` are transient, and a future
+ *   PVE release's new key does not land in this estate's unencrypted state store until this
+ *   resource is taught to manage it.
+ */
+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)) continue;
+    if (value === null || value === undefined || typeof value === 'object') continue;
+    out[key] = wireValue(value);
+  }
+  return out;
+};

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

@@ -0,0 +1,229 @@
+/**
+ * Pure unit tests for `judgeDisk` — the red-team C1 fix on PR 297. No network, no fake PVE.
+ * ⛔ WHAT THESE PIN: a "fresh" declaration (new-disk GiB, `storage:cloudinit`, or
+ *   `storage:0,import-from=...`) never re-drifts against an existing live volume in the same slot;
+ *   a genuine volume/storage swap is refused, never written; a size change is refused (no resize
+ *   call exists here); an option-only change is written on the LIVE volume id and LIVE size.
+ */
+import { describe, expect, test } from 'bun:test';
+import { judgeDisk, parseDisk } from './qemu-volume.ts';
+
+describe('a "fresh" declaration matches any existing volume in its slot', () => {
+  test('new-disk GiB spelling: the measured C1 regression', () => {
+    expect(judgeDisk('scsi0', 'cephtb4:32', 'cephtb4:vm-101-disk-0,size=32G')).toEqual({});
+  });
+
+  test('cloud-init spelling, QEMU-only: no LXC equivalent', () => {
+    expect(judgeDisk('ide2', 'cephtb4:cloudinit', 'cephtb4:vm-101-cloudinit,media=cdrom')).toEqual(
+      {},
+    );
+  });
+});
+
+/**
+ * The disk-import convergence bug homeflare-proxmox PR 84's red team found (2026-09-26, real
+ * fake-PVE engine): `judgeDisk` never recognized `<storage>:0,import-from=<volid>` as a new-disk
+ * spelling, so it compared the literal volname `"0"` against PVE's live read-back of the real
+ * `vm-<vmid>-disk-<n>` it allocated on import and refused -- on the very deploy that created the
+ * disk, and on every plan after (Talos's `declareTalos` declares the import spelling every time,
+ * never switches to the resolved volname). Each `judgeDisk` call below stands in for one PVE read
+ * a real Talos deploy makes; none of them are a live PVE call.
+ */
+describe('the import-from create spelling converges (PR 84 red team)', () => {
+  const IMPORT_DECLARED = 'cephtb4:0,import-from=cephfs-tb4:import/talos-factory.raw';
+
+  test('create: post-write verification reads back the real volume PVE allocated', () => {
+    // The deploy that creates the VM re-reads the config right after the PUT to verify it landed.
+    // Before the fix this was refused (declared volname "0" vs live "vm-10000-disk-0").
+    expect(judgeDisk('scsi0', IMPORT_DECLARED, 'cephtb4:vm-10000-disk-0,size=2G')).toEqual({});
+  });
+
+  test('re-plan: the same declared import spelling against the now-adopted live disk', () => {
+    // A later `bun run plan` fabricates the same live read as create did; declared is unchanged
+    // (declareTalos always emits import-from, never the resolved volname). Must still be a no-op.
+    const verdict = judgeDisk('scsi0', IMPORT_DECLARED, 'cephtb4:vm-10000-disk-0,size=2G');
+    expect(verdict.refuse).toBeUndefined();
+    expect(verdict.put).toBeUndefined();
+  });
+
+  test('second deploy: PVE has since filled in defaults the fresh check must not treat as drift', () => {
+    // pve-qemu-server fills in options nobody declared (ssd/discard/etc.). A "fresh" declaration
+    // skips option comparison entirely, so this must be a no-op too -- not a PUT trying to "fix"
+    // options that were never wrong, and not a resize of the placeholder "0" against the real size.
+    const verdict = judgeDisk(
+      'scsi0',
+      IMPORT_DECLARED,
+      'cephtb4:vm-10000-disk-0,size=2G,ssd=1,discard=on',
+    );
+    expect(verdict).toEqual({});
+  });
+
+  test('no resize is ever attempted for an import-from disk', () => {
+    // The live size (2G, from the imported image) never appears in a `put` -- there is no `put` at
+    // all, because `want.kind === 'fresh'` returns before size or options are ever inspected.
+    expect(judgeDisk('scsi0', IMPORT_DECLARED, 'cephtb4:vm-10000-disk-0,size=200G')).toEqual({});
+  });
+
+  test('a volid with its own colon (storage:path) still parses as one fresh spelling', () => {
+    // import-from points at cephfs-tb4:import/talos-factory.raw -- a second colon inside the value,
+    // which a colon-anchored regex could truncate. Confirms the whole declared string is consumed.
+    expect(
+      judgeDisk(
+        'scsi0',
+        'cephtb4:0,import-from=cephfs-tb4:import/talos-factory.raw',
+        'cephtb4:vm-10042-disk-0,size=2G',
+      ),
+    ).toEqual({});
+  });
+
+  test('a genuine size mismatch on an already-adopted volume is still refused', () => {
+    // Not an import-from declaration: a plain adopted volume whose declared size disagrees with the
+    // live one. Must still hit the existing no-resize refusal, unchanged by the new spelling.
+    const verdict = judgeDisk(
+      'scsi0',
+      'cephtb4:vm-10000-disk-0,size=4G',
+      'cephtb4:vm-10000-disk-0,size=2G',
+    );
+    expect(verdict.refuse).toMatch(/does not resize a disk/);
+    expect(verdict.put).toBeUndefined();
+  });
+
+  test('volname "0" without import-from is not swept into the new "fresh" spelling', () => {
+    // Guards NEW_IMPORT's literal ",import-from=" requirement: a coincidental "storage:0,k=v" (no
+    // import-from) must still be judged as a real volume named "0", not treated as always-matching.
+    const verdict = judgeDisk('scsi0', 'cephtb4:0,ssd=1', 'cephtb4:vm-10000-disk-0,size=2G');
+    expect(verdict.refuse).toMatch(/is not the live vm-10000-disk-0/);
+  });
+
+  test('a mismatched storage on an import-from declaration is still refused, not silently matched', () => {
+    // "fresh" only skips the volname/size/options checks -- the storage check above it still runs.
+    const verdict = judgeDisk(
+      'scsi0',
+      'cephtb4:0,import-from=cephfs-tb4:import/talos-factory.raw',
+      'local-zfs:vm-10000-disk-0,size=2G',
+    );
+    expect(verdict.refuse).toMatch(/the volume is on local-zfs, declared on cephtb4/);
+  });
+});
+
+/**
+ * The LAND red team's Important finding on this same PR (2026-09-26): options declared alongside
+ * `import-from` were either silently dropped (declared after it -- `.+` swallowed them uncompared)
+ * or stranded the disk forever (declared before it -- missed the old regex, fell to the `volume`
+ * branch, and got refused against the real live volname just like the bug this file fixes). Fixed by
+ * detecting `import-from` after the general comma split instead of a position-anchored regex.
+ */
+describe('options declared alongside import-from are enforced, in either order (LAND red team)', () => {
+  const IMPORT = 'cephtb4:0,import-from=cephfs-tb4:import/talos-factory.raw';
+
+  test('an option after import-from that already matches live is a noop', () => {
+    const verdict = judgeDisk(
+      'scsi0',
+      `${IMPORT},iothread=1`,
+      'cephtb4:vm-150-disk-0,iothread=1,size=2G',
+    );
+    expect(verdict).toEqual({});
+  });
+
+  test('an option after import-from that disagrees with live is written, on the live volume id', () => {
+    // Scenario B from the red team: iothread was declared and honored at create; discard/ssd are
+    // added later. Before this fix, verify said `noop` and the deploy wrote nothing.
+    const verdict = judgeDisk(
+      'scsi0',
+      `${IMPORT},iothread=1,discard=on,ssd=1`,
+      'cephtb4:vm-150-disk-0,iothread=1,size=2G',
+    );
+    expect(verdict.put).toBe('cephtb4:vm-150-disk-0,iothread=1,discard=on,ssd=1,size=2G');
+  });
+
+  test('an option BEFORE import-from is still recognized as fresh, not a stranded volume', () => {
+    // Scenario C from the red team: `cephtb4:0,iothread=1,import-from=...` missed the old
+    // position-anchored regex entirely and was refused forever as a volname "0" vs the live one.
+    const verdict = judgeDisk(
+      'scsi0',
+      'cephtb4:0,iothread=1,import-from=cephfs-tb4:import/talos-factory.raw',
+      'cephtb4:vm-150-disk-0,iothread=1,size=2G',
+    );
+    expect(verdict).toEqual({});
+  });
+
+  test('a live-only default the caller never declared is not treated as drift', () => {
+    // Only iothread was declared; ssd/discard are PVE's own fill-in. A full-map compare (sameMap)
+    // would call this drift and rewrite the disk on every plan -- the subset check must not.
+    const verdict = judgeDisk(
+      'scsi0',
+      `${IMPORT},iothread=1`,
+      'cephtb4:vm-150-disk-0,iothread=1,size=2G,ssd=1,discard=on',
+    );
+    expect(verdict).toEqual({});
+  });
+});
+
+describe('an existing-volume declaration', () => {
+  const live = 'cephtb4:vm-101-disk-0,size=32G,ssd=1';
+
+  test('matching options is a noop', () => {
+    expect(judgeDisk('scsi0', live, live)).toEqual({});
+  });
+
+  test('a different storage is refused, never written', () => {
+    const verdict = judgeDisk('scsi0', 'other:vm-101-disk-0,size=32G,ssd=1', live);
+    expect(verdict.refuse).toMatch(/the volume is on cephtb4, declared on other/);
+    expect(verdict.put).toBeUndefined();
+  });
+
+  test('a different volume on the same storage is refused: it would detach the live one', () => {
+    const verdict = judgeDisk('scsi0', 'cephtb4:vm-101-disk-9,size=32G', live);
+    expect(verdict.refuse).toMatch(/detach the live volume to unusedN/);
+  });
+
+  test('a declared size difference is refused: this resource does not resize', () => {
+    const verdict = judgeDisk('scsi0', 'cephtb4:vm-101-disk-0,size=64G,ssd=1', live);
+    expect(verdict.refuse).toMatch(/does not resize a disk/);
+  });
+
+  test('an option-only change writes the LIVE volume id and LIVE size, not the declared ones', () => {
+    const verdict = judgeDisk('scsi0', 'cephtb4:vm-101-disk-0,size=32G,ssd=0', live);
+    expect(verdict.put).toBe('cephtb4:vm-101-disk-0,ssd=0,size=32G');
+  });
+
+  test('the cloud-init slot has no size to carry: the PUT omits it rather than writing size=', () => {
+    const cloudinitLive = 'cephtb4:vm-101-cloudinit,media=cdrom';
+    const verdict = judgeDisk(
+      'ide2',
+      'cephtb4:vm-101-cloudinit,media=cdrom,readonly=1',
+      cloudinitLive,
+    );
+    expect(verdict.put).toBe('cephtb4:vm-101-cloudinit,media=cdrom,readonly=1');
+  });
+});
+
+describe('parseDisk', () => {
+  test('a bare new-disk spelling has no volname and no size stored as an option', () => {
+    expect(parseDisk('cephtb4:32')).toEqual({
+      kind: 'fresh',
+      options: new Map(),
+      size: undefined,
+      source: 'cephtb4',
+      volname: '',
+    });
+  });
+
+  test('an existing volume splits size out of the options map', () => {
+    const disk = parseDisk('cephtb4:vm-101-disk-0,size=32G,ssd=1');
+    expect(disk.kind).toBe('volume');
+    expect(disk.volname).toBe('vm-101-disk-0');
+    expect(disk.size).toBe('32G');
+    expect(disk.options).toEqual(new Map([['ssd', '1']]));
+  });
+
+  test('the import-from spelling parses as fresh, same shape as the other two', () => {
+    expect(parseDisk('cephtb4:0,import-from=cephfs-tb4:import/talos-factory.raw')).toEqual({
+      kind: 'fresh',
+      options: new Map(),
+      size: undefined,
+      source: 'cephtb4',
+      volname: '',
+    });
+  });
+});

package/src/proxmox/qemu-volume.ts

@@ -0,0 +1,178 @@
+/**
+ * `scsiN` and `ideN`: what a declared disk may change on a live VM, and how.
+ *
+ * ★ PORTED FROM lxc-volume.ts (2026-09-26, red-team C1 on PR 297): pve-qemu-server shares the same
+ *   "new-disk spelling" rule pve-container has. `storage:GiB` in a PUT means "allocate a fresh
+ *   volume" — so a declared `cephtb4:32` that already has a live `cephtb4:vm-101-disk-0,size=32G`
+ *   in that slot must compare EQUAL, never be re-sent. Measured by the builder's red team: resending
+ *   it allocated a second volume every deploy and parked the guest's real disk at `unusedN` (or left
+ *   the swap pending on a running boot disk until the next reboot).
+ * ⚠️ `ideN` HAS A SECOND NEW-VOLUME SPELLING QEMU DOES NOT SHARE WITH LXC: `<storage>:cloudinit`
+ *   creates a fresh cloud-init seed drive; the live slot then reads back
+ *   `<storage>:vm-<vmid>-cloudinit,media=cdrom`. Both spellings compare equal to an existing volume
+ *   already in the slot, for the same reason `storage:GiB` does.
+ * ⛔ A THIRD NEW-VOLUME SPELLING, FOUND BY homeflare-proxmox PR 84's RED TEAM (2026-09-26, real
+ *   fake-PVE engine): `<storage>:0,import-from=<volid>` imports a disk from another volume or a
+ *   downloaded image at create time. Before this fix it fell through to the `volume` branch below
+ *   (it has a comma, so `NEW_DISK` never matched it), so `want.volname` stayed the literal `"0"`
+ *   forever while PVE's live read-back reported the real `vm-<vmid>-disk-<n>` it allocated on
+ *   import -- a volname mismatch, REFUSED. That refusal fired on the very deploy that created the
+ *   disk (post-write verification reads the config right back) and on every plan after, because
+ *   the declared value is `import-from=...` again each time (Talos's `declareTalos` recomputes it
+ *   from the download resource, never switches to the resolved volname). Fixed the same way as the
+ *   other two: an `import-from` disk also counts as `kind: 'fresh'`, which already matches whatever
+ *   is live unconditionally when nothing else is declared (see `want.kind === 'fresh'` below) -- no
+ *   special-casing of the live side needed.
+ * ⛔ IMPORT-FROM IMPORTS ONLY AT CREATE. Changing just the `import-from=` *source* (e.g. bumping a
+ *   factory image path) on an already-created disk still reads as `noop`: PVE does not re-import an
+ *   existing volume, and this resource has no rebuild-the-disk path. That is correct for Talos, which
+ *   upgrades in place through `talosctl`, not by recreating its disk -- a caller that DOES want a
+ *   fresh import on image change must delete and recreate the row itself.
+ * ⛔ LAND RED TEAM (2026-09-26): OPTIONS DECLARED ALONGSIDE `import-from` MUST STILL BE ENFORCED, AND
+ *   MUST BE RECOGNIZED REGARDLESS OF WHERE `import-from` SITS IN THE LIST. The first cut matched
+ *   `import-from` only when it came immediately after `:0,`, via a regex whose `.+` then swallowed
+ *   every option after it uncompared (silently never written) while any option declared BEFORE it
+ *   (`cephtb4:0,iothread=1,import-from=...`) missed the regex entirely and fell to the `volume`
+ *   branch, comparing literal volname `"0"` against the live real one forever -- REFUSED, same
+ *   stranded-disk failure this file exists to fix, just for a different option order. Fixed by
+ *   folding the import check into the general `storage:volname,k=v,...` parse below: ANY declaration
+ *   whose volname is the literal `"0"` and whose options include an `import-from` key is `fresh`,
+ *   with `import-from` itself dropped and every other declared option carried through for
+ *   `judgeDisk` to enforce (see its `want.kind === 'fresh'` branch) -- independent of option order.
+ * ⛔ NO RESIZE IS MADE HERE. lxc-volume.ts drives a second endpoint (`PUT .../resize`) this resource
+ *   does not call — Talos's disks are declared once at their create size. A size difference between
+ *   two already-adopted volume declarations is REFUSED with the `qm resize` to run by hand, never
+ *   guessed at or silently written.
+ * ⚠️ OPTIONS BEYOND `size` ARE COMPARED AS A WHOLE, NOT KEY BY KEY, FOR AN ADOPTED `volume` -- BUT AS
+ *   A SUBSET FOR A `fresh` IMPORT. Unlike lxc-volume.ts, this file does not model pve-qemu-server's
+ *   per-option defaults (`ssd`, `discard`, `iothread`, …) — that table is unverified here. For an
+ *   already-adopted volume, any options difference from live is real drift and gets written in full,
+ *   exactly as the whole-string comparison this replaces already did. An `import-from` disk cannot
+ *   use that same whole-map comparison: nobody declares PVE's post-import defaults, so comparing the
+ *   full map would treat every default PVE fills in as drift and rewrite the disk on every plan (the
+ *   builder's "second deploy" test below pins this). So a `fresh` import instead checks only the
+ *   options the caller actually declared against live, ignoring any live-only keys, and PUTs the
+ *   declared options (not merged with what live already has) when one of them disagrees.
+ */
+import { sameMap } from './lxc-wire.ts';
+
+/** PVE's own new-disk spelling: `storage:SIZE`, SIZE in GiB, fractional allowed. */
+const NEW_DISK = /^([^:\s]+):(\d+(?:\.\d+)?)$/;
+/** The `ideN` cloud-init-drive spelling — QEMU only, no GiB, no LXC equivalent. */
+const NEW_CLOUDINIT = /^([^:\s]+):cloudinit$/;
+
+export type Disk = {
+  /** `fresh`: a new-disk spelling (`storage:GiB`, `storage:cloudinit`, or `storage:0,import-from=...`
+   *  possibly with more options). `volume`: an existing volume, `storage:volname,...`. */
+  readonly kind: 'fresh' | 'volume';
+  readonly source: string;
+  readonly volname: string;
+  readonly size: string | undefined;
+  readonly options: Map<string, string>;
+};
+
+/**
+ * `storage:volname,k=v,...` (or one of the "fresh" spellings) into its comparable parts.
+ * ⚠️ THE IMPORT SPELLING IS DETECTED AFTER THE GENERAL SPLIT, NOT BY ITS OWN REGEX: `import-from`'s
+ *   value can itself contain a colon (e.g. `cephfs-tb4:import/talos-factory.raw`) and other options
+ *   can come before or after it, so a regex anchored on `:0,import-from=` right after the colon (as
+ *   the first cut had) misses that ordering and swallows everything after it into one opaque match.
+ *   Splitting on commas like any `volume` spelling first, THEN checking for a literal `"0"` volname
+ *   plus an `import-from` key among the parsed options, catches every ordering and keeps every other
+ *   declared option (`iothread=1`, `discard=on`, …) visible to `judgeDisk` instead of swallowed.
+ */
+export const parseDisk = (text: string): Disk => {
+  const bare = NEW_DISK.exec(text) ?? NEW_CLOUDINIT.exec(text);
+  if (bare !== null) {
+    return {
+      kind: 'fresh',
+      options: new Map(),
+      size: undefined,
+      source: bare[1] ?? '',
+      volname: '',
+    };
+  }
+  const [first, ...rest] = text.split(',');
+  const at = (first ?? '').indexOf(':');
+  const source = at === -1 ? (first ?? '') : (first ?? '').slice(0, at);
+  const volname = at === -1 ? '' : (first ?? '').slice(at + 1);
+  const options = new Map(
+    rest.map((part): [string, string] => {
+      const eq = part.indexOf('=');
+      return eq === -1 ? [part, ''] : [part.slice(0, eq), part.slice(eq + 1)];
+    }),
+  );
+  const size = options.get('size');
+  options.delete('size');
+  if (volname === '0' && options.has('import-from')) {
+    options.delete('import-from');
+    return { kind: 'fresh', options, size: undefined, source, volname: '' };
+  }
+  return { kind: 'volume', options, size, source, volname };
+};
+
+export type DiskVerdict = {
+  readonly refuse?: string;
+  /** The value to PUT, built on the LIVE volume id and LIVE size — never the declared spelling. */
+  readonly put?: string;
+};
+
+/**
+ * A map back to `key=value,...` — mirrors lxc-wire.ts's `printMap`.
+ * ⚠️ `size` OMITTED WHEN THE LIVE SLOT HAS NONE (the cloud-init drive: no GiB figure to carry).
+ *   Writing `size=` empty is not a value PVE's own parser accepts.
+ */
+const printOptions = (
+  source: string,
+  volname: string,
+  options: Map<string, string>,
+  size: string | undefined,
+) =>
+  [
+    `${source}:${volname}`,
+    ...[...options].map(([k, v]) => `${k}=${v}`),
+    ...(size === undefined ? [] : [`size=${size}`]),
+  ].join(',');
+
+export const judgeDisk = (key: string, declared: string, live: string): DiskVerdict => {
+  const want = parseDisk(declared);
+  const have = parseDisk(live);
+  if (want.source !== have.source) {
+    return {
+      refuse:
+        `${key}: the volume is on ${have.source}, declared on ${want.source}. Moving a disk ` +
+        'between storages is not an update this resource makes -- move it by hand, then declare it.',
+    };
+  }
+  // ⛔ A "fresh" declaration never re-triggers create: PVE holds a real volume in this slot already,
+  //   and re-sending storage:GiB / storage:cloudinit / storage:0,import-from=... as the PUT value
+  //   would allocate a SECOND volume and park the live one at unusedN (the header's ⛔, ported from
+  //   lxc-volume.ts's own). So a `fresh` PUT, when one is needed, is always built from the LIVE
+  //   volume id (`have.volname`/`have.size`), never the declared placeholder -- same as `volume`.
+  // ⚠️ ONLY THE OPTIONS THE CALLER ACTUALLY DECLARED ARE CHECKED (a subset, not `sameMap`): nobody
+  //   declares PVE's post-import defaults, so an empty `want.options` (plain import-from, nothing
+  //   else declared) is always a noop no matter what live has filled in, and a non-empty one is
+  //   compared key-by-key against live, ignoring any key live has that the caller never declared.
+  if (want.kind === 'fresh') {
+    if (want.options.size === 0) return {};
+    if ([...want.options].every(([k, v]) => have.options.get(k) === v)) return {};
+    return { put: printOptions(have.source, have.volname, want.options, have.size) };
+  }
+  if (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.',
+    };
+  }
+  if (want.size !== undefined && have.size !== undefined && want.size !== have.size) {
+    return {
+      refuse:
+        `${key}: declared size ${want.size} differs from the live ${have.size}. This resource does ` +
+        'not resize a disk -- grow it by hand (`qm resize`) and declare the size it then reports.',
+    };
+  }
+  if (sameMap(want.options, have.options)) return {};
+  // ⚠️ THE LIVE SIZE, NOT THE DECLARED ONE — see the header's ⛔ on why no resize happens here.
+  return { put: printOptions(have.source, have.volname, want.options, have.size) };
+};

package/src/proxmox/qemu.ts

@@ -1,5 +1,7 @@
 /**
- * `Proxmox.Vm` — a QEMU virtual machine, declared.
+ * `Proxmox.Vm` — a QEMU virtual machine, declared. Exported (not just Provider-only) since
+ * 2026-09-26 for Talos: see qemu-props.ts for what a declaration may say and why `cipassword`
+ * and `machine` may never be one of them.
  *
  * ⚠️ CREATE is `POST /nodes/{node}/qemu`. GET and PUT stay on `.../qemu/{vmid}/config`.
  *   ⛔ DELETE is `DELETE /nodes/{node}/qemu/{vmid}` (`destroy_vm` in qemu-server Qemu.pm). The
@@ -10,39 +12,22 @@
  *   collision Alchemy can see -- they are different resource types -- and PVE refuses the second
  *   with "already exists". Pick ids per cluster, not per kind.
  *
- * ⚠️ POWER STATE IS REPORTED, NEVER DECLARED. `status` is an attribute so a plan can show it; there
- *   is no `running` prop. Starting and stopping a VM from a plan would make a deploy a maintenance
- *   window, and the estate has one of those already.
+ * ⛔ THIS RESOURCE NEVER MIGRATES. `qemu-read.ts` refuses the plan outright when the declared vmid
+ *   is found running on a DIFFERENT node than the one declared ("A migration is not an update") --
+ *   unchanged by the 2026-09-26 export, and exactly what keeps a node-pinned Talos VM pinned.
+ *
+ * ⚠️ POWER STATE IS NEITHER DECLARED NOR REPORTED. There is no `running` prop and `VmAttributes`
+ *   carries no `status` field (qemu-props.ts) — starting and stopping a VM from a plan would make a
+ *   deploy a maintenance window, and the estate has one of those already.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import { qemuHandlers } from './qemu-lifecycle.ts';
-import type { PveRequirements, WithTarget } from './resource.ts';
-
-export interface VmProps extends WithTarget {
-  node: string;
-  /** ⛔ Cluster-wide, and shared with LXC. See the ⛔ above. */
-  vmid: number;
-  name?: string;
-  /** MiB. */
-  memory?: number;
-  cores?: number;
-  sockets?: number;
-  /** e.g. `virtio=<mac>,bridge=vmbr0`. */
-  net0?: string;
-  onboot?: boolean;
-}
+import type { PveRequirements } from './resource.ts';
+import type { VmAttributes, VmProps } from './qemu-props.ts';
 
-export interface VmAttributes {
-  vmid: number;
-  node: string;
-  name: string;
-  memory: number;
-  cores: number;
-  sockets: number;
-  onboot: boolean;
-}
+export type { VmAttributes, VmProps } from './qemu-props.ts';
 
 export interface ProxmoxVm extends Resource<
   'Proxmox.Vm',
@@ -52,7 +37,8 @@ export interface ProxmoxVm extends Resource<
   PveRequirements
 > {}
 
-export const ProxmoxVm = Resource<ProxmoxVm>('Proxmox.Vm');
+/** ★ `retain` by default — a VM's disks cannot be rebuilt from a line. See resource.ts / lxc.ts. */
+export const ProxmoxVm = Resource<ProxmoxVm>('Proxmox.Vm', { defaultRemovalPolicy: 'retain' });
 
 export { createForm } from './qemu-form.ts';
 

package/src/proxmox/storage-download-errors.ts

@@ -0,0 +1,7 @@
+/** A `Proxmox.StorageDownload` write or observation this provider will not turn into a claim of success. */
+export class StorageDownloadRefusedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'StorageDownloadRefusedError';
+  }
+}