@homeflare/alchemy 0.1.0

package/dist/proxmox/pbs-datastore-form.d.ts

@@ -0,0 +1,147 @@
+/**
+ * A PBS datastore on the wire: the transport that reaches PBS, the form it wants, and the coercion
+ * back to something comparable.
+ *
+ * ★ SPLIT OUT OF pbs-datastore.ts FOR THE 250-LINE CAP, the seam notification-target-form.ts uses:
+ *   this file is everything that touches PBS's encoding, and the resource file is the declaration
+ *   and the five handlers. The `import type` back is erased, so it is a cycle on paper only.
+ *
+ * ⛔ THIS FILE IS OVER THE 250-LINE CAP AND THE EXTRACTION IS NAMED RATHER THAN FUDGED. `PbsTarget`,
+ *   `PbsRole`, `PbsError`, `pbsAuthorization`, `PveForm`, `encode`, `pbs` and `settle` — about 150
+ *   lines — are a PBS CLIENT, not a datastore form, and belong in `pbs-client.ts`. Lifting them
+ *   leaves this file near 200 and costs nothing but a move. It was not done here only because the
+ *   family was commissioned as a two-file split; ceph-pool is the in-package precedent for three
+ *   (ceph-pool.ts + ceph-pool-form.ts + ceph-pool-settle.ts, 532 lines for one family). Everything
+ *   in that list is also what Pbs.SyncJob, Pbs.PruneJob and Pbs.Remote will each need unchanged,
+ *   so the second PBS family forces the move anyway. ⛔ DO NOT MEET THE CAP BY CUTTING COMMENTS.
+ */
+import * as Effect from 'effect/Effect';
+import { type PveForm } from './client.ts';
+import type { PbsTarget as ApiPbsTarget } from './credentials.ts';
+import type { PbsDatastoreProps } from './pbs-datastore.ts';
+/**
+ * ★ PBS REUSES THE PVE CLIENT RATHER THAN OWNING ONE. An earlier draft of this file carried its
+ *   own `PbsTarget`, `PbsError`, `pbsAuthorization`, form encoder and `pve()` — a near-copy of
+ *   client.ts differing in one header. They are gone: `PveTarget` now carries a `scheme`, and
+ *   `authorization()` spells the header `PBSAPIToken=<id>:<secret>` when it is `'pbs'`. The
+ *   insight that survived is the FORM TYPE — PBS decodes a multi-valued field from repeated keys
+ *   where PVE wants a comma string — and that now lives on `PveForm` in client.ts, so both
+ *   products share one encoder and neither can reach for the other's convention by accident.
+ *
+ * 🔴 THIS ALIAS SAID `= PveTarget` AND IT WAS WRONG — Pbs.Datastore REQUIRED A PVE TARGET. When
+ *   `credentials.ts` grew a real `PbsTarget` with `scheme: 'pbs'`, this line was left pointing at
+ *   the PVE type, which pins `scheme: 'pve'`. So the one family that most needs the discriminant
+ *   was the one family that refused the correct value: declaring a datastore against the PBS host
+ *   failed to compile with `Type '"pbs"' is not assignable to type 'Input<"pve">'`, and passing a
+ *   PVE target compiled fine and would have 401'd every call — which `read` folds into "absent",
+ *   so the plan would say CREATE for a datastore holding the estate's backups.
+ *   ⛔ IT SURVIVED BECAUSE NOTHING EVER DECLARED ONE. The provider was registered in
+ *   alchemy.run.ts from the day it was written and `pveHandlers`' `list` answers empty, so
+ *   registration exercises no call site at all. Three sibling families import `PbsTarget` from
+ *   credentials.ts directly and were always correct; only the one with its own alias drifted.
+ *   ★ THE LESSON, WHICH IS NOT ABOUT THIS TYPE: a provider nobody has declared an instance of is
+ *   not tested by anything, including tsc.
+ */
+export type PbsTarget = ApiPbsTarget;
+export interface PbsDatastoreAttributes {
+    name: string;
+    /**
+     * ⚠️ READ FROM PBS, NEVER ECHOED FROM PROPS. Echoing the declared path would make a divergent or
+     *   unreadable datastore look like agreement, and this is the field whose divergence means the
+     *   backups are going somewhere nobody declared. `''` when PBS did not say.
+     */
+    path: string;
+    comment: string;
+    'gc-schedule': string;
+    'prune-schedule': string;
+    'keep-last': number;
+    'keep-hourly': number;
+    'keep-daily': number;
+    'keep-weekly': number;
+    'keep-monthly': number;
+    'keep-yearly': number;
+    /** Normalised property strings — sorted and canonicalised, so key order is never a diff. */
+    notify: string;
+    'notify-user': string;
+    'verify-new': boolean;
+    tuning: string;
+    'maintenance-mode': string;
+    /** ⚠️ Create-only. Canonicalised property string; `''` on a plain local datastore. */
+    backend: string;
+    'counter-reset-schedule': string;
+    'notification-thresholds': string;
+}
+/**
+ * ⚠️ `digest` IS DELIBERATELY NOT AN ATTRIBUTE, for storage.ts's reason exactly: PBS returns one on
+ *   every read and it covers `datastore.cfg` as a FILE, not this section of it, so keeping it would
+ *   rewrite this resource's state whenever an unrelated datastore was edited — churn that reads
+ *   like drift. It is not sent on writes either, so this family never joins PBS's optimistic-locking
+ *   dance and last write wins, as everywhere else in this package.
+ */
+export declare const attributes: (live: Record<string, unknown>, props: PbsDatastoreProps) => PbsDatastoreAttributes;
+/**
+ * ⛔ DECLARING WHAT IS LIVE MUST PLAN noop, AND EVERY OMISSION IS DELIBERATE. Out: `name` (the
+ *   address the read was made at — true by construction, never a diff); `path` (create-only, so
+ *   comparing it could only plan an update no PUT can apply — pbs-datastore.ts guards it by dying
+ *   instead, see the ⛔ on the prop); `digest` (not an attribute, above); and every field the
+ *   declaration does not mention, because undeclared is UNMANAGED here.
+ * ⚠️ A SCHEDULE THAT NEVER SETTLES MEANS PBS NORMALISED IT. Calendar events are compared as trimmed
+ *   strings; if a version rewrites `sat 18:15` as `Sat 18:15` the plan asks for the same update
+ *   forever. The fix is to declare the spelling PBS stores, never to stop comparing it.
+ */
+export declare const matches: (live: PbsDatastoreAttributes, props: PbsDatastoreProps) => boolean;
+/**
+ * ⚠️ `path` IS SENT ONCE, HERE, AND NEVER AGAIN — the fact the whole `path` guard hangs off.
+ * ⚠️ `reuse-datastore` IS NOT SENT, AND THE REFUSAL IT CAUSES IS A FEATURE: without it PBS refuses
+ *   a create against a directory that already holds a chunk store, which is the difference between
+ *   building a new store and silently adopting somebody else's backups. Adopt out of band.
+ * ⚠️ NEITHER IS `backing-device`. A removable datastore's UUID is a property of the hardware in the
+ *   slot, not of the declaration; one that could re-point it is one that can send backups to the
+ *   wrong drive.
+ */
+export declare const createForm: (props: PbsDatastoreProps) => PveForm;
+/**
+ * ⛔ THERE IS NO `delete` LIST HERE, AND THAT IS A CHOICE ABOUT BACKUPS RATHER THAN AN OMISSION.
+ *   sdn-vnet.ts derives one from absent props, which is right for an alias and wrong for a
+ *   retention policy: a declaration that simply fails to mention `keep-daily` would strip it, and a
+ *   prune job whose keeps have all been stripped is one PBS version away from a prune job that
+ *   keeps nothing. So undeclared is UNMANAGED, as in storage.ts and backup-job.ts.
+ *   ⚠️ THE PRICE IS THAT DROPPING A LINE DOES NOT CLEAR A FIELD. Clear one out of band:
+ *     `proxmox-backup-manager datastore update <name> --delete keep-daily`. It does not cost a
+ *     forever-diff, because an undeclared field is not compared either.
+ *   ⛔ WHEN SOMEBODY ADDS ONE, IT TAKES TWO STEPS AND SKIPPING EITHER IS A SILENT BUG. First build
+ *     it with `values.withClears`, which drops a cleared key from the body — CLEAR WINS — because
+ *     PBS applies its deletes BEFORE its sets, so a key both set and deleted keeps its value: the
+ *     declaration would say "unset this", the PUT would succeed, and the next plan would ask for
+ *     the very same update forever. (PVE instead DIES on that pair; the two behaviours want the
+ *     same guard.) Second, split the comma-joined value `withClears` produces into a real array —
+ *     PBS's `delete` is `type: array` and wants REPEATED KEYS, and a comma string arrives as one
+ *     element that fails the enum check. `PveForm` and `encode` already carry arrays for exactly
+ *     this. ⚠️ REASONED FROM THE PUBLISHED SCHEMA, NOT PROVEN ON A WIRE.
+ */
+export declare const updateForm: (props: PbsDatastoreProps) => PveForm;
+export declare const object: (props: PbsDatastoreProps) => string;
+/**
+ * The live datastore, or undefined.
+ *
+ * ⛔ `name` IS THE PRESENCE TEST, NOT THE STATUS CODE — PBS does not answer 404 for a section that
+ *   is missing from `datastore.cfg`, it answers a generic error, so there is no code to key off.
+ * ⛔ A MISSING READ PRIVILEGE THEREFORE LOOKS EXACTLY LIKE ABSENCE, because the fold below cannot
+ *   tell them apart. The signature is a plan that says CREATE followed by PBS answering
+ *   "datastore '<name>' already exists." — that pair means Datastore.Audit, not a missing
+ *   datastore. It is loud and non-destructive, which is the only reason the fold is tolerable here;
+ *   see the ⛔ on `readRole` in resource.ts for the PVE families where it is not.
+ * ⛔ ON THE DELETE PATH THE SAME FOLD IS A LIE, AND THIS IS THE ONE HAZARD IN THIS FAMILY I COULD
+ *   NOT CLOSE. `delete` settles by polling this read until it answers `undefined` — and a `read`
+ *   role that lacks `Datastore.Audit` answers `undefined` from the very first poll, so EVERY delete
+ *   would report success while the datastore stood. Worse, the two lanes are different leases: the
+ *   DELETE goes out under `provision` and may genuinely fail, and this read cannot see that it did.
+ *   ★ THE SHAPE OF THE FIX IS ALREADY IN THIS PACKAGE: `confirmAbsent` in ceph-pool-settle.ts asks
+ *     a SECOND, DIFFERENT question — does the collection LIST this object? — and lets a failure
+ *     PROPAGATE rather than folding it, so "I could not ask" fails the deploy instead of passing
+ *     it. Add the same over `GET /config/datastore` before anyone relies on a reported deletion.
+ *   ⚠️ UNTIL THEN THE PRECONDITION IS EXPLICIT: the `read` role MUST hold `Datastore.Audit` on the
+ *     datastore, or this provider cannot tell a deletion from a refusal.
+ */
+export declare const readOne: (props: PbsDatastoreProps) => Effect.Effect<PbsDatastoreAttributes | undefined, never, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=pbs-datastore-form.d.ts.map

package/dist/proxmox/pbs-datastore-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pbs-datastore-form.d.ts","sourceRoot":"","sources":["../../src/proxmox/pbs-datastore-form.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,KAAK,OAAO,EAAO,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,IAAI,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG5D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,SAAS,GAAG,YAAY,CAAC;AAErC,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,4FAA4F;IAC5F,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB,EAAE,MAAM,CAAC;IACjC,yBAAyB,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,SACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SACtB,iBAAiB,KACvB,sBAoBD,CAAC;AAIH;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO,SAAU,sBAAsB,SAAS,iBAAiB,YAkBK,CAAC;AAqCpF;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,UAAW,iBAAiB,KAAG,OASpD,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,UAAU,UAAW,iBAAiB,KAAG,OAAyB,CAAC;AAEhF,eAAO,MAAM,MAAM,UAAW,iBAAiB,WAAqC,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,OAAO,UAAW,iBAAiB,mHAM7C,CAAC"}

package/dist/proxmox/pbs-datastore-guard.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The two things a datastore write needs that are not form-building: refusing a moved `path`, and
+ * waiting for PBS to finish.
+ *
+ * ★ SPLIT OUT OF pbs-datastore-form.ts FOR THE 250-LINE CAP, and the seam is real. That file turns
+ *   a declaration into a form; this one is the SAFETY GUARD and the POLLING. A reader asking "can
+ *   this destroy my backups" has one short file to read rather than a long one to search.
+ */
+import * as Effect from 'effect/Effect';
+import { type PbsDatastoreAttributes } from './pbs-datastore-form.ts';
+import type { PbsDatastoreProps } from './pbs-datastore.ts';
+/**
+ * ⛔ THE `path` GUARD, YIELDED FROM BOTH `diff` AND `reconcile`. Both need it: `diff` catches a
+ *   changed declaration, and `reconcile` catches an ADOPTION, which Alchemy routes straight past
+ *   `diff` (Apply.ts:980, :1045). `''` is skipped — an unreadable path is not a divergent one.
+ */
+export declare const guardPath: (live: PbsDatastoreAttributes, props: PbsDatastoreProps) => Effect.Effect<void, never, never>;
+/**
+ * ⛔ THE `backend` GUARD, AND IT MATTERS MORE THAN `path`. A wrong `path` sends backups to the
+ *   wrong directory on the same machine; a wrong `backend` is the difference between a datastore
+ *   on local disk and one in a Cloudflare R2 bucket. MEASURED on 4.2: `datastore create` takes
+ *   `--backend`, `datastore update` does not, and `backend` is not in update's `--delete` enum —
+ *   so divergence CANNOT be reconciled, and the only honest options are to refuse or to lie.
+ *
+ * ⚠️ AN UNDECLARED `backend` IS NOT A DIVERGENCE. Undeclared is unmanaged everywhere in this
+ *   family, and this guard keeps that rule: it fires only when the declaration says something and
+ *   PBS says something else. Adopting `r2-offsite` without mentioning `backend` still plans noop.
+ *
+ * ⚠️ COMPARED AS A CANONICAL PROPERTY STRING, so `bucket=x,type=s3` and `type=s3,bucket=x` are the
+ *   same backend and key order cannot deadlock a plan — the reason `samePath` trims a slash.
+ */
+export declare const guardBackend: (live: PbsDatastoreAttributes, props: PbsDatastoreProps) => Effect.Effect<void, never, never>;
+/**
+ * Wait for PBS to finish, then answer the last thing it said.
+ *
+ * ⛔ IT EXISTS BECAUSE A PBS CREATE IS A FORKED WORKER AND THE CONFIG SECTION IS WRITTEN LAST.
+ *   `POST /config/datastore` answers with a UPID while a `create-datastore` task builds the chunk
+ *   store's 65536 directories; only when that finishes does the section reach `datastore.cfg`. An
+ *   immediate read-back therefore sees a datastore that is not there yet, and the factory's "the
+ *   write returned no error but the object is still absent" would fire on a create going perfectly.
+ *   The DELETE forks a worker too. ⚠️ DOCUMENTED FROM THE PUBLISHED SCHEMA, NOT MEASURED — I hold
+ *   no PBS token. If a create turns out to be synchronous, the first poll simply succeeds.
+ * ★ IT TAKES THE READ AS AN EFFECT RATHER THAN A FUNCTION — the one simplification over
+ *   ceph-pool-settle.ts: an Effect is a description, so re-running it re-reads and no dependency
+ *   has to be threaded back in to avoid a cycle.
+ * ⚠️ 2s APART, 60 TRIES, ABOUT TWO MINUTES — longer than ceph-pool's minute, and REASONED rather
+ *   than measured: 65536 `mkdir`s is seconds on NVMe and can be a minute on a slow or USB disk.
+ *   Anything still unsettled after two minutes is a fault to surface, not a wait to lengthen, and
+ *   the caller's message points at the task log, which is where the real answer is. `Effect.sleep`
+ *   yields between polls; nothing here parks a call on one long wait.
+ * ⚠️ POLLING THE TASK STATUS INSTEAD WOULD BE WORSE, for ceph-pool-settle.ts's reason: every call
+ *   mints a FRESH token, so the token asking about the task is not the one that started it.
+ */
+export declare const settle: <A, E, R>(read: Effect.Effect<A, E, R>, done: (live: A) => boolean) => Effect.Effect<A, E, R>;
+//# sourceMappingURL=pbs-datastore-guard.d.ts.map

package/dist/proxmox/pbs-datastore-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pbs-datastore-guard.d.ts","sourceRoot":"","sources":["../../src/proxmox/pbs-datastore-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,KAAK,sBAAsB,EAAU,MAAM,yBAAyB,CAAC;AAC9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAmB5D;;;;GAIG;AACH,eAAO,MAAM,SAAS,SAAU,sBAAsB,SAAS,iBAAiB,sCAWzE,CAAC;AAER;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,SAAU,sBAAsB,SAAS,iBAAiB,sCAY5E,CAAC;AAER;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,2BAQpF,CAAC"}

package/dist/proxmox/pbs-datastore.d.ts

@@ -0,0 +1,140 @@
+/**
+ * `Pbs.Datastore` — one section of Proxmox Backup Server's `datastore.cfg`, declared.
+ *
+ * ★ PBS IS A SIBLING OF PVE, NOT A PART OF IT. The estate runs both — PVE carries a storage of
+ *   `type: pbs` — so declaring the datastore turns `Proxmox.Storage`'s `locator.datastore` from a
+ *   string nothing checks into a reference Alchemy can order, as `Proxmox.SdnVnet` did for a bridge.
+ *
+ * ⛔ DIFFERENT HOST, DIFFERENT REALM, DIFFERENT AUTH HEADER. MEASURED 2026-09-13, strict TLS, no
+ *   `-k` anywhere: `GET https://pbs.example.com:8007/api2/json/ping` answers 200
+ *   `{"data":{"pong":true}}` against a Let's Encrypt certificate for CN=pbs.example.com;
+ *   `/version` and `/config/datastore` answer 401 "authentication failed";
+ *   `pbs.mgmt.example.com:8007` answers 401 and its certificate verifies too; and
+ *   `/access/domains` lists the realms `pbs`, `pam` and an openid realm `Schenanigans`. So the
+ *   prefix, the `{"data": …}` envelope and the strict-TLS story are PVE's exactly — and only the
+ *   credential differs. There is no `pve` realm here; a PVE token cannot authenticate at all.
+ *   The header differs too, which is why `pve()` exists rather than `pve()` being reused — see the
+ *   ⛔ on `pbsAuthorization` in pbs-datastore-form.ts.
+ *
+ * ⛔ THERE IS NO OPENBAO MOUNT FOR PBS TODAY, SO NOTHING HERE CAN DEPLOY YET. `PbsTarget.mount` is
+ *   a parameter for the reason `PveTarget.mount` is — the provider must be able to leave this
+ *   estate — but the estate has nothing to put in it. MEASURED: under the `claude-code` approle,
+ *   `bao token capabilities` answers `deny` for `proxmox-tb4/creds/{read,provision}`,
+ *   `proxmox-ops/creds/read` and every `…pbs…` path tried, and `sys/mounts` is 403 — so I could
+ *   not enumerate the mounts to PROVE a PBS one is absent. That it is absent is the brief's
+ *   statement, not my measurement.
+ *   ★ WHAT THE MOUNT MUST VEND, so `mint()` is reused unchanged: `bao read -format=json
+ *     <mount>/creds/<role>` answering `{"data":{"token_id":…,"secret":…}}`, where `token_id` is a
+ *     PBS token id `user@realm!tokenname` — `hf-read@pbs!…` and `hf-provision@pbs!…`. Same short,
+ *     non-renewable lease contract as `proxmox-tb4`.
+ *   ⚠️ PBS HAS NO DYNAMIC-SECRETS PLUGIN OF ITS OWN — OpenBao's Proxmox support is a PVE thing — so
+ *     the mount is a small custom vendor against `POST /access/users/{id}/token/{name}`. Say which
+ *     mount and role you needed rather than reaching for the read-only `monitoring@pbs` token on
+ *     the kv shelf: widening that would delete the outer lock for every reader of the shelf.
+ *
+ * ⛔ A DATASTORE HOLDS THE BACKUPS, SO `retain` IS THE DEFAULT AND `delete` IS FULLY IMPLEMENTED —
+ *   the ★ on removal policy in resource.ts has the whole reasoning. A stub returning `Effect.void`
+ *   would report a deletion that never happened, and this is the family where that lie costs most.
+ *
+ * ⚠️ PRIVILEGES, READ OFF THE PUBLISHED SCHEMA RATHER THAN OFF THIS HOST:
+ *     read   GET    config/datastore/{name}   Datastore.Audit    on /datastore/{name}
+ *     create POST   config/datastore          Datastore.Allocate on /datastore
+ *     update PUT    config/datastore/{name}   Datastore.Modify   on /datastore/{name}
+ *     delete DELETE config/datastore/{name}   Datastore.Allocate on /datastore/{name}
+ *   Built-in `DatastoreAdmin` at `/datastore` covers all four; `DatastoreAudit` covers the read
+ *   lane alone, which is what the `read` role should hold.
+ *
+ * ⛔ NO SECRET IS A PROP OR AN ATTRIBUTE, AND THIS FAMILY IS CLEAN BY CONSTRUCTION: a datastore
+ *   section holds no password, token or key — encryption keys belong to the backup CLIENT. Every
+ *   field below is a name, a path, a schedule, a count or a policy string, all of which are safe in
+ *   a state store Alchemy writes UNENCRYPTED and this estate dumps to CT100 nightly.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import { type PbsDatastoreAttributes, type PbsTarget } from './pbs-datastore-form.ts';
+import type { PveRequirements } from './resource.ts';
+export type { PbsDatastoreAttributes, PbsTarget };
+/**
+ * ⚠️ PBS'S OWN KEY NAMES, HYPHENS INCLUDED — backup-job.ts's rule: the form 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.
+ * ⚠️ AN UNDECLARED FIELD IS NEITHER SENT NOR COMPARED — storage.ts's rule, not sdn-vnet.ts's, and
+ *   for a retention policy the choice is not close: see the ⛔ on `updateForm`.
+ */
+export interface PbsDatastoreProps {
+    target: PbsTarget;
+    /** PBS's primary key. Create-only: there is no rename, and a new name is a new datastore. */
+    name: string;
+    /**
+     * Absolute path to the datastore directory.
+     *
+     * ⛔ CREATE-ONLY, AND THE ONE FIELD THIS FILE REFUSES TO LET DRIFT QUIETLY. PBS's update endpoint
+     *   does not accept `path`, so comparing it in `matches` could only plan an update no PUT can
+     *   apply — the forever-diff storage.ts avoids by letting its create-only `type` plan as NOOP.
+     *   Here a silent noop is the wrong trade: the operator would read a green plan while PBS kept
+     *   writing backups to the old directory. So `diff` and `reconcile` compare it themselves and DIE
+     *   with both values named. A path change is remove-and-redeclare, deliberately.
+     */
+    path: string;
+    comment?: string;
+    /** Calendar event for garbage collection, e.g. `daily` or `sat 18:15`. */
+    'gc-schedule'?: string;
+    /** Calendar event for the built-in prune job. Retention itself is the `keep-*` fields below. */
+    'prune-schedule'?: string;
+    /** ⚠️ PBS's minimum is 1 for every keep-*. A declared `0` is refused, and does not mean "off". */
+    'keep-last'?: number;
+    'keep-hourly'?: number;
+    'keep-daily'?: number;
+    'keep-weekly'?: number;
+    'keep-monthly'?: number;
+    'keep-yearly'?: number;
+    /**
+     * Legacy notification routing: `gc=<never|always|error>`, and the same for `verify` and `sync`.
+     * ⚠️ PBS 3.2+ picks between this and the notification system with `notification-mode`, which is
+     *   NOT declarable here: flipping a live datastore between the two silently changes who hears
+     *   about a failed verify, and silence is the failure mode that costs most (notification-target.ts).
+     */
+    notify?: string;
+    /** PBS user id legacy notifications go to. PBS's schema default is `root@pam`. */
+    'notify-user'?: string;
+    /** Verify every new backup the moment it completes. PBS's default is false. */
+    'verify-new'?: boolean;
+    /** Property string: `chunk-order=<none|inode>,sync-level=<none|file|filesystem>`, and more. */
+    tuning?: string;
+    /**
+     * Takes the datastore out of service: `type=<offline|read-only|unmount>`, optional
+     * `message=<text>`. PBS's default key is `type`, so the bare `offline` normalises to the same
+     * string here and either spelling is safe.
+     * ⛔ NEVER DECLARE `type=delete`. PBS sets that itself while destroying a datastore's contents.
+     * ⚠️ A `message` CONTAINING A COMMA BREAKS THE COMPARISON, not the write: `propertyString` splits
+     *   on commas and does not honour PBS's quoting, so the two sides never compare equal and the
+     *   plan asks for the same update forever. Keep the message comma-free.
+     */
+    'maintenance-mode'?: string;
+    /**
+     * ⛔ CREATE-ONLY, LIKE `path`, AND FOR A SHARPER REASON. MEASURED on the live 4.2 host:
+     *   `datastore create --help` offers `--backend`, `datastore update --help` does NOT, and
+     *   `backend` is absent from update's `--delete` enum. PBS will not move a datastore between
+     *   local disk and object storage, ever.
+     * ★ IT IS A PROP AT ALL BECAUSE THE ESTATE HAS ONE. `r2-offsite` holds
+     *   `type=s3,client=cloudflare-r2,bucket=homeflare-pbs`. Leaving it undeclared would still plan
+     *   noop — undeclared is unmanaged here — but the declaration would then describe a LOCAL
+     *   datastore, and anyone recreating from it would get exactly that: an empty directory on the
+     *   mini's disk where the offsite copy used to be, behind a green plan the whole way.
+     * ⚠️ A property string. Compared canonically, so key order is never a diff.
+     */
+    backend?: string;
+    /** ⚠️ S3 request counters reset on this calendar event. Mutable; in update's `--delete` enum. */
+    'counter-reset-schedule'?: string;
+    /**
+     * ⚠️ S3 request-count thresholds that raise a notification, e.g. `s3-put=700000,s3-get=200000`.
+     *   A property string, compared canonically. Mutable.
+     */
+    'notification-thresholds'?: string;
+}
+export interface PbsDatastore extends Resource<'Pbs.Datastore', PbsDatastoreProps, PbsDatastoreAttributes, never, PveRequirements> {
+}
+/** ★ `retain` by default — a datastore holds the backups. See the ★ in resource.ts. */
+export declare const PbsDatastore: import("alchemy").ResourceClass<PbsDatastore>;
+export declare const PbsDatastoreProvider: () => import("effect/Layer").Layer<Provider.Provider<PbsDatastore>, never, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=pbs-datastore.d.ts.map

package/dist/proxmox/pbs-datastore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pbs-datastore.d.ts","sourceRoot":"","sources":["../../src/proxmox/pbs-datastore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAG7C,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,SAAS,EAMf,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,YAAY,EAAE,sBAAsB,EAAE,SAAS,EAAE,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,SAAS,CAAC;IAClB,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;OASG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gGAAgG;IAChG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kGAAkG;IAClG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,+FAA+F;IAC/F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,YAAa,SAAQ,QAAQ,CAC5C,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,EACL,eAAe,CAChB;CAAG;AAEJ,uFAAuF;AACvF,eAAO,MAAM,YAAY,+CAEvB,CAAC;AAEH,eAAO,MAAM,oBAAoB,kIA4G9B,CAAC"}

package/dist/proxmox/pbs-prune-job-form.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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';
+/**
+ * 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 declare const KEEP_KEYS: readonly ['keep-last', 'keep-hourly', 'keep-daily', 'keep-weekly', 'keep-monthly', 'keep-yearly'];
+export type KeepKey = (typeof KEEP_KEYS)[number];
+/**
+ * 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 declare const keepAttributes: (live: Record<string, unknown>) => Pick<PruneJobAttributes, KeepKey>;
+/**
+ * ⚠️ 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 declare const keepsMatch: (attributes: Pick<PruneJobAttributes, KeepKey>, props: PruneJobProps) => boolean;
+/**
+ * ⛔ `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 declare const createBody: (props: PruneJobProps) => Record<string, string>;
+/**
+ * ⛔ 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 declare const updateBody: (props: PruneJobProps) => Record<string, string>;
+//# sourceMappingURL=pbs-prune-job-form.d.ts.map

package/dist/proxmox/pbs-prune-job-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pbs-prune-job-form.d.ts","sourceRoot":"","sources":["../../src/proxmox/pbs-prune-job-form.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAG5E;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,YACpB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,aAAa,EACb,cAAc,EACd,aAAa,CACL,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAYjD;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,SACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,IAAI,CAAC,kBAAkB,EAAE,OAAO,CAOjC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,eAAgB,IAAI,CAAC,kBAAkB,EAAE,OAAO,CAAC,SAAS,aAAa,YACR,CAAC;AA0EvF;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,UAAW,aAAa,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAGtE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,UAAU,UAAW,aAAa,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAGtE,CAAC"}

package/dist/proxmox/pbs-prune-job.d.ts

@@ -0,0 +1,168 @@
+/**
+ * `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 type { PbsTarget } from './credentials.ts';
+import { type PveRequirements, type WithPbsTarget } from './resource.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 declare const PbsPruneJob: import("alchemy").ResourceClass<PbsPruneJob>;
+/**
+ * ⛔ `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 declare const PbsPruneJobProvider: () => import("effect/Layer").Layer<Provider.Provider<PbsPruneJob>, never, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=pbs-prune-job.d.ts.map