@homeflare/alchemy 0.37.0 → 0.37.1

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

@@ -6,12 +6,10 @@
  * ★ 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"}`) — a generic failure, not a parsed field like `Proxmox.NodeNetwork`'s 400. That
- *   is why `readPoolStatus` (ceph-pool-wire.ts) folds every failure the same way `ops.read` always
- *   did, and why `confirmAbsent` (ceph-pool-settle.ts) asks a SECOND, different question — does
- *   the index list this name — before a create is allowed to run. `fakePve` (fake-pve.ts) cannot
- *   answer anything but HTTP 200, so this file builds its own stub the way
- *   zfs-pool-read-failure.test.ts does, to answer the measured 500 directly.
+ *   '<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';
@@ -28,10 +26,13 @@ const INDEX = `nodes/${NODE}/ceph/pool`;
 const OBJECT = `${INDEX}/${NAME}`;
 const STATUS = `${OBJECT}/status`;
 
-/** A generic 500 — the measured absence shape, indistinguishable from any other server error. */
+/** 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` },
+    {
+      data: null,
+      message: `error with 'osd pool get': mon_cmd failed - unrecognized pool '${NAME}'\n`,
+    },
     { status: 500 },
   );
 

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

package/src/proxmox/unreadable-read.ts

@@ -18,10 +18,10 @@
  *   on a lane that cannot prove one is needed and (b) never takes the rest of the plan down with
  *   it — the "noop-with-warning" reading of the fix, over the alternative of a typed plan error.
  *
- * ⛔ ONLY THE CREDENTIAL DENIAL IS CAUGHT HERE. Every other read failure (a genuine
- *   `Cause.TimeoutError`, `PveClusterExhausted`, a network error) keeps folding into `undefined`
- *   exactly as it always has — this narrows ONE typed tag out of that fold, via `catchTag`, and
- *   changes nothing else about it. See credential-errors.ts's own ⛔ for why 403 alone qualifies.
+ * ⛔ ONLY THE CREDENTIAL DENIAL IS CAUGHT HERE. Other errors propagate to the caller.
+ *   Legacy callers may still fold them, but the typed-absence follow-up makes User/Group/
+ *   Storage catch only their SDK missing-object tag. Never infer a resource is absent from
+ *   this sentinel. See credential-errors.ts's own ⛔ for why the OpenBao mint's 403 qualifies.
  */
 import * as Effect from 'effect/Effect';
 import type { PveCredentialDenied } from './credential-errors.ts';
@@ -31,9 +31,9 @@ export const UNREADABLE = Symbol('pve-unreadable');
 export type Unreadable = typeof UNREADABLE;
 
 /**
- * Catches ONLY `PveCredentialDenied` and turns it into the sentinel, so a caller that also
- * `.pipe(Effect.orElseSucceed(() => undefined))` for every OTHER failure never conflates a
- * refusal with a genuine absence. Compose this INSIDE that fold, never after it.
+ * Catches ONLY `PveCredentialDenied` and returns the sentinel. Compose this BEFORE the
+ * caller's absence handling so a credential refusal cannot become a genuine absence.
+ * This helper itself classifies neither SDK missing-object tags nor transport failures.
  *
  * ⚠️ `E | PveCredentialDenied` IN, `E` OUT — not a generic `E` narrowed by `Exclude`. `catchTag`
  *   needs the tag to be STATICALLY present in the error union to typecheck at all; a bare

package/src/proxmox/user-wire.ts

@@ -130,18 +130,15 @@ export const readUserOrFail = (props: UserProps) =>
   ).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. A
- *   missing user is a thrown 500 (user.ts's own header), so `reconcile`'s create branch NEEDS
- *   "absent" from a failure to ever run — without this fold, a brand-new account could never be
- *   created. Safe here because a wrongful fold costs at most a redundant `createAccessUser` POST,
- *   which PVE refuses loudly rather than silently corrupting anything.
- * ⛔ `user.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. `diff` calls `readUserOrFail` directly, so a genuine failure there
- *   propagates and fails the whole plan loudly instead.
+ * ⛔ ONLY `UserNotFound` 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).
+ * ★ `readUserOrFail` 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 readUser = (props: UserProps) =>
-  readUserOrFail(props).pipe(Effect.orElseSucceed(() => undefined));
+  readUserOrFail(props).pipe(Effect.catchTag('UserNotFound', () => Effect.succeed(undefined)));
 
 /** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */
 export const dropUnreadable = (live: UserAttributes | Unreadable | undefined) =>

package/src/proxmox/user.ts

@@ -34,11 +34,11 @@
  *     · `Sys.Audit` (or `User.Modify`) for the read, which the `read` role's auditor already has.
  *
  * ⚠️ A MISSING USER IS A 500, NOT A 404 — MEASURED against the live cluster, "no such user
- *   ('x@pve')". distilled turns that into an `InternalServerError`, with no distinct "not found"
- *   tag to catch. `user-wire.ts`'s `readUser` (used by `read`/`reconcile`, where the create
- *   workflow needs "absent" from exactly this failure) still folds it; `readUserOrFail` (used by
- *   `diff` below) does not — see that function's own header for why folding it there was the
- *   cries-wolf bug all over again, just for a genuine PVE quirk instead of a permission denial.
+ *   ('x@pve')". The first SDK migration exposed it as `InternalServerError`, so its create
+ *   workflow needed a catch-all fold. SDK PR #265 now recognizes `UserNotFound`; `readUser`
+ *   catches only that tag, letting other cold-read/reconcile failures propagate. The strict
+ *   `readUserOrFail` path for confirmed rows remains unchanged: its original transient-failure
+ *   fix stopped the cries-wolf update with nothing compared (user-wire.ts).
  *
  * ⚠️ THE WIRE URL FOR THIS FAMILY CHANGED, THOUGH NOTHING A CALLER SEES DID. MEASURED
  *   (user.test.ts): distilled's `{userid}` label substitution percent-encodes it —