@homeflare/distilled-proxmox 0.2.0

package/src/credentials.ts

@@ -0,0 +1,101 @@
+/**
+ * Proxmox VE credentials — hand-written.
+ *
+ * The `Credentials` service resolves `{ tokenId, secret, apiBaseUrl }` per
+ * request; the protocol layer formats the `Authorization:
+ * PVEAPIToken=<tokenId>=<secret>` header from it.
+ *
+ * PVE is self-hosted (a cluster node, not a single-tenant SaaS), so — like
+ * `@distilled.cloud/forgejo` — there is no default API root: the instance
+ * URL is part of the credential. `tokenId` is the FULL
+ * `<user>@<realm>!<tokenid>` string PVE prints when an API token is
+ * created (`pveum user token add …`); `secret` is the value shown exactly
+ * once at creation time.
+ */
+import * as EffectConfig from "effect/Config";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import { ConfigError } from "@distilled.cloud/core/errors";
+
+/** PVE's own API root, relative to the node origin. Always port 8006, always `/api2/json`. */
+export const API_PATH = "/api2/json";
+
+/**
+ * Normalize a node origin (or an already-complete API root) into the API
+ * base URL: trailing slashes dropped, {@link API_PATH} appended exactly
+ * once. Does NOT default the port — `https://pve.example.com:8006` (or a
+ * bare host, which the caller must have already put a scheme+port on) is
+ * expected, matching how the kit's own `PveTarget` is built per node/vip.
+ *
+ * ⛔ THE TRIM IS A LOOP, NEVER `/\/+$/`. That regex backtracks
+ *   polynomially on a long run of trailing `/` (CodeQL `js/polynomial-
+ *   redos`) — caller input, so a real DoS surface, not a hypothetical one.
+ *   Measured the same fix already landed in `@homeflare/distilled-netbox`'s
+ *   identical trim (`taslabs-net/homeflare-kit` PR 184): 0 mismatches
+ *   against the old regex over 13 edge cases and 20,000 random inputs, a
+ *   100,000-slash input in 0.01ms linear.
+ */
+export const normalizeBaseUrl = (baseUrl: string): string => {
+  let end = baseUrl.length;
+  while (end > 0 && baseUrl.charCodeAt(end - 1) === 47 /* "/" */) end--;
+  const trimmed = baseUrl.slice(0, end);
+  return trimmed.endsWith(API_PATH) ? trimmed : `${trimmed}${API_PATH}`;
+};
+
+export interface Config {
+  /** The full `<user>@<realm>!<tokenid>` string, e.g. `root@pam!terraform`. */
+  readonly tokenId: string;
+  readonly secret: Redacted.Redacted<string>;
+  /** Fully-qualified API root, e.g. `https://pve1.example.com:8006/api2/json`. */
+  readonly apiBaseUrl: string;
+}
+
+export class Credentials extends Context.Service<
+  Credentials,
+  Effect.Effect<Config>
+>()("ProxmoxCredentials") {}
+
+const envConfig = EffectConfig.all({
+  tokenId: EffectConfig.String("PROXMOX_TOKEN_ID"),
+  secret: EffectConfig.Redacted("PROXMOX_TOKEN_SECRET"),
+  baseUrl: EffectConfig.String("PROXMOX_URL"),
+});
+
+export const CredentialsFromEnv = Layer.succeed(
+  Credentials,
+  envConfig.pipe(
+    Effect.mapError(
+      () =>
+        new ConfigError({
+          message:
+            "PROXMOX_URL, PROXMOX_TOKEN_ID and PROXMOX_TOKEN_SECRET environment variables are required",
+        }),
+    ),
+    Effect.map(({ tokenId, secret, baseUrl }) => ({
+      tokenId,
+      secret,
+      apiBaseUrl: normalizeBaseUrl(baseUrl),
+    })),
+    Effect.orDie,
+  ),
+);
+
+/** Convenience layer from a plain token and the node origin (or API root). */
+export const credentials = (config: {
+  readonly tokenId: string;
+  readonly secret: string | Redacted.Redacted<string>;
+  readonly baseUrl: string;
+}): Layer.Layer<Credentials> =>
+  Layer.succeed(
+    Credentials,
+    Effect.succeed({
+      tokenId: config.tokenId,
+      secret:
+        typeof config.secret === "string"
+          ? Redacted.make(config.secret)
+          : config.secret,
+      apiBaseUrl: normalizeBaseUrl(config.baseUrl),
+    }),
+  );

package/src/errors.ts

@@ -0,0 +1,152 @@
+/**
+ * Proxmox VE-specific error types.
+ *
+ * Re-exports the common HTTP errors from core and adds PVE's own failure
+ * shapes — see `src/protocol.ts` for how each is recognized on the wire.
+ *
+ * ★ TWO DIFFERENT WIRING STYLES, ON PURPOSE:
+ *   - `ParameterVerificationFailed` (and the plain `BadRequest` fallback
+ *     for a 400 PVE didn't attach an `errors` object to) is GLOBAL
+ *     (`commonErrorClasses`) — recognized generically in `protocol.ts`'s
+ *     `unknownError`, which core's `makeRestProtocol` reaches LAST, after
+ *     per-op `matchTypedError` and the status map both miss (never
+ *     "before per-op matching runs" — 400 is deliberately absent from
+ *     `PROXMOX_STATUS_MAP` so it always lands there). ANY write can fail
+ *     parameter verification, so patching all 680 generated operations
+ *     with the same error shape would be the RFC-6902 equivalent of
+ *     copy-pasting one line 680 times for no additional truth. `BadRequest`
+ *     matters here specifically because it is NOT retryable
+ *     (`Category.withBadRequestError`) where `UnknownProxmoxError`'s
+ *     `Category.withServerError` IS (core's default retry policy treats
+ *     `ServerError` as transient) — see `protocol.ts`'s `unknownError` for
+ *     the incident this prevents: a permanent 400 must never be retried.
+ *   - `ClusterNodeUnreachable` is added via an ACTUAL RFC-6902 patch —
+ *     `patches/nodes/task-polling.json` — to the four `/nodes/{node}/
+ *     tasks/…` operations the vendor schema itself marks `proxyto: "node"`
+ *     (this package's own `src/task.ts` polls one of them). It is NOT
+ *     global: most PVE calls are answered by the node you connected to
+ *     directly and never proxy at all, so declaring a 595 possible on
+ *     every operation would be a claim the schema does not support for
+ *     most of them. Matched purely by status (never a guessed message —
+ *     see the patch file).
+ */
+export {
+  BadGateway,
+  BadRequest,
+  Conflict,
+  ConfigError,
+  Forbidden,
+  GatewayTimeout,
+  InternalServerError,
+  Locked,
+  NotFound,
+  ServiceUnavailable,
+  TooManyRequests,
+  Unauthorized,
+  UnprocessableEntity,
+  HTTP_STATUS_MAP,
+  DEFAULT_ERRORS,
+  API_ERRORS,
+} from "@distilled.cloud/core/errors";
+// `export { X } from "mod"` (above) is a RE-EXPORT ONLY — it creates no local
+// binding for `X`, so `BadRequest` needs its own `import type` to be usable
+// in this file's own `DefaultErrors` union below. Caught by the kit's copy
+// of this package typechecking under `verbatimModuleSyntax`, not by this
+// package's own `tsc -b` — see `docs/distilled-interim.md`'s "prove it in
+// both places" step for why that gap exists at all.
+import type {
+  BadRequest,
+  DefaultErrors as CoreDefaultErrors,
+} from "@distilled.cloud/core/errors";
+
+import * as Schema from "effect/Schema";
+import * as Category from "@distilled.cloud/core/category";
+
+/**
+ * PVE's generic parameter-validation failure: `400` with `{"data":null,
+ * "errors":{"<param>":"<message>", …}, "message":"Parameter verification
+ * failed."}` — measured in `taslabs-net/homeflare-kit`'s
+ * `codegen/README.md` (the incident that package's whole vendor-schema
+ * pipeline exists to prevent): `PVE POST config/verify -> 400: parameter
+ * verification failed - comment: value may only be 128 characters long`.
+ * `errors` carries the per-field messages verbatim.
+ */
+export class ParameterVerificationFailed extends Schema.TaggedError<ParameterVerificationFailed>()(
+  "ParameterVerificationFailed",
+  {
+    message: Schema.String,
+    errors: Schema.Record(Schema.String, Schema.String),
+  },
+).pipe(Category.withBadRequestError) {}
+
+/**
+ * PVE's non-standard status for a cluster-forwarded request whose target
+ * node could not be reached (`pveproxy`/`pvedaemon` proxying — every
+ * endpoint the vendor schema marks `proxyto` can answer this). Standard
+ * HTTP has no 595; this is PVE's own convention, matched purely by status
+ * (never guessed message text — see `protocol.ts`). Treated as transient:
+ * the node the request was forwarded to may simply be mid-reboot or
+ * between cluster-membership changes.
+ */
+export class ClusterNodeUnreachable extends Schema.TaggedError<ClusterNodeUnreachable>()(
+  "ClusterNodeUnreachable",
+  {
+    message: Schema.String,
+  },
+).pipe(Category.withServerError, Category.withRetryable()) {}
+
+/**
+ * Unknown Proxmox error — returned when a failed response's HTTP status has
+ * no mapped error class. Carries the raw body for later cataloging.
+ */
+export class UnknownProxmoxError extends Schema.TaggedError<UnknownProxmoxError>()(
+  "UnknownProxmoxError",
+  {
+    status: Schema.optional(Schema.Number),
+    message: Schema.optional(Schema.String),
+    body: Schema.Unknown,
+  },
+).pipe(Category.withServerError) {}
+
+/** Schema parse error wrapper. */
+export class ProxmoxParseError extends Schema.TaggedError<ProxmoxParseError>()(
+  "ProxmoxParseError",
+  {
+    body: Schema.Unknown,
+    cause: Schema.Unknown,
+  },
+).pipe(Category.withParseError) {}
+
+/**
+ * A polled task ended with an `exitstatus` other than exactly `"OK"` — see
+ * `src/task.ts`. `exitstatus` carries PVE's own failure text verbatim
+ * (e.g. `"job errors"`, `"OK (warnings)"` — the latter is why the compare
+ * is exact-equality against `"OK"`, never a prefix/substring check).
+ */
+export class ProxmoxTaskFailed extends Schema.TaggedError<ProxmoxTaskFailed>()(
+  "ProxmoxTaskFailed",
+  {
+    node: Schema.String,
+    upid: Schema.String,
+    exitstatus: Schema.String,
+  },
+) {}
+
+/**
+ * Errors any Proxmox operation may surface in addition to the per-operation
+ * typed status errors.
+ */
+export type ClientErrors = UnknownProxmoxError | ProxmoxParseError;
+
+/**
+ * Default Proxmox operation errors: the shared HTTP status errors from
+ * core, PVE's global parameter-verification failure, plus the client-level
+ * fallback/decode errors. `ClusterNodeUnreachable` is NOT here — see the
+ * header: it rides only the specific operations `patches/nodes/
+ * task-polling.json` adds it to.
+ */
+export type DefaultErrors =
+  | CoreDefaultErrors
+  | BadRequest
+  | ParameterVerificationFailed
+  | ClientErrors;

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @distilled.cloud/proxmox — Proxmox VE API SDK for Effect.
+ *
+ * `./services` is generated by `scripts/generate.ts` from the Smithy models
+ * in `.generated-specs` (written by `scripts/convert.ts` from PVE's own
+ * `apidata.js`, mirrored under `specs/`). Everything else in this folder is
+ * hand-written.
+ *
+ * One module per PVE top-level path segment — `access`, `cluster`,
+ * `nodes`, `pools`, `storage`, `version` — the same split the vendor's own
+ * api-viewer uses.
+ *
+ * @example
+ * ```ts
+ * import * as Proxmox from "@distilled.cloud/proxmox";
+ *
+ * const status = yield* Proxmox.Services.nodes.getNodeTaskStatus({
+ *   node: "pve1",
+ *   upid: "UPID:pve1:00001234:...",
+ * });
+ * ```
+ */
+export * from "./credentials.ts";
+export * from "./errors.ts";
+export * as T from "./traits.ts";
+export {
+  ProxmoxProtocol,
+  type ProxmoxOpError,
+  type ProxmoxOpContext,
+} from "./protocol.ts";
+export * as Retry from "./retry.ts";
+export * as Services from "./services/index.ts";
+export { awaitTask, type TaskRef, type AwaitTaskOptions } from "./task.ts";

package/src/protocol.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Proves the exact bug an adversarial review of this package caught and
+ * this file exists to stop recurring: a bare PVE 400 (no `errors` object)
+ * must decode to the non-retryable `BadRequest`, never the
+ * `Category.withServerError`-tagged `UnknownProxmoxError` — core's default
+ * retry policy treats `ServerError` as transient, so the wrong class would
+ * have silently retried a permanent, caller-caused failure several times
+ * before surfacing it. See `protocol.ts`'s `unknownError` and
+ * `errors.ts`'s module header for the full account.
+ */
+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 { credentials } from "./credentials.ts";
+import {
+  BadRequest,
+  ParameterVerificationFailed,
+  UnknownProxmoxError,
+} from "./errors.ts";
+import * as Retry from "./retry.ts";
+import { getNodeTime } from "./services/nodes.ts";
+
+const testCredentials = credentials({
+  tokenId: "root@pam!test",
+  secret: "test-secret",
+  baseUrl: "https://pve.test:8006",
+});
+
+const fakePve = (status: number, body: unknown) =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) =>
+      Effect.sync(() =>
+        HttpClientResponse.fromWeb(
+          request,
+          new Response(JSON.stringify(body), { status }),
+        ),
+      ),
+    ),
+  );
+
+const call = (status: number, body: unknown) =>
+  Effect.runPromise(
+    getNodeTime({ node: "pve1" }).pipe(
+      Retry.none,
+      Effect.provide(Layer.mergeAll(fakePve(status, body), testCredentials)),
+      Effect.flip,
+    ),
+  );
+
+describe("protocol.ts error decoding", () => {
+  test("a bare 400 (no `errors` object) is BadRequest, never UnknownProxmoxError", async () => {
+    const error = await call(400, { data: null, message: "invalid parameter" });
+    expect(error).toBeInstanceOf(BadRequest);
+    expect(error).not.toBeInstanceOf(UnknownProxmoxError);
+    expect(error).toMatchObject({ message: "invalid parameter" });
+  });
+
+  test("a 400 with an `errors` object is ParameterVerificationFailed, carrying the per-field messages", async () => {
+    const error = await call(400, {
+      data: null,
+      message: "Parameter verification failed.",
+      errors: { comment: "value may only be 128 characters long" },
+    });
+    expect(error).toBeInstanceOf(ParameterVerificationFailed);
+    expect(error).toMatchObject({
+      message: "Parameter verification failed.",
+      errors: { comment: "value may only be 128 characters long" },
+    });
+  });
+
+  // 418 is neither in PROXMOX_STATUS_MAP nor >= 500 (the unmapped-5xx
+  // fallback in core's makeRestProtocol answers a bare `InternalServerError`
+  // for those before `unknownError` is ever reached — see that decode step).
+  test("a genuinely unmapped, non-5xx status still falls back to UnknownProxmoxError", async () => {
+    const error = await call(418, { data: null, message: "weird" });
+    expect(error).toBeInstanceOf(UnknownProxmoxError);
+  });
+
+  test('the {"data": ...} envelope is unwrapped before decode', async () => {
+    const result = await Effect.runPromise(
+      getNodeTime({ node: "pve1" }).pipe(
+        Effect.provide(
+          Layer.mergeAll(
+            fakePve(200, {
+              data: {
+                time: 1700000000,
+                timezone: "UTC",
+                localtime: 1700000000,
+              },
+            }),
+            testCredentials,
+          ),
+        ),
+      ),
+    );
+    expect(result).toMatchObject({ time: 1700000000, timezone: "UTC" });
+  });
+});

package/src/protocol.ts

@@ -0,0 +1,204 @@
+/**
+ * ProxmoxProtocol — the shared bearer-REST protocol instantiated for
+ * Proxmox VE. Hand-written; `@distilled.cloud/core` is never changed for a
+ * provider's own quirks — they all live here.
+ *
+ * ## The envelope
+ *
+ * Every PVE response — success AND failure — is wrapped `{"data": …}`
+ * (measured, and already relied on by `packages/alchemy/src/proxmox/
+ * client.ts` in `taslabs-net/homeflare-kit`: "EVERY PVE ANSWER IS WRAPPED
+ * IN `{"data": ...}`, errors included — a failed call can still be HTTP
+ * 200 with `{"data": null}`"). `transformResponse` below unwraps it before
+ * `core/protocol-rest`'s schema-driven decode ever sees a payload, so a
+ * generated operation's output type is the PAYLOAD, not the envelope.
+ *
+ * ## Authentication
+ *
+ * The API-token scheme: `Authorization: PVEAPIToken=<user>@<realm>!
+ * <tokenid>=<secret>` (no `Bearer`, and the token id is embedded in the
+ * header value itself, not just the credential).
+ *
+ * ## THE THREE 200-TRAPS
+ *
+ * (a) **Async POST/PUT/DELETE answer 200 with a UPID and can fail later.**
+ *     PVE hands back a bare task id string (`"UPID:node:...);"`) for any
+ *     long-running action — a VM start, a backup, a storage scan — and the
+ *     200 means "the task was QUEUED", not "the task succeeded". Handled
+ *     with real code: `src/task.ts`'s `awaitTask`, which polls
+ *     `GetNodeTaskStatus` (this package's own generated operation) until
+ *     `exitstatus` is present, then fails with the typed
+ *     `ProxmoxTaskFailed` unless it is EXACTLY `"OK"` — PVE also answers
+ *     `"OK (warnings)"`, which is not a bare-prefix match on purpose (see
+ *     that file).
+ *
+ * (b) **Some PUTs answer 200 `{"data":null}` even when nothing changed.**
+ *     PVE's update handlers commonly return `null` unconditionally on
+ *     success, whether or not any field actually differed from what was
+ *     already stored — there is no wire signal that distinguishes "applied"
+ *     from "already exactly this". THIS IS NOT SOMETHING A PROTOCOL LAYER
+ *     CAN DETECT OR FIX — it is a statement about business semantics no
+ *     amount of parsing recovers. Documented here so it travels with the
+ *     protocol rather than being rediscovered per resource: an update
+ *     operation's caller (a future kit `Resource`) MUST read the value back
+ *     with a follow-up GET rather than trust a 200 as proof anything
+ *     changed.
+ *
+ * (c) **Permission-filtered lists return 200 + `[]` instead of 403.** A
+ *     list endpoint called with a token that has no visibility into any
+ *     member of the collection answers an EMPTY array, not a permission
+ *     error — indistinguishable, on the wire, from "the collection is
+ *     genuinely empty". Also undetectable here for the same reason as (b):
+ *     documented so a caller treats an empty list from a narrowly-scoped
+ *     token as "unknown", never as "confirmed absent".
+ *
+ * ## Self-signed TLS
+ *
+ * A fresh PVE node serves its own self-signed certificate. This is
+ * EXPLICITLY NOT handled here, or anywhere in this package: the custom
+ * CA / certificate trust decision belongs to the `HttpClient.HttpClient`
+ * layer the CALLER provides (Effect's platform HTTP client layers take a
+ * `NodeHttpClient.layerConfig` / custom `Agent` for this), never to a
+ * distilled protocol module, which only ever builds and decodes requests
+ * against whatever transport it is handed. Wiring a custom CA at the
+ * `HttpClient` layer is a caller decision to prototype and own.
+ */
+import * as Effect from "effect/Effect";
+import type * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type * as HttpClientError from "effect/unstable/http/HttpClientError";
+import type * as API from "@distilled.cloud/core/api";
+import {
+  BadRequest,
+  HTTP_STATUS_MAP,
+  type ConfigError,
+} from "@distilled.cloud/core/errors";
+import {
+  makeRestProtocol,
+  type RestErrorEnvelope,
+} from "@distilled.cloud/core/protocol-rest";
+import { Credentials, type Config } from "./credentials.ts";
+import {
+  ParameterVerificationFailed,
+  UnknownProxmoxError,
+  type DefaultErrors,
+} from "./errors.ts";
+
+/**
+ * Error channel shared by every generated Proxmox operation. Generated
+ * service files annotate operations with `API.OperationMethod<I, O,
+ * ProxmoxOpError, ProxmoxOpContext>` explicitly so the compiler never
+ * infers these back out of the schema generics.
+ */
+export type ProxmoxOpError =
+  | DefaultErrors
+  | ConfigError
+  | HttpClientError.HttpClientError;
+
+/** Context (requirements) shared by every generated Proxmox operation. */
+export type ProxmoxOpContext = Credentials | HttpClient.HttpClient;
+
+/**
+ * PVE's failure envelope is `{"data": null, "message": "...", "errors"?:
+ * {…}}` — `message` is the only field every failure carries (the `errors`
+ * sub-object, PVE's parameter-verification detail, is read straight from
+ * the body in `unknownError` below, not here — `RestErrorEnvelope` has no
+ * room for a nested object and `errorEnvelope` only feeds per-op typed-error
+ * MATCHING, never the classes themselves).
+ */
+const errorEnvelope = (body: unknown): RestErrorEnvelope | undefined => {
+  if (body === null || typeof body !== "object") return undefined;
+  const b = body as Record<string, unknown>;
+  return { message: typeof b.message === "string" ? b.message : undefined };
+};
+
+/**
+ * `HTTP_STATUS_MAP` minus 400: PVE's 400 is not one shape (a generic
+ * "bad request" some other providers mean by it) — it is SPECIFICALLY the
+ * parameter-verification failure, and answering it with the generic
+ * `BadRequest` would throw away the per-field `errors` object the vendor
+ * always attaches. Dropping the entry here is what lets a 400 fall through
+ * to `unknownError`, which reads that object.
+ */
+const PROXMOX_STATUS_MAP: Record<number, new (args: any) => unknown> = {
+  ...HTTP_STATUS_MAP,
+};
+delete (PROXMOX_STATUS_MAP as Record<number, unknown>)[400];
+
+export const ProxmoxProtocol: Layer.Layer<API.Protocol> =
+  makeRestProtocol<Config>({
+    // Resolved on the CALLING fiber per request (the layer is memoized per
+    // process); the Credentials service holds an effect, so a token rotated
+    // between calls is picked up without rebuilding the layer.
+    credentials: Effect.gen(function* () {
+      const resolve = yield* Credentials;
+      return yield* resolve;
+    }),
+    baseUrl: (creds) => creds.apiBaseUrl,
+    headers: (creds) => ({
+      Authorization: `PVEAPIToken=${creds.tokenId}=${Redacted.value(creds.secret)}`,
+      Accept: "application/json",
+    }),
+    errorEnvelope,
+    statusMap: PROXMOX_STATUS_MAP,
+    // Unwrap PVE's `{"data": …}` envelope BEFORE the schema-driven decode —
+    // see the module header. `data` is `null`/absent for a Unit-output
+    // operation; `?? {}` is core's own convention for "no body".
+    transformResponse: (body) => {
+      if (
+        body !== null &&
+        typeof body === "object" &&
+        "data" in (body as Record<string, unknown>)
+      ) {
+        return (body as Record<string, unknown>).data ?? {};
+      }
+      return body;
+    },
+    // Reached for a 400 (see PROXMOX_STATUS_MAP above), an operation-declared
+    // typed error that didn't match (`ClusterNodeUnreachable`'s 595 — see
+    // `patches/nodes/task-polling.json` — when the status is right but the
+    // matcher's other fields aren't), or a status with no core mapping at
+    // all. `body` is the FULL parsed failure envelope (unlike
+    // `errorEnvelope`, which only ever sees `{code?, message?}`), so this is
+    // where PVE's per-field `errors` object is actually read.
+    //
+    // ⛔ A BARE 400 WITHOUT THE `errors` OBJECT MUST NOT FALL INTO
+    //   `UnknownProxmoxError`. That class is `.pipe(Category.withServerError)`
+    //   (matching every other provider's Unknown*Error fallback here), and
+    //   `ServerError` is one of the categories `core/category.ts`'s
+    //   `isTransientError` retries AUTOMATICALLY — with no caller opt-in —
+    //   via `makeDefault` (`core/api.ts`: `Option.isSome(opt) ? opt.value :
+    //   makeDefault` when no retry policy is in context). A malformed
+    //   request is permanent; retrying it up to `makeDefault`'s cap before
+    //   finally surfacing would silently multiply every truly-bad call by
+    //   several attempts and several seconds of backoff for no chance of a
+    //   different outcome. `BadRequest` (`Category.withBadRequestError`,
+    //   not retryable) is the honest answer for "PVE said 400 and gave no
+    //   further structure" — `UnknownProxmoxError` stays for statuses this
+    //   package genuinely has no mapping for at all (never 400).
+    unknownError: ({ status, message, body }) => {
+      const b =
+        body !== null && typeof body === "object"
+          ? (body as Record<string, unknown>)
+          : undefined;
+      const fieldErrors = b?.errors;
+      if (status === 400) {
+        if (
+          fieldErrors !== null &&
+          typeof fieldErrors === "object" &&
+          !Array.isArray(fieldErrors)
+        ) {
+          const errors: Record<string, string> = {};
+          for (const [k, v] of Object.entries(
+            fieldErrors as Record<string, unknown>,
+          )) {
+            if (typeof v === "string") errors[k] = v;
+          }
+          return new ParameterVerificationFailed({ message, errors });
+        }
+        return new BadRequest({ message });
+      }
+      return new UnknownProxmoxError({ status, message, body });
+    },
+  });

package/src/retry.ts

@@ -0,0 +1,74 @@
+/**
+ * Proxmox retry surface — a veneer over `@distilled.cloud/core/retry`.
+ *
+ * The `Retry` service tag is threaded into every generated operation via
+ * `API.make({ retry: Retry })`, so a caller-installed policy applies to all
+ * Proxmox calls below it and core's `makeDefault` is the fallback when none
+ * is provided.
+ *
+ * @example
+ * ```ts
+ * import * as Proxmox from "@distilled.cloud/proxmox";
+ *
+ * myEffect.pipe(Proxmox.Retry.transient);
+ * ```
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Retries from "@distilled.cloud/core/retry";
+
+export type Options = Retries.Options;
+export type Factory = Retries.Factory;
+export type Policy = Retries.Policy;
+
+/** Context tag for configuring retry behavior of Proxmox API calls. */
+export class Retry extends Context.Service<Retry, Policy>()("ProxmoxRetry") {}
+
+/** Provides a custom retry policy to every Proxmox API call below it. */
+export const policy: {
+  (
+    options: Options,
+  ): <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E, Exclude<R, Retry>>;
+  (
+    factory: Factory,
+  ): <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E, Exclude<R, Retry>>;
+} = (optionsOrFactory: Options | Factory) =>
+  Effect.provide(Layer.succeed(Retry, optionsOrFactory));
+
+/** Disables all automatic retries. */
+export const none: <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+) => Effect.Effect<A, E, Exclude<R, Retry>> = Effect.provide(
+  Layer.succeed(Retry, { while: () => false }),
+);
+
+/**
+ * The default retry policy (core's): transient/throttling/retryable errors,
+ * capped exponential backoff with jitter, server `retryAfter` hints honored
+ * with precedence.
+ */
+export const makeDefault: Factory = Retries.makeDefault;
+
+export const jittered = Retries.jittered;
+export const capped = Retries.capped;
+
+/** Retry options that retry all throttling errors indefinitely. */
+export const throttlingOptions: Options = Retries.throttlingOptions;
+
+/** Retries all throttling errors indefinitely (honoring server hints). */
+export const throttling: <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+) => Effect.Effect<A, E, Exclude<R, Retry>> = policy(Retries.throttlingFactory);
+
+/** Retry options that retry all transient errors indefinitely. */
+export const transientOptions: Options = Retries.transientOptions;
+
+/** Retries all transient errors indefinitely (honoring server hints). */
+export const transient: <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+) => Effect.Effect<A, E, Exclude<R, Retry>> = policy(Retries.transientFactory);