@homeflare/alchemy 0.37.2 → 0.37.3

package/src/proxmox/pbs-notification-target-distilled.ts

@@ -0,0 +1,124 @@
+/**
+ * PBS 4.2.6-1 notification operations, generated from its vendor schema in SDK 0.3.0.
+ *
+ * ★ Keep targetForm's selective secret groups and deletion semantics. The SDK schemas validate
+ *   the spelling adapter before their typed operations encode it; no request shape is cast.
+ *   Only the SDK's NotFound is absence. An unreadable target must stop adoption, not create it.
+ */
+import * as config from '@distilled.cloud/proxmox-backup/config';
+import type {
+  ProxmoxBackupOpContext,
+  ProxmoxBackupOpError,
+} from '@distilled.cloud/proxmox-backup/Protocol';
+import * as Effect from 'effect/Effect';
+import { notificationInput } from './pbs-notification-input.ts';
+import type { PveForm } from './client.ts';
+import { runPbs } from './distilled-pbs.ts';
+import type { PbsNotificationTargetProps as Props } from './pbs-notification-target.ts';
+import { targetAttributes } from './pbs-notification-target-wire.ts';
+
+/** SDK property names differ from the vendor's form keys only at these two fields. */
+const requestFields = (props: Props, form: PveForm) => ({
+  ...form,
+  from_address: form['from-address'],
+  mailto_user: form['mailto-user'],
+  name: props.name,
+});
+
+const read = (
+  props: Props,
+): Effect.Effect<Record<string, unknown>, ProxmoxBackupOpError, ProxmoxBackupOpContext> => {
+  switch (props.type) {
+    case 'sendmail':
+      return config.getConfigNotificationEndpointSendmail({ name: props.name }).pipe(
+        Effect.map((row) => ({
+          ...row,
+          'from-address': row.from_address,
+          'mailto-user': row.mailto_user,
+        })),
+      );
+    case 'smtp':
+      return config.getConfigNotificationEndpointSmtp({ name: props.name }).pipe(
+        Effect.map((row) => ({
+          ...row,
+          'from-address': row.from_address,
+          'mailto-user': row.mailto_user,
+        })),
+      );
+    case 'webhook':
+      return config
+        .getConfigNotificationEndpointWebhook({ name: props.name })
+        .pipe(Effect.map((row) => ({ ...row })));
+  }
+};
+
+export const readTarget = (props: Props) =>
+  runPbs(props.target, 'read', read(props)).pipe(
+    Effect.map((row) => targetAttributes(row, props)),
+    Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+  );
+
+/** No request: run the same translated-input validation before replacement can delete anything. */
+export const validateTargetWrite = (props: Props, form: PveForm, mode: 'create' | 'update') => {
+  const schema =
+    mode === 'create'
+      ? {
+          sendmail: config.CreateConfigNotificationEndpointSendmailRequest,
+          smtp: config.CreateConfigNotificationEndpointSmtpRequest,
+          webhook: config.CreateConfigNotificationEndpointWebhookRequest,
+        }[props.type]
+      : {
+          sendmail: config.PutConfigNotificationEndpointSendmailRequest,
+          smtp: config.PutConfigNotificationEndpointSmtpRequest,
+          webhook: config.PutConfigNotificationEndpointWebhookRequest,
+        }[props.type];
+  return notificationInput(schema, requestFields(props, form)).pipe(Effect.asVoid);
+};
+
+export const createTarget = (props: Props, form: PveForm) => {
+  const fields = requestFields(props, form);
+  const operation =
+    props.type === 'sendmail'
+      ? notificationInput(config.CreateConfigNotificationEndpointSendmailRequest, fields).pipe(
+          Effect.flatMap(config.createConfigNotificationEndpointSendmail),
+        )
+      : props.type === 'smtp'
+        ? notificationInput(config.CreateConfigNotificationEndpointSmtpRequest, fields).pipe(
+            Effect.flatMap(config.createConfigNotificationEndpointSmtp),
+          )
+        : notificationInput(config.CreateConfigNotificationEndpointWebhookRequest, fields).pipe(
+            Effect.flatMap(config.createConfigNotificationEndpointWebhook),
+          );
+  return runPbs(props.target, 'provision', operation);
+};
+
+export const updateTarget = (props: Props, form: PveForm) => {
+  const fields = requestFields(props, form);
+  const operation =
+    props.type === 'sendmail'
+      ? notificationInput(config.PutConfigNotificationEndpointSendmailRequest, fields).pipe(
+          Effect.flatMap(config.putConfigNotificationEndpointSendmail),
+        )
+      : props.type === 'smtp'
+        ? notificationInput(config.PutConfigNotificationEndpointSmtpRequest, fields).pipe(
+            Effect.flatMap(config.putConfigNotificationEndpointSmtp),
+          )
+        : notificationInput(config.PutConfigNotificationEndpointWebhookRequest, fields).pipe(
+            Effect.flatMap(config.putConfigNotificationEndpointWebhook),
+          );
+  return runPbs(props.target, 'provision', operation);
+};
+
+/** Built-ins still follow PBS's revert-on-delete semantics; missing objects are already deleted. */
+export const deleteTarget = (props: Props) => {
+  const request = { name: props.name };
+  const operation =
+    props.type === 'sendmail'
+      ? config.deleteConfigNotificationEndpointSendmail(request)
+      : props.type === 'smtp'
+        ? config.deleteConfigNotificationEndpointSmtp(request)
+        : config.deleteConfigNotificationEndpointWebhook(request);
+  return runPbs(props.target, 'provision', operation).pipe(
+    Effect.catchTag('NotFound', () => Effect.void),
+  );
+};

package/src/proxmox/pbs-notification-target-lifecycle.ts

@@ -14,7 +14,13 @@
 import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
 import * as Effect from 'effect/Effect';
-import { pve } from './client.ts';
+import {
+  createTarget,
+  deleteTarget,
+  readTarget as readLive,
+  updateTarget,
+  validateTargetWrite,
+} from './pbs-notification-target-distilled.ts';
 import { guardForm } from './constraint-guard.ts';
 import { pbsTargetEndpoint } from './pbs-notification-target-endpoint.ts';
 import type {
@@ -31,7 +37,6 @@ import {
   sealedState,
   targetForm,
 } from './pbs-notification-target-form.ts';
-import { targetAttributes } from './pbs-notification-target-wire.ts';
 import { seal } from '../secrets/write-only.ts';
 
 type Props = PbsNotificationTargetProps;
@@ -39,16 +44,6 @@ type Attributes = PbsNotificationTargetAttributes;
 
 const path = (props: Props) => `config/notifications/endpoints/${props.type}/${props.name}`;
 
-/**
- * ⚠️ A 404 and `{"data": null}` are answers here — and so, resource.ts's ⛔, is a 403. `pve()`
- *   returns `null` for the second, not `undefined`, so the test is `== null`.
- */
-const readLive = (props: Props) =>
-  pve<Record<string, unknown>>(props.target, 'read', 'GET', path(props)).pipe(
-    Effect.map((data) => (data == null ? undefined : targetAttributes(data, props))),
-    Effect.orElseSucceed(() => undefined),
-  );
-
 const refuse = (props: Props) => {
   const reasons = refusals(props);
   return reasons.length === 0
@@ -124,10 +119,25 @@ export const handlers = {
   }) =>
     Effect.gen(function* () {
       if (output === undefined || !isResolved(news)) return undefined;
+      yield* refuse(news);
       if (olds !== undefined && (olds.type !== news.type || olds.name !== news.name)) {
+        // ⛔ Preflight the destination before delete-first can remove a working target. A rename
+        // may adopt an existing endpoint; its write-only values have no seal from this resource.
+        const destination = yield* readLive(news);
+        const groups = resolveGroups(news);
+        const carry =
+          destination === undefined
+            ? { header: true, sealed: true }
+            : toCarry(destination, news, groups, '');
+        if (carry !== undefined) {
+          yield* requireValues(news, groups, carry);
+          const mode = destination === undefined ? 'create' : 'update';
+          const form = targetForm(news, groups, carry, mode);
+          yield* guardForm(pbsTargetEndpoint(news)[mode], form, destination === undefined);
+          yield* validateTargetWrite(news, form, mode);
+        }
         return { action: 'replace', deleteFirst: olds.name === news.name } as const;
       }
-      yield* refuse(news);
       const live = yield* readLive(news);
       if (live === undefined) return { action: 'update' } as const;
       return toCarry(live, news, resolveGroups(news), output.sealed) === undefined
@@ -143,7 +153,6 @@ export const handlers = {
       if (live === undefined) {
         const carry = { header: true, sealed: true } as const;
         yield* requireValues(news, groups, carry);
-        const collection = `config/notifications/endpoints/${news.type}`;
         const form = targetForm(news, groups, carry, 'create');
         /**
          * ⛔ WITH PRESENCE, BECAUSE THIS BRANCH IS UNCONDITIONALLY THE CREATE. PBS marks `name` on
@@ -153,7 +162,7 @@ export const handlers = {
          *   parameter NAME into its message (constraints.ts), so a refusal never quotes one.
          */
         yield* guardForm(pbsTargetEndpoint(news).create, form, true);
-        yield* pve(news.target, 'provision', 'POST', collection, form);
+        yield* createTarget(news, form);
         sealed = seal(groups.sealed.values);
       } else {
         const carry = toCarry(live, news, groups, sealed);
@@ -162,7 +171,7 @@ export const handlers = {
           const form = targetForm(news, groups, carry, 'update');
           /** ⚠️ NO PRESENCE: an update form is partial by design — it carries what `toCarry` said. */
           yield* guardForm(pbsTargetEndpoint(news).update, form, false);
-          yield* pve(news.target, 'provision', 'PUT', path(news), form);
+          yield* updateTarget(news, form);
           if (carry.sealed) sealed = seal(groups.sealed.values);
         }
       }
@@ -175,5 +184,5 @@ export const handlers = {
       }
       return { ...after, sealed } satisfies Attributes;
     }),
-  delete: ({ olds }: { olds: Props }) => pve(olds.target, 'provision', 'DELETE', path(olds)),
+  delete: ({ olds }: { olds: Props }) => deleteTarget(olds),
 };

package/src/proxmox/pbs-notification-target.ts

@@ -24,7 +24,7 @@
  *   the consequence. Read `origin` before declaring a name you did not create.
  *
  * ★ WHAT THIS NEEDS (generated/pbs.ts source): Sys.Audit on /system/notifications to read,
- *   Sys.Modify there to write. A datastore-scoped credential reads every target as absent.
+ *   Sys.Modify there to write. A datastore-scoped credential cannot read targets; its typed refusal now fails the plan.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';

package/src/proxmox/pbs-notifications-stack.test.ts

@@ -92,3 +92,28 @@ test('a new type under the same name replaces delete-first — names are unique
     'POST config/notifications/endpoints/sendmail',
   ]);
 });
+
+test('renaming a matcher replaces it instead of leaving the old route behind', async () => {
+  const fake = fakeNotify();
+  const declare = (name: string) =>
+    PbsNotificationMatcher('route', {
+      name,
+      target: PBS,
+      targets: ['mail-to-root'],
+    });
+  await withoutBao(async () => {
+    const engine = engineOver(
+      PbsNotificationMatcherProvider().pipe(Layer.provideMerge(fake.layer)),
+    );
+    await engine.deploy(declare('route-old'));
+    await engine.deploy(declare('route-new'));
+    expect((await engine.verify(declare('route-new'), { all: true })).rows[0]?.diff).toBe('noop');
+  });
+  expect(fake.objects.has('config/notifications/matchers/route-old')).toBe(false);
+  expect(fake.objects.has('config/notifications/matchers/route-new')).toBe(true);
+  expect(fake.writes()).toEqual([
+    'POST config/notifications/matchers',
+    'POST config/notifications/matchers',
+    'DELETE config/notifications/matchers/route-old',
+  ]);
+});

package/src/proxmox/pbs-prune-job-lifecycle.ts

@@ -0,0 +1,52 @@
+/** PBS 4.2.6-1 prune lifecycle; the SDK owns serialization and typed API errors. */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import { specGuards } from './resource-guard.ts';
+import type { PruneJobAttributes, PruneJobProps } from './pbs-prune-job.ts';
+import { spec } from './pbs-prune-job-spec.ts';
+import { createOne, deleteOne, readOne, updateOne } from './pbs-prune-job-wire.ts';
+
+const { guardCreate, guardUpdate } = specGuards(spec);
+
+export const handlers = {
+  // ⛔ Explicit adoption only: a listed job may be somebody else's only backup policy.
+  list: () => Effect.succeed([]),
+  read: ({ olds }: { olds: PruneJobProps }) => readOne(olds),
+  diff: ({
+    news,
+    output,
+  }: {
+    news: Input<PruneJobProps>;
+    output: PruneJobAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* guardCreate(news, output === undefined);
+      yield* guardUpdate(news);
+      if (output === undefined) return undefined;
+      const live = yield* readOne(news);
+      if (live === undefined) {
+        yield* guardCreate(news, true);
+        return { action: 'update' } as const;
+      }
+      return { action: spec.matches(live, news) ? 'noop' : 'update' } as const;
+    }),
+  reconcile: ({ news }: { news: PruneJobProps }) =>
+    Effect.gen(function* () {
+      const live = yield* readOne(news);
+      yield* guardCreate(news, live === undefined);
+      yield* guardUpdate(news);
+      if (live === undefined) yield* createOne(news);
+      else if (!spec.matches(live, news)) yield* updateOne(news);
+      // ⛔ A successful write is not evidence of a job; read it back through the SDK.
+      const after = yield* readOne(news);
+      if (after === undefined) {
+        return yield* Effect.fail(
+          new Error(`${spec.path(news)}: write succeeded but job is absent.`),
+        );
+      }
+      return after;
+    }),
+  delete: ({ olds }: { olds: PruneJobProps }) => deleteOne(olds),
+};

package/src/proxmox/pbs-prune-job-spec.ts

@@ -0,0 +1,53 @@
+/** PBS 4.2.6-1 values and vendor form guards; SDK transport is in pbs-prune-job-wire.ts. */
+import type { PruneJobAttributes, PruneJobProps } from './pbs-prune-job.ts';
+import type { PveSpec } from './resource-spec.ts';
+import { createBody, keepAttributes, keepsMatch, updateBody } from './pbs-prune-job-form.ts';
+import { bool, int, text } from './values.ts';
+
+/** "Not declared, or equal" — the single shape every unmanaged field is compared with. */
+const same = <T>(declared: T | undefined, live: T) => declared === undefined || declared === live;
+
+export const spec: PveSpec<PruneJobProps, PruneJobAttributes> = {
+  /**
+   * ⚠️ EVERY OPTIONAL FIELD FALLS BACK TO ITS ABSENT SENTINEL RATHER THAN TO PBS'S DEFAULT, because
+   *   for this family the two are different questions. `keep-daily` absent does not mean "keep zero
+   *   dailies", it means "this window is not part of the policy", and `matches` must not compare a
+   *   window the declaration never mentioned against an invented value.
+   * ⛔ NO "IS IT REALLY THERE" GUARD, for backup-job.ts's reason: returning undefined for a job
+   *   whose JSON is missing a key would be a guess about which keys PBS echoes, and a wrong guess
+   *   sends reconcile down the POST branch — which creates ANOTHER prune job rather than failing.
+   */
+  attributes: (live, props) => ({
+    comment: text(live['comment'], ''),
+    disable: bool(live['disable'], false),
+    id: props.id,
+    ...keepAttributes(live),
+    'max-depth': int(live['max-depth'], -1),
+    ns: text(live['ns'], ''),
+    schedule: text(live['schedule'], ''),
+    store: text(live['store'], props.store),
+  }),
+  collection: () => 'config/prune',
+  createForm: createBody,
+  /**
+   * ⚠️ THE UNDECLARED HALF IS NOT COMPARED, AND THAT IS THE WHOLE SAFETY MODEL. `same` reads "not
+   *   declared, or equal", so a field set by hand on an adopted job survives adoption untouched and
+   *   never appears as drift. `keepsMatch` applies the identical rule to the six windows, from the
+   *   file that also writes and reads them — see the ★ at the top of pbs-prune-job-form.ts.
+   * ⚠️ `store` AND `schedule` HAVE NO UNDECLARED CASE because both are required props, so both are
+   *   compared unconditionally. A changed `store` is an update, not a replace: PBS accepts `store`
+   *   on PUT, so the job is re-pointed in place.
+   */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pbs:POST /config/prune', update: 'pbs:PUT /config/prune/{id}' },
+  matches: (attributes, props) =>
+    attributes.schedule === props.schedule &&
+    attributes.store === props.store &&
+    same(props.ns, attributes.ns) &&
+    same(props['max-depth'], attributes['max-depth']) &&
+    same(props.disable, attributes.disable) &&
+    same(props.comment, attributes.comment) &&
+    keepsMatch(attributes, props),
+  path: (props) => `config/prune/${props.id}`,
+  updateForm: updateBody,
+};

package/src/proxmox/pbs-prune-job-wire.ts

@@ -0,0 +1,68 @@
+/** PBS 4.2.6-1 operations through @distilled.cloud/proxmox-backup. */
+import * as config from '@distilled.cloud/proxmox-backup/config';
+import * as Effect from 'effect/Effect';
+import { runPbs } from './distilled-pbs.ts';
+import type { PruneJobProps } from './pbs-prune-job.ts';
+import { createBody, updateBody } from './pbs-prune-job-form.ts';
+import { spec } from './pbs-prune-job-spec.ts';
+
+/** SDK member names differ from the vendor form names; omission stays unmanaged. */
+const members = (form: Record<string, string>) => ({
+  ...(form['comment'] === undefined ? {} : { comment: form['comment'] }),
+  ...(form['disable'] === undefined ? {} : { disable: form['disable'] }),
+  ...(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['max-depth'] === undefined ? {} : { max_depth: form['max-depth'] }),
+  ...(form['ns'] === undefined ? {} : { ns: form['ns'] }),
+  ...(form['schedule'] === undefined ? {} : { schedule: form['schedule'] }),
+  ...(form['store'] === undefined ? {} : { store: form['store'] }),
+});
+
+const createRequest = (props: PruneJobProps): config.CreateConfigPruneRequest => ({
+  ...members(createBody(props)),
+  id: props.id,
+  store: props.store,
+  schedule: props.schedule,
+});
+
+const updateRequest = (props: PruneJobProps): config.PutConfigPruneRequest => ({
+  ...members(updateBody(props)),
+  id: props.id,
+});
+
+/** Preserve the state attribute shape while the SDK decodes its typed field names. */
+const wire = (row: config.GetConfigPruneResponse): Record<string, unknown> => ({
+  ...row,
+  '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,
+  'max-depth': row.max_depth,
+});
+
+/** ⛔ Only the SDK PruneJobNotFound is absence; permission, transport and malformed replies propagate. */
+export const readOne = (props: PruneJobProps) =>
+  runPbs(props.target, 'read', config.getConfigPrune({ id: props.id })).pipe(
+    Effect.map((row) => spec.attributes(wire(row), props)),
+    Effect.catchTag('PruneJobNotFound', () => Effect.succeed(undefined)),
+  );
+
+export const createOne = (props: PruneJobProps) =>
+  runPbs(props.target, 'provision', config.createConfigPrune(createRequest(props)));
+
+export const updateOne = (props: PruneJobProps) =>
+  runPbs(props.target, 'provision', config.putConfigPrune(updateRequest(props)));
+
+/** Deleting the schedule never deletes backups; already missing is a successful deletion. */
+export const deleteOne = (props: PruneJobProps) =>
+  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.deleteConfigPrune({ id: props.id }));
+  });

package/src/proxmox/pbs-prune-job.ts

@@ -1,6 +1,6 @@
 /**
  * `Pbs.PruneJob` — a Proxmox Backup Server retention schedule, declared. PBS is a SIBLING of PVE,
- * so this family reuses `pveHandlers` wholesale rather than growing a second factory.
+ * and this family uses its own distilled SDK's typed config operations (PBS 4.2.6-1).
  *
  * ⛔ THIS IS THE ONE RESOURCE IN THIS PACKAGE THAT DESTROYS DATA ON AN ORDINARY *UPDATE*. CephPool,
  *   ZfsPool and Storage can destroy data too — which is exactly why they default to `retain` and
@@ -26,8 +26,9 @@
  *   `-1` in the attributes means "absent from prune.cfg", the sentinel storage.ts uses for
  *   `maxfiles`, because `0` here is a real and very different setting.
  *
- * ⛔ THE CREDENTIAL DOES NOT EXIST YET, SO NOTHING BELOW HAS EVER MADE A CALL. PBS is a different
- *   host and a different auth realm from PVE. MEASURED 2026-09-13: pbs.example.com:8007 answers
+ * ⚠️ HISTORICAL BOOTSTRAP BLOCKER, 2026-09-13: PBS was a different
+ *   host and auth realm from PVE. The later PBS credential lane and SDK resolved this blocker.
+ *   MEASURED 2026-09-13: pbs.example.com:8007 answers
  *   HTTP 401 under STRICT TLS behind a real Let's Encrypt certificate (CN=pbs.example.com, issuer
  *   YR1, valid 2026-09-02 to 2026-12-01) — so there is no `-k` to reach for and `client.ts` needs
  *   no TLS escape hatch, exactly as on PVE. What it does need is a header it cannot build today.
@@ -47,7 +48,7 @@
  * ★ WHAT A `PbsTarget` NEEDS, AND WHY IT IS ALMOST `PveTarget`. Structurally `PveTarget` already
  *   fits a PBS host: a credential mount name and an `/api2/json` base are the whole of it, and PBS
  *   shares the `{"data": …}` envelope, the four-operation shape and the read-back discipline —
- *   which is exactly why this file declares a spec and stops. The single thing `PveTarget` cannot
+ *   which is why the pure spec survives the SDK transport migration. The single thing `PveTarget` cannot
  *   carry is WHICH AUTHORIZATION SCHEME the host at the other end speaks, so `PbsTarget` below adds
  *   that and nothing else rather than bending the PVE type in silence.
  *
@@ -55,9 +56,9 @@
  *   below are MEASURED from the PBS API as published at pbs.proxmox.com/docs/api-viewer, fetched
  *   2026-09-13 — current PBS 4.x. Before PBS 2.2 there was no `/config/prune` at all: retention
  *   lived on the datastore section itself, as `keep-*` plus `prune-schedule` under
- *   `/config/datastore/{name}`. Against anything older every path here 404s, `pveOperations.read`
- *   folds that into "absent", and the plan says create forever. Check `GET /api2/json/version`
- *   before the first plan.
+ *   `/config/datastore/{name}`. The old `pveOperations.read` folded those 404s into "absent",
+ *   producing a create forever. The SDK path now propagates an unknown route's 404; only the
+ *   vendor's typed missing-prune response means absent. Check the PBS version before planning.
  *
  * ★ THE READ LANE NEEDS NOTHING EXTRA, UNLIKE THREE PVE FAMILIES — so there is no `readRole:
  *   'provision'` below and there should not be one. MEASURED: `GET /config/prune/{id}` requires
@@ -79,10 +80,9 @@
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
+import { handlers } from './pbs-prune-job-lifecycle.ts';
 import type { PbsTarget } from './credentials.ts';
-import { createBody, keepAttributes, keepsMatch, updateBody } from './pbs-prune-job-form.ts';
-import { type PveRequirements, type WithPbsTarget, pveHandlers } from './resource.ts';
-import { bool, int, text } from './values.ts';
+import type { PveRequirements, WithPbsTarget } from './resource-spec.ts';
 
 /**
  * ⚠️ THE PROPS ARE PBS'S OWN KEY NAMES, HYPHENS INCLUDED, for backup-job.ts's reason: the form
@@ -160,54 +160,6 @@ export interface PbsPruneJob extends Resource<
  */
 export const PbsPruneJob = Resource<PbsPruneJob>('Pbs.PruneJob');
 
-/** "Not declared, or equal" — the single shape every unmanaged field is compared with. */
-const same = <T>(declared: T | undefined, live: T) => declared === undefined || declared === live;
-
-const handlers = pveHandlers<PruneJobProps, PruneJobAttributes>({
-  /**
-   * ⚠️ EVERY OPTIONAL FIELD FALLS BACK TO ITS ABSENT SENTINEL RATHER THAN TO PBS'S DEFAULT, because
-   *   for this family the two are different questions. `keep-daily` absent does not mean "keep zero
-   *   dailies", it means "this window is not part of the policy", and `matches` must not compare a
-   *   window the declaration never mentioned against an invented value.
-   * ⛔ NO "IS IT REALLY THERE" GUARD, for backup-job.ts's reason: returning undefined for a job
-   *   whose JSON is missing a key would be a guess about which keys PBS echoes, and a wrong guess
-   *   sends reconcile down the POST branch — which creates ANOTHER prune job rather than failing.
-   */
-  attributes: (live, props) => ({
-    comment: text(live['comment'], ''),
-    disable: bool(live['disable'], false),
-    id: props.id,
-    ...keepAttributes(live),
-    'max-depth': int(live['max-depth'], -1),
-    ns: text(live['ns'], ''),
-    schedule: text(live['schedule'], ''),
-    store: text(live['store'], props.store),
-  }),
-  collection: () => 'config/prune',
-  createForm: createBody,
-  /**
-   * ⚠️ THE UNDECLARED HALF IS NOT COMPARED, AND THAT IS THE WHOLE SAFETY MODEL. `same` reads "not
-   *   declared, or equal", so a field set by hand on an adopted job survives adoption untouched and
-   *   never appears as drift. `keepsMatch` applies the identical rule to the six windows, from the
-   *   file that also writes and reads them — see the ★ at the top of pbs-prune-job-form.ts.
-   * ⚠️ `store` AND `schedule` HAVE NO UNDECLARED CASE because both are required props, so both are
-   *   compared unconditionally. A changed `store` is an update, not a replace: PBS accepts `store`
-   *   on PUT, so the job is re-pointed in place.
-   */
-  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
-  endpoint: { create: 'pbs:POST /config/prune', update: 'pbs:PUT /config/prune/{id}' },
-  matches: (attributes, props) =>
-    attributes.schedule === props.schedule &&
-    attributes.store === props.store &&
-    same(props.ns, attributes.ns) &&
-    same(props['max-depth'], attributes['max-depth']) &&
-    same(props.disable, attributes.disable) &&
-    same(props.comment, attributes.comment) &&
-    keepsMatch(attributes, props),
-  path: (props) => `config/prune/${props.id}`,
-  updateForm: updateBody,
-});
-
 /**
  * ⛔ `list` IS EMPTY like every other family here, and the stakes are the usual ones read backwards.
  *   `GET /config/prune` hands back every prune job on the server, the ones an operator tuned by

package/src/proxmox/pbs-sync-job-attributes.ts

@@ -0,0 +1,33 @@
+/** Stable PBS sync-job state; only vendor configuration, never runtime task status. */
+export interface SyncJobAttributes {
+  /** From the props — it is the path this object was read by. */
+  id: string;
+  store: string;
+  /** `''` is the root namespace, which is also how PBS spells it. */
+  ns: string;
+  /** `''` means a LOCAL sync — datastore to datastore on this PBS. */
+  remote: string;
+  'remote-store': string;
+  'remote-ns': string;
+  /** `''` means the job runs only when somebody starts it. */
+  schedule: string;
+  comment: string;
+  'remove-vanished': boolean;
+  /** ⚠️ Absent on the wire means `false`, PBS's own default. */
+  'verified-only': boolean;
+  /** `''` means no owner in the config, i.e. `root@pam` at runtime. An identifier, never a secret. */
+  owner: string;
+  /** Bytes per second, or `UNSET` (-1). See `bytes()`. */
+  'rate-in': number;
+  /** `UNSET` (-1) means unset, which means full recursion. `0` is a real value meaning none. */
+  'max-depth': number;
+  /** `UNSET` (-1) means all snapshots. */
+  'transfer-last': number;
+  /**
+   * ⚠️ REPORTED, NEVER SENT, NEVER COMPARED — the live filter list joined for display only. See the
+   *   ⛔ on the prop for why it is not declarable.
+   */
+  'group-filter': string;
+  /** `pull` or `push`. Reported, never compared — create-only here. */
+  'sync-direction': string;
+}

package/src/proxmox/pbs-sync-job-form.ts

@@ -7,17 +7,18 @@ import type { SyncJobAttributes, SyncJobProps } from './pbs-sync-job.ts';
  *   with the wire instead of staying with the props. The `import type` back is a cycle on paper
  *   only — erased before anything runs, so the runtime arrow points one way, resource to wire.
  *
- * ★ IT USES THE SHARED PVE CLIENT, NOT A PBS ONE. An earlier draft of this file was written
+ * ★ HISTORICALLY IT USED THE SHARED PVE CLIENT, NOT A PBS ONE. An earlier draft of this file was written
  *   against a `./pbs-client.ts` that never existed, and spelled out what it would have to export.
  *   That module is not needed: PBS speaks the same `/api2/json` paths and the same `{"data": …}`
  *   envelope, its OpenBao mount vends the same `{token_id, secret}`, and the only difference is
  *   the authorization header — so `PveTarget` carries a `scheme` and `authorization()` spells
- *   `PBSAPIToken=<id>:<secret>` for `'pbs'`. `pveHandlers` and `pveOperations` work unchanged.
+ *   `PBSAPIToken=<id>:<secret>` for `'pbs'`. The SDK now owns that header; the pure spec below
+ *   preserves the existing field and retention semantics.
  *   The one PBS-specific thing that survived is the FORM TYPE: PBS decodes a multi-valued field
- *   from repeated keys, and `PveForm` in client.ts admits a list for exactly that reason.
+ *   from repeated keys, and the distilled PBS protocol must preserve that encoding.
 
  */
-import { pveHandlers } from './resource.ts';
+import type { PveSpec } from './resource-spec.ts';
 import { bool, int, text } from './values.ts';
 
 /**
@@ -150,7 +151,7 @@ export const createBody = (props: SyncJobProps): Record<string, string> => ({
  */
 export const updateBody = (props: SyncJobProps): Record<string, string> => shape(props);
 
-export const handlers = pveHandlers<SyncJobProps, SyncJobAttributes>({
+export const spec: PveSpec<SyncJobProps, SyncJobAttributes> = {
   /**
    * ⛔ NO "IS IT REALLY THERE" GUARD, for backup-job.ts's reason: absence is the API declining to
    *   answer, which the factory's `read` already handles, not a key missing from an answer that did
@@ -233,4 +234,4 @@ export const handlers = pveHandlers<SyncJobProps, SyncJobAttributes>({
   /** ⚠️ A Proxmox safe id has no `/` or `:` in it, so there is nothing here to encode. */
   path: (props) => `config/sync/${props.id}`,
   updateForm: updateBody,
-});
+};