@homeflare/alchemy 0.37.5 → 0.37.7

package/src/proxmox/lxc-lifecycle.ts

@@ -1,50 +1,33 @@
 /**
  * The calls a `Proxmox.Lxc` makes: read one config, create, update in place, grow, delete.
  *
- * ⛔ A READ FAILURE IS A FAILURE HERE, NOT "ABSENT" — THE ONE PLACE THIS PACKAGE DEPARTS FROM
- *   resource.ts. `pveOperations.read` folds every error into `undefined`, which for a guest means a
- *   403 or a node that did not answer plans a CREATE over a running container. PVE answers a
- *   missing guest with HTTP 500, `Configuration file 'nodes/<node>/lxc/<vmid>.conf' does not
- *   exist` (pve-guest-common `AbstractConfig::load_config`), so only a 500 may mean absent — and
- *   even then only after the cluster says so, below. Anything else fails the plan.
- *
- * ⛔ "ABSENT" IS DECIDED BY THE WHOLE CLUSTER, NOT BY THE ERROR TEXT. A config lives under its
- *   node, so a guest migrated to another node — or a QEMU VM holding the same cluster-wide vmid —
- *   also reads as missing at the declared path. `GET /cluster/resources?type=vm` settles it: the
- *   vmid nowhere is absent; the vmid anywhere else FAILS the read with where it is; the vmid on
- *   the declared node fails with PVE's own error. ★ Keyed on the cluster rather than on matching
- *   the message, so a PVE that words it differently still cannot turn into a create.
+ * ★ Discovery lives in lxc-read.ts; it proves precise absence with one read credential.
+ *   Writes use named distilled operations, and lxc-task.ts preserves task ownership and bounds.
  *
  * ⚠️ CREATE, RESIZE AND DELETE ARE ASYNCHRONOUS; A CONFIG PUT IS NOT. The first three answer a
  *   UPID the moment PVE forks the worker (`NodesNodeLxcPostReturn`, `…ResizePutReturn`,
  *   `…VmidDeleteReturn` are all `string`), so each waits for its task's exitstatus. `PUT …/config`
  *   answers `null` after writing (`…ConfigPutReturn`), so it needs no wait.
- * ⛔ EACH TASK IS POLLED WITH THE CREDENTIAL THAT STARTED IT — see `awaitTask`: only the owner
+ * ⛔ EACH TASK IS POLLED WITH THE CREDENTIAL THAT STARTED IT — see `lxcTask`: only the owner
  *   skips `Sys.Audit`. A fresh `provision` mint per write gives the full 300s lease a create needs;
  *   a cached lease can be handed out with 60s left (lease-cache.ts).
  */
 import * as Effect from 'effect/Effect';
-import { PveError, pve, pveWith } from './client.ts';
+import * as nodes from '@distilled.cloud/proxmox/nodes';
+import { runPve } from './distilled-pve.ts';
+import { LxcRefusedError, type LxcWhere } from './lxc-errors.ts';
+import { readLive } from './lxc-read.ts';
+import { lxcTask } from './lxc-task.ts';
 import { guardForm } from './constraint-guard.ts';
 import type { EndpointKey } from './constraints.ts';
-import type { PveTarget } from './credentials.ts';
-import { mint } from './mint.ts';
 import { createForm } from './lxc-create-form.ts';
 import { type LxcChange, judge } from './lxc-judge.ts';
 import type { LxcAttributes, LxcProps } from './lxc-props.ts';
 import { rawKeysOf, storedConfig } from './lxc-props.ts';
-import { awaitTask } from './network-apply-read.ts';
 import { text, withClears } from './values.ts';
 
-/** A plan-time or apply-time refusal. Nothing was written when one of these is raised. */
-export class LxcRefusedError extends Error {
-  override readonly name = 'LxcRefusedError';
-}
-
-/** Where one guest lives. Its identity, and nothing else. */
-export type LxcWhere = { readonly target: PveTarget; readonly node: string; readonly vmid: number };
-
-export const guestPath = (where: LxcWhere) => `nodes/${where.node}/lxc/${String(where.vmid)}`;
+export { LxcRefusedError, type LxcWhere } from './lxc-errors.ts';
+export { readLive } from './lxc-read.ts';
 
 /**
  * The three vendor endpoints a guest is written through, as the generated tables key them.
@@ -70,52 +53,6 @@ const LXC_ENDPOINTS = {
 const CREATE_POLLS = 180;
 const TASK_POLLS = 60;
 
-const isServerError = (error: unknown): error is PveError =>
-  error instanceof PveError && error.status === 500;
-
-/** One `GET /cluster/resources?type=vm` row. */
-type GuestRow = { readonly vmid?: unknown; readonly node?: unknown; readonly type?: unknown };
-
-/** The live config, or undefined when no guest holds this vmid anywhere in the cluster. */
-export const readLive = (where: LxcWhere) =>
-  Effect.gen(function* () {
-    const answer = yield* pve<Record<string, unknown> | null>(
-      where.target,
-      'read',
-      'GET',
-      `${guestPath(where)}/config`,
-    ).pipe(
-      Effect.map((data) => ({ data, error: undefined })),
-      Effect.catchIf(isServerError, (error) => Effect.succeed({ data: undefined, error })),
-    );
-    if (answer.data !== undefined && answer.data !== null) return answer.data;
-    const rows = yield* pve<readonly GuestRow[]>(
-      where.target,
-      'read',
-      'GET',
-      'cluster/resources?type=vm',
-    );
-    // ⚠️ `Number()`, NOT `===` ON THE RAW VALUE: a vmid that came back as `"900"` would otherwise
-    //   match nothing, and "listed nowhere" is the one answer that turns into a create.
-    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 ??
-          new LxcRefusedError(`CT ${String(where.vmid)} is listed but its config read empty.`),
-      );
-    }
-    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;
-  });
-
 export const attributesOf = (where: LxcWhere, live: Record<string, unknown>): LxcAttributes => ({
   config: storedConfig(live),
   node: where.node,
@@ -123,36 +60,6 @@ export const attributesOf = (where: LxcWhere, live: Record<string, unknown>): Lx
   vmid: where.vmid,
 });
 
-/** Run one task-starting call and wait for it on the same credential. Fails unless `OK`. */
-const task = (
-  where: LxcWhere,
-  method: 'POST' | 'PUT' | 'DELETE',
-  path: string,
-  what: string,
-  polls: number,
-  form?: Record<string, string>,
-) =>
-  Effect.gen(function* () {
-    const credential = yield* mint(where.target, 'provision');
-    const upid = text(yield* pveWith<string>(where.target, credential, method, path, form));
-    if (upid === '') {
-      return yield* Effect.fail(
-        new LxcRefusedError(
-          `${what}: PVE returned no task id, so the write cannot be confirmed and is not claimed.`,
-        ),
-      );
-    }
-    const exit = yield* awaitTask(where.target, credential, where.node, upid, polls);
-    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.`,
-        ),
-      );
-    }
-  });
-
 /** POST the create and wait for the template to unpack. ⛔ Refusals are the caller's to check. */
 export const createGuest = (props: LxcProps) =>
   Effect.gen(function* () {
@@ -165,13 +72,16 @@ export const createGuest = (props: LxcProps) =>
      *   knew: `cores` 1..8192, `memory` ≥ 16, `hostname` as a dns-name, `tags`, `startup`.
      */
     yield* guardForm(LXC_ENDPOINTS.create, form, true);
-    return yield* task(
+    return yield* lxcTask(
       props,
-      'POST',
-      `nodes/${props.node}/lxc`,
+      nodes.createNodeLxc({
+        ...form,
+        node: props.node,
+        vmid: String(props.vmid),
+        ostemplate: text(form['ostemplate']),
+      }),
       `create CT ${String(props.vmid)}`,
       CREATE_POLLS,
-      form,
     );
   });
 
@@ -194,20 +104,23 @@ export const updateGuest = (props: LxcProps, change: LxcChange, digest: string)
       );
       /** ⚠️ NO PRESENCE: this form is partial by construction — it is `judge`'s answer. */
       yield* guardForm(LXC_ENDPOINTS.update, form, false);
-      yield* pve(props.target, 'provision', 'PUT', `${guestPath(props)}/config`, form);
+      yield* runPve(
+        props.target,
+        'provision',
+        true,
+        nodes.putNodeLxcConfig({ ...form, node: props.node, vmid: String(props.vmid) }),
+      );
     }
     for (const grow of change.resize) {
       const grown = { disk: grow.disk, size: grow.size };
       // ⛔ WITH PRESENCE: `disk` and `size` are both required and both always sent, so this is a
       //   value check over PVE's own `+<n>` size pattern and its `rootfs|mp0..mp255` enum.
       yield* guardForm(LXC_ENDPOINTS.resize, grown, true);
-      yield* task(
+      yield* lxcTask(
         props,
-        'PUT',
-        `${guestPath(props)}/resize`,
+        nodes.putNodeLxcResize({ ...grown, node: props.node, vmid: String(props.vmid) }),
         `grow ${grow.disk} of CT ${String(props.vmid)} to ${grow.size}`,
         TASK_POLLS,
-        grown,
       );
     }
   });
@@ -236,5 +149,10 @@ export const destroyGuest = (where: LxcWhere, declared: LxcProps) =>
         ),
       );
     }
-    yield* task(where, 'DELETE', guestPath(where), `destroy CT ${String(where.vmid)}`, TASK_POLLS);
+    yield* lxcTask(
+      where,
+      nodes.deleteNodeLxc({ node: where.node, vmid: String(where.vmid) }),
+      `destroy CT ${String(where.vmid)}`,
+      TASK_POLLS,
+    );
   });

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');