@homeflare/alchemy 0.36.0 → 0.37.1

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

@@ -0,0 +1,146 @@
+/**
+ * `Proxmox.CephPool`'s write paths, through Alchemy's own Plan and Apply over a fake cluster —
+ * the paths ceph-pool-adopt.test.ts does not reach: a genuine create, the PG-merge guard that
+ * stops a create over a pool the read could not confirm, and a real destroy.
+ *
+ * ★ THE ABSENCE SIGNAL IS THE MEASURED ONE. `GET .../pool/{name}/status` on a name with no pool
+ *   answers HTTP 500 (live TB4 `n2`, 2026-09-24, read-role, read-only probe:
+ *   `{"data":null,"message":"error with 'osd pool get': mon_cmd failed - unrecognized pool
+ *   '<name>'\n"}`) — SDK PR #265 now recognizes it as `CephPoolNotFound`. Only that tag folds
+ *   to absence; unrelated 500s propagate. `confirmAbsent` (ceph-pool-settle.ts) still asks a
+ *   SECOND, different question — does the index list this name — before create may run.
+ *   `fakePve` only answers HTTP 200, so this file stubs the measured 500 directly.
+ */
+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 * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { engineOver } from '../verify/fake-engine.ts';
+import { ProxmoxCephPool, ProxmoxCephPoolProvider } from './ceph-pool.ts';
+import { FAKE_TARGET, withoutBao } from './fake-pve.ts';
+
+const NODE = 'node-b';
+const NAME = 'newpool';
+const INDEX = `nodes/${NODE}/ceph/pool`;
+const OBJECT = `${INDEX}/${NAME}`;
+const STATUS = `${OBJECT}/status`;
+
+/** The measured missing-pool 500, classified by the SDK as `CephPoolNotFound`. */
+const absent = () =>
+  Response.json(
+    {
+      data: null,
+      message: `error with 'osd pool get': mon_cmd failed - unrecognized pool '${NAME}'\n`,
+    },
+    { status: 500 },
+  );
+
+/**
+ * A cluster the test drives through three states: no pool at all, the pool listed but its status
+ * unreadable (the PG-merge guard's own case), and a real pool. `writes` records every non-GET
+ * call the same way `fakePve.writes()` does, for the same assertions.
+ */
+const cluster = () => {
+  const writes: string[] = [];
+  let indexRow: Record<string, unknown> | undefined;
+  let statusRow: Record<string, unknown> | undefined;
+  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 wire = decodeURIComponent(url.pathname.replace(/^\/api2\/json\//, ''));
+    if (request.method !== 'GET') writes.push(`${request.method} ${wire}`);
+    if (wire === INDEX && request.method === 'GET') {
+      return Response.json({ data: indexRow === undefined ? [] : [indexRow] });
+    }
+    if (wire === INDEX && request.method === 'POST') {
+      indexRow = { pool_name: NAME };
+      statusRow = {
+        application_list: [],
+        crush_rule: 'replicated_rule',
+        id: 9,
+        min_size: 2,
+        name: NAME,
+        pg_autoscale_mode: 'on',
+        pg_num: 128,
+        size: 3,
+      };
+      return Response.json({ data: 'UPID:node-b:fake:createpool' });
+    }
+    if (wire === STATUS && request.method === 'GET') {
+      return statusRow === undefined ? absent() : Response.json({ data: statusRow });
+    }
+    if (wire === OBJECT && request.method === 'DELETE') {
+      indexRow = undefined;
+      statusRow = undefined;
+      return Response.json({ data: 'UPID:node-b:fake:destroypool' });
+    }
+    return Response.json({ data: null });
+  };
+  const fetchStub = Object.assign(stub, { preconnect: globalThis.fetch.preconnect });
+  return {
+    layer: FetchHttpClient.layer.pipe(
+      Layer.provideMerge(Layer.succeed(FetchHttpClient.Fetch, fetchStub as typeof fetch)),
+    ),
+    listAsIfPresent: () => {
+      indexRow = { pool_name: NAME };
+    },
+    writes,
+  };
+};
+
+const declared = () =>
+  ProxmoxCephPool(NAME, {
+    crush_rule: 'replicated_rule',
+    min_size: 2,
+    name: NAME,
+    node: NODE,
+    pg_autoscale_mode: 'on',
+    size: 3,
+    target: FAKE_TARGET,
+  });
+
+const engineFor = (fake: ReturnType<typeof cluster>) =>
+  engineOver(ProxmoxCephPoolProvider().pipe(Layer.provideMerge(fake.layer)));
+
+describe('a genuinely new pool', () => {
+  test('creates once confirmAbsent finds the index empty, and settle confirms the match', async () => {
+    const fake = cluster();
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      expect(await engine.deploy(declared())).toEqual({ [NAME]: 'create' });
+    });
+    expect(fake.writes).toEqual([`POST ${INDEX}`]);
+  });
+});
+
+describe("the PG-merge guard: the index lists the pool but its status can't be read", () => {
+  test('refuses the create rather than risking a PG merge on a live pool', async () => {
+    const fake = cluster();
+    fake.listAsIfPresent(); // index says present; statusRow stays undefined -> every read 500s
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await expect(engine.deploy(declared())).rejects.toBeDefined();
+    });
+    // ⛔ THE ASSERTION THAT MATTERS: no POST ever reached the fake cluster.
+    expect(fake.writes).toEqual([]);
+  });
+});
+
+describe('destroying a pool', () => {
+  test('RemovalPolicy.destroy() then undeclaring sends exactly one DELETE', async () => {
+    const fake = cluster();
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      expect(await engine.deploy(declared())).toEqual({ [NAME]: 'create' });
+      await engine.deploy(declared().pipe(RemovalPolicy.destroy()));
+      await engine.deploy(Effect.void);
+    });
+    expect(fake.writes).toEqual([`POST ${INDEX}`, `DELETE ${OBJECT}`]);
+  });
+});

package/src/proxmox/ceph-pool.ts

@@ -5,11 +5,16 @@
  * ⛔ IT DOES NOT USE `pveHandlers`, AND THE REASON IS MEASURED RATHER THAN STYLISTIC: THE READ AND
  *   THE WRITES SIT AT DIFFERENT PATHS. `GET /nodes/{node}/ceph/pool/{name}` is `poolindex` and
  *   answers `[{"name":"status"}]` — an INDEX OF CHILDREN, not the pool. The pool is one level
- *   further down, at `.../status` (`getpool`), which accepts no PUT and no DELETE. A `PveSpec`
- *   carries ONE `path` for read, update and delete, so this family cannot be spelled in it. `path`
- *   below is therefore the READ path and nothing else consumes it: `ops.reconcile` and
- *   `ops.destroy` go unused and the two write handlers name their own path. acl.ts is the
- *   precedent for hand-writing the five handlers over `pveOperations`.
+ *   further down, at `.../status` (`getpool`), which accepts no PUT and no DELETE. Every handler
+ *   below is hand-written for that reason, on `client.ts` and now on distilled alike — acl.ts is
+ *   the precedent for hand-writing over the factory.
+ *
+ * ★ MIGRATED OFF `client.ts`'s generic `pve()` ONTO `@distilled.cloud/proxmox`'s typed
+ *   `nodes.getNodeCephPoolStatus`/`createNodeCephPool`/`putNodeCephPool`/`deleteNodeCephPool`/
+ *   `listNodeCephPool` (2026-09-24, decision 43's walk-down, 2c). `distilled-pve.ts`'s `runPve`
+ *   replaces `pve()`; `readPoolStatus` (ceph-pool-wire.ts) keeps the SAME single-fold shape this
+ *   family always had — see that file's own header for why this migration does not also add the
+ *   newer dual-path pattern `Proxmox.NodeNetwork` carries.
  *
  * ⛔ A CREATE FIRED AT A POOL THAT ALREADY EXISTS IS NOT A NO-OP, IT IS A PG MERGE — the second ⛔
  *   in ceph-pool-form.ts has the evidence, and `confirmAbsent` below is the guard that stops it.
@@ -36,14 +41,13 @@
  *   deliberately, the way `Pool.Allocate` was widened for `Proxmox.Pool`.
  */
 import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
+import * as nodes from '@distilled.cloud/proxmox/nodes';
 import * as Effect from 'effect/Effect';
 import {
   type CephPoolAttributes,
   type CephPoolProps,
-  UNSET,
-  applications,
-  collection,
   createBody,
   hint,
   object,
@@ -51,10 +55,17 @@ import {
   updateBody,
 } from './ceph-pool-form.ts';
 import { confirmAbsent, settle } from './ceph-pool-settle.ts';
-import { pve } from './client.ts';
-import { type PveRequirements, type PveSpec, pveOperations } from './resource.ts';
+import {
+  CEPH_POOL_CREATE,
+  CEPH_POOL_UPDATE,
+  readPoolStatus,
+  toDistilledCreate,
+  toDistilledUpdate,
+} from './ceph-pool-wire.ts';
+import { guardWrite } from './distilled-guard.ts';
+import { runPve } from './distilled-pve.ts';
+import { type PveRequirements } from './resource.ts';
 import { formToSend } from './update-guard.ts';
-import { bool, int, num, text } from './values.ts';
 
 export type { CephPoolAttributes, CephPoolProps };
 
@@ -71,73 +82,24 @@ export const ProxmoxCephPool = Resource<ProxmoxCephPool>('Proxmox.CephPool', {
   defaultRemovalPolicy: 'retain',
 });
 
-const spec: PveSpec<CephPoolProps, CephPoolAttributes> = {
-  /**
-   * ⛔ `name` IS THE PRESENCE TEST, AND IT IS ALSO HOW THE INDEX TRAP FAILS SAFE. Pointed at
-   *   `.../pool/{name}` rather than `.../status`, the factory would hand this function an ARRAY:
-   *   every field would read absent and the plan would report an update no write can satisfy.
-   *   `getpool` always returns `name` for a real pool, so that shape answers "not there" instead
-   *   — and "not there" cannot reach a create unless `confirmAbsent` agrees.
-   */
-  attributes: (live, props) => {
-    if (typeof live['name'] !== 'string') return undefined;
-    return {
-      applications: applications(live['application_list']),
-      crush_rule: text(live['crush_rule']),
-      id: int(live['id'], UNSET),
-      min_size: int(live['min_size'], UNSET),
-      name: props.name,
-      node: props.node,
-      nodelete: bool(live['nodelete']),
-      nopgchange: bool(live['nopgchange']),
-      nosizechange: bool(live['nosizechange']),
-      pg_autoscale_mode: text(live['pg_autoscale_mode']),
-      pg_num: int(live['pg_num'], UNSET),
-      pg_num_min: int(live['pg_num_min'], UNSET),
-      size: int(live['size'], UNSET),
-      target_size: int(live['target_size'], UNSET),
-      target_size_ratio: num(live['target_size_ratio'], UNSET),
-    };
-  },
-  collection,
-  createForm: createBody,
-  /** The vendor rules both forms are checked against at plan time — resource-spec.ts. */
-  endpoint: {
-    create: 'pve:POST /nodes/{node}/ceph/pool',
-    update: 'pve:PUT /nodes/{node}/ceph/pool/{name}',
-  },
-  /**
-   * ⛔ DECLARING WHAT IS LIVE MUST PLAN noop, AND EVERY OMISSION HERE IS WHY. Out, each with its
-   *   reason on the prop it belongs to: `pg_num` (the autoscaler rewrites it), `application` (the
-   *   write only ever ADDS to a list), `target_size_ratio` (float equality), `id`, `applications`
-   *   and the three `no*` flags (PVE returns them and accepts none of them on write), `node` and
-   *   `name` (the address the read was made at — true by construction, never a diff). In, and each
-   *   measured to round-trip unchanged against C1's four pools on 2026-09-13: size 3, min_size 2,
-   *   pg_autoscale_mode `on`, crush_rule `replicated_rule`, pg_num_min where it is set (16 on
-   *   cephfs-c1_metadata, absent on rbd-c1), target_size in bytes — and each of the last two
-   *   through `hint`, which drops a declared zero for the reason given on it.
-   */
-  matches: (attributes, props) =>
-    same(props.size, attributes.size, attributes.nosizechange) &&
-    same(props.min_size, attributes.min_size, attributes.nosizechange) &&
-    same(props.pg_autoscale_mode, attributes.pg_autoscale_mode) &&
-    same(hint(props.pg_num_min), attributes.pg_num_min, attributes.nopgchange) &&
-    same(props.crush_rule, attributes.crush_rule, attributes.crush_rule === '') &&
-    same(hint(props.target_size), attributes.target_size),
-  /**
-   * ⛔ THE READ PATH, AND ONLY THE READ PATH.
-   * ⚠️ `?verbose=1` IS WHAT MAKES `applications` VISIBLE AT ALL — without it PVE omits the tags
-   *   entirely (MEASURED across all four pools; there is no `application` key either way, only
-   *   `application_list`, and only when verbose). The cost is that verbose adds two unguarded mon
-   *   commands, `df` and `osd pool application get`, so a degraded mgr can fail the read. That is
-   *   safe here rather than merely unlucky: a failed read is "absent", and "absent" cannot reach a
-   *   create unless `confirmAbsent` agrees.
-   */
-  path: (props) => `${object(props)}/status?verbose=1`,
-  updateForm: updateBody,
-};
-
-const ops = pveOperations(spec);
+/**
+ * ⛔ DECLARING WHAT IS LIVE MUST PLAN noop, AND EVERY OMISSION HERE IS WHY. Out, each with its
+ *   reason on the prop it belongs to: `pg_num` (the autoscaler rewrites it), `application` (the
+ *   write only ever ADDS to a list), `target_size_ratio` (float equality), `id`, `applications`
+ *   and the three `no*` flags (PVE returns them and accepts none of them on write), `node` and
+ *   `name` (the address the read was made at — true by construction, never a diff). In, and each
+ *   measured to round-trip unchanged against C1's four pools on 2026-09-13: size 3, min_size 2,
+ *   pg_autoscale_mode `on`, crush_rule `replicated_rule`, pg_num_min where it is set (16 on
+ *   cephfs-c1_metadata, absent on rbd-c1), target_size in bytes — and each of the last two
+ *   through `hint`, which drops a declared zero for the reason given on it.
+ */
+const matches = (attributes: CephPoolAttributes, props: CephPoolProps) =>
+  same(props.size, attributes.size, attributes.nosizechange) &&
+  same(props.min_size, attributes.min_size, attributes.nosizechange) &&
+  same(props.pg_autoscale_mode, attributes.pg_autoscale_mode) &&
+  same(hint(props.pg_num_min), attributes.pg_num_min, attributes.nopgchange) &&
+  same(props.crush_rule, attributes.crush_rule, attributes.crush_rule === '') &&
+  same(hint(props.target_size), attributes.target_size);
 
 export const ProxmoxCephPoolProvider = () =>
   Provider.effect(
@@ -146,28 +108,45 @@ export const ProxmoxCephPoolProvider = () =>
       ProxmoxCephPool.Provider.of({
         /** ⛔ Empty, and here it is what keeps `.mgr` and the two cephfs pools out — see the header. */
         list: () => Effect.succeed([]),
-        read: ({ olds }) => ops.read(olds),
-        diff: ({ news, output }) => ops.diff(news, output),
+        read: ({ olds }) => readPoolStatus(olds),
         /**
-         * ⚠️ NOT `ops.reconcile`: it POSTs the moment a read comes back empty, and reads back once,
-         *   immediately. Both are wrong for a family whose writes are forked workers and whose
+         * ★ HAND-WRITTEN, matching the pre-migration `ops.diff` shape exactly (resource.ts) — this
+         *   family never used the factory's own `diff`/`reconcile` (only its `read`), and the
+         *   factory itself cannot run a distilled operation, so both are inlined here now.
+         */
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          yield* guardWrite(CEPH_POOL_CREATE, createBody(news), output === undefined);
+          yield* guardWrite(CEPH_POOL_UPDATE, updateBody(news), false);
+          if (output === undefined) return undefined;
+          const live = yield* readPoolStatus(news);
+          if (live === undefined) {
+            yield* guardWrite(CEPH_POOL_CREATE, createBody(news), true);
+            return { action: 'update' } as const;
+          }
+          return matches(live, news)
+            ? ({ action: 'noop' } as const)
+            : ({ action: 'update' } as const);
+        }),
+        /**
+         * ⚠️ NOT A GENERIC reconcile: it POSTs the moment a read comes back empty, and reads back
+         *   once, immediately. Both are wrong for a family whose writes are forked workers and whose
          *   create is destructive against a pool that is already there.
          */
         reconcile: Effect.fn(function* ({ news }) {
-          const live = yield* ops.read(news);
+          const live = yield* readPoolStatus(news);
           let upid: string | undefined;
           if (live === undefined) {
-            // ⛔ THE GUARD `ops.reconcile` WOULD HAVE RUN, RESTORED. This handler replaces it
+            // ⛔ THE GUARD A GENERIC reconcile WOULD HAVE RUN, RESTORED. This handler replaces it
             //   wholesale, so without these two calls an ADOPTED pool — whose diff answer Alchemy
             //   discards — would reach the cluster with nothing having checked its body.
-            yield* ops.guardCreate(news, true);
-            yield* confirmAbsent(news, spec.collection(news), object(news));
-            upid = yield* pve<string>(
+            yield* guardWrite(CEPH_POOL_CREATE, createBody(news), true);
+            yield* confirmAbsent(news, object(news));
+            upid = yield* runPve(
               news.target,
               'provision',
-              'POST',
-              collection(news),
-              createBody(news),
+              true,
+              nodes.createNodeCephPool(toDistilledCreate(news)),
             );
           } else {
             /**
@@ -177,18 +156,23 @@ export const ProxmoxCephPoolProvider = () =>
              *   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));
+            const form = formToSend(matches, live, news, updateBody(news));
             if (form !== undefined) {
-              yield* ops.guardUpdate(news);
-              upid = yield* pve<string>(news.target, 'provision', 'PUT', object(news), form);
+              yield* guardWrite(CEPH_POOL_UPDATE, updateBody(news), false);
+              upid = yield* runPve(
+                news.target,
+                'provision',
+                true,
+                nodes.putNodeCephPool(toDistilledUpdate(news)),
+              );
             }
           }
           const after = yield* settle(
             news,
-            ops.read,
-            (row) => row !== undefined && spec.matches(row, news),
+            readPoolStatus,
+            (row) => row !== undefined && matches(row, news),
           );
-          if (after === undefined || !spec.matches(after, news)) {
+          if (after === undefined || !matches(after, news)) {
             return yield* Effect.die(
               new Error(
                 `${object(news)}: the write returned no error but the pool still does not match ` +
@@ -212,8 +196,13 @@ export const ProxmoxCephPoolProvider = () =>
          *   set in ceph.conf and the two sources disagree by design.
          */
         delete: Effect.fn(function* ({ olds }) {
-          yield* pve<string>(olds.target, 'provision', 'DELETE', object(olds));
-          const left = yield* settle(olds, ops.read, (row) => row === undefined);
+          yield* runPve(
+            olds.target,
+            'provision',
+            true,
+            nodes.deleteNodeCephPool({ name: olds.name, node: olds.node }),
+          );
+          const left = yield* settle(olds, readPoolStatus, (row) => row === undefined);
           if (left !== undefined) {
             return yield* Effect.die(
               new Error(

package/src/proxmox/group-wire.ts

@@ -97,20 +97,15 @@ export const readGroupOrFail = (props: GroupProps) =>
   );
 
 /**
- * ⛔ FOLDS A GENUINE READ FAILURE TO `undefined` TOO, AND ONLY `read`/`reconcile` MAY USE IT.
- *   PVE's OWN missing-group answer is a thrown 500 (the ⛔ above), so `reconcile`'s create branch
- *   NEEDS "absent" from a failure to ever run at all — without this fold, a brand-new group could
- *   never be created, because its very-first read would always fail loudly. Safe here because a
- *   wrongful fold costs at most a redundant `createAccessGroup` POST, which PVE refuses loudly
- *   ("group already exists") rather than silently corrupting anything.
- * ⛔ `group.ts`'s `diff` does **NOT** use this — found 2026-09-24, the SAME bug class as the
- *   credential denial fix: folding a TRANSIENT failure (a `PveClusterExhausted`, the encoding bug
- *   above) into "absent" at PLAN TIME is exactly what forced a false `update` with nothing
- *   compared. `diff` calls `readGroupOrFail` directly instead, so a genuine failure there
- *   propagates and fails the whole plan loudly — never silently misreports one row.
+ * ⛔ ONLY `GroupNotFound` MEANS ABSENT. The initial distilled transport swap preserved a
+ *   catch-all fold because PVE reports missing objects as HTTP 500. SDK PR 265 now types that
+ *   measured message, so permission errors, unrelated 500s and exhausted transports propagate
+ *   instead of triggering a speculative create (decision 49 follow-up, 2026-09-24).
+ * ★ `readGroupOrFail` remains the strict path used for an already-confirmed state row. This
+ *   change narrows cold reads/reconcile without changing that existing drift/diff contract.
  */
 export const readGroup = (props: GroupProps) =>
-  readGroupOrFail(props).pipe(Effect.orElseSucceed(() => undefined));
+  readGroupOrFail(props).pipe(Effect.catchTag('GroupNotFound', () => Effect.succeed(undefined)));
 
 /** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */
 export const dropUnreadable = (live: GroupAttributes | Unreadable | undefined) =>

package/src/proxmox/read-failure-propagation.test.ts

@@ -8,9 +8,9 @@
  *     field, never the whole declared props object — the root cause: distilled's `buildRequest`
  *     treats every OTHER key as an "unknown key" and attaches it as a JSON body to what must stay
  *     a bodyless GET, which a stricter fetch client refuses outright.
- *  2. `diff` must never fold a genuine (non-credential-denial) read failure into "absent" — only
- *     `read`/`reconcile` may, where a wrongful fold costs at most a redundant, loudly-refused
- *     create, never a silent wrong write.
+ *  2. `diff` must never fold a genuine (non-credential-denial) read failure into "absent".
+ *     The later typed-absence follow-up extends that protection to cold `read`/`reconcile`:
+ *     only the SDK's resource-specific missing-object tags may trigger a create.
  */
 import { describe, expect, test } from 'bun:test';
 import * as Layer from 'effect/Layer';
@@ -116,8 +116,8 @@ describe('a transient read failure fails the plan loudly, never a silent false u
   });
 
   // ★ A brand-new declaration's own create-from-a-500 path is already covered end to end by
-  //   user.test.ts's `missingAs500` fixture — `readUser`/`readGroup` (used by `reconcile`) kept
-  //   their fold on purpose, exactly so that path stays unaffected by this fix.
+  //   user.test.ts's `missingAs500` fixture. The typed-absence follow-up keeps that path by
+  //   catching `UserNotFound`, while unrelated 500s now propagate on cold reads too.
 });
 
 describe('the same fix, one command over: alchemy drift never reports a transient failure as missing', () => {

package/src/proxmox/storage-wire.ts

@@ -93,18 +93,17 @@ export const readStorageOrFail = (props: StorageProps) =>
   ).pipe(Effect.map((live) => (live === UNREADABLE ? UNREADABLE : attributesOf(live, props))));
 
 /**
- * ⛔ FOLDS A GENUINE READ FAILURE TO `undefined` TOO, AND ONLY `read`/`reconcile` MAY USE IT —
- *   user.ts's `readUser` has the full reasoning. Safe here because a wrongful fold costs at most a
- *   redundant `createStorage` POST, which PVE refuses loudly ("storage ID already exists") rather
- *   than silently corrupting anything.
- * ⛔ `storage.ts`'s `diff` does **NOT** use this — the SAME bug class as the credential denial fix:
- *   folding a TRANSIENT failure into "absent" at PLAN TIME is what forced a false `update` with
- *   nothing compared (the ORIGINAL cries-wolf bug this family shipped with, per unreadable-read.ts's
- *   own header). `diff` calls `readStorageOrFail` directly, so a genuine failure there propagates
- *   and fails the whole plan loudly instead.
+ * ⛔ ONLY `StorageNotFound` MEANS ABSENT. The initial distilled transport swap preserved a
+ *   catch-all fold because PVE reports missing objects as HTTP 500. SDK PR 265 now types that
+ *   measured message, so permission errors, unrelated 500s and exhausted transports propagate
+ *   instead of triggering a speculative create (decision 49 follow-up, 2026-09-24).
+ * ★ `readStorageOrFail` remains the strict path used for an already-confirmed state row. This
+ *   change narrows cold reads/reconcile without changing that existing drift/diff contract.
  */
 export const readStorage = (props: StorageProps) =>
-  readStorageOrFail(props).pipe(Effect.orElseSucceed(() => undefined));
+  readStorageOrFail(props).pipe(
+    Effect.catchTag('StorageNotFound', () => Effect.succeed(undefined)),
+  );
 
 /** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */
 export const dropUnreadable = (live: StorageAttributes | Unreadable | undefined) =>

package/src/proxmox/typed-absence.test.ts

@@ -0,0 +1,146 @@
+/**
+ * A failed read is not evidence of absence. Exercise the real SDK's protocol and errors,
+ * including PVE's resource-specific HTTP 500s, before checking the engine's write boundary.
+ * Fixtures come from the vendor-source evidence in the SDK's generated error declarations.
+ * All HTTP is in-process, and `withoutBao` removes the shell's real credentials.
+ */
+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 * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { engineOver } from '../verify/fake-engine.ts';
+import { readDaemon } from './ceph-daemon-wire.ts';
+import { readFs } from './ceph-fs-distilled.ts';
+import { ProxmoxCephFs, ProxmoxCephFsProvider } from './ceph-fs.ts';
+import { readPoolStatus } from './ceph-pool-wire.ts';
+import { FAKE_TARGET, withoutBao } from './fake-pve.ts';
+import { readGroup } from './group-wire.ts';
+import { readStorage } from './storage-wire.ts';
+import { readUser } from './user-wire.ts';
+import { ProxmoxUser, ProxmoxUserProvider } from './user.ts';
+
+const target = FAKE_TARGET;
+const ceph = { name: 'testfs', node: 'node-b', target };
+const user = { userid: 'test@pve', target };
+
+/** A mutable answer lets a formerly readable filesystem fail exactly when delete runs. */
+const cluster = (initial: () => Response) => {
+  let answer = initial;
+  const writes: string[] = [];
+  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);
+    if (new URL(request.url).pathname.includes('/creds/')) {
+      const data = { secret: 'fake-secret-not-real', token_id: 'hf-test@pve!fake' };
+      return Response.json({ data, lease_duration: 0 });
+    }
+    if (request.method !== 'GET') writes.push(request.method);
+    return answer();
+  };
+  return {
+    answer: (next: () => Response) => {
+      answer = next;
+    },
+    layer: FetchHttpClient.layer.pipe(
+      Layer.provideMerge(
+        Layer.succeed(
+          FetchHttpClient.Fetch,
+          Object.assign(stub, { preconnect: globalThis.fetch.preconnect }) as typeof fetch,
+        ),
+      ),
+    ),
+    writes,
+  };
+};
+
+interface ReadCase {
+  name: string;
+  read: () => Effect.Effect<unknown, unknown, HttpClient.HttpClient>;
+  missing?: string;
+}
+const cases: ReadCase[] = [
+  { name: 'User', read: () => readUser(user), missing: "no such user ('test@pve')\n" },
+  {
+    name: 'Group',
+    read: () => readGroup({ groupid: 'test', target }),
+    missing: "group 'test' does not exist\n",
+  },
+  {
+    name: 'Storage',
+    read: () => readStorage({ storage: 'test', type: 'dir', target }),
+    missing: "storage 'test' does not exist\n",
+  },
+  {
+    name: 'CephPool',
+    read: () => readPoolStatus(ceph),
+    missing: "error with 'osd pool get': mon_cmd failed - unrecognized pool 'testfs'\n",
+  },
+  { name: 'CephFs', read: () => readFs(ceph) },
+  ...(['mon', 'mgr', 'mds'] as const).map((kind) => ({
+    name: `CephDaemon/${kind}`,
+    read: () => readDaemon({ ...ceph, kind }),
+  })),
+];
+const errorResponse = (status: number, message: string) => () =>
+  Response.json({ data: null, message }, { status });
+
+for (const entry of cases) {
+  describe(entry.name, () => {
+    test('only the measured absence signal returns undefined', async () => {
+      const fake = cluster(
+        entry.missing === undefined
+          ? () => Response.json({ data: [] })
+          : errorResponse(500, entry.missing),
+      );
+      await withoutBao(async () => {
+        expect(
+          await Effect.runPromise(entry.read().pipe(Effect.provide(fake.layer))),
+        ).toBeUndefined();
+      });
+      expect(fake.writes).toEqual([]);
+    });
+    for (const [status, tag] of [
+      [401, 'Unauthorized'],
+      [403, 'Forbidden'],
+      [500, 'InternalServerError'],
+    ] as const) {
+      test(`${status} unrelated failure propagates ${tag}`, async () => {
+        const fake = cluster(errorResponse(status, 'unrelated read failure'));
+        await withoutBao(async () => {
+          const error = await Effect.runPromise(
+            entry.read().pipe(Effect.flip, Effect.provide(fake.layer)),
+          );
+          expect(error).toMatchObject({ _tag: tag });
+        });
+        expect(fake.writes).toEqual([]);
+      });
+    }
+  });
+}
+
+test('a cold User adoption fails before any create when its read fails', async () => {
+  const fake = cluster(errorResponse(500, 'unrelated read failure'));
+  await withoutBao(async () => {
+    const engine = engineOver(ProxmoxUserProvider().pipe(Layer.provideMerge(fake.layer)));
+    await expect(engine.deploy(ProxmoxUser('test', user))).rejects.toBeDefined();
+  });
+  expect(fake.writes).toEqual([]);
+});
+
+test('CephFs delete fails on an unreadable index instead of falsely dropping state', async () => {
+  const fake = cluster(() =>
+    Response.json({
+      data: [{ name: ceph.name, data_pool: 'testfs_data', metadata_pool: 'testfs_metadata' }],
+    }),
+  );
+  await withoutBao(async () => {
+    const engine = engineOver(ProxmoxCephFsProvider().pipe(Layer.provideMerge(fake.layer)));
+    const declared = () => ProxmoxCephFs('fs', ceph).pipe(RemovalPolicy.destroy());
+    expect(await engine.deploy(declared())).toEqual({ fs: 'adopted' });
+    fake.answer(errorResponse(403, 'permission denied'));
+    await expect(engine.deploy(Effect.void)).rejects.toBeDefined();
+  });
+  expect(fake.writes).toEqual([]);
+});