@homeflare/alchemy 0.1.0

package/src/proxmox/ceph-pool.ts

@@ -0,0 +1,212 @@
+/**
+ * `Proxmox.CephPool` — a Ceph RADOS pool, declared. The richest Ceph family and the one a stack is
+ * most likely to reach for, because every RBD disk in the cluster lives inside one.
+ *
+ * ⛔ 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`.
+ *
+ * ⛔ 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.
+ *
+ * ⛔ EVERY WRITE HERE IS A FORKED WORKER. createpool, setpool and destroypool each return a UPID
+ *   string, so HTTP 200 means "the task started" — an immediate read-back can see a pool that does
+ *   not exist yet, or values that have not landed. `settle` waits for the cluster to agree.
+ *
+ * ⛔ THE FOUR POOLS ON TB4 INCLUDE CEPH'S OWN, AND NONE OF THEM MAY BE ADOPTED. Measured
+ *   2026-09-13: `.mgr` (application `mgr`, created and owned by the manager daemons),
+ *   `cephfs-tb4_data` and `cephfs-tb4_metadata` (the two halves of the `cephfs-tb4` filesystem —
+ *   destroying either destroys the filesystem), and `cephtb4`, the rbd pool the guests sit on.
+ *   `list` answers empty like every resource in this package, so adoption stays an explicit act;
+ *   the `applications` attribute is reported so that a plan SHOWS which of those a declaration hit.
+ *
+ * ⚠️ DELETING A POOL DESTROYS EVERY OBJECT IN IT AND CEPH DOES NOT ASK TWICE. Neither `force` nor
+ *   `remove_storages` is ever sent, so PVE's refusal while a storage on the pool still lists RBD
+ *   images is left standing. That refusal does NOT cover an RBD user outside storage.cfg.
+ *
+ * ⚠️ PRIVILEGES, AND THE WRITE LANE IS A BIG ASK. Read is `Sys.Audit` OR `Datastore.Audit` on `/`
+ *   (PVEAuditor holds both, so the mount's `read` role covers read, diff and the guard). Create,
+ *   update and delete each check `Sys.Modify` on `/` — there is no `/ceph` object to scope to, so
+ *   granting it also buys datacenter options and every other cluster-wide write. Widen
+ *   deliberately, the way `Pool.Allocate` was widened for `Proxmox.Pool`.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import {
+  type CephPoolAttributes,
+  type CephPoolProps,
+  UNSET,
+  applications,
+  collection,
+  createBody,
+  hint,
+  object,
+  same,
+  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 { bool, int, num, text } from './values.ts';
+
+export type { CephPoolAttributes, CephPoolProps };
+
+export interface ProxmoxCephPool extends Resource<
+  'Proxmox.CephPool',
+  CephPoolProps,
+  CephPoolAttributes,
+  never,
+  PveRequirements
+> {}
+
+/** ★ `retain` by default — a pool holding objects cannot be rebuilt. See the ★ in resource.ts. */
+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,
+  /**
+   * ⛔ 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 TB4'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-tb4_metadata, absent on cephtb4), 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);
+
+export const ProxmoxCephPoolProvider = () =>
+  Provider.effect(
+    ProxmoxCephPool,
+    Effect.succeed(
+      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),
+        /**
+         * ⚠️ 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
+         *   create is destructive against a pool that is already there.
+         */
+        reconcile: Effect.fn(function* ({ news }) {
+          const live = yield* ops.read(news);
+          let upid: string | undefined;
+          if (live === undefined) {
+            yield* confirmAbsent(news, spec.collection(news), object(news));
+            upid = yield* pve<string>(
+              news.target,
+              'provision',
+              'POST',
+              collection(news),
+              createBody(news),
+            );
+          } else {
+            // ⚠️ An empty form is not a write — resource.ts skips one for the same reason.
+            const form = updateBody(news);
+            if (Object.keys(form).length > 0) {
+              upid = yield* pve<string>(news.target, 'provision', 'PUT', object(news), form);
+            }
+          }
+          const after = yield* settle(
+            news,
+            ops.read,
+            (row) => row !== undefined && spec.matches(row, news),
+          );
+          if (after === undefined || !spec.matches(after, news)) {
+            return yield* Effect.die(
+              new Error(
+                `${object(news)}: the write returned no error but the pool still does not match ` +
+                  `the declaration after 60s. PVE answered with task ${upid ?? '(none)'} -- read ` +
+                  'its log with `pvesh get /nodes/<node>/tasks/<upid>/log` to see what Ceph ' +
+                  'refused.',
+              ),
+            );
+          }
+          return after;
+        }),
+        /**
+         * ⛔ THIS DESTROYS EVERY OBJECT IN THE POOL. No `force`, so PVE's own check — it refuses
+         *   while a PVE storage on this pool still lists RBD images — is left standing; and no
+         *   `remove_storages`, so a storage.cfg section pointing here survives and stays somebody's
+         *   to remove deliberately.
+         * ⚠️ AND THE REFUSAL CAN ARRIVE AFTER THE RESPONSE, WHICH IS WHY THIS WAITS. The DELETE
+         *   forks a worker and answers 200 with a UPID, so mons running with
+         *   `mon_allow_pool_delete` false fail once the call has already returned. MEASURED on TB4
+         *   2026-09-13: the config-db value is false while the running mons report true, i.e. it is
+         *   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);
+          if (left !== undefined) {
+            return yield* Effect.die(
+              new Error(
+                `${object(olds)}: the DELETE returned no error but the pool is still there after ` +
+                  '60s. Either a storage on it still holds RBD images, or the mons are running ' +
+                  'with mon_allow_pool_delete false.',
+              ),
+            );
+          }
+        }),
+      }),
+    ),
+  );

package/src/proxmox/client.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Cluster member failover with fake PVE servers — no live hosts, no credentials. The rule for what
+ * counts as pre-send is pinned separately in members.test.ts.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+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 { PveError, pveWith } from './client.ts';
+import type { PveCredential, PveTarget } from './credentials.ts';
+import { orderedMembers, resetLastGoodForTest } from './members.ts';
+
+type ServeOptions = { fetch(request: Request): Response | Promise<Response>; port: number };
+const { Bun } = globalThis as unknown as {
+  Bun: { serve(options: ServeOptions): { port: number; stop(closeActive: boolean): void } };
+};
+
+const CRED: PveCredential = {
+  leaseSeconds: 300,
+  secret: 'not-a-real-secret',
+  tokenId: 'hf-read@pve!fake',
+};
+
+const target = (members: readonly string[]): PveTarget => ({
+  members,
+  mount: 'proxmox-tb4-test',
+  scheme: 'pve',
+});
+
+/** Remap https://member:8006 to http://127.0.0.1:<port> — wired through FetchHttpClient.Fetch. */
+// ⚠️ `typeof fetch` INCLUDES `preconnect` on bun's lib, which no stub implements — the
+//   platform fetch carries a property nothing hand-written does. Object.assign puts it
+//   back so the stub still satisfies the type it is standing in for.
+const remapFetch = (
+  ports: Record<string, number>,
+  underlying: typeof fetch = globalThis.fetch,
+): typeof fetch =>
+  Object.assign(
+    (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+      const href =
+        typeof input === 'string'
+          ? input
+          : input instanceof URL
+            ? input.href
+            : input instanceof Request
+              ? input.url
+              : String(input);
+      const url = new URL(href);
+      const port = ports[url.hostname];
+      if (port !== undefined) {
+        url.protocol = 'http:';
+        url.hostname = '127.0.0.1';
+        url.port = String(port);
+        return underlying(url, init);
+      }
+      return underlying(input, init);
+    },
+    { preconnect: globalThis.fetch.preconnect },
+  );
+
+const layerFor = (ports: Record<string, number>) =>
+  FetchHttpClient.layer.pipe(
+    Layer.provideMerge(Layer.succeed(FetchHttpClient.Fetch, remapFetch(ports))),
+  );
+
+const run = <A, E>(
+  effect: Effect.Effect<A, E, HttpClient.HttpClient>,
+  ports: Record<string, number> = {},
+) => Effect.runPromise(effect.pipe(Effect.provide(layerFor(ports))));
+
+/** A fake member that counts its requests and answers `data`. */
+const counting = (data: unknown) => {
+  let hits = 0;
+  const server = Bun.serve({
+    fetch: () => {
+      hits += 1;
+      return Response.json({ data });
+    },
+    port: 0,
+  });
+  return { hits: () => hits, port: server.port, stop: () => server.stop(true) };
+};
+
+const A = 'pve-a.test';
+const B = 'pve-b.test';
+
+describe('cluster member failover', () => {
+  it('skips an unresolvable first member and answers from the second', async () => {
+    resetLastGoodForTest();
+    const up = counting(['ok']);
+    try {
+      const data = await run(pveWith(target([A, B]), CRED, 'GET', 'pools'), { [B]: up.port });
+      assert.deepEqual(data, ['ok']);
+    } finally {
+      up.stop();
+    }
+  });
+
+  it('does not fail over on HTTP 500 from the first member', async () => {
+    resetLastGoodForTest();
+    const bad = Bun.serve({ fetch: () => new Response('fail', { status: 500 }), port: 0 });
+    const good = counting([]);
+    try {
+      const error = await run(pveWith(target([A, B]), CRED, 'GET', 'pools').pipe(Effect.flip), {
+        [A]: bad.port,
+        [B]: good.port,
+      });
+      assert.ok(error instanceof PveError);
+      assert.equal(error.status, 500);
+      assert.equal(good.hits(), 0);
+    } finally {
+      bad.stop(true);
+      good.stop();
+    }
+  });
+
+  it('tries the last-good member first on the next call', async () => {
+    resetLastGoodForTest();
+    const serverA = counting(['a']);
+    const serverB = counting(['b']);
+    try {
+      const t = target([A, B]);
+      const ports = { [A]: serverA.port, [B]: serverB.port };
+      await run(pveWith(t, CRED, 'GET', 'pools'), ports);
+      assert.equal(serverA.hits(), 1);
+      assert.equal(serverB.hits(), 0);
+      assert.deepEqual(orderedMembers(t), [A, B]);
+      await run(pveWith(t, CRED, 'GET', 'cluster/status'), ports);
+      assert.equal(serverA.hits(), 2);
+      assert.equal(serverB.hits(), 0);
+    } finally {
+      serverA.stop();
+      serverB.stop();
+    }
+  });
+
+  it('does not re-send a write after a transport timeout', async () => {
+    resetLastGoodForTest();
+    const hang = Bun.serve({ fetch: () => new Promise<Response>(() => {}), port: 0 });
+    const backup = counting('UPID:1');
+    try {
+      await run(
+        pveWith(target([A, B]), CRED, 'PUT', 'nodes/n3/network').pipe(
+          Effect.timeout('50 millis'),
+          Effect.flip,
+        ),
+        { [A]: hang.port, [B]: backup.port },
+      );
+      // ⛔ B must never receive the PUT — a post-send timeout is not pre-send failover.
+      assert.equal(backup.hits(), 0);
+    } finally {
+      hang.stop(true);
+      backup.stop();
+    }
+  });
+
+  // ⛔ AND THE OTHER HALF: a write to a member that REFUSES the connection was never sent, so it
+  //   must reach the next member. A real Bun refusal on a closed port, not a hand-built error.
+  it('fails a write over when the first member refuses the connection', async () => {
+    resetLastGoodForTest();
+    const backup = counting('UPID:2');
+    try {
+      // Loopback port 1 is closed: Bun answers ConnectionRefused before a byte is written.
+      const data = await run(pveWith(target([A, B]), CRED, 'PUT', 'nodes/n3/network'), {
+        [A]: 1,
+        [B]: backup.port,
+      });
+      assert.equal(data, 'UPID:2');
+      assert.equal(backup.hits(), 1);
+    } finally {
+      backup.stop();
+    }
+  });
+
+  it('names every member when all are down', async () => {
+    resetLastGoodForTest();
+    const error = await run(pveWith(target([A, B]), CRED, 'GET', 'pools').pipe(Effect.flip));
+    assert.ok(error instanceof PveError);
+    assert.match(error.message, /all members failed/);
+    assert.match(error.message, new RegExp(A));
+    assert.match(error.message, new RegExp(B));
+  });
+});

package/src/proxmox/client.ts

@@ -0,0 +1,240 @@
+/**
+ * One authenticated call to the Proxmox VE API.
+ *
+ * ★ PLAIN `fetch`, NO TLS ESCAPE HATCH, AND THAT IS A MEASURED CHOICE RATHER THAN AN OMISSION.
+ *   Proxmox is usually met with `curl -k` because a fresh install serves its own self-signed
+ *   certificate — I reached for `-k` myself before checking. This cluster serves a real Let's
+ *   Encrypt certificate (`CN=cluster-tb4.example.com`), and strict TLS answers 401, i.e. the
+ *   handshake succeeds and only the credential is missing. So there is no `rejectUnauthorized`
+ *   option here to be left switched on by accident in somebody else's estate.
+ *
+ * ⚠️ EVERY PVE ANSWER IS WRAPPED IN `{"data": ...}`, errors included — a failed call can still be
+ *   HTTP 200 with `{"data": null}`. Unwrapping is not cosmetic; a caller that reads the envelope
+ *   as the payload sees `undefined` and calls it "absent".
+ */
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
+import {
+  type ApiTarget,
+  type PveCredential,
+  type PveRole,
+  type PveTarget,
+  authorization,
+} from './credentials.ts';
+import { leased } from './lease-cache.ts';
+import { executeOnCluster } from './members.ts';
+
+export class PveError extends Error {
+  constructor(
+    readonly status: number,
+    readonly method: string,
+    readonly path: string,
+    detail: string,
+  ) {
+    super(`PVE ${method} ${path} -> ${String(status)}: ${detail}`);
+    this.name = 'PveError';
+  }
+}
+
+const clusterExhausted = (
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE',
+  path: string,
+  attempts: ReadonlyArray<{ member: string; why: string }>,
+) =>
+  new PveError(
+    0,
+    method,
+    path,
+    `all members failed: ${attempts.map((a) => `${a.member} (${a.why})`).join('; ')}`,
+  );
+
+/**
+ * A form body, where a value may be a LIST.
+ *
+ * ⛔ PVE AND PBS SPELL A MULTI-VALUED FIELD DIFFERENTLY, AND THE LIST FORM IS FOR PBS. PBS is Rust:
+ *   its schemas use `type: array` — `delete` on every update endpoint is one — and its urlencoded
+ *   decoder builds that array from REPEATED KEYS (`delete=a&delete=b`). PVE's Perl takes a comma
+ *   string for the same idea, which is what `withClears` in values.ts produces, and for the one
+ *   PVE field that genuinely needs repetition it wants a NUL-joined value instead (see
+ *   notification-target.ts). So: PVE callers pass strings and are unaffected; a PBS caller that
+ *   needs an array passes one and gets repeated keys rather than reaching for PVE's encoding.
+ */
+export type PveForm = Record<string, readonly string[] | string>;
+
+/** ⚠️ `append`, NOT `set`: a repeated key is the point, and `set` would keep only the last. */
+const encode = (form: PveForm): string => {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(form)) {
+    if (typeof value === 'string') params.append(key, value);
+    else for (const item of value) params.append(key, item);
+  }
+  return params.toString();
+};
+
+const buildRequest = (
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE',
+  apiBase: string,
+  path: string,
+  credential: PveCredential,
+  target: ApiTarget,
+  form?: PveForm,
+) => {
+  const url = `${apiBase}/${path}`;
+  /**
+   * ⛔ THE CONTENT TYPE IS AN ARGUMENT TO `bodyText`, NOT AN ENTRY IN THE HEADER MAP, AND GETTING
+   *   THAT WRONG MADE EVERY WRITE IN THIS PACKAGE FAIL.
+   *
+   * 🔴 THE BUG, AND HOW IT HID FOR A WHOLE DAY. The header map DID set
+   *   `application/x-www-form-urlencoded` — and `bodyText(s)` with no second argument sets
+   *   `text/plain` and OVERWRITES it, because it is piped AFTER `setHeaders`. PVE and PBS accept
+   *   ONLY form encoding or JSON and reject everything else outright (measured in
+   *   proxmox-rest-server's `get_request_parameters`), so every create, update and delete this
+   *   package can perform was broken from the day the client was written.
+   *   ⛔ NOTHING CAUGHT IT BECAUSE NOTHING HAD EVER WRITTEN. Ninety-eight resources were adopted
+   *     against the live cluster and every one matched, so `reconcile` never reached a PUT. The
+   *     identical bug in house/forgejo/src/client.ts surfaced the moment a write token existed
+   *     and answered `422 Unsupported Content-Type`; this one is the same line, found by looking.
+   *   ★ A PLAN THAT SAYS `noop` PROVES THE READ PATH AND NOTHING ELSE. That is the lesson worth
+   *     more than the fix.
+   *
+   * ⚠️ PVE TAKES FORM ENCODING, NOT JSON. Sending application/json is accepted and then SILENTLY
+   *   IGNORED on several endpoints, which reads as "the API did nothing" rather than as a wrong
+   *   content type — so the type below is load bearing in both directions.
+   */
+  return HttpClientRequest.make(method)(url).pipe(
+    HttpClientRequest.setHeaders({ Authorization: authorization(credential, target) }),
+    form === undefined
+      ? (self) => self
+      : HttpClientRequest.bodyText(encode(form), 'application/x-www-form-urlencoded'),
+  );
+};
+
+const executeOne = (
+  target: ApiTarget,
+  credential: PveCredential,
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE',
+  path: string,
+  form: PveForm | undefined,
+  apiBase: string,
+) =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const request = buildRequest(method, apiBase, path, credential, target, form);
+    return yield* client
+      .execute(request)
+      .pipe(Effect.mapError((cause) => new PveError(0, method, path, String(cause))));
+  });
+
+const readResponse = <T>(
+  response: {
+    status: number;
+    text: Effect.Effect<string, unknown>;
+    json: Effect.Effect<unknown, unknown>;
+  },
+  method: string,
+  path: string,
+) =>
+  Effect.gen(function* () {
+    /**
+     * ⛔ STATUS FIRST, THEN THE BODY, AND THE BODY IS READ EXACTLY ONCE. `text` and `json` both
+     *   consume the response stream, so asking for both is a bug waiting to happen. A failure is
+     *   read as TEXT because an error body is not reliably JSON — PVE answers HTML for some 5xx —
+     *   and a success is read as JSON by the client rather than by a hand-rolled `JSON.parse`.
+     */
+    if (response.status < 200 || response.status >= 300) {
+      // ⚠️ 401 HERE USUALLY MEANS THE LEASE EXPIRED, NOT THAT THE ROLE IS WRONG. `provision` is a
+      //   300s non-renewable lease; a long reconcile should mint again rather than widen the role.
+      const detail = yield* response.text.pipe(Effect.orElseSucceed(() => ''));
+      return yield* Effect.fail(new PveError(response.status, method, path, detail.slice(0, 300)));
+    }
+    const body = (yield* response.json.pipe(
+      Effect.mapError((cause) => new PveError(0, method, path, String(cause))),
+    )) as { data?: T };
+    return body.data;
+  });
+
+/** A call that already holds a credential. Used when one mint serves several calls. */
+export const pveWith = <T>(
+  target: ApiTarget,
+  credential: PveCredential,
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE',
+  path: string,
+  form?: PveForm,
+) =>
+  Effect.gen(function* () {
+    const response =
+      target.scheme === 'pve'
+        ? yield* executeOnCluster(target, method, path, (apiBase) =>
+            buildRequest(method, apiBase, path, credential, target, form),
+          ).pipe(
+            Effect.mapError((failure) =>
+              failure.tag === 'cluster'
+                ? clusterExhausted(failure.method, failure.path, failure.attempts)
+                : new PveError(0, method, path, String(failure)),
+            ),
+          )
+        : yield* executeOne(target, credential, method, path, form, target.api);
+    return yield* readResponse<T>(response, method, path);
+  });
+
+/**
+ * Like `pveWith`, but returns the full JSON body — for endpoints whose answer lives beside `data`.
+ *
+ * ⚠️ `network-apply-read.ts` is the caller today; the local fetch there should fold into this once
+ *   the envelope shape is stable across both paths.
+ */
+export const pveEnvelopeWith = (
+  target: PveTarget,
+  credential: PveCredential,
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE',
+  path: string,
+) =>
+  Effect.gen(function* () {
+    const response = yield* executeOnCluster(target, method, path, (apiBase) =>
+      buildRequest(method, apiBase, path, credential, target),
+    ).pipe(
+      Effect.mapError((failure) =>
+        failure.tag === 'cluster'
+          ? clusterExhausted(failure.method, failure.path, failure.attempts)
+          : new PveError(0, method, path, String(failure)),
+      ),
+    );
+    if (response.status < 200 || response.status >= 300) {
+      const detail = yield* response.text.pipe(Effect.orElseSucceed(() => ''));
+      return yield* Effect.fail(new PveError(response.status, method, path, detail.slice(0, 300)));
+    }
+    return (yield* response.json.pipe(
+      Effect.mapError((cause) => new PveError(0, method, path, String(cause))),
+    )) as Record<string, unknown>;
+  });
+
+/**
+ * Make one call on a credential for `role`, REUSING a still-valid lease rather than minting one.
+ *
+ * 🔴 IT USED TO MINT PER CALL, AND AT 98 RESOURCES THAT STOPPED BEING FREE. One plan plus deploy
+ *   of the TB4 stack left 760 token entries in `/etc/pve/user.cfg` — read, diff, reconcile and the
+ *   read-back each minted their own, and `/etc/pve` is a replicated cluster filesystem every node
+ *   has to agree on. src/lease-cache.ts carries the measurement and the safety argument.
+ *
+ * ⚠️ `pveWith` IS STILL THERE AND STILL TAKES AN EXPLICIT CREDENTIAL. network-apply.ts needs ONE
+ *   identity across its apply and its task poll — PVE only skips the task-status privilege check
+ *   for the task's OWNER — and it threads a lease through by hand for that. Caching makes that
+ *   property easier to hold, never weaker, but the explicit path stays because that caller is
+ *   reasoning about identity rather than about cost.
+ *
+ * ★ TASK POLL ON A DIFFERENT MEMBER THAN THE APPLY STILL HOLDS: the owner is the token id, not the
+ *   node that received the PUT. Any member serves any task path; the privilege skip is keyed on
+ *   whether the caller IS the task's owner.
+ */
+export const pve = <T>(
+  target: ApiTarget,
+  role: PveRole,
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE',
+  path: string,
+  form?: PveForm,
+) =>
+  Effect.gen(function* () {
+    const credential = yield* leased(target, role);
+    return yield* pveWith<T>(target, credential, method, path, form);
+  });