@homeflare/alchemy 0.1.0

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

@@ -0,0 +1,234 @@
+import type { SyncJobAttributes, SyncJobProps } from './pbs-sync-job.ts';
+/**
+ * A sync job on the wire: how a PBS answer becomes comparable values, how a declaration becomes a
+ * create or an update, and — because that question is downstream of this one — when it has changed.
+ *
+ * ★ SPLIT OUT OF pbs-sync-job.ts FOR THE 250-LINE CAP; the ★ SEAM there says why `matches` came
+ *   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
+ *   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.
+ *   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.
+
+ */
+import { pveHandlers } from './resource.ts';
+import { bool, int, text } from './values.ts';
+
+/**
+ * The marker for "PBS has no value for this number".
+ *
+ * ⚠️ `-1` RATHER THAN `0`, AND metric-server.ts's `UNSET = -1` IS THE PRECEDENT. `max-depth` has a
+ *   legal value of 0 — sync this namespace and no child of it — which is a completely different
+ *   instruction from the absent field, where PBS recurses as deep as it is allowed. Using 0 as the
+ *   marker would make "no recursion" and "full recursion" the same attribute. `rate-in` and
+ *   `transfer-last` take the same marker for uniformity rather than because 0 is legal for them:
+ *   depending on a schema minimum I could not measure is exactly the kind of guess that becomes a
+ *   forever-diff.
+ */
+export const UNSET = -1;
+
+/** ⚠️ BINARY AND DECIMAL BOTH, because PBS's HumanByte can print either and parses both. */
+const UNITS: Record<string, number> = {
+  '': 1,
+  B: 1,
+  GB: 1e9,
+  GiB: 1073741824,
+  KB: 1e3,
+  KiB: 1024,
+  MB: 1e6,
+  MiB: 1048576,
+  TB: 1e12,
+  TiB: 1099511627776,
+};
+
+/**
+ * A PBS rate limit off the wire, as a plain byte count.
+ *
+ * ⛔ THE VALUE GOES OUT AS A NUMBER AND COMES BACK AS PROSE. PBS types `rate-in` as a `HumanByte`,
+ *   which parses `10485760` on the way in and prints something like `10.00 MiB` on the way out, so
+ *   the two sides of a comparison are never the same string. Flattening both to bytes is what makes
+ *   the field comparable at all. REASONED from the type's parse/print asymmetry, NOT measured —
+ *   there was no credential to round-trip one with.
+ * ⚠️ IT ROUNDS, AND A RATE THAT DOES NOT DIVIDE EVENLY WILL NEVER SETTLE. `10.00 MiB` carries two
+ *   decimals, so a declared 10485761 reads back as 10485760, `matches` reports an update, the PUT
+ *   writes the same rounded value, and the next plan reports it again — forever. Declare a whole
+ *   multiple of a binary unit. This is the likeliest forever-diff in the family and the first thing
+ *   to check on the first plan against a live PBS.
+ * ⚠️ AN UNPARSEABLE ANSWER READS AS `UNSET`, which for a DECLARED rate means "not equal" and so an
+ *   update rather than a silent noop. Wrong-but-loud is the right way round here.
+ */
+export const bytes = (value: unknown): number => {
+  if (typeof value === 'number') return value;
+  const raw = text(value).trim();
+  const match = /^([0-9]+(?:\.[0-9]+)?)\s*([A-Za-z]*)$/.exec(raw);
+  if (match === null) return UNSET;
+  const unit = UNITS[match[2] ?? ''];
+  return unit === undefined ? UNSET : Math.round(Number(match[1] ?? '0') * unit);
+};
+
+/**
+ * The live group filters, joined for a human.
+ *
+ * ⚠️ DISPLAY ONLY — NEVER SENT, NEVER COMPARED. The ⛔ on the `group-filter` prop says why the field
+ *   is not declarable; this exists so that a plan against an adopted job SHOWS the filters this
+ *   resource is deliberately leaving alone, rather than making them invisible.
+ * ⚠️ THE SEPARATOR IS ` | `, NOT A COMMA: a `regex:` filter may contain either, so no join here is
+ *   unambiguous — and a comma is the one that would invite somebody to parse this back.
+ */
+export const filters = (value: unknown): string =>
+  Array.isArray(value) ? value.map((entry: unknown) => String(entry)).join(' | ') : text(value);
+
+/**
+ * The half of a declaration that create and update both send.
+ *
+ * ⛔ `remove-vanished` IS ALWAYS SENT, AT ITS DEFAULT INCLUDED, and that is the one field here that
+ *   breaks the "undeclared is unmanaged" rule on purpose. It is always COMPARED (see `matches`), and
+ *   backup-job.ts records why the two must agree: a field compared against a default but not sent as
+ *   that default is an update reported on every plan that the PUT never performs. `0` is the
+ *   direction that does not delete; the prop says why that is still not a free edit.
+ * ⚠️ THE TERNARY IS NOT A REFUSAL TO REUSE values.ts's `flag()`; IT IS WHAT `flag()` IS DOCUMENTED
+ *   NOT TO DO. That coercion answers `undefined` for an undeclared boolean precisely so an omitted
+ *   field is never sent — it is the tool for "send it only if declared", and this is the one field
+ *   that must be sent ALWAYS. Calling it here types as `string | undefined` and tsc rejects the
+ *   form (MEASURED: TS2322, "Type 'undefined' is not assignable to type 'string'"), which is the
+ *   type system saying the same thing. replication-job-form.ts writes its always-sent `disable` the
+ *   same way, for the same reason.
+ * ⚠️ `1`/`0` RATHER THAN `true`/`false`: PBS's boolean schema accepts both spellings (DOCUMENTED),
+ *   and one spelling shared with the PVE families is one fewer thing to keep in step.
+ * ⚠️ EVERY OTHER FIELD IS SPREAD IN ONLY WHEN DECLARED. An undeclared key is not sent, so PBS leaves
+ *   it exactly as it is — which is what makes adopting a hand-made job non-destructive.
+ */
+const shape = (props: SyncJobProps) => ({
+  'remote-store': props['remote-store'],
+  'remove-vanished': props['remove-vanished'] === true ? '1' : '0',
+  store: props.store,
+  ...(props.comment === undefined ? {} : { comment: props.comment }),
+  ...(props['max-depth'] === undefined ? {} : { 'max-depth': String(props['max-depth']) }),
+  ...(props.ns === undefined ? {} : { ns: props.ns }),
+  ...(props.owner === undefined ? {} : { owner: props.owner }),
+  ...(props['rate-in'] === undefined ? {} : { 'rate-in': String(props['rate-in']) }),
+  ...(props.remote === undefined ? {} : { remote: props.remote }),
+  ...(props['remote-ns'] === undefined ? {} : { 'remote-ns': props['remote-ns'] }),
+  ...(props.schedule === undefined ? {} : { schedule: props.schedule }),
+  ...(props['verified-only'] === undefined
+    ? {}
+    : { 'verified-only': props['verified-only'] ? '1' : '0' }),
+  ...(props['transfer-last'] === undefined
+    ? {}
+    : { 'transfer-last': String(props['transfer-last']) }),
+});
+
+/**
+ * ⛔ `id` IS SENT AND IS NOT OPTIONAL. PBS's create takes it rather than inventing one, so this
+ *   family avoids backup-job.ts's worst failure by construction — but only while the id is here.
+ *   A POST without one would be refused rather than silently duplicating the job, which is the
+ *   better failure, and it is still not a reason to leave it out.
+ * ⛔ `sync-direction` IS THE ONE FIELD SENT ONLY ON CREATE. It decides which side `remove-vanished`
+ *   deletes from, it is not compared (see `matches`), and on a PBS old enough to have no push
+ *   support it is an unknown parameter — so sending it on every update would turn every deploy
+ *   against such a server into a 400 over a field nobody was changing.
+ */
+export const createBody = (props: SyncJobProps): Record<string, string> => ({
+  ...shape(props),
+  id: props.id,
+  ...(props['sync-direction'] === undefined ? {} : { 'sync-direction': props['sync-direction'] }),
+});
+
+/**
+ * ⚠️ THE UPDATE IS THE SHARED HALF AND NOTHING ELSE — no `id` (it is the path), no
+ *   `sync-direction`, no `delete` list. The factory only PUTs when `matches` is false and the form
+ *   is non-empty, and this form is never empty because `remove-vanished` and the two store names
+ *   are always present. That is fine here: reconcile reaches this line only when something really
+ *   does differ, and re-sending the two store names it just compared is a write of what is already
+ *   there rather than a change.
+ */
+export const updateBody = (props: SyncJobProps): Record<string, string> => shape(props);
+
+export const handlers = pveHandlers<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
+   *   arrive. Every fallback below is PBS's documented default rather than one picked for
+   *   convenience, so the answer does not depend on whether a release echoes a key it never wrote.
+   * ⛔ EXCEPT `store` AND `remote-store`, WHICH FALL BACK TO `''` RATHER THAN TO THE DECLARED VALUE.
+   *   They are the only required fields `matches` COMPARES, and a props-shaped fallback would make a
+   *   malformed answer compare EQUAL — drift that hides itself, where `''` can only be loud. `id`
+   *   keeps its props fallback: it is the path the object was read by, and is never compared.
+   * ⚠️ `digest` IS DELIBERATELY NOT AN ATTRIBUTE. PBS returns one for `sync.cfg` as a FILE, so
+   *   keeping it would rewrite this resource's state whenever an unrelated sync job was edited —
+   *   churn that reads like drift. ha-resource.ts hit exactly that on PVE.
+   * ⚠️ NEITHER IS THE RUN STATUS. `last-run-state`, `last-run-upid`, `last-run-endtime` and
+   *   `next-run` come from the LIST endpoint, not from `GET /config/sync/{id}` which this reads.
+   *   A plan whose output changes every time the job runs is a plan people stop reading.
+   */
+  attributes: (live, props) => ({
+    comment: text(live['comment'], ''),
+    'group-filter': filters(live['group-filter']),
+    id: props.id,
+    'max-depth': int(live['max-depth'], UNSET),
+    ns: text(live['ns'], ''),
+    owner: text(live['owner'], ''),
+    'rate-in': bytes(live['rate-in']),
+    remote: text(live['remote'], ''),
+    'remote-ns': text(live['remote-ns'], ''),
+    'remote-store': text(live['remote-store'], ''),
+    // ⚠️ PBS answers with a JSON `true`/`false` where PVE answers `1`/`0`; `bool` takes both, and
+    //   takes the string `'false'` correctly too if some release spells it that way.
+    'remove-vanished': bool(live['remove-vanished'], false),
+    schedule: text(live['schedule'], ''),
+    // ⚠️ ABSENT MEANS FALSE, the PBS-side default — so an undeclared prop and a job that never had
+    //   the field compare equal, and adopting one does not plan an edit.
+    'verified-only': bool(live['verified-only'], false),
+    store: text(live['store'], ''),
+    'sync-direction': text(live['sync-direction'], 'pull'),
+    'transfer-last': int(live['transfer-last'], UNSET),
+  }),
+  collection: () => 'config/sync',
+  createForm: createBody,
+  /**
+   * ⛔ ONLY FIELDS A WRITE CAN ACTUALLY SET ARE COMPARED, and on PBS that list is REASONED rather
+   *   than measured: the published update schema for `PUT /config/sync/{id}` takes every property
+   *   of the job except its `id`. If a release turns out to refuse one of these, the comparison
+   *   becomes an update the PUT cannot perform — reported on every plan, forever. That is what the
+   *   first plan against a live PBS is for.
+   * ⚠️ `remove-vanished` IS COMPARED UNCONDITIONALLY — undeclared means false. Every other optional
+   *   field reads "not declared, or equal": undeclared is UNMANAGED, so a schedule, comment, owner,
+   *   namespace or limit somebody set by hand survives adoption untouched. The destructive one does
+   *   not get that courtesy, and the price is that adopting a job with it switched on is a real
+   *   edit, announced only as "update" — toward not deleting, and toward a datastore that grows.
+   * ⚠️ `store` AND `remote-store` ARE COMPARED UNCONDITIONALLY because PBS requires them at create,
+   *   so there is no undeclared case to protect. `remote` is NOT: an absent `remote` on an existing
+   *   job would otherwise plan an update clearing it, and `remote=` is not a value PBS's id schema
+   *   accepts — a failing PUT on every deploy, over a field the declaration never mentioned.
+   * ⚠️ `id`, `group-filter` AND `sync-direction` ARE OUT. The first is the path, a change to which
+   *   is a different object; the other two are argued on their props in pbs-sync-job.ts.
+   */
+  matches: (attributes, props) =>
+    attributes['remove-vanished'] === (props['remove-vanished'] === true) &&
+    attributes.store === props.store &&
+    attributes['remote-store'] === props['remote-store'] &&
+    (props.remote === undefined || attributes.remote === props.remote) &&
+    (props.ns === undefined || attributes.ns === props.ns) &&
+    (props['remote-ns'] === undefined || attributes['remote-ns'] === props['remote-ns']) &&
+    (props.schedule === undefined || attributes.schedule === props.schedule) &&
+    (props.comment === undefined || attributes.comment === props.comment) &&
+    (props.owner === undefined || attributes.owner === props.owner) &&
+    // ⚠️ NOT COMPARED UNCONDITIONALLY, unlike `remove-vanished`. Turning `verified-only` ON is the
+    //   safe direction (sync less), so undeclared stays UNMANAGED like every other optional field;
+    //   `remove-vanished` gets the unconditional treatment because its unsafe direction deletes.
+    (props['verified-only'] === undefined ||
+      attributes['verified-only'] === props['verified-only']) &&
+    (props['rate-in'] === undefined || attributes['rate-in'] === props['rate-in']) &&
+    (props['max-depth'] === undefined || attributes['max-depth'] === props['max-depth']) &&
+    (props['transfer-last'] === undefined ||
+      attributes['transfer-last'] === props['transfer-last']),
+  /** ⚠️ 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.ts

@@ -0,0 +1,258 @@
+/**
+ * `Pbs.SyncJob` — one section of Proxmox Backup Server's `sync.cfg`, declared: a remote datastore's
+ * snapshots pulled into a local one on a schedule.
+ *
+ * ★ IT USES THE SHARED PVE CLIENT, AND THE TYPES STOP THE TWO HOSTS BEING SWAPPED. An earlier
+ *   draft imported a `./pbs-client.ts` that never existed, arguing that reusing the PVE machinery
+ *   would COMPILE and that this was the danger — a PBS host accepted wherever a PVE one belongs,
+ *   every call 401ing, `read` folding that into "absent". The argument was right and the fix is
+ *   the discriminant rather than a second client: `scheme` is REQUIRED on a target, so a PBS host
+ *   is not assignable to a PVE resource or the reverse, and the mistake is a compile error. See
+ *   the ⛔ on `scheme` in credentials.ts.
+ *
+ * ⛔ THE CREDENTIAL IS A PBS TOKEN AND IT DOES NOT EXIST YET; NO MOUNT NAME IS INVENTED IN THIS
+ *   FILE. PBS wants `user@realm!tokenname` plus a UUID secret, issued by PBS — a PVE token is not
+ *   one, whatever it is spelled like. MEASURED from this machine on 2026-09-13: the `claude-code`
+ *   approle cannot enumerate mounts (`bao secrets list` -> 403) and
+ *   `bao token capabilities kv/infra/proxmox/pbs` -> `deny`, so I could not confirm from here what
+ *   does or does not exist. What credentials.ts records is that every PBS token on the kv shelf is
+ *   READ-ONLY (`Audit`, as `monitoring@pve`) and STATIC — too narrow to create a sync job, and
+ *   exactly the kind of credential this provider exists to avoid writing with.
+ *   ★ SO THE MOUNT IS A `PbsTarget.mount` THE STACK SUPPLIES, and somebody has to build it first:
+ *     a dynamic PBS mount with `read` and `provision` roles mirroring `proxmox-tb4`. Until it
+ *     exists this family can be declared and cannot be deployed. `permission denied` means the
+ *     grant is missing — say which mount and role you needed; do not fall back to the shelf token.
+ *
+ * ⚠️ WHAT IS MEASURED AND WHAT IS NOT. MEASURED on 2026-09-13 from this machine, read-only and
+ *   under STRICT TLS (no `-k`; curl reports `ssl_verify_result` 0):
+ *   `GET https://pbs.example.com:8007/api2/json/ping` -> HTTP 200 `{"data":{"pong":true}}`. So
+ *   the host is real, its certificate validates, and PBS WRAPS ITS ANSWER IN THE SAME `{"data": …}`
+ *   ENVELOPE AS PVE — which is what lets the PVE-shaped client body be reused at all.
+ *   ⛔ EVERYTHING ELSE BELOW IS DOCUMENTED, FROM PBS'S PUBLISHED API SCHEMA, AND NOT MEASURED — the
+ *     field list, the parameter spellings, which of them a PUT accepts, the privileges. Without a
+ *     credential every other endpoint answers 401, and PBS answers 401 BEFORE it routes:
+ *     `/api2/json/config/nosuchthing` -> 401, not 404 (measured). So the 401 from
+ *     `/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.
+ *
+ * ⚠️ `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
+ *   host. The `Pbs.` prefix is what keeps them apart in a plan, so it is not shortened.
+ *
+ * ★ THE SEAM, SINCE IT IS NOT THE USUAL ONE. This file answers "what a sync job is and what it
+ *   costs to declare one": the props, the attributes, the resource. pbs-sync-job-form.ts answers
+ *   "how it meets PBS": the coercions, the create and update bodies, and — the part that normally
+ *   lives here — `matches`. `matches` went with the wire because it is DOWNSTREAM of the wire:
+ *   ha-rule.ts's rule is that only a field a write can actually set may be compared, so every line
+ *   of that predicate is an argument about what the PUT accepts. Splitting it from the forms would
+ *   have put the claim and its evidence in different files. `Provider.of(handlers)` stays HERE, for
+ *   resource.ts's ⛔: it is the one place the handlers are checked against the concrete resource
+ *   types, and a cast there would be a lie about whether they match.
+ */
+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 type { PveRequirements } from './resource.ts';
+import type { WithPbsTarget } from './resource.ts';
+
+/**
+ * ⚠️ THE PROPS ARE PBS'S OWN PARAMETER NAMES, DASHES INCLUDED, for backup-job.ts's reason: the form
+ *   builder 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.
+ */
+export interface SyncJobProps extends WithPbsTarget {
+  /**
+   * ⛔ PBS'S SECTION ID AND THIS RESOURCE'S KEY, REQUIRED. Unlike a PVE vzdump job PBS does not
+   *   autogenerate one — `POST /config/sync` takes `id` — so the backup-job.ts failure of creating
+   *   a second job beside the first on every reconcile cannot happen here. It is still required
+   *   rather than derived: to adopt a job that exists, declare the id it already has.
+   * ⚠️ A PROXMOX SAFE ID — letters, digits, `_`, `.`, `-`, 3 to 32 characters — so there is nothing
+   *   in it for `path` below to encode.
+   */
+  id: string;
+  /** The LOCAL datastore the snapshots land in. Required by PBS at create. */
+  store: string;
+  /** Local namespace, e.g. `tenant/db`. Unset means the root namespace, which PBS spells `''`. */
+  ns?: string;
+  /**
+   * ⛔ A REMOTE BY NAME ONLY. THIS RESOURCE NEVER MODELS THE CREDENTIAL BEHIND IT, and a
+   *   `Pbs.Remote` family is OUT OF SCOPE for this package rather than merely unwritten:
+   *   `POST /config/remote` requires `password`, and Alchemy persists props and attributes to its
+   *   state store UNENCRYPTED (StateEncoding.ts tags Redacted values rather than encrypting them),
+   *   which here is the `alchemy` Postgres that pg-backup.sh dumps nightly to CT100. A remote's
+   *   password in a prop is that password in four places, for months. The only Remote resource that
+   *   could exist would refuse `password` the way storage.ts refuses it — as a `never` — and could
+   *   therefore never CREATE a remote, which is a resource that cannot do what its name promises.
+   *   Create remotes out of band (`proxmox-backup-manager remote create`) and name one here.
+   *   ⚠️ The fingerprint is not the problem: a certificate fingerprint is public. The password is.
+   * ⚠️ UNSET MEANS A LOCAL SYNC — datastore to datastore on this same PBS — which is a real and
+   *   supported mode, not an omission. See `matches`: an unset `remote` is NOT compared, so leaving
+   *   it out does not claim a job with a remote is local; it claims nothing at all.
+   */
+  remote?: string;
+  /** The datastore on that remote. Required by PBS at create. */
+  'remote-store': string;
+  /** Namespace on the remote. Unset means its root namespace. */
+  'remote-ns'?: string;
+  /**
+   * A PBS calendar event — `daily`, `hourly`, `mon..fri 02:30`. Unset means the job runs ONLY when
+   * somebody starts it by hand, which is a sync that is not happening; declare one.
+   * ⚠️ THIS COMPARES STRINGS, NOT MEANINGS. A calendar event has many equivalent spellings and PBS
+   *   stores the one it was handed, so declare the spelling the server echoes back.
+   */
+  schedule?: string;
+  /** Single line only — PBS's comment schema rejects a newline. */
+  comment?: string;
+  /**
+   * ⛔ THIS DELETES SNAPSHOTS. NOT "prunes", NOT "tidies" — DELETES, on a schedule, driven by
+   *   ANOTHER SERVER'S STATE. On a PULL job (the default), every backup group in the local `store`
+   *   and `ns` that is no longer on the remote is REMOVED LOCALLY the next time the job runs. The
+   *   remote decides; this side obeys. Somebody pruning hard on the remote, a remote datastore
+   *   restored from an older copy, a remote namespace renamed, or a remote that has simply lost
+   *   data — each of those becomes deletion HERE, and the local copy is usually the copy that was
+   *   supposed to survive the remote.
+   *   ⛔ AND ON A PUSH JOB IT DELETES ON THE REMOTE INSTEAD — same flag, opposite victim. Read
+   *     `sync-direction` before reading this one.
+   * ⚠️ IT IS COMPARED AND SENT EVEN WHEN UNDECLARED, unlike every other optional field here, and
+   *   that is deliberate: undeclared means `false`, so adopting a job somebody had switched this on
+   *   for plans as an UPDATE that switches it off — a real edit, and NOT a free one. It is the
+   *   direction that does not delete, but a job that was BOUNDING a datastore now grows it, and a
+   *   full PBS datastore fails every backup on it. The plan says only "update"; read the live job.
+   */
+  'remove-vanished'?: boolean;
+  /**
+   * The PBS Authid that owns the synced groups, e.g. `sync@pbs` or `sync@pbs!job1`. Unset leaves
+   * the config without one, which PBS reads as `root@pam` AT RUNTIME — so unset and `root@pam` are
+   * not the same value in the config even though they behave alike. Owning a group is what lets an
+   * Authid prune or delete it, so changing this is a permissions change, not a label.
+   * ⚠️ AN AUTHID IS AN IDENTIFIER, NEVER A SECRET — it may name an API token (`user@realm!name`),
+   *   and the token's VALUE is the secret. This resource stores the name and never the value.
+   */
+  owner?: string;
+  /**
+   * Incoming rate limit in BYTES PER SECOND. Unset means unlimited.
+   * ⚠️ DECLARED IN BYTES, STORED AS A HUMAN STRING. PBS types this as a `HumanByte`, so a written
+   *   `10485760` comes back as something like `10.00 MiB`; `bytes()` in the form file parses both
+   *   ends back to a byte count so the two can be compared at all. REASONED from the type, NOT
+   *   measured — I had no credential to round-trip one.
+   * ⛔ DECLARE A VALUE PBS CAN PRINT EXACTLY — a whole multiple of a binary unit. A rate that
+   *   rounds in the printed form (10485761) reads back as the rounded value, never equals what was
+   *   declared, and becomes an update reported on every plan forever. This is the single most
+   *   likely forever-diff in this file; it is the first thing to check on the first plan.
+   * ⚠️ `burst-in`, `rate-out` AND `burst-out` ARE NOT MODELLED. PBS's rate limit is four fields
+   *   flattened into the job; this resource manages one and leaves the others alone, which is safe
+   *   because PBS's update assigns only the parameters it was sent.
+   */
+  'rate-in'?: number;
+  /**
+   * How many namespace levels below `remote-ns` to sync, 0 (no recursion) upwards. Unset means PBS
+   * recurses as deep as it is allowed — which is MORE data, not less, so it is not a safe default
+   * to leave implicit on a job whose target namespace has children.
+   */
+  'max-depth'?: number;
+  /** Sync only the last N snapshots of each group. Unset means all of them. */
+  '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.
+   *   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.
+   *   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
+   *      filter excludes. A field that MIGHT delete snapshots when changed does not get a
+   *      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.
+   */
+  'group-filter'?: never;
+  /**
+   * `pull` (default) or `push`. ⛔ IT DECIDES WHICH SIDE `remove-vanished` DELETES FROM. Push also
+   * needs a newer PBS: on a server that predates it the parameter is unknown and the create is
+   * refused, which is the honest failure.
+   * ⚠️ CREATE-ONLY HERE, SO A CHANGED DIRECTION PLANS AS NOOP — see `matches`. That is the
+   *   deliberately safe half of an unmeasured question: if PBS does accept it on PUT, the cost of
+   *   this choice is a noop; if PBS refuses it, comparing it would be an update the PUT can never
+   *   perform, on every plan, forever. Retire the declaration and add another, as user.ts says for
+   *   `userid`.
+   */
+  'sync-direction'?: 'pull' | 'push';
+  /**
+   * ⚠️ SYNC ONLY SNAPSHOTS THAT HAVE PASSED VERIFICATION. Present on 4.2 (`sync-job update
+   *   --verified-only <boolean>`, and in its `--delete` enum), and the estate sets it: the parked
+   *   `sync-all-to-dc` job carries `verified-only: true`, so without this prop that job cannot be
+   *   declared as it actually is.
+   * ⛔ IT PAIRS WITH A VERIFICATION JOB THAT ACTUALLY RUNS. With PBS's defaults a snapshot is
+   *   verified once and never again — see `rechecks` in pbs-verify-job-form.ts — so `verified-only`
+   *   on a datastore whose verify job is parked means "sync only what was checked once, long ago".
+   */
+  '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,
+  SyncJobAttributes,
+  never,
+  PveRequirements
+> {}
+
+/**
+ * ⚠️ NO `defaultRemovalPolicy: 'retain'`, and the reasoning is replication-job.ts's. Deleting this
+ *   object removes a SCHEDULE, not data: every snapshot already synced stays in the local
+ *   datastore, and PBS's own pruning is a different job. What is lost is freshness — which is
+ *   destructive in six months rather than today, and is exactly why the plan line deserves reading.
+ */
+export const PbsSyncJob = Resource<PbsSyncJob>('Pbs.SyncJob');
+
+/**
+ * ⛔ THE EMPTY `list` FROM THE FACTORY STANDS. `GET /config/sync` hands back every sync job an
+ *   operator ever made in the UI, and adopting one is how a later `alchemy destroy` silently stops
+ *   a second copy being refreshed. Adoption is an explicit act — declare the `id` you mean.
+ * ⚠️ DELETING THE JOB DOES NOT DELETE SNAPSHOTS, AND `remove-vanished` DOES. Those two sentences
+ *   are the whole risk model of this family and they point opposite ways: the DELETE plan line is
+ *   safe today and expensive in six months, while a single `remove-vanished: true` is a standing
+ *   instruction to delete local snapshots whenever another server loses them.
+ */
+export const PbsSyncJobProvider = () =>
+  Provider.effect(PbsSyncJob, Effect.succeed(PbsSyncJob.Provider.of(handlers)));

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

@@ -0,0 +1,131 @@
+/**
+ * A verification job's props as the form PBS wants, and the one derived string worth reporting.
+ *
+ * ★ SPLIT OUT OF pbs-verify-job.ts TO KEEP BOTH FILES UNDER THE 250-LINE CAP, on the seam
+ *   replication-job-form.ts and ha-rule-form.ts already cut: this file answers "how does a
+ *   declaration become a PBS write, and what do the two filter fields actually mean", and
+ *   pbs-verify-job.ts answers "what is a verification job and when has it changed". Nothing here
+ *   reads the host and nothing here decides a diff.
+ *
+ * ⚠️ THE `import type` BACK TO pbs-verify-job.ts IS A CYCLE ON PAPER ONLY — type-only, erased
+ *   before anything runs, and `PbsVerifyJobProps` stays public in the file declaring the resource.
+ *
+ * ⛔ THERE IS NO `disable` FIELD ON A PBS VERIFICATION JOB, AND SHIPPING A PROP FOR ONE WOULD HAVE
+ *   BEEN THE WORST BUG IN THIS FAMILY. Prune jobs have `disable` and sync jobs have `disable`;
+ *   `VerificationJobConfig` does not, in the struct, in the API schema, or in the update handler's
+ *   `DeletableProperty` enum — read at HEAD of pbs-api-types and src/api2/config/verify.rs on
+ *   2026-09-13. A `disable` prop would therefore be a prop that either does nothing or 400s the
+ *   whole call (the create schema has `additional_properties: false`, so an unknown key is
+ *   rejected with "schema does not allow additional properties"). Either way it would be a
+ *   declaration saying "verification is paused" that PBS never agreed to. The real off switch is
+ *   an absent `schedule`.
+ *   ★ NOW VERIFIED AGAINST THE RUNNING HOST, which this comment previously said it was not.
+ *     `proxmox-backup-manager verify-job update --help` on the live 4.2 server offers
+ *     `--comment --delete --digest --ignore-verified --max-depth --ns --outdated-after
+ *     --read-threads --schedule --store --verify-threads` — no `--disable` — and its `--delete`
+ *     enum contains `schedule`. Both halves of the claim hold on this estate's actual version.
+ *   ⚠️ `read-threads` AND `verify-threads` EXIST ON 4.2 AND ARE NOT PROPS HERE. Nothing on this
+ *     estate sets either, and a prop nobody uses is an abstraction with no user — the same reason
+ *     `PveSpec.immutable` was backed out. Add them when something needs them.
+ *
+ * ⛔ `withClears` FROM values.ts IS DELIBERATELY NOT USED HERE, AND USING IT WOULD BREAK EVERY
+ *   UPDATE. PVE's `delete` is ONE comma-separated string; PBS's is an ARRAY of an enum. MEASURED in
+ *   proxmox-schema's `do_parse_parameter_strings`: for an `Schema::Array` property each occurrence
+ *   of the key pushes ONE element, so a form body must REPEAT the key — `delete=ns&delete=comment`.
+ *   `withClears` emits `delete: 'ns,comment'`, which PBS parses as a single element `"ns,comment"`,
+ *   which is not a `DeletableProperty` variant, so the call fails with a parameter error. It fails
+ *   loudly rather than quietly, which is the only good news in it.
+ *   ★ AND IT COULD NOT BE FIXED IN THIS FILE ANYWAY. `client.ts` types a form as
+ *     `Record<string, string>` and builds it with `new URLSearchParams(form)`; neither a plain
+ *     object nor that constructor overload can express a repeated key. Clearing a PBS field needs
+ *     a client that takes entry pairs. Until one exists, this form SETS and never CLEARS — so an
+ *     undeclared field is left alone and, in pbs-verify-job.ts, is not compared either.
+ */
+import type { PbsVerifyJobProps } from './pbs-verify-job.ts';
+
+/**
+ * What the live pair actually causes, rendered for a plan line.
+ *
+ * ⛔ THE DEFAULTS MEAN "VERIFY EACH SNAPSHOT EXACTLY ONCE, EVER", AND THAT IS THE FAILURE THIS
+ *   WHOLE FAMILY EXISTS TO MAKE VISIBLE. Read from src/backup/verify.rs `verify_filter` and
+ *   src/server/verify_job.rs at HEAD on 2026-09-13, the filter is:
+ *
+ *     ignore_verified = ignore_verified.unwrap_or(true)      // absent means TRUE
+ *     if !ignore_verified                       -> verify
+ *     manifest has no verify state              -> verify
+ *     outdated_after is None                    -> SKIP, forever
+ *     days_since_last_verify > outdated_after   -> verify
+ *
+ *   So a job created with neither field set — the shape the PBS web UI produces when nobody
+ *   touches those two boxes — checks every snapshot once on the run after it is written and then
+ *   never looks at it again. Bit rot that appears a month later is never found. The job stays
+ *   green the entire time, because a job that verified nothing verified nothing badly.
+ *
+ * ⚠️ A FAILED PAST VERIFICATION IS SKIPPED TOO. `verify_filter` looks only at whether a verify
+ *   state EXISTS, never at whether it says Ok or Failed, so a snapshot that failed once is not
+ *   re-checked by a defaulted job either. Pair that with a prune job and the failure ages out
+ *   without anyone confirming it.
+ *
+ * ⛔ `outdated-after: 0` DOES NOT MEAN "NEVER", THOUGH PBS'S OWN STRUCT DOC SAYS IT DOES. That
+ *   comment — "Reverify snapshots after X days, never if 0" — contradicts the code beside it: the
+ *   test is `days_since_last_verify > max_age`, so `0` re-verifies everything checked more than a
+ *   day ago, i.e. very nearly every run. The schema text calls `0` deprecated and the minimum is
+ *   `0`, so it is accepted. "Never" is the ABSENT value, not the zero — and this resource cannot
+ *   get a job back to absent (see the ⛔ on `withClears` above), so a declaration that sets
+ *   `outdated-after` has made a one-way choice. Undo it by hand:
+ *   `proxmox-backup-manager verify-job update <id> --delete outdated-after`.
+ *
+ * ⚠️ THE COMPARISON IS INTEGER DAYS SINCE THE LAST RUN'S START, `(now - upid.starttime) / 86400`,
+ *   and it is strictly greater-than. `outdated-after: 30` therefore re-checks on day 31.
+ */
+export const rechecks = (ignoreVerified: boolean, outdatedAfter: number): string => {
+  if (!ignoreVerified) return 'every snapshot on every run';
+  // ⚠️ `-1` is this package's spelling of "the key is absent", set in `attributes`. It is not a
+  //   value PBS accepts: the schema's minimum is 0.
+  if (outdatedAfter < 0) return 'never: each snapshot is checked once and then skipped forever';
+  return `once the last check is more than ${String(outdatedAfter)} day(s) old`;
+};
+
+/**
+ * The form for create and update alike.
+ *
+ * ⛔ `schedule: null` OMITS THE KEY, AND ON AN UPDATE THAT DOES NOT CLEAR AN EXISTING ONE. This
+ *   form SETS and never CLEARS — the ⛔ on `withClears` above is why — so declaring `null` against
+ *   a job that already has a schedule plans an update that changes nothing, every time. Park a job
+ *   by hand once and the declaration then describes it truthfully:
+ *   `proxmox-backup-manager verify-job update <id> --delete schedule`. The honest failure is a
+ *   plan that keeps asking; the dishonest one would be a form that quietly reported success.
+ *
+ * ⚠️ `store` AND `ignore-verified` ARE ALWAYS SENT BECAUSE THEY ARE ALWAYS COMPARED.
+ *   A field compared against a default but not sent as that default is an update reported on every
+ *   plan that the write never performs — backup-job.ts and replication-job-form.ts both record the
+ *   same trade. `ignore-verified` is the only one of the three with a PBS-side default, and it is
+ *   TRUE, so an undeclared prop is sent as `1` rather than left out.
+ *
+ * ⚠️ THE BOOLEAN IS SPELLED INLINE RATHER THAN THROUGH `flag()` FROM values.ts, AND THAT IS A TYPE
+ *   FACT RATHER THAN A STYLE ONE. `flag` answers `'1' | '0' | undefined` so that an undeclared
+ *   field is dropped; here the field must never be dropped, and the `undefined` in its return type
+ *   is not assignable to a `Record<string, string>` form body.
+ *
+ * ⚠️ PBS ACCEPTS BOTH `application/x-www-form-urlencoded` AND `application/json` AND NOTHING ELSE —
+ *   any other content type is rejected outright with "unsupported content type", measured in
+ *   proxmox-rest-server's `get_request_parameters`. `client.ts` sends the form encoding whenever a
+ *   body is present, so it is already speaking one of the two. Numbers are stringified here for
+ *   that reason; PBS parses them back through the integer schema.
+ *
+ * ⛔ `ns` IS DROPPED WHEN IT IS EMPTY, NOT SENT AS `''`. The empty string IS a legal namespace
+ *   value — `BACKUP_NS_RE` is wrapped in `(?:…)?`, so it passes the schema and reaches the update
+ *   handler — and the handler then throws it away at `if !ns.is_root()`. Sending it would look like
+ *   a write that moves the job to the root namespace and would silently be nothing at all.
+ */
+export const shape = (props: PbsVerifyJobProps): Record<string, string> => ({
+  'ignore-verified': props['ignore-verified'] === false ? '0' : '1',
+  store: props.store,
+  ...(props.schedule === null ? {} : { schedule: props.schedule }),
+  ...(props.comment === undefined ? {} : { comment: props.comment }),
+  ...(props['max-depth'] === undefined ? {} : { 'max-depth': String(props['max-depth']) }),
+  ...(props.ns === undefined || props.ns === '' ? {} : { ns: props.ns }),
+  ...(props['outdated-after'] === undefined
+    ? {}
+    : { 'outdated-after': String(props['outdated-after']) }),
+});