@homeflare/alchemy 0.37.5 → 0.37.7

package/src/openbao/policy.ts

@@ -10,9 +10,9 @@ import { ownedRead } from '../ownership/probe.ts';
 import { provingResumes } from '../ownership/resume.ts';
 import { sha256 } from './digest.ts';
 import { isEmptyAssembly } from './policy-assembly.ts';
-import { deletePolicy, policyPath, readPolicy, writePolicy } from './policy-wire.ts';
-import { policyKey } from './rename.ts';
-import { guardRename, judgeRename, nameIdentity } from './rename-identity.ts';
+import { judgePolicyRename, policyIdentity } from './policy-identity.ts';
+import { deletePolicy, readPolicy, writePolicy } from './policy-wire.ts';
+import { guardRename } from './rename-identity.ts';
 
 /**
  * An OpenBao ACL policy, assembled from the HCL fragments that declare it.
@@ -103,9 +103,6 @@ export const BaoPolicy = Resource<BaoPolicy>('Bao.Policy', {
   defaultRemovalPolicy: 'retain',
 });
 
-/** A policy is its name, keyed as OpenBao keys it (`policyKey`). */
-const IDENTITY = nameIdentity<BaoPolicyAttributes>('Bao.Policy', policyPath, policyKey);
-
 /** `path "..."` grant count — the same number the apply script prints. */
 const grantsOf = (hcl: string) => (hcl.match(/^path /gm) ?? []).length;
 
@@ -140,12 +137,12 @@ export const BaoPolicyProvider = () =>
          */
         list: () => Effect.succeed([]),
 
-        // ★ '' means genuinely absent (a 404); a refusal fails. policy-wire.ts has the history.
+        // ★ Only undefined means absent (a typed 404); even a live empty policy occupies its name.
         // ⛔ With no attributes in state, a live policy is `Unowned` unless it is the one our own
         //   interrupted create wrote: these fragments, byte for byte (ownership/probe.ts).
         read: Effect.fn(function* ({ fqn, instanceId, olds, output }) {
           const live = yield* readPolicy(olds.name);
-          const found = live.length === 0 ? undefined : attributesOf(olds.name, live, 0);
+          const found = live === undefined ? undefined : attributesOf(olds.name, live, 0);
           const ours = Effect.map(
             assemble(olds.fragments),
             (a) => sha256(a.joined) === found?.digest,
@@ -170,7 +167,7 @@ export const BaoPolicyProvider = () =>
            *   delete, so a role outside this graph that names the old policy must move in the same
            *   PR (REPLACE.md).
            */
-          const move = yield* judgeRename(IDENTITY, olds, news, output);
+          const move = yield* judgePolicyRename(olds, news, output);
           // ★ No attributes: an unfinished generation, proven ours or not by provingResumes.
           if (output === undefined) return undefined;
           if (move !== undefined) return { action: 'replace' } as const;
@@ -180,7 +177,7 @@ export const BaoPolicyProvider = () =>
           if (!isResolved(news)) return undefined;
           const { joined } = yield* assemble(news.fragments);
           const live = yield* readPolicy(news.name);
-          return live.length > 0 && sha256(live) === sha256(joined)
+          return live !== undefined && sha256(live) === sha256(joined)
             ? ({ action: 'noop' } as const)
             : ({ action: 'update' } as const);
         }),
@@ -188,7 +185,7 @@ export const BaoPolicyProvider = () =>
         reconcile: Effect.fn(function* ({ fqn, instanceId, news, output }) {
           const name = news.name;
           // ⛔ An `update` across a rename the diff could not see — refused before any write.
-          yield* guardRename(IDENTITY, news, output);
+          yield* guardRename(policyIdentity, news, output);
           const { joined, parts } = yield* assemble(news.fragments);
           /**
            * ⛔ AN EMPTY ASSEMBLY IS A REFUSAL, NOT AN EMPTY POLICY. `bao policy write` with
@@ -218,9 +215,9 @@ export const BaoPolicyProvider = () =>
            *   sibling PVE provider does exactly this in pveOperations.reconcile.
            */
           const current = yield* readPolicy(name);
-          if (current.length > 0)
+          if (current !== undefined)
             yield* refuseTakeover({ fqn, instanceId, output }, `Bao.Policy ${name}`);
-          if (current.length > 0 && sha256(current) === sha256(joined)) {
+          if (current !== undefined && sha256(current) === sha256(joined)) {
             return attributesOf(name, joined, parts);
           }
           // ⚠️ In the request body, never on argv — see `writePolicy` for why the temp file went.

package/src/openbao/rename.ts

@@ -127,12 +127,28 @@ export const judgeMove = (
   declared: string | undefined,
   pathOf: (identity: string) => string,
   key: (identity: string) => string = exact,
+) =>
+  judgeMoveWith(
+    family,
+    tried,
+    declared,
+    (identity) => Effect.map(baoRead(pathOf(identity)), (value) => value !== undefined),
+    key,
+  );
+
+/** SDK families supply their own typed read so a rename cannot fall back to raw HTTP. */
+export const judgeMoveWith = <E, R>(
+  family: string,
+  tried: string | undefined,
+  declared: string | undefined,
+  occupied: (identity: string) => Effect.Effect<boolean, E, R>,
+  key: (identity: string) => string = exact,
 ) =>
   Effect.gen(function* () {
     if (tried === undefined || declared === undefined || key(tried) === key(declared)) {
       return undefined;
     }
-    if ((yield* baoRead(pathOf(declared))) === undefined) return { from: tried, to: declared };
+    if (!(yield* occupied(declared))) return { from: tried, to: declared };
     return yield* Effect.die(
       new Error(
         `${family}: ${tried} → ${declared} would land on an object that already exists at ` +

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

@@ -0,0 +1,39 @@
+/** Existing alias normalization and forms, independent of the named SDK transport. */
+import type { FirewallAliasAttributes, FirewallAliasProps } from './firewall-alias.ts';
+import type { PveSpec } from './resource-spec.ts';
+import { body, cidr, comment } from './firewall-alias-form.ts';
+import { int, text } from './values.ts';
+
+export const firewallAliasSpec = {
+  /** The SDK read refuses malformed successful payloads before applying these normalizers. */
+  attributes: (live, props) => {
+    const address = cidr(live['cidr']);
+    return {
+      cidr: address,
+      comment: comment(live['comment']),
+      ipversion: int(live['ipversion'], 0),
+      /** The read checks identity; the stored spelling is preserved for display. */
+      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,
+} satisfies PveSpec<FirewallAliasProps, FirewallAliasAttributes>;

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

@@ -106,7 +106,7 @@ export const comment = (value: unknown) => {
  *   this form would be a second, invisible identity for the object, set from a field the resource
  *   does not have.
  */
-export const body = (props: FirewallAliasProps): Record<string, string> => {
+export const body = (props: FirewallAliasProps): Record<string, string> & { cidr: string } => {
   const note = comment(props.comment);
   return { cidr: cidr(props.cidr), ...(note === '' ? {} : { comment: note }) };
 };

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