@homeflare/alchemy 0.37.2 → 0.37.4

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

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

@@ -0,0 +1,46 @@
+/** PBS 4.2.6-1 sync 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 { SyncJobAttributes, SyncJobProps } from './pbs-sync-job.ts';
+import { spec } from './pbs-sync-job-form.ts';
+import { createOne, deleteOne, readOne, updateOne } from './pbs-sync-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: SyncJobProps }) => readOne(olds),
+  diff: ({ news, output }: { news: Input<SyncJobProps>; output: SyncJobAttributes | 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: SyncJobProps }) =>
+    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: SyncJobProps }) => deleteOne(olds),
+};

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

@@ -0,0 +1,71 @@
+/** 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 { SyncJobProps } from './pbs-sync-job.ts';
+import { createBody, spec, updateBody } from './pbs-sync-job-form.ts';
+
+/** SDK member names differ from the vendor form names; omission stays unmanaged. */
+const members = (form: Record<string, string>) => ({
+  ...(form['remote-store'] === undefined ? {} : { remote_store: form['remote-store'] }),
+  ...(form['remove-vanished'] === undefined ? {} : { remove_vanished: form['remove-vanished'] }),
+  ...(form['store'] === undefined ? {} : { store: form['store'] }),
+  ...(form['comment'] === undefined ? {} : { comment: form['comment'] }),
+  ...(form['max-depth'] === undefined ? {} : { max_depth: form['max-depth'] }),
+  ...(form['ns'] === undefined ? {} : { ns: form['ns'] }),
+  ...(form['owner'] === undefined ? {} : { owner: form['owner'] }),
+  ...(form['rate-in'] === undefined ? {} : { rate_in: form['rate-in'] }),
+  ...(form['remote'] === undefined ? {} : { remote: form['remote'] }),
+  ...(form['remote-ns'] === undefined ? {} : { remote_ns: form['remote-ns'] }),
+  ...(form['schedule'] === undefined ? {} : { schedule: form['schedule'] }),
+  ...(form['verified-only'] === undefined ? {} : { verified_only: form['verified-only'] }),
+  ...(form['transfer-last'] === undefined ? {} : { transfer_last: form['transfer-last'] }),
+  ...(form['sync-direction'] === undefined ? {} : { sync_direction: form['sync-direction'] }),
+});
+
+const createRequest = (props: SyncJobProps): config.SyncConfigRequest => ({
+  ...members(createBody(props)),
+  id: props.id,
+  store: props.store,
+  remote_store: props['remote-store'],
+});
+
+const updateRequest = (props: SyncJobProps): config.PutConfigSyncRequest => ({
+  ...members(updateBody(props)),
+  id: props.id,
+});
+
+/** Preserve the state attribute shape while the SDK decodes its typed field names. */
+const wire = (row: config.GetConfigSyncResponse): Record<string, unknown> => ({
+  ...row,
+  'remote-store': row.remote_store,
+  'remove-vanished': row.remove_vanished,
+  'max-depth': row.max_depth,
+  'rate-in': row.rate_in,
+  'remote-ns': row.remote_ns,
+  'verified-only': row.verified_only,
+  'transfer-last': row.transfer_last,
+  'sync-direction': row.sync_direction,
+  'group-filter': row.group_filter,
+});
+
+/** ⛔ Only the SDK SyncJobNotFound is absence; permission, transport and malformed replies propagate. */
+export const readOne = (props: SyncJobProps) =>
+  runPbs(props.target, 'read', config.getConfigSync({ id: props.id })).pipe(
+    Effect.map((row) => spec.attributes(wire(row), props)),
+    Effect.catchTag('SyncJobNotFound', () => Effect.succeed(undefined)),
+  );
+
+export const createOne = (props: SyncJobProps) =>
+  runPbs(props.target, 'provision', config.syncConfig(createRequest(props)));
+
+export const updateOne = (props: SyncJobProps) =>
+  runPbs(props.target, 'provision', config.putConfigSync(updateRequest(props)));
+
+/** Deleting the schedule never deletes backups; already missing is a successful deletion. */
+export const deleteOne = (props: SyncJobProps) =>
+  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.deleteConfigSync({ id: props.id }));
+  });

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

@@ -35,8 +35,8 @@
  *     `/api2/json/config/sync` is not even evidence that the endpoint exists. THE FIRST PLAN
  *     AGAINST A LIVE PBS IS THE MEASUREMENT. Read it; do not deploy it unseen.
  *   ⚠️ AN ERROR BODY IS NOT WRAPPED: the 401 body is the bare text `authentication failed`, not
- *     JSON. `pve()` checks `response.ok` before it parses, so a `pbs()` copied from it is safe —
- *     provided the check stays in that order.
+ *     JSON. The original `pve()` checked status before decoding success data. The distilled PBS
+ *     protocol preserves this distinction and classifies error text through SDK patches.
  *
  * ⚠️ `Proxmox.BackupJob` AND `Pbs.SyncJob` ARE NOT THE SAME FAMILY AND THE NAMES NEARLY COLLIDE.
  *   The first is a PVE vzdump schedule; this is a Proxmox Backup SERVER sync job, on a different
@@ -55,7 +55,9 @@
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { handlers } from './pbs-sync-job-form.ts';
+import { handlers } from './pbs-sync-job-lifecycle.ts';
+import type { SyncJobAttributes } from './pbs-sync-job-attributes.ts';
+export type { SyncJobAttributes } from './pbs-sync-job-attributes.ts';
 import type { PveRequirements } from './resource.ts';
 import type { WithPbsTarget } from './resource.ts';
 
@@ -158,10 +160,10 @@ export interface SyncJobProps extends WithPbsTarget {
   'transfer-last'?: number;
   /**
    * ⛔ NOT DECLARABLE, AND A COMPILE ERROR RATHER THAN A PROP THAT HALF WORKS — the storage.ts
-   *   `password` idiom, for two independent reasons, either of which alone would be enough.
+   *   `password` idiom. Two barriers originally applied; the second remains unresolved.
    *   1. THE WIRE FORM IS AN ARRAY. PBS takes `group-filter` as a repeated parameter
-   *      (`group-filter=type:ct&group-filter=regex:^web`), and `pve()`'s form is
-   *      `Record<string, string>` — one value per key — so a list cannot be expressed at all.
+   *      (`group-filter=type:ct&group-filter=regex:^web`). The old single-value form could not
+   *      express it; the distilled PBS protocol now supports repeated keys.
    *   2. NARROWING A FILTER MAY BE A DELETE. Whether `remove-vanished` skips the groups a filter
    *      excludes is NOT something I could measure without a credential. If it does not, then
    *      editing this field on a job with `remove-vanished` set removes every local group the new
@@ -169,8 +171,8 @@ export interface SyncJobProps extends WithPbsTarget {
    *      half-working prop.
    *   ★ IT IS STILL REPORTED in the attributes, so a plan shows the filters a hand-made job carries
    *     and this resource never strips them: undeclared is unmanaged, and PBS's update assigns only
-   *     what it was sent. To make it declarable, fix both halves — a form type that can repeat a
-   *     key, and a MEASURED answer to (2) — in that order.
+   *     what it was sent. Making it declarable still needs a MEASURED answer to (2), even though
+   *     the SDK now supplies the necessary repeated-key transport.
    */
   'group-filter'?: never;
   /**
@@ -196,39 +198,6 @@ export interface SyncJobProps extends WithPbsTarget {
   'verified-only'?: boolean;
 }
 
-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;
-}
-
 export interface PbsSyncJob extends Resource<
   'Pbs.SyncJob',
   SyncJobProps,

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

@@ -0,0 +1,52 @@
+/** PBS 4.2.6-1 verify 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 { PbsVerifyJobAttributes, PbsVerifyJobProps } from './pbs-verify-job.ts';
+import { spec } from './pbs-verify-job-spec.ts';
+import { createOne, deleteOne, readOne, updateOne } from './pbs-verify-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: PbsVerifyJobProps }) => readOne(olds),
+  diff: ({
+    news,
+    output,
+  }: {
+    news: Input<PbsVerifyJobProps>;
+    output: PbsVerifyJobAttributes | 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: PbsVerifyJobProps }) =>
+    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: PbsVerifyJobProps }) => deleteOne(olds),
+};