@homeflare/alchemy 0.1.0

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

@@ -0,0 +1,208 @@
+/**
+ * A prune job's wire half — and, deliberately, EVERY LINE THAT CAN DELETE A BACKUP.
+ *
+ * ★ SPLIT OUT OF pbs-prune-job.ts ON THE SEAM replication-job-form.ts USES: that file answers
+ *   "what is a prune job and when has it changed", this one answers "how does a declaration become
+ *   a PBS write". The one deliberate departure from that seam is `keepsMatch`, which is diff logic
+ *   and lives here anyway — see the ★ below, which is the reason the cut falls where it does.
+ *
+ * ★ THE SIX RETENTION WINDOWS ARE TOUCHED IN THREE PLACES AND ALL THREE ARE IN THIS FILE: sent by
+ *   `keepForm`, read back by `keepAttributes`, compared by `keepsMatch`. The three must stay in
+ *   step — a window written but not compared is a diff that never settles, and one compared but not
+ *   written is an update reported on every plan forever — and this is the half of the resource
+ *   where being wrong costs backups rather than a confusing plan. Keeping all three on one screen
+ *   is what makes that review possible in one sitting instead of a grep across two files.
+ *
+ * ⚠️ THE `import type` BACK TO pbs-prune-job.ts IS A CYCLE ON PAPER ONLY. It is type-only, erased
+ *   before anything runs, so `PruneJobProps` stays the resource's public shape in the file that
+ *   declares the resource rather than being moved somewhere odd to dodge the arrow.
+ *
+ * ⚠️ FORM ENCODING IS THE ONE TRANSPORT ASSUMPTION THIS FAMILY RESTS ON, AND IT IS REASONED RATHER
+ *   THAN MEASURED. `pveWith` sends `application/x-www-form-urlencoded`; PBS's REST server accepts
+ *   that alongside JSON and parses each value through the parameter schema, which is how its own
+ *   ExtJS GUI talks to it. I could not prove it: there is no credential for this host (see the ⛔ in
+ *   pbs-prune-job.ts) and the only unauthenticated endpoint that would have distinguished a 400
+ *   "bad parameters" from a 401 is the login form, which is not a thing to poke on a live box. If
+ *   PBS turns out to want JSON here, every key and value below is still right and only the
+ *   transport is wrong — VERIFY THIS FIRST, before anything else in these two files.
+ */
+import type { PruneJobAttributes, PruneJobProps } from './pbs-prune-job.ts';
+import { flag, int } from './values.ts';
+
+/**
+ * The six retention windows, in PBS's own spelling.
+ *
+ * ⚠️ ONE LIST, READ THREE TIMES — by `keepForm` on the way to the wire, by `keepsMatch` on the way
+ *   back, and by `keepsSomething` in the guard. Two hand-kept copies of six key names is how a
+ *   seventh window gets added to one of them and silently never sent, which for this family means
+ *   never applied and never noticed until a restore.
+ */
+export const KEEP_KEYS = [
+  'keep-last',
+  'keep-hourly',
+  'keep-daily',
+  'keep-weekly',
+  'keep-monthly',
+  'keep-yearly',
+] as const;
+
+export type KeepKey = (typeof KEEP_KEYS)[number];
+
+/** ⚠️ Undeclared windows are simply absent — see `requireKeeps` for why zero is never sent. */
+const keepForm = (props: PruneJobProps): Record<string, string> => {
+  const form: Record<string, string> = {};
+  for (const key of KEEP_KEYS) {
+    const value = props[key];
+    if (value !== undefined) form[key] = String(value);
+  }
+  return form;
+};
+
+/**
+ * The six windows off the wire, where `0` MEANS ABSENT.
+ *
+ * ⛔ ZERO IS A SENTINEL HERE AND CAN NEVER BE A LIVE VALUE, which is the only reason it is safe to
+ *   use one. MEASURED from the published PBS schema: every `keep-*` carries `minimum: 1`, so PBS
+ *   cannot store a zero and cannot be sent one — `keep-daily=0` is a 400, not a wipe. A field that
+ *   comes back missing is a window that is not part of this job's policy, and `keepsMatch` must be
+ *   able to tell that apart from "the declaration asked for zero", which it cannot express either.
+ */
+export const keepAttributes = (
+  live: Record<string, unknown>,
+): Pick<PruneJobAttributes, KeepKey> => ({
+  'keep-daily': int(live['keep-daily'], 0),
+  'keep-hourly': int(live['keep-hourly'], 0),
+  'keep-last': int(live['keep-last'], 0),
+  'keep-monthly': int(live['keep-monthly'], 0),
+  'keep-weekly': int(live['keep-weekly'], 0),
+  'keep-yearly': int(live['keep-yearly'], 0),
+});
+
+/**
+ * ⚠️ AN UNDECLARED WINDOW IS NOT COMPARED, AND THAT IS THE SAFETY MODEL RATHER THAN AN OVERSIGHT.
+ *   A `keep-weekly` an operator set by hand on an adopted job is not drift this stack repairs —
+ *   repairing it would mean narrowing retention nobody asked to narrow. The cost is stated rather
+ *   than hidden: deleting a `keep-daily` line from a declaration plans as a NOOP and changes
+ *   nothing on the server. See the ⛔ on `updateBody` for why clearing is a hand operation.
+ */
+export const keepsMatch = (attributes: Pick<PruneJobAttributes, KeepKey>, props: PruneJobProps) =>
+  KEEP_KEYS.every((key) => props[key] === undefined || props[key] === attributes[key]);
+
+/**
+ * ⛔ A PRUNE JOB WITH NO `keep-*` KEEPS NOTHING, AND THIS REFUSES TO BUILD ONE.
+ *
+ *   MEASURED from the published PBS API: all six windows are `optional: 1` on POST and on PUT. So
+ *   on the wire "I forgot the retention" and "I want no retention" are the SAME REQUEST, and the
+ *   second one is not a configuration — it is a scheduled deletion of every backup in scope. This
+ *   is the one mistake this family must not be able to make.
+ *
+ * ⚠️ PBS PROBABLY REFUSES IT TOO, AND THAT IS NOT GOOD ENOUGH TO LEAN ON. Its GUI warns about a
+ *   keep-less prune job, which suggests the API guards it as well, but I could not reach a PBS to
+ *   prove it and "probably refused upstream" is not a thing to bet a restore on. The guard is
+ *   local, it is cheap, and it costs nothing at all on a declaration that is already correct.
+ *
+ * ⛔ IT THROWS RATHER THAN RETURNING AN EMPTY FORM. `reconcile` calls these builders inside
+ *   `Effect.gen`, so the throw lands as a defect and stops the deploy carrying this sentence. A
+ *   builder that quietly answered `{}` instead would be a PUT of nothing — reported as success —
+ *   over the retention the declaration existed to set.
+ *
+ * ⚠️ IT FIRES AT DEPLOY, NOT AT PLAN, because `diff` never calls a form builder: a keep-less
+ *   declaration plans as a clean create and then dies on apply. Loud and safe, but not early. The
+ *   stronger guard is a props type where one window is mandatory — a `Base & ({'keep-last': number}
+ *   | …)` union — and it is NOT here because I could not satisfy myself that Alchemy's
+ *   `Input<Props>` narrowing distributes over that union, and an unverified type trick in the file
+ *   that decides what gets deleted is worse than an honest runtime throw.
+ */
+const keepsSomething = (props: PruneJobProps) => KEEP_KEYS.some((key) => props[key] !== undefined);
+
+const requireKeeps = (props: PruneJobProps) => {
+  if (keepsSomething(props)) return;
+  throw new Error(
+    `Pbs.PruneJob ${props.id}: declares no keep-* window, which tells PBS to keep NOTHING on ` +
+      `datastore '${props.store}'. Every keep-* is optional on the wire, so an omission and a ` +
+      'deliberate "retain nothing" are indistinguishable; declare at least one window (keep-last, ' +
+      'keep-hourly, keep-daily, keep-weekly, keep-monthly or keep-yearly) or delete the job.',
+  );
+};
+
+/** ⚠️ An undeclared field emits NO KEY AT ALL, not an empty one — see the ⚠️ on `shape`. */
+const field = (name: string, value: string | undefined): Record<string, string> =>
+  value === undefined ? {} : { [name]: value };
+
+/** ⚠️ `undefined` in, `undefined` out, so `field` can drop it — never the text "undefined". */
+const integer = (value: number | undefined) => (value === undefined ? undefined : String(value));
+
+/**
+ * The mutable half, shared by create and update.
+ *
+ * ⚠️ `store` AND `schedule` ARE ALWAYS SENT because they are always declared and always compared —
+ *   a field compared against a value but NOT SENT as that value is an update reported on every
+ *   plan that the PUT never performs (backup-job.ts and replication-job-form.ts both record that
+ *   trade). PBS makes both required on POST and optional on PUT, so sending them on both calls is
+ *   legal and keeps one shape for the two.
+ *
+ * ⚠️ EVERYTHING ELSE IS SENT ONLY WHEN DECLARED, AND UNDECLARED MEANS UNMANAGED — the rule
+ *   storage.ts sets, not backup-job.ts's "always send the documented default". The difference is
+ *   what the drift costs: an undetected `enabled 0` on a vzdump job means backups quietly are not
+ *   happening, while an unasked-for change here means backups quietly ARE being deleted. Writing a
+ *   default this stack never declared is the worse error for a destructive job, so it is not done.
+ *   ⛔ `max-depth` IS THE EXCEPTION THAT PROVES IT AND IT RUNS THE OTHER WAY — see the ⛔ in
+ *     pbs-prune-job.ts. Its unset value is FULL RECURSION, so leaving it unmanaged is the WIDE
+ *     choice rather than the narrow one. Declare it.
+ */
+const shape = (props: PruneJobProps): Record<string, string> => ({
+  ...keepForm(props),
+  ...field('comment', props.comment),
+  ...field('disable', flag(props.disable)),
+  ...field('max-depth', integer(props['max-depth'])),
+  ...field('ns', props.ns),
+  schedule: props.schedule,
+  store: props.store,
+});
+
+/**
+ * ⛔ `id` IS SENT AND IS NOT OPTIONAL, for backup-job.ts's reason sharpened by this API's shape.
+ *   MEASURED: `id` is a REQUIRED parameter of `POST /config/prune` — PBS does not generate one —
+ *   so an omitted id is a 400 rather than a duplicate job. That is the good case; the bad one is
+ *   the id being WRONG. `pveOperations.read` folds every failed GET into "absent", so a 403 or an
+ *   expired lease reads as "no such job", the plan says create, and a second prune job appears
+ *   beside the first with this declaration's retention applied to the same datastore. Two prune
+ *   jobs on one store do not negotiate: each deletes what its own windows do not keep.
+ */
+export const createBody = (props: PruneJobProps): Record<string, string> => {
+  requireKeeps(props);
+  return { ...shape(props), id: props.id };
+};
+
+/**
+ * ⛔ THERE IS NO `delete` LIST HERE AND `withClears()` IS DELIBERATELY NOT IMPORTED. Two
+ *   independent reasons, either of which alone would be enough.
+ *
+ *   FIRST, THE WIRE SHAPE IS NOT PVE'S. MEASURED from the published PBS schema, `PUT
+ *   /config/prune/{id}` declares `delete` as `{"type":"array","items":{"type":"string","enum":[
+ *   "comment","disable","ns","max-depth","keep-last","keep-hourly","keep-daily","keep-weekly",
+ *   "keep-monthly","keep-yearly"]}}` — an ARRAY of enum members. PVE's `delete` is a comma-joined
+ *   string, which is exactly what `withClears()` builds, and a form-encoded array is built by
+ *   REPEATING the key. `delete=comment,disable` is therefore ONE item that is in no enum: a 400,
+ *   not a clear.
+ *   ⚠️ AND THE CORRECT SHAPE IS NOT EXPRESSIBLE TODAY. `pveWith` takes `Record<string, string>` and
+ *     runs it through `new URLSearchParams`, which cannot repeat a key from a plain object. A PBS
+ *     clear list needs a client that can, and that is a change to client.ts rather than to this
+ *     file — so a clear list could not be shipped here even if it were wanted.
+ *
+ *   SECOND, AND THIS ONE WOULD STAND ANYWAY: CLEARING A `keep-*` IS THE MOST DESTRUCTIVE THING
+ *   THIS API CAN DO. Removing `keep-last` from a job that had it does not restore a default — PBS
+ *   has no default retention — it NARROWS what survives the next run. So an undeclared field is
+ *   unmanaged, and a window this stack never mentioned is one it never widens and never removes.
+ *   Dropping a `keep-daily` line from a declaration therefore does NOTHING on purpose; clear it by
+ *   hand, having first looked at what it is holding.
+ *
+ * ★ THE DISJOINTNESS `withClears()` EXISTS TO ENFORCE IS THEREFORE VACUOUS HERE: with no clear list
+ *   there is no key that can be set and deleted in one call, which is the failure it guards. If a
+ *   later change does add one it must go through `withClears()` AND teach the client to repeat the
+ *   key — half of that is a 400, and the other half is PVE's spelling sent to a PBS host.
+ */
+export const updateBody = (props: PruneJobProps): Record<string, string> => {
+  requireKeeps(props);
+  return shape(props);
+};

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

@@ -0,0 +1,227 @@
+/**
+ * `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.
+ *
+ * ⛔ 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
+ *   make a caller opt in with `destroy()`, and that guard covers DELETE and nothing else. Here the
+ *   destruction rides a plain `1 to update` that no removal policy has any opinion about. A wrong
+ *   `keep-*` does not fail: it succeeds. The PUT returns 200, and the NEXT SCHEDULED RUN — minutes
+ *   or days later, with nobody watching — removes every snapshot that fell outside the new window.
+ *   There is no undo, PBS does not ask, and nothing about the deploy looks unusual.
+ *   ★ CONCRETELY, SO NOBODY HAS TO IMAGINE IT: a live job with `keep-daily 30`, a declaration
+ *     saying `keep-daily: 7`. `matches` reports an update, the PUT lands, and twenty-three days of
+ *     daily backups are gone at the next run. The plan showed one word. READ THE `keep-*` HALF OF
+ *     EVERY PLAN TWICE; it is the only warning there is.
+ *   ⚠️ THE ONE THING THAT CANNOT HAPPEN IS A SILENT ZERO. MEASURED from the published schema: every
+ *     `keep-*` carries `minimum: 1`, so a literal `keep-daily=0` is a 400 rather than a wipe. And
+ *     an UNDECLARED window is not sent as zero either — it is not sent at all, because undeclared
+ *     means unmanaged here exactly as it does in storage.ts. A window this stack never named is one
+ *     it never narrows. `0` in the attributes below therefore means ABSENT, never a real setting.
+ *
+ * ⛔ `max-depth` UNSET IS THE WIDEST SCOPE, NOT THE NARROWEST, AND IT IS THE ONE FIELD WHERE
+ *   "UNMANAGED" IS NOT THE SAFE ANSWER. MEASURED, quoting the published schema's own description:
+ *   "0 == no recursion, empty == automatic full recursion". So a job that names an `ns` but leaves
+ *   `max-depth` alone prunes every namespace BENEATH that one too, with these windows. Declare it.
+ *   `-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
+ *   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.
+ *   PBS's documented form is `Authorization: PBSAPIToken=TOKENID:TOKENSECRET` (measured from the
+ *   published PBS documentation, 2026-09-13) while `authorization()` in credentials.ts builds
+ *   `PVEAPIToken=<tokenid>=<secret>`: BOTH the scheme and the separator differ. A wrong separator
+ *   answers 401 "authentication failure", which reads as a bad credential rather than as a
+ *   malformed header — the same trap credentials.ts already records for PVE's colon form.
+ *   ⛔ AND THERE IS NO MOUNT TO MINT FROM. `mint()` runs `bao read <mount>/creds/<role>`; no
+ *     OpenBao mount vends PBS tokens — `proxmox-tb4` and `proxmox-ops` vend PVE ones. The
+ *     `kv/infra/proxmox` shelf holds a READ-ONLY `Audit` token for PBS, and a read-only token
+ *     cannot create a prune job. I could not confirm that shelf's contents: this machine's
+ *     claude-code approle answers 403 on `sys/mounts` AND on `kv/metadata/infra/proxmox`
+ *     (MEASURED). What is needed is a dynamic PBS mount vending a `provision` role with
+ *     `Datastore.Modify` — say that, rather than reaching for the stored auditor token.
+ *
+ * ★ 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
+ *   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.
+ *
+ * ⚠️ WHICH VERSION THIS IS AUTHORED AGAINST, BECAUSE PRUNE JOBS MOVED. The paths and every field
+ *   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.
+ *
+ * ★ 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
+ *   "Datastore.Audit or Datastore.Verify on job's datastore", i.e. the AUDIT privilege is enough
+ *   for the ITEM read. That is precisely what `Proxmox.Storage` and the two SDN families could not
+ *   say, and it is why the ⛔ on `readRole` in resource.ts does not claim a fourth family here.
+ *   ⚠️ THE WRITE PRIVILEGES ARE NOT ONE PRIVILEGE, AND DELETE IS THE ODD ONE OUT. MEASURED: POST
+ *     and PUT require `Datastore.Modify` on the job's datastore; DELETE requires `Datastore.Verify`.
+ *     A credential that can create and edit a prune job cannot necessarily remove one, and the
+ *     symptom is a destroy that 403s long after the creates worked.
+ *
+ * ⚠️ RUNTIME STATUS IS NOT HERE AND WAS NOT FORGOTTEN. `last-run-endtime` and friends come from
+ *   `/admin/prune`, not from this endpoint: MEASURED, `GET /config/prune/{id}` returns exactly
+ *   comment, disable, id, the six keep-*, max-depth, ns, schedule and store — no digest, no status.
+ *   Reporting a last-run time would make a plan's output change when nothing changed, and a plan
+ *   whose output moves on its own is one people stop reading. `/admin/prune/{id}/run` triggers a
+ *   prune by hand and is deliberately not modelled: running one is an act, not a declaration.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+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';
+
+/**
+ * ⚠️ THE PROPS ARE PBS'S OWN KEY NAMES, HYPHENS 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. Here a field that is never sent is a
+ *   retention window that never applies.
+ */
+export interface PruneJobProps extends WithPbsTarget {
+  /** ⛔ A PBS host, not a PVE one. See `PbsTarget` and the credential ⛔ in the header. */
+  target: PbsTarget;
+  /**
+   * ⛔ The primary key, REQUIRED, and PBS does not generate one. Measured: 3–32 chars matching
+   * `^[A-Za-z0-9_][A-Za-z0-9._\-]*$`. To adopt a job that exists, declare its existing id — any
+   * other id is a SECOND prune job on the same datastore, and two prune jobs do not negotiate.
+   */
+  id: string;
+  /** ⚠️ The datastore this prunes. Changing it re-points the job rather than adding one: the old
+   * store stops being pruned and the new one starts, with these windows, at the next run. */
+  store: string;
+  /**
+   * A systemd calendar event, e.g. `daily` or `sat 02:30`. ⛔ REQUIRED — measured, it is the one
+   * non-optional field of `POST /config/prune` besides `id` and `store`, and it is NOT in the PUT
+   * `delete` enum, so there is no way to un-schedule a job short of disabling or removing it.
+   * ⚠️ THIS COMPARES STRINGS, NOT MEANINGS. A calendar event has many equivalent spellings and PBS
+   *   stores the one it was handed; declare the spelling the server echoes back.
+   */
+  schedule: string;
+  /** Namespace to prune, `''` or unset for the root one. ⚠️ Scope, so read it with `max-depth`. */
+  ns?: string;
+  /** ⛔ UNSET MEANS FULL RECURSION, NOT NONE — see the ⛔ in the header. 0–7. Declare it. */
+  'max-depth'?: number;
+  /** ⚠️ Undeclared is UNMANAGED, so a job somebody disabled by hand stays disabled. That is the
+   * deliberate direction for a destructive job: never switch one on that nobody asked for. */
+  disable?: boolean;
+  comment?: string;
+  /** ⚠️ Every window below is `minimum: 1` (measured) and undeclared means unmanaged. */
+  'keep-last'?: number;
+  'keep-hourly'?: number;
+  'keep-daily'?: number;
+  'keep-weekly'?: number;
+  'keep-monthly'?: number;
+  'keep-yearly'?: number;
+}
+
+export interface PruneJobAttributes {
+  id: string;
+  store: string;
+  schedule: string;
+  ns: string;
+  /** ⚠️ `-1` is ABSENT — and absent means full recursion. `0` is the real "no recursion" setting. */
+  'max-depth': number;
+  disable: boolean;
+  comment: string;
+  /** ⚠️ `0` is ABSENT in all six. PBS's own minimum is 1, so zero can never be a live value. */
+  'keep-last': number;
+  'keep-hourly': number;
+  'keep-daily': number;
+  'keep-weekly': number;
+  'keep-monthly': number;
+  'keep-yearly': number;
+}
+
+export interface PbsPruneJob extends Resource<
+  'Pbs.PruneJob',
+  PruneJobProps,
+  PruneJobAttributes,
+  never,
+  PveRequirements
+> {}
+
+/**
+ * ★ NO `defaultRemovalPolicy: 'retain'`, UNLIKE Storage AND ZfsPool, AND THE REASON IS THE REVERSE
+ *   OF THEIRS. Destroying this resource destroys a POLICY, and a policy is a line of TypeScript.
+ *   The archives it would have trimmed are not touched by the DELETE — see the ⚠️ on the provider.
+ */
+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.
+   */
+  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
+ *   hand included. Adopting those would give Alchemy the right to REWRITE their retention the first
+ *   time a declaration disagreed — and rewriting retention is deleting backups. Adoption stays an
+ *   explicit act: name the id you mean.
+ *
+ * ⚠️ THE DELETE IS THE SAFE DIRECTION, AND IT IS STILL NOT FREE. Removing a prune job deletes
+ *   NOTHING: the archives that survived the last run stay exactly where they are. What goes away is
+ *   the only thing trimming that datastore, so the failure mode is a datastore that fills up weeks
+ *   later — an outage with no obvious cause and no backup written during it. Nothing on the server
+ *   depends on a prune job, so PBS will not refuse this the way PVE refuses to delete a pool still
+ *   holding guests; the plan line is the only warning anyone gets.
+ *   ⚠️ DELETE ALSO NEEDS A DIFFERENT PRIVILEGE FROM THE WRITES — `Datastore.Verify`, not
+ *     `Datastore.Modify`. See the ⚠️ in the header before assuming a working create means a working
+ *     destroy.
+ */
+export const PbsPruneJobProvider = () =>
+  Provider.effect(PbsPruneJob, Effect.succeed(PbsPruneJob.Provider.of(handlers)));