@homeflare/alchemy 0.1.0

package/src/proxmox/pbs-datastore-form.ts

@@ -0,0 +1,248 @@
+/**
+ * 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, pve } from './client.ts';
+import type { PbsTarget as ApiPbsTarget } from './credentials.ts';
+import type { PbsDatastoreProps } from './pbs-datastore.ts';
+import { bool, flag, int, propertyString, text } from './values.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 const attributes = (
+  live: Record<string, unknown>,
+  props: PbsDatastoreProps,
+): PbsDatastoreAttributes => ({
+  backend: propertyString(live['backend']),
+  comment: text(live['comment']),
+  'counter-reset-schedule': text(live['counter-reset-schedule']).trim(),
+  'gc-schedule': text(live['gc-schedule']).trim(),
+  '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),
+  'maintenance-mode': propertyString(live['maintenance-mode'], 'type'),
+  name: props.name,
+  'notification-thresholds': propertyString(live['notification-thresholds']),
+  notify: propertyString(live['notify']),
+  'notify-user': text(live['notify-user']),
+  path: text(live['path']),
+  'prune-schedule': text(live['prune-schedule']).trim(),
+  tuning: propertyString(live['tuning']),
+  'verify-new': bool(live['verify-new']),
+});
+
+const same = <T>(declared: T | undefined, live: T) => declared === undefined || declared === live;
+
+/**
+ * ⛔ 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 const matches = (live: PbsDatastoreAttributes, props: PbsDatastoreProps) =>
+  same(props.comment, live.comment) &&
+  same(props['gc-schedule']?.trim(), live['gc-schedule']) &&
+  same(props['prune-schedule']?.trim(), live['prune-schedule']) &&
+  same(props['keep-last'], live['keep-last']) &&
+  same(props['keep-hourly'], live['keep-hourly']) &&
+  same(props['keep-daily'], live['keep-daily']) &&
+  same(props['keep-weekly'], live['keep-weekly']) &&
+  same(props['keep-monthly'], live['keep-monthly']) &&
+  same(props['keep-yearly'], live['keep-yearly']) &&
+  same(props['notify-user'], live['notify-user']) &&
+  same(props['counter-reset-schedule']?.trim(), live['counter-reset-schedule']) &&
+  (props['notification-thresholds'] === undefined ||
+    propertyString(props['notification-thresholds']) === live['notification-thresholds']) &&
+  same(props['verify-new'], live['verify-new']) &&
+  (props.notify === undefined || propertyString(props.notify) === live.notify) &&
+  (props.tuning === undefined || propertyString(props.tuning) === live.tuning) &&
+  (props['maintenance-mode'] === undefined ||
+    propertyString(props['maintenance-mode'], 'type') === live['maintenance-mode']);
+
+const set = (key: string, value: string | undefined): Record<string, string> =>
+  value === undefined ? {} : { [key]: value };
+
+/** ⚠️ PBS's minimum for every keep-* is 1, so a declared `0` is refused rather than meaning "off". */
+const count = (value: number | undefined) => (value === undefined ? undefined : String(value));
+
+/**
+ * The mutable half, shared by create and update.
+ *
+ * ⚠️ AN UNDECLARED FIELD IS NOT SENT — storage.ts's rule. PBS leaves a parameter it was not given
+ *   alone, so this form is safe to re-apply to a datastore that already matches, which is what the
+ *   adoption path does.
+ * ⛔ `name` AND `path` ARE ABSENT ON PURPOSE. Both are create-only: `name` is the address forever
+ *   after, and PBS's update endpoint does not accept `path` at all, so including it here would turn
+ *   every single update into a 400.
+ */
+const mutable = (props: PbsDatastoreProps): Record<string, string> => ({
+  ...set('comment', props.comment),
+  ...set('gc-schedule', props['gc-schedule']?.trim()),
+  ...set('keep-daily', count(props['keep-daily'])),
+  ...set('keep-hourly', count(props['keep-hourly'])),
+  ...set('keep-last', count(props['keep-last'])),
+  ...set('keep-monthly', count(props['keep-monthly'])),
+  ...set('keep-weekly', count(props['keep-weekly'])),
+  ...set('keep-yearly', count(props['keep-yearly'])),
+  ...set('counter-reset-schedule', props['counter-reset-schedule']),
+  ...set('maintenance-mode', props['maintenance-mode']),
+  ...set('notification-thresholds', props['notification-thresholds']),
+  ...set('notify', props.notify),
+  ...set('notify-user', props['notify-user']),
+  ...set('prune-schedule', props['prune-schedule']?.trim()),
+  ...set('tuning', props.tuning),
+  ...set('verify-new', flag(props['verify-new'])),
+});
+
+/**
+ * ⚠️ `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 const createForm = (props: PbsDatastoreProps): PveForm => ({
+  ...mutable(props),
+  name: props.name,
+  path: props.path,
+  // ⛔ CREATE ONLY, AND ABSENT FROM `mutable` ON PURPOSE. PBS has no `--backend` on update and no
+  //   `backend` in update's `--delete` enum (measured on 4.2), so sending it on a PUT is a
+  //   parameter error at best. Divergence is caught by guardBackend, which DIES — the same shape
+  //   as `path`, for a bigger consequence.
+  ...(props.backend === undefined ? {} : { backend: props.backend }),
+});
+
+/**
+ * ⛔ 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 const updateForm = (props: PbsDatastoreProps): PveForm => mutable(props);
+
+export const object = (props: PbsDatastoreProps) => `config/datastore/${props.name}`;
+
+/**
+ * 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 const readOne = (props: PbsDatastoreProps) =>
+  pve<Record<string, unknown>>(props.target, 'read', 'GET', object(props)).pipe(
+    Effect.map((live) =>
+      live === undefined || typeof live['name'] !== 'string' ? undefined : attributes(live, props),
+    ),
+    Effect.orElseSucceed(() => undefined),
+  );

package/src/proxmox/pbs-datastore-guard.ts

@@ -0,0 +1,105 @@
+/**
+ * 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, object } from './pbs-datastore-form.ts';
+import type { PbsDatastoreProps } from './pbs-datastore.ts';
+import { propertyString } from './values.ts';
+
+/**
+ * ⛔ A TRAILING SLASH MUST NOT DEADLOCK EVERY PLAN, WHICH IS WHY THIS IS NOT `===`. `guardPath`
+ *   DIES, so a false positive is not a spurious update — it is an `alchemy plan` that cannot run at
+ *   all until somebody edits the declaration, on a family whose whole point is that the operator
+ *   can see the state of their backups. `/mnt/backups/` and `/mnt/backups` are one directory, and
+ *   whether PBS canonicalises the path it was handed is a property of the version you are talking
+ *   to. Both sides are trimmed here so that guess cannot cost an outage of the plan itself.
+ * ⚠️ THAT IS THE ONLY NORMALISATION APPLIED. A symlink, a bind mount or `/mnt/./backups` still
+ *   reads as divergent, and deliberately so: this guard's job is to refuse to GUESS that two
+ *   spellings are the same directory, and only the trailing slash is certain.
+ */
+const samePath = (left: string, right: string) => {
+  const trim = (value: string) => (value.length > 1 ? value.replace(/\/+$/, '') : value);
+  return trim(left) === trim(right);
+};
+
+/**
+ * ⛔ 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 const guardPath = (live: PbsDatastoreAttributes, props: PbsDatastoreProps) =>
+  live.path === '' || samePath(live.path, props.path)
+    ? Effect.void
+    : Effect.die(
+        new Error(
+          `${object(props)}: declared path ${props.path} but PBS holds ${live.path}. \`path\` ` +
+            'is create-only, so this cannot be reconciled and will NOT be planned as a silent ' +
+            'noop: backups would keep landing in the old directory behind a green plan. Correct ' +
+            'the declaration, or remove the datastore and declare a new one -- the contents live, ' +
+            'because `destroy-data` is never sent.',
+        ),
+      );
+
+/**
+ * ⛔ 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 const guardBackend = (live: PbsDatastoreAttributes, props: PbsDatastoreProps) =>
+  props.backend === undefined || propertyString(props.backend) === live.backend
+    ? Effect.void
+    : Effect.die(
+        new Error(
+          `${object(props)}: declared backend ${props.backend} but PBS holds ` +
+            `${live.backend === '' ? '(none — a local datastore)' : live.backend}. \`backend\` ` +
+            'is create-only: PBS has no update for it, so this cannot be reconciled and will NOT ' +
+            'be planned as a silent noop. Correct the declaration to match what is really there, ' +
+            'or remove the datastore and declare a new one -- the contents live, because ' +
+            '`destroy-data` is never sent.',
+        ),
+      );
+
+/**
+ * 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 const settle = <A, E, R>(read: Effect.Effect<A, E, R>, done: (live: A) => boolean) =>
+  Effect.gen(function* () {
+    for (let attempt = 0; attempt < 60; attempt += 1) {
+      const live = yield* read;
+      if (done(live)) return live;
+      yield* Effect.sleep('2 seconds');
+    }
+    return yield* read;
+  });

package/src/proxmox/pbs-datastore.ts

@@ -0,0 +1,271 @@
+/**
+ * `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 { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { pve } from './client.ts';
+import {
+  type PbsDatastoreAttributes,
+  type PbsTarget,
+  createForm,
+  matches,
+  object,
+  readOne,
+  updateForm,
+} from './pbs-datastore-form.ts';
+import { guardBackend, guardPath, settle } from './pbs-datastore-guard.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 const PbsDatastore = Resource<PbsDatastore>('Pbs.Datastore', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const PbsDatastoreProvider = () =>
+  Provider.effect(
+    PbsDatastore,
+    Effect.succeed(
+      PbsDatastore.Provider.of({
+        /**
+         * ⛔ EMPTY, AND HERE IT GUARDS THE ESTATE'S BACKUPS. `GET /config/datastore` returns every
+         *   datastore on the host, the one PVE's `type: pbs` storage writes into included. See
+         *   `pveHandlers` in resource.ts for why adoption stays an explicit act.
+         */
+        list: () => Effect.succeed([]),
+        read: ({ olds }) => readOne(olds),
+        /**
+         * ⚠️ `isResolved` IS THE NARROWING, resource.ts's reason: at plan time a prop can still be an
+         *   unresolved Output, and comparing a placeholder to a live value reports a phantom update.
+         * ⛔ `guardPath` IS A DELIBERATE DEPARTURE FROM storage.ts, which lets its create-only field
+         *   plan as noop. Dying fails `alchemy plan` with both paths named — see the ⛔ on the prop.
+         */
+        diff: ({ news, output }) =>
+          Effect.gen(function* () {
+            if (output === undefined || !isResolved(news)) return undefined;
+            const live = yield* readOne(news);
+            // ⚠️ `update`, not `create` — Alchemy's Diff admits only noop/update/replace, and an
+            //   object Alchemy has state for but PBS does not is drift for reconcile to repair.
+            if (live === undefined) return { action: 'update' } as const;
+            yield* guardPath(live, news);
+            yield* guardBackend(live, news);
+            return matches(live, news)
+              ? ({ action: 'noop' } as const)
+              : ({ action: 'update' } as const);
+          }),
+        /**
+         * ⚠️ NOT THE FACTORY'S reconcile: it reads back ONCE, immediately — see the ⛔ on `settle`.
+         * ⛔ `guardPath` RUNS HERE TOO, AND THAT IS NOT BELT-AND-BRACES — see the ⛔ on it.
+         * ⛔ THE `matches` GUARD BEFORE THE PUT IS resource.ts's, AND IT IS WHY ADOPTION IS FREE.
+         */
+        reconcile: Effect.fn(function* ({ news }) {
+          const live = yield* readOne(news);
+          let upid: string | undefined;
+          if (live === undefined) {
+            upid = yield* pve<string>(
+              news.target,
+              'provision',
+              'POST',
+              'config/datastore',
+              createForm(news),
+            );
+          } else {
+            yield* guardPath(live, news);
+            yield* guardBackend(live, news);
+            // ⚠️ An empty form is not a write — resource.ts skips one for the same reason.
+            const form = updateForm(news);
+            if (!matches(live, news) && Object.keys(form).length > 0) {
+              yield* pve(news.target, 'provision', 'PUT', object(news), form);
+            }
+          }
+          const after = yield* settle(
+            readOne(news),
+            (row) => row !== undefined && matches(row, news),
+          );
+          if (after === undefined || !matches(after, news)) {
+            /**
+             * ⛔ REFUSE RATHER THAN RETURN THE PROPS AS THOUGH THEY LANDED — resource.ts's rule.
+             *   A create answers with a task id, so "no error" is not evidence of a datastore.
+             */
+            return yield* Effect.die(
+              new Error(
+                `${object(news)}: the write returned no error but the datastore still does not ` +
+                  `match the declaration after 120s. PBS answered with task ${upid ?? '(none)'} ` +
+                  '-- read it with `proxmox-backup-manager task log <upid>`. A slow disk is a ' +
+                  'plausible cause (see `settle`); a create over an existing chunk store is not, ' +
+                  'because PBS refuses that outright rather than timing out.',
+              ),
+            );
+          }
+          return after;
+        }),
+        /**
+         * ⛔ FULLY IMPLEMENTED, NEVER A STUB, and it only ever runs on an explicit
+         *   `.pipe(RemovalPolicy.destroy())` because this family defaults to `retain`.
+         * ⛔ NO `destroy-data`. PBS's DELETE drops the section from `datastore.cfg` and leaves every
+         *   chunk and snapshot on disk; `destroy-data=1` erases the contents. It is not a prop and
+         *   not a flag here, so this provider can un-declare a datastore and can never erase one.
+         *   ⚠️ IT IS STILL A ONE-WAY DOOR FOR A DECLARATION: re-adding a datastore over an existing
+         *     chunk store needs `reuse-datastore`, which is deliberately not declarable — see the
+         *     ⚠️ on `createForm`. Re-adopt with `proxmox-backup-manager datastore create …`.
+         * ⚠️ NO `keep-job-configs` EITHER, SO THE JOBS GO TOO: PBS defaults it false and removes the
+         *   verify, sync and prune jobs referencing this datastore — objects nothing here declares.
+         *   PBS's default stands, so the blast radius is what a human clicking Remove would get.
+         * ⚠️ AND THE REFUSAL CAN ARRIVE AFTER THE RESPONSE: the delete forks a worker too, so a store
+         *   held open by a running backup can fail once the call has already returned 200.
+         */
+        delete: Effect.fn(function* ({ olds }) {
+          yield* pve<string>(olds.target, 'provision', 'DELETE', object(olds));
+          const left = yield* settle(readOne(olds), (row) => row === undefined);
+          if (left !== undefined) {
+            return yield* Effect.die(
+              new Error(
+                `${object(olds)}: the DELETE returned no error but the datastore is still in ` +
+                  'datastore.cfg after 120s. Either a backup, verify or GC task still holds it, ' +
+                  'or the provision role lacks Datastore.Allocate on /datastore/' +
+                  `${olds.name}. Read the task log with \`proxmox-backup-manager task log <upid>\`.`,
+              ),
+            );
+          }
+        }),
+      }),
+    ),
+  );