@homeflare/alchemy 0.1.0

package/dist/proxmox/ceph-daemon-form.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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';
+/**
+ * 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 declare const daemonId: (props: CephDaemonProps) => string;
+/**
+ * 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 declare const collectionPath: (props: CephDaemonProps) => string;
+/** The write path: POST creates here, DELETE destroys here. Never read from — see the ⛔ above. */
+export declare const daemonPath: (props: CephDaemonProps) => string;
+/**
+ * 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 declare const createForm: (props: CephDaemonProps) => Record<string, string>;
+/**
+ * ⚠️ 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 declare const findRow: (live: unknown, props: CephDaemonProps) => Record<string, unknown> | undefined;
+//# sourceMappingURL=ceph-daemon-form.d.ts.map

package/dist/proxmox/ceph-daemon-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ceph-daemon-form.d.ts","sourceRoot":"","sources":["../../src/proxmox/ceph-daemon-form.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGxD;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,UAAW,eAAe,WAA6B,CAAC;AAE7E;;;;;GAKG;AACH,eAAO,MAAM,cAAc,UAAW,eAAe,WAA6C,CAAC;AAEnG,kGAAkG;AAClG,eAAO,MAAM,UAAU,UAAW,eAAe,WAAkD,CAAC;AAEpG;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,UAAW,eAAe,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAMxE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,SAAU,OAAO,SAAS,eAAe,wCAGV,CAAC"}

package/dist/proxmox/ceph-daemon.d.ts

@@ -0,0 +1,162 @@
+/**
+ * `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 { type PveRequirements, type WithTarget } from './resource.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 declare const ProxmoxCephDaemon: import("alchemy").ResourceClass<ProxmoxCephDaemon>;
+export declare const ProxmoxCephDaemonProvider: () => import("effect/Layer").Layer<Provider.Provider<ProxmoxCephDaemon>, never, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=ceph-daemon.d.ts.map

package/dist/proxmox/ceph-daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ceph-daemon.d.ts","sourceRoot":"","sources":["../../src/proxmox/ceph-daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAI7C,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAe,MAAM,eAAe,CAAC;AAGnF;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAEnD,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,IAAI,EAAE,cAAc,CAAC;IACrB;;;;;;;;;OASG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,qGAAqG;IACrG,IAAI,EAAE,MAAM,CAAC;IACb,mGAAmG;IACnG,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,MAAM,EAAE,OAAO,CAAC;IAChB,+EAA+E;IAC/E,aAAa,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,iGAAiG;IACjG,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,iBAAkB,SAAQ,QAAQ,CACjD,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACpB,KAAK,EACL,eAAe,CAChB;CAAG;AAEJ,iGAAiG;AACjG,eAAO,MAAM,iBAAiB,oDAE5B,CAAC;AA+CH,eAAO,MAAM,yBAAyB,uIAoBnC,CAAC"}

package/dist/proxmox/ceph-flag.d.ts

@@ -0,0 +1,131 @@
+/**
+ * `Proxmox.CephFlag` — one cluster-wide Ceph OSD flag, declared: `noout`, `pause`, `norebalance`.
+ *
+ * ★ ONE RESOURCE PER FLAG, NOT ONE CARRYING ALL ELEVEN, AND THE CLUSTER'S OWN API DECIDED IT.
+ *   MEASURED on TB4 2026-09-13 (pve-manager 9.2.11, ceph tentacle 20.2.2) by reading
+ *   `/usr/share/perl5/PVE/API2/Cluster/Ceph.pm` and the published schema in
+ *   `/usr/share/pve-docs/api-viewer/apidoc.js`:
+ *     · `PUT /cluster/ceph/flags` ends in `fork_worker('cephsetflags', ...)` and returns a STRING
+ *       — a UPID. The bulk write is ASYNCHRONOUS, and this package has no task-polling machinery.
+ *     · `PUT /cluster/ceph/flags/{flag}` calls `$rados->mon_command` inline and returns null. The
+ *       per-flag write is SYNCHRONOUS.
+ *   `pveOperations.reconcile` READS BACK after every write and refuses to record a value it did
+ *   not see. Against the bulk endpoint that read-back races a worker which has not run yet, so it
+ *   would record the OLD value as the new attributes — the one honesty mechanism in this package
+ *   turned into a lie generator. Per-flag, the read-back means what it says.
+ *   ★ THE SECOND REASON IS SMALLER AND STILL REAL. The bulk GET answers rows of
+ *     `{name, description, value}`, and `description` is PVE's own English prose that no write
+ *     accepts: compare it and you have a forever-update, report it and this provider is pretending
+ *     to manage prose. `GET /cluster/ceph/flags/{flag}` answers a BARE BOOLEAN, so that trap
+ *     cannot be written here at all. The brief's plural `Proxmox.CephFlags` became singular for
+ *     those two reasons; the bulk endpoint is read by nothing in this package.
+ *
+ * ⛔ THESE ARE NOT CONFIGURATION. THEY ARE A HAND ON THE BRAKE, AND A DECLARATION CAN PULL IT OFF.
+ *   `noout` is what a person sets before pulling a disk. A stack saying `value: false` reasserts
+ *   that off on EVERY deploy — including a deploy somebody else runs, for an unrelated resource,
+ *   twenty minutes into a maintenance window — and the plan line reads `Proxmox.CephFlag noout
+ *   update`, which nobody reads as "ceph is about to start rebalancing 128 PGs across three nodes
+ *   while a disk is out of the chassis".
+ *   ★ SO `value` IS REQUIRED AND HAS NO DEFAULT, AND THAT IS THE MITIGATION. An optional `value`
+ *     defaulting to false would make `CephFlag('noout', { flag: 'noout', target })` mean "clear
+ *     it" — the dangerous direction, chosen by OMISSION. Here the dangerous sentence has to be
+ *     typed out by a person. Do not add a default, and do not declare a flag merely to document
+ *     that it is off: MEASURED 2026-09-13, all eleven flags on TB4 read 0, so eleven
+ *     `value: false` lines would plan green forever and do nothing except take the brake off
+ *     whenever somebody happens to apply them.
+ *
+ * ⛔ `delete` DOES NOTHING, ON PURPOSE, AND THE ASYMMETRY OF THE TWO FAILURES IS THE ARGUMENT.
+ *   `flags/{flag}` has exactly two methods, GET and PUT, so the factory's `destroy` would answer
+ *   "Method 'DELETE /cluster/ceph/flags/noout' not implemented" on every teardown — whatever this
+ *   handler does is INVENTED. The obvious invention, "clear the flag", is refused: removing a line
+ *   from a stack file, or Alchemy collecting an old generation after a replace, would silently
+ *   take the brake off and nothing would warn. Leaving a flag set that nothing declares any more
+ *   is the opposite kind of failure — ceph reports `HEALTH_WARN ... flag(s) set` for every one of
+ *   these, on `ceph -s`, in the PVE UI and in the `pve_*` metrics this estate already scrapes.
+ *   A silent destructive failure loses to a loud inert one.
+ *   ⚠️ THE RESIDUAL RISK, NAMED RATHER THAN DENIED: deleting a `value: true` declaration LEAVES
+ *     THE FLAG SET. Retire a maintenance window by flipping the line to `value: false` and
+ *     deploying BEFORE the line is removed, or a `noout` outlives the window that needed it.
+ *   ⚠️ REASONED, NOT MEASURED: that health warning was not observed, because observing it means
+ *     setting a flag on a live cluster and this file was researched read-only. Undeclaring stops
+ *     MANAGING a flag; to clear one, declare `value: false` and deploy, where a plan says so.
+ *
+ * ⛔ `pause` IS TWO CEPH FLAGS AND THIS RESOURCE READS ONLY ONE OF THEM. MEASURED in
+ *   `PVE::Ceph::Tools::get_real_flag_name`, whose own comment reads "the 'pause' flag gets always
+ *   set to both 'pauserd' and 'pausewr'": PVE writes both and then decides the flag is set by
+ *   looking at `pauserd` alone. A cluster where somebody ran `ceph osd unset pauserd` by hand
+ *   still has `pausewr` — writes blocked, guests hung — and this resource reports `value: false`
+ *   and plans `noop` straight past it. It cannot express a half-pause, so never use it to prove
+ *   one is gone; `ceph osd dump | head -1` can.
+ *   ⛔ `pause` AND `noup` ARE ALSO THE TWO THAT TAKE THE CLUSTER DOWN FROM A TYPO. `pause: true`
+ *     stops all reads and writes, so every guest on `cephtb4` — the cluster's only rbd pool,
+ *     MEASURED 2026-09-13 — freezes on its root disk, and so does `cephfs-tb4`. `noup: true`
+ *     stops a rebooted OSD from ever rejoining. Neither is undone by deleting the line.
+ *
+ * ⚠️ PRIVILEGES, AND THE WRITE ONE IS A BIG ASK. Both GETs check `Sys.Audit` on `/`; both PUTs
+ *   check `Sys.Modify` on `/`, and all four carry `allowtoken => 1`, so an API token may make the
+ *   call at all. There is no `/ceph` ACL object to scope to — the check names the ROOT path
+ *   literally — so granting the provision role `Sys.Modify` here also buys datacenter options,
+ *   metric servers, notification targets and every other cluster-wide write, exactly as
+ *   metric-server.ts warns about its own family.
+ *   ⚠️ REASONED, NOT MEASURED: nothing here was exercised under a minted lease, because a mint
+ *     writes an API token into the cluster and the brief for this file was reads only. Expect
+ *     "Permission check failed (/, Sys.Modify)" on the first deploy, and widen deliberately.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import { type PveRequirements, type WithTarget } from './resource.ts';
+/**
+ * PVE's eleven flags, spelled as `PVE::Ceph::Tools::get_possible_osd_flags` spells them.
+ *
+ * ⚠️ THE ENUM IS CLOSED AND A TYPO IS A 400, WHICH IS WHY THIS IS A UNION AND NOT `string`. Both
+ *   the GET and the PUT declare `additionalProperties => 0` over exactly this list.
+ * ⚠️ CEPH HAS FLAGS PVE DOES NOT MODEL, and four of them are always on. MEASURED on TB4:
+ *   `ceph osd dump` reports `flags sortbitwise,recovery_deletes,purged_snapdirs,pglog_hardlimit`.
+ *   PVE reads that same string and answers only about its own eleven, so the others can neither
+ *   leak in here nor be set from here — `noautoscale` and `nosnaptrim` included.
+ *   ⛔ IF SOMEBODY LATER "IMPROVES" THE READ BY PARSING `osd dump` DIRECTLY, those four become
+ *     permanently-set flags that nothing declares: a forever-diff on a brand new cluster.
+ */
+export type CephFlagName = 'nobackfill' | 'nodeep-scrub' | 'nodown' | 'noin' | 'noout' | 'norebalance' | 'norecover' | 'noscrub' | 'notieragent' | 'noup' | 'pause';
+export interface CephFlagProps extends WithTarget {
+    /**
+     * Which flag. PVE's primary key here, and the last segment of the path.
+     *
+     * ⚠️ EDITING IT IN PLACE ORPHANS THE OLD FLAG RATHER THAN MOVING ANYTHING. `diff` reads the NEW
+     *   path and reconcile writes it, while the old flag keeps whatever this stack last put there.
+     *   There is deliberately no replace override for it — acl.ts needs one because its `delete`
+     *   removes a real grant, and `delete` here is inert by design, so a replace would do exactly
+     *   what an update already does. Declare a second resource and set the old one to `value: false`
+     *   rather than renaming this one.
+     * ⛔ TWO RESOURCES DECLARING THE SAME FLAG ARE ONE CLUSTER OBJECT, and Alchemy sees two ids
+     *   rather than a collision — the acl.ts hazard exactly. Disagreeing, they take turns winning
+     *   and BOTH plan `update` for ever; agreeing, deleting either leaves the flag where the other
+     *   put it. One declaration per flag per cluster.
+     */
+    flag: CephFlagName;
+    /**
+     * Set the flag (`true`) or clear it (`false`).
+     *
+     * ⛔ REQUIRED, WITH NO DEFAULT — see the second ⛔ in the header, which is the whole safety
+     *   argument for this family. It is also the only field PVE accepts on this endpoint, and it is
+     *   not optional in the schema either: omitting it from the form is a 400, not an untouched
+     *   flag. (The BULK endpoint is the one where omission means "leave it alone"; this is not it.)
+     */
+    value: boolean;
+}
+export interface CephFlagAttributes {
+    /**
+     * ⚠️ REPORTED, NEVER COMPARED. It is the path key the read was made WITH, copied back out of
+     *   props, so comparing it against props would be true by construction — the same reasoning
+     *   acl.ts gives for the four identity fields it also declines to diff.
+     */
+    flag: CephFlagName;
+    /** Whether ceph has the flag set right now. The only field `matches` looks at. */
+    value: boolean;
+}
+export interface ProxmoxCephFlag extends Resource<'Proxmox.CephFlag', CephFlagProps, CephFlagAttributes, never, PveRequirements> {
+}
+export declare const ProxmoxCephFlag: import("alchemy").ResourceClass<ProxmoxCephFlag>;
+export declare const ProxmoxCephFlagProvider: () => import("effect/Layer").Layer<Provider.Provider<ProxmoxCephFlag>, never, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=ceph-flag.d.ts.map

package/dist/proxmox/ceph-flag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ceph-flag.d.ts","sourceRoot":"","sources":["../../src/proxmox/ceph-flag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAe,MAAM,eAAe,CAAC;AAGnF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GACpB,YAAY,GACZ,cAAc,GACd,QAAQ,GACR,MAAM,GACN,OAAO,GACP,aAAa,GACb,WAAW,GACX,SAAS,GACT,aAAa,GACb,MAAM,GACN,OAAO,CAAC;AAEZ,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C;;;;;;;;;;;;;OAaG;IACH,IAAI,EAAE,YAAY,CAAC;IACnB;;;;;;;OAOG;IACH,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,IAAI,EAAE,YAAY,CAAC;IACnB,kFAAkF;IAClF,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,eAAgB,SAAQ,QAAQ,CAC/C,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,KAAK,EACL,eAAe,CAChB;CAAG;AAEJ,eAAO,MAAM,eAAe,kDAAgD,CAAC;AAqD7E,eAAO,MAAM,uBAAuB,qIA4CjC,CAAC"}

package/dist/proxmox/ceph-fs-wire.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The wire lane of `Proxmox.CephFs`: how a PVE answer becomes attributes, how a declaration becomes
+ * a PVE call, and how that call becomes a fact.
+ *
+ * ★ SPLIT OUT OF ceph-fs.ts TO KEEP BOTH FILES UNDER THE 250-LINE CAP, and the seam is a real one
+ *   rather than a convenient line number. ceph-fs.ts answers "what is a CephFS, and when has it
+ *   changed"; this file answers "what does PVE say, what does it want, and has it finished". On
+ *   this family that is where all the strangeness lives — the read is an index and not an object,
+ *   the paths are inverted, the delete takes its arguments in the query string, and both writes
+ *   fork a worker — so keeping it in one place is what stops the next reader assuming the ordinary
+ *   shape from the other nineteen resources. ⚠️ NOTHING HERE DECIDES A DIFF.
+ *
+ * ⚠️ THE `import type` BACK TO ceph-fs.ts IS A CYCLE ON PAPER ONLY. It is type-only and erased
+ *   before anything runs, exactly as metric-server-form.ts imports `MetricServerProps`. The props
+ *   stay the resource's public shape, declared in the file that declares the resource.
+ *
+ * ⛔ POST AND DELETE ANSWER WITH A UPID, NOT A RESULT — THE WRITE IS ASYNCHRONOUS AND A FAILED ONE
+ *   IS STILL HTTP 200. Read from the cluster's own source, /usr/share/perl5/PVE/API2/Ceph/FS.pm on
+ *   n2: `createfs` and `destroyfs` both end `return $rpcenv->fork_worker(...)`. Two different lies
+ *   come out of trusting that status code. A read-back straight after the POST reports "still
+ *   absent" about a filesystem that is being built as it says so — which is precisely the message
+ *   `pveOperations.reconcile` would print, pointing at the wrong cause. And a worker that dies
+ *   INSIDE — the pool create, or the add-storage step, both of which are wrapped in `eval` — is
+ *   never reported to the caller at all. `settle` below is the answer to both.
+ *   ⚠️ REASONED FROM THAT SOURCE, NOT MEASURED. Nothing was written to this cluster, so the race
+ *     has not been observed; only the `fork_worker` that guarantees it is there.
+ *
+ * ⛔ A DELETE BODY IS SILENTLY DISCARDED BY PVE, SO `remove-pools` GOES IN THE QUERY STRING.
+ *   MEASURED in /usr/share/perl5/PVE/APIServer/AnyEvent.pm on n2: line 928 reads the request
+ *   content into params only `if ($method eq 'PUT' || $method eq 'POST')`, and line 1653 sends
+ *   every other method down a branch that parses `$request->url->query()` and nothing else. So
+ *   `pve(target, role, 'DELETE', path, form)` would send a body PVE never looks at: the flags would
+ *   read as unset, the pools would quietly survive a delete that asked for them, and no error would
+ *   be raised anywhere. sdn-apply.ts already puts `?pending=1` in the path for the same reason.
+ *
+ * ⚠️ THE TASK POLL RUNS ON THE `read` ROLE THOUGH IT SITS INSIDE reconcile, FOR TWO REASONS. It is
+ *   a read, and resource.ts already mints `read` for its own read-back inside reconcile. And the
+ *   leases differ where it matters: `provision` is 300s and explicitly non-renewable, so a create
+ *   that waits out a slow worker on that lease can expire mid-poll, while `read` is 3600s.
+ *
+ * ⛔ THE POLLER IS NEVER THE TASK'S OWNER, WHICH COSTS A PRIVILEGE, AND THIS ONE IS MEASURED
+ *   RATHER THAN FEARED. client.ts mints a fresh credential per call and the mount vends a NEW
+ *   token id each time, so the token reading the status is never the token recorded in the UPID —
+ *   and PVE compares them exactly. /usr/share/perl5/PVE/API2/Tasks.pm on n2, `$check_task_user`:
+ *   `return $user eq $fulltoken || $user eq $task->{user};`, above it the comment "token only sees
+ *   token tasks, user sees user + token tasks". Token B of the same user matches neither branch.
+ *   So the fallback is the schema's other clause for `GET /nodes/{node}/tasks/{upid}/status`: "The
+ *   user needs 'Sys.Audit' permissions on '/nodes/<node>' if they are not the owner of the task."
+ *   Grant it on the `read` role, or every create burns the full cap below and reports the wrong
+ *   cause.
+ */
+import * as Effect from 'effect/Effect';
+import type { CephFsAttributes, CephFsProps } from './ceph-fs.ts';
+/**
+ * This filesystem's row of the index, as attributes.
+ *
+ * ⚠️ `GET /nodes/{node}/ceph/fs` ANSWERS AN ARRAY, while the factory hands `attributes` the
+ *   `Record<string, unknown>` every other PVE read is shaped like. Rows are narrowed rather than
+ *   trusted, the same way acl.ts narrows its one flat grant list.
+ *
+ * ⛔ RETURNING undefined IS WHAT MAKES "ABSENT" MEAN ABSENT HERE, unlike acl.ts where the object is
+ *   always present-but-unbound. A filesystem missing from the index has not been created, and
+ *   `reconcile` takes the create branch on exactly that signal.
+ */
+export declare const readRow: (live: Record<string, unknown>, props: CephFsProps) => CephFsAttributes | undefined;
+/** ⚠️ `nodes/{n}/ceph/fs/{name}` — the POST and DELETE target, and NOT where a read goes. */
+export declare const objectPath: (props: CephFsProps) => string;
+/**
+ * ⚠️ `name` IS DELIBERATELY ABSENT FROM THE FORM. It is already the last segment of the path being
+ *   POSTed to — the metric-server.ts case again — and a second copy can only ever disagree with it.
+ */
+export declare const createForm: (props: CephFsProps) => Record<string, string>;
+/**
+ * POST the create, then wait for the worker. ⛔ The caller still reads back; see ceph-fs.ts.
+ *
+ * ⚠️ A CREATE NEEDS A RUNNING *AND* A STANDBY MDS, and refuses BEFORE it forks -- "no running
+ *   Metadata Server (MDS) found!" / "no standby Metadata Server (MDS) found!" are synchronous, so
+ *   they surface as a failed POST rather than as a silent worker. TB4 has three (MEASURED: n3
+ *   `up:active` for cephfs-tb4, n2 and n4 `up:standby`), so this is a note for a smaller cluster.
+ * ⚠️ BOTH WRITES CHECK `Sys.Modify` ON `/` -- the root, with the breadth metric-server.ts warns
+ *   about: granting it buys datacenter options and every other cluster-wide config write too.
+ */
+export declare const createFs: (props: CephFsProps) => Effect.Effect<undefined, Error, import("effect/unstable/http/HttpClient").HttpClient>;
+/**
+ * DELETE the filesystem, then wait for the worker.
+ *
+ * ⛔ WHAT THIS TAKES AWAY DEPENDS ENTIRELY ON `remove-pools`, AND THE DEFAULT IS THE SAFE ONE. With
+ *   it unset PVE removes the filesystem from the MDS map and LEAVES the two pools on disk: every
+ *   mount breaks, but the bytes are still there for an operator to recover. With it set the pools
+ *   go too and nothing is recoverable. Leaving it unset also means a later create of the SAME name
+ *   fails with "ceph pools '<name>_data' and/or '<name>_metadata' already exist" -- that refusal is
+ *   a BRAKE, not a bug, and it is the last thing standing between a mis-typed rename and the data.
+ */
+export declare const destroyFs: (props: CephFsProps) => Effect.Effect<void, Error, import("effect/unstable/http/HttpClient").HttpClient>;
+/**
+ * The two read-back failures, as messages rather than as guesses.
+ *
+ * ⛔ WAITING PROVES THE TASK ENDED; ONLY A READ PROVES THE FILESYSTEM DID OR DID NOT. `createfs`
+ *   wraps its pool creates in an `eval` and CLEANS THEM UP on error before dying, so a worker can
+ *   plausibly end having built and then removed everything it made. `destroyfs` refuses outright
+ *   while a non-disabled `cephfs` storage still references the filesystem. Neither outcome is
+ *   visible in a status code, which is why ceph-fs.ts reads back after both and dies with these.
+ */
+export declare const notCreated: (props: CephFsProps) => Error;
+export declare const notDestroyed: (props: CephFsProps) => Error;
+//# sourceMappingURL=ceph-fs-wire.d.ts.map

package/dist/proxmox/ceph-fs-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ceph-fs-wire.d.ts","sourceRoot":"","sources":["../../src/proxmox/ceph-fs-wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAKlE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO,SACZ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SACtB,WAAW,KACjB,gBAAgB,GAAG,SAkBrB,CAAC;AAaF,6FAA6F;AAC7F,eAAO,MAAM,UAAU,UAAW,WAAW,WAAgD,CAAC;AAM9F;;;GAGG;AACH,eAAO,MAAM,UAAU,UAAW,WAAW,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAGnE,CAAC;AA2DH;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,UAAW,WAAW,0FAiBvC,CAAC;AAEL;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,UAAW,WAAW,qFAQxC,CAAC;AAEL;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,UAAW,WAAW,UAK1C,CAAC;AAEJ,eAAO,MAAM,YAAY,UAAW,WAAW,UAK5C,CAAC"}

package/dist/proxmox/ceph-fs.d.ts

@@ -0,0 +1,124 @@
+/**
+ * `Proxmox.CephFs` — a CephFS on the cluster's own Ceph. The filesystem a `cephfs` storage mounts.
+ *
+ * ⛔ A REPLACE OF THIS RESOURCE DESTROYS A LIVE FILESYSTEM, AND THERE IS NO PUT TO SAVE YOU FROM
+ *   IT. MEASURED from the published schema on n2, 2026-09-13: `/nodes/{node}/ceph/fs/{name}` has
+ *   exactly two methods, POST and DELETE. A CephFS cannot be edited in place, so `updateForm` is
+ *   left undefined and anything the factory can see as changed becomes a REPLACE — and Alchemy's
+ *   replace is create-then-delete, where the delete is `destroyfs`: the entry leaves the MDS map,
+ *   every mount on every node breaks, and whether the bytes survive rests on `remove-pools` alone.
+ *   ★ WHICH IS THE WHOLE REASON `matches` COMPARES NOTHING. Read its ⛔ before adding a field to
+ *     it. On every other resource in this package a forever-diff is an annoying plan line; on this
+ *     one it is a live filesystem destroyed on every deploy, forever, because a background daemon
+ *     moved a number nobody declared.
+ *
+ * ⛔ THERE IS NO SINGLE-OBJECT READ, WHICH INVERTS `path` AND `collection`. MEASURED on n2:
+ *     pvesh get /nodes/n2/ceph/fs/cephfs-tb4
+ *       -> No 'get' handler defined for '/nodes/n2/ceph/fs/cephfs-tb4'
+ *   `GET /nodes/{node}/ceph/fs` is a directory index and is the only read there is, so `path()`
+ *   below returns the INDEX and `attributes` picks this filesystem out of the array client-side —
+ *   the shape acl.ts uses for the one flat `GET /access/acl`. The POST goes to the `{name}` path,
+ *   so `collection()` is the LONGER of the two strings, the mirror of metric-server.ts.
+ *   ⚠️ AND THAT IS WHY `delete` AND `reconcile` ARE HAND-WRITTEN BELOW rather than taken from
+ *     `pveHandlers`. `pveOperations.destroy` deletes `spec.path`, which here is the index:
+ *     `DELETE /nodes/{node}/ceph/fs` is not a route, so a factory delete would fail every destroy
+ *     while the filesystem stayed exactly where it was. `reconcile` is hand-written for a second,
+ *     independent reason — the forked worker — set out in ceph-fs-wire.ts. acl.ts is the
+ *     precedent for a family that genuinely does not fit; this is the second.
+ *
+ * ⛔ CREATING A CephFS CREATES TWO CEPH POOLS, AND A `Proxmox.CephPool` MUST NOT ALSO DECLARE THEM.
+ *   `createfs` builds `<name>_data` and `<name>_metadata` itself and refuses outright if either
+ *   exists ("ceph pools '…_data' and/or '…_metadata' already exist"). MEASURED on TB4: the live
+ *   `cephfs-tb4` owns `cephfs-tb4_data` (id 6) and `cephfs-tb4_metadata` (id 7), both of which
+ *   `GET /nodes/n2/ceph/pool` lists like any other pool — and `/nodes/{node}/ceph/pool/{name}` DOES
+ *   have GET, PUT and DELETE, so a pool resource would be a clean `pveHandlers` fit and would
+ *   adopt them without noticing. Declaring both is double management of one object: whichever
+ *   reconciles first wins, and the loser either fails its create or PUTs `size`/`pg_num` onto pools
+ *   this resource believes it owns. Declare the filesystem here and leave its two pools alone.
+ *
+ * ⚠️ `add-storage` IS A SECOND SIDE EFFECT AND IT LANDS IN storage.cfg. Set, `createfs` also calls
+ *   `PVE::API2::Storage::Config->create` with type `cephfs`, content `backup,iso,vztmpl` and
+ *   `fs-name <name>`. MEASURED: /etc/pve/storage.cfg on n2 holds exactly that — `cephfs:
+ *   cephfs-tb4` / `content backup,vztmpl,iso` / `fs-name cephfs-tb4`. So a `Proxmox.Storage`
+ *   declaring `cephfs-tb4` would be managing an entry this resource created. Declare ONE of them:
+ *   either `add-storage` here and no storage resource, or `add-storage` off and a
+ *   `Proxmox.Storage` that reads this resource's `name` attribute — which also gets the ordering
+ *   right for free, because Alchemy orders by data flow.
+ *
+ * ⚠️ `node` IS A ROUTE, NOT IDENTITY, AND MUST NEVER BE DIFFED. A CephFS is cluster-wide; the node
+ *   in the path only says which node PVE proxies the call to. MEASURED: `GET /nodes/n2/ceph/fs`,
+ *   `…/n3/…` and `…/n4/…` returned the byte-identical array. So changing `node` plans `noop`, and
+ *   two resources naming the same `name` on different nodes are the SAME filesystem — the vmid
+ *   hazard from lxc.ts, with a filesystem on the end of it instead of a container.
+ *
+ * ⚠️ PRIVILEGES: the read lane needs `Sys.Audit` OR `Datastore.Audit` on `/`, which an auditor
+ *   role already holds — unlike storage.ts, nothing needs widening before the first plan. The
+ *   write side is in ceph-fs-wire.ts beside the calls, and in docs/privileges.md with the rest.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import { type PveRequirements, type WithTarget } from './resource.ts';
+export interface CephFsProps extends WithTarget {
+    /** ⚠️ Which node answers the call, NOT which node holds the filesystem. See the header. */
+    node: string;
+    /**
+     * The filesystem name, and the cluster-wide primary key. PVE's pattern is `^[^:/\s]+$`.
+     * ⛔ CHANGING IT IS A REPLACE, WHICH DESTROYS THE OLD FILESYSTEM. `diff` says so explicitly
+     *   below rather than letting the factory report a create-shaped `update` and orphan the old one.
+     */
+    name: string;
+    /**
+     * Placement groups for the backing data pool; the metadata pool gets a quarter of it, or 8 when
+     * this is under 32. PVE's default is 128.
+     *
+     * ⛔ CREATE-TIME ONLY, UNREADABLE, AND OWNED BY THE AUTOSCALER FROM THE SECOND IT LANDS. It is
+     *   never compared — see the ⛔ on `matches` — and this is not caution, it is measured. TB4's
+     *   `cephfs-tb4` was created with the default 128 (the arithmetic proves it: `cephfs-tb4_metadata`
+     *   sits at 32, which is 128/4), and `cephfs-tb4_data` reads pg_num 32 TODAY. The autoscaler moved
+     *   it by a factor of four, and it is not finished: `pg_autoscale_mode` is `on` for every pool on
+     *   this cluster and `cephfs-tb4_metadata` already reports `pg_num_final: 16` against its live 32.
+     */
+    pg_num?: number;
+    /**
+     * Also write a `cephfs` storage entry for this filesystem. ⚠️ Create-time only and never read
+     *   back — it is an ACTION, not a field. See the header for what it does to `Proxmox.Storage`.
+     */
+    'add-storage'?: boolean;
+    /** ⛔ DELETE-TIME ONLY, AND IT ERASES THE DATA. Read the ⛔ on `destroyFs` before setting it. */
+    'remove-pools'?: boolean;
+    /**
+     * Delete the pveceph-managed storage entries too. ⚠️ PVE refuses unless they are already
+     *   disabled ("storage '…' is not disabled, make sure to disable and unmount the storage first"),
+     *   so this fails the destroy rather than unmounting anything out from under a running guest.
+     */
+    'remove-storages'?: boolean;
+}
+/**
+ * ⚠️ EVERY FIELD HERE IS REPORTED AND NONE IS COMPARED. They exist so a plan, and the state entry
+ *   behind it, can say what the declaration actually points at — which pools hold the bytes.
+ */
+export interface CephFsAttributes {
+    name: string;
+    /** The first data pool. PVE keeps it for compatibility; `data_pools` is the real answer. */
+    data_pool: string;
+    /**
+     * ⚠️ SORTED, AND IT IS A SET RATHER THAN A LIST. A CephFS can hold several data pools — added
+     *   with `ceph fs add_data_pool`, which this resource has no way to express — and PVE reports
+     *   them in the MDS map's own order. Sorting is what keeps this attribute stable across reads.
+     */
+    data_pools: string;
+    metadata_pool: string;
+    /**
+     * ⚠️ AN INTEGER THAT NAMES SOMETHING WRITTEN AS A NAME, AND THEREFORE A CLASSIC FOREVER-DIFF IF
+     *   IT EVER REACHED `matches`. PVE answers `metadata_pool_id: 7` while every write in this family
+     *   spells a pool by name. It is here to be read, never to be compared. `-1` means absent: the
+     *   field is optional in the schema and older PVE omits it.
+     */
+    metadata_pool_id: number;
+}
+export interface ProxmoxCephFs extends Resource<'Proxmox.CephFs', CephFsProps, CephFsAttributes, never, PveRequirements> {
+}
+/** ★ `retain` by default — a filesystem holding data cannot be rebuilt. See the ★ in resource.ts. */
+export declare const ProxmoxCephFs: import("alchemy").ResourceClass<ProxmoxCephFs>;
+export declare const ProxmoxCephFsProvider: () => import("effect/Layer").Layer<Provider.Provider<ProxmoxCephFs>, never, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=ceph-fs.d.ts.map

package/dist/proxmox/ceph-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ceph-fs.d.ts","sourceRoot":"","sources":["../../src/proxmox/ceph-fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAW7C,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAiB,MAAM,eAAe,CAAC;AAErF,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,2FAA2F;IAC3F,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+FAA+F;IAC/F,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,4FAA4F;IAC5F,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,QAAQ,CAC7C,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,KAAK,EACL,eAAe,CAChB;CAAG;AAEJ,qGAAqG;AACrG,eAAO,MAAM,aAAa,gDAExB,CAAC;AA4BH,eAAO,MAAM,qBAAqB,mIA6E/B,CAAC"}