@homeflare/alchemy 0.37.2 → 0.37.3

package/src/proxmox/backup-job-distilled.ts

@@ -0,0 +1,86 @@
+/** Backup-job operations from distilled-proxmox, walked against pve-manager 9.2.11. */
+import * as cluster from '@distilled.cloud/proxmox/cluster';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import { ProxmoxParseError } from '@distilled.cloud/proxmox/Errors';
+import { backupJobSpec } from './backup-job-config.ts';
+import type { BackupJobProps } from './backup-job.ts';
+import { runPve } from './distilled-pve.ts';
+
+/** SDK member names differ from the vendor's hyphenated form keys; omission stays omission. */
+export const backupJobRequest = (
+  props: BackupJobProps,
+  form = backupJobSpec.updateForm(props),
+): cluster.PutClusterBackupRequest => {
+  const {
+    'notes-template': notes_template,
+    'notification-mode': notification_mode,
+    'prune-backups': prune_backups,
+    'repeat-missed': repeat_missed,
+    ...fields
+  } = form;
+  return {
+    ...fields,
+    id: props.id,
+    notification_mode,
+    repeat_missed,
+    ...(notes_template === undefined ? {} : { notes_template }),
+    ...(prune_backups === undefined ? {} : { prune_backups }),
+  };
+};
+
+/**
+ * SDK decode also renames NESTED retention keys. Restore the vendor's property-string
+ * spelling before the existing canonical comparison, or keep_daily becomes perpetual drift.
+ * A property string from an older server remains a property string.
+ */
+export const readBackupJob = (props: BackupJobProps) =>
+  runPve(props.target, 'read', false, cluster.getClusterBackup({ id: props.id })).pipe(
+    // Legacy PVE emits these two properties as strings; current PVE expands objects.
+    // Validate the generated response's remaining fields without narrowing that compatibility.
+    Effect.flatMap((live) =>
+      Schema.decodeUnknownEffect(Schema.toType(cluster.GetClusterBackupResponse))({
+        ...live,
+        prune_backups: undefined,
+        fleecing: undefined,
+      }).pipe(
+        Effect.mapError(
+          () =>
+            new ProxmoxParseError({
+              body: undefined,
+              cause: 'Backup job response does not match its vendor schema',
+            }),
+        ),
+        Effect.as(live),
+      ),
+    ),
+    Effect.map((live) =>
+      backupJobSpec.attributes(
+        {
+          ...live,
+          'next-run': live.next_run,
+          'notes-template': live.notes_template,
+          'notification-mode': live.notification_mode,
+          'prune-backups':
+            typeof live.prune_backups === 'object' && live.prune_backups !== null
+              ? Object.fromEntries(
+                  Object.entries(live.prune_backups).map(([key, value]) => [
+                    key.replaceAll('_', '-'),
+                    value,
+                  ]),
+                )
+              : live.prune_backups,
+          'repeat-missed': live.repeat_missed,
+        },
+        props,
+      ),
+    ),
+    Effect.catchTag('BackupJobNotFound', () => Effect.succeed(undefined)),
+    Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+  );
+
+export const deleteBackupJob = (props: BackupJobProps) =>
+  runPve(props.target, 'provision', true, cluster.deleteClusterBackup({ id: props.id })).pipe(
+    Effect.catchTag('BackupJobNotFound', () => Effect.void),
+    Effect.catchTag('NotFound', () => Effect.void),
+  );

package/src/proxmox/backup-job.ts

@@ -13,14 +13,13 @@
  *   COULD CARRY. PVE's own API schema says so in one parenthesis — `id`: "Job ID (will be
  *   autogenerated)." — and a generated id looks like `backup-f56d8ab7-d524`. A resource that
  *   POSTed without an id would create a SECOND job beside the first on EVERY reconcile, and the
- *   read-back in `pveOperations` would still pass, because a job did appear: that check asks "is
- *   the object there", not "is it the one I meant". So `id` is a REQUIRED prop and is always sent
+ *   read-back could still pass, because a job did appear: that check asks "is the object there",
+ *   not "is it the one I meant". So `id` is a REQUIRED prop and is always sent
  *   on create. To adopt a job that already exists, declare its existing id; any other id is a new
  *   job beside it, not an adoption.
- *   ★ AN EXPLICIT id ALSO CLOSES A SECOND HOLE. `pveOperations.read` turns ANY failed GET into
- *     "absent" — an expired lease, a 403, a node that did not answer — and reconcile then POSTs.
- *     With an id, PVE refuses a duplicate section id and the deploy fails loudly; without one, that
- *     same swallowed error would have quietly doubled the cluster's backup jobs.
+ *   ★ FAILED READS NOW PROPAGATE THROUGH DISTILLED. Only a typed missing-job response means
+ *     absent. An expired lease, a 403 or an unrelated server error stops reconciliation before
+ *     any POST. The explicit id remains a second defense against accidentally duplicating jobs.
  *
  * ⚠️ `Sys.Modify` ON `/` IS THE GATE AND IT IS NOT A SMALL GRANT. PVE has no Backup.* privilege:
  *   create, update and delete of a vzdump job are all checked against `Sys.Modify` at `/` — the
@@ -30,17 +29,21 @@
  *   reaction to a 403.
  */
 import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import * as cluster from '@distilled.cloud/proxmox/cluster';
+import { runPve } from './distilled-pve.ts';
+import { specGuards } from './resource-guard.ts';
+import { formToSend } from './update-guard.ts';
+import { backupJobSpec } from './backup-job-config.ts';
+import { backupJobRequest, deleteBackupJob, readBackupJob } from './backup-job-distilled.ts';
+
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
-import { bool, guestList, propertyString, text } from './values.ts';
+import type { PveRequirements, WithTarget } from './resource-spec.ts';
 
 /**
- * ⚠️ THE PROPS ARE PVE'S OWN KEY NAMES, DASHES INCLUDED. `notes-template` rather than
- *   `notesTemplate` is deliberate: `createForm` is then a copy rather than a translation table,
- *   and a translation table is one more place for a key to be renamed and silently never sent. A
- *   field that is never sent reads back as whatever it already was, which is indistinguishable
- *   from "PVE ignored me".
+ * ★ Public props retain PVE's own dashed field names. The distilled transport maps those
+ *   existing forms to the SDK's generated identifiers; lifecycle tests check the actual wire.
  */
 export interface BackupJobProps extends WithTarget {
   /** ⛔ The primary key, REQUIRED. Never let PVE generate it — see the ⛔ above. */
@@ -107,109 +110,68 @@ export interface ProxmoxBackupJob extends Resource<
 export const ProxmoxBackupJob = Resource<ProxmoxBackupJob>('Proxmox.BackupJob');
 
 /**
- * The form for both create and update.
- *
- * ⛔ A FIELD THE DECLARATION LEAVES OUT IS NOT SENT, AND THAT IS LOAD BEARING. PVE's PUT can only
- *   SET a key; clearing one needs `delete=<key>`, which this resource deliberately never sends.
- *   `updateForm` is handed the props and nothing else, so a `delete` list could only be "every
- *   field you did not declare" — and on a job adopted out of the UI that would silently strip
- *   settings this resource does not even model, `compress`, `mailto` and `bwlimit` among them, on
- *   the first deploy. Leaving undeclared fields alone is the smaller lie, and `matches` tells the
- *   same lie consistently: it does not compare what it cannot change.
- *
- * ⚠️ THE FIVE FIELDS PVE DOCUMENTS A DEFAULT FOR ARE ALWAYS SENT AND ALWAYS COMPARED — `enabled`
- *   (1), `all` (0), `mode` (snapshot), `notification-mode` (auto), `repeat-missed` (0). That is
- *   what makes a hand-flipped `enabled 0` show up as drift rather than as silence, and it is also
- *   what stops those five looping: a field compared against a default must be sent as that
- *   default, or every plan reports an update the PUT never performs. The cost is worth reading
- *   before the first deploy against an adopted job — an omitted `all` is a declaration that this
- *   job backs up NOTHING, and PVE accepts a job that selects nothing without a word. Read that
- *   first plan; do not deploy it unseen.
+ * ⛔ Adoption stays explicit: listing every backup job could grant Alchemy deletion rights over
+ *   an undeclared schedule. Delete removes the schedule, not its stored archives; that still
+ *   stops future backups, so the plan line is a consequential warning.
  */
-const shape = (props: BackupJobProps) => ({
-  all: props.all === true ? '1' : '0',
-  enabled: props.enabled === false ? '0' : '1',
-  mode: props.mode ?? 'snapshot',
-  'notification-mode': props['notification-mode'] ?? 'auto',
-  'repeat-missed': props['repeat-missed'] === true ? '1' : '0',
-  schedule: props.schedule,
-  ...(props.comment === undefined ? {} : { comment: props.comment }),
-  ...(props.exclude === undefined ? {} : { exclude: guestList(props.exclude) }),
-  ...(props.fleecing === undefined ? {} : { fleecing: props.fleecing }),
-  ...(props['notes-template'] === undefined ? {} : { 'notes-template': props['notes-template'] }),
-  ...(props.pool === undefined ? {} : { pool: props.pool }),
-  ...(props['prune-backups'] === undefined ? {} : { 'prune-backups': props['prune-backups'] }),
-  ...(props.storage === undefined ? {} : { storage: props.storage }),
-  ...(props.vmid === undefined ? {} : { vmid: guestList(props.vmid) }),
-});
+const { guardCreate, guardUpdate } = specGuards(backupJobSpec);
 
-const handlers = pveHandlers<BackupJobProps, BackupJobAttributes>({
-  /**
-   * ⛔ NO "IS IT REALLY THERE" GUARD, ON PURPOSE. Returning undefined for a job whose JSON is
-   *   missing some key would be a guess about which keys PVE echoes back, and a wrong guess here
-   *   does not read as absent-and-harmless: `reconcile` would POST, and POST creates ANOTHER job.
-   *   Absence is decided by the API declining to answer, which `pveOperations.read` already
-   *   handles — not by a key being missing from an answer that did arrive.
-   */
-  attributes: (live, props) => ({
-    all: bool(live['all'], false),
-    comment: text(live['comment'], ''),
-    enabled: bool(live['enabled'], true),
-    exclude: guestList(live['exclude']),
-    fleecing: propertyString(live['fleecing'], 'enabled'),
-    id: props.id,
-    mode: text(live['mode'], 'snapshot'),
-    'next-run': typeof live['next-run'] === 'number' ? live['next-run'] : 0,
-    'notes-template': text(live['notes-template'], ''),
-    'notification-mode': text(live['notification-mode'], 'auto'),
-    pool: text(live['pool'], ''),
-    'prune-backups': propertyString(live['prune-backups']),
-    'repeat-missed': bool(live['repeat-missed'], false),
-    schedule: text(live['schedule'], ''),
-    storage: text(live['storage'], ''),
-    vmid: guestList(live['vmid']),
-  }),
-  collection: () => 'cluster/backup',
-  /** ⛔ `id` IS SENT AND IS NOT OPTIONAL. Everything above depends on PVE not inventing one. */
-  createForm: (props) => ({ ...shape(props), id: props.id }),
-  /** Each line reads "not declared, or equal"; the five defaulted fields have no undeclared case. */
-  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
-  endpoint: { create: 'pve:POST /cluster/backup', update: 'pve:PUT /cluster/backup/{id}' },
-  matches: (attributes, props) =>
-    attributes.schedule === props.schedule &&
-    attributes.enabled === (props.enabled !== false) &&
-    attributes.all === (props.all === true) &&
-    attributes.mode === (props.mode ?? 'snapshot') &&
-    attributes['notification-mode'] === (props['notification-mode'] ?? 'auto') &&
-    attributes['repeat-missed'] === (props['repeat-missed'] === true) &&
-    (props.storage === undefined || attributes.storage === props.storage) &&
-    (props.pool === undefined || attributes.pool === props.pool) &&
-    (props.comment === undefined || attributes.comment === props.comment) &&
-    (props.vmid === undefined || attributes.vmid === guestList(props.vmid)) &&
-    (props.exclude === undefined || attributes.exclude === guestList(props.exclude)) &&
-    (props['notes-template'] === undefined ||
-      attributes['notes-template'] === props['notes-template']) &&
-    (props['prune-backups'] === undefined ||
-      attributes['prune-backups'] === propertyString(props['prune-backups'])) &&
-    (props.fleecing === undefined ||
-      attributes.fleecing === propertyString(props.fleecing, 'enabled')),
-  path: (props) => `cluster/backup/${props.id}`,
-  updateForm: shape,
-});
-
-/**
-* ⛔ Empty for the same reason as every other resource here: adoption must be explicit.
-*   `GET /cluster/backup` would hand back the job somebody made by hand, and adopting it
-*   implicitly would give Alchemy the right to DELETE a cluster's only backup schedule the
-*   first time a line left a stack file.
- 
- *
-* ⚠️ DELETING THE JOB DOES NOT DELETE THE BACKUPS, AND THAT CUTS BOTH WAYS. The archives
-*   stay on the storage, so this looks harmless today; it is destructive in six months,
-*   when the schedule that should have replaced them has not run since. PVE will not
-*   refuse this the way it refuses to delete a pool still holding guests — nothing depends
-*   on a backup job — so the plan line is the only warning anyone gets.
- 
- */
+/** SDK lifecycle walked against pve-manager 9.2.11; failed reads never imply create. */
 export const ProxmoxBackupJobProvider = () =>
-  Provider.effect(ProxmoxBackupJob, Effect.succeed(ProxmoxBackupJob.Provider.of(handlers)));
+  Provider.effect(
+    ProxmoxBackupJob,
+    Effect.succeed(
+      ProxmoxBackupJob.Provider.of({
+        list: () => Effect.succeed([]),
+        read: ({ olds }) => readBackupJob(olds),
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          yield* guardCreate(news, output === undefined);
+          yield* guardUpdate(news);
+          if (output === undefined) return undefined;
+          const live = yield* readBackupJob(news);
+          if (live === undefined) {
+            yield* guardCreate(news, true);
+            return { action: 'update' } as const;
+          }
+          return { action: backupJobSpec.matches(live, news) ? 'noop' : 'update' } as const;
+        }),
+        reconcile: Effect.fn(function* ({ news }) {
+          const live = yield* readBackupJob(news);
+          yield* guardCreate(news, live === undefined);
+          yield* guardUpdate(news);
+          if (live === undefined) {
+            yield* runPve(
+              news.target,
+              'provision',
+              true,
+              cluster.createClusterBackup(backupJobRequest(news)),
+            );
+          } else {
+            const form = formToSend(
+              backupJobSpec.matches,
+              live,
+              news,
+              backupJobSpec.updateForm(news),
+            );
+            if (form !== undefined)
+              yield* runPve(
+                news.target,
+                'provision',
+                true,
+                cluster.putClusterBackup(backupJobRequest(news, form)),
+              );
+          }
+          const after = yield* readBackupJob(news);
+          if (after === undefined)
+            return yield* Effect.fail(
+              new Error(
+                `${backupJobSpec.path(news)}: write returned success but the resource is still absent`,
+              ),
+            );
+          return after;
+        }),
+        delete: ({ olds }) => deleteBackupJob(olds),
+      }),
+    ),
+  );

package/src/proxmox/constraints.test.ts

@@ -18,7 +18,8 @@ import { engineOver } from '../verify/fake-engine.ts';
 import { constraintsFor, formViolations } from './constraint-guard.ts';
 import { type EndpointConstraints, refusal, violations } from './constraints.ts';
 import type { PbsTarget } from './credentials.ts';
-import { fakePve, withoutBao } from './fake-pve.ts';
+import { withoutBao } from './fake-pve.ts';
+import { fakePbsJobs } from './fake-pbs-jobs.ts';
 import { PROXMOX_CONSTRAINTS, PROXMOX_CONSTRAINTS_DIGEST } from './generated/constraints/index.ts';
 import { PbsVerifyJob, PbsVerifyJobProvider } from './pbs-verify-job.ts';
 
@@ -46,12 +47,8 @@ describe('the v-r2-offsite failure, refused at plan instead of by the server', (
      * skip entirely (`output === undefined` returned before any check). It remembers the POST so
      * the read-back in `reconcile` can succeed, which is what the 128-character case needs.
      */
-    const live = new Map<string, Record<string, unknown>>();
-    const fake = fakePve((call) => {
-      if (call.method === 'GET') return live.get(call.path);
-      if (call.method === 'POST') live.set(`config/verify/${String(call.form['id'])}`, call.form);
-      return undefined;
-    });
+    // Missing PBS sections are measured plain-text HTTP400, not HTTP200 data:null.
+    const fake = fakePbsJobs();
     const engine = engineOver(PbsVerifyJobProvider().pipe(Layer.provideMerge(fake.layer)));
     const outcome = await withoutBao(() =>
       engine.deploy(job(comment)).then(
@@ -59,7 +56,11 @@ describe('the v-r2-offsite failure, refused at plan instead of by the server', (
         (error: unknown) => ({ error }),
       ),
     );
-    return { ...outcome, calls: fake.calls, writes: fake.writes() };
+    return {
+      ...outcome,
+      calls: fake.calls,
+      writes: fake.writes.map((row) => `${row.method} ${row.path}`),
+    };
   };
 
   test('129 characters is refused, and NOTHING is written', async () => {

package/src/proxmox/distilled-pbs.test.ts

@@ -0,0 +1,87 @@
+/** The real PBS SDK protocol: correct credentials, bounded attempts, and no implicit re-send. */
+import { expect, test } from 'bun:test';
+import * as config from '@distilled.cloud/proxmox-backup/config';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import type { PbsTarget, PveCredential } from './credentials.ts';
+import { runPbsWith } from './distilled-pbs.ts';
+
+const TARGET: PbsTarget = { api: 'https://pbs.invalid:8007', mount: 'pbs-test', scheme: 'pbs' };
+const CREDENTIAL: PveCredential = {
+  leaseSeconds: 300,
+  secret: 'fake-secret-not-real',
+  tokenId: 'test@pbs!fake',
+};
+
+const transport = (answer: (request: Request) => Response | Promise<Response>) => {
+  const stub = (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) =>
+    Promise.resolve(
+      answer(
+        input instanceof Request ? new Request(input, init) : new Request(String(input), init),
+      ),
+    );
+  return FetchHttpClient.layer.pipe(
+    Layer.provideMerge(
+      Layer.succeed(
+        FetchHttpClient.Fetch,
+        Object.assign(stub, { preconnect: globalThis.fetch.preconnect }),
+      ),
+    ),
+  );
+};
+
+test('the PBS SDK builds its own colon-separated authorization and normalizes the API root', async () => {
+  let called = false;
+  const layer = transport((request) => {
+    called = true;
+    expect(request.url).toBe(
+      'https://pbs.invalid:8007/api2/json/config/notifications/matchers/pager',
+    );
+    expect(request.headers.get('authorization')).toBe(
+      'PBSAPIToken=test@pbs!fake:fake-secret-not-real',
+    );
+    return Response.json({ data: { name: 'pager', target: ['mail-to-root'] } });
+  });
+  const row = await Effect.runPromise(
+    runPbsWith(TARGET, CREDENTIAL, config.getConfigNotificationMatcher({ name: 'pager' })).pipe(
+      Effect.provide(layer),
+    ),
+  );
+  expect(called).toBe(true);
+  expect(row.target).toEqual(['mail-to-root']);
+});
+
+test('a typed HTTP failure is returned once, without the SDK default retry', async () => {
+  let calls = 0;
+  const layer = transport(() => {
+    calls += 1;
+    return Response.json({ message: 'unavailable' }, { status: 503 });
+  });
+  const error = await Effect.runPromise(
+    runPbsWith(TARGET, CREDENTIAL, config.deleteConfigNotificationMatcher({ name: 'pager' })).pipe(
+      Effect.flip,
+      Effect.provide(layer),
+    ),
+  );
+  expect(error).toMatchObject({ _tag: 'ServiceUnavailable' });
+  expect(calls).toBe(1);
+});
+
+test('a sent write that never answers is bounded and never repeated', async () => {
+  let calls = 0;
+  const layer = transport(() => {
+    calls += 1;
+    return new Promise<Response>(() => {});
+  });
+  const error = await Effect.runPromise(
+    runPbsWith(
+      TARGET,
+      CREDENTIAL,
+      config.deleteConfigNotificationMatcher({ name: 'pager' }),
+      '20 millis',
+    ).pipe(Effect.flip, Effect.provide(layer)),
+  );
+  expect(error).toMatchObject({ _tag: 'TimeoutError' });
+  expect(calls).toBe(1);
+});

package/src/proxmox/distilled-pbs.ts

@@ -0,0 +1,50 @@
+/**
+ * PBS 4.2.6-1 operations through the distilled SDK, with the existing OpenBao leases.
+ *
+ * ⛔ PBS IS A SINGLE HOST, NOT A PVE CLUSTER. Its Credentials layer supplies the
+ *   `PBSAPIToken=id:secret` scheme; running a PBS operation through runPve would send PVE's
+ *   different header. Nothing here invents another host or retries a possibly completed write.
+ * ★ Retry.none also disables distilled's default transient-error retries within that host.
+ *   MEMBER_TIMEOUT bounds the one attempt, just as it bounds each PVE member attempt.
+ */
+import { credentials } from '@distilled.cloud/proxmox-backup/Credentials';
+import type { ProxmoxBackupOpContext } from '@distilled.cloud/proxmox-backup/Protocol';
+import * as Retry from '@distilled.cloud/proxmox-backup/Retry';
+import type * as Cause from 'effect/Cause';
+import type * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import type { PveCredentialDenied } from './credential-errors.ts';
+import type { PbsTarget, PveCredential, PveRole } from './credentials.ts';
+import { leased } from './lease-cache.ts';
+import { MEMBER_TIMEOUT } from './members.ts';
+
+/** An already-held lease, also used by offline protocol tests. Production uses the default bound. */
+export const runPbsWith = <A, E>(
+  target: PbsTarget,
+  credential: PveCredential,
+  op: Effect.Effect<A, E, ProxmoxBackupOpContext>,
+  timeout: Duration.Input = MEMBER_TIMEOUT,
+): Effect.Effect<A, E | Cause.TimeoutError, HttpClient.HttpClient> =>
+  op.pipe(
+    Retry.none,
+    Effect.provide(
+      credentials({
+        baseUrl: target.api,
+        secret: credential.secret,
+        tokenId: credential.tokenId,
+      }),
+    ),
+    Effect.timeout(timeout),
+  );
+
+/** Preserve lease sharing and expose credential refusal and SDK error tags unchanged. */
+export const runPbs = <A, E>(
+  target: PbsTarget,
+  role: PveRole,
+  op: Effect.Effect<A, E, ProxmoxBackupOpContext>,
+): Effect.Effect<A, E | Cause.TimeoutError | PveCredentialDenied | Error, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const credential = yield* leased(target, role);
+    return yield* runPbsWith(target, credential, op);
+  });

package/src/proxmox/fake-pbs-jobs.ts

@@ -0,0 +1,99 @@
+/** Test-only PBS 4.2.6-1 wire fixture. Every HTTP request is intercepted; no live credentials. */
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import type { PbsTarget } from './credentials.ts';
+
+export const PBS_JOBS_TARGET: PbsTarget = {
+  api: 'https://pbs.test:8007/api2/json',
+  mount: 'pbs-test',
+  scheme: 'pbs',
+};
+
+const sections: Record<string, string> = {
+  datastore: 'datastore',
+  prune: 'prune',
+  sync: 'sync',
+  verify: 'verification',
+};
+const numbers =
+  /^(keep-(daily|hourly|last|monthly|weekly|yearly)|max-depth|outdated-after|transfer-last)$/;
+const booleans = /^(disable|ignore-verified|remove-vanished|verified-only|verify-new)$/;
+
+type Write = { method: string; path: string; form: Record<string, string> };
+
+export const fakePbsJobs = () => {
+  const rows = new Map<string, Record<string, unknown>>();
+  const writes: Write[] = [];
+  const calls: { method: string; path: string }[] = [];
+  let failure: { status: number; body: unknown } | undefined;
+  let deleteFailure: { status: number; body: unknown } | undefined;
+  const stub = async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    if (url.pathname.includes('/creds/')) {
+      return Response.json({
+        data: { secret: 'fake-secret-not-real', token_id: 'test@pbs!fake' },
+        lease_duration: 0,
+      });
+    }
+    const path = decodeURIComponent(url.pathname.replace('/api2/json/', ''));
+    calls.push({ method: request.method, path });
+    if (request.method === 'GET' && failure !== undefined) {
+      return Response.json(failure.body, { status: failure.status });
+    }
+    const parts = path.split('/');
+    const family = parts[1] ?? '';
+    const id = parts[2] ?? '';
+    const row = rows.get(path);
+    if (request.method === 'GET') {
+      // ★ Measured live 2026-09-24: these four missing sections are plain-text HTTP400.
+      return row === undefined
+        ? new Response(`no such ${sections[family]} '${id}'`, { status: 400 })
+        : Response.json({ data: row });
+    }
+    const form = Object.fromEntries(new URLSearchParams(await request.text()));
+    writes.push({ method: request.method, path, form });
+    if (request.method === 'DELETE') {
+      if (deleteFailure !== undefined) {
+        return Response.json(deleteFailure.body, { status: deleteFailure.status });
+      }
+      rows.delete(path);
+      return Response.json({ data: family === 'datastore' ? 'UPID:fake:delete' : null });
+    }
+    const key = request.method === 'POST' ? `${path}/${form['id'] ?? form['name']}` : path;
+    const after = { ...rows.get(key) };
+    for (const [name, value] of Object.entries(form)) {
+      after[name] = numbers.test(name)
+        ? Number(value)
+        : booleans.test(name)
+          ? value === '1'
+          : value;
+    }
+    rows.set(key, after);
+    // ★ Pinned schema: create datastore is Unit/null; DELETE alone yields a UPID.
+    return Response.json({ data: null });
+  };
+  const fetchStub = Object.assign(stub, { preconnect: globalThis.fetch.preconnect });
+  return {
+    rows,
+    writes,
+    calls,
+    failRead: (status: number, body: unknown) => {
+      failure = { status, body };
+    },
+    failDelete: (status: number, body: unknown) => {
+      deleteFailure = { status, body };
+    },
+    reset: () => {
+      rows.clear();
+      calls.length = 0;
+      writes.length = 0;
+      failure = undefined;
+      deleteFailure = undefined;
+    },
+    layer: FetchHttpClient.layer.pipe(
+      Layer.provideMerge(Layer.succeed(FetchHttpClient.Fetch, fetchStub as typeof fetch)),
+    ),
+  };
+};

package/src/proxmox/fake-pbs-notify.ts

@@ -83,7 +83,10 @@ export const fakeNotify = (
     const { deletes, fields } = body(call);
     if (call.method === 'GET') {
       const object = objects.get(path);
-      return object === undefined ? undefined : withSecretsBlanked(path, object, secrets);
+      // SDK reads require the resource shape: data:null is malformed, not evidence of absence.
+      return object === undefined
+        ? Response.json({ message: 'not found' }, { status: 404 })
+        : withSecretsBlanked(path, object, secrets);
     }
     if (call.method === 'DELETE') {
       objects.delete(path);

package/src/proxmox/fake-pve.ts

@@ -35,7 +35,7 @@ export interface PveCall {
   readonly pairs: readonly (readonly [string, string])[];
 }
 
-/** Answers one call with its `data`; `undefined` is PVE's `{"data": null}`. */
+/** Answers with `data`, or an explicit Response for SDK error fixtures; undefined is data:null. */
 export type PveAnswer = (call: PveCall) => unknown;
 
 export interface FakePve {
@@ -69,7 +69,8 @@ export const fakePve = (answer: PveAnswer): FakePve => {
       path,
     };
     calls.push(call);
-    return Response.json({ data: answer(call) ?? null });
+    const value = answer(call);
+    return value instanceof Response ? value : Response.json({ data: value ?? null });
   };
   // ⚠️ `typeof fetch` carries `preconnect` on bun's lib — client.test.ts has the note.
   const fetchStub = Object.assign(stub, { preconnect: globalThis.fetch.preconnect });