@homeflare/alchemy 0.1.0

package/src/proxmox/backup-job.ts

@@ -0,0 +1,213 @@
+/**
+ * `Proxmox.BackupJob` — the vzdump schedule, declared. The one object whose drift nothing else on
+ * the cluster reveals.
+ *
+ * ★ WHY THIS ONE EARNS ITS PLACE. A hand-made vzdump job drifts silently: a schedule moved by an
+ *   hour, a retention trimmed to `keep-last=1`, or `enabled 0` set during a maintenance window and
+ *   never set back. All three look like a healthy cluster from every angle except a restore.
+ *   Declared here, `diff` reads the LIVE job on every plan, so a hand edit surfaces as
+ *   `1 to update` that day rather than on the day somebody needs last night's backup and finds a
+ *   week-old one, or none.
+ *
+ * ⛔ PVE GENERATES `id` WHEN YOU OMIT IT, WHICH MAKES OMITTING IT THE WORST BUG THIS RESOURCE
+ *   COULD CARRY. PVE's own API schema says so in one parenthesis — `id`: "Job ID (will be
+ *   autogenerated)." — and a generated id looks like `backup-f56d8ab7-d524`. A resource that
+ *   POSTed without an id would create a SECOND job beside the first on EVERY reconcile, and the
+ *   read-back in `pveOperations` would still pass, because a job did appear: that check asks "is
+ *   the object there", not "is it the one I meant". So `id` is a REQUIRED prop and is always sent
+ *   on create. To adopt a job that already exists, declare its existing id; any other id is a new
+ *   job beside it, not an adoption.
+ *   ★ AN EXPLICIT id ALSO CLOSES A SECOND HOLE. `pveOperations.read` turns ANY failed GET into
+ *     "absent" — an expired lease, a 403, a node that did not answer — and reconcile then POSTs.
+ *     With an id, PVE refuses a duplicate section id and the deploy fails loudly; without one, that
+ *     same swallowed error would have quietly doubled the cluster's backup jobs.
+ *
+ * ⚠️ `Sys.Modify` ON `/` IS THE GATE AND IT IS NOT A SMALL GRANT. PVE has no Backup.* privilege:
+ *   create, update and delete of a vzdump job are all checked against `Sys.Modify` at `/` — the
+ *   same privilege that covers node network configuration. A credential that can declare backup
+ *   jobs can also rewrite the cluster's networking. That is PVE's granularity rather than a choice
+ *   made here, and it is exactly why widening a role for this should be a decision rather than a
+ *   reaction to a 403.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
+import { bool, guestList, propertyString, text } from './values.ts';
+
+/**
+ * ⚠️ THE PROPS ARE PVE'S OWN KEY NAMES, DASHES INCLUDED. `notes-template` rather than
+ *   `notesTemplate` is deliberate: `createForm` 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. A
+ *   field that is never sent reads back as whatever it already was, which is indistinguishable
+ *   from "PVE ignored me".
+ */
+export interface BackupJobProps extends WithTarget {
+  /** ⛔ The primary key, REQUIRED. Never let PVE generate it — see the ⛔ above. */
+  id: string;
+  /** A subset of systemd calendar events, e.g. `01:00` or `mon..fri 02:30`. */
+  schedule: string;
+  /** Target storage id. That storage's own retention applies unless `prune-backups` overrides it. */
+  storage?: string;
+  mode?: 'snapshot' | 'suspend' | 'stop';
+  /** PVE's default is enabled. A disabled job is a backup that silently is not happening. */
+  enabled?: boolean;
+  /** Back up every guest. ⚠️ Pick exactly one of `all`, `vmid` and `pool` — see `shape` below. */
+  all?: boolean;
+  vmid?: readonly number[];
+  pool?: string;
+  /** Guest ids to skip. PVE reads this as "all guests except these", so it belongs with `all`. */
+  exclude?: readonly number[];
+  /** Retention, as a property string: `keep-daily=7,keep-weekly=4`. */
+  'prune-backups'?: string;
+  /** Supports {{cluster}}, {{guestname}}, {{node}} and {{vmid}}. Single line only. */
+  'notes-template'?: string;
+  'notification-mode'?: 'auto' | 'legacy-sendmail' | 'notification-system';
+  /** Run a missed job as soon as the scheduler is back. */
+  'repeat-missed'?: boolean;
+  /** VM-only fleecing, as a property string: `enabled=1,storage=<id>`. See `propertyString`. */
+  fleecing?: string;
+  comment?: string;
+}
+
+export interface BackupJobAttributes {
+  id: string;
+  schedule: string;
+  storage: string;
+  mode: string;
+  enabled: boolean;
+  all: boolean;
+  /** Sorted and comma-joined, so re-ordering a declaration is not a diff. See `guestList`. */
+  vmid: string;
+  pool: string;
+  exclude: string;
+  /** Flattened and sorted — never the raw value PVE returned. See `propertyString`. */
+  'prune-backups': string;
+  'notes-template': string;
+  'notification-mode': string;
+  'repeat-missed': boolean;
+  fleecing: string;
+  comment: string;
+  /**
+   * PVE's own estimate, epoch seconds. REPORTED, NEVER COMPARED: `next-run` in `matches` would
+   * report an update every time the clock passed a scheduled run. It is here so a plan can show
+   * that a job is still due — a `next-run` of 0 is a job the scheduler will not run.
+   */
+  'next-run': number;
+}
+
+export interface ProxmoxBackupJob extends Resource<
+  'Proxmox.BackupJob',
+  BackupJobProps,
+  BackupJobAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const ProxmoxBackupJob = Resource<ProxmoxBackupJob>('Proxmox.BackupJob');
+
+/**
+ * The form for both create and update.
+ *
+ * ⛔ A FIELD THE DECLARATION LEAVES OUT IS NOT SENT, AND THAT IS LOAD BEARING. PVE's PUT can only
+ *   SET a key; clearing one needs `delete=<key>`, which this resource deliberately never sends.
+ *   `updateForm` is handed the props and nothing else, so a `delete` list could only be "every
+ *   field you did not declare" — and on a job adopted out of the UI that would silently strip
+ *   settings this resource does not even model, `compress`, `mailto` and `bwlimit` among them, on
+ *   the first deploy. Leaving undeclared fields alone is the smaller lie, and `matches` tells the
+ *   same lie consistently: it does not compare what it cannot change.
+ *
+ * ⚠️ THE FIVE FIELDS PVE DOCUMENTS A DEFAULT FOR ARE ALWAYS SENT AND ALWAYS COMPARED — `enabled`
+ *   (1), `all` (0), `mode` (snapshot), `notification-mode` (auto), `repeat-missed` (0). That is
+ *   what makes a hand-flipped `enabled 0` show up as drift rather than as silence, and it is also
+ *   what stops those five looping: a field compared against a default must be sent as that
+ *   default, or every plan reports an update the PUT never performs. The cost is worth reading
+ *   before the first deploy against an adopted job — an omitted `all` is a declaration that this
+ *   job backs up NOTHING, and PVE accepts a job that selects nothing without a word. Read that
+ *   first plan; do not deploy it unseen.
+ */
+const shape = (props: BackupJobProps) => ({
+  all: props.all === true ? '1' : '0',
+  enabled: props.enabled === false ? '0' : '1',
+  mode: props.mode ?? 'snapshot',
+  'notification-mode': props['notification-mode'] ?? 'auto',
+  'repeat-missed': props['repeat-missed'] === true ? '1' : '0',
+  schedule: props.schedule,
+  ...(props.comment === undefined ? {} : { comment: props.comment }),
+  ...(props.exclude === undefined ? {} : { exclude: guestList(props.exclude) }),
+  ...(props.fleecing === undefined ? {} : { fleecing: props.fleecing }),
+  ...(props['notes-template'] === undefined ? {} : { 'notes-template': props['notes-template'] }),
+  ...(props.pool === undefined ? {} : { pool: props.pool }),
+  ...(props['prune-backups'] === undefined ? {} : { 'prune-backups': props['prune-backups'] }),
+  ...(props.storage === undefined ? {} : { storage: props.storage }),
+  ...(props.vmid === undefined ? {} : { vmid: guestList(props.vmid) }),
+});
+
+const handlers = pveHandlers<BackupJobProps, BackupJobAttributes>({
+  /**
+   * ⛔ NO "IS IT REALLY THERE" GUARD, ON PURPOSE. Returning undefined for a job whose JSON is
+   *   missing some key would be a guess about which keys PVE echoes back, and a wrong guess here
+   *   does not read as absent-and-harmless: `reconcile` would POST, and POST creates ANOTHER job.
+   *   Absence is decided by the API declining to answer, which `pveOperations.read` already
+   *   handles — not by a key being missing from an answer that did arrive.
+   */
+  attributes: (live, props) => ({
+    all: bool(live['all'], false),
+    comment: text(live['comment'], ''),
+    enabled: bool(live['enabled'], true),
+    exclude: guestList(live['exclude']),
+    fleecing: propertyString(live['fleecing'], 'enabled'),
+    id: props.id,
+    mode: text(live['mode'], 'snapshot'),
+    'next-run': typeof live['next-run'] === 'number' ? live['next-run'] : 0,
+    'notes-template': text(live['notes-template'], ''),
+    'notification-mode': text(live['notification-mode'], 'auto'),
+    pool: text(live['pool'], ''),
+    'prune-backups': propertyString(live['prune-backups']),
+    'repeat-missed': bool(live['repeat-missed'], false),
+    schedule: text(live['schedule'], ''),
+    storage: text(live['storage'], ''),
+    vmid: guestList(live['vmid']),
+  }),
+  collection: () => 'cluster/backup',
+  /** ⛔ `id` IS SENT AND IS NOT OPTIONAL. Everything above depends on PVE not inventing one. */
+  createForm: (props) => ({ ...shape(props), id: props.id }),
+  /** Each line reads "not declared, or equal"; the five defaulted fields have no undeclared case. */
+  matches: (attributes, props) =>
+    attributes.schedule === props.schedule &&
+    attributes.enabled === (props.enabled !== false) &&
+    attributes.all === (props.all === true) &&
+    attributes.mode === (props.mode ?? 'snapshot') &&
+    attributes['notification-mode'] === (props['notification-mode'] ?? 'auto') &&
+    attributes['repeat-missed'] === (props['repeat-missed'] === true) &&
+    (props.storage === undefined || attributes.storage === props.storage) &&
+    (props.pool === undefined || attributes.pool === props.pool) &&
+    (props.comment === undefined || attributes.comment === props.comment) &&
+    (props.vmid === undefined || attributes.vmid === guestList(props.vmid)) &&
+    (props.exclude === undefined || attributes.exclude === guestList(props.exclude)) &&
+    (props['notes-template'] === undefined ||
+      attributes['notes-template'] === props['notes-template']) &&
+    (props['prune-backups'] === undefined ||
+      attributes['prune-backups'] === propertyString(props['prune-backups'])) &&
+    (props.fleecing === undefined ||
+      attributes.fleecing === propertyString(props.fleecing, 'enabled')),
+  path: (props) => `cluster/backup/${props.id}`,
+  updateForm: shape,
+});
+
+/**
+* ⛔ Empty for the same reason as every other resource here: adoption must be explicit.
+*   `GET /cluster/backup` would hand back the job somebody made by hand, and adopting it
+*   implicitly would give Alchemy the right to DELETE a cluster's only backup schedule the
+*   first time a line left a stack file.
+ 
+ *
+* ⚠️ DELETING THE JOB DOES NOT DELETE THE BACKUPS, AND THAT CUTS BOTH WAYS. The archives
+*   stay on the storage, so this looks harmless today; it is destructive in six months,
+*   when the schedule that should have replaced them has not run since. PVE will not
+*   refuse this the way it refuses to delete a pool still holding guests — nothing depends
+*   on a backup job — so the plan line is the only warning anyone gets.
+ 
+ */
+export const ProxmoxBackupJobProvider = () =>
+  Provider.effect(ProxmoxBackupJob, Effect.succeed(ProxmoxBackupJob.Provider.of(handlers)));

package/src/proxmox/ceph-daemon-form.ts

@@ -0,0 +1,84 @@
+/**
+ * Where a Ceph daemon lives on the API, and what a declaration of one looks like as a PVE form.
+ *
+ * ★ SPLIT OUT OF ceph-daemon.ts TO KEEP BOTH FILES UNDER THE 250-LINE CAP, and the seam is a real
+ *   one rather than a convenient line number — the same seam metric-server-form.ts cuts on.
+ *   This file answers "how does a declaration address ONE daemon" — which URL, which body, and
+ *   which row of the collection's answer is it. ceph-daemon.ts answers "what does the cluster
+ *   say about that daemon, and when has it changed". Nothing here calls the API and nothing
+ *   here decides a diff; `findRow` picks a row out of an answer its caller already fetched.
+ *
+ * ⛔ THE TWO PATHS ARE DIFFERENT AND THAT IS THE WHOLE REASON THIS FILE HAS TWO OF THEM. MEASURED
+ *   on n2, 2026-09-13: there is no GET on the id path — `pvesh get /nodes/n2/ceph/mon/n2` answers
+ *   "No 'get' handler defined" — while POST and DELETE are registered ONLY there. So the read uses
+ *   `collectionPath` and the two writes use `daemonPath`, and swapping either one is a silent
+ *   501: a create that never lands, or a destroy that reports failure while the daemon runs on.
+ *
+ * ⚠️ THE `import type` BACK TO ceph-daemon.ts IS A CYCLE ON PAPER ONLY — type-only, so it is
+ *   erased before anything runs. `CephDaemonProps` stays the resource's public shape, in the file
+ *   that declares the resource.
+ *
+ * ⛔ POST AND DELETE RETURN A UPID, NOT AN OBJECT — both are `protected` task endpoints whose
+ *   schema `returns` is a bare string. REASONED, NOT MEASURED: this cluster is read-only to me, so
+ *   no create was ever run. The consequence to expect is that `reconcile` reads back immediately
+ *   after the POST, and if the worker has not yet written ceph.conf the read-back still says
+ *   absent and reconcile dies with "the write returned no error but the object is still absent".
+ *   That refusal is honest — nothing is recorded for an object that is not there — and a second
+ *   deploy converges once the task has finished, but it is a confusing FIRST-RUN failure. Watch
+ *   the task in the PVE UI before concluding the create failed.
+ *
+ */
+import type { CephDaemonProps } from './ceph-daemon.ts';
+import { flag } from './values.ts';
+
+/**
+ * PVE defaults the id to the nodename for all three kinds, and that default is resolved HERE
+ * rather than left to PVE, because the id is a PATH SEGMENT: create, delete and the row lookup in
+ * ceph-daemon.ts all need the same string, and a default resolved on the far side would leave
+ * three call sites guessing. Live on this cluster every daemon's name equals its node.
+ */
+export const daemonId = (props: CephDaemonProps) => props.name ?? props.node;
+
+/**
+ * The read path. ⚠️ `{node}` HERE IS ONLY THE NODE BEING ASKED, not a filter. MEASURED:
+ *   `GET /nodes/n2/ceph/mon` returns n2, n3 AND n4, and `GET /nodes/n3/ceph/mon` returns the same
+ *   three IN A DIFFERENT ORDER — [n4,n2,n3] from n2 against [n3,n2,n4] from n3. A caller that took
+ *   row zero, or assumed the list was this node's daemons, would be wrong on both counts.
+ */
+export const collectionPath = (props: CephDaemonProps) => `nodes/${props.node}/ceph/${props.kind}`;
+
+/** The write path: POST creates here, DELETE destroys here. Never read from — see the ⛔ above. */
+export const daemonPath = (props: CephDaemonProps) => `${collectionPath(props)}/${daemonId(props)}`;
+
+/**
+ * The create body, which is EMPTY for a mgr and nearly empty for the other two.
+ *
+ * ⚠️ THE ID IS NOT SENT, because it is already the last segment of the path being POSTed to — the
+ *   same reasoning as metric-server.ts, where a second copy of the key can only disagree with the
+ *   first. PVE's schema does accept `monid`/`id`/`name` as body parameters; the path wins, so
+ *   sending one would be a second source of truth for the object's identity and nothing else.
+ *
+ * ⚠️ AND THE BRANCHES CANNOT BE ONE SHARED BODY. `hotstandby` is an mds parameter and
+ *   `mon-address` a mon one; each POST schema lists only its own, so the wrong field is a 400
+ *   rather than an ignored hint. Both are create-only — the ⛔s on those props say why neither is
+ *   ever compared afterwards.
+ */
+export const createForm = (props: CephDaemonProps): Record<string, string> => {
+  if (props.kind === 'mon' && props['mon-address'] !== undefined) {
+    return { 'mon-address': props['mon-address'] };
+  }
+  const hotstandby = props.kind === 'mds' ? flag(props.hotstandby) : undefined;
+  return hotstandby === undefined ? {} : { hotstandby };
+};
+
+/**
+ * ⚠️ THE COLLECTION ANSWERS AN ARRAY while the factory types `attributes`' first parameter as the
+ *   `Record<string, unknown>` every other PVE read is shaped like — the same mismatch acl.ts
+ *   carries, handled the same way: narrow the rows, trust none of them, and match on `name`.
+ * ⚠️ MATCHED ON `name` ALONE, NEVER ON POSITION — the list comes back in a different order
+ *   depending on which node was asked. See the ⚠️ on `collectionPath` above.
+ */
+export const findRow = (live: unknown, props: CephDaemonProps) =>
+  (Array.isArray(live) ? live : [])
+    .filter((row): row is Record<string, unknown> => typeof row === 'object' && row !== null)
+    .find((row) => row['name'] === daemonId(props));

package/src/proxmox/ceph-daemon.ts

@@ -0,0 +1,243 @@
+/**
+ * `Proxmox.CephDaemon` — a Ceph monitor, manager or metadata server on one node.
+ *
+ * ★ ONE RESOURCE FOR THREE KINDS, AND THE SCHEMAS WERE CHECKED BEFORE THAT WAS DECIDED. Parsed
+ *   from `/usr/share/pve-docs/api-viewer/apidoc.js` on n2, 2026-09-13: mon, mgr and mds each
+ *   expose GET on the collection and POST + DELETE on the id below it, each returns
+ *   name/host/state/addr/ceph_version*, and the only divergence is the create parameter
+ *   (`mon-address` / none / `hotstandby`) and the read-only extras (mon: quorum, rank; mds: rank,
+ *   fs_name, standby_replay). Three near-identical files would have carried the traps below three
+ *   times over and let them drift — the argument resource.ts already makes for the factory itself.
+ *
+ * ⛔ THE ONLY GET IS THE COLLECTION'S, AND IT ANSWERS FOR THE WHOLE CLUSTER. MEASURED:
+ *   `GET /nodes/n2/ceph/mon` returns n2, n3 AND n4, and `GET /nodes/n3/ceph/mon` returns the same
+ *   three IN A DIFFERENT ORDER — [n4,n2,n3] from n2, [n3,n2,n4] from n3 — so a row is found by
+ *   `name` and NEVER by position, and the `{node}` in the path is only the node being ASKED.
+ *   MEASURED too: there is no GET on the id path at all; `pvesh get /nodes/n2/ceph/mon/n2` answers
+ *   "No 'get' handler defined for '/nodes/n2/ceph/mon/n2'", and mgr and mds answer the same.
+ *   That is why `path()` below is the COLLECTION, and that in turn is why `delete` is the one
+ *   handler this file writes by hand: `pveOperations.destroy` sends its DELETE to `spec.path`,
+ *   which here would be the collection — a 501 reported as a failed destroy, with the daemon still
+ *   running. Same shape and same rule as the override in acl.ts: do not "restore symmetry" by
+ *   pointing it back at `ops.destroy`.
+ *
+ * ⛔ WHAT A DESTROY ACTUALLY DOES, BECAUSE THE PLAN LINE SAYS ONLY "delete". REASONED FROM PVE'S
+ *   AND CEPH'S DOCUMENTED BEHAVIOUR, NOT MEASURED — nothing on this cluster was destroyed to find
+ *   out, and nothing should be to check. `mon`: stops ceph-mon@id, removes it from the monmap and
+ *   strips its section from ceph.conf. THREE MONS TOLERATE ONE LOSS; TWO TOLERATE NONE. Removing
+ *   two in one deploy — or removing the mon on the node whose API is serving the call — loses
+ *   quorum, and a cluster without mon quorum BLOCKS every RBD and CephFS I/O rather than erroring
+ *   it, so on this cluster every guest on `cephtb4` hangs.
+ *   `mds`: destroying a STANDBY is a non-event; destroying the ACTIVE one fails CephFS over,
+ *   and with no standby left `cephfs-tb4` goes unavailable. `mgr`: no guest I/O depends on it, but
+ *   the last one takes the PG autoscaler, the dashboard and PVE's own Ceph status with it.
+ *   Live on 2026-09-13: mon, mgr AND mds on each of n2, n3, n4.
+ *
+ * ★ AND THE ONLY WAY TO REACH THAT DESTROY IS TO DELETE THE DECLARATION. `matches` is deliberately
+ *   total (see its ⛔), so this resource CANNOT plan a `replace` — which is the one action that
+ *   would tear down a live mon off the back of an edited field rather than a removed line.
+ *
+ * ⚠️ THE PRIVILEGES ARE ASYMMETRIC AND THE READ SIDE IS THE CHEAP ONE. The GET checks `any` of
+ *   `Sys.Audit`/`Datastore.Audit` on `/`, and PVEAuditor holds both (MEASURED:
+ *   `GET /access/roles/PVEAuditor`), so the mount's `read` role can see this family — unlike
+ *   `Proxmox.Storage`, which 403s under that lease. POST and DELETE both check `Sys.Modify` on
+ *   `/`, and MEASURED on this cluster `LXCProvisioner` already holds it, so the provision lane
+ *   needs no widening for once. ⚠️ `Sys.Modify` on the ROOT path is broad — it also buys
+ *   datacenter options and every other cluster-wide config write — so it is worth knowing that
+ *   this credential already has it rather than discovering it the next time something is scoped.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { collectionPath, createForm, daemonId, daemonPath, findRow } from './ceph-daemon-form.ts';
+import { pve } from './client.ts';
+import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
+import { bool, num, text } from './values.ts';
+
+/**
+ * Which Ceph daemon this is. The discriminant picks the collection, the create parameters and
+ * which of the read-only extras below will even be populated.
+ *
+ * ⚠️ `osd` IS NOT HERE AND MUST NOT BE ADDED TO THIS UNION. `/nodes/{node}/ceph/osd` takes a disk
+ *   device, wipes it, and its DELETE has a `cleanup` flag — a create that destroys data on the way
+ *   in is a different resource with a different set of refusals, not a fourth case in this one.
+ */
+export type CephDaemonKind = 'mon' | 'mgr' | 'mds';
+
+export interface CephDaemonProps extends WithTarget {
+  kind: CephDaemonKind;
+  /**
+   * The node the daemon RUNS on. Identity — a daemon cannot be moved, only destroyed and rebuilt.
+   * ⚠️ It is also the node whose API is asked, and the read is only as available as that node: a
+   *   node that is down — or has no Ceph installed, or answers 403 — reads as nothing at all,
+   *   because `pveOperations.read` folds EVERY failure into "absent" (a 404 is a legitimate answer
+   *   there and it cannot tell the two apart). Its daemons then plan as `update`, and reconcile
+   *   POSTs a create for a mon that already exists. PVE refuses that with "monitor already
+   *   exists", and the read-back refuses again — so it fails loudly rather than damaging anything,
+   *   but the message will point at the daemon rather than at the node that would not answer.
+   */
+  node: string;
+  /**
+   * The daemon id. PVE defaults it to the nodename, and `daemonId` in ceph-daemon-form.ts resolves
+   * that default HERE rather than leaving it to PVE, because the id is a PATH SEGMENT: create,
+   * delete and the row lookup all need the same string, and a default resolved on the far side
+   * would leave three call sites guessing. Live on this cluster every daemon's name is its node.
+   */
+  name?: string;
+  /**
+   * mon only. Overrides the autodetected monitor IP; must sit in Ceph's public network — on this
+   * cluster that is 10.20.11.0/24, carried by `vmbr1.11`.
+   * ⛔ CREATE-ONLY AND NEVER COMPARED. PVE takes a bare ip-list on write and hands back `addr` as
+   *   `10.20.11.12:6789/0` — an address, a port and a nonce. The two are not the same string and
+   *   never will be, so diffing them would report a mismatch on every plan; with no PUT on this
+   *   family that mismatch becomes a REPLACE, and a replace of a mon is the quorum loss in the
+   *   header. Left out of `matches` on purpose.
+   */
+  'mon-address'?: string;
+  /**
+   * mds only. Makes this standby replay the active MDS's journal for a faster failover.
+   * ⛔ CREATE-ONLY AND NEVER COMPARED, AND THE FIELD THAT LOOKS LIKE ITS READBACK IS NOT ONE.
+   *   `standby_replay` in the list is the daemon's CURRENT state, not its configuration: MEASURED
+   *   2026-09-13, all three mds report `standby_replay: false`, n3 included — and n3 is the ACTIVE
+   *   mds, which is not a standby at all and so can never report true however it was created.
+   *   Comparing `hotstandby` to it would plan a replace against whichever mds Ceph happens to have
+   *   elected, i.e. against a value no declaration controls.
+   * ⚠️ SET ON A mon OR mgr IT IS DROPPED RATHER THAN SENT, and `mon-address` likewise on an mds:
+   *   each POST schema lists only its own parameter, so the wrong one is a 400 rather than an
+   *   ignored hint. A field silently dropped is the lesser of the two, but it IS dropped.
+   */
+  hotstandby?: boolean;
+}
+
+/**
+ * Everything the cluster says about this daemon — reported, and (bar its identity) none of it
+ * compared. Read the ⛔ on `matches` for why that is the only safe split on this family.
+ */
+export interface CephDaemonAttributes {
+  kind: CephDaemonKind;
+  node: string;
+  name: string;
+  /**
+   * The host Ceph says it runs on.
+   * ⚠️ REPORTED, NOT COMPARED, AND THAT IS A DELIBERATE BLIND SPOT. A daemon found under this name
+   *   on a DIFFERENT node than `node` declares plans as `noop`, which does hide a misdeclaration.
+   *   The alternative is worse: `host` is `optional` in the schema, so an absent one would read as
+   *   a mismatch, and with no PUT a mismatch is a replace — i.e. a missing field in one API answer
+   *   would destroy a live mon. When in doubt, out of `matches`; fix a wrong node by hand.
+   */
+  host: string;
+  /**
+   * mon `running`/`stopped`/`unknown`, mgr `active`/`standby`, mds `up:active`/`up:standby`/…
+   * ⛔ CEPH ELECTS THIS AND REWRITES IT WITHOUT ANYONE DECLARING ANYTHING. MEASURED: mgr n2 is
+   *   `active` while n3 and n4 are `standby`; mds n3 is `up:active` while n2 and n4 are
+   *   `up:standby`. Restart a daemon and the roles move. It is reported so a plan can show what is
+   *   live and kept out of `matches` so that an election is never a diff.
+   * ⚠️ IT ALSO MEANS THIS RESOURCE DOES NOT MANAGE WHETHER THE DAEMON IS RUNNING. A configured but
+   *   stopped daemon is still a row in the list, so it reads as present and plans `noop`.
+   */
+  state: string;
+  /** Ceph-formatted, e.g. `10.20.11.12:6789/0`. Reported; see `mon-address` for why never compared. */
+  addr: string;
+  /** `ceph_version_short`, e.g. `20.2.2`. Reported: a straggler after an upgrade is worth seeing. */
+  version: string;
+  /**
+   * mon rank in the monmap, mds rank in the filesystem, `-1` when the daemon has neither.
+   * ⛔ CEPH ASSIGNS IT AND NOTHING DECLARES IT. MEASURED: the mons are ranked n4=0, n3=1, n2=2 —
+   *   monmap order, not declaration order — and the mds ranks are 0 for the active n3 and -1 for
+   *   the two standbys. Rank moves when a daemon is added, removed or restarted.
+   */
+  rank: number;
+  /** mon only: in the current quorum. Reported. MEASURED: all three mons are in quorum. */
+  quorum: boolean;
+  /** mds only, and NOT the readback of `hotstandby` — see the ⛔ on that prop. */
+  standbyReplay: boolean;
+  /**
+   * mds only: the CephFS this daemon currently serves — `cephfs-tb4` here.
+   * ⛔ PRESENT ONLY ON THE ACTIVE MDS. MEASURED: n3 carries `fs_name`, n2 and n4 have no such key
+   *   at all. So it is empty for two of three identical declarations, and comparing it would
+   *   report work on exactly the daemons that are healthy standbys.
+   */
+  fsName: string;
+  /** A `ceph-<kind>@<id>` systemd unit is enabled on the host. Reported; absent reads as false. */
+  service: boolean;
+}
+
+export interface ProxmoxCephDaemon extends Resource<
+  'Proxmox.CephDaemon',
+  CephDaemonProps,
+  CephDaemonAttributes,
+  never,
+  PveRequirements
+> {}
+
+/** ★ `retain` by default — a mon carrying quorum cannot be rebuilt. See the ★ in resource.ts. */
+export const ProxmoxCephDaemon = Resource<ProxmoxCephDaemon>('Proxmox.CephDaemon', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const handlers = pveHandlers<CephDaemonProps, CephDaemonAttributes>({
+  /** ⚠️ `undefined` when no row carries this name: that is how the factory learns to create. */
+  attributes: (live, props) => {
+    const row = findRow(live, props);
+    if (row === undefined) return undefined;
+    return {
+      addr: text(row['addr']),
+      fsName: text(row['fs_name']),
+      host: text(row['host']),
+      kind: props.kind,
+      name: daemonId(props),
+      node: props.node,
+      quorum: bool(row['quorum']),
+      rank: num(row['rank'], -1),
+      service: bool(row['service']),
+      standbyReplay: bool(row['standby_replay']),
+      state: text(row['state']),
+      version: text(row['ceph_version_short']),
+    };
+  },
+  /** ⛔ The ID path, not the collection — POST is registered on `{id}`, exactly like a metric server. */
+  collection: daemonPath,
+  createForm,
+  /**
+   * ⛔ TOTAL, AND THIS IS THE REASON THE FILE EXISTS RATHER THAN A SHORTCUT PAST WRITING IT. Every
+   *   field a declaration can carry is CREATE-ONLY and unreadable — `mon-address` comes back as a
+   *   different kind of string, `hotstandby` comes back as a state Ceph elects — and every field
+   *   the read returns is assigned by Ceph: state, rank, quorum, fs_name, standby_replay, addr,
+   *   version. Nothing is left that is both declared and readable. So the honest comparison is
+   *   "does a daemon of this kind and name exist", which `attributes` has already answered by
+   *   returning a value at all, and anything further would be a diff no write could ever satisfy.
+   *   ⛔ AND ON THIS FAMILY THAT DIFF IS NOT MERELY NOISY. There is no PUT, so resource.ts answers
+   *     `replace` rather than `update` whenever `matches` is false — and replace on a mon is
+   *     delete-then-create against a live quorum. A forever-diff here is a forever-OUTAGE-RISK.
+   *   ⚠️ THE PRICE, STATED PLAINLY: editing `hotstandby` or `mon-address` on a declared daemon
+   *     plans as `noop` and never applies. Same bargain storage.ts strikes for a changed `type`.
+   *     Change one by removing the declaration and re-adding it, ONE DAEMON AT A TIME, reading the
+   *     ⛔ on destroy in the header first.
+   */
+  matches: () => true,
+  /** ⛔ The COLLECTION, because there is no GET on the id path. See the second ⛔ in the header. */
+  path: collectionPath,
+  /** ⚠️ No `updateForm`: none of the three has a PUT, so nothing about a daemon is editable. */
+});
+
+export const ProxmoxCephDaemonProvider = () =>
+  Provider.effect(
+    ProxmoxCephDaemon,
+    Effect.succeed(
+      ProxmoxCephDaemon.Provider.of({
+        ...handlers,
+        /**
+         * ⛔ THE ONE HANDLER NOT TAKEN FROM THE FACTORY, AND THE ONLY REASON IS THE PATH SPLIT.
+         *   `ops.destroy` DELETEs `spec.path`, which this resource must point at the collection so
+         *   that `read` works at all; DELETE on the collection is not implemented and would answer
+         *   501 while the daemon kept running — a failed destroy that reads like a permissions
+         *   problem. Everything else here is the factory's.
+         * ⚠️ AND IT IS THE DANGEROUS ONE. Re-read the destroy ⛔ in the header before letting a
+         *   plan that removes a mon run: two gone at once is a cluster with no quorum and every
+         *   guest on `cephtb4` blocked on I/O.
+         */
+        delete: ({ olds }: { olds: CephDaemonProps }) =>
+          pve(olds.target, 'provision', 'DELETE', daemonPath(olds)),
+      }),
+    ),
+  );