@homeflare/alchemy 0.36.0 → 0.37.0

package/src/proxmox/ceph-daemon.ts

@@ -45,19 +45,19 @@
  *   needs no widening for once. ⚠️ `Sys.Modify` on the ROOT path is broad — it also buys
  *   datacenter options and every other cluster-wide config write — so it is worth knowing that
  *   this credential already has it rather than discovering it the next time something is scoped.
+ *
+ * ★ MIGRATED OFF `client.ts` (2026-09-24, decision 43, 2c) — ceph-daemon-wire.ts has the rename
+ *   and why no protocol gap blocks any of the three kinds; `readDaemon` there keeps this family's
+ *   pre-migration single-fold shape (ceph-pool-wire.ts explains why that is not left unfixed).
  */
 import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import {
-  DAEMON_ENDPOINTS,
-  collectionPath,
-  createForm,
-  daemonAttributes,
-  daemonPath,
-} from './ceph-daemon-form.ts';
-import { pve } from './client.ts';
-import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
+import { DAEMON_ENDPOINTS, createForm } from './ceph-daemon-form.ts';
+import { createDaemon, deleteDaemon, notCreated, readDaemon } from './ceph-daemon-wire.ts';
+import { guardWrite } from './distilled-guard.ts';
+import { type PveRequirements, type WithTarget } from './resource.ts';
 
 /**
  * Which Ceph daemon this is. The discriminant picks the collection, the create parameters and
@@ -180,33 +180,41 @@ export const ProxmoxCephDaemon = Resource<ProxmoxCephDaemon>('Proxmox.CephDaemon
   defaultRemovalPolicy: 'retain',
 });
 
-const handlers = pveHandlers<CephDaemonProps, CephDaemonAttributes>({
-  attributes: daemonAttributes,
-  /** ⛔ The ID path, not the collection — POST is registered on `{id}`, exactly like a metric server. */
-  collection: daemonPath,
-  createForm,
-  /** ⚠️ A function, because the kind picks the endpoint — see `DAEMON_ENDPOINTS`. */
-  endpoint: (props: CephDaemonProps) => DAEMON_ENDPOINTS[props.kind],
-  /**
-   * ⛔ TOTAL, AND THIS IS THE REASON THE FILE EXISTS RATHER THAN A SHORTCUT PAST WRITING IT. Every
-   *   field a declaration can carry is CREATE-ONLY and unreadable — `mon-address` comes back as a
-   *   different kind of string, `hotstandby` comes back as a state Ceph elects — and every field
-   *   the read returns is assigned by Ceph: state, rank, quorum, fs_name, standby_replay, addr,
-   *   version. Nothing is left that is both declared and readable. So the honest comparison is
-   *   "does a daemon of this kind and name exist", which `attributes` has already answered by
-   *   returning a value at all, and anything further would be a diff no write could ever satisfy.
-   *   ⛔ AND ON THIS FAMILY THAT DIFF IS NOT MERELY NOISY. There is no PUT, so resource.ts answers
-   *     `replace` rather than `update` whenever `matches` is false — and replace on a mon is
-   *     delete-then-create against a live quorum. A forever-diff here is a forever-OUTAGE-RISK.
-   *   ⚠️ THE PRICE, STATED PLAINLY: editing `hotstandby` or `mon-address` on a declared daemon
-   *     plans as `noop` and never applies. Same bargain storage.ts strikes for a changed `type`.
-   *     Change one by removing the declaration and re-adding it, ONE DAEMON AT A TIME, reading the
-   *     ⛔ on destroy in the header first.
-   */
-  matches: () => true,
-  /** ⛔ The COLLECTION, because there is no GET on the id path. See the second ⛔ in the header. */
-  path: collectionPath,
-  /** ⚠️ No `updateForm`: none of the three has a PUT, so nothing about a daemon is editable. */
+/**
+ * ⛔ TOTAL, AND THIS IS THE REASON THE FILE EXISTS RATHER THAN A SHORTCUT PAST WRITING IT. Every
+ *   field a declaration can carry is CREATE-ONLY and unreadable — `mon-address` comes back as a
+ *   different kind of string, `hotstandby` comes back as a state Ceph elects — and every field
+ *   the read returns is assigned by Ceph: state, rank, quorum, fs_name, standby_replay, addr,
+ *   version. Nothing is left that is both declared and readable. So the honest comparison is
+ *   "does a daemon of this kind and name exist", which `readDaemon` has already answered by
+ *   returning a value at all, and anything further would be a diff no write could ever satisfy.
+ *   ⛔ AND ON THIS FAMILY THAT DIFF IS NOT MERELY NOISY. There is no PUT, so a false mismatch
+ *     would have to be a REPLACE — and replace on a mon is delete-then-create against a live
+ *     quorum. A forever-diff here is a forever-OUTAGE-RISK.
+ *   ⚠️ THE PRICE, STATED PLAINLY: editing `hotstandby` or `mon-address` on a declared daemon
+ *     plans as `noop` and never applies. Same bargain storage.ts strikes for a changed `type`.
+ *     Change one by removing the declaration and re-adding it, ONE DAEMON AT A TIME, reading the
+ *     ⛔ on destroy in the header first.
+ */
+/**
+ * ★ The factory's shape with no `updateForm`: create if absent, else read back untouched.
+ * ⛔ `guardWrite` RUNS RIGHT AFTER THE READ, UNCONDITIONALLY, NOT ONLY ON THE CREATE BRANCH —
+ *   found on adversarial review, 2026-09-24, matching node-network.ts's own `reconcile`.
+ *   `reconcile` also runs for an ADOPTED row with no fresh `diff` first (Plan.ts forces it after
+ *   the probe even when `diff` said noop), so a guard only on the create branch would let a
+ *   caller that skips `diff` (a resumed apply, a verify harness) reach `createDaemon` with
+ *   `mon-address` — a real vendor rule — unchecked.
+ * ★ EXPORTED SO A TEST CAN CALL IT DIRECTLY, bypassing `diff` — the shape the review's own proof
+ *   needed: `findProvider` gives back the wrapped service, this gives the plain function.
+ */
+export const reconcileDaemon = Effect.fn(function* ({ news }: { news: CephDaemonProps }) {
+  const live = yield* readDaemon(news);
+  yield* guardWrite(DAEMON_ENDPOINTS[news.kind], createForm(news), live === undefined);
+  if (live !== undefined) return live;
+  yield* createDaemon(news);
+  const after = yield* readDaemon(news);
+  if (after === undefined) return yield* Effect.die(notCreated(news));
+  return after;
 });
 
 export const ProxmoxCephDaemonProvider = () =>
@@ -214,19 +222,29 @@ export const ProxmoxCephDaemonProvider = () =>
     ProxmoxCephDaemon,
     Effect.succeed(
       ProxmoxCephDaemon.Provider.of({
-        ...handlers,
+        /** ⛔ Empty, like every other resource here — adopting the whole cluster's daemons is not
+         *   an accident anyone should be one `destroy` away from. Adoption stays explicit. */
+        list: () => Effect.succeed([]),
+        read: ({ olds }) => readDaemon(olds),
+        // ★ Matches the pre-migration factory shape exactly (resource.ts): present is settled.
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          yield* guardWrite(DAEMON_ENDPOINTS[news.kind], createForm(news), output === undefined);
+          if (output === undefined) return undefined;
+          const live = yield* readDaemon(news);
+          if (live === undefined) {
+            yield* guardWrite(DAEMON_ENDPOINTS[news.kind], createForm(news), true);
+            return { action: 'update' } as const;
+          }
+          return { action: 'noop' } as const;
+        }),
+        reconcile: ({ news }) => reconcileDaemon({ news }),
         /**
-         * ⛔ THE ONE HANDLER NOT TAKEN FROM THE FACTORY, AND THE ONLY REASON IS THE PATH SPLIT.
-         *   `ops.destroy` DELETEs `spec.path`, which this resource must point at the collection so
-         *   that `read` works at all; DELETE on the collection is not implemented and would answer
-         *   501 while the daemon kept running — a failed destroy that reads like a permissions
-         *   problem. Everything else here is the factory's.
-         * ⚠️ AND IT IS THE DANGEROUS ONE. Re-read the destroy ⛔ in the header before letting a
-         *   plan that removes a mon run: two gone at once is a cluster with no quorum and every
-         *   guest on `rbd-c1` blocked on I/O.
+         * ⛔ THE DANGEROUS ONE. Re-read the destroy ⛔ in the header before letting a plan that
+         *   removes a mon run: two gone at once is a cluster with no quorum and every guest on
+         *   `rbd-c1` blocked on I/O.
          */
-        delete: ({ olds }: { olds: CephDaemonProps }) =>
-          pve(olds.target, 'provision', 'DELETE', daemonPath(olds)),
+        delete: ({ olds }) => deleteDaemon(olds),
       }),
     ),
   );

package/src/proxmox/ceph-fs-delete.test.ts

@@ -0,0 +1,81 @@
+/**
+ * `Proxmox.CephFs`'s destroy path — the one place in this migration that composes a distilled
+ * call (`readFs`, before and after) with a hand-client one (`destroyFs`, unmigrated — ceph-fs-
+ * wire.ts's header has the measured protocol reason) inside a single handler. Flagged by
+ * adversarial review as untested anywhere in the repo before this file: `readFs` alone is proven
+ * by ceph-fs-write.test.ts and ceph-adopt.test.ts, `destroyFs` alone is unchanged from main, but
+ * the two composed together — on a destructive, hard-to-reverse `RemovalPolicy.destroy()` — had
+ * no coverage of the seam itself.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { ProxmoxCephFs, ProxmoxCephFsProvider } from './ceph-fs.ts';
+import { engineOver } from '../verify/fake-engine.ts';
+import { FAKE_TARGET, type PveCall, fakePve, withoutBao } from './fake-pve.ts';
+
+const NODE = 'node-b';
+const NAME = 'oldfs';
+const INDEX = `nodes/${NODE}/ceph/fs`;
+const OBJECT = `${INDEX}/${NAME}`;
+const UPID = 'UPID:node-b:fake:destroyfs';
+const TASK_STATUS = `nodes/${NODE}/tasks/${encodeURIComponent(UPID)}/status`;
+
+const declared = () => ProxmoxCephFs(NAME, { name: NAME, node: NODE, target: FAKE_TARGET });
+
+describe('destroying a CephFS', () => {
+  test(
+    'RemovalPolicy.destroy() then undeclaring: readFs (distilled) finds it, destroyFs ' +
+      '(client.ts) removes it, and the distilled read-back confirms it is gone',
+    async () => {
+      let destroyed = false;
+      const fake = fakePve((call: PveCall) => {
+        if (call.method === 'GET' && call.path === INDEX) {
+          return destroyed
+            ? []
+            : [{ data_pool: `${NAME}_data`, metadata_pool: `${NAME}_metadata`, name: NAME }];
+        }
+        if (call.method === 'DELETE' && call.path === OBJECT) {
+          destroyed = true;
+          return UPID;
+        }
+        if (call.method === 'GET' && call.path === TASK_STATUS) {
+          return { exitstatus: 'OK', status: 'stopped' };
+        }
+        return undefined;
+      });
+      await withoutBao(async () => {
+        const engine = engineOver(ProxmoxCephFsProvider().pipe(Layer.provideMerge(fake.layer)));
+        expect(await engine.deploy(declared())).toEqual({ [NAME]: 'adopted' });
+        await engine.deploy(declared().pipe(RemovalPolicy.destroy()));
+        await engine.deploy(Effect.void);
+      });
+      expect(fake.writes()).toEqual([`DELETE ${OBJECT}`]);
+    },
+  );
+
+  test('a filesystem already removed by hand: delete is a no-op, not a false DELETE', async () => {
+    let removedByHand = false;
+    const fake = fakePve((call: PveCall) => {
+      if (call.method === 'GET' && call.path === INDEX) {
+        return removedByHand
+          ? []
+          : [{ data_pool: `${NAME}_data`, metadata_pool: `${NAME}_metadata`, name: NAME }];
+      }
+      return undefined;
+    });
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxCephFsProvider().pipe(Layer.provideMerge(fake.layer)));
+      expect(await engine.deploy(declared())).toEqual({ [NAME]: 'adopted' });
+      await engine.deploy(declared().pipe(RemovalPolicy.destroy()));
+      // ⚠️ Cleaned up outside Alchemy, AFTER that redeploy and BEFORE the undeclare below —
+      //   `readFs` (distilled) already answers absent by the time `delete` runs, the same branch
+      //   ceph-fs.ts's own ⚠️ on `delete` documents. Removing it any earlier would instead read as
+      //   drift on the redeploy above and reconcile a create, which is a different test.
+      removedByHand = true;
+      await engine.deploy(Effect.void);
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+});

package/src/proxmox/ceph-fs-distilled.ts

@@ -0,0 +1,102 @@
+/**
+ * `Proxmox.CephFs`'s distilled half: the index read and the create — see ceph-fs-wire.ts's own
+ * header for why `destroyFs` stays there, on `client.ts`, unmigrated.
+ *
+ * ⛔ `nodes.updateNodeCephFs` IS distilled's GENERATOR MISNAMING A CREATE, NOT A SECOND ENDPOINT.
+ *   Checked directly against its schema (`T.Http({ method: "POST", uri:
+ *   "/nodes/{node}/ceph/fs/{name}" })`) rather than trusted from the function name — it is the
+ *   SAME single write PVE registers, `createfs`. Harmless once named here for what it is.
+ *
+ * ★ THE SETTLE POLL IS A SEPARATE FUNCTION FROM ceph-fs-wire.ts's, NOT A SHARED ONE, because it
+ *   calls a different task-status operation on a different transport — `nodes.getNodeTaskStatus`
+ *   here, `pve()` there — but the POLICY is identical on purpose: same cadence
+ *   (`POLL_SECONDS`/`POLL_ATTEMPTS`, imported, not retyped), same "an unreadable status is not
+ *   settled yet, not a failure" tolerance. That tolerance is why this calls the RAW distilled
+ *   operation directly rather than `@distilled.cloud/proxmox`'s own `Task.awaitTask` — CHECKED
+ *   against its source (`task.ts`): it propagates a poll failure as a genuine typed
+ *   `GetNodeTaskStatusError` instead of treating it as "not yet", which would turn a missing
+ *   `Sys.Audit` grant or a node mid-restart into a failed create instead of a patient one.
+ */
+import * as nodes from '@distilled.cloud/proxmox/nodes';
+import * as Effect from 'effect/Effect';
+import type { CephFsProps } from './ceph-fs.ts';
+import { POLL_ATTEMPTS, POLL_SECONDS, createForm, objectPath, readRow } from './ceph-fs-wire.ts';
+import { runPve } from './distilled-pve.ts';
+
+/**
+ * The index, read via distilled — the same shape `readRow` (ceph-fs-wire.ts) already narrows.
+ *
+ * ⛔ FOLDS EVERY FAILURE TO `undefined`, matching the pre-migration `pveOperations.read` this
+ *   family used (`resource.ts`, `Effect.orElseSucceed`) — the same single-fold shape
+ *   ceph-pool-wire.ts's `readPoolStatus` preserves and explains: this migration's own rule is
+ *   behaviour surviving byte-for-byte, not the newer dual-path pattern gaining a new family.
+ */
+export const readFs = (props: CephFsProps) =>
+  runPve(props.target, 'read', false, nodes.listNodeCephFs({ node: props.node })).pipe(
+    Effect.map((rows) => readRow(rows as unknown as Record<string, unknown>, props)),
+    Effect.orElseSucceed(() => undefined),
+  );
+
+/** `updateNodeCephFs`'s own request shape — `createForm`, translated. No field is renamed. */
+const toDistilledCreate = (props: CephFsProps): nodes.UpdateNodeCephFsRequest =>
+  ({
+    ...createForm(props),
+    name: props.name,
+    node: props.node,
+  }) as unknown as nodes.UpdateNodeCephFsRequest;
+
+/** Wait for the create's forked task — the distilled twin of ceph-fs-wire.ts's `settle`. */
+const settleCreate = (props: CephFsProps, upid: string) =>
+  Effect.gen(function* () {
+    for (let attempt = 0; attempt < POLL_ATTEMPTS; attempt += 1) {
+      const status = yield* runPve(
+        props.target,
+        'read',
+        false,
+        nodes.getNodeTaskStatus({ node: props.node, upid }),
+      ).pipe(Effect.orElseSucceed(() => undefined));
+      if (status?.status === 'stopped') {
+        if (status.exitstatus === 'OK') return;
+        return yield* Effect.die(
+          new Error(
+            `${objectPath(props)}: PVE task ${upid} finished with "${status.exitstatus ?? 'no exit status'}". ` +
+              'The write returned HTTP 200 because it only forked the worker -- the real error is ' +
+              `in \`pvesh get /nodes/${props.node}/tasks/${upid}/log\`.`,
+          ),
+        );
+      }
+      yield* Effect.sleep(POLL_SECONDS * 1000);
+    }
+    return yield* Effect.die(
+      new Error(
+        `${objectPath(props)}: PVE task ${upid} was still running after ` +
+          `${String(POLL_ATTEMPTS * POLL_SECONDS)}s, or its status could not be read. Check the ` +
+          'task log, and check that the `read` role holds Sys.Audit on ' +
+          `/nodes/${props.node} -- each call mints a new token, so the poller is never the task ` +
+          'owner and is answered 403 rather than told to wait.',
+      ),
+    );
+  });
+
+/** POST the create, then wait for the worker. ⛔ The caller still reads back; see ceph-fs.ts. */
+export const createFs = (props: CephFsProps) =>
+  Effect.gen(function* () {
+    const upid = yield* runPve(
+      props.target,
+      'provision',
+      true,
+      nodes.updateNodeCephFs(toDistilledCreate(props)),
+    );
+    // ⛔ NO UPID MEANS NO WORKER. PVE answers 200 with `{"data":null}` on calls that did nothing,
+    //   and here that is indistinguishable from success by status code alone. Refusing now is the
+    //   difference between a clear failure and a state entry for a filesystem nobody built.
+    if (upid === '') {
+      return yield* Effect.die(
+        new Error(
+          `${objectPath(props)}: POST returned no task id. PVE wraps every answer in ` +
+            '{"data":...} and can report success on a call that did nothing.',
+        ),
+      );
+    }
+    yield* settleCreate(props, upid);
+  });

package/src/proxmox/ceph-fs-wire.ts

@@ -48,6 +48,17 @@
  *   user needs 'Sys.Audit' permissions on '/nodes/<node>' if they are not the owner of the task."
  *   Grant it on the `read` role, or every create burns the full cap below and reports the wrong
  *   cause.
+ *
+ * ★ AS OF 2026-09-24 (decision 43's walk-down, 2c) THIS FILE IS `client.ts`'s HALF ONLY. The read
+ *   (`readRow`) moved to `ceph-fs-distilled.ts`, and so did the create — `nodes.updateNodeCephFs`
+ *   (distilled's own misnamed POST, confirmed against its `T.Http` annotation) plus a SEPARATE
+ *   distilled `settle`, using the raw `getNodeTaskStatus` operation in its own tolerant poll loop
+ *   rather than `Task.awaitTask`, which does not tolerate a poll failure the way this family needs
+ *   (network-apply-read.ts's own header has the fuller reasoning). `destroyFs` stays HERE,
+ *   unmigrated: distilled types `remove_pools`/`remove_storages` as `T.Body` on a DELETE, and the
+ *   ⛔ two paragraphs up is the MEASURED reason PVE would silently ignore both flags if sent that
+ *   way — a real protocol gap, not a judgement call. `settle` below is still shared where it can
+ *   be: `createForm`/`objectPath`/`destroyPath` are pure and reused by the distilled file too.
  */
 import * as Effect from 'effect/Effect';
 import type { CephFsAttributes, CephFsProps } from './ceph-fs.ts';
@@ -97,12 +108,16 @@ type TaskStatus = { readonly status?: string; readonly exitstatus?: string };
  *   itself spends waiting for an MDS to go active, and is short enough that a stuck task fails the
  *   deploy rather than parking it for the afternoon.
  */
-const POLL_SECONDS = 2;
-const POLL_ATTEMPTS = 45;
+// ★ EXPORTED so ceph-fs-distilled.ts's OWN settle polls the same cadence and cap — one number.
+export const POLL_SECONDS = 2;
+export const POLL_ATTEMPTS = 45;
 
 /** ⚠️ `nodes/{n}/ceph/fs/{name}` — the POST and DELETE target, and NOT where a read goes. */
 export const objectPath = (props: CephFsProps) => `nodes/${props.node}/ceph/fs/${props.name}`;
 
+/** The vendor rules `createForm` is checked against — `guardWrite`, distilled-guard.ts. */
+export const CEPH_FS_CREATE = 'pve:POST /nodes/{node}/ceph/fs/{name}';
+
 /** Only the declared flags. ⚠️ An omitted one is PVE's own default, not a value to send. */
 const field = (name: string, value: string | undefined): Record<string, string> =>
   value === undefined ? {} : { [name]: value };
@@ -173,35 +188,6 @@ const settle = (target: PveTarget, node: string, upid: string, what: string) =>
     );
   });
 
-/**
- * POST the create, then wait for the worker. ⛔ The caller still reads back; see ceph-fs.ts.
- *
- * ⚠️ A CREATE NEEDS A RUNNING *AND* A STANDBY MDS, and refuses BEFORE it forks -- "no running
- *   Metadata Server (MDS) found!" / "no standby Metadata Server (MDS) found!" are synchronous, so
- *   they surface as a failed POST rather than as a silent worker. C1 has three (MEASURED: node-c
- *   `up:active` for cephfs-c1, node-b and node-d `up:standby`), so this is a note for a smaller cluster.
- * ⚠️ BOTH WRITES CHECK `Sys.Modify` ON `/` -- the root, with the breadth metric-server.ts warns
- *   about: granting it buys datacenter options and every other cluster-wide config write too.
- */
-export const createFs = (props: CephFsProps) =>
-  Effect.gen(function* () {
-    const upid = text(
-      yield* pve<string>(props.target, 'provision', 'POST', objectPath(props), createForm(props)),
-    );
-    // ⛔ NO UPID MEANS NO WORKER. PVE answers 200 with `{"data":null}` on calls that did nothing,
-    //   and here that is indistinguishable from success by status code alone. Refusing now is the
-    //   difference between a clear failure and a state entry for a filesystem nobody built.
-    if (upid === '') {
-      return yield* Effect.die(
-        new Error(
-          `${objectPath(props)}: POST returned no task id. PVE wraps every answer in ` +
-            '{"data":...} and can report success on a call that did nothing.',
-        ),
-      );
-    }
-    yield* settle(props.target, props.node, upid, objectPath(props));
-  });
-
 /**
  * DELETE the filesystem, then wait for the worker.
  *

package/src/proxmox/ceph-fs-write.test.ts

@@ -0,0 +1,67 @@
+/**
+ * `Proxmox.CephFs`'s create path, through Alchemy's own Plan and Apply over a fake cluster — the
+ * path ceph-adopt.test.ts does not reach (it is adopt-only). Proves the distilled-based create
+ * (ceph-fs-distilled.ts) POSTs, polls the forked task via the RAW `getNodeTaskStatus` operation
+ * (not `Task.awaitTask` — that file's own header has the measured reason), and reads back.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { ProxmoxCephFs, ProxmoxCephFsProvider } from './ceph-fs.ts';
+import { FAKE_TARGET, type PveCall, fakePve, withoutBao } from './fake-pve.ts';
+
+const NODE = 'node-b';
+const NAME = 'newfs';
+const INDEX = `nodes/${NODE}/ceph/fs`;
+const OBJECT = `${INDEX}/${NAME}`;
+const UPID = 'UPID:node-b:fake:createfs';
+// ⚠️ PERCENT-ENCODED, MATCHING ceph-fs-wire.ts's OWN `encodeURIComponent(upid)` — the UPID is
+//   full of colons, and distilled's `T.Label()` encodes the path segment the same way.
+const TASK_STATUS = `nodes/${NODE}/tasks/${encodeURIComponent(UPID)}/status`;
+
+const declared = () => ProxmoxCephFs(NAME, { name: NAME, node: NODE, target: FAKE_TARGET });
+
+describe('a genuinely new CephFS', () => {
+  test('POSTs, polls the forked task through, and reads the index back', async () => {
+    let posted = false;
+    let polls = 0;
+    const fake = fakePve((call: PveCall) => {
+      if (call.method === 'GET' && call.path === INDEX) {
+        return posted
+          ? [{ data_pool: `${NAME}_data`, metadata_pool: `${NAME}_metadata`, name: NAME }]
+          : [];
+      }
+      if (call.method === 'POST' && call.path === OBJECT) {
+        posted = true;
+        return UPID;
+      }
+      if (call.method === 'GET' && call.path === TASK_STATUS) {
+        polls += 1;
+        // ⚠️ RUNNING ONCE FIRST — proves the poll loop actually loops, not just checks once.
+        return polls === 1 ? { status: 'running' } : { exitstatus: 'OK', status: 'stopped' };
+      }
+      return undefined;
+    });
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxCephFsProvider().pipe(Layer.provideMerge(fake.layer)));
+      expect(await engine.deploy(declared())).toEqual({ [NAME]: 'create' });
+    });
+    expect(polls).toBeGreaterThanOrEqual(2);
+    expect(fake.writes()).toEqual([`POST ${OBJECT}`]);
+  });
+
+  test('a task that finishes with a real error dies with the task log pointer, not a false create', async () => {
+    const fake = fakePve((call: PveCall) => {
+      if (call.method === 'GET' && call.path === INDEX) return [];
+      if (call.method === 'POST' && call.path === OBJECT) return UPID;
+      if (call.method === 'GET' && call.path === TASK_STATUS) {
+        return { exitstatus: 'no running Metadata Server (MDS) found!', status: 'stopped' };
+      }
+      return undefined;
+    });
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxCephFsProvider().pipe(Layer.provideMerge(fake.layer)));
+      await expect(engine.deploy(declared())).rejects.toBeDefined();
+    });
+  });
+});