@homeflare/alchemy 0.37.5 → 0.37.7

package/src/proxmox/network-apply-run.ts

@@ -0,0 +1,97 @@
+/** The reload itself: one node, one lease, one task, then a health check. */
+import * as nodes from '@distilled.cloud/proxmox/nodes';
+import * as Effect from 'effect/Effect';
+import { guardNetworkApply } from './apply-endpoints.ts';
+import { runPveWith } from './distilled-pve.ts';
+import { mint } from './mint.ts';
+import { awaitTask, degradedReason, pendingCount } from './network-apply-read.ts';
+import type { NetworkApplyProps } from './network-apply.ts';
+import { text } from './values.ts';
+
+/** Stop the deploy, loudly, with the node in the message. ⚠️ A die here is the SAFE outcome. */
+const refuse = (node: string, why: string) =>
+  Effect.die(new Error(`Proxmox.NetworkApply ${node}: ${why}`));
+
+export const applyNetwork = (props: NetworkApplyProps) =>
+  Effect.gen(function* () {
+    const node = props.node;
+    const staged = yield* pendingCount(props.target, node);
+    /**
+     * ⛔ NOTHING STAGED MEANS NOTHING TO APPLY, AND THIS BRANCH IS A SAFETY PROPERTY RATHER THAN AN
+     *   OPTIMISATION. `reconcile` also runs on CREATE — the first time this resource appears in a
+     *   stack, before `diff` has ever been consulted — and the PVE worker runs `ifreload -a`
+     *   UNCONDITIONALLY, staged file or not. Without this branch, adding `Proxmox.NetworkApply` to
+     *   a stack describing the cluster as it already is would reload networking on every node it
+     *   names, for nothing. Adoption must cost nothing; that is true here in the strongest sense.
+     */
+    if (staged === 0) return { node, pending: 0 };
+
+    const before = yield* degradedReason(props.target);
+    if (before !== undefined) {
+      return yield* refuse(
+        node,
+        `refusing to reload networking on a cluster that is already degraded (${before}). ` +
+          'Ceph spans these nodes -- fix the cluster first, then re-run the deploy.',
+      );
+    }
+
+    /**
+     * ⚠️ ONE LEASE FOR BOTH CALLS, VIA `runPveWith` RATHER THAN `runPve`. Each mint returns a NEW token
+     *   id, and the task-status endpoint only skips its `Sys.Audit` check for the task's OWNER —
+     *   so polling with a fresh mint is a different identity and needs a privilege this role does
+     *   not have. The `provision` lease is 300s and non-renewable, which is far longer than a
+     *   reload and is the reason no renew path is reached for.
+     */
+    // ⛔ BEFORE THE MINT AND THE RELOAD. The apply takes no body, so this is the lookup rather
+    //   than a value check: a vendor that moved this endpoint fails here, not mid-ifreload.
+    yield* guardNetworkApply;
+    const credential = yield* mint(props.target, 'provision');
+    const upid = text(
+      yield* runPveWith(props.target, credential, true, nodes.putNodeNetwork({ node })),
+    );
+    if (upid === '') {
+      return yield* refuse(
+        node,
+        'the apply returned no UPID. PVE wraps every answer in {"data":...} and can report success ' +
+          'on a call that did nothing -- the reload cannot be confirmed, so it is not claimed.',
+      );
+    }
+
+    /**
+     * ⛔ POLLING `pending` INSTEAD OF THE TASK WOULD REPORT SUCCESS BEFORE THE NETWORK WAS TOUCHED.
+     *   MEASURED in the worker above: the `rename` happens FIRST and `ifreload -a` second, so the
+     *   staged file — and therefore `changes`, and therefore `pending` — disappears while the
+     *   reload has not yet started. A provider that watched the count would call a reload that had
+     *   not run, and a reload that then FAILED, a success. The task's exitstatus is the only
+     *   honest answer.
+     */
+    const exitstatus = yield* awaitTask(props.target, credential, node, upid);
+    if (exitstatus !== 'OK') {
+      return yield* refuse(
+        node,
+        `the reload ended "${exitstatus}" (${upid}). Read it from ANOTHER node -- ` +
+          `\`pvesh get /nodes/${node}/tasks/${upid}/log\` -- and do not apply the next node until ` +
+          'this one is understood.',
+      );
+    }
+
+    const after = yield* degradedReason(props.target);
+    if (after !== undefined) {
+      return yield* refuse(
+        node,
+        `the reload reported OK but the cluster is now degraded (${after}). The next ` +
+          'node has NOT been applied. Restore this one before continuing -- Ceph runs over these ' +
+          'links and a second reload now would take pools below min_size.',
+      );
+    }
+
+    const left = yield* pendingCount(props.target, node);
+    if (left !== 0) {
+      return yield* refuse(
+        node,
+        `the reload reported OK but ${String(left)} staged line(s) remain. The running config does ` +
+          'not match the declared one, and saying otherwise is the lie this resource exists to stop.',
+      );
+    }
+    return { node, pending: left };
+  });

package/src/proxmox/network-apply.ts

@@ -45,19 +45,16 @@
  *   GRANT — it also carries that node's DNS, hosts file, time and service configuration. Granting
  *   it cluster-wide to run this resource widens the provisioning role well beyond networking.
  *
- * ⛔ STAYS ON `client.ts` (2026-09-24) — network-apply-read.ts's header has the two MEASURED reasons.
+ * Named operations: `listNodeNetwork` keeps the diff sibling, `putNodeNetwork` reloads.
  */
 import { Resource } from 'alchemy';
 import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { guardNetworkApply } from './apply-endpoints.ts';
-import { pveWith } from './client.ts';
-import { mint } from './mint.ts';
-import { awaitTask, degradedReason, pendingCount } from './network-apply-read.ts';
-import type { PveRequirements } from './resource.ts';
-import type { WithTarget } from './resource.ts';
+import { applyNetwork } from './network-apply-run.ts';
+import { pendingCount } from './network-apply-read.ts';
+import type { PveRequirements, WithTarget } from './resource.ts';
 
 export interface NetworkApplyProps extends WithTarget {
   /**
@@ -141,92 +138,6 @@ const diff = (news: Input<NetworkApplyProps>) =>
     return pending === 0 ? ({ action: 'noop' } as const) : ({ action: 'update' } as const);
   });
 
-/** Stop the deploy, loudly, with the node in the message. ⚠️ A die here is the SAFE outcome. */
-const refuse = (node: string, why: string) =>
-  Effect.die(new Error(`Proxmox.NetworkApply ${node}: ${why}`));
-
-const apply = (props: NetworkApplyProps) =>
-  Effect.gen(function* () {
-    const node = props.node;
-    const staged = yield* pendingCount(props.target, node);
-    /**
-     * ⛔ NOTHING STAGED MEANS NOTHING TO APPLY, AND THIS BRANCH IS A SAFETY PROPERTY RATHER THAN AN
-     *   OPTIMISATION. `reconcile` also runs on CREATE — the first time this resource appears in a
-     *   stack, before `diff` has ever been consulted — and the PVE worker runs `ifreload -a`
-     *   UNCONDITIONALLY, staged file or not. Without this branch, adding `Proxmox.NetworkApply` to
-     *   a stack describing the cluster as it already is would reload networking on every node it
-     *   names, for nothing. Adoption must cost nothing; that is true here in the strongest sense.
-     */
-    if (staged === 0) return { node, pending: 0 };
-
-    const before = yield* degradedReason(props.target);
-    if (before !== undefined) {
-      return yield* refuse(
-        node,
-        `refusing to reload networking on a cluster that is already degraded (${before}). ` +
-          'Ceph spans these nodes -- fix the cluster first, then re-run the deploy.',
-      );
-    }
-
-    /**
-     * ⚠️ ONE LEASE FOR BOTH CALLS, VIA `pveWith` RATHER THAN `pve`. Each mint returns a NEW token
-     *   id, and the task-status endpoint only skips its `Sys.Audit` check for the task's OWNER —
-     *   so polling with a fresh mint is a different identity and needs a privilege this role does
-     *   not have. The `provision` lease is 300s and non-renewable, which is far longer than a
-     *   reload and is the reason no renew path is reached for.
-     */
-    // ⛔ BEFORE THE MINT AND THE RELOAD. The apply takes no body, so this is the lookup rather
-    //   than a value check: a vendor that moved this endpoint fails here, not mid-ifreload.
-    yield* guardNetworkApply;
-    const credential = yield* mint(props.target, 'provision');
-    const upid = yield* pveWith<string>(props.target, credential, 'PUT', `nodes/${node}/network`);
-    if (upid === undefined) {
-      return yield* refuse(
-        node,
-        'the apply returned no UPID. PVE wraps every answer in {"data":...} and can report success ' +
-          'on a call that did nothing -- the reload cannot be confirmed, so it is not claimed.',
-      );
-    }
-
-    /**
-     * ⛔ POLLING `pending` INSTEAD OF THE TASK WOULD REPORT SUCCESS BEFORE THE NETWORK WAS TOUCHED.
-     *   MEASURED in the worker above: the `rename` happens FIRST and `ifreload -a` second, so the
-     *   staged file — and therefore `changes`, and therefore `pending` — disappears while the
-     *   reload has not yet started. A provider that watched the count would call a reload that had
-     *   not run, and a reload that then FAILED, a success. The task's exitstatus is the only
-     *   honest answer.
-     */
-    const exitstatus = yield* awaitTask(props.target, credential, node, upid);
-    if (exitstatus !== 'OK') {
-      return yield* refuse(
-        node,
-        `the reload ended "${exitstatus}" (${upid}). Read it from ANOTHER node -- ` +
-          `\`pvesh get /nodes/${node}/tasks/${upid}/log\` -- and do not apply the next node until ` +
-          'this one is understood.',
-      );
-    }
-
-    const after = yield* degradedReason(props.target);
-    if (after !== undefined) {
-      return yield* refuse(
-        node,
-        `the reload reported OK but the cluster is now degraded (${after}). The next ` +
-          'node has NOT been applied. Restore this one before continuing -- Ceph runs over these ' +
-          'links and a second reload now would take pools below min_size.',
-      );
-    }
-
-    const left = yield* pendingCount(props.target, node);
-    if (left !== 0) {
-      return yield* refuse(
-        node,
-        `the reload reported OK but ${String(left)} staged line(s) remain. The running config does ` +
-          'not match the declared one, and saying otherwise is the lie this resource exists to stop.',
-      );
-    }
-    return { node, pending: left };
-  });
-
 /**
  * ⛔ HAND-WRITTEN RATHER THAN `pveHandlers`, FOR THE SAME REASON `sdn-apply.ts` IS. The factory's
  *   spec is create/update/delete over ONE object at ONE path, and an apply is not an object: there
@@ -243,7 +154,7 @@ const handlers = {
   diff: ({ news }: { news: Input<NetworkApplyProps> }) => diff(news),
   list: () => Effect.succeed([]),
   read: ({ olds }: { olds: NetworkApplyProps }) => read(olds),
-  reconcile: ({ news }: { news: NetworkApplyProps }) => apply(news),
+  reconcile: ({ news }: { news: NetworkApplyProps }) => applyNetwork(news),
 };
 
 export const ProxmoxNetworkApplyProvider = () =>

package/src/proxmox/node-network-read-failure.test.ts

@@ -139,6 +139,30 @@ describe('only the measured "interface does not exist" 400 means absent', () =>
     });
   });
 
+  /**
+   * ⛔ THE RETAG REGRESSION'S OWN TEST — RED-TEAM FINDING, 2026-09-25: `@distilled.cloud/proxmox`
+   *   retagged this exact 400 from the generic `ParameterVerificationFailed` to a specific
+   *   `NetworkInterfaceNotFound` (`nodes.ts`), and `readInterfaceOrFail`'s `catchTag` still named
+   *   the OLD tag — so on an already-adopted row (this is `diff`'s and `verify --all`'s `read`'s
+   *   `output !== undefined` branch, the non-folding one) the absence signal went UNCAUGHT and
+   *   threw straight through `engine.verify`, instead of resolving a `diff`/`missing` report.
+   *   Proven by temporarily reverting the `catchTag` to `'ParameterVerificationFailed'`: only this
+   *   test fails, with an unhandled `NetworkInterfaceNotFound`.
+   */
+  test('an already-adopted interface whose live GET now answers genuinely absent resolves via diff as missing, never throws', async () => {
+    const fake = clusterOverInterface('n2', 'vmbr0', live);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxNodeNetworkProvider().pipe(Layer.provideMerge(fake.layer)));
+      expect(await engine.deploy(declare())).toEqual({ 'n2-vmbr0': 'adopted' });
+      fake.setAnswer('genuinely-absent');
+      const report = await engine.verify(declare(), { all: true });
+      // ⛔ `update` IS THE RIGHT ANSWER HERE, NOT A THROW: this resource's `diff` treats a
+      //   vanished interface as something `reconcile` recreates (node-network.ts's `diff`,
+      //   `live === undefined` branch), the same as any other drifted-away row.
+      expect(report.rows[0]).toMatchObject({ diff: 'update' });
+    });
+  });
+
   /**
    * ★ WHY `read` FOLDS AT ALL, SPELLED OUT ON A BRAND NEW DECLARATION. Plan.ts's cold-start
    *   adoption probe (no prior Alchemy state for this declaration) calls `provider.read` with no

package/src/proxmox/node-network-wire.ts

@@ -156,14 +156,17 @@ const attributesOf = (
  *   `{"errors":{"iface":"interface does not exist"},"data":null,"message":"Parameter verification
  *   failed.\n"}` at HTTP 400 — a THIRD shape, different from every other migrated family's
  *   measured 500. `@distilled.cloud/proxmox` types this as a genuine typed error,
- *   `ParameterVerificationFailed` (`errors.ts`), carrying the per-field `errors` object rather
- *   than collapsing it to an opaque `BadRequest` — PVE's OWN 400 is never one shape (it is
- *   whatever the endpoint's parameter verification rejected), so `errors.ts`'s own header spells
- *   out why this ONE typed error is global rather than per-operation.
- * ⛔ ONLY THIS EXACT SIGNAL MEANS ABSENT, EVEN WITH THE FOLD BELOW. A different 400 reason, a
- *   permission gap, a network blip, or ANY OTHER `ParameterVerificationFailed` reason is never
- *   read as "this interface is not there" — `diff` calls this directly and propagates every one
- *   of them loudly.
+ *   `NetworkInterfaceNotFound` (`nodes.ts`, generated from `patches/nodes/network-errors.json`),
+ *   attached ONLY to `getNodeNetwork`'s error union and matched by the SDK's own
+ *   `errorEnvelope`/`matchTypedError` against the EXACT sole-field body `errors.iface ===
+ *   "interface does not exist"` — the precision the code here used to check by hand
+ *   (`error.errors['iface'] === '…'`) is now the SDK's own matcher contract, not this file's.
+ *   Any 400 that fails that exact match (a different field, a different message, more than one
+ *   field) decodes as the generic `ParameterVerificationFailed` instead, never this tag.
+ * ⛔ ONLY THIS EXACT SIGNAL MEANS ABSENT, EVEN WITH THE FOLD BELOW. A different 400 reason
+ *   (`ParameterVerificationFailed`), a permission gap, a network blip, or any other failure is
+ *   never read as "this interface is not there" — `diff` calls this directly and propagates
+ *   every one of them loudly.
  */
 export const readInterfaceOrFail = (props: NodeNetworkProps) =>
   readOrUnreadable(
@@ -172,13 +175,7 @@ export const readInterfaceOrFail = (props: NodeNetworkProps) =>
       'read',
       false,
       nodes.getNodeNetwork({ iface: props.iface, node: props.node }),
-    ).pipe(
-      Effect.catchTag('ParameterVerificationFailed', (error) =>
-        error.errors['iface'] === 'interface does not exist'
-          ? Effect.succeed(undefined)
-          : Effect.fail(error),
-      ),
-    ),
+    ).pipe(Effect.catchTag('NetworkInterfaceNotFound', () => Effect.succeed(undefined))),
   ).pipe(
     Effect.map((live) => {
       if (live === UNREADABLE) return UNREADABLE;
@@ -198,8 +195,9 @@ export const readInterfaceOrFail = (props: NodeNetworkProps) =>
  *   interrupted-create recovery, and Apply.ts's delete recovery, all call `read` with
  *   `output: undefined` and NO catch of their own (`Plan.ts` v2.0.0-beta.79 ~line 1308) — and
  *   Plan.ts fails the WHOLE PLAN, every other resource included, if that call throws. A malformed
- *   `iface` in ONE brand-new declaration (a DIFFERENT `ParameterVerificationFailed` than the
- *   absence one) would abort `bun run plan` for the entire stack under the precise-only design,
+ *   `iface` in ONE brand-new declaration (a `ParameterVerificationFailed`, DIFFERENT from the
+ *   `NetworkInterfaceNotFound` absence tag) would abort `bun run plan` for the entire stack under
+ *   the precise-only design,
  *   where every other migrated family instead defers that same malformed declaration to a scoped,
  *   loud refusal at apply. This restores that same fold for those three call sites.
  */

package/src/proxmox/qemu-errors.ts

@@ -0,0 +1,7 @@
+/** A QEMU write or observation this provider will not turn into a create or a delete. */
+export class QemuRefusedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'QemuRefusedError';
+  }
+}

package/src/proxmox/qemu-form.ts

@@ -0,0 +1,15 @@
+/** 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 }),
+});
+
+/** ★ 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) });

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

@@ -0,0 +1,171 @@
+/** QEMU engine tests over a stub fetch. No live host is contacted. */
+import { describe, expect, test } from 'bun:test';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+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';
+
+const NODE = 'pve1';
+const VMID = 150;
+const props = { target: FAKE_TARGET, node: NODE, vmid: VMID };
+const digest = 'a'.repeat(40);
+const live = { digest, name: 'vm150', memory: '512', cores: 1, sockets: 1, onboot: 0 };
+const missing = () =>
+  Response.json(
+    {
+      data: null,
+      message: `Configuration file 'nodes/${NODE}/qemu-server/${String(VMID)}.conf' does not exist\n`,
+    },
+    { status: 500 },
+  );
+const UPID = `UPID:${NODE}:00000001:0:0:qmcreate:${String(VMID)}:test@pve!fake:`;
+
+const engine = (fake: FakePve) =>
+  engineOver(ProxmoxVmProvider().pipe(Layer.provideMerge(fake.layer)));
+
+const isIndex = (call: { method: string; path: string }) =>
+  call.method === 'GET' && call.path.startsWith('cluster/resources');
+
+describe('Proxmox.Vm distilled transport', () => {
+  test('adoption and a second plan write nothing', async () => {
+    const fake = fakePve((call) => (call.method === 'GET' ? live : null));
+    await withoutBao(async () => {
+      const stack = engine(fake);
+      expect(await stack.deploy(ProxmoxVm('row', props))).toEqual({ row: 'adopted' });
+      expect((await stack.verify(ProxmoxVm('row', props), { all: true })).rows).toEqual([
+        expect.objectContaining({ diff: 'noop', ok: true }),
+      ]);
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('absence creates on the collection route, waits, then settles', async () => {
+    let exists = 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 exists ? live : missing();
+      exists = true;
+      return UPID;
+    });
+    await withoutBao(async () => {
+      const stack = engine(fake);
+      await stack.deploy(
+        ProxmoxVm('row', { ...props, net0: 'virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0' }),
+      );
+      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(
+      'virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0',
+    );
+    expect(fake.calls.some((call) => call.path.includes('/tasks/'))).toBe(true);
+  });
+
+  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
+    //   nodes.ts) -- a status word this endpoint's contract was never proven to exclude must
+    //   keep polling rather than abort the whole create, since only "stopped" ends the task
+    //   (2026-09-25 adversarial review; matches lxc-task.ts's own regression test).
+    let exists = false;
+    let polls = 0;
+    const fake = fakePve((call) => {
+      if (call.path.includes('/tasks/') && call.path.endsWith('/status')) {
+        polls++;
+        return polls === 1 ? { status: 'starting' } : { status: 'stopped', exitstatus: 'OK' };
+      }
+      if (isIndex(call)) return [];
+      if (call.method === 'GET') return exists ? live : missing();
+      exists = true;
+      return UPID;
+    });
+    await withoutBao(async () => {
+      const stack = engine(fake);
+      await stack.deploy(ProxmoxVm('row', props));
+      expect((await stack.verify(ProxmoxVm('row', props), { all: true })).rows[0]).toMatchObject({
+        diff: 'noop',
+      });
+    });
+    expect(polls).toBe(2);
+    expect(fake.writes()).toEqual([`POST nodes/${NODE}/qemu`]);
+  });
+
+  test('a vmid held by a container is not created', async () => {
+    const fake = fakePve((call) => {
+      if (isIndex(call)) {
+        return [{ id: 'lxc/150', type: 'lxc', vmid: 150, node: 'pve2' }];
+      }
+      if (call.method === 'GET') return missing();
+      return UPID;
+    });
+    await withoutBao(async () => {
+      await expect(engine(fake).deploy(ProxmoxVm('row', props))).rejects.toThrow(
+        /container|lxc|pve2/,
+      );
+    });
+    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' };
+    const fake = fakePve((call) => {
+      if (call.method === 'GET') return current;
+      current = live;
+      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(fake.writes()).toEqual([`PUT nodes/${NODE}/qemu/${String(VMID)}/config`]);
+  });
+
+  test('unrelated read failures and a digest-less body do not write', async () => {
+    for (const body of [
+      Response.json({ data: null, message: 'unrelated failure' }, { status: 500 }),
+      Response.json({ data: null, message: 'permission denied' }, { status: 403 }),
+      { name: 'vm150' },
+    ]) {
+      const fake = fakePve(() => body);
+      await withoutBao(async () => {
+        await expect(engine(fake).deploy(ProxmoxVm('row', props))).rejects.toBeDefined();
+      });
+      expect(fake.writes()).toEqual([]);
+    }
+  });
+
+  test('destroy deletes the guest route and waits for its task', async () => {
+    let exists = true;
+    const fake = fakePve((call) => {
+      if (call.path.includes('/tasks/') && call.path.endsWith('/status')) {
+        return { status: 'stopped', exitstatus: 'OK' };
+      }
+      if (call.method === 'GET') return exists ? live : missing();
+      if (call.method === 'DELETE') {
+        exists = false;
+        return UPID;
+      }
+      return null;
+    });
+    await withoutBao(async () => {
+      const stack = engine(fake);
+      await stack.deploy(ProxmoxVm('row', props).pipe(RemovalPolicy.destroy()));
+      await stack.deploy(Effect.void);
+    });
+    expect(fake.writes()).toEqual([`DELETE nodes/${NODE}/qemu/${String(VMID)}`]);
+    expect(fake.writes().some((line) => line.includes('/config'))).toBe(false);
+  });
+});

package/src/proxmox/qemu-lifecycle.ts

@@ -0,0 +1,134 @@
+/**
+ * QEMU lifecycle on named operations.
+ * ⛔ GET and PUT use `/nodes/{node}/qemu/{vmid}/config`. DELETE uses `/nodes/{node}/qemu/{vmid}`.
+ *   qemu-server Qemu.pm names that second route `destroy_vm`. Sending DELETE to the config
+ *   route does not destroy the guest.
+ */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as nodes from '@distilled.cloud/proxmox/nodes';
+import * as Effect from 'effect/Effect';
+import { runPve } from './distilled-pve.ts';
+import { createForm, shape } from './qemu-form.ts';
+import { QemuRefusedError } from './qemu-errors.ts';
+import { readVm } from './qemu-read.ts';
+import { qemuTask } from './qemu-task.ts';
+import type { VmAttributes, VmProps } from './qemu.ts';
+import type { PveSpec } from './resource-spec.ts';
+import { specGuards } from './resource-guard.ts';
+import { formToSend } from './update-guard.ts';
+import { int } from './values.ts';
+
+const CREATE_POLLS = 180;
+const DELETE_POLLS = 60;
+
+const attributesOf = (
+  live: {
+    cores?: unknown;
+    memory?: unknown;
+    name?: unknown;
+    onboot?: unknown;
+    sockets?: unknown;
+  },
+  props: VmProps,
+): VmAttributes => ({
+  cores: int(live.cores, 1),
+  memory: int(live.memory, 512),
+  name: typeof live.name === 'string' ? live.name : '',
+  node: props.node,
+  onboot: live.onboot === 1 || live.onboot === true,
+  sockets: int(live.sockets, 1),
+  vmid: props.vmid,
+});
+
+const matches = (attributes: VmAttributes, props: VmProps) =>
+  attributes.name === (props.name ?? `vm${String(props.vmid)}`) &&
+  attributes.memory === (props.memory ?? 512) &&
+  attributes.cores === (props.cores ?? 1) &&
+  attributes.sockets === (props.sockets ?? 1) &&
+  attributes.onboot === (props.onboot === true);
+
+const spec = {
+  attributes: attributesOf,
+  collection: (props: VmProps) => `nodes/${props.node}/qemu`,
+  createForm,
+  endpoint: {
+    create: 'pve:POST /nodes/{node}/qemu',
+    update: 'pve:PUT /nodes/{node}/qemu/{vmid}/config',
+  },
+  matches,
+  path: (props: VmProps) => `nodes/${props.node}/qemu/${String(props.vmid)}/config`,
+  updateForm: shape,
+} satisfies PveSpec<VmProps, VmAttributes>;
+
+const { guardCreate, guardUpdate } = specGuards(spec);
+
+export const readQemu = (props: VmProps) =>
+  readVm(props).pipe(
+    Effect.map((live) => (live === undefined ? undefined : attributesOf(live, props))),
+  );
+
+/** No purge, no skiplock, no destroy-unreferenced-disks. A missing config is already gone. */
+export const deleteQemu = (props: VmProps) =>
+  qemuTask(
+    props,
+    nodes.deleteNodeQemu({ node: props.node, vmid: String(props.vmid) }),
+    `destroy VM ${String(props.vmid)}`,
+    DELETE_POLLS,
+  ).pipe(Effect.catchTag('QemuConfigNotFound', () => Effect.void));
+
+export const qemuHandlers = {
+  list: () => Effect.succeed([]),
+  read: ({ olds }: { olds: VmProps }) => readQemu(olds),
+  diff: Effect.fn(function* ({
+    news,
+    output,
+  }: {
+    news: Input<VmProps>;
+    output: VmAttributes | undefined;
+  }) {
+    if (!isResolved(news)) return undefined;
+    yield* guardCreate(news, output === undefined);
+    yield* guardUpdate(news);
+    if (output === undefined) return undefined;
+    const live = yield* readQemu(news);
+    if (live === undefined) {
+      yield* guardCreate(news, true);
+      return { action: 'update' } as const;
+    }
+    return { action: spec.matches(live, news) ? 'noop' : 'update' } as const;
+  }),
+  reconcile: Effect.fn(function* ({ news }: { news: VmProps }) {
+    const live = yield* readQemu(news);
+    yield* guardCreate(news, live === undefined);
+    yield* guardUpdate(news);
+    if (live === undefined) {
+      yield* qemuTask(
+        news,
+        nodes.createNodeQemu({ ...createForm(news), node: news.node }),
+        `create VM ${String(news.vmid)}`,
+        CREATE_POLLS,
+      );
+    } else {
+      const form = formToSend(spec.matches, live, news, spec.updateForm(news));
+      if (form !== undefined) {
+        yield* runPve(
+          news.target,
+          'provision',
+          true,
+          nodes.putNodeQemuConfig({ ...form, node: news.node, vmid: String(news.vmid) }),
+        );
+      }
+    }
+    const after = yield* readQemu(news);
+    if (after === undefined) {
+      return yield* Effect.fail(
+        new QemuRefusedError(
+          `${spec.path(news)}: write returned success but the VM is still absent`,
+        ),
+      );
+    }
+    return after;
+  }),
+  delete: ({ olds }: { olds: VmProps }) => deleteQemu(olds),
+};