@homeflare/alchemy 0.36.0 → 0.37.1

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 —

package/src/proxmox/distilled-task-await.test.ts

@@ -1,124 +0,0 @@
-/**
- * Exercises `@distilled.cloud/proxmox`'s `awaitTask` (the async-task
- * 200-trap — see that package's `src/protocol.ts` header) against a FAKE
- * `HttpClient`, no live PVE node involved.
- *
- * ⚠️ THIS PACKAGE IS CONSUMED VIA THE INTERIM-PACKAGE ALIAS
- *   (`packages/alchemy/package.json`'s `dependencies`:
- *   `"@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.2.0"`)
- *   — see `packages/alchemy/docs/distilled-interim.md`. Nothing in
- *   `packages/alchemy/src/proxmox/*` (the existing 98-resource family) is
- *   touched or migrated onto it here; this file is standalone proof the
- *   package works end to end, ahead of migrating any hand-written resource
- *   onto it (a later PR).
- */
-import { describe, expect, test } from 'bun:test';
-import * as Effect from 'effect/Effect';
-import * as Layer from 'effect/Layer';
-import * as HttpClient from 'effect/unstable/http/HttpClient';
-import * as HttpClientResponse from 'effect/unstable/http/HttpClientResponse';
-import * as Proxmox from '@distilled.cloud/proxmox';
-
-const credentials = Proxmox.credentials({
-  tokenId: 'root@pam!test',
-  secret: 'test-secret',
-  baseUrl: 'https://pve.test:8006',
-});
-
-/** A fake PVE that answers `running` (no `exitstatus`) `pendingPolls` times, then `finalBody`. */
-const fakePve = (pendingPolls: number, finalBody: Record<string, unknown>) => {
-  let calls = 0;
-  return Layer.succeed(
-    HttpClient.HttpClient,
-    HttpClient.make((request) =>
-      Effect.sync(() => {
-        calls++;
-        const body =
-          calls <= pendingPolls
-            ? {
-                status: 'running',
-                id: 'qmstart',
-                node: 'pve1',
-                pid: 100,
-                pstart: 1,
-                starttime: 1,
-                type: 'qmstart',
-                upid: 'UPID:pve1:...',
-                user: 'root@pam',
-              }
-            : finalBody;
-        return HttpClientResponse.fromWeb(
-          request,
-          new Response(JSON.stringify({ data: body }), { status: 200 }),
-        );
-      }),
-    ),
-  );
-};
-
-const runAwaitTask = (pendingPolls: number, finalBody: Record<string, unknown>) =>
-  Effect.runPromise(
-    Proxmox.awaitTask(
-      { node: 'pve1', upid: 'UPID:pve1:00000001:00000001:00000001:qmstart:100:root@pam:' },
-      { pollInterval: '5 millis' },
-    ).pipe(Effect.provide(Layer.mergeAll(fakePve(pendingPolls, finalBody), credentials))),
-  );
-
-const OK_STATUS = {
-  status: 'stopped',
-  exitstatus: 'OK',
-  id: 'qmstart',
-  node: 'pve1',
-  pid: 100,
-  pstart: 1,
-  starttime: 1,
-  type: 'qmstart',
-  upid: 'UPID:pve1:...',
-  user: 'root@pam',
-};
-
-describe("awaitTask (against a fake PVE, per protocol.ts's async-task trap)", () => {
-  test("resolves once exitstatus is exactly OK, after polling through 'running'", async () => {
-    const result = await runAwaitTask(2, OK_STATUS);
-    expect(result.exitstatus).toBe('OK');
-    expect(result.status).toBe('stopped');
-  });
-
-  test('resolves immediately when the task is already done on the first poll', async () => {
-    const result = await runAwaitTask(0, OK_STATUS);
-    expect(result.exitstatus).toBe('OK');
-  });
-
-  test('fails with ProxmoxTaskFailed for any exitstatus other than exactly OK', async () => {
-    const failed = await Effect.runPromise(
-      Proxmox.awaitTask(
-        { node: 'pve1', upid: 'UPID:pve1:00000001:00000001:00000001:qmstart:100:root@pam:' },
-        { pollInterval: '5 millis' },
-      ).pipe(
-        Effect.provide(
-          Layer.mergeAll(fakePve(0, { ...OK_STATUS, exitstatus: 'job errors' }), credentials),
-        ),
-        Effect.flip,
-      ),
-    );
-    expect(failed).toBeInstanceOf(Proxmox.ProxmoxTaskFailed);
-    expect(failed).toMatchObject({ node: 'pve1', exitstatus: 'job errors' });
-  });
-
-  // ⛔ "OK (warnings)" is NOT a success — see task.ts's exact-equality note.
-  test("fails (does not swallow) 'OK (warnings)'", async () => {
-    const failed = await Effect.runPromise(
-      Proxmox.awaitTask(
-        { node: 'pve1', upid: 'UPID:pve1:00000001:00000001:00000001:qmstart:100:root@pam:' },
-        { pollInterval: '5 millis' },
-      ).pipe(
-        Effect.provide(
-          Layer.mergeAll(fakePve(0, { ...OK_STATUS, exitstatus: 'OK (warnings)' }), credentials),
-        ),
-        Effect.flip,
-      ),
-    );
-    expect(failed).toBeInstanceOf(Proxmox.ProxmoxTaskFailed);
-    expect(failed).toMatchObject({ exitstatus: 'OK (warnings)' });
-  });
-});