@homeflare/alchemy 0.1.0

package/src/proxmox/ceph-fs.ts

@@ -0,0 +1,249 @@
+/**
+ * `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 { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import {
+  createForm,
+  createFs,
+  destroyFs,
+  notCreated,
+  notDestroyed,
+  objectPath,
+  readRow,
+} from './ceph-fs-wire.ts';
+import { type PveRequirements, type WithTarget, pveOperations } 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 const ProxmoxCephFs = Resource<ProxmoxCephFs>('Proxmox.CephFs', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const ops = pveOperations<CephFsProps, CephFsAttributes>({
+  attributes: readRow,
+  /** ⚠️ The `{name}` path — longer than `path()`, deliberately. See the second ⛔ in the header. */
+  collection: objectPath,
+  createForm,
+  /**
+   * ⛔ NOTHING IS COMPARED, AND THAT IS THE MOST DELIBERATE LINE IN THIS FILE. A CephFS has no
+   *   readable, writable field: the index returns only the name and the pools behind it, and every
+   *   prop this resource accepts is create-time or delete-time. So "present" IS "settled", and the
+   *   only honest comparison is none at all.
+   *   ⚠️ THE TEMPTING ADDITION IS `pg_num`, AND IT WOULD BE THE WORST BUG THIS PACKAGE HAS SHIPPED.
+   *     It is not in the index at all, so it can only be read from the pool endpoint — where the
+   *     autoscaler owns it. MEASURED on TB4 today: created at 128, live at 32, with the metadata
+   *     pool already scheduled down to 16. Compared, that is an eternal mismatch; and because
+   *     `updateForm` is undefined, the action it produces is REPLACE. The plan would destroy and
+   *     rebuild a live filesystem on every deploy, triggered by a daemon on its own schedule.
+   *   ⚠️ `data_pools` AND `metadata_pool_id` ARE OUT FOR THE ORDINARY REASONS: a set PVE returns
+   *     in its own order, and an integer id for something written as a name. `name` is out because
+   *     it is the FILTER that produced these attributes, so comparing it is true by construction —
+   *     an identity change is handled in `diff`, not here. `node` is out because it is a route.
+   */
+  matches: () => true,
+  /** ⚠️ THE INDEX, NOT THE OBJECT. There is no GET on `{name}`; see the second ⛔ in the header. */
+  path: (props) => `nodes/${props.node}/ceph/fs`,
+});
+
+export const ProxmoxCephFsProvider = () =>
+  Provider.effect(
+    ProxmoxCephFs,
+    Effect.succeed(
+      ProxmoxCephFs.Provider.of({
+        /**
+         * ⛔ EMPTY, LIKE EVERY OTHER RESOURCE HERE. The index answers with every filesystem on the
+         *   cluster, `cephfs-tb4` included — the one holding this estate's ISOs and templates.
+         *   Adopting it would put Alchemy one `destroy` away from it. Adoption stays explicit.
+         */
+        list: () => Effect.succeed([]),
+        read: Effect.fn(function* ({ olds }) {
+          return yield* ops.read(olds);
+        }),
+        /**
+         * ⛔ A CHANGED `name` IS A REPLACE, AND THE FACTORY CANNOT SAY SO ALONE. Left to delegate,
+         *   a rename reads the NEW name, finds nothing, and returns the drift-shaped `update` that
+         *   `pveOperations.diff` uses for "Alchemy has state, the cluster does not" — so reconcile
+         *   would build the new filesystem and LEAVE THE OLD ONE, with its pools, its storage entry
+         *   and its bytes, owned by nobody and invisible in every later plan.
+         *   ⛔ SAYING `replace` IS HONEST, AND IT IS ALSO WHAT MAKES A TYPO EXPENSIVE. Alchemy
+         *     creates first and deletes second, so the old filesystem is destroyed AFTER the new
+         *     one exists — with `remove-pools` unset the bytes are stranded rather than erased, and
+         *     that default is the only thing between a mis-typed rename and an unrecoverable one.
+         *     Do not "simplify" this back to the factory: the alternative is not safer, it is
+         *     silent. ⚠️ `node` is NOT part of identity and must never join this comparison.
+         */
+        diff: Effect.fn(function* ({ news, output }) {
+          if (output !== undefined && isResolved(news) && news.name !== output.name) {
+            return { action: 'replace' } as const;
+          }
+          return yield* ops.diff(news, output);
+        }),
+        /**
+         * ⛔ NOT `ops.reconcile`, BECAUSE ITS READ-BACK RACES A FORKED WORKER. The POST returns a
+         *   UPID and nothing else; `createFs` waits the task out and surfaces its real error. The
+         *   read-back the factory does is kept here rather than dropped — waiting proves the task
+         *   ENDED, reading proves the filesystem EXISTS, and PVE has shipped tasks that end OK
+         *   having done nothing.
+         * ⚠️ AN EXISTING FILESYSTEM IS RETURNED UNTOUCHED. There is no update call to make, so the
+         *   only write this handler can perform is a create; `diff` has already decided that a
+         *   real change is a replace, and Alchemy calls delete for the old generation itself.
+         */
+        reconcile: Effect.fn(function* ({ news }) {
+          const live = yield* ops.read(news);
+          if (live !== undefined) return live;
+          yield* createFs(news);
+          const after = yield* ops.read(news);
+          if (after === undefined) return yield* Effect.die(notCreated(news));
+          return after;
+        }),
+        /**
+         * ⛔ NOT `ops.destroy`, AND NOT AN OVERSIGHT. It would DELETE `spec.path`, which on this
+         *   family is the index — a route PVE does not implement — so every destroy would fail
+         *   while the filesystem stayed exactly where it was. The read-back afterwards is what
+         *   turns "the task said OK" into "it is actually gone": `destroyfs` refuses while a
+         *   non-disabled `cephfs` storage still references the filesystem, and that refusal must
+         *   fail the destroy rather than letting Alchemy drop the state entry for a live object.
+         */
+        delete: Effect.fn(function* ({ olds }) {
+          /**
+           * ⚠️ A FILESYSTEM SOMEBODY ALREADY REMOVED BY HAND IS NOT AN ERROR. `destroyfs` dies
+           *   synchronously with "no such cephfs", which would fail every destroy of a stack whose
+           *   filesystem was cleaned up outside Alchemy and leave the state entry unremovable
+           *   without editing the store. ⚠️ THE COST IS STATED PLAINLY: `ops.read` folds a FAILED
+           *   read into "absent" (the storage.ts trap), so a read this credential cannot perform
+           *   turns this into a destroy that reports success having done nothing. That is not a
+           *   new hazard — a broken read defeats the read-back below in exactly the same way — but
+           *   it is the reason a 403 on this family must be fixed rather than lived with.
+           */
+          if ((yield* ops.read(olds)) === undefined) return;
+          yield* destroyFs(olds);
+          const after = yield* ops.read(olds);
+          if (after !== undefined) return yield* Effect.die(notDestroyed(olds));
+        }),
+      }),
+    ),
+  );

package/src/proxmox/ceph-osd-tree.ts

@@ -0,0 +1,193 @@
+/**
+ * The CRUSH tree, walked down to one OSD leaf.
+ *
+ * ★ SPLIT OUT OF ceph-osd.ts TO KEEP BOTH FILES UNDER THE 250-LINE CAP, and the seam is the same
+ *   one metric-server-form.ts cuts: this file answers "what does the cluster say about osd.N",
+ *   ceph-osd.ts answers "what is an OSD and what may a plan do about it". Nothing here calls the
+ *   API and nothing here decides a diff. `CephOsdAttributes` lives on this side of the seam
+ *   because it is a description of what the TREE says — keeping each field's
+ *   reported-never-compared reasoning against the line that builds it — and ceph-osd.ts re-exports
+ *   it so a consumer still imports one name from one place. The `import type` back for
+ *   `CephOsdProps` is a cycle on paper only: it is erased before anything runs.
+ *
+ * ⛔ `GET /nodes/{node}/ceph/osd` ANSWERS A TREE, NOT A LIST, AND IT IS THE WHOLE CLUSTER'S TREE.
+ *   MEASURED 2026-09-13: asked of n2 it answers `{"flags":…,"root":{"children":[…]}}` whose
+ *   leaves include osd.0 and osd.5 on n4; asked of n3 it answers the identical six leaves. The
+ *   `{node}` in the path chooses WHO ANSWERS, not what is listed. A provider that read it as "the
+ *   OSDs on this node" would find osd.0 through n2 and then report it as living there.
+ *
+ * ⛔ AND THE SINGLE-OBJECT PATH CANNOT BE USED INSTEAD — THIS WALK EXISTS BECAUSE IT LIES.
+ *   MEASURED: `GET /nodes/n2/ceph/osd/99`, an id with no OSD behind it, answers HTTP 200 with
+ *   `[{"name":"metadata"},{"name":"lv-info"}]` — byte for byte what `…/osd/2` answers for a real
+ *   one. It is a directory index (its schema says `permissions: {"user":"all"}`), not a read of
+ *   the OSD. Point `PveSpec.path` at it and every declared OSD is "present": `diff` reports
+ *   `noop` over a dead replica forever, and `reconcile`'s read-back guard — the one thing that
+ *   stops this package recording objects that do not exist — passes on an OSD that was never
+ *   built. The only endpoint that can tell present from absent is the tree.
+ *
+ * ★ MEASURED ON TB4 ON 2026-09-13, `GET /nodes/n2/ceph/osd`. Six leaves, all `up` and `in`, Ceph
+ *   20.2.2 tentacle:
+ *
+ *     id  name   host  device_class  crush_weight      reweight  pgs  status
+ *     0   osd.0  n4    ssd           1.86299133300781  1          99  up
+ *     5   osd.5  n4    ssd           1.86299133300781  1          94  up
+ *     1   osd.1  n3    ssd           1.86299133300781  1          96  up
+ *     4   osd.4  n3    ssd           1.81939697265625  1          97  up
+ *     2   osd.2  n2    ssd           1.81939697265625  1          88  up
+ *     3   osd.3  n2    ssd           1.81939697265625  1         105  up
+ *
+ *   `{ node: 'n2', osdid: 2, host: 'n2', device_class: 'ssd' }` plans `noop` against that row.
+ *   That is the acceptance test this file was written to pass.
+ *
+ * ⚠️ EVERY OTHER COLUMN IS REPORTED AND NEVER COMPARED, FOR FOUR DIFFERENT REASONS. `pgs` is the
+ *   autoscaler's placement rather than anybody's declaration — MEASURED, it spans 88 to 105 across
+ *   six identical disks, and Ceph moves PGs whenever it rebalances. `crush_weight` is a FLOAT
+ *   derived from device size (MEASURED: 1.86299133300781), so comparing it is float equality
+ *   against a number Ceph recomputes on `crush reweight`. `reweight` is what
+ *   `reweight-by-utilization` writes, unasked. `status` and `in` are daemon state: an OSD that
+ *   flaps down while a node reboots would otherwise put work in the plan that no write this
+ *   provider owns could ever clear. Each of those is the forever-update this package has already
+ *   been bitten by, and each is out of `settled` below.
+ *
+ * ⚠️ THE CLUSTER'S OSD FLAGS ARE NOT AN ATTRIBUTE EITHER. The read carries
+ *   `"flags":"sortbitwise,recovery_deletes,purged_snapdirs,pglog_hardlimit"` NEXT TO the root
+ *   rather than inside any leaf: they describe the OSDMap, not this OSD. Recording them per-OSD
+ *   would rewrite all six resources' state the moment somebody set `noout` for ten minutes of
+ *   maintenance — the churn-that-reads-like-drift that keeps `digest` out of storage.ts.
+ *
+ */
+import * as Effect from 'effect/Effect';
+import type { CephOsdProps } from './ceph-osd.ts';
+import { pve } from './client.ts';
+import { bool, int, num, text } from './values.ts';
+
+/** A CRUSH node. Buckets carry `children`; an OSD leaf carries `type: 'osd'`. */
+type CrushNode = Record<string, unknown>;
+
+const branches = (node: CrushNode): CrushNode[] =>
+  (Array.isArray(node['children']) ? node['children'] : []).filter(
+    (child): child is CrushNode => typeof child === 'object' && child !== null,
+  );
+
+/**
+ * Every OSD leaf under the tree root, at any depth.
+ *
+ * ⚠️ RECURSIVE BECAUSE THE TREE IS NOT THREE LEVELS DEEP BY LAW. TB4 measures as
+ *   root(`default`) -> host(n2|n3|n4) -> osd, but CRUSH admits datacenter, rack and chassis
+ *   buckets between them, and an OSD created outside a host bucket hangs off the root. Reaching
+ *   in as `root.children[].children[]` would read this cluster correctly and answer "absent" —
+ *   i.e. "the replica is gone" — on the first cluster that has a rack in it.
+ *
+ * ⚠️ THE OUTERMOST OBJECT IS NOT ITSELF A BUCKET. MEASURED: `root` is `{"children":[…],"leaf":0}`
+ *   with no `type` and no `name`; the bucket called `default` is its first child. So the walk
+ *   starts at `tree.root` and selects on `type === 'osd'` rather than assuming a shape.
+ */
+export const osdLeaves = (tree: CrushNode): CrushNode[] => {
+  const root = tree['root'];
+  const start: CrushNode = typeof root === 'object' && root !== null ? (root as CrushNode) : {};
+  const walk = (node: CrushNode): CrushNode[] => [
+    ...(node['type'] === 'osd' ? [node] : []),
+    ...branches(node).flatMap(walk),
+  ];
+  return walk(start);
+};
+
+/**
+ * The leaf for one OSD id, or undefined when nothing in the tree carries it.
+ *
+ * ⛔ `id` COMES BACK AS A STRING HERE AND AS AN INTEGER EVERYWHERE ELSE, which is the "an id
+ *   returned one way and written another" forever-diff in its most expensive form. MEASURED: the
+ *   leaf for osd.2 carries `"id":"2"` (and the host buckets carry `"id":"-7"`), while
+ *   `GET …/osd/2/metadata` carries `"id":2` and the `osdid` parameter on POST and DELETE is typed
+ *   integer. `'2' === 2` is false, so a provider comparing the raw value finds NOTHING, calls
+ *   every declared OSD absent — and, with a create path wired up, offers to build six OSDs over
+ *   six live disks. `int` from values.ts is the narrowing, and `Number.NaN` is the fallback
+ *   precisely because it equals nothing, id 0 included.
+ *
+ * ⚠️ FIRST MATCH WINS. OSD ids are unique cluster-wide, and PVE does not put the per-device-class
+ *   shadow buckets (`default~ssd`) in this tree — MEASURED: the whole tree is one `default` root,
+ *   three hosts, six leaves. If a future PVE did include them, taking the first match keeps the
+ *   answer stable instead of reporting drift depending on which copy was walked into first.
+ */
+export const findOsd = (tree: CrushNode, osdid: number) =>
+  osdLeaves(tree).find((leaf) => int(leaf['id'], Number.NaN) === osdid);
+
+export interface CephOsdAttributes {
+  /** Normalised to an integer here even though the tree spells it `"2"`. */
+  osdid: number;
+  /** `osd.2` — how Ceph, the UI and every log line name it. */
+  name: string;
+  /** COMPARED, but only when `props.host` is declared. */
+  host: string;
+  /** COMPARED, but only when `props.device_class` is declared. */
+  device_class: string;
+  /**
+   * ⚠️ REPORTED, NEVER COMPARED — `bluestore` on every live OSD and filestore has been gone for
+   *   years, so declaring it would add a field that cannot disagree. It is recorded because a
+   *   future objectstore change is exactly the kind of thing state should have caught in writing.
+   */
+  osdtype: string;
+  /** ⚠️ REPORTED, NEVER COMPARED. Daemon state — see the second ⚠️ in the header. */
+  status: string;
+  /** ⚠️ REPORTED, NEVER COMPARED. Ceph itself sets this to 0 after `mon_osd_down_out_interval`. */
+  in: boolean;
+  /** ⚠️ REPORTED, NEVER COMPARED. A float Ceph recomputes; comparing it is a permanent diff. */
+  crush_weight: number;
+  /** ⚠️ REPORTED, NEVER COMPARED. `reweight-by-utilization` owns this number, not a declaration. */
+  reweight: number;
+  /** ⚠️ REPORTED, NEVER COMPARED. The autoscaler moves PGs between OSDs whenever it likes. */
+  pgs: number;
+  /** Device capacity in bytes. Stable per disk, and the honest answer to "how big is this OSD". */
+  total_space: number;
+  /** `20.2.2`. ⚠️ Reported, never compared — an upgrade is not this resource's drift. */
+  ceph_version: string;
+}
+
+/**
+ * One leaf, as the attributes a plan and the state store get to see.
+ *
+ * ⚠️ THE TELEMETRY IS DELIBERATELY DROPPED, NOT FORGOTTEN. The leaf also carries `bytes_used`,
+ *   `percent_used`, `apply_latency_ms` and `commit_latency_ms`. MEASURED, AND THE MEASUREMENT SAYS
+ *   THE OPPOSITE OF WHAT YOU WOULD EXPECT: across two reads minutes apart, all four were identical
+ *   on every OSD, and both latencies read 0 — TB4 was idle, so nothing was caught in the act. That
+ *   these move is therefore REASONED, from what they count, not observed. Alchemy persists
+ *   attributes; on a cluster doing work, keeping them would rewrite all six resources' state on
+ *   every deploy and record a number that is stale by the time anybody reads it. What is kept is
+ *   what a human asking "what is this replica, and is it healthy" needs; it is not a metrics feed.
+ *
+ * ⚠️ `osdid` AND `name` ARE THE NORMALISED ID AND ITS SPELLING, taken from the leaf rather than
+ *   echoed from props, so that state records what the cluster said. They agree by construction
+ *   here — the leaf was found BY id — but echoing props into attributes is how a resource ends up
+ *   recording a declaration as though it were an observation.
+ */
+export const osdAttributes = (leaf: CrushNode, props: CephOsdProps): CephOsdAttributes => ({
+  ceph_version: text(leaf['ceph_version_short']),
+  crush_weight: num(leaf['crush_weight'], 0),
+  device_class: text(leaf['device_class']),
+  host: text(leaf['host']),
+  in: bool(leaf['in']),
+  name: text(leaf['name'], `osd.${String(props.osdid)}`),
+  osdid: int(leaf['id'], props.osdid),
+  osdtype: text(leaf['osdtype']),
+  pgs: num(leaf['pgs'], 0),
+  reweight: num(leaf['reweight'], 0),
+  status: text(leaf['status']),
+  total_space: num(leaf['total_space'], 0),
+});
+
+/**
+ * The live OSD as attributes, or undefined.
+ *
+ * ★ IT LIVES HERE RATHER THAN IN ceph-osd.ts BECAUSE THE READ SIDE IS THIS FILE'S WHOLE JOB —
+ *   `findOsd` and `osdAttributes` are the two halves it composes, and keeping the caller beside
+ *   them is what let ceph-osd.ts come back under the 250-line cap when create and delete were
+ *   added. ⚠️ A 404 or a 403 both arrive here as `undefined`: see the ⛔ on `readRole` in
+ *   resource.ts for why that distinction is invisible and what it costs.
+ */
+export const readOsd = (props: CephOsdProps) =>
+  pve<Record<string, unknown>>(props.target, 'read', 'GET', `nodes/${props.node}/ceph/osd`).pipe(
+    Effect.map((t) => {
+      const leaf = t === undefined ? undefined : findOsd(t, props.osdid);
+      return leaf === undefined ? undefined : osdAttributes(leaf, props);
+    }),
+  );

package/src/proxmox/ceph-osd-write.ts

@@ -0,0 +1,76 @@
+/**
+ * The two operations that change a disk: building an OSD and removing one.
+ *
+ * ★ SPLIT OUT OF ceph-osd.ts FOR THE 250-LINE CAP, and the seam is the honest one — this file is
+ *   everything that WRITES, and ceph-osd.ts is the declaration and the assertion. A reader asking
+ *   "can this destroy my data" has one file to read.
+ *
+ * ⛔ BOTH OF THESE ARE IRREVERSIBLE. `create` hands a block device to `ceph-volume lvm create`,
+ *   which zaps it; `delete` takes a replica out of a live pool and Ceph immediately begins
+ *   rewriting the missing copies across the remaining nodes. `Proxmox.CephOsd` therefore declares
+ *   `defaultRemovalPolicy: 'retain'`, so removing a declaration does NOT reach `destroyOsd` — a
+ *   caller opts in with `.pipe(RemovalPolicy.destroy())`.
+ */
+import * as Effect from 'effect/Effect';
+import { readOsd } from './ceph-osd-tree.ts';
+import type { CephOsdProps } from './ceph-osd.ts';
+import { pve } from './client.ts';
+
+const describe = (props: CephOsdProps) => `osd.${String(props.osdid)} on ${props.node}`;
+
+export const createOsd = Effect.fn(function* (news: CephOsdProps) {
+  if (news.dev === undefined) {
+    return yield* Effect.die(
+      new Error(
+        `${describe(news)}: no such OSD in the CRUSH tree, and no \`dev\` was declared. ` +
+          'Without a device this resource is an ASSERTION over an OSD that must already ' +
+          'exist. Declare `dev` to let it create one -- which WIPES that device -- or fix ' +
+          'the declaration; if the disk was there yesterday, a replica is missing and Ceph ' +
+          'is degraded.',
+      ),
+    );
+  }
+  yield* pve(news.target, 'provision', 'POST', `nodes/${news.node}/ceph/osd`, {
+    dev: news.dev,
+    ...(news.device_class === undefined ? {} : { 'crush-device-class': news.device_class }),
+  });
+  const created = yield* readOsd(news);
+  if (created === undefined) {
+    return yield* Effect.die(
+      new Error(
+        `${describe(news)}: the create returned no error but osd.${String(news.osdid)} is ` +
+          'still absent. Ceph allocates OSD ids and cannot be told which to use, so it most ' +
+          'likely assigned a different number -- check `ceph osd tree`, and declare the id it ' +
+          'actually gave the device rather than deploying again.',
+      ),
+    );
+  }
+  return created;
+});
+
+/**
+ * ⛔ REMOVING THE DECLARATION REMOVES THE ASSERTION, NOT THE REPLICA, AND THAT ASYMMETRY IS THE
+ *   POINT. `DELETE /nodes/{node}/ceph/osd/{osdid}` takes a replica out of a live pool — with
+ *   `nobackfill`/`norecover` unset, Ceph immediately starts rewriting the missing copies across
+ *   the two remaining nodes — and with `cleanup=1` it zaps the LVs as well. A stack file is
+ *   edited by people in a hurry; a disk is not a thing a deleted line gets to destroy. Take an
+ *   OSD out by hand, with the cluster healthy and `ceph -s` in front of you: `ceph osd out N`,
+ *   wait for the backfill to finish, then `pveceph osd destroy N`.
+ *
+ * ★ SO IT IS IMPLEMENTED, AND THE RESOURCE DEFAULTS TO `retain` INSTEAD. Removing a declaration
+ *   drops the state row and leaves the replica alone; a caller who really means it opts in with
+ *   `.pipe(RemovalPolicy.destroy())`. That is the same shape Terraform gives `prevent_destroy`,
+ *   and it beats a `delete` that silently does nothing — which is a lie to anyone reading the
+ *   plan.
+ *
+ * ⚠️ `cleanup` DEFAULTS TO FALSE, so the logical volumes survive and the disk can be re-added
+ *   without a rebuild. Ceph still starts backfilling the missing copies the moment the OSD goes.
+ */
+export const destroyOsd = (olds: CephOsdProps) =>
+  pve(
+    olds.target,
+    'provision',
+    'DELETE',
+    `nodes/${olds.node}/ceph/osd/${String(olds.osdid)}`,
+    olds.cleanup === true ? { cleanup: '1' } : {},
+  );