@homeflare/alchemy 0.38.0 → 0.39.0

package/src/proxmox/generated/constraints/pve-cluster-ceph.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-firewall.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-ha.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-metrics.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-notifications.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-replication.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-sdn.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-ceph.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-disks.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-lxc.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-network.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-qemu.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-storage.ts

@@ -0,0 +1,30 @@
+/**
+ * Generated pve-manager parameter constraints for `/nodes/{node}/storage` — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/constraints.ts
+ * Manifest entry: `pve-apidoc` — pve-manager 9.2.11/f6997e698c7933ea
+ *   sha256 9def8f13611184ee, read on a PVE cluster node from
+ *   /usr/share/pve-docs/api-viewer/apidoc.js
+ *
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
+ * and therefore unchecked at plan time.
+ *
+ * ⚠️ A `patternSource` with no `pattern` beside it is a rule that could NOT be carried into a
+ *   JavaScript RegExp faithfully (codegen/pattern.ts). It is recorded and NOT enforced.
+ * ⚠️ `pattern` IS NOT THE VENDOR'S SPELLING. For PVE it is anchored, because PVE applies
+ *   `m/^$pattern$/` itself (JSONSchema.pm); for PBS it is the vendor's own, which already
+ *   carries its anchors. `patternSource` is the spelling to quote at a human — param-rules.ts.
+ * ⚠️ `each: true` means the value rules describe every ELEMENT of a repeated key, because the
+ *   parameter is an array and stated its limits on `items`.
+ */
+import type { EndpointConstraints } from '../../constraints.ts';
+
+export const PVE_NODES_STORAGE_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>> = {
+  "pve:POST /nodes/{node}/storage/{storage}/download-url": {
+    "checksum-algorithm": {"enum":["md5","sha1","sha224","sha256","sha384","sha512"],"type":"string"},
+    "content": {"enum":["iso","vztmpl","import"],"format":"pve-storage-content","required":true,"type":"string"},
+    "filename": {"maxLength":255,"required":true,"type":"string"},
+    "url": {"pattern":"^https?://.*\\n?$","patternSource":"https?://.*","required":true,"type":"string"},
+  },
+};

package/src/proxmox/generated/constraints/pve-pools.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-storage.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/index.test.ts

@@ -1,15 +1,19 @@
 /**
- * Public barrel: control-plane Resource constructors and `ProxmoxLxc`, not QEMU or NIC apply.
+ * Public barrel: control-plane Resource constructors and `ProxmoxLxc`, not NIC apply.
  *
- * ⛔ 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).
+ * ⛔ 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).
  * ★ CephDaemon, CephFs and CephOsd are Resources since 2026-09-22: adopt-only by shape and retain
  *   on destroy (ceph-adopt.test.ts). ⛔ CephFlag stays Provider-only: a declared flag reasserts a
  *   maintenance toggle on every deploy (ceph-flag.ts).
  * ★ ApiToken and ZfsPool are Resources since 2026-09-23, decision 9: ApiToken metadata-only,
  *   ZfsPool adopt-only when `devices`/`raidlevel` are left undeclared (api-token-adopt.test.ts,
  *   zfs-pool-adopt.test.ts).
+ * ★ Vm and StorageDownload are Resources since 2026-09-26, for Talos: Vm's declared-keys model
+ *   (qemu-props.ts) and retain-by-default; StorageDownload's checksum-pinned, create-oriented
+ *   `download-url` (storage-download.ts). Neither was Provider-only for a design reason that
+ *   changed — Vm's old "5-default PUT" is what kept it off this barrel until qemu-props.ts fixed
+ *   it, per qemu-lifecycle.test.ts's own regression test.
  */
 import { expect, test } from 'bun:test';
 import { PbsDatastore, ProxmoxStorage } from './index.ts';
@@ -42,7 +46,9 @@ const resourceExports = [
   'ProxmoxSdnVnet',
   'ProxmoxSdnZone',
   'ProxmoxStorage',
+  'ProxmoxStorageDownload',
   'ProxmoxUser',
+  'ProxmoxVm',
   'ProxmoxZfsPool',
 ] as const;
 
@@ -61,8 +67,7 @@ test('the provisioning baseline is on the barrel: the list, the declaration, the
   expect(barrel.provisionBootstrap()).toStartWith('#!/bin/sh\n');
 });
 
-test('QEMU, NIC apply and the Ceph flag stay Provider-only', () => {
-  expect(src).not.toMatch(/export \{ ProxmoxVm[, }]/);
+test('NIC apply and the Ceph flag stay Provider-only', () => {
   expect(src).not.toMatch(/export \{ ProxmoxNodeNetwork[, }]/);
   expect(src).not.toMatch(/export \{ ProxmoxNetworkApply[, }]/);
   expect(src).not.toMatch(/export \{ ProxmoxCephFlag[, }]/);

package/src/proxmox/index.ts

@@ -6,8 +6,18 @@
  *   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. NIC apply and QEMU stay
- *   Provider-only so a stack cannot declare them by accident.
+ *   metrics, PBS) sit next to their Providers. NIC apply stays Provider-only
+ *   so a stack cannot declare it by accident.
+ * ★ `ProxmoxVm` JOINED THEM 2026-09-26, FOR TALOS. Its declared-keys model (qemu-props.ts) is
+ *   what let it join safely: an undeclared field is unmanaged, so it is never sent and never
+ *   compared — the fix for the "5-default PUT" a Provider-only `Proxmox.Vm` never exercised.
+ *   `cipassword` and `machine` are typed `never` and refused if smuggled past the types
+ *   (qemu-form.ts's `formRefusals`); `defaultRemovalPolicy: 'retain'` means dropping a
+ *   declaration never destroys a guest's disks. Node-pinned semantics (qemu-read.ts's "A
+ *   migration is not an update") are unchanged by the export.
+ * ★ `Proxmox.StorageDownload` JOINED 2026-09-26 TOO, ALONGSIDE IT: `download-url` (content
+ *   `import`, checksum-pinned) as a CREATE-oriented family — no adoption, no update, a task-poll
+ *   failure (a checksum mismatch included) refuses rather than reports success.
  * ★ `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
@@ -102,7 +112,13 @@ export {
 } from './provision-baseline.ts';
 export { provisionBootstrap } from './provision-bootstrap.ts';
 export { type DeclareProvisionOptions, declareProvisionBaseline } from './provision-declare.ts';
-export { ProxmoxVmProvider } from './qemu.ts';
+export { ProxmoxVm, ProxmoxVmProvider, type VmAttributes, type VmProps } from './qemu.ts';
+export {
+  ProxmoxStorageDownload,
+  ProxmoxStorageDownloadProvider,
+  type StorageDownloadAttributes,
+  type StorageDownloadProps,
+} from './storage-download.ts';
 export { ProxmoxReplicationJobProvider } from './replication-job.ts';
 export { ProxmoxRole, ProxmoxRoleProvider } from './role.ts';
 export { ProxmoxSdnApply, ProxmoxSdnApplyProvider } from './sdn-apply.ts';

package/src/proxmox/qemu-form.ts

@@ -1,15 +1,51 @@
-/** QEMU create and update forms. Path identity stays out of the body. */
-import type { VmProps } from './qemu.ts';
-
-/** Fields both create and update send. `net0` is optional and is not compared. */
-export const shape = (props: VmProps) => ({
-  cores: String(props.cores ?? 1),
-  memory: String(props.memory ?? 512),
-  name: props.name ?? `vm${String(props.vmid)}`,
-  onboot: props.onboot === true ? '1' : '0',
-  sockets: String(props.sockets ?? 1),
-  ...(props.net0 === undefined ? {} : { net0: props.net0 }),
+/**
+ * QEMU create and update forms — declared keys only. Path identity stays out of the body.
+ *
+ * ⛔ NO DEFAULT IS EVER SUBSTITUTED FOR AN UNDECLARED FIELD. See qemu-props.ts's header for the
+ *   "5-default PUT" this replaces: the old `shape()` sent `cores`/`memory`/`name`/`onboot`/
+ *   `sockets` on every write, defaults included for whichever the declaration left out, so
+ *   editing one field on an adopted VM silently reset every other to its factory value.
+ */
+import {
+  type VmProps,
+  declaredKeys,
+  declaredValue,
+  isManagedKey,
+  wireValue,
+} from './qemu-props.ts';
+
+/**
+ * Why a declared key cannot go on the wire, checked before every create and every update.
+ * ★ THE SAME RULE `lxc-create-form.ts` ENFORCES FOR `Proxmox.Lxc`: a key smuggled past the types
+ *   (a cast, a JS caller) is refused here rather than silently dropped or silently sent.
+ */
+export const formRefusals = (props: VmProps): string[] =>
+  declaredKeys(props)
+    .filter((key) => !isManagedKey(key))
+    .map((key) => `${key}: not a config key this resource manages (vmid ${String(props.vmid)}).`);
+
+/** The declared config, wire-spelled — every key `formRefusals` did not already refuse. */
+export const form = (props: VmProps): Record<string, string> => {
+  const out: Record<string, string> = {};
+  for (const key of declaredKeys(props)) {
+    if (!isManagedKey(key)) continue;
+    out[key] = wireValue(declaredValue(props, key));
+  }
+  return out;
+};
+
+/**
+ * The create body: the declared form plus the vmid a create needs.
+ * ⚠️ NO RETURN-TYPE ANNOTATION, ON PURPOSE. Annotating this `Record<string, string>` erases the
+ *   object literal's own inferred shape, and with it the one thing `nodes.createNodeQemu({
+ *   ...createForm(news), node: news.node })` (qemu-lifecycle.ts) needs: TypeScript only accepts a
+ *   spread as satisfying `CreateNodeQemuRequest`'s required `vmid` when the spread's inferred type
+ *   still carries `vmid` as a literal key, which an index-signature-only type cannot prove.
+ */
+export const createForm = (props: VmProps) => ({
+  ...form(props),
+  vmid: String(props.vmid),
 });
 
-/** ★ Exported so the constraint proof can run the REAL create form, not a retyped copy of it. */
-export const createForm = (props: VmProps) => ({ ...shape(props), vmid: String(props.vmid) });
+/** The update body — identical construction to `createForm`, minus `vmid`, which PUT never sends. */
+export const updateForm = form;

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

@@ -0,0 +1,30 @@
+/**
+ * `Proxmox.Vm` identity — red-team I1 on PR 297, through the real engine over a stub fetch.
+ * ⛔ WHAT THIS PINS: a changed `vmid` on an already-managed VM is refused as a different machine,
+ *   never planned as an `update` (which used to POST a second VM and leave the first one running
+ *   and untracked).
+ */
+import { expect, test } from 'bun:test';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { FAKE_TARGET, fakePve, withoutBao } from './fake-pve.ts';
+import { ProxmoxVm, ProxmoxVmProvider } from './qemu.ts';
+
+const NODE = 'pve1';
+const props = { node: NODE, target: FAKE_TARGET, vmid: 150 };
+const live = { digest: 'a'.repeat(40), memory: '512' };
+
+const engine = (fake: ReturnType<typeof fakePve>) =>
+  engineOver(ProxmoxVmProvider().pipe(Layer.provideMerge(fake.layer)));
+
+test('a changed vmid is refused as a different VM, never planned as an update', async () => {
+  const fake = fakePve((call) => (call.method === 'GET' ? live : null));
+  await withoutBao(async () => {
+    const stack = engine(fake);
+    await stack.deploy(ProxmoxVm('row', props));
+    await expect(stack.deploy(ProxmoxVm('row', { ...props, vmid: 151 }))).rejects.toThrow(
+      /vmid: 150 -> 151 is a different VM/,
+    );
+  });
+  expect(fake.writes()).toEqual([]);
+});

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

@@ -0,0 +1,65 @@
+/**
+ * Pure unit tests for `judge`/`identityRefusal` — red-team C1/I1 on PR 297. No network, no fake PVE.
+ * ⛔ WHAT THESE PIN: only drifted keys are ever PUT (an unrelated field's drift does not drag the
+ *   disk/NIC keys along, the failure mode a whole-form resend had); a vmid change is refused, never
+ *   built as a second VM.
+ */
+import { describe, expect, test } from 'bun:test';
+import { FAKE_TARGET } from './fake-pve.ts';
+import { identityRefusal, judge } from './qemu-judge.ts';
+import type { VmProps } from './qemu-props.ts';
+
+const base = { node: 'pve1', target: FAKE_TARGET, vmid: 101 } as const;
+
+describe('judge', () => {
+  test('a fresh-spelled disk and a MAC-less NIC both settle against live, drifting nothing', () => {
+    const props: VmProps = {
+      ...base,
+      ide2: 'cephtb4:cloudinit',
+      net0: 'virtio,bridge=vmbr0,tag=20',
+      scsi0: 'cephtb4:32',
+    };
+    const config = {
+      ide2: 'cephtb4:vm-101-cloudinit,media=cdrom',
+      net0: 'virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0,tag=20',
+      scsi0: 'cephtb4:vm-101-disk-0,size=32G',
+    };
+    expect(judge(props, config)).toEqual({ drift: [], put: {}, refuse: [] });
+  });
+
+  test('an unrelated field drifting does not drag the settled disk/NIC keys into the PUT', () => {
+    const props: VmProps = {
+      ...base,
+      memory: 4096,
+      net0: 'virtio,bridge=vmbr0,tag=20',
+      scsi0: 'cephtb4:32',
+    };
+    const config = {
+      memory: '2048',
+      net0: 'virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0,tag=20',
+      scsi0: 'cephtb4:vm-101-disk-0,size=32G',
+    };
+    const change = judge(props, config);
+    expect(change.drift).toEqual(['memory']);
+    expect(change.put).toEqual({ memory: '4096' });
+  });
+
+  test('a scalar key not yet on the live config is put as declared', () => {
+    const change = judge({ ...base, agent: true }, {});
+    expect(change.put).toEqual({ agent: '1' });
+  });
+});
+
+describe('identityRefusal', () => {
+  test('no prior vmid: never refused (a fresh create)', () => {
+    expect(identityRefusal(101, undefined)).toBeUndefined();
+  });
+
+  test('the same vmid: never refused', () => {
+    expect(identityRefusal(101, 101)).toBeUndefined();
+  });
+
+  test('a changed vmid: refused, naming both -- a new resource, not an update', () => {
+    expect(identityRefusal(151, 150)).toMatch(/vmid: 150 -> 151 is a different VM/);
+  });
+});

package/src/proxmox/qemu-judge.ts

@@ -0,0 +1,84 @@
+/**
+ * Declared against live: what a `Proxmox.Vm` deploy would write, per key — the QEMU sibling of
+ * lxc-judge.ts, added 2026-09-26 (red-team C1/I1 on PR 297).
+ *
+ * ⛔ REPLACES A WHOLE-STRING, WHOLE-FORM COMPARISON. Before this, `matches` compared each declared
+ *   key to live BYTE FOR BYTE and, on any drift, `formToSend` re-PUT every declared key at once
+ *   (qemu-lifecycle.ts). A `scsi0`/`ide2`/`net0` declared in the "new" or MAC-less spelling then
+ *   NEVER matched its own live volume/NIC (qemu-volume.ts / qemu-net.ts explain why), so every
+ *   deploy re-sent all three -- reallocating the disk, re-importing it, and handing out a fresh MAC
+ *   each time, even when nothing else changed. `judge` below decides per key, on the LIVE volume id
+ *   and LIVE MAC, so an unrelated field's drift no longer drags the disk/NIC keys along with it.
+ */
+import { type VmProps, declaredKeys, declaredValue, indexedKey, wireValue } from './qemu-props.ts';
+import { judgeDisk } from './qemu-volume.ts';
+import { netWrite, sameNet } from './qemu-net.ts';
+
+export type VmChange = {
+  /** Keys to `PUT …/config`, wire-spelled and built on live ids where one exists. */
+  readonly put: Record<string, string>;
+  /** Why a key cannot be written as an update. Non-empty means nothing is written. */
+  readonly refuse: readonly string[];
+  /** Every declared key that differs from live, refused or not. */
+  readonly drift: readonly string[];
+};
+
+export const judge = (props: VmProps, config: Record<string, string>): VmChange => {
+  const put: Record<string, string> = {};
+  const refuse: string[] = [];
+  const drift = new Set<string>();
+
+  for (const key of declaredKeys(props)) {
+    const want = wireValue(declaredValue(props, key));
+    const have = config[key];
+    const family = indexedKey(key)?.[0];
+
+    if (family === 'scsi' || family === 'ide') {
+      if (have === undefined) {
+        drift.add(key);
+        put[key] = want;
+      } else {
+        const verdict = judgeDisk(key, want, have);
+        if (verdict.refuse !== undefined) {
+          drift.add(key);
+          refuse.push(verdict.refuse);
+        } else if (verdict.put !== undefined) {
+          drift.add(key);
+          put[key] = verdict.put;
+        }
+      }
+      continue;
+    }
+
+    if (family === 'net') {
+      if (have === undefined) {
+        drift.add(key);
+        put[key] = want;
+      } else if (!sameNet(want, have)) {
+        drift.add(key);
+        put[key] = netWrite(want, have);
+      }
+      continue;
+    }
+
+    // Scalars, `ipconfigN`, `serialN`: a plain string compare, as the old whole-form model did.
+    // ⚠️ No "new spelling" or MAC ambiguity applies to these -- see qemu-props.ts's own doc per key.
+    if (want !== (have ?? '')) {
+      drift.add(key);
+      put[key] = want;
+    }
+  }
+  return { drift: [...drift].sort(), put, refuse };
+};
+
+/**
+ * What makes a `Proxmox.Vm` a DIFFERENT machine: a new vmid (red-team I1). Never planned as a
+ * replace -- see qemu.ts's header on why nothing here replaces a running VM.
+ * ⚠️ `was` PREFERS THE RECORDED ATTRIBUTE, so a `node` change (HA failover, a hand `qm migrate`)
+ *   never reads as a vmid change: only `vmid` is judged here, mirroring lxc-identity.ts.
+ */
+export const identityRefusal = (vmid: number, was: number | undefined): string | undefined =>
+  was === undefined || vmid === was
+    ? undefined
+    : `vmid: ${String(was)} -> ${String(vmid)} is a different VM. Declare it as a new resource; ` +
+      'this one is retained when its declaration goes.';

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

@@ -5,7 +5,7 @@ import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import { engineOver } from '../verify/fake-engine.ts';
 import { FAKE_TARGET, type FakePve, fakePve, withoutBao } from './fake-pve.ts';
-import { ProxmoxVm, ProxmoxVmProvider } from './qemu.ts';
+import { ProxmoxVm, ProxmoxVmProvider, type VmProps } from './qemu.ts';
 
 const NODE = 'pve1';
 const VMID = 150;
@@ -42,24 +42,27 @@ describe('Proxmox.Vm distilled transport', () => {
   });
 
   test('absence creates on the collection route, waits, then settles', async () => {
-    let exists = false;
+    let posted: Record<string, string> | undefined;
     const fake = fakePve((call) => {
       if (call.path.includes('/tasks/') && call.path.endsWith('/status')) {
         return { status: 'stopped', exitstatus: 'OK' };
       }
       if (isIndex(call)) return [];
-      if (call.method === 'GET') return exists ? live : missing();
-      exists = true;
+      // ⚠️ `net0` IS NOW A MANAGED, COMPARED KEY (qemu-props.ts) — the old fixture answered the
+      //   SAME static `live` regardless of what was posted, which only worked because the old
+      //   `matches` never looked at `net0` at all. Echoing the create form back is what proves
+      //   the declared value is what a real PVE config would report.
+      if (call.method === 'GET') return posted === undefined ? missing() : { ...live, ...posted };
+      posted = call.form;
       return UPID;
     });
+    const declared = { ...props, net0: 'virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0' };
     await withoutBao(async () => {
       const stack = engine(fake);
-      await stack.deploy(
-        ProxmoxVm('row', { ...props, net0: 'virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0' }),
+      await stack.deploy(ProxmoxVm('row', declared));
+      expect((await stack.verify(ProxmoxVm('row', declared), { all: true })).rows[0]).toMatchObject(
+        { diff: 'noop' },
       );
-      expect((await stack.verify(ProxmoxVm('row', props), { all: true })).rows[0]).toMatchObject({
-        diff: 'noop',
-      });
     });
     expect(fake.writes()).toEqual([`POST nodes/${NODE}/qemu`]);
     expect(fake.calls.find((call) => call.method === 'POST')?.form['net0']).toBe(
@@ -68,6 +71,41 @@ describe('Proxmox.Vm distilled transport', () => {
     expect(fake.calls.some((call) => call.path.includes('/tasks/'))).toBe(true);
   });
 
+  test('C1: a "fresh" disk/cloudinit and a MAC-less NIC do not re-drift after PVE allocates them', async () => {
+    // ⛔ THE MEASURED REGRESSION: before qemu-judge.ts, every deploy after the create re-sent
+    //   scsi0/ide2/net0 in their DECLARED (fresh) spelling, because a plain string compare never
+    //   equals what PVE reports back for an allocated volume or a generated MAC -- reallocating the
+    //   disk and handing out a new MAC on every single deploy.
+    const declared = {
+      ...props,
+      ide2: 'cephtb4:cloudinit',
+      net0: 'virtio,bridge=vmbr0,tag=20',
+      scsi0: 'cephtb4:32',
+    };
+    const allocated = {
+      ide2: 'cephtb4:vm-150-cloudinit,media=cdrom',
+      net0: 'virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0,tag=20',
+      scsi0: 'cephtb4:vm-150-disk-0,size=32G',
+    };
+    let created = false;
+    const fake = fakePve((call) => {
+      if (call.path.includes('/tasks/') && call.path.endsWith('/status')) {
+        return { status: 'stopped', exitstatus: 'OK' };
+      }
+      if (isIndex(call)) return [];
+      if (call.method === 'GET') return created ? { ...live, ...allocated } : missing();
+      created = true;
+      return UPID;
+    });
+    await withoutBao(async () => {
+      const stack = engine(fake);
+      await stack.deploy(ProxmoxVm('row', declared));
+      await stack.deploy(ProxmoxVm('row', declared));
+      await stack.deploy(ProxmoxVm('row', declared));
+    });
+    expect(fake.writes()).toEqual([`POST nodes/${NODE}/qemu`]);
+  });
+
   test('a transitional task status keeps polling instead of aborting the create', async () => {
     // ⚠️ `GetNodeTaskStatusResponseStatus` types `status` as the closed union
     //   "running" | "stopped", but the runtime validator is `S.String` (distilled-proxmox's
@@ -113,24 +151,45 @@ describe('Proxmox.Vm distilled transport', () => {
     expect(fake.writes()).toEqual([]);
   });
 
-  test('drift updates the config route and the next plan is a no-op', async () => {
-    let current: unknown = { ...live, memory: '256' };
+  test('drift on a declared field updates the config route, and only that field', async () => {
+    // ⛔ THE "5-DEFAULT PUT" REGRESSION TEST. `name` is deliberately left UNDECLARED and deliberately
+    //   NOT what qemu-form.ts's old default would have produced (`vm150`) -- the old `shape()` sent
+    //   it (and `cores`/`sockets`/`onboot`) on every write regardless, silently resetting an
+    //   undeclared field to its factory value. Only `memory` is declared here, so only `memory`
+    //   may appear in the PUT body.
+    const declared = { ...props, memory: 512 };
+    let current: unknown = { ...live, memory: '256', name: 'a-name-nobody-declared' };
     const fake = fakePve((call) => {
       if (call.method === 'GET') return current;
-      current = live;
+      current = { ...(current as Record<string, unknown>), memory: '512' };
       return null;
     });
     await withoutBao(async () => {
       const stack = engine(fake);
-      expect((await stack.verify(ProxmoxVm('row', props), { all: true })).rows[0]).toMatchObject({
-        diff: 'update',
-      });
-      await stack.deploy(ProxmoxVm('row', props));
-      expect((await stack.verify(ProxmoxVm('row', props), { all: true })).rows[0]).toMatchObject({
-        diff: 'noop',
-      });
+      expect((await stack.verify(ProxmoxVm('row', declared), { all: true })).rows[0]).toMatchObject(
+        { diff: 'update' },
+      );
+      await stack.deploy(ProxmoxVm('row', declared));
+      expect((await stack.verify(ProxmoxVm('row', declared), { all: true })).rows[0]).toMatchObject(
+        { diff: 'noop' },
+      );
     });
     expect(fake.writes()).toEqual([`PUT nodes/${NODE}/qemu/${String(VMID)}/config`]);
+    const put = fake.calls.find((call) => call.method === 'PUT');
+    expect(put?.form).toEqual({ memory: '512' });
+  });
+
+  test('an unmanaged key smuggled past the types is refused before any write', async () => {
+    const fake = fakePve((call) => (call.method === 'GET' ? live : null));
+    // ⛔ `cipassword` IS TYPED `never` (qemu-props.ts): a cast is the only way in, exactly the
+    //   scenario the type cannot guard against by itself. `formRefusals` is the runtime backstop.
+    const smuggled = { ...props, cipassword: 'not-a-real-secret' } as unknown as VmProps;
+    await withoutBao(async () => {
+      await expect(engine(fake).deploy(ProxmoxVm('row', smuggled))).rejects.toThrow(
+        /cipassword: not a config key this resource manages/,
+      );
+    });
+    expect(fake.writes()).toEqual([]);
   });
 
   test('unrelated read failures and a digest-less body do not write', async () => {