@homeflare/alchemy 0.37.0 → 0.37.2

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 —