@homeflare/alchemy 0.8.0 → 0.10.1

package/src/proxmox/lxc-identity.ts

@@ -0,0 +1,43 @@
+/**
+ * What makes a `Proxmox.Lxc` a DIFFERENT guest: a new vmid, or another template. Judged by `diff`
+ * and `reconcile` in lxc.ts before anything else, and never planned as a replace — see lxc.ts.
+ */
+import type { LxcAttributes, LxcProps } from './lxc-props.ts';
+
+/** A prop's value if it is already plain data, else undefined (an unresolved Output). */
+const plain = (news: unknown, key: string): unknown => {
+  const value: unknown = (news as Record<string, unknown>)[key];
+  return typeof value === 'string' || typeof value === 'number' ? value : undefined;
+};
+
+/**
+ * ⛔ IDENTITY IS JUDGED BEFORE `isResolved(news)`. That guard returns early when ANY prop is still
+ *   an Output, and the engine then plans `update` — which, for a new vmid, would build a second
+ *   guest and orphan the first (the openbao rename lesson, rename.ts). A template is identity
+ *   too: it is consumed at create, so a different one is a different guest.
+ * ★ `node` IS NOT JUDGED HERE, BECAUSE A NODE CHANGE CAN BE THE DECLARATION CATCHING UP. HA fails
+ *   a guest over, or somebody runs `pct migrate`; the guest is on its new node before any line
+ *   says so. `readLive` at the declared node settles both cases: the guest is there (follow it,
+ *   and re-record state with a write-free update), or it is elsewhere and the read FAILS naming
+ *   where — asking to move a guest is a migration, and this resource does not migrate.
+ */
+export const identityRefusals = (
+  news: unknown,
+  olds: LxcProps,
+  output: LxcAttributes | undefined,
+): string[] => {
+  const was = output?.vmid ?? olds.vmid;
+  const vmid = plain(news, 'vmid');
+  const template = plain(news, 'ostemplate');
+  const reasons: string[] = [];
+  if (vmid !== undefined && vmid !== was) {
+    reasons.push(
+      `vmid: ${String(was)} -> ${String(vmid)} is a different guest. Declare it as a new ` +
+        'resource; this one is retained when its declaration goes.',
+    );
+  }
+  if (template !== undefined && olds.ostemplate !== undefined && template !== olds.ostemplate) {
+    reasons.push('ostemplate: a template is consumed at create; another one is a new guest.');
+  }
+  return reasons;
+};

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

@@ -0,0 +1,175 @@
+/**
+ * The pure half of `Proxmox.Lxc`: which spellings are one value, what a change writes, and what is
+ * refused — no server. The engine-level tests beside this one prove the same rules survive plan
+ * and apply; these pin each rule on its own, with PVE's reason next to it.
+ */
+import { describe, expect, test } from 'bun:test';
+import { TARGET } from './lxc-harness.ts';
+import { createForm, createRefusals } from './lxc-create-form.ts';
+import { judge } from './lxc-judge.ts';
+import { type LxcProps, rawKeysOf, storedConfig } from './lxc-props.ts';
+import { judgeVolume, parseVolume, sizeBytes } from './lxc-volume.ts';
+
+const props = (over: Partial<LxcProps>): LxcProps => ({
+  node: 'pve1',
+  target: TARGET,
+  vmid: 100,
+  ...over,
+});
+const live = (config: Record<string, unknown>) => ({ unprivileged: 1, ...config });
+
+describe('sizes and volumes, as pve-container parses them', () => {
+  test('parse_size: binary units, bare bytes, and nothing else', () => {
+    expect(sizeBytes('40G')).toBe(40 * 1024 ** 3);
+    expect(sizeBytes('1.5T')).toBe(1.5 * 1024 ** 4);
+    expect(sizeBytes('512M')).toBe(512 * 1024 ** 2);
+    expect(sizeBytes('100')).toBe(100);
+    expect(sizeBytes('40GB')).toBeUndefined();
+  });
+
+  test('classify_mountpoint, plus the new-disk spelling', () => {
+    expect(parseVolume('local-zfs:40').kind).toBe('new');
+    expect(parseVolume('local-zfs:subvol-1-disk-0,size=40G').kind).toBe('volume');
+    expect(parseVolume('/srv/share,mp=/share').kind).toBe('bind');
+    expect(parseVolume('/dev/sdb1,mp=/disk').kind).toBe('device');
+  });
+
+  test('an options change on a volume declared as new is written with the LIVE volume id', () => {
+    const verdict = judgeVolume('mp0', 'tank:200,mp=/data,backup=1', LIVE_MP);
+    expect(verdict).toEqual({ put: 'tank:subvol-100-disk-0,mp=/data,backup=1,size=200G' });
+  });
+
+  test('a fractional new-disk size grows by the same GiB', () => {
+    expect(judgeVolume('mp0', 'tank:200.5,mp=/data', LIVE_MP)).toEqual({ resize: '200.5G' });
+  });
+});
+
+const LIVE_MP = 'tank:subvol-100-disk-0,mp=/data,backup=0,size=200G';
+
+describe('scalars compare the way PVE stores them', () => {
+  test.each([
+    [
+      'a description PVE handed back with a newline',
+      { description: 'hi' },
+      { description: 'hi\n' },
+    ],
+    ['tags in another order and case', { tags: 'B;a' }, { tags: 'a;b' }],
+    ['a default PVE leaves out', { onboot: 0, cpulimit: 0, swap: 512 }, {}],
+    ['startup with its default key bare', { startup: '1,up=30' }, { startup: 'order=1,up=30' }],
+    ['a boolean as true', { protection: true }, { protection: 1 }],
+    [
+      'features with an off key spelled out',
+      { features: 'nesting=1,keyctl=0' },
+      { features: 'nesting=1' },
+    ],
+  ])('%s is no drift', (_, declared, config) => {
+    expect(judge(props(declared as Partial<LxcProps>), live(config)).drift).toEqual([]);
+  });
+
+  test('cores absent means every host core, which no number is', () => {
+    expect(judge(props({ cores: 4 }), live({})).put).toEqual({ cores: '4' });
+  });
+
+  test('nameserver order is meaningful', () => {
+    const change = judge(props({ nameserver: 'b a' }), live({ nameserver: 'a b' }));
+    expect(change.put).toEqual({ nameserver: 'b a' });
+  });
+
+  test("'' clears a clearable key and refuses one that cannot be removed", () => {
+    expect(judge(props({ description: '' }), live({ description: 'x\n' })).clear).toEqual([
+      'description',
+    ]);
+    expect(judge(props({ hostname: '' }), live({ hostname: 'x' })).refuse[0]).toMatch(
+      /cannot be removed/,
+    );
+  });
+
+  test('a key this resource does not manage is refused, not written', () => {
+    const odd = props({}) as unknown as Record<string, unknown>;
+    odd['hookscript'] = 'local:snippets/x.sh';
+    expect(judge(odd as unknown as LxcProps, live({})).refuse[0]).toMatch(/not a config key/);
+  });
+});
+
+describe('features follow check_ct_modify_config_perm', () => {
+  test('nesting alone on an unprivileged guest is an update', () => {
+    expect(judge(props({ features: 'nesting=1' }), live({})).put).toEqual({
+      features: 'nesting=1',
+    });
+  });
+
+  test('any features write on a privileged guest is root@pam only', () => {
+    const change = judge(props({ features: 'nesting=1' }), { unprivileged: 0 });
+    expect(change.refuse[0]).toMatch(/root@pam/);
+    expect(change.put).toEqual({});
+  });
+
+  test('clearing features that hold more than nesting is root@pam only, as PVE counts keys', () => {
+    const change = judge(props({ features: '' }), live({ features: 'nesting=1,keyctl=0' }));
+    expect(change.refuse[0]).toMatch(/pct set 100 --delete features/);
+  });
+});
+
+describe('NICs and devices', () => {
+  test("net '' removes a NIC; a new NIC is added as declared", () => {
+    const change = judge(props({ net1: '', net2: 'name=eth2,bridge=vmbr1' }), live({ net1: 'x' }));
+    expect(change.clear).toEqual(['net1']);
+    expect(change.put).toEqual({ net2: 'name=eth2,bridge=vmbr1' });
+  });
+
+  test('a declared MAC is compared, case-insensitively', () => {
+    const net = 'name=eth0,bridge=vmbr0,hwaddr=00:00:5E:00:53:01,type=veth';
+    expect(judge(props({ net0: net.toLowerCase() }), live({ net0: net })).drift).toEqual([]);
+    const other = judge(props({ net0: net.replace(':01', ':09') }), live({ net0: net }));
+    expect(other.drift).toEqual(['net0']);
+  });
+
+  test("a device with deny-write=0 is the same device; a new one is root@pam's", () => {
+    const dev = '/dev/net/tun,deny-write=0';
+    expect(judge(props({ dev0: dev }), live({ dev0: '/dev/net/tun' })).drift).toEqual([]);
+    expect(judge(props({ dev0: dev }), live({})).refuse[0]).toMatch(/Device passthrough/);
+  });
+});
+
+describe('create', () => {
+  test('the form carries declared keys, drops empties, and sends features without off keys', () => {
+    const form = createForm(
+      props({
+        description: '',
+        features: 'nesting=1,keyctl=0',
+        ostemplate: 'local:vztmpl/t.tar.zst',
+        start: true,
+        unprivileged: true,
+      }),
+    );
+    expect(form).toEqual({
+      features: 'nesting=1',
+      ostemplate: 'local:vztmpl/t.tar.zst',
+      start: '1',
+      unprivileged: '1',
+      vmid: '100',
+    });
+  });
+
+  test('a privileged create with any feature is refused', () => {
+    const refusals = createRefusals(
+      props({ features: 'nesting=1', ostemplate: 't', unprivileged: false }),
+    );
+    expect(refusals.join('\n')).toMatch(/Any feature on a privileged guest/);
+  });
+});
+
+describe('what state keeps', () => {
+  test('never the notes, digest, lock, env or raw lxc values; raw keys by name only', () => {
+    const read = {
+      description: 'notes a human wrote\n',
+      digest: 'd',
+      env: 'A=1',
+      hostname: 'x',
+      lock: 'backup',
+      lxc: [['lxc.a', 'v']],
+    };
+    expect(storedConfig(read)).toEqual({ hostname: 'x' });
+    expect(rawKeysOf(read)).toEqual(['lxc.a']);
+  });
+});

package/src/proxmox/lxc-judge.ts

@@ -0,0 +1,196 @@
+/**
+ * Declared against live: what a deploy would write to a container, and what it must refuse.
+ *
+ * ★ ONE PURE FUNCTION DECIDES FOR BOTH `diff` AND `reconcile`, so the plan and the write cannot
+ *   disagree about what is drift. This is resource.ts's `matches` guard grown up: an adopted guest
+ *   that already says what the declaration says produces an empty change, and an empty change is
+ *   not a write — adopting a running container must cost nothing.
+ *
+ * ⛔ SOME CHANGES NO API TOKEN CAN MAKE, AND THEY ARE REFUSED AT PLAN RATHER THAN 403'd MID-DEPLOY.
+ *   `PVE::LXC::check_ct_modify_config_perm` (pve-container 6.1.14) returns early only for
+ *   `$authuser eq 'root@pam'`, and a token's authuser is `root@pam!name` at best. So for a token:
+ *   - `devN` — "configuring device passthrough is only allowed for root@pam";
+ *   - a bind or device `mpN`/`rootfs` — "mount point type … is only allowed for root@pam";
+ *   - `features` on a privileged guest, or any feature but `nesting` — root@pam only.
+ *   Each refusal names the `pct set` to run on the node instead. After it, declare the value and
+ *   the next plan compares it like any other key.
+ */
+import {
+  type LxcProps,
+  declaredKeys,
+  declaredValue,
+  indexedKey,
+  isManagedKey,
+  wireValue,
+} from './lxc-props.ts';
+import { isHostPath, judgeVolume, parseVolume } from './lxc-volume.ts';
+import {
+  CLEARABLE,
+  SCALAR_DEFAULTS,
+  netMaps,
+  netWrite,
+  optionMap,
+  pairs,
+  sameMap,
+  scalarForm,
+  sortedForm,
+} from './lxc-wire.ts';
+import { bool, canonicalToken } from './values.ts';
+
+export type LxcChange = {
+  /** Keys to `PUT …/config`, as PVE's wire strings. */
+  readonly put: Record<string, string>;
+  /** Keys to remove with `delete=`. */
+  readonly clear: readonly string[];
+  /** Mount points to grow, one `PUT …/resize` each, after the config PUT. */
+  readonly resize: readonly { readonly disk: string; readonly size: string }[];
+  /** Why the change cannot be made as an update. Non-empty means nothing is written. */
+  readonly refuse: readonly string[];
+  /** Every declared key that differs from live, refused or not — what a plan should name. */
+  readonly drift: readonly string[];
+};
+
+const text = (value: unknown): string | undefined =>
+  value === undefined || value === null ? undefined : wireValue(value);
+
+/** A refusal naming the `pct set` to run instead. `''` is a removal, so it names `--delete`. */
+export const rootOnly = (vmid: number, key: string, value: string, why: string): string =>
+  `${key}: ${why} PVE lets only root@pam write it, and an API token is never root@pam. Run ` +
+  `\`pct set ${String(vmid)} ${value === '' ? `--delete ${key}` : `--${key} '${value}'`}\` ` +
+  'on the node, then plan again.';
+
+/** `features` parsed the way PVE's `parse_features` does: booleans as 1/0, nothing dropped. */
+const rawFeatures = (value: string) =>
+  new Map(
+    pairs(value).map(([key, entry]) => [key, key === 'mount' ? entry : canonicalToken(entry)]),
+  );
+
+/**
+ * PVE's own `features` rule, on the value actually SENT (`sent` undefined means `delete=features`):
+ * nesting alone needs `VM.Allocate`, anything else is root@pam's.
+ * ⚠️ MIRRORED KEY FOR KEY, DEFAULTS INCLUDED, because PVE does not drop them: a live `keyctl=0`
+ *   against a sent value without `keyctl` is a change to PVE (`'0' ne ''`) and makes the write
+ *   root-only. `scalarForm` drops off keys from what is sent for the same reason.
+ */
+export const featuresNeedRoot = (
+  live: string,
+  sent: string | undefined,
+  unprivileged: boolean,
+): boolean => {
+  if (!unprivileged) return true;
+  const have = rawFeatures(live);
+  if (sent === undefined) return !(have.size === 0 || (have.size === 1 && have.has('nesting')));
+  const want = rawFeatures(sent);
+  const keys = new Set([...have.keys(), ...want.keys()]);
+  return [...keys].some(
+    (key) => key !== 'nesting' && (have.get(key) ?? '') !== (want.get(key) ?? ''),
+  );
+};
+
+export const featureWhy = (unprivileged: boolean): string =>
+  unprivileged ? 'A feature other than nesting.' : 'Any feature on a privileged guest.';
+
+export const judge = (props: LxcProps, live: Record<string, unknown>): LxcChange => {
+  const put: Record<string, string> = {};
+  const clear: string[] = [];
+  const resize: { disk: string; size: string }[] = [];
+  const refuse: string[] = [];
+  const drift = new Set<string>();
+  const unprivileged = bool(live['unprivileged'], false);
+
+  for (const key of declaredKeys(props)) {
+    const want = wireValue(declaredValue(props, key));
+    const have = text(live[key]);
+    const indexed = indexedKey(key);
+
+    if (key === 'unprivileged') {
+      if (canonicalToken(want) !== canonicalToken(have ?? '0')) {
+        drift.add(key);
+        refuse.push(
+          `unprivileged: live ${have ?? '0'}, declared ${want}. PVE refuses to change it ("unable ` +
+            'to modify read-only option"); only a backup and restore can, and that is a new guest.',
+        );
+      }
+      continue;
+    }
+
+    if (key === 'rootfs' || indexed?.[0] === 'mp') {
+      if (want === '') {
+        if (have === undefined) continue;
+        drift.add(key);
+        refuse.push(
+          `${key}: detaching a mount point moves its volume to unusedN -- do it by hand.`,
+        );
+      } else if (have === undefined) {
+        drift.add(key);
+        if (isHostPath(parseVolume(want))) {
+          refuse.push(rootOnly(props.vmid, key, want, 'A bind or device mount point.'));
+        } else put[key] = want;
+      } else {
+        const verdict = judgeVolume(key, want, have);
+        if (verdict.refuse !== undefined) refuse.push(verdict.refuse);
+        if (verdict.rootOnly === true) {
+          refuse.push(rootOnly(props.vmid, key, want, 'A bind or device mount point.'));
+        }
+        if (verdict.put !== undefined) put[key] = verdict.put;
+        if (verdict.resize !== undefined) resize.push({ disk: key, size: verdict.resize });
+        if (Object.keys(verdict).length > 0) drift.add(key);
+      }
+      continue;
+    }
+
+    if (indexed?.[0] === 'dev') {
+      const same = want === '' ? have === undefined : have !== undefined && devSame(want, have);
+      if (!same) {
+        drift.add(key);
+        refuse.push(rootOnly(props.vmid, key, want, 'Device passthrough.'));
+      }
+      continue;
+    }
+
+    if (indexed?.[0] === 'net') {
+      if (want === '') {
+        if (have !== undefined) {
+          drift.add(key);
+          clear.push(key);
+        }
+      } else if (have === undefined) {
+        drift.add(key);
+        put[key] = want;
+      } else {
+        const maps = netMaps(want, have);
+        if (!sameMap(maps.want, maps.have)) {
+          drift.add(key);
+          put[key] = netWrite(want, have);
+        }
+      }
+      continue;
+    }
+
+    if (!isManagedKey(key)) {
+      drift.add(key);
+      refuse.push(`${key}: not a config key this resource manages.`);
+      continue;
+    }
+
+    const wanted = want === '' ? '' : scalarForm(key, want);
+    const current = have ?? SCALAR_DEFAULTS[key];
+    const had = current === undefined ? '' : scalarForm(key, current);
+    if (wanted === had) continue;
+    drift.add(key);
+    // ⚠️ `features` goes out with its off keys dropped — see `featuresNeedRoot`.
+    const next = key === 'features' ? wanted : want;
+    if (key === 'features' && featuresNeedRoot(have ?? '', next || undefined, unprivileged)) {
+      refuse.push(rootOnly(props.vmid, key, want, featureWhy(unprivileged)));
+    } else if (next === '' && CLEARABLE.has(key)) {
+      clear.push(key);
+    } else if (next === '') {
+      refuse.push(`${key}: cannot be removed; declare the value it should have.`);
+    } else put[key] = next;
+  }
+  return { clear, drift: [...drift].sort(), put, refuse, resize };
+};
+
+/** Two `devN` values as one device: same path, same options, `deny-write=0` meaning absent. */
+const devSame = (want: string, have: string) =>
+  sortedForm(optionMap(want, 'dev', 'path')) === sortedForm(optionMap(have, 'dev', 'path'));

package/src/proxmox/lxc-lifecycle.ts

@@ -0,0 +1,200 @@
+/**
+ * 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.
+ *
+ * ⚠️ 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
+ *   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 { type PveTarget, mint } from './credentials.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)}`;
+
+/** How long each task may run, in one-second polls. ⚠️ A cap, not an estimate. */
+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 `"100"` 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,
+  rawKeys: rawKeysOf(live),
+  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) =>
+  task(
+    props,
+    'POST',
+    `nodes/${props.node}/lxc`,
+    `create CT ${String(props.vmid)}`,
+    CREATE_POLLS,
+    createForm(props),
+  );
+
+/**
+ * Apply a judged change: the config PUT first, then each resize.
+ * ⚠️ IN THAT ORDER BECAUSE A MOUNT POINT'S PUT CARRIES ITS LIVE `size=`, and the resize rewrites it.
+ * ⛔ THE PUT CARRIES THE `digest` OF THE CONFIG IT WAS JUDGED AGAINST. PVE refuses the write if the
+ *   file changed since (`assert_if_modified`), so an edit landing between reconcile's own read and
+ *   its PUT fails the deploy instead of being overwritten by a change computed from the older file.
+ * ⚠️ THE DIGEST IS THE DEPLOY'S READ, NOT THE PLAN'S. A hand edit between `plan` and `deploy` is
+ *   seen by reconcile's fresh judge instead: a declared key edited meanwhile is written back to the
+ *   declaration (even after a plan that warned of nothing), an undeclared one is left alone.
+ */
+export const updateGuest = (props: LxcProps, change: LxcChange, digest: string) =>
+  Effect.gen(function* () {
+    if (Object.keys(change.put).length > 0 || change.clear.length > 0) {
+      const form = withClears(
+        { ...change.put, ...(digest === '' ? {} : { digest }) },
+        change.clear,
+      );
+      yield* pve(props.target, 'provision', 'PUT', `${guestPath(props)}/config`, form);
+    }
+    for (const grow of change.resize) {
+      yield* task(
+        props,
+        'PUT',
+        `${guestPath(props)}/resize`,
+        `grow ${grow.disk} of CT ${String(props.vmid)} to ${grow.size}`,
+        TASK_POLLS,
+        { disk: grow.disk, size: grow.size },
+      );
+    }
+  });
+
+/**
+ * ⛔ NO `force`, NO `purge`, NO STOP FIRST. PVE refuses to destroy a running or protected guest,
+ *   and that refusal is kept: stopping a guest so a delete can proceed is an operator's decision.
+ *   Reached only under `RemovalPolicy.destroy()` — this resource retains by default.
+ * ⛔ AND ONLY THE GUEST THIS STACK DECLARED. State holds a vmid, and a vmid is reusable: after a
+ *   hand `pct destroy` and a new `pct create` at the same id, "delete CT 150" is somebody else's
+ *   container and all its volumes. So the live guest is judged against the last declaration
+ *   first; one that no longer matches is refused with the keys that differ, and deleting it (or
+ *   declaring it again) is the operator's call.
+ */
+export const destroyGuest = (where: LxcWhere, declared: LxcProps) =>
+  Effect.gen(function* () {
+    const live = yield* readLive(where);
+    if (live === undefined) return;
+    const drift = judge(declared, live).drift;
+    if (drift.length > 0) {
+      return yield* Effect.fail(
+        new LxcRefusedError(
+          `destroy CT ${String(where.vmid)}: the guest on ${where.node} no longer matches its last ` +
+            `declaration (${drift.join(', ')}), so it may not be the guest this stack made. ` +
+            'Nothing was deleted. Delete it by hand if it should go, or declare it again.',
+        ),
+      );
+    }
+    yield* task(where, 'DELETE', guestPath(where), `destroy CT ${String(where.vmid)}`, TASK_POLLS);
+  });