@homeflare/alchemy 0.37.6 → 0.37.7

package/src/proxmox/firewall-alias-lifecycle.ts

@@ -0,0 +1,100 @@
+/** Named SDK operations; pve-firewall 6.0.5 Aliases.pm supplies exact absence and idempotent delete. */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as cluster from '@distilled.cloud/proxmox/cluster';
+import { ProxmoxParseError } from '@distilled.cloud/proxmox/Errors';
+import * as Effect from 'effect/Effect';
+import type { FirewallAliasAttributes, FirewallAliasProps } from './firewall-alias.ts';
+import { firewallAliasSpec as spec } from './firewall-alias-config.ts';
+import { cidr, fold } from './firewall-alias-form.ts';
+import { runPve } from './distilled-pve.ts';
+import { specGuards } from './resource-guard.ts';
+import { formToSend } from './update-guard.ts';
+
+const { guardCreate, guardUpdate } = specGuards(spec);
+
+export const readFirewallAlias = (props: FirewallAliasProps) =>
+  runPve(props.target, 'read', false, cluster.getClusterFirewallAlias({ name: props.name })).pipe(
+    Effect.flatMap((live) => {
+      // Vendor's GET schema is bare object; read_alias returns the stored name/cidr entry.
+      // ⛔ A malformed successful read is not absence and must never authorize a POST.
+      if (
+        live === null ||
+        typeof live !== 'object' ||
+        Array.isArray(live) ||
+        !('name' in live) ||
+        typeof live.name !== 'string' ||
+        fold(live.name) !== fold(props.name) ||
+        !('cidr' in live) ||
+        typeof live.cidr !== 'string' ||
+        cidr(live.cidr) === ''
+      ) {
+        return Effect.fail(
+          new ProxmoxParseError({
+            body: undefined,
+            cause: 'Firewall alias response does not match the requested vendor identity',
+          }),
+        );
+      }
+      return Effect.succeed(spec.attributes({ ...live }, props));
+    }),
+    Effect.catchTag('FirewallAliasNotFound', () => Effect.succeed(undefined)),
+  );
+
+/** Vendor deletion silently removes a missing key. All actual SDK failures still propagate. */
+export const deleteFirewallAlias = (props: FirewallAliasProps) =>
+  runPve(props.target, 'provision', true, cluster.deleteClusterFirewallAlias({ name: props.name }));
+
+export const firewallAliasHandlers = {
+  list: () => Effect.succeed([]),
+  read: ({ olds }: { olds: FirewallAliasProps }) => readFirewallAlias(olds),
+  diff: Effect.fn(function* ({
+    news,
+    output,
+  }: {
+    news: Input<FirewallAliasProps>;
+    output: FirewallAliasAttributes | undefined;
+  }) {
+    if (!isResolved(news)) return undefined;
+    yield* guardCreate(news, output === undefined);
+    yield* guardUpdate(news);
+    if (output === undefined) return undefined;
+    // A case-only spelling is the same vendor key; a real rename remains create-first replacement.
+    if (fold(news.name) !== fold(output.name)) return { action: 'replace' } as const;
+    const live = yield* readFirewallAlias(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: FirewallAliasProps }) {
+    const live = yield* readFirewallAlias(news);
+    yield* guardCreate(news, live === undefined);
+    yield* guardUpdate(news);
+    if (live === undefined) {
+      yield* runPve(
+        news.target,
+        'provision',
+        true,
+        cluster.createClusterFirewallAlias(spec.createForm(news)),
+      );
+    } else {
+      const form = formToSend(spec.matches, live, news, spec.updateForm(news));
+      if (form !== undefined)
+        yield* runPve(
+          news.target,
+          'provision',
+          true,
+          cluster.putClusterFirewallAlias({ ...form, name: news.name }),
+        );
+    }
+    const after = yield* readFirewallAlias(news);
+    if (after === undefined)
+      return yield* Effect.fail(
+        new Error(`${spec.path(news)}: write returned success but the resource is still absent`),
+      );
+    return after;
+  }),
+  delete: ({ olds }: { olds: FirewallAliasProps }) => deleteFirewallAlias(olds),
+};

package/src/proxmox/firewall-alias.ts

@@ -93,12 +93,10 @@
  *   confirm the SECOND plan says noop before trusting this file.
  */
 import { Resource } from 'alchemy';
-import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { body, cidr, comment, fold } from './firewall-alias-form.ts';
-import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
-import { int, text } from './values.ts';
+import type { PveRequirements, WithTarget } from './resource-spec.ts';
+import { firewallAliasHandlers } from './firewall-alias-lifecycle.ts';
 
 export interface FirewallAliasProps extends WithTarget {
   /**
@@ -144,70 +142,9 @@ export interface ProxmoxFirewallAlias extends Resource<
 
 export const ProxmoxFirewallAlias = Resource<ProxmoxFirewallAlias>('Proxmox.FirewallAlias');
 
-const handlers = pveHandlers<FirewallAliasProps, FirewallAliasAttributes>({
-  /**
-   * ⚠️ AN ENTRY WITH NO CIDR IS NOT AN ALIAS. `read_alias` raises for a name it does not hold, so
-   *   absence normally arrives as a failed call the factory folds into `undefined`; this guard
-   *   covers the other shape — a 200 carrying something that is not an alias — rather than
-   *   recording state for an object with an empty address. The next reconcile then POSTs and PVE
-   *   answers "alias already exists", which is loud and points at the read.
-   */
-  attributes: (live, props) => {
-    const address = cidr(live['cidr']);
-    return address === ''
-      ? undefined
-      : {
-          cidr: address,
-          comment: comment(live['comment']),
-          ipversion: int(live['ipversion'], 0),
-          /** ⚠️ FROM THE CLUSTER, falling back to props: the stored spelling is the interesting one. */
-          name: text(live['name'], props.name),
-        };
-  },
-  collection: () => 'cluster/firewall/aliases',
-  createForm: (props) => ({ ...body(props), name: props.name }),
-  /**
-   * ⚠️ EXACTLY THE TWO FIELDS A PUT CAN PUT BACK, both sides through the same normalisers. `name`
-   *   is identity and case-only drift (see the header); `ipversion` is derived and unwritable.
-   *   Comparing either would report an update that no update can settle.
-   */
-  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
-  endpoint: {
-    create: 'pve:POST /cluster/firewall/aliases',
-    update: 'pve:PUT /cluster/firewall/aliases/{name}',
-  },
-  matches: (attributes, props) =>
-    attributes.cidr === cidr(props.cidr) && attributes.comment === comment(props.comment),
-  /**
-   * ⚠️ UNESCAPED ON PURPOSE: `pve-fw-alias` admits only `[A-Za-z][A-Za-z0-9\-\_]+`, so there is no
-   *   character here that a URL would need to encode, and PVE lowercases the segment on arrival.
-   */
-  path: (props) => `cluster/firewall/aliases/${props.name}`,
-  updateForm: body,
-});
-
-/**
- * ⛔ ONE HANDLER IS OVERRIDDEN AND THE REST COME FROM THE FACTORY, for the reason `acl.ts` spells
- *   out at length: the factory answers `replace` only for an object with no update path, and this
- *   one has a PUT. Left to delegate, a changed `name` would read absent at the new path, plan as an
- *   update, and quietly leave the old alias behind. Everything else — the empty `list`, the read,
- *   the read-back-guarded reconcile, the delete — is the factory's, unchanged.
- */
+/** Named distilled operations preserve create-first identity replacement and explicit adoption. */
 export const ProxmoxFirewallAliasProvider = () =>
   Provider.effect(
     ProxmoxFirewallAlias,
-    Effect.succeed(
-      ProxmoxFirewallAlias.Provider.of({
-        ...handlers,
-        diff: Effect.fn(function* ({ news, output }) {
-          // ⚠️ `isResolved` FIRST: at plan time `news.name` can still be an unresolved Output, and
-          //   folding a placeholder would report a replace nobody asked for — the worst possible
-          //   false positive on this family, since a replace here DELETES an alias.
-          if (output !== undefined && isResolved(news) && fold(news.name) !== fold(output.name)) {
-            return { action: 'replace' } as const;
-          }
-          return yield* handlers.diff({ news, output });
-        }),
-      }),
-    ),
+    Effect.succeed(ProxmoxFirewallAlias.Provider.of(firewallAliasHandlers)),
   );

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

@@ -96,7 +96,10 @@ describe('removing a container', () => {
       `POST nodes/${NODE}/lxc`,
       `DELETE nodes/${NODE}/lxc/${String(VMID)}`,
     ]);
-    expect(pve.seen.some((call) => /\/tasks\/UPID:.*vzdestroy/.test(call.path))).toBe(true);
+    // PVE APIServer/AnyEvent.pm uri_unescape runs before routing; the SDK encodes labels.
+    expect(
+      pve.seen.some((call) => /\/tasks\/UPID:.*vzdestroy/.test(decodeURIComponent(call.path))),
+    ).toBe(true);
     // ⛔ No `force` (stops a running guest), `purge` (drops it from HA and backup jobs) or
     //   `destroy-unreferenced-disks` (deletes volumes the config does not even name).
     const del = pve.seen.find((call) => call.method === 'DELETE');

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

@@ -0,0 +1,239 @@
+/** Real SDK HTTP boundary: credential continuity, dynamic fields, digest and task uncertainty. */
+import { expect, test } from 'bun:test';
+import * as nodes from '@distilled.cloud/proxmox/nodes';
+import * as Deferred from 'effect/Deferred';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Fiber from 'effect/Fiber';
+import * as Layer from 'effect/Layer';
+import * as TestClock from 'effect/testing/TestClock';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { FAKE_TARGET, withoutBao } from './fake-pve.ts';
+import { createGuest, updateGuest } from './lxc-lifecycle.ts';
+import type { LxcProps } from './lxc-props.ts';
+import { readLive } from './lxc-read.ts';
+import { lxcTask } from './lxc-task.ts';
+
+const props: LxcProps = {
+  hostname: 'ct-example',
+  node: 'pve1',
+  vmid: 900,
+  target: FAKE_TARGET,
+  ostemplate: 'local:vztmpl/test.tar.zst',
+  rootfs: 'local-zfs:8',
+  net0: 'name=eth0,bridge=vmbr0,ip=dhcp',
+  mp0: 'tank:10,mp=/data',
+};
+type Seen = { method: string; path: string; auth: string | null; form: URLSearchParams };
+const UPID = 'UPID:pve1:00000001:0:0:vzcreate:900:test@pve!lease:';
+
+const transport = (
+  poll: () => Response = () => Response.json({ data: { status: 'stopped', exitstatus: 'OK' } }),
+  index: unknown = [],
+) => {
+  const seen: Seen[] = [];
+  let mints = 0;
+  const stub = async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    if (url.pathname.includes('/creds/')) {
+      mints++;
+      return Response.json({
+        data: { secret: `fake-${mints}`, token_id: `test@pve!lease-${mints}` },
+        lease_duration: 0,
+      });
+    }
+    const body = await request.text();
+    if (request.method === 'GET') expect(body).toBe('');
+    const path = decodeURIComponent(url.pathname.replace(/^\/api2\/json\//, ''));
+    seen.push({
+      method: request.method,
+      path,
+      auth: request.headers.get('Authorization'),
+      form: new URLSearchParams(body),
+    });
+    if (path.endsWith('/status')) return poll();
+    if (request.method === 'GET' && path.endsWith('/config'))
+      return Response.json(
+        { data: null, message: "Configuration file 'nodes/pve1/lxc/900.conf' does not exist\n" },
+        { status: 500 },
+      );
+    if (path === 'cluster/resources') {
+      expect(url.searchParams.get('type')).toBe('vm');
+      return Response.json({ data: index });
+    }
+    return Response.json({ data: path.endsWith('/config') ? null : UPID });
+  };
+  const fake = Object.assign(stub, { preconnect: globalThis.fetch.preconnect }) as typeof fetch;
+  return {
+    seen,
+    mints: () => mints,
+    layer: FetchHttpClient.layer.pipe(
+      Layer.provideMerge(Layer.succeed(FetchHttpClient.Fetch, fake)),
+    ),
+  };
+};
+
+test('missing config and permission-filtered guest index use one read credential', async () => {
+  const fake = transport();
+  const result = await withoutBao(() =>
+    Effect.runPromise(readLive(props).pipe(Effect.provide(fake.layer))),
+  );
+  expect(result).toBeUndefined();
+  expect(fake.mints()).toBe(1);
+  expect(fake.seen.map((call) => call.path)).toEqual([
+    'nodes/pve1/lxc/900/config',
+    'cluster/resources',
+  ]);
+  expect(fake.seen[0]?.auth).toBe(fake.seen[1]?.auth);
+});
+
+test('each task starts with a fresh credential and every poll keeps its owner', async () => {
+  const fake = transport();
+  await withoutBao(() =>
+    Effect.runPromise(
+      Effect.gen(function* () {
+        yield* createGuest(props);
+        yield* updateGuest(
+          props,
+          { put: {}, clear: [], resize: [{ disk: 'rootfs', size: '12G' }], refuse: [], drift: [] },
+          'digest-live',
+        );
+      }).pipe(Effect.provide(fake.layer)),
+    ),
+  );
+  expect(fake.mints()).toBe(2);
+  expect(fake.seen.map((call) => call.method)).toEqual(['POST', 'GET', 'PUT', 'GET']);
+  expect(fake.seen[0]?.auth).toBe(fake.seen[1]?.auth);
+  expect(fake.seen[2]?.auth).toBe(fake.seen[3]?.auth);
+  expect(fake.seen[0]?.auth).not.toBe(fake.seen[2]?.auth);
+  const form = fake.seen[0]?.form;
+  expect(form?.get('net0')).toBe(props.net0);
+  expect(form?.get('mp0')).toBe(props.mp0);
+  expect(form?.has('net[n]')).toBe(false);
+  expect(form?.has('node')).toBe(false);
+  expect(fake.seen[2]?.form.get('size')).toBe('12G');
+});
+
+test('config updates retain the observed digest and concrete indexed form keys', async () => {
+  const fake = transport();
+  await withoutBao(() =>
+    Effect.runPromise(
+      updateGuest(
+        props,
+        {
+          put: { net1: 'name=eth1,bridge=vmbr1,ip=dhcp' },
+          clear: ['tags'],
+          resize: [],
+          refuse: [],
+          drift: [],
+        },
+        'observed-digest',
+      ).pipe(Effect.provide(fake.layer)),
+    ),
+  );
+  expect(fake.seen).toHaveLength(1);
+  const form = fake.seen[0]?.form;
+  expect(form?.get('digest')).toBe('observed-digest');
+  expect(form?.get('net1')).toBe('name=eth1,bridge=vmbr1,ip=dhcp');
+  expect(form?.get('delete')).toBe('tags');
+  expect(form?.has('vmid')).toBe(false);
+  expect(form?.has('node')).toBe(false);
+});
+
+for (const [name, response] of [
+  ['denied', () => Response.json({ data: null, message: 'denied' }, { status: 403 })],
+  ['malformed', () => Response.json({ data: null })],
+] as const) {
+  test(`${name} task polling reports uncertainty with UPID, never repeats POST`, async () => {
+    const fake = transport(response);
+    const error = await withoutBao(() =>
+      Effect.runPromise(createGuest(props).pipe(Effect.flip, Effect.provide(fake.layer))),
+    );
+    expect(String(error)).toContain(UPID);
+    expect(String(error)).toContain('task could not be read');
+    expect(fake.seen.map((call) => call.method)).toEqual(['POST', 'GET']);
+  });
+}
+
+test('a still-running task stops at its bound with no second POST', async () => {
+  let polls = 0;
+  const fake = transport(() => {
+    polls++;
+    return Response.json({ data: { status: 'running' } });
+  });
+  const outcome = await withoutBao(() =>
+    Effect.runPromise(
+      Effect.gen(function* () {
+        const ready = yield* Deferred.make<void>();
+        // Start the virtual clock only after the SDK transport has completed its first response.
+        const observed = fake.layer;
+        const worker = yield* lxcTask(
+          props,
+          nodes.createNodeLxc({
+            node: props.node,
+            vmid: String(props.vmid),
+            ostemplate: props.ostemplate ?? '',
+          }),
+          'create test CT',
+          2,
+        ).pipe(Effect.exit, Effect.provide(observed), Effect.forkChild);
+        const signal = yield* Effect.gen(function* () {
+          while (polls < 1) yield* Effect.yieldNow;
+          yield* Deferred.succeed(ready, undefined);
+        }).pipe(Effect.forkChild);
+        yield* Deferred.await(ready);
+        yield* TestClock.adjust('2 seconds');
+        yield* Fiber.join(signal);
+        return yield* Fiber.join(worker);
+      }).pipe(Effect.provide(TestClock.layer())),
+    ),
+  );
+  expect(Exit.isFailure(outcome)).toBe(true);
+  expect(polls).toBe(2);
+  expect(fake.seen.filter((call) => call.method === 'POST')).toHaveLength(1);
+});
+
+test('a transitional status value keeps polling, never aborts like an unreadable poll', async () => {
+  // ⚠️ `GetNodeTaskStatusResponseStatus` TYPES `status` AS "running" | "stopped" BUT VALIDATES IT
+  //   AT RUNTIME AS A PLAIN STRING — that union is not actually enforced on the wire, so a value
+  //   this endpoint's real contract was never proven to exclude must be tolerated the same way
+  //   `awaitTask` (network-apply-read.ts) tolerates it, rather than read as "task could not be
+  //   read" and abort the deploy. The sibling malformed-answer tests above pin the other half:
+  //   a response with no `status` field at all still aborts (2026-09-25 adversarial review).
+  let polls = 0;
+  const fake = transport(() => {
+    polls++;
+    return Response.json({
+      data: { status: polls === 1 ? 'queued' : 'stopped', exitstatus: 'OK' },
+    });
+  });
+  const outcome = await withoutBao(() =>
+    Effect.runPromise(
+      lxcTask(
+        props,
+        nodes.createNodeLxc({
+          node: props.node,
+          vmid: String(props.vmid),
+          ostemplate: props.ostemplate ?? '',
+        }),
+        'create test CT',
+        5,
+      ).pipe(Effect.provide(fake.layer)),
+    ),
+  );
+  expect(outcome).toBeUndefined();
+  expect(polls).toBe(2);
+});
+
+for (const index of [null, [{}], [{ vmid: 'unknown', node: 'pve1', type: 'lxc' }]]) {
+  test(`malformed guest index ${JSON.stringify(index)} cannot prove absence`, async () => {
+    const fake = transport(undefined, index);
+    const error = await withoutBao(() =>
+      Effect.runPromise(readLive(props).pipe(Effect.flip, Effect.provide(fake.layer))),
+    );
+    expect(String(error)).toContain('did not identify its rows');
+    expect(fake.seen.every((call) => call.method === 'GET')).toBe(true);
+  });
+}

package/src/proxmox/lxc-errors.ts

@@ -0,0 +1,9 @@
+import type { PveTarget } from './credentials.ts';
+
+/** A lifecycle refusal. Post-write refusals carry the task diagnostic, never imply rollback. */
+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 };

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,
+    );
   });