@homeflare/alchemy 0.37.6 → 0.37.7

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

@@ -1,9 +1,9 @@
 /**
  * When a container read counts as "absent" — the question that decides between adopt and create.
  *
- * ⛔ WHAT THESE PIN: only a 500 whose vmid the cluster does not list anywhere is absent, whatever
- *   the message says; a 403 or a 500 for a guest the cluster lists on the declared node FAILS the
- *   plan with PVE's own error; nothing is written in any case. resource.ts's fold of every error
+ * ⛔ WHAT THESE PIN: only the SDK's exact missing-config tag may consult the same credential's
+ *   cluster index for absence. A 403 or any other 500 FAILS the plan with PVE's own error;
+ *   nothing is written in any case. resource.ts's fold of every error
  *   into "absent" is exactly what this resource must not inherit — under it, a lease without
  *   VM.Audit plans a CREATE over a running guest.
  */
@@ -31,11 +31,14 @@ const declared = (vmid: number) =>
   }).pipe(adopt(true));
 
 describe('absent means the cluster does not list the vmid', () => {
-  test('a 500 with no message, for a vmid nowhere in the cluster, plans a create', async () => {
+  test('a 500 with no message never uses a filtered empty index to authorize creation', async () => {
     fake = fakePve();
     fake.configErrors.set(`${NODE}/150`, { body: { data: null }, status: 500 });
     const run = await lxcEngine(fake).plan(declared(150));
-    expect(run).toMatchObject({ actions: { ct: 'create' }, failure: '' });
+    expect(run.failure).toContain('InternalServerError');
+    expect(run.actions).toEqual({});
+    expect(writesOf(fake)).toEqual([]);
+    expect(fake.seen.some((call) => call.path.endsWith('/cluster/resources'))).toBe(false);
   });
 
   test('a 500 for a guest the cluster lists on this node fails with PVE’s error', async () => {
@@ -54,7 +57,27 @@ describe('absent means the cluster does not list the vmid', () => {
     const message = 'Permission check failed (/vms/150, VM.Audit)\n';
     fake.configErrors.set(`${NODE}/150`, { body: { data: null, message }, status: 403 });
     const run = await lxcEngine(fake).plan(declared(150));
-    expect(run.failure).toContain('-> 403');
+    expect(run.failure).toContain('Forbidden');
     expect(run.actions).toEqual({});
+    expect(writesOf(fake)).toEqual([]);
+    expect(fake.seen.some((call) => call.path.endsWith('/cluster/resources'))).toBe(false);
   });
+
+  test('exact missing config plus an empty index permits the existing create plan', async () => {
+    fake = fakePve();
+    const run = await lxcEngine(fake).plan(declared(150));
+    expect(run).toMatchObject({ actions: { ct: 'create' }, failure: '' });
+    expect(writesOf(fake)).toEqual([]);
+  });
+
+  for (const data of [null, {}, { hostname: 'example' }]) {
+    test(`malformed config success ${JSON.stringify(data)} is not absence`, async () => {
+      fake = fakePve();
+      fake.configErrors.set(`${NODE}/150`, { body: { data }, status: 200 });
+      const run = await lxcEngine(fake).plan(declared(150));
+      expect(run.failure).toContain('digest-bearing config');
+      expect(run.actions).toEqual({});
+      expect(writesOf(fake)).toEqual([]);
+    });
+  }
 });

package/src/proxmox/lxc-read.ts

@@ -0,0 +1,88 @@
+/**
+ * Precise container discovery, with cluster-wide vmid collision checks.
+ * ⛔ A config path missing on one node does not mean its vmid is free: migration or a QEMU
+ *   guest may hold it. Only the SDK's exact LxcConfigNotFound permits the second observation.
+ *   Generic 500s, permission failures and malformed successes never authorize creation.
+ * ★ SAME CREDENTIAL FOR BOTH READS. Installed pve-container6.1.13 Config.pm:31 checks
+ *   VM.Audit on /vms/{vmid} before AbstractConfig.pm:58 raises the missing-config error.
+ *   The pinned pve-manager9.2.11 Cluster.pm:588 filters rows by that SAME permission. Keeping
+ *   the credential makes an absent row meaningful for this vmid without claiming the entire
+ *   cluster list is unfiltered. A newly minted credential would not carry that evidence.
+ */
+import * as cluster from '@distilled.cloud/proxmox/cluster';
+import * as nodes from '@distilled.cloud/proxmox/nodes';
+import * as Effect from 'effect/Effect';
+import { runPveWith } from './distilled-pve.ts';
+import { leased } from './lease-cache.ts';
+import { LxcRefusedError, type LxcWhere } from './lxc-errors.ts';
+import { text } from './values.ts';
+
+export const readLive = (where: LxcWhere) =>
+  Effect.gen(function* () {
+    const credential = yield* leased(where.target, 'read');
+    const answer = yield* runPveWith(
+      where.target,
+      credential,
+      false,
+      nodes.getNodeLxcConfig({ node: where.node, vmid: String(where.vmid) }),
+    ).pipe(
+      Effect.map((data) => ({ data, error: undefined })),
+      Effect.catchTag('LxcConfigNotFound', (error) => Effect.succeed({ data: undefined, error })),
+    );
+    if (answer.error === undefined) {
+      const live: unknown = answer.data;
+      // ⛔ The vendor requires digest on a real config. Null/empty output is not absence.
+      if (
+        live === null ||
+        typeof live !== 'object' ||
+        Array.isArray(live) ||
+        !('digest' in live) ||
+        typeof live.digest !== 'string' ||
+        live.digest === ''
+      ) {
+        return yield* Effect.fail(
+          new LxcRefusedError(
+            `CT ${String(where.vmid)}: config read did not return a valid digest-bearing config.`,
+          ),
+        );
+      }
+      return live as Record<string, unknown>;
+    }
+    const rows = yield* runPveWith(
+      where.target,
+      credential,
+      false,
+      cluster.listClusterResources({ type: 'vm' }),
+    );
+    // ⛔ Unknown row identities cannot establish that this cluster-wide vmid is free.
+    if (
+      !Array.isArray(rows) ||
+      rows.some(
+        (row) =>
+          !Number.isSafeInteger(Number(row?.vmid)) ||
+          Number(row?.vmid) <= 0 ||
+          typeof row?.node !== 'string' ||
+          row.node === '' ||
+          !['lxc', 'qemu'].includes(row.type),
+      )
+    ) {
+      return yield* Effect.fail(
+        new LxcRefusedError('The cluster guest index did not identify its rows.'),
+      );
+    }
+    // Number() preserves the vendor's numeric/string vmid spellings.
+    const found = rows.find((row) => Number(row.vmid) === where.vmid);
+    if (found !== undefined && found.node === where.node && found.type === 'lxc') {
+      return yield* Effect.fail(answer.error);
+    }
+    if (found !== undefined) {
+      return yield* Effect.fail(
+        new LxcRefusedError(
+          `vmid ${String(where.vmid)} is a ${text(found.type, 'guest')} on ` +
+            `${text(found.node, '?')}, not a container on ${where.node}. A migration is not an ` +
+            'update and vmids are cluster-wide: declare the node it is on, or pick a free vmid.',
+        ),
+      );
+    }
+    return undefined;
+  });

package/src/proxmox/lxc-task.ts

@@ -0,0 +1,71 @@
+/** LXC task observation is bounded and uses the exact credential that started the worker. */
+import * as nodes from '@distilled.cloud/proxmox/nodes';
+import type { ProxmoxOpContext } from '@distilled.cloud/proxmox/Protocol';
+import * as Effect from 'effect/Effect';
+import { runPveWith } from './distilled-pve.ts';
+import { LxcRefusedError, type LxcWhere } from './lxc-errors.ts';
+import { mint } from './mint.ts';
+import { text } from './values.ts';
+
+/**
+ * ⛔ Fresh provision mint for each write, then retain it for every task poll. PVE's task
+ *   owner skips Sys.Audit; another mint is another token identity. This also gives a create
+ *   the full lease rather than a cached lease with only 60 seconds left.
+ * ⚠️ A failed post-write poll is uncertainty, never absence or permission to retry the write.
+ *   Preserve the existing one-second bound and the UPID diagnostic. NetworkApply keeps its
+ *   separate raw helper; migrating this caller does not alter reload behavior.
+ * ★ SDK labels are percent-encoded. Installed APIServer/AnyEvent.pm uri_unescape runs before
+ *   routing, so an encoded UPID reaches the same task as its old literal spelling.
+ */
+export const lxcTask = <E>(
+  where: LxcWhere,
+  operation: Effect.Effect<string, E, ProxmoxOpContext>,
+  what: string,
+  polls: number,
+) =>
+  Effect.gen(function* () {
+    const credential = yield* mint(where.target, 'provision');
+    const upid = text(yield* runPveWith(where.target, credential, true, operation));
+    if (upid === '')
+      return yield* Effect.fail(
+        new LxcRefusedError(
+          `${what}: PVE returned no task id, so the write cannot be confirmed and is not claimed.`,
+        ),
+      );
+    let exit = 'still running when this provider stopped waiting';
+    for (let attempt = 0; attempt < polls; attempt++) {
+      const status = yield* runPveWith(
+        where.target,
+        credential,
+        false,
+        nodes.getNodeTaskStatus({ node: where.node, upid }),
+      ).pipe(Effect.orElseSucceed(() => undefined));
+      // ⚠️ "COULD NOT BE READ" IS A MISSING ANSWER OR A MISSING `status` FIELD, NOT AN UNEXPECTED
+      //   ONE. `GetNodeTaskStatusResponseStatus` types `status` as the closed union
+      //   `"running" | "stopped"`, but the runtime validator is `S.String` (measured in
+      //   distilled-proxmox's nodes.ts) and MEASURED here to accept an empty `{}` for a malformed
+      //   `data: null` answer (status.status undefined, no decode error) — so `status.status ===
+      //   undefined` is the real "unreadable" signal, matching network-apply-read.ts's `awaitTask`
+      //   and this file's own malformed-answer test. A well-formed answer with a status word this
+      //   endpoint's contract was never proven to exclude (something other than exactly "running")
+      //   must keep polling rather than abort, since only "stopped" ends the task
+      //   (2026-09-25 adversarial review).
+      if (status === undefined || status.status === undefined) {
+        exit =
+          'the task could not be read -- the node stopped answering, or this lease cannot see it';
+        break;
+      }
+      if (status.status === 'stopped') {
+        exit = text(status.exitstatus, 'stopped with no exitstatus');
+        break;
+      }
+      yield* Effect.sleep('1 second');
+    }
+    if (exit !== 'OK')
+      return yield* Effect.fail(
+        new LxcRefusedError(
+          `${what}: task ${upid} ended "${exit}". Read \`pvesh get /nodes/${where.node}/tasks/` +
+            `${upid}/log\` before running the deploy again.`,
+        ),
+      );
+  });

package/src/proxmox/network-apply-distilled.test.ts

@@ -0,0 +1,76 @@
+/** NetworkApply over a stub. The interfaces diff must not enter state. */
+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 { ProxmoxNetworkApply, ProxmoxNetworkApplyProvider } from './network-apply.ts';
+
+const SECRET = 'wpa-psk-do-not-store';
+const DIFF = `--- a/interfaces\n+++ b/interfaces\n@@ -1 +1 @@\n-old\n+${SECRET}\n`;
+const UPID = 'UPID:pve1:00000001:0:0:srvreload:networking:test@pve!fake:';
+const health = [
+  { id: 'cluster', name: 'c1', type: 'cluster', quorate: 1 },
+  { id: 'node/pve1', name: 'pve1', type: 'node', online: 1 },
+];
+const task = {
+  exitstatus: 'OK',
+  id: 'networking',
+  node: 'pve1',
+  pid: 1,
+  pstart: 1,
+  starttime: 1,
+  status: 'stopped',
+  type: 'srvreload',
+  upid: UPID,
+  user: 'test@pve',
+};
+
+const engine = (staged: { value: boolean }) => {
+  const fake = fakePve((call) => {
+    if (call.path.startsWith('cluster/status')) return health;
+    if (call.path.includes('/tasks/')) return task;
+    if (call.method === 'PUT') {
+      staged.value = false;
+      return UPID;
+    }
+    if (call.path.startsWith('nodes/pve1/network')) {
+      return staged.value
+        ? Response.json({
+            changes: DIFF,
+            data: [{ iface: 'vmbr0', type: 'bridge' }],
+          })
+        : [{ iface: 'vmbr0', type: 'bridge' }];
+    }
+    return null;
+  });
+  return {
+    fake,
+    stack: engineOver(ProxmoxNetworkApplyProvider().pipe(Layer.provideMerge(fake.layer))),
+  };
+};
+
+const declare = () => ProxmoxNetworkApply('row', { node: 'pve1', target: FAKE_TARGET });
+
+test('a settled node is adopted without a reload', async () => {
+  const { fake, stack } = engine({ value: false });
+  await withoutBao(async () => {
+    expect(await stack.deploy(declare())).toEqual({ row: 'adopted' });
+    expect((await stack.verify(declare(), { all: true })).rows[0]).toMatchObject({ diff: 'noop' });
+  });
+  expect(fake.writes()).toEqual([]);
+});
+
+test('a staged diff is applied once, then the secret is not in state', async () => {
+  const staged = { value: true };
+  const { fake, stack } = engine(staged);
+  await withoutBao(async () => {
+    expect((await stack.verify(declare(), { all: true })).rows[0]).toMatchObject({
+      diff: 'update',
+    });
+    await stack.deploy(declare());
+    expect(stack.stored()).not.toContain(SECRET);
+    expect((await stack.verify(declare(), { all: true })).rows[0]).toMatchObject({ diff: 'noop' });
+  });
+  expect(fake.writes()).toEqual(['PUT nodes/pve1/network']);
+  expect(fake.calls.some((call) => JSON.stringify(call).includes(SECRET))).toBe(false);
+});

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

@@ -17,13 +17,8 @@
  *   of `data`, set only when the diff is non-empty. `client.ts`'s `pve()` returns `body.data` and
  *   drops the envelope, so the one readable pending signal is invisible to every other resource in
  *   this package. Without the fetch below, `Proxmox.NetworkApply` could not diff honestly at all.
- *   ★ `pveEnvelopeWith` in client.ts now carries the same member failover as every other call.
- *   ⛔ WHY THIS FAMILY DID NOT MOVE TO DISTILLED WITH `Proxmox.NodeNetwork` (2026-09-24, decision
- *     43's walk-down): CONFIRMED against `@distilled.cloud/proxmox`'s own `protocol.ts` that its
- *     `transformResponse` unconditionally returns `body.data ?? {}` for every operation, before a
- *     generated call's typed output is even built — no typed call, current or future, could see
- *     `changes` without a protocol-level change upstream. `pveEnvelopeWith` stays because nothing
- *     else preserves the sibling this function needs.
+ *   ★ `listNodeNetwork` keeps a string `changes` sibling. The protocol unwraps every other
+ *     envelope. The diff string is counted here and then dropped.
  *
  * ⛔ AND THE INTERFACE ROWS CANNOT TELL YOU EITHER. MEASURED in PVE/INotify.pm `read_file`: when
  *   `/etc/network/interfaces.new` exists, THAT is the file that gets parsed, so
@@ -41,21 +36,14 @@
  *   there waiting for the next reload anybody triggers. The file's existence is not exposed by the
  *   API in any other form, so the alternative is not a better read — it is SSH.
  */
+import * as cluster from '@distilled.cloud/proxmox/cluster';
+import * as nodes from '@distilled.cloud/proxmox/nodes';
 import * as Effect from 'effect/Effect';
-import { pve, pveEnvelopeWith, pveWith } from './client.ts';
+import { runPve, runPveWith } from './distilled-pve.ts';
 import { type PveCredential, type PveTarget } from './credentials.ts';
 import { leased } from './lease-cache.ts';
 import { bool, text } from './values.ts';
 
-/** The `GET /nodes/{node}/network` envelope. ⛔ `changes` is beside `data`, never inside it. */
-type NetworkEnvelope = { changes?: string };
-
-/** One row of `GET /cluster/status` — a `cluster` row, or one `node` row per member. */
-type StatusRow = { type?: string; name?: string; quorate?: unknown; online?: unknown };
-
-/** One `GET /nodes/{node}/tasks/{upid}/status` answer. `status` is `running` or `stopped`. */
-type TaskStatus = { status?: string; exitstatus?: string };
-
 /** What the cluster looked like the moment it was asked. Never persisted — see network-apply.ts. */
 export type ClusterHealth = { quorate: boolean; offline: readonly string[] };
 
@@ -70,7 +58,6 @@ export type ClusterHealth = { quorate: boolean; offline: readonly string[] };
  */
 const stagedDiff = (target: PveTarget, node: string) =>
   Effect.gen(function* () {
-    const path = `nodes/${node}/network`;
     // ⚠️ THE `read` ROLE IS ENOUGH, AND DELIBERATELY SO. The schema's permission for this GET is
     //   `"user": "all"` — no privilege check at all — so the pending read never needs the
     //   provisioning lease, and a plan stays a plan even if the write role is missing entirely.
@@ -79,8 +66,9 @@ const stagedDiff = (target: PveTarget, node: string) =>
     //   SIX extra `hf-read@pve` tokens on node-b per C1 plan (one per node, for read and for diff),
     //   MEASURED 2026-09-14 while the cache itself made one read mint for the whole run.
     const credential = yield* leased(target, 'read');
-    const envelope = (yield* pveEnvelopeWith(target, credential, 'GET', path)) as NetworkEnvelope;
-    return text(envelope.changes);
+    const live = yield* runPveWith(target, credential, false, nodes.listNodeNetwork({ node }));
+    // ⛔ The diff string is not returned from pendingCount and is not an attribute.
+    return Array.isArray(live) ? '' : live.changes;
   });
 
 /**
@@ -128,7 +116,7 @@ export const pendingCount = (target: PveTarget, node: string) =>
  *   It is asked of the `read` role, which is auditor-shaped, rather than of `provision`.
  */
 const clusterHealth = (target: PveTarget) =>
-  pve<StatusRow[]>(target, 'read', 'GET', 'cluster/status').pipe(
+  runPve(target, 'read', false, cluster.listClusterStatus({})).pipe(
     Effect.map((rows) => {
       const all = rows ?? [];
       const cluster = all.find((row) => row.type === 'cluster');
@@ -195,11 +183,8 @@ const ATTEMPTS = 30;
  *   is not the owner — which is why this takes a `PveCredential` and the caller keeps one lease
  *   across both calls, instead of widening the provisioning role to read its own tasks.
  *
- * ⛔ THE OTHER REASON THIS FAMILY DID NOT MOVE TO DISTILLED (2026-09-24): CHECKED against
- *   `@distilled.cloud/proxmox`'s own `Task.awaitTask` (`src/task.ts`) before deciding — it
- *   propagates a poll failure as a genuine typed `GetNodeTaskStatusError` rather than collapsing
- *   it to `UNREACHABLE` the way this function does, which would turn the ⛔ two paragraphs above
- *   into a failed `reconcile` on exactly the poll a mid-reload connection drop is expected to hit.
+ * ★ A poll failure stays `UNREACHABLE`. `getNodeTaskStatus` would otherwise fail the reload
+ *   on the connection drop this function exists to survive.
  */
 export const awaitTask = (
   target: PveTarget,
@@ -210,16 +195,7 @@ export const awaitTask = (
   attempts: number = ATTEMPTS,
 ) =>
   Effect.gen(function* () {
-    /**
-     * ⚠️ THE UPID GOES IN RAW, NOT PERCENT-ENCODED, AND THE CHOICE IS DELIBERATE. A UPID is
-     *   `UPID:<node>:<hex>:<hex>:<hex>:<type>:<id>:<user>:` — its only punctuation is `:`, `@`, `!`
-     *   and `-`, every one of which is a legal path character, so raw needs nothing from the
-     *   router. Encoding them instead RELIES on PVE unescaping each path segment, which is
-     *   plausible and was NOT measured here (measuring it means starting a task, i.e. writing). If
-     *   that assumption were wrong the poll would 404, this would report the outcome as unknown,
-     *   and a perfectly good reload would stop the deploy. Raw removes the assumption.
-     */
-    const path = `nodes/${node}/tasks/${upid}/status`;
+    // ★ The SDK percent-encodes the UPID label. PVE APIServer unescapes it before routing.
     for (let attempt = 0; attempt < attempts; attempt += 1) {
       /**
        * ⛔ A FAILED POLL IS NOT A FAILED RELOAD, AND CALLING IT ONE WOULD BE THE WORST KIND OF
@@ -231,9 +207,12 @@ export const awaitTask = (
        *   task's owner, the endpoint wants `Sys.Audit` on the node and this sees only "no answer" —
        *   which is why `UNREACHABLE` names both possibilities rather than blaming the network.
        */
-      const status = yield* pveWith<TaskStatus>(target, credential, 'GET', path).pipe(
-        Effect.orElseSucceed(() => undefined),
-      );
+      const status = yield* runPveWith(
+        target,
+        credential,
+        false,
+        nodes.getNodeTaskStatus({ node, upid }),
+      ).pipe(Effect.orElseSucceed(() => undefined));
       if (status === undefined) return UNREACHABLE;
       if (status.status === 'stopped') return text(status.exitstatus, 'stopped with no exitstatus');
       yield* Effect.sleep('1 second');

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/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) });