@homeflare/alchemy 0.8.0 → 0.10.1

package/src/proxmox/adopt-noop.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Adopting an object that already matches must be read-only — measured per reconcile SHAPE, through
+ * Alchemy's own Plan and Apply over a fake cluster (fake-pve.ts, ../verify/fake-engine.ts).
+ *
+ * ★ ONE ROW PER WAY A FAMILY REACHES ITS WRITE, not one per family. Every family built on
+ *   `pveHandlers` shares resource.ts's reconcile, so `Proxmox.Pool` stands for all of them; `Acl`
+ *   wraps that reconcile; `PbsDatastore` and `SdnApply` write their own. CephPool, the one that got
+ *   it wrong, has its own file. docs/adopt-verify.md carries the full per-family table.
+ * ⚠️ A FIXTURE THAT DOES NOT MATCH TURNS A ROW INTO A DRIFT TEST, and the assertion on the
+ *   verifier's `noop` is what catches that: a wrong fixture fails loudly instead of passing for
+ *   the wrong reason. The Pool drift row proves the harness can see a write at all.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { ProxmoxAcl, ProxmoxAclProvider } from './acl.ts';
+import type { PbsTarget } from './credentials.ts';
+import { FAKE_TARGET, fakePve, withoutBao } from './fake-pve.ts';
+import { PbsDatastore, PbsDatastoreProvider } from './pbs-datastore.ts';
+import { ProxmoxPool, ProxmoxPoolProvider } from './pool.ts';
+import { ProxmoxSdnApply, ProxmoxSdnApplyProvider } from './sdn-apply.ts';
+
+const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };
+
+type Case = {
+  readonly name: string;
+  readonly provider: () => Layer.Layer<never, never, never>;
+  readonly declare: () => ReturnType<typeof ProxmoxPool>;
+  /** GET path → the `data` PVE/PBS answers; anything unlisted answers `null`. */
+  readonly live: Readonly<Record<string, unknown>>;
+};
+
+const cases: readonly Case[] = [
+  {
+    declare: () => ProxmoxPool('house', { comment: 'x', poolid: 'house', target: FAKE_TARGET }),
+    live: { 'pools/house': { comment: 'x', members: [] } },
+    name: 'Proxmox.Pool (pveHandlers: every factory family)',
+    provider: ProxmoxPoolProvider as never,
+  },
+  {
+    declare: () =>
+      ProxmoxAcl('auditor', {
+        path: '/',
+        roleid: 'PVEAuditor',
+        target: FAKE_TARGET,
+        type: 'user',
+        ugid: 'u@pve',
+      }) as never,
+    live: {
+      'access/acl': [
+        { path: '/', propagate: 1, roleid: 'PVEAuditor', type: 'user', ugid: 'u@pve' },
+      ],
+    },
+    name: 'Proxmox.Acl (wraps the factory reconcile)',
+    provider: ProxmoxAclProvider as never,
+  },
+  {
+    declare: () =>
+      PbsDatastore('store1', {
+        comment: 'c',
+        'gc-schedule': 'daily',
+        name: 'store1',
+        path: '/mnt/store1',
+        target: PBS,
+      }) as never,
+    live: {
+      'config/datastore/store1': {
+        comment: 'c',
+        'gc-schedule': 'daily',
+        name: 'store1',
+        path: '/mnt/store1',
+      },
+    },
+    name: 'Pbs.Datastore (its own reconcile)',
+    provider: PbsDatastoreProvider as never,
+  },
+  {
+    declare: () => ProxmoxSdnApply('sdn', { target: FAKE_TARGET }) as never,
+    live: {},
+    name: 'Proxmox.SdnApply (its own reconcile; nothing staged)',
+    provider: ProxmoxSdnApplyProvider as never,
+  },
+];
+
+const clusterWith = (live: Readonly<Record<string, unknown>>) =>
+  fakePve((call) => (call.method === 'GET' ? live[call.path] : 'UPID:fake'));
+
+describe('adopting a matching object only reads', () => {
+  test.each(cases.map((c) => [c.name, c] as const))('%s', async (_, c) => {
+    const fake = clusterWith(c.live);
+    await withoutBao(async () => {
+      const engine = engineOver(c.provider().pipe(Layer.provideMerge(fake.layer)));
+      const report = await engine.verify(c.declare());
+      expect(report.rows).toEqual([expect.objectContaining({ diff: 'noop', ok: true })]);
+      expect(Object.values(await engine.deploy(c.declare()))).toEqual(['adopted']);
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('and the harness does see a write: a drifted Pool is PUT once', async () => {
+    const fake = clusterWith({ 'pools/house': { comment: 'old', members: [] } });
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxPoolProvider().pipe(Layer.provideMerge(fake.layer)));
+      const declared = () =>
+        ProxmoxPool('house', { comment: 'x', poolid: 'house', target: FAKE_TARGET });
+      const report = await engine.verify(declared());
+      expect(report.rows[0]).toMatchObject({ changed: ['comment'], diff: 'update', ok: false });
+      expect(await engine.deploy(declared())).toEqual({ house: 'adopted' });
+    });
+    expect(fake.writes()).toEqual(['PUT pools/house']);
+  });
+});

package/src/proxmox/ceph-pool-adopt.test.ts

@@ -0,0 +1,120 @@
+/**
+ * `Proxmox.CephPool` adopted through Alchemy's own Plan and Apply, over a fake cluster.
+ *
+ * 🔴 THE BUG THIS PINS (found 2026-09-21, update-guard.ts). The family's hand-written reconcile
+ *   PUT the declared set whenever the pool existed. Plan.ts forces reconcile after the adoption
+ *   probe even when the diff says `noop`, so adopting a pool that already matched sent `setpool`
+ *   and forked a worker on the live cluster. The first test fails with that PUT on the old code.
+ * ★ THE VERIFIER RUNS OVER THE SAME ENGINE, so the same test also shows what it reports before
+ *   the deploy: `adopted` from the engine, `noop` from the provider.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { ProxmoxCephPool, ProxmoxCephPoolProvider } from './ceph-pool.ts';
+import { FAKE_TARGET, type PveCall, fakePve, withoutBao } from './fake-pve.ts';
+
+const STATUS = 'nodes/n2/ceph/pool/cephtb4/status?verbose=1';
+const OBJECT = 'nodes/n2/ceph/pool/cephtb4';
+
+/** TB4's rbd pool as `getpool` answers it — the fields ceph-pool.ts reads. */
+const livePool = (size: number): Record<string, unknown> => ({
+  application_list: ['rbd'],
+  crush_rule: 'replicated_rule',
+  id: 2,
+  min_size: 2,
+  name: 'cephtb4',
+  pg_autoscale_mode: 'on',
+  pg_num: 128,
+  size,
+});
+
+/** A cluster holding one pool; a PUT to it lands, as `setpool` would. */
+const cluster = (size: number) => {
+  const pool = livePool(size);
+  return fakePve((call: PveCall) => {
+    if (call.method === 'GET' && call.path === STATUS) return pool;
+    if (call.method === 'PUT' && call.path === OBJECT) {
+      for (const [key, value] of Object.entries(call.form)) {
+        pool[key] = /^\d+$/.test(value) ? Number(value) : value;
+      }
+      return 'UPID:n2:fake:setpool';
+    }
+    return undefined;
+  });
+};
+
+const declared = () =>
+  ProxmoxCephPool('cephtb4', {
+    crush_rule: 'replicated_rule',
+    min_size: 2,
+    name: 'cephtb4',
+    node: 'n2',
+    pg_autoscale_mode: 'on',
+    size: 3,
+    target: FAKE_TARGET,
+  });
+
+const engineFor = (fake: ReturnType<typeof cluster>) =>
+  engineOver(ProxmoxCephPoolProvider().pipe(Layer.provideMerge(fake.layer)));
+
+describe('adopting a Ceph pool', () => {
+  test('that already matches: the verifier says noop, and the deploy only reads', async () => {
+    const fake = cluster(3);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const report = await engine.verify(declared());
+      expect(report.rows).toEqual([
+        expect.objectContaining({ diff: 'noop', ok: true, planned: 'adopted', read: 'found' }),
+      ]);
+      expect(await engine.deploy(declared())).toEqual({ cephtb4: 'adopted' });
+    });
+    expect(fake.writes()).toEqual([]);
+    expect(fake.calls.every((call) => call.path === STATUS)).toBe(true);
+  });
+
+  /**
+   * ★ THE RECHECK MUST NOT FAIL A FIELD THE FAMILY DOES NOT MANAGE. `pg_num` is create-time only and
+   *   the autoscaler owns it, so a declared birth size differs from the live count and shows under
+   *   `changed`. recheck.ts asks the diff again with the live value as recorded props; this diff
+   *   re-reads the cluster and ignores `olds`, so it says `noop` again, and the deploy only reads.
+   */
+  test('declaring a field it does not manage: rechecked, still noop, and the deploy only reads', async () => {
+    const fake = cluster(3);
+    const birth = () =>
+      ProxmoxCephPool('cephtb4', {
+        min_size: 2,
+        name: 'cephtb4',
+        node: 'n2',
+        pg_num: 32,
+        size: 3,
+        target: FAKE_TARGET,
+      });
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const report = await engine.verify(birth());
+      expect(report.rows[0]).toMatchObject({
+        changed: ['pg_num'],
+        diff: 'noop',
+        ok: true,
+        recheck: 'noop',
+      });
+      expect(report.rows[0]?.why).toContain('does not manage');
+      expect(await engine.deploy(birth())).toEqual({ cephtb4: 'adopted' });
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('that drifted: the verifier names the field, and the deploy PUTs once', async () => {
+    const fake = cluster(2);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const report = await engine.verify(declared());
+      expect(report.rows[0]).toMatchObject({ changed: ['size'], diff: 'update', ok: false });
+      expect(fake.writes()).toEqual([]);
+      expect(await engine.deploy(declared())).toEqual({ cephtb4: 'adopted' });
+    });
+    expect(fake.writes()).toEqual([`PUT ${OBJECT}`]);
+    expect(fake.calls.find((call) => call.method === 'PUT')?.form['size']).toBe('3');
+  });
+});

package/src/proxmox/ceph-pool-form.ts

@@ -192,9 +192,9 @@ const numeric = (value: number | undefined) => (value === undefined ? undefined
  * the way storage.ts's `mutable` serves both of its forms. `name` is the path's last segment on an
  * update and is not repeated here.
  *
- * ⚠️ SAFE TO RE-APPLY TO A POOL THAT ALREADY MATCHES, which reconcile relies on. MEASURED in
- *   PVE::Ceph::Tools::set_pool (Tools.pm:293-300): it reads `osd pool get all` first and SKIPS
- *   every setting whose value did not change, so re-sending the declared set costs one mon read.
+ * ⚠️ SAFE TO RE-APPLY TO A POOL THAT ALREADY MATCHES (reconcile leaned on it until update-guard.ts).
+ *   MEASURED in PVE::Ceph::Tools::set_pool (Tools.pm:293-300): it reads `osd pool get all` first
+ *   and SKIPS every unchanged setting, so the undrifted fields that ride along cost one mon read.
  * ⛔ BUT A SETTING THAT DID CHANGE AND CANNOT BE APPLIED KILLS THE WHOLE PUT. Tools.pm:310 dies
  *   with "Could not set: <fields>" if any parameter is left unapplied, so a pool carrying Ceph's
  *   `nosizechange` fails an entire update over one field. That is why the `no*` flags are reported

package/src/proxmox/ceph-pool.ts

@@ -53,6 +53,7 @@ import {
 import { confirmAbsent, settle } from './ceph-pool-settle.ts';
 import { pve } from './client.ts';
 import { type PveRequirements, type PveSpec, pveOperations } from './resource.ts';
+import { formToSend } from './update-guard.ts';
 import { bool, int, num, text } from './values.ts';
 
 export type { CephPoolAttributes, CephPoolProps };
@@ -160,9 +161,15 @@ export const ProxmoxCephPoolProvider = () =>
               createBody(news),
             );
           } else {
-            // ⚠️ An empty form is not a write — resource.ts skips one for the same reason.
-            const form = updateBody(news);
-            if (Object.keys(form).length > 0) {
+            /**
+             * ⛔ ONLY WHEN `matches` IS FALSE. This PUT used to fire whenever the pool existed, so
+             *   adopting a pool that already matched — Plan.ts forces reconcile after the probe —
+             *   sent `setpool` and forked a worker on the live cluster. PVE skipping the unchanged
+             *   settings (ceph-pool-form.ts) made it harmless to Ceph, not free: it is still a
+             *   provision-lease write and a task in the cluster's list. update-guard.ts has the rest.
+             */
+            const form = formToSend(spec.matches, live, news, updateBody(news));
+            if (form !== undefined) {
               upid = yield* pve<string>(news.target, 'provision', 'PUT', object(news), form);
             }
           }

package/src/proxmox/fake-bao-env.ts

@@ -0,0 +1,28 @@
+/**
+ * The shell's OpenBao variables, replaced for the life of one test run and put back afterwards.
+ *
+ * ⛔ WHY A TEST CANNOT LEAVE THEM ALONE. `leased` mints through credentials.ts `mint`, which reads
+ *   `BAO_AGENT_ADDR` before `BAO_ADDR` (and the `VAULT_*` spellings), and sends `BAO_TOKEN` as a
+ *   header. A developer shell with any of them set would send its real token to a fake, or a mint
+ *   to a real agent. credentials.test.ts avoids it by passing an explicit environment; a test that
+ *   drives a provider cannot, because the lease cache reads `process.env`.
+ * ★ ONE HELPER FOR EVERY FAKE. lxc-harness.ts and fake-pve.ts each carried their own copy; the
+ *   first covered three names and the second every `BAO_*` / `VAULT_*`, so they now share the
+ *   wider one. ⛔ TEST-ONLY. No provider imports this file.
+ */
+const BAO_VARIABLES = /^(BAO|VAULT)_/;
+
+/** Run `body` with every BAO_* / VAULT_* unset except `BAO_ADDR=address`, then restore them. */
+export const withFakeBao = async <A>(address: string, body: () => Promise<A>): Promise<A> => {
+  const saved = Object.entries(process.env).filter(([name]) => BAO_VARIABLES.test(name));
+  for (const [name] of saved) delete process.env[name];
+  process.env['BAO_ADDR'] = address;
+  try {
+    return await body();
+  } finally {
+    for (const name of Object.keys(process.env)) {
+      if (BAO_VARIABLES.test(name)) delete process.env[name];
+    }
+    for (const [name, value] of saved) process.env[name] = value;
+  }
+};

package/src/proxmox/fake-pve-lxc.ts

@@ -0,0 +1,210 @@
+/**
+ * A fake PVE cluster for `Proxmox.Lxc`: containers in memory, tasks that finish at once, and the
+ * OpenBao creds endpoint the mint reads — one Bun server, reached through `FetchHttpClient.Fetch`.
+ *
+ * ⛔ TEST-ONLY, AND NEVER A REAL HOST. No provider imports this file and it is not on the barrel.
+ *   Hostnames are `.test` (RFC 2606) and are remapped to the loopback server; any other host is
+ *   refused with ENOTFOUND rather than resolved (client.test.ts has the incident behind that).
+ * ★ IT ANSWERS THE WAY PVE 9 DOES WHERE THE PROVIDER DEPENDS ON IT, and each shape is a measured
+ *   one: a missing config is HTTP 500 with `message` in the JSON body (pve-http-server
+ *   `Formatter/Standard.pm`); a PUT with a stale `digest` is refused; a create allocates
+ *   `<storage>:subvol-<vmid>-disk-<n>,size=<n>G` and generates `hwaddr` and `type=veth`, as a live
+ *   guest's own config shows; tags come back sorted and lower-cased (`get_unique_tags`).
+ * ⚠️ EVERY MAC HERE IS FROM THE RFC 7042 DOCUMENTATION BLOCK (`00:00:5E:00:53:xx`), as every
+ *   address is TEST-NET: PVE's own prefix is `BC:24:11`, but no value in this package may be one a
+ *   real NIC could carry.
+ */
+import { pairs } from './lxc-wire.ts';
+
+export type Seen = {
+  readonly method: string;
+  readonly path: string;
+  readonly form: URLSearchParams;
+};
+
+export type FakePve = {
+  /** Live configs, keyed `node/vmid`. Mutate freely between deploys to simulate hand edits. */
+  readonly guests: Map<string, Record<string, unknown>>;
+  /** Extra `GET /cluster/resources` rows — a QEMU VM, or a guest on another node. */
+  readonly others: { vmid: number | string; node: string; type: string }[];
+  /** Forced answers for `GET …/config`, keyed `node/vmid`: an HTTP status and a JSON body. */
+  readonly configErrors: Map<string, { status: number; body: unknown }>;
+  /**
+   * Guests that read as ABSENT for the next N cluster listings (their config GET 500s meanwhile),
+   * keyed `node/vmid` — a guest that appears between a plan and its deploy.
+   */
+  readonly vanish: Map<string, number>;
+  /** Config keys a `PUT …/config` accepts with 200 and then does not store. */
+  readonly ignore: Set<string>;
+  /** How every task ends, and whether a task-starting call answers with no UPID at all. */
+  readonly task: { exit: string; noUpid: boolean };
+  readonly seen: Seen[];
+  readonly fetch: typeof fetch;
+  readonly stop: () => void;
+};
+
+/** The member hostname a test target names, and the OpenBao address the mint is pointed at. */
+export const FAKE_MEMBER = 'pve-a.test';
+export const FAKE_BAO = 'http://bao.test:8200';
+
+const json = (body: unknown, status = 200) => Response.json(body, { status });
+
+let digestCounter = 0;
+const nextDigest = () => {
+  digestCounter += 1;
+  return `digest-${String(digestCounter)}`;
+};
+
+/** What PVE's create does to the declared form: allocate volumes, fill NIC defaults, sort tags. */
+const created = (vmid: string, form: URLSearchParams): Record<string, unknown> => {
+  const config: Record<string, unknown> = { arch: 'amd64', ostype: 'debian', unprivileged: 1 };
+  let disk = 0;
+  for (const [key, value] of form) {
+    if (['ostemplate', 'start', 'vmid'].includes(key)) continue;
+    if (key === 'rootfs' || /^mp\d+$/.test(key)) {
+      const [first, ...rest] = value.split(',');
+      const fresh = /^([^:]+):(\d+)$/.exec(first ?? '');
+      config[key] =
+        fresh === null
+          ? value
+          : [
+              `${fresh[1] ?? ''}:subvol-${vmid}-disk-${String(disk++)}`,
+              ...rest,
+              `size=${fresh[2] ?? '0'}G`,
+            ].join(',');
+    } else if (/^net\d+$/.test(key)) {
+      const map = new Map(pairs(value));
+      if (!map.has('hwaddr'))
+        map.set('hwaddr', `00:00:5E:00:53:${vmid.slice(-2).padStart(2, '0')}`);
+      if (!map.has('type')) map.set('type', 'veth');
+      config[key] = [...map].map(([k, v]) => `${k}=${v}`).join(',');
+    } else if (key === 'tags') {
+      config[key] = [...new Set(value.toLowerCase().split(/[;,\s]+/))].sort().join(';');
+    } else config[key] = /^\d+$/.test(value) ? Number(value) : value;
+  }
+  return config;
+};
+
+export const fakePve = (): FakePve => {
+  const guests = new Map<string, Record<string, unknown>>();
+  const others: { vmid: number | string; node: string; type: string }[] = [];
+  const configErrors = new Map<string, { status: number; body: unknown }>();
+  const vanish = new Map<string, number>();
+  const ignore = new Set<string>();
+  const task = { exit: 'OK', noUpid: false };
+  const seen: Seen[] = [];
+  let upids = 0;
+  const upid = (node: string, kind: string, vmid: string) => {
+    upids += 1;
+    if (task.noUpid) return null;
+    return `UPID:${node}:${String(upids).padStart(8, '0')}:0:0:${kind}:${vmid}:hf-test@pve!fake:`;
+  };
+
+  const handle = async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    // ⚠️ QUERY AND BODY BOTH: a DELETE carries its parameters in the query, and a `force=1` there
+    //   must be visible to the test that says there is none.
+    const form = new URLSearchParams(url.search);
+    if (request.method !== 'GET')
+      for (const pair of new URLSearchParams(await request.text())) form.append(...pair);
+    seen.push({ form, method: request.method, path: url.pathname });
+    if (url.pathname.startsWith('/v1/') && url.pathname.includes('/creds/')) {
+      return json({
+        data: { secret: 'not-a-secret', token_id: 'hf-test@pve!fake' },
+        lease_duration: 300,
+      });
+    }
+    const path = url.pathname.replace(/^\/api2\/json\//, '');
+    if (path === 'cluster/resources') {
+      const rows = [...guests.keys()]
+        .filter((key) => (vanish.get(key) ?? 0) <= 0)
+        .map((key) => {
+          const [node, vmid] = key.split('/');
+          return { node, type: 'lxc', vmid: Number(vmid) };
+        });
+      for (const [key, left] of vanish) vanish.set(key, left - 1);
+      return json({ data: [...rows, ...others] });
+    }
+    if (/^nodes\/[^/]+\/tasks\/.+\/status$/.test(path)) {
+      return json({ data: { exitstatus: task.exit, status: 'stopped' } });
+    }
+    const create = /^nodes\/([^/]+)\/lxc$/.exec(path);
+    if (create !== null && request.method === 'POST') {
+      const node = create[1] ?? '';
+      const vmid = form.get('vmid') ?? '';
+      guests.set(`${node}/${vmid}`, { ...created(vmid, form), digest: nextDigest() });
+      return json({ data: upid(node, 'vzcreate', vmid) });
+    }
+    const guest = /^nodes\/([^/]+)\/lxc\/(\d+)(\/config|\/resize)?$/.exec(path);
+    if (guest === null) return json({ data: null, message: `no such path ${path}\n` }, 501);
+    const [, node = '', vmid = '', tail] = guest;
+    const forced = configErrors.get(`${node}/${vmid}`);
+    if (forced !== undefined && tail === '/config' && request.method === 'GET') {
+      return json(forced.body, forced.status);
+    }
+    const config =
+      (vanish.get(`${node}/${vmid}`) ?? 0) > 0 ? undefined : guests.get(`${node}/${vmid}`);
+    if (config === undefined) {
+      const message = `Configuration file 'nodes/${node}/lxc/${vmid}.conf' does not exist\n`;
+      return json({ data: null, message }, 500);
+    }
+    if (tail === '/config' && request.method === 'GET') return json({ data: config });
+    if (tail === '/config' && request.method === 'PUT') {
+      const digest = form.get('digest');
+      if (digest !== null && digest !== config['digest']) {
+        return json({ data: null, message: 'detected modified configuration\n' }, 500);
+      }
+      for (const [key, value] of form)
+        if (key !== 'digest' && key !== 'delete' && !ignore.has(key)) config[key] = value;
+      for (const key of (form.get('delete') ?? '').split(',')) if (key !== '') delete config[key];
+      config['digest'] = nextDigest();
+      return json({ data: null });
+    }
+    if (tail === '/resize' && request.method === 'PUT') {
+      const disk = form.get('disk') ?? '';
+      const current = String(config[disk] ?? '');
+      config[disk] = current.replace(/size=[^,]+/, `size=${form.get('size') ?? ''}`);
+      config['digest'] = nextDigest();
+      return json({ data: upid(node, 'resize', vmid) });
+    }
+    if (tail === undefined && request.method === 'DELETE') {
+      guests.delete(`${node}/${vmid}`);
+      return json({ data: upid(node, 'vzdestroy', vmid) });
+    }
+    return json({ data: null, message: 'unhandled\n' }, 501);
+  };
+
+  const server = Bun.serve({ fetch: handle, port: 0 });
+  const port = String(server.port);
+  const remapped = (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    const url = new URL(input instanceof Request ? input.url : String(input));
+    if (url.hostname !== FAKE_MEMBER && url.hostname !== new URL(FAKE_BAO).hostname) {
+      return Promise.reject(
+        Object.assign(new Error(`getaddrinfo ENOTFOUND ${url.hostname}`), {
+          code: 'ENOTFOUND',
+        }),
+      );
+    }
+    url.protocol = 'http:';
+    url.hostname = '127.0.0.1';
+    url.port = port;
+    return globalThis.fetch(url, init);
+  };
+  return {
+    configErrors,
+    fetch: Object.assign(remapped, { preconnect: globalThis.fetch.preconnect }),
+    guests,
+    ignore,
+    others,
+    seen,
+    stop: () => server.stop(true),
+    task,
+    vanish,
+  };
+};
+
+/** Every call that changed something, as `METHOD path`, in order — OpenBao mints excluded. */
+export const writesOf = (fake: FakePve) =>
+  fake.seen
+    .filter((call) => call.method !== 'GET')
+    .map((call) => `${call.method} ${call.path.replace(/^\/api2\/json\//, '')}`);

package/src/proxmox/fake-pve.ts

@@ -0,0 +1,75 @@
+/**
+ * A PVE cluster and the OpenBao that mints for it, both answered in-process by one stub `fetch` —
+ * so a family's REAL provider can run through Alchemy's engine with every call recorded.
+ *
+ * ★ A STUB `fetch`, NOT A SERVER. client.test.ts remaps hosts onto Bun.serve to test failover;
+ *   here the question is only which calls a lifecycle makes, and a stub answers every URL without
+ *   a socket, so nothing can reach a real host whatever the environment says.
+ * ⛔ AND THE ENVIRONMENT IS EMPTIED ANYWAY (`withoutBao`, fake-bao-env.ts), so a token in the
+ *   shell running the tests is never read.
+ * ⚠️ `lease_duration: 0` KEEPS THE LEASE CACHE COLD (lease-cache.ts `timeToLive`), so no fake
+ *   credential outlives the test that minted it.
+ * ⛔ TEST-ONLY. No provider imports this file.
+ */
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import type { PveTarget } from './credentials.ts';
+import { withFakeBao } from './fake-bao-env.ts';
+import { resetLastGoodForTest } from './members.ts';
+
+export const FAKE_TARGET: PveTarget = {
+  members: ['pve.test'],
+  mount: 'proxmox-test',
+  scheme: 'pve',
+};
+
+export interface PveCall {
+  readonly method: string;
+  /** Relative to `/api2/json/`, query included — the string a family passes to `pve()`. */
+  readonly path: string;
+  readonly form: Readonly<Record<string, string>>;
+}
+
+/** Answers one call with its `data`; `undefined` is PVE's `{"data": null}`. */
+export type PveAnswer = (call: PveCall) => unknown;
+
+export interface FakePve {
+  readonly calls: PveCall[];
+  /** Every call that is not a GET, as `METHOD path`. */
+  readonly writes: () => string[];
+  /** Provide over a provider layer: `Provider().pipe(Layer.provideMerge(fake.layer))`. */
+  readonly layer: ReturnType<typeof transport>;
+}
+
+/** Effect's own fetch client over a stub — client.test.ts wires failover the same way. */
+const transport = (stub: typeof fetch) =>
+  FetchHttpClient.layer.pipe(Layer.provideMerge(Layer.succeed(FetchHttpClient.Fetch, stub)));
+
+export const fakePve = (answer: PveAnswer): FakePve => {
+  const calls: PveCall[] = [];
+  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/')) {
+      const data = { secret: 'fake-secret-not-real', token_id: 'hf-test@pve!fake' };
+      return Response.json({ data, lease_duration: 0 });
+    }
+    const path = `${url.pathname.replace(/^\/api2\/json\//, '')}${url.search}`;
+    const form = Object.fromEntries(new URLSearchParams(await request.text()));
+    const call = { form, method: request.method, path };
+    calls.push(call);
+    return Response.json({ data: answer(call) ?? null });
+  };
+  // ⚠️ `typeof fetch` carries `preconnect` on bun's lib — client.test.ts has the note.
+  const fetchStub = Object.assign(stub, { preconnect: globalThis.fetch.preconnect });
+  return {
+    calls,
+    layer: transport(fetchStub as typeof fetch),
+    writes: () => calls.filter((c) => c.method !== 'GET').map((c) => `${c.method} ${c.path}`),
+  };
+};
+
+/** Run `body` against the stub's OpenBao (fake-bao-env.ts), then forget the member failover state. */
+export const withoutBao = <A>(body: () => Promise<A>): Promise<A> =>
+  withFakeBao('http://bao.invalid', body).finally(resetLastGoodForTest);

package/src/proxmox/index.test.ts

@@ -1,9 +1,9 @@
 /**
- * Public barrel: control-plane Resource constructors, not guests or NIC apply.
+ * Public barrel: control-plane Resource constructors and `ProxmoxLxc`, not QEMU or NIC apply.
  *
- * ⛔ Lxc/Vm stay Provider-only. A Resource export would let a stack declare
- *   guests before storage/SDN exist. NodeNetwork/NetworkApply stay off the
- *   barrel for the same reason — they stage interfaces.new.
+ * ⛔ Vm stays Provider-only. NodeNetwork/NetworkApply stay off the barrel — they stage
+ *   interfaces.new. ★ Lxc is a Resource since 2026-09-21: adopt-first, refuse-not-replace,
+ *   retain on destroy (lxc.ts).
  */
 import { expect, test } from 'bun:test';
 import { PbsDatastore, ProxmoxStorage } from './index.ts';
@@ -20,6 +20,7 @@ const resourceExports = [
   'ProxmoxGroup',
   'ProxmoxHaResource',
   'ProxmoxHaRule',
+  'ProxmoxLxc',
   'ProxmoxMetricServer',
   'ProxmoxNotificationTarget',
   'ProxmoxRole',
@@ -39,8 +40,7 @@ test('control-plane Resource constructors are on the public barrel', () => {
   }
 });
 
-test('guests and NIC apply stay Provider-only', () => {
-  expect(src).not.toMatch(/export \{ ProxmoxLxc[, }]/);
+test('QEMU and NIC apply stay Provider-only', () => {
   expect(src).not.toMatch(/export \{ ProxmoxVm[, }]/);
   expect(src).not.toMatch(/export \{ ProxmoxNodeNetwork[, }]/);
   expect(src).not.toMatch(/export \{ ProxmoxNetworkApply[, }]/);

package/src/proxmox/index.ts

@@ -6,8 +6,12 @@
  *   provider needs but a consumer should not depend on. An `export *` here would publish
  *   every helper as API and make the next refactor a breaking change.
  * ★ Control-plane Resource constructors (Storage, SDN, access, HA, backup,
- *   metrics, PBS) sit next to their Providers. Guests and NIC apply stay
+ *   metrics, PBS) sit next to their Providers. NIC apply and QEMU stay
  *   Provider-only so a stack cannot declare them by accident.
+ * ★ `ProxmoxLxc` JOINED THEM 2026-09-21, AND IT WAS KEPT OFF UNTIL IT COULD NOT HURT A GUEST.
+ *   The provider-only version diffed four fields and would have planned a create over any read
+ *   failure. The Resource now adopts from the live config, refuses every change PVE cannot make
+ *   in place, and retains on destroy (lxc.ts).
  * ★ Anything else unlisted is still reachable by path if you genuinely need
  *   it — that is a deliberate, visible act rather than an accident of barrelling.
  */
@@ -23,7 +27,7 @@ export { ProxmoxFirewallAliasProvider } from './firewall-alias.ts';
 export { ProxmoxGroup, ProxmoxGroupProvider } from './group.ts';
 export { ProxmoxHaResource, ProxmoxHaResourceProvider } from './ha-resource.ts';
 export { ProxmoxHaRule, ProxmoxHaRuleProvider } from './ha-rule.ts';
-export { ProxmoxLxcProvider } from './lxc.ts';
+export { type LxcAttributes, type LxcProps, ProxmoxLxc, ProxmoxLxcProvider } from './lxc.ts';
 export { ProxmoxMetricServer, ProxmoxMetricServerProvider } from './metric-server.ts';
 export { ProxmoxNetworkApplyProvider } from './network-apply.ts';
 export { ProxmoxNodeNetworkProvider } from './node-network.ts';