@homeflare/alchemy 0.37.1 → 0.37.3

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);
+});

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

@@ -0,0 +1,215 @@
+/** Four PBS families through the real SDK and Alchemy's upstream test harness. */
+import { afterEach, beforeEach, expect } from 'bun:test';
+import * as Test from 'alchemy/Test/Bun';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { PBS_JOBS_TARGET, fakePbsJobs } from './fake-pbs-jobs.ts';
+import { PbsDatastore, PbsDatastoreProvider } from './pbs-datastore.ts';
+import { deleteOne as deleteDatastore } from './pbs-datastore-wire.ts';
+import { PbsPruneJob, PbsPruneJobProvider } from './pbs-prune-job.ts';
+import { PbsSyncJob, PbsSyncJobProvider } from './pbs-sync-job.ts';
+import { PbsVerifyJob, PbsVerifyJobProvider } from './pbs-verify-job.ts';
+
+const fake = fakePbsJobs();
+// ⛔ Test harness hooks take Effects, so isolate the shell before its per-test runtime starts.
+let saved: [string, string | undefined][] = [];
+beforeEach(() => {
+  saved = Object.entries(process.env).filter(([key]) => /^(BAO|VAULT)_/.test(key));
+  for (const [key] of saved) delete process.env[key];
+  process.env['BAO_ADDR'] = 'http://bao.invalid';
+  fake.reset();
+});
+afterEach(() => {
+  for (const key of Object.keys(process.env))
+    if (/^(BAO|VAULT)_/.test(key)) delete process.env[key];
+  for (const [key, value] of saved) process.env[key] = value;
+});
+
+const { test } = Test.make({
+  adopt: true,
+  dev: false,
+  sidecar: false,
+  stage: 'test',
+  providers: Layer.mergeAll(
+    PbsDatastoreProvider(),
+    PbsPruneJobProvider(),
+    PbsSyncJobProvider(),
+    PbsVerifyJobProvider(),
+  ).pipe(Layer.provideMerge(fake.layer)),
+});
+
+const stack = (comment = 'current') =>
+  Effect.gen(function* () {
+    yield* PbsDatastore('store', {
+      name: 'store',
+      path: '/mnt/store',
+      'gc-schedule': 'daily',
+      'verify-new': false,
+      comment,
+      target: PBS_JOBS_TARGET,
+    });
+    yield* PbsPruneJob('prune', {
+      id: 'prune',
+      store: 'store',
+      schedule: 'daily',
+      'keep-daily': 30,
+      'max-depth': 0,
+      comment,
+      target: PBS_JOBS_TARGET,
+    });
+    yield* PbsSyncJob('sync', {
+      id: 'sync',
+      store: 'store',
+      'remote-store': 'other',
+      'remote-ns': 'archive',
+      'remove-vanished': false,
+      'max-depth': 0,
+      'verified-only': true,
+      comment,
+      target: PBS_JOBS_TARGET,
+    });
+    yield* PbsVerifyJob('verify', {
+      id: 'verify',
+      store: 'store',
+      schedule: null,
+      'outdated-after': 30,
+      comment,
+      target: PBS_JOBS_TARGET,
+    });
+  });
+
+const existing = () => {
+  fake.rows.set('config/datastore/store', {
+    name: 'store',
+    path: '/mnt/store',
+    'gc-schedule': 'daily',
+    'verify-new': false,
+    comment: 'current',
+  });
+  fake.rows.set('config/prune/prune', {
+    id: 'prune',
+    store: 'store',
+    schedule: 'daily',
+    'keep-daily': 30,
+    'max-depth': 0,
+    comment: 'current',
+  });
+  fake.rows.set('config/sync/sync', {
+    id: 'sync',
+    store: 'store',
+    'remote-store': 'other',
+    'remote-ns': 'archive',
+    'remove-vanished': false,
+    'max-depth': 0,
+    'verified-only': true,
+    comment: 'current',
+  });
+  fake.rows.set('config/verify/verify', {
+    id: 'verify',
+    store: 'store',
+    'ignore-verified': true,
+    'outdated-after': 30,
+    comment: 'current',
+  });
+};
+
+const actions = (plan: { resources: Record<string, { action: string }> }) =>
+  Object.values(plan.resources)
+    .map((row) => row.action)
+    .sort();
+
+test.provider(
+  'matching datastore and three job families adopt without writes, then plan noop',
+  (scratch) =>
+    Effect.gen(function* () {
+      existing();
+      yield* scratch.deploy(stack());
+      expect(fake.writes).toEqual([]);
+      expect(actions(yield* scratch.plan(stack()))).toEqual(['noop', 'noop', 'noop', 'noop']);
+    }),
+);
+
+test.provider(
+  'measured missing sections create through typed SDK forms and settle to noop',
+  (scratch) =>
+    Effect.gen(function* () {
+      yield* scratch.deploy(stack());
+      expect(fake.writes.map((row) => `${row.method} ${row.path}`).sort()).toEqual([
+        'POST config/datastore',
+        'POST config/prune',
+        'POST config/sync',
+        'POST config/verify',
+      ]);
+      expect(fake.writes.find((row) => row.path === 'config/prune')?.form).toMatchObject({
+        'keep-daily': '30',
+        'max-depth': '0',
+      });
+      expect(fake.writes.find((row) => row.path === 'config/sync')?.form).toMatchObject({
+        'remote-store': 'other',
+        'remote-ns': 'archive',
+        'remove-vanished': '0',
+        'verified-only': '1',
+      });
+      expect(fake.writes.find((row) => row.path === 'config/verify')?.form).not.toHaveProperty(
+        'schedule',
+      );
+      expect(actions(yield* scratch.plan(stack()))).toEqual(['noop', 'noop', 'noop', 'noop']);
+    }),
+);
+
+test.provider(
+  'drift updates only declared fields through SDK forms and the next plan is noop',
+  (scratch) =>
+    Effect.gen(function* () {
+      existing();
+      yield* scratch.deploy(stack());
+      yield* scratch.deploy(stack('changed'));
+      expect(fake.writes.map((row) => `${row.method} ${row.path}`).sort()).toEqual([
+        'PUT config/datastore/store',
+        'PUT config/prune/prune',
+        'PUT config/sync/sync',
+        'PUT config/verify/verify',
+      ]);
+      for (const write of fake.writes) expect(write.form).not.toHaveProperty('delete');
+      expect(actions(yield* scratch.plan(stack('changed')))).toEqual([
+        'noop',
+        'noop',
+        'noop',
+        'noop',
+      ]);
+    }),
+);
+
+for (const status of [200, 400, 401, 403, 500]) {
+  test.provider(
+    `HTTP ${status} malformed or refused read never becomes create or noop`,
+    (scratch) =>
+      Effect.gen(function* () {
+        existing();
+        yield* scratch.deploy(stack());
+        fake.failRead(status, { message: 'unrelated server refusal', data: null });
+        const result = yield* Effect.exit(scratch.plan(stack()));
+        expect(result._tag).toBe('Failure');
+        expect(fake.writes).toEqual([]);
+        // Clear the injected failure before Test.Bun's automatic fixture teardown.
+        fake.reset();
+      }),
+  );
+}
+
+test.provider(
+  'a refused datastore delete read cannot confirm deletion; already absent needs no write',
+  (scratch) =>
+    Effect.gen(function* () {
+      existing();
+      yield* scratch.deploy(stack());
+      const props = { name: 'store', path: '/mnt/store', target: PBS_JOBS_TARGET };
+      fake.failRead(403, { message: 'permission denied', data: null });
+      expect((yield* Effect.exit(deleteDatastore(props)))._tag).toBe('Failure');
+      expect(fake.writes).toEqual([]);
+      fake.reset();
+      yield* deleteDatastore(props);
+      yield* scratch.destroy();
+      expect(fake.writes).toEqual([]);
+    }),
+);