@homeflare/alchemy 0.37.6 → 0.37.8

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

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