@homeflare/alchemy 0.37.2 → 0.37.3

package/src/proxmox/pbs-datastore-form.ts

@@ -1,42 +1,41 @@
 /**
- * A PBS datastore on the wire: the transport that reaches PBS, the form it wants, and the coercion
- * back to something comparable.
+ * A PBS datastore's pure vendor forms and coercion back to comparable state. SDK transport is
+ * in pbs-datastore-wire.ts; lifecycle behavior is in pbs-datastore-lifecycle.ts.
  *
  * ★ SPLIT OUT OF pbs-datastore.ts FOR THE 250-LINE CAP, the seam notification-target-form.ts uses:
- *   this file is everything that touches PBS's encoding, and the resource file is the declaration
- *   and the five handlers. The `import type` back is erased, so it is a cycle on paper only.
+ *   this file originally held PBS encoding beside forms, while the resource held its declaration
+ *   and five handlers. The `import type` back is erased, so it is a cycle on paper only.
  *
- * ⛔ THIS FILE IS OVER THE 250-LINE CAP AND THE EXTRACTION IS NAMED RATHER THAN FUDGED. `PbsTarget`,
+ * ⛔ HISTORICAL EXTRACTION NOTE: THIS FILE EXCEEDED THE 250-LINE CAP IN THE ORIGINAL DRAFT. `PbsTarget`,
  *   `PbsRole`, `PbsError`, `pbsAuthorization`, `PveForm`, `encode`, `pbs` and `settle` — about 150
  *   lines — are a PBS CLIENT, not a datastore form, and belong in `pbs-client.ts`. Lifting them
  *   leaves this file near 200 and costs nothing but a move. It was not done here only because the
  *   family was commissioned as a two-file split; ceph-pool is the in-package precedent for three
  *   (ceph-pool.ts + ceph-pool-form.ts + ceph-pool-settle.ts, 532 lines for one family). Everything
  *   in that list is also what Pbs.SyncJob, Pbs.PruneJob and Pbs.Remote will each need unchanged,
- *   so the second PBS family forces the move anyway. ⛔ DO NOT MEET THE CAP BY CUTTING COMMENTS.
+ *   so the second PBS family forced that move. The SDK and focused siblings now own these seams.
+ *   ⛔ DO NOT MEET THE CAP BY CUTTING COMMENTS.
  */
-import * as Effect from 'effect/Effect';
-import { type PveForm, pve } from './client.ts';
 import type { PbsTarget as ApiPbsTarget } from './credentials.ts';
 import type { PbsDatastoreProps } from './pbs-datastore.ts';
 import { bool, flag, int, propertyString, text } from './values.ts';
 
 /**
- * ★ PBS REUSES THE PVE CLIENT RATHER THAN OWNING ONE. An earlier draft of this file carried its
- *   own `PbsTarget`, `PbsError`, `pbsAuthorization`, form encoder and `pve()` — a near-copy of
- *   client.ts differing in one header. They are gone: `PveTarget` now carries a `scheme`, and
- *   `authorization()` spells the header `PBSAPIToken=<id>:<secret>` when it is `'pbs'`. The
- *   insight that survived is the FORM TYPE — PBS decodes a multi-valued field from repeated keys
- *   where PVE wants a comma string — and that now lives on `PveForm` in client.ts, so both
- *   products share one encoder and neither can reach for the other's convention by accident.
+ * ★ PBS ORIGINALLY REUSED THE PVE CLIENT RATHER THAN OWNING ANOTHER. An earlier draft carried
+ *   its own `PbsTarget`, `PbsError`, `pbsAuthorization`, form encoder and `pve()` — a near-copy of
+ *   client.ts differing in one header. The shared target's `scheme` replaced that copy. This
+ *   family now uses the distilled PBS SDK through `distilled-pbs.ts`, retaining the same leased
+ *   credentials and PBS authorization scheme. The important encoding distinction survives:
+ *   PBS decodes a multi-valued field from repeated keys where PVE wants a comma string. The SDK
+ *   protocol owns that behavior; these pure forms describe only this datastore's scalar fields.
  *
  * 🔴 THIS ALIAS SAID `= PveTarget` AND IT WAS WRONG — Pbs.Datastore REQUIRED A PVE TARGET. When
  *   `credentials.ts` grew a real `PbsTarget` with `scheme: 'pbs'`, this line was left pointing at
  *   the PVE type, which pins `scheme: 'pve'`. So the one family that most needs the discriminant
  *   was the one family that refused the correct value: declaring a datastore against the PBS host
  *   failed to compile with `Type '"pbs"' is not assignable to type 'Input<"pve">'`, and passing a
- *   PVE target compiled fine and would have 401'd every call — which `read` folds into "absent",
- *   so the plan would say CREATE for a datastore holding the estate's backups.
+ *   PVE target compiled fine and would have 401'd every call — which the old `read` folded into
+ *   "absent", so the plan would say CREATE for a datastore holding the estate's backups.
  *   ⛔ IT SURVIVED BECAUSE NOTHING EVER DECLARED ONE. The provider was registered in
  *   alchemy.run.ts from the day it was written and `pveHandlers`' `list` answers empty, so
  *   registration exercises no call site at all. Three sibling families import `PbsTarget` from
@@ -183,7 +182,7 @@ const mutable = (props: PbsDatastoreProps): Record<string, string> => ({
  *   slot, not of the declaration; one that could re-point it is one that can send backups to the
  *   wrong drive.
  */
-export const createForm = (props: PbsDatastoreProps): PveForm => ({
+export const createForm = (props: PbsDatastoreProps): Record<string, string> => ({
   ...mutable(props),
   name: props.name,
   path: props.path,
@@ -213,36 +212,6 @@ export const createForm = (props: PbsDatastoreProps): PveForm => ({
  *     element that fails the enum check. `PveForm` and `encode` already carry arrays for exactly
  *     this. ⚠️ REASONED FROM THE PUBLISHED SCHEMA, NOT PROVEN ON A WIRE.
  */
-export const updateForm = (props: PbsDatastoreProps): PveForm => mutable(props);
+export const updateForm = (props: PbsDatastoreProps): Record<string, string> => mutable(props);
 
 export const object = (props: PbsDatastoreProps) => `config/datastore/${props.name}`;
-
-/**
- * The live datastore, or undefined.
- *
- * ⛔ `name` IS THE PRESENCE TEST, NOT THE STATUS CODE — PBS does not answer 404 for a section that
- *   is missing from `datastore.cfg`, it answers a generic error, so there is no code to key off.
- * ⛔ A MISSING READ PRIVILEGE THEREFORE LOOKS EXACTLY LIKE ABSENCE, because the fold below cannot
- *   tell them apart. The signature is a plan that says CREATE followed by PBS answering
- *   "datastore '<name>' already exists." — that pair means Datastore.Audit, not a missing
- *   datastore. It is loud and non-destructive, which is the only reason the fold is tolerable here;
- *   see the ⛔ on `readRole` in resource.ts for the PVE families where it is not.
- * ⛔ ON THE DELETE PATH THE SAME FOLD IS A LIE, AND THIS IS THE ONE HAZARD IN THIS FAMILY I COULD
- *   NOT CLOSE. `delete` settles by polling this read until it answers `undefined` — and a `read`
- *   role that lacks `Datastore.Audit` answers `undefined` from the very first poll, so EVERY delete
- *   would report success while the datastore stood. Worse, the two lanes are different leases: the
- *   DELETE goes out under `provision` and may genuinely fail, and this read cannot see that it did.
- *   ★ THE SHAPE OF THE FIX IS ALREADY IN THIS PACKAGE: `confirmAbsent` in ceph-pool-settle.ts asks
- *     a SECOND, DIFFERENT question — does the collection LIST this object? — and lets a failure
- *     PROPAGATE rather than folding it, so "I could not ask" fails the deploy instead of passing
- *     it. Add the same over `GET /config/datastore` before anyone relies on a reported deletion.
- *   ⚠️ UNTIL THEN THE PRECONDITION IS EXPLICIT: the `read` role MUST hold `Datastore.Audit` on the
- *     datastore, or this provider cannot tell a deletion from a refusal.
- */
-export const readOne = (props: PbsDatastoreProps) =>
-  pve<Record<string, unknown>>(props.target, 'read', 'GET', object(props)).pipe(
-    Effect.map((live) =>
-      live === undefined || typeof live['name'] !== 'string' ? undefined : attributes(live, props),
-    ),
-    Effect.orElseSucceed(() => undefined),
-  );

package/src/proxmox/pbs-datastore-guard.ts

@@ -76,13 +76,15 @@ export const guardBackend = (live: PbsDatastoreAttributes, props: PbsDatastorePr
 /**
  * Wait for PBS to finish, then answer the last thing it said.
  *
- * ⛔ IT EXISTS BECAUSE A PBS CREATE IS A FORKED WORKER AND THE CONFIG SECTION IS WRITTEN LAST.
+ * ⛔ THE ORIGINAL CREATE-WORKER ASSUMPTION BELOW WAS REASONED, NOT MEASURED.
  *   `POST /config/datastore` answers with a UPID while a `create-datastore` task builds the chunk
  *   store's 65536 directories; only when that finishes does the section reach `datastore.cfg`. An
  *   immediate read-back therefore sees a datastore that is not there yet, and the factory's "the
  *   write returned no error but the object is still absent" would fire on a create going perfectly.
  *   The DELETE forks a worker too. ⚠️ DOCUMENTED FROM THE PUBLISHED SCHEMA, NOT MEASURED — I hold
- *   no PBS token. If a create turns out to be synchronous, the first poll simply succeeds.
+ *   no PBS token. The pinned PBS 4.2.6-1 schema actually declares a NULL create response,
+ *   while DELETE declares a UPID. We preserve bounded readback for both; a synchronous create
+ *   succeeds at the first poll rather than depending on the old UPID assumption.
  * ★ IT TAKES THE READ AS AN EFFECT RATHER THAN A FUNCTION — the one simplification over
  *   ceph-pool-settle.ts: an Effect is a description, so re-running it re-reads and no dependency
  *   has to be threaded back in to avoid a cycle.
@@ -91,8 +93,9 @@ export const guardBackend = (live: PbsDatastoreAttributes, props: PbsDatastorePr
  *   Anything still unsettled after two minutes is a fault to surface, not a wait to lengthen, and
  *   the caller's message points at the task log, which is where the real answer is. `Effect.sleep`
  *   yields between polls; nothing here parks a call on one long wait.
- * ⚠️ POLLING THE TASK STATUS INSTEAD WOULD BE WORSE, for ceph-pool-settle.ts's reason: every call
- *   mints a FRESH token, so the token asking about the task is not the one that started it.
+ * ⚠️ THE ORIGINAL TRANSPORT MINTED A TOKEN PER CALL, making task-owner polling unreliable.
+ *   The SDK runner now reuses leases, but create has no task id in its measured response schema.
+ *   This migration therefore preserves bounded readback rather than inventing a task handle.
  */
 export const settle = <A, E, R>(read: Effect.Effect<A, E, R>, done: (live: A) => boolean) =>
   Effect.gen(function* () {

package/src/proxmox/pbs-datastore-lifecycle.ts

@@ -0,0 +1,114 @@
+/** PBS 4.2.6-1 datastore lifecycle. Reads and writes use the distilled SDK. */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import type { PbsDatastoreProps } from './pbs-datastore.ts';
+import { type PbsDatastoreAttributes, matches, object, updateForm } from './pbs-datastore-form.ts';
+import { createOne, deleteOne, readOne, updateOne } from './pbs-datastore-wire.ts';
+import { guardBackend, guardPath, settle } from './pbs-datastore-guard.ts';
+import { guardDatastoreForms } from './pbs-datastore-endpoint.ts';
+import { formToSend } from './update-guard.ts';
+
+export const handlers = {
+  /**
+   * ⛔ EMPTY, AND HERE IT GUARDS THE ESTATE'S BACKUPS. `GET /config/datastore` returns every
+   *   datastore on the host, the one PVE's `type: pbs` storage writes into included. See
+   *   `pveHandlers` in resource.ts for why adoption stays an explicit act.
+   */
+  list: () => Effect.succeed([]),
+  read: ({ olds }: { olds: PbsDatastoreProps }) => readOne(olds),
+  /**
+   * ⚠️ `isResolved` IS THE NARROWING, resource.ts's reason: at plan time a prop can still be an
+   *   unresolved Output, and comparing a placeholder to a live value reports a phantom update.
+   * ⛔ `guardPath` IS A DELIBERATE DEPARTURE FROM storage.ts, which lets its create-only field
+   *   plan as noop. Dying fails `alchemy plan` with both paths named — see the ⛔ on the prop.
+   */
+  diff: ({
+    news,
+    output,
+  }: {
+    news: Input<PbsDatastoreProps>;
+    output: PbsDatastoreAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      // ⛔ BEFORE the `output === undefined` return: that branch IS the create, which is the
+      //   one this family has never checked. resource.ts carries the argument in full.
+      yield* guardDatastoreForms(news);
+      if (output === undefined) return undefined;
+      const live = yield* readOne(news);
+      // ⚠️ `update`, not `create` — Alchemy's Diff admits only noop/update/replace, and an
+      //   object Alchemy has state for but PBS does not is drift for reconcile to repair.
+      if (live === undefined) return { action: 'update' } as const;
+      yield* guardPath(live, news);
+      yield* guardBackend(live, news);
+      return matches(live, news) ? ({ action: 'noop' } as const) : ({ action: 'update' } as const);
+    }),
+  /**
+   * ⚠️ NOT THE FACTORY'S reconcile: it reads back ONCE, immediately — see the ⛔ on `settle`.
+   * ⛔ `guardPath` RUNS HERE TOO, AND THAT IS NOT BELT-AND-BRACES — see the ⛔ on it.
+   * ⛔ THE `matches` GUARD BEFORE THE PUT IS resource.ts's, AND IT IS WHY ADOPTION IS FREE.
+   */
+  reconcile: Effect.fn(function* ({ news }: { news: PbsDatastoreProps }) {
+    // ⚠️ Again here: an ADOPTED row's diff answer is discarded by Alchemy and reconcile runs.
+    yield* guardDatastoreForms(news);
+    const live = yield* readOne(news);
+    if (live === undefined) {
+      yield* createOne(news);
+    } else {
+      yield* guardPath(live, news);
+      yield* guardBackend(live, news);
+      // ⚠️ An empty form is not a write, and a match is not one either — update-guard.ts.
+      const form = formToSend(matches, live, news, updateForm(news));
+      if (form !== undefined) {
+        yield* updateOne(news);
+      }
+    }
+    const after = yield* settle(readOne(news), (row) => row !== undefined && matches(row, news));
+    if (after === undefined || !matches(after, news)) {
+      /**
+       * ⛔ REFUSE RATHER THAN RETURN THE PROPS AS THOUGH THEY LANDED — resource.ts's rule.
+       *   The pinned PBS 4.2.6-1 schema gives create a null return, so readback is its evidence.
+       */
+      return yield* Effect.die(
+        new Error(
+          `${object(news)}: the write returned no error but the datastore still does not ` +
+            'match the declaration after 120s. Check the PBS task list ' +
+            '-- read it with `proxmox-backup-manager task log <upid>`. A slow disk is a ' +
+            'plausible cause (see `settle`); a create over an existing chunk store is not, ' +
+            'because PBS refuses that outright rather than timing out.',
+        ),
+      );
+    }
+    return after;
+  }),
+  /**
+   * ⛔ FULLY IMPLEMENTED, NEVER A STUB, and it only ever runs on an explicit
+   *   `.pipe(RemovalPolicy.destroy())` because this family defaults to `retain`.
+   * ⛔ NO `destroy-data`. PBS's DELETE drops the section from `datastore.cfg` and leaves every
+   *   chunk and snapshot on disk; `destroy-data=1` erases the contents. It is not a prop and
+   *   not a flag here, so this provider can un-declare a datastore and can never erase one.
+   *   ⚠️ IT IS STILL A ONE-WAY DOOR FOR A DECLARATION: re-adding a datastore over an existing
+   *     chunk store needs `reuse-datastore`, which is deliberately not declarable — see the
+   *     ⚠️ on `createForm`. Re-adopt with `proxmox-backup-manager datastore create …`.
+   * ⚠️ NO `keep-job-configs` EITHER, SO THE JOBS GO TOO: PBS defaults it false and removes the
+   *   verify, sync and prune jobs referencing this datastore — objects nothing here declares.
+   *   PBS's default stands, so the blast radius is what a human clicking Remove would get.
+   * ⚠️ AND THE REFUSAL CAN ARRIVE AFTER THE RESPONSE: the delete forks a worker too, so a store
+   *   held open by a running backup can fail once the call has already returned 200.
+   */
+  delete: Effect.fn(function* ({ olds }: { olds: PbsDatastoreProps }) {
+    yield* deleteOne(olds);
+    const left = yield* settle(readOne(olds), (row) => row === undefined);
+    if (left !== undefined) {
+      return yield* Effect.die(
+        new Error(
+          `${object(olds)}: the DELETE returned no error but the datastore is still in ` +
+            'datastore.cfg after 120s. Either a backup, verify or GC task still holds it, ' +
+            'or the provision role lacks Datastore.Allocate on /datastore/' +
+            `${olds.name}. Read the task log with \`proxmox-backup-manager task log <upid>\`.`,
+        ),
+      );
+    }
+  }),
+};

package/src/proxmox/pbs-datastore-wire.ts

@@ -0,0 +1,94 @@
+/** PBS 4.2.6-1 datastore SDK operations; no raw route-string transport. */
+import * as config from '@distilled.cloud/proxmox-backup/config';
+import * as Effect from 'effect/Effect';
+import { runPbs } from './distilled-pbs.ts';
+import { attributes, createForm, updateForm } from './pbs-datastore-form.ts';
+import type { PbsDatastoreProps } from './pbs-datastore.ts';
+
+/** Keep the existing form's unmanaged-field decisions while using typed SDK member names. */
+const members = (form: Record<string, string>) => ({
+  ...(form['comment'] === undefined ? {} : { comment: form['comment'] }),
+  ...(form['counter-reset-schedule'] === undefined
+    ? {}
+    : { counter_reset_schedule: form['counter-reset-schedule'] }),
+  ...(form['gc-schedule'] === undefined ? {} : { gc_schedule: form['gc-schedule'] }),
+  ...(form['keep-daily'] === undefined ? {} : { keep_daily: form['keep-daily'] }),
+  ...(form['keep-hourly'] === undefined ? {} : { keep_hourly: form['keep-hourly'] }),
+  ...(form['keep-last'] === undefined ? {} : { keep_last: form['keep-last'] }),
+  ...(form['keep-monthly'] === undefined ? {} : { keep_monthly: form['keep-monthly'] }),
+  ...(form['keep-weekly'] === undefined ? {} : { keep_weekly: form['keep-weekly'] }),
+  ...(form['keep-yearly'] === undefined ? {} : { keep_yearly: form['keep-yearly'] }),
+  ...(form['maintenance-mode'] === undefined ? {} : { maintenance_mode: form['maintenance-mode'] }),
+  ...(form['notification-thresholds'] === undefined
+    ? {}
+    : { notification_thresholds: form['notification-thresholds'] }),
+  ...(form['notify'] === undefined ? {} : { notify: form['notify'] }),
+  ...(form['notify-user'] === undefined ? {} : { notify_user: form['notify-user'] }),
+  ...(form['prune-schedule'] === undefined ? {} : { prune_schedule: form['prune-schedule'] }),
+  ...(form['tuning'] === undefined ? {} : { tuning: form['tuning'] }),
+  ...(form['verify-new'] === undefined ? {} : { verify_new: form['verify-new'] }),
+});
+
+const createRequest = (props: PbsDatastoreProps): config.CreateConfigDatastoreRequest => ({
+  ...members(createForm(props)),
+  name: props.name,
+  path: props.path,
+  ...(props.backend === undefined ? {} : { backend: props.backend }),
+});
+
+const updateRequest = (props: PbsDatastoreProps): config.PutConfigDatastoreRequest => ({
+  ...members(updateForm(props)),
+  name: props.name,
+});
+
+const wire = (row: config.GetConfigDatastoreResponse): Record<string, unknown> => ({
+  ...row,
+  'counter-reset-schedule': row.counter_reset_schedule,
+  'gc-schedule': row.gc_schedule,
+  'keep-daily': row.keep_daily,
+  'keep-hourly': row.keep_hourly,
+  'keep-last': row.keep_last,
+  'keep-monthly': row.keep_monthly,
+  'keep-weekly': row.keep_weekly,
+  'keep-yearly': row.keep_yearly,
+  'maintenance-mode': row.maintenance_mode,
+  'notification-thresholds': row.notification_thresholds,
+  'notify-user': row.notify_user,
+  'prune-schedule': row.prune_schedule,
+  'verify-new': row.verify_new,
+});
+
+/**
+ * ⛔ THE RAW READ FOLDED EVERY ERROR TO ABSENCE. Its `name` presence check could not distinguish
+ *   a missing section from a denied read: both suggested CREATE for a datastore holding backups.
+ *   The resulting "already exists" failure was loud, but the same fold on DELETE was worse:
+ *   the first denied read confirmed removal while the datastore still stood.
+ * ★ MEASURED 2026-09-24 against PBS 4.2.6-1: a missing section is plain-text HTTP400,
+ *   `no such datastore '<name>'`. The distilled patch types that GET response as
+ *   DatastoreNotFound. Only that tag means absent; no permission, transport or malformed-response
+ *   error can settle deletion. This replaces the old recommendation to disambiguate by listing.
+ * ⚠️ The read role still requires Datastore.Audit, and a missing grant now fails visibly.
+ */
+export const readOne = (props: PbsDatastoreProps) =>
+  runPbs(props.target, 'read', config.getConfigDatastore({ name: props.name })).pipe(
+    Effect.map((live) => attributes(wire(live), props)),
+    Effect.catchTag('DatastoreNotFound', () => Effect.succeed(undefined)),
+  );
+
+export const createOne = (props: PbsDatastoreProps) =>
+  runPbs(props.target, 'provision', config.createConfigDatastore(createRequest(props)));
+
+export const updateOne = (props: PbsDatastoreProps) =>
+  runPbs(props.target, 'provision', config.putConfigDatastore(updateRequest(props)));
+
+/** ⛔ No destroy-data or keep-job-configs flag: retain the original removal contract. */
+export const deleteOne = (props: PbsDatastoreProps) =>
+  Effect.gen(function* () {
+    // ⛔ Missing-item tags are measured for GET only. Do not guess the DELETE error shape.
+    if ((yield* readOne(props)) === undefined) return;
+    return yield* runPbs(
+      props.target,
+      'provision',
+      config.deleteConfigDatastore({ name: props.name }),
+    );
+  });

package/src/proxmox/pbs-datastore.ts

@@ -13,12 +13,11 @@
  *   `/access/domains` lists the realms `pbs`, `pam` and an openid realm. So the
  *   prefix, the `{"data": …}` envelope and the strict-TLS story are PVE's exactly — and only the
  *   credential differs. There is no `pve` realm here; a PVE token cannot authenticate at all.
- *   The header differs too, which is why `pve()` exists rather than `pve()` being reused — see the
- *   ⛔ on `pbsAuthorization` in pbs-datastore-form.ts.
+ *   The distilled PBS SDK owns that distinct header; `distilled-pbs.ts` supplies its credentials.
  *
- * ⛔ THERE IS NO OPENBAO MOUNT FOR PBS TODAY, SO NOTHING HERE CAN DEPLOY YET. `PbsTarget.mount` is
+ * ⚠️ HISTORICAL BOOTSTRAP BLOCKER, 2026-09-13: THERE WAS NO PBS MOUNT. `PbsTarget.mount` is
  *   a parameter for the reason `PveTarget.mount` is — the provider must be able to leave this
- *   estate — but the estate has nothing to put in it. MEASURED: under the agent's approle,
+ *   estate. A later PBS credential lane resolved the following incident. MEASURED: under the agent's approle,
  *   `bao token capabilities` answers `deny` for `proxmox-c1/creds/{read,provision}`,
  *   `proxmox-c2/creds/read` and every `…pbs…` path tried, and `sys/mounts` is 403 — so I could
  *   not enumerate the mounts to PROVE a PBS one is absent. That it is absent is the brief's
@@ -27,7 +26,7 @@
  *     <mount>/creds/<role>` answering `{"data":{"token_id":…,"secret":…}}`, where `token_id` is a
  *     PBS token id `user@realm!tokenname` — `hf-read@pbs!…` and `hf-provision@pbs!…`. Same short,
  *     non-renewable lease contract as `proxmox-c1`.
- *   ⚠️ PBS HAS NO DYNAMIC-SECRETS PLUGIN OF ITS OWN — OpenBao's Proxmox support is a PVE thing — so
+ *   ⚠️ PBS HAD NO DYNAMIC-SECRETS PLUGIN OF ITS OWN — OpenBao's Proxmox support is a PVE thing — so
  *     the mount is a small custom vendor against `POST /access/users/{id}/token/{name}`. Say which
  *     mount and role you needed rather than reaching for the read-only `metrics@pbs` token on
  *     the kv shelf: widening that would delete the outer lock for every reader of the shelf.
@@ -50,23 +49,11 @@
  *   a state store Alchemy writes UNENCRYPTED and this estate copies to a backup guest nightly.
  */
 import { Resource } from 'alchemy';
-import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { pve } from './client.ts';
-import {
-  type PbsDatastoreAttributes,
-  type PbsTarget,
-  createForm,
-  matches,
-  object,
-  readOne,
-  updateForm,
-} from './pbs-datastore-form.ts';
-import { guardBackend, guardPath, settle } from './pbs-datastore-guard.ts';
-import { guardDatastoreForms } from './pbs-datastore-endpoint.ts';
+import type { PbsDatastoreAttributes, PbsTarget } from './pbs-datastore-form.ts';
+import { handlers } from './pbs-datastore-lifecycle.ts';
 import type { PveRequirements } from './resource.ts';
-import { formToSend } from './update-guard.ts';
 
 export type { PbsDatastoreAttributes, PbsTarget };
 
@@ -163,117 +150,4 @@ export const PbsDatastore = Resource<PbsDatastore>('Pbs.Datastore', {
 });
 
 export const PbsDatastoreProvider = () =>
-  Provider.effect(
-    PbsDatastore,
-    Effect.succeed(
-      PbsDatastore.Provider.of({
-        /**
-         * ⛔ EMPTY, AND HERE IT GUARDS THE ESTATE'S BACKUPS. `GET /config/datastore` returns every
-         *   datastore on the host, the one PVE's `type: pbs` storage writes into included. See
-         *   `pveHandlers` in resource.ts for why adoption stays an explicit act.
-         */
-        list: () => Effect.succeed([]),
-        read: ({ olds }) => readOne(olds),
-        /**
-         * ⚠️ `isResolved` IS THE NARROWING, resource.ts's reason: at plan time a prop can still be an
-         *   unresolved Output, and comparing a placeholder to a live value reports a phantom update.
-         * ⛔ `guardPath` IS A DELIBERATE DEPARTURE FROM storage.ts, which lets its create-only field
-         *   plan as noop. Dying fails `alchemy plan` with both paths named — see the ⛔ on the prop.
-         */
-        diff: ({ news, output }) =>
-          Effect.gen(function* () {
-            if (!isResolved(news)) return undefined;
-            // ⛔ BEFORE the `output === undefined` return: that branch IS the create, which is the
-            //   one this family has never checked. resource.ts carries the argument in full.
-            yield* guardDatastoreForms(news);
-            if (output === undefined) return undefined;
-            const live = yield* readOne(news);
-            // ⚠️ `update`, not `create` — Alchemy's Diff admits only noop/update/replace, and an
-            //   object Alchemy has state for but PBS does not is drift for reconcile to repair.
-            if (live === undefined) return { action: 'update' } as const;
-            yield* guardPath(live, news);
-            yield* guardBackend(live, news);
-            return matches(live, news)
-              ? ({ action: 'noop' } as const)
-              : ({ action: 'update' } as const);
-          }),
-        /**
-         * ⚠️ NOT THE FACTORY'S reconcile: it reads back ONCE, immediately — see the ⛔ on `settle`.
-         * ⛔ `guardPath` RUNS HERE TOO, AND THAT IS NOT BELT-AND-BRACES — see the ⛔ on it.
-         * ⛔ THE `matches` GUARD BEFORE THE PUT IS resource.ts's, AND IT IS WHY ADOPTION IS FREE.
-         */
-        reconcile: Effect.fn(function* ({ news }) {
-          // ⚠️ Again here: an ADOPTED row's diff answer is discarded by Alchemy and reconcile runs.
-          yield* guardDatastoreForms(news);
-          const live = yield* readOne(news);
-          let upid: string | undefined;
-          if (live === undefined) {
-            upid = yield* pve<string>(
-              news.target,
-              'provision',
-              'POST',
-              'config/datastore',
-              createForm(news),
-            );
-          } else {
-            yield* guardPath(live, news);
-            yield* guardBackend(live, news);
-            // ⚠️ An empty form is not a write, and a match is not one either — update-guard.ts.
-            const form = formToSend(matches, live, news, updateForm(news));
-            if (form !== undefined) {
-              yield* pve(news.target, 'provision', 'PUT', object(news), form);
-            }
-          }
-          const after = yield* settle(
-            readOne(news),
-            (row) => row !== undefined && matches(row, news),
-          );
-          if (after === undefined || !matches(after, news)) {
-            /**
-             * ⛔ REFUSE RATHER THAN RETURN THE PROPS AS THOUGH THEY LANDED — resource.ts's rule.
-             *   A create answers with a task id, so "no error" is not evidence of a datastore.
-             */
-            return yield* Effect.die(
-              new Error(
-                `${object(news)}: the write returned no error but the datastore still does not ` +
-                  `match the declaration after 120s. PBS answered with task ${upid ?? '(none)'} ` +
-                  '-- read it with `proxmox-backup-manager task log <upid>`. A slow disk is a ' +
-                  'plausible cause (see `settle`); a create over an existing chunk store is not, ' +
-                  'because PBS refuses that outright rather than timing out.',
-              ),
-            );
-          }
-          return after;
-        }),
-        /**
-         * ⛔ FULLY IMPLEMENTED, NEVER A STUB, and it only ever runs on an explicit
-         *   `.pipe(RemovalPolicy.destroy())` because this family defaults to `retain`.
-         * ⛔ NO `destroy-data`. PBS's DELETE drops the section from `datastore.cfg` and leaves every
-         *   chunk and snapshot on disk; `destroy-data=1` erases the contents. It is not a prop and
-         *   not a flag here, so this provider can un-declare a datastore and can never erase one.
-         *   ⚠️ IT IS STILL A ONE-WAY DOOR FOR A DECLARATION: re-adding a datastore over an existing
-         *     chunk store needs `reuse-datastore`, which is deliberately not declarable — see the
-         *     ⚠️ on `createForm`. Re-adopt with `proxmox-backup-manager datastore create …`.
-         * ⚠️ NO `keep-job-configs` EITHER, SO THE JOBS GO TOO: PBS defaults it false and removes the
-         *   verify, sync and prune jobs referencing this datastore — objects nothing here declares.
-         *   PBS's default stands, so the blast radius is what a human clicking Remove would get.
-         * ⚠️ AND THE REFUSAL CAN ARRIVE AFTER THE RESPONSE: the delete forks a worker too, so a store
-         *   held open by a running backup can fail once the call has already returned 200.
-         */
-        delete: Effect.fn(function* ({ olds }) {
-          yield* pve<string>(olds.target, 'provision', 'DELETE', object(olds));
-          const left = yield* settle(readOne(olds), (row) => row === undefined);
-          if (left !== undefined) {
-            return yield* Effect.die(
-              new Error(
-                `${object(olds)}: the DELETE returned no error but the datastore is still in ` +
-                  'datastore.cfg after 120s. Either a backup, verify or GC task still holds it, ' +
-                  'or the provision role lacks Datastore.Allocate on /datastore/' +
-                  `${olds.name}. Read the task log with \`proxmox-backup-manager task log <upid>\`.`,
-              ),
-            );
-          }
-        }),
-      }),
-    ),
-  );
+  Provider.effect(PbsDatastore, Effect.succeed(PbsDatastore.Provider.of(handlers)));

package/src/proxmox/pbs-jobs-delete.test.ts

@@ -0,0 +1,40 @@
+/** A readable PBS section does not make a refused DELETE successful. No live calls. */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { withFakeBao } from './fake-bao-env.ts';
+import { PBS_JOBS_TARGET, fakePbsJobs } from './fake-pbs-jobs.ts';
+import { deleteOne as deleteDatastore } from './pbs-datastore-wire.ts';
+import { deleteOne as deletePrune } from './pbs-prune-job-wire.ts';
+import { deleteOne as deleteSync } from './pbs-sync-job-wire.ts';
+import { deleteOne as deleteVerify } from './pbs-verify-job-wire.ts';
+
+test('all four PBS DELETE paths propagate a typed refusal after a successful pre-read', async () => {
+  const fake = fakePbsJobs();
+  const target = PBS_JOBS_TARGET;
+  fake.rows.set('config/datastore/store', { name: 'store', path: '/mnt/store' });
+  fake.rows.set('config/prune/prune', { id: 'prune', store: 'store', schedule: 'daily' });
+  fake.rows.set('config/sync/sync', { id: 'sync', store: 'store', 'remote-store': 'other' });
+  fake.rows.set('config/verify/verify', { id: 'verify', store: 'store' });
+  // ★ A permission refusal exercises propagation without inventing an absent-DELETE shape.
+  fake.failDelete(403, { message: 'permission denied' });
+  const deletions = [
+    deleteDatastore({ name: 'store', path: '/mnt/store', target }).pipe(Effect.asVoid),
+    deletePrune({ id: 'prune', store: 'store', schedule: 'daily', target }).pipe(Effect.asVoid),
+    deleteSync({ id: 'sync', store: 'store', 'remote-store': 'other', target }).pipe(Effect.asVoid),
+    deleteVerify({ id: 'verify', store: 'store', schedule: null, target }).pipe(Effect.asVoid),
+  ];
+  await withFakeBao('http://bao.invalid', async () => {
+    for (const deletion of deletions) {
+      const error = await Effect.runPromise(deletion.pipe(Effect.flip, Effect.provide(fake.layer)));
+      expect(error).toMatchObject({ _tag: 'Forbidden' });
+    }
+  });
+  expect(fake.calls.filter((call) => call.method === 'GET')).toHaveLength(4);
+  expect(fake.writes.map((write) => write.method)).toEqual([
+    'DELETE',
+    'DELETE',
+    'DELETE',
+    'DELETE',
+  ]);
+  expect(fake.rows.size).toBe(4);
+});