@homeflare/alchemy 0.1.0

package/src/proxmox/ceph-osd.ts

@@ -0,0 +1,244 @@
+/**
+ * `Proxmox.CephOsd` — one OSD in the cluster's CRUSH tree.
+ *
+ * ⛔ CREATE AND DELETE ARE IMPLEMENTED AND `root@pam` IS THE ONLY IDENTITY THAT CAN RUN THEM.
+ *   That is PVE's restriction, not this package's caution, and it is MEASURED from the cluster's
+ *   own schema (`/usr/share/pve-docs/api-viewer/apidoc.js`, 2026-09-13):
+ *
+ *     GET    /nodes/{node}/ceph/osd          -> {"check":["perm","/",["Sys.Audit","Datastore.Audit"],"any",1]}
+ *     POST   /nodes/{node}/ceph/osd          -> *** no permissions block at all ***
+ *     DELETE /nodes/{node}/ceph/osd/{osdid}  -> *** no permissions block at all ***
+ *
+ *   A PVE method with no permissions block is refused to every identity except `root@pam`, so an
+ *   OpenBao-minted `hf-provision@pve!…` token is answered 403 however wide its role — widening
+ *   `LXCProvisioner` cannot fix it. Compare the sibling families, which DO carry a check and
+ *   therefore do work with a token: `ceph/fs`, `ceph/mon` and `disks/zfs` all want `Sys.Modify`.
+ *
+ * ⚠️ SO THE WRITE PATH IS HONEST RATHER THAN USEFUL. It is written out properly in
+ *   `ceph-osd-write.ts` — read that file for what each verb destroys — and it will work for an
+ *   operator running as root@pam. Through this package's credential it will 403, and a 403 is a
+ *   better answer than a `delete` that silently does nothing while the plan claims otherwise.
+ *
+ * ★ WHAT IT IS ACTUALLY FOR, THEN: ASSERTION. It turns "n2, n3 and n4 each hold two ssd OSDs"
+ *   into a line a plan checks, and it gives Ceph-backed resources something real to depend on —
+ *   read `osd.osdid` into an `rbd` storage's props and Alchemy orders that storage after the
+ *   assertion, so a stack can no longer report a healthy Ceph storage on a cluster whose OSDs are
+ *   gone. A replica that disappears becomes work in `plan` and a loud failure on the deploy.
+ *
+ * ⛔ THE WRITE VERBS MAY NOT EVEN BE REACHABLE FOR THIS PACKAGE'S CREDENTIAL. MEASURED from the
+ *   cluster's own schema (`/usr/share/pve-docs/api-viewer/apidoc.js`, 2026-09-13): `index`,
+ *   `osdindex`, `metadata` and `lv-info` each declare a `permissions` block, while `createosd`
+ *   and `destroyosd` declare NONE — the key is absent, not empty. REASONED, NOT MEASURED: PVE
+ *   refuses a method with no permissions block to everyone but `root@pam`, so an OpenBao-minted
+ *   `hf-provision@pve!…` token would likely be answered 403 however wide its role. That is a
+ *   reason to leave the write lane closed, not something to confirm by trying: if the reasoning
+ *   is wrong, the confirmation costs a disk.
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type { CephOsdAttributes } from './ceph-osd-tree.ts';
+import { readOsd } from './ceph-osd-tree.ts';
+import { createOsd, destroyOsd } from './ceph-osd-write.ts';
+import type { PveRequirements } from './resource.ts';
+import type { WithTarget } from './resource.ts';
+
+/**
+ * ⚠️ RE-EXPORTED, NOT DECLARED HERE — it is built in ceph-osd-tree.ts, next to the walk that fills
+ *   it in and to the reasoning for which of its fields may be compared. One name, one import.
+ */
+export type { CephOsdAttributes };
+
+export interface CephOsdProps extends WithTarget {
+  /**
+   * Which node ANSWERS the read — not where the OSD lives. MEASURED: the tree n2 returns and the
+   * tree n3 returns are the same six leaves, n4's included. Point this at any node that is up;
+   * `host` is the field that says where the disk is.
+   */
+  node: string;
+  /** `2` for `osd.2`. Identity, and an INTEGER — see the ⛔ on `findOsd` in ceph-osd-tree.ts. */
+  osdid: number;
+  /**
+   * The CRUSH host bucket this OSD must sit in. Undeclared means unmanaged, as in storage.ts.
+   *
+   * ⚠️ DECLARING IT IS AN ASSERTION WITH NO REPAIR. If osd.2 turns up under n3, the plan reports
+   *   work every time and the deploy fails, because moving an OSD between failure domains is a
+   *   `ceph osd crush move` this provider will not perform. That is the intent: a replica in the
+   *   wrong failure domain is not something to converge quietly past.
+   */
+  host?: string;
+  /**
+   * `ssd` | `hdd` | `nvme`, asserted the same way as `host`.
+   *
+   * ⚠️ THE READ'S SPELLING IS KEPT rather than the create parameter's (`crush-device-class`).
+   *   This resource never writes, so the tree's name is the only one it has, and inventing a
+   *   second name for one field is exactly what values.ts exists to stop.
+   */
+  device_class?: string;
+  /**
+   * The block device to build this OSD from, e.g. `/dev/nvme1n1`. Declaring it makes the resource
+   * able to CREATE; leaving it out keeps the resource a pure assertion over an OSD that exists.
+   *
+   * ⛔ EVERYTHING ON THIS DEVICE IS DESTROYED BY A CREATE. `POST /nodes/{node}/ceph/osd` hands it
+   *   to `ceph-volume lvm create`, which zaps it. Declare it only for a disk that is genuinely
+   *   blank, and read the ⛔ about id allocation below before assuming the create will land as the
+   *   `osdid` written above.
+   */
+  dev?: string;
+  /**
+   * Zap the OSD's logical volumes on destroy (`cleanup=1`). Default false: the LVs are left behind
+   * so the disk can be re-added without a rebuild, which is the recoverable choice.
+   */
+  cleanup?: boolean;
+}
+
+export interface ProxmoxCephOsd extends Resource<
+  'Proxmox.CephOsd',
+  CephOsdProps,
+  CephOsdAttributes,
+  never,
+  PveRequirements
+> {}
+
+/**
+ * ★ `retain` BY DEFAULT, FOLLOWING ALCHEMY'S OWN PRECEDENT. `GitHub.Repository` and
+ *   `Cloudflare.Zone` default to retain "because their contents are irreplaceable"; an OSD is a
+ *   replica of live data and qualifies twice over. Retain means DELETING THE DECLARATION DOES NOT
+ *   DELETE THE OSD — Alchemy drops its state row and leaves the disk alone. `destroyOsd` is fully
+ *   implemented in ceph-osd-write.ts and runs when the caller opts in with
+ *   `.pipe(RemovalPolicy.destroy())`, so this is the Terraform `prevent_destroy` shape rather than
+ *   a missing operation — and through a minted token it 403s anyway, per the ⛔ at the top.
+ */
+export const ProxmoxCephOsd = Resource<ProxmoxCephOsd>('Proxmox.CephOsd', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/**
+ * The live OSD, or undefined when the tree has no leaf with that id.
+ *
+ * ⛔ NO `Effect.orElseSucceed(() => undefined)`, AND THAT IS THE ONE DELIBERATE DEPARTURE FROM
+ *   `pveOperations.read`. The factory folds every failure into "absent" because a 404 is a
+ *   legitimate answer on a per-object path — but this path is a COLLECTION that always exists
+ *   while Ceph is installed, so a failure here is never "the OSD is gone". It is an unreachable
+ *   node, an expired lease, a role without `Sys.Audit`, or a cluster with no Ceph at all. Folding
+ *   those into "absent" would turn every one of them into the sentence "osd.2 is missing", which
+ *   is the most alarming thing this provider can say and would be a lie in all four cases. Left
+ *   to fail, the plan shows `PVE GET nodes/n2/ceph/osd -> 500: …` and names the real problem.
+ */
+
+/**
+ * Whether the live OSD is the one that was declared.
+ *
+ * ⚠️ AN UNDECLARED FIELD IS NOT COMPARED, as in storage.ts: undeclared means unmanaged, and there
+ *   is no default to fall back on — the whole point of a CRUSH placement is that it is a choice.
+ *   Declaring nothing but `osdid` therefore asserts only presence, which is a perfectly good
+ *   thing to assert about a replica and the safest declaration this resource accepts.
+ */
+const settled = (live: CephOsdAttributes, props: CephOsdProps) =>
+  (props.host === undefined || props.host === live.host) &&
+  (props.device_class === undefined || props.device_class === live.device_class);
+
+const describe = (props: CephOsdProps) =>
+  `osd.${String(props.osdid)} (read via nodes/${props.node}/ceph/osd)`;
+
+/**
+ * ⛔ HAND-WRITTEN RATHER THAN `pveHandlers(spec)`, and the reason is not that the shape does not
+ *   fit — it fits perfectly, which is the danger. Given a spec, the factory's `reconcile` POSTs
+ *   `createForm` at `collection` whenever the read says absent, and `destroy` DELETEs `path`.
+ *   Wired to this family that is: build an OSD over whatever block device the props named, and
+ *   remove a replica when somebody deletes a line from a stack file. acl.ts is the precedent for
+ *   overriding the factory because PVE lacks a verb; this file overrides it because PVE HAS the
+ *   verbs and they must not be reachable from a declaration.
+ *
+ * ⚠️ THERE IS NO `replace` PATH HERE AND THERE CANNOT BE ONE. Alchemy implements a replace as
+ *   create-then-delete (or the reverse); with both of those refusing, `replace` could only ever
+ *   be a failure wearing a different word. A changed `osdid` is simply a different assertion.
+ */
+const handlers = {
+  /**
+   * ⛔ EMPTY, as everywhere in this package, and here the stakes are at their highest. The tree is
+   *   the whole cluster's — adopting it would hand Alchemy six resources it never created, each
+   *   with a `delete` in its future. Adoption stays an explicit act, and for this family it stays
+   *   an act with no teeth: see `delete` below.
+   */
+  list: () => Effect.succeed([]),
+
+  read: Effect.fn(function* ({ olds }: { olds: CephOsdProps }) {
+    return yield* readOsd(olds);
+  }),
+
+  /**
+   * ⚠️ `update` IS THE LOUDEST WORD AVAILABLE, NOT A PROMISE TO FIX ANYTHING. Alchemy's Diff
+   *   admits only noop/update/replace, so a missing or misplaced OSD has to be spelled `update`
+   *   — and the deploy that follows fails on purpose in `reconcile`. A resource that answered
+   *   `noop` over a replica that is not there would be the exact lie this package keeps writing
+   *   guards against; a permanent entry in `plan` until a human puts a disk back is the cost, and
+   *   it is the right cost for a degraded pool.
+   */
+  diff: Effect.fn(function* ({
+    news,
+    output,
+  }: {
+    news: Input<CephOsdProps>;
+    output: CephOsdAttributes | undefined;
+  }) {
+    if (output === undefined || !isResolved(news)) return undefined;
+    const live = yield* readOsd(news);
+    if (live === undefined) return { action: 'update' } as const;
+    /**
+     * ⛔ THE RECORDED STATE MUST DESCRIBE THE OSD THE DECLARATION NOW NAMES. `settled` compares
+     *   only host and device_class, so changing `osdid: 2` to `3` reads osd.3, finds it on the
+     *   same host with the same class, and answers noop — which records nothing, leaving OSD 2's
+     *   crush_weight, pgs and name in state under a declaration that says 3. It is the OUTPUT's id
+     *   that must be checked: the LIVE id is found BY `news.osdid`, so comparing that is vacuous.
+     */
+    if (output.osdid !== news.osdid) return { action: 'update' } as const;
+    return settled(live, news) ? ({ action: 'noop' } as const) : ({ action: 'update' } as const);
+  }),
+
+  /**
+   * ⛔ THE ASSERTION, AND THE WHOLE REASON THIS PROVIDER IS HAND-WRITTEN. It reads, and then it
+   *   either records what it found or dies. It never POSTs. The first deploy of a declaration is
+   *   an adoption of an OSD that already exists; every later one is a check that it still does.
+   */
+  reconcile: Effect.fn(function* ({ news }: { news: CephOsdProps }) {
+    const live = yield* readOsd(news);
+    if (live === undefined) {
+      /**
+       * ⛔ CEPH ALLOCATES THE OSD ID; THE DECLARATION CANNOT CHOOSE IT. Measured from the schema:
+       *   `POST /nodes/{node}/ceph/osd` requires `dev` and takes `crush-device-class`, `db_dev`,
+       *   `wal_dev`, `encrypted` and `osds-per-device` — and NO id. The cluster assigns the next
+       *   free number. So a create only lands on the declared `osdid` when that number happens to
+       *   be the one Ceph picks, which for a fresh disk on a contiguous cluster it usually is.
+       *   The read-back below is what keeps that from being a silent mismatch: if Ceph assigned a
+       *   different id, the OSD this resource names is still absent and reconcile refuses.
+       */
+      return yield* createOsd(news);
+    }
+    if (!settled(live, news)) {
+      return yield* Effect.die(
+        new Error(
+          `${describe(news)}: exists but not as declared -- live host=${live.host} ` +
+            `device_class=${live.device_class}. Nothing here moves an OSD between hosts or ` +
+            'reclassifies it; fix the declaration, or move it deliberately with `ceph osd crush ' +
+            'move` / `ceph osd crush set-device-class` and deploy again.',
+        ),
+      );
+    }
+    return live;
+  }),
+
+  /**
+   * ⛔ REMOVING THE DECLARATION REMOVES THE ASSERTION, NOT THE REPLICA — the resource defaults
+   *   to `retain`, so this runs only on `.pipe(RemovalPolicy.destroy())`. What the DELETE actually
+   *   does to a live pool is documented on `destroyOsd` in ceph-osd-write.ts.
+   */
+  delete: Effect.fn(function* ({ olds }: { olds: CephOsdProps }) {
+    yield* destroyOsd(olds);
+  }),
+};
+
+export const ProxmoxCephOsdProvider = () =>
+  Provider.effect(ProxmoxCephOsd, Effect.succeed(ProxmoxCephOsd.Provider.of(handlers)));

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

@@ -0,0 +1,249 @@
+/**
+ * What a Ceph pool IS as a declaration, and the two different forms PVE wants it in.
+ *
+ * ★ SPLIT OUT OF ceph-pool.ts TO KEEP BOTH FILES UNDER THE 250-LINE CAP, and the seam is
+ *   "does this touch the cluster" — the same one metric-server-form.ts draws, just with more on
+ *   this side because this family needs it. Here: the declared shape, the reported shape, and the
+ *   coercions that turn one into the other. There: reading TB4, deciding a diff, and the four
+ *   handlers. Nothing in this file makes a call or decides an action.
+ * ⚠️ THE PROPS LIVE HERE RATHER THAN IN THE RESOURCE FILE, which is the one place this pair
+ *   differs from metric-server / notification-target. There is no `import type` cycle back as a
+ *   result; ceph-pool.ts re-exports both interfaces so the public surface is unchanged.
+ *
+ * ⛔ POST AND PUT DO NOT TAKE THE SAME PARAMETERS, AND BOTH EXTRAS ARE DESTRUCTIVE. MEASURED from
+ *   the cluster's own schema (/usr/share/pve-docs/api-viewer/apidoc.js on n2, pve-manager 9.2.11,
+ *   2026-09-13): POST adds `add_storages` and `erasure-coding` to the shared set, PUT takes
+ *   neither. Both are refused below, so what is left between the two bodies is `name`, which PUT
+ *   reads from the path, and `pg_num`.
+ *
+ * ⛔ `pg_num` IS IN THE CREATE BODY AND NOT IN THE UPDATE BODY, AND THAT IS THE MOST IMPORTANT
+ *   LINE IN THIS FILE. MEASURED in PVE::API2::Ceph::Pool::createpool on n2: a POST carrying no
+ *   `pg_num` gets 128 substituted (`$param->{pg_num} //= 128`), and PVE::Ceph::Tools::create_pool
+ *   then runs `osd pool create` — which Ceph answers with SUCCESS for a pool that already exists,
+ *   before applying the rest of the body to it. So a create fired at a live pool SETS its pg_num,
+ *   and lowering pg_num starts a PG MERGE: hours of backfill across every OSD, on a cluster whose
+ *   Ceph traffic shares vmbr1.11 with everything else. ceph-pool.ts guards the create for exactly
+ *   that reason; this half simply never offers pg_num to an update.
+ */
+import type { WithTarget } from './resource.ts';
+import { csv } from './values.ts';
+
+export interface CephPoolProps extends WithTarget {
+  /**
+   * ⚠️ WHICH NODE THE CALL GOES THROUGH, NOT WHERE THE POOL LIVES. A pool is cluster-wide: n2 and
+   *   n3 answer byte-identically for `cephtb4` (measured). The endpoint is node-scoped only
+   *   because PVE talks to the local RADOS socket, so this is a door, not a location — it is never
+   *   compared, and moving a declaration from n2 to n3 plans noop. Point it at a node you expect
+   *   to be up: a node that is down makes the read fail, and a failed read reads as "absent".
+   */
+  node: string;
+  /**
+   * Ceph's primary key, cluster-wide.
+   * ⛔ CHANGING IT DOES NOT RENAME ANYTHING. There is no rename in this API: the plan reads the new
+   *   name, finds nothing, and CREATES AN EMPTY POOL, leaving the old one and its data behind,
+   *   untracked. `replace` was considered and rejected — it would DELETE the old pool and every
+   *   image in it to satisfy an edited string. Rename by hand, deliberately, or not at all.
+   */
+  name: string;
+  /** Replicas per object, 1-7. ⚠️ Frozen when the pool carries Ceph's `nosizechange`. */
+  size?: number;
+  /** Replicas required to accept writes, 1-7. ⚠️ Frozen by `nosizechange` too. */
+  min_size?: number;
+  /**
+   * ⛔ CREATE-TIME ONLY, AND NEVER COMPARED — the single biggest noop hazard in this family. With
+   *   `pg_autoscale_mode` on or warn the autoscaler owns this number: MEASURED on TB4, `cephtb4`
+   *   sits at pg_num 128 while the autoscaler's own `pg_num_final` is 256, so a declaration
+   *   diffing it reports an update the moment Ceph decides to act. A split is gradual even with
+   *   the autoscaler off, and `nopgchange` can refuse the write outright — which kills the WHOLE
+   *   PUT, not just this field. Declare it as the birth size; steer it afterwards with
+   *   `pg_num_min`, or by hand.
+   */
+  pg_num?: number;
+  /** The floor the autoscaler may not go below. Operator-owned and stable, so it IS compared. */
+  pg_num_min?: number;
+  /** ⚠️ PVE's create default is `warn`; Ceph's own is `on`, which is what all four TB4 pools have. */
+  pg_autoscale_mode?: 'off' | 'on' | 'warn';
+  /**
+   * The CRUSH rule BY NAME, e.g. `replicated_rule`.
+   * ★ THE SUSPECTED INTEGER-VS-NAME TRAP IS REAL BUT NOT ON THE PATH THIS RESOURCE READS, AND THAT
+   *   IS MEASURED BOTH WAYS. `GET .../ceph/pool` (the collection) reports `crush_rule: 0` with the
+   *   name beside it in `crush_rule_name`; `GET .../ceph/pool/{name}/status` reports
+   *   `crush_rule: "replicated_rule"` — the same spelling POST and PUT accept. Reading the
+   *   collection instead would reintroduce the forever-diff in a single edit.
+   */
+  crush_rule?: string;
+  /**
+   * ⛔ CREATE-TIME ONLY, AND NEVER COMPARED. PVE's PUT turns this into
+   *   `osd pool application enable` (Tools.pm:250-255), which ADDS a tag and never removes one,
+   *   and Ceph refuses a second application without `--yes-i-really-mean-it` — so an update would
+   *   either leave the pool tagged twice or die, and comparing one declared string against the
+   *   LIST that comes back is the set-in-arbitrary-order forever-diff. The live list is reported
+   *   as `applications` instead.
+   */
+  application?: 'cephfs' | 'rbd' | 'rgw';
+  /** Autoscaler size hint, ⚠️ IN BYTES — see the ⚠️ on `updateBody`. A `1T` string is not accepted. */
+  target_size?: number;
+  /**
+   * Autoscaler share of total capacity, 0-1.
+   * ⚠️ WRITTEN BUT NEVER DIFFED, because a float is not a safe equality: Ceph stores a double and
+   *   PVE prints about 15 significant digits, so a ratio that is not exactly representable would
+   *   report an update on every plan for a pool nobody touched.
+   */
+  target_size_ratio?: number;
+  /**
+   * ⛔ `never` ON PURPOSE, BOTH OF THEM, AND THE COMPILE ERROR IS THE FEATURE.
+   *   `erasure-coding` does not configure this pool — it makes PVE build TWO pools and name
+   *   neither of them what you declared: `<name>-data` for the EC data and `<name>-metadata` for
+   *   the replicated half (Pool.pm:517-530). Nothing would then exist at `{name}`, so every plan
+   *   would read absent and try to create it again, forever.
+   *   `add_storages` writes a section into storage.cfg that this graph does not own; declare a
+   *   `Proxmox.Storage` and pass this pool's `name` into it instead, which makes the link real.
+   */
+  'erasure-coding'?: never;
+  add_storages?: never;
+}
+
+/**
+ * ⚠️ THE THREE `no*` FLAGS ARE REPORTED BECAUSE THEY EXPLAIN A REFUSAL. Ceph can freeze a pool's
+ *   size or its PG shape, and `set_pool` dies on the whole PUT when any one parameter will not
+ *   apply (Tools.pm:310). `matches` refuses to diff the fields they freeze, so these attributes
+ *   are the only place a plan can show WHY a declared size is not being enforced. All three read
+ *   false on all four TB4 pools.
+ * ⚠️ `pg_num`, `id` AND `applications` ARE REPORTED AND NEVER COMPARED — see the props above.
+ * ⛔ NO `statistics` AND NO `autoscale_status`, though the verbose read returns both. They change
+ *   every few seconds; persisting them would rewrite this resource's state on every deploy and
+ *   read like drift. `UNSET` means the pool carries no value for that field.
+ */
+export interface CephPoolAttributes {
+  name: string;
+  /** The node the read went through. A debugging aid, not a property of the pool. */
+  node: string;
+  id: number;
+  size: number;
+  min_size: number;
+  pg_num: number;
+  pg_num_min: number;
+  pg_autoscale_mode: string;
+  /** ⚠️ Empty when PVE answered with a rule id instead of a name; `matches` then stops diffing it. */
+  crush_rule: string;
+  /** Sorted comma list, e.g. `rbd` or `cephfs`. Readable only under `?verbose=1`. */
+  applications: string;
+  target_size: number;
+  target_size_ratio: number;
+  nodelete: boolean;
+  nopgchange: boolean;
+  nosizechange: boolean;
+}
+
+/**
+ * Where one pool is WRITTEN, and where a new one is POSTed.
+ *
+ * ⚠️ NEITHER IS WHERE IT IS READ — the read path is a segment longer and lives in ceph-pool.ts
+ *   next to the ⛔ that explains it. These two are here because a path is wire knowledge, and
+ *   because the create guard needs the collection without needing anything else from the spec.
+ */
+export const object = (props: CephPoolProps) => `nodes/${props.node}/ceph/pool/${props.name}`;
+export const collection = (props: CephPoolProps) => `nodes/${props.node}/ceph/pool`;
+
+/**
+ * ⚠️ "NOT SET" IS -1 AND NOT 0, for the reason metric-server-form.ts gives: `pg_num_min`,
+ *   `target_size` and `target_size_ratio` each take 0 as a REAL value meaning "no floor, no hint",
+ *   so a provider using 0 as its absent-marker cannot tell a declared zero from an undeclared
+ *   field. Every one of these is >= 0, so -1 sits outside all of their ranges.
+ */
+export const UNSET = -1;
+
+/** ⚠️ PVE returns the tags as an ARRAY in Ceph's order, so `csv` sorts before anything sees them. */
+export const applications = (value: unknown) =>
+  csv(Array.isArray(value) ? value.map((entry: unknown) => String(entry)) : []);
+
+/**
+ * Declared? compare it. Undeclared, or frozen by a flag the pool carries? leave it alone.
+ *
+ * ⚠️ `frozen` IS THE WHOLE ANSWER TO "A FIELD PVE WILL NOT ACCEPT ON WRITE". Comparing one can only
+ *   plan an update that no write can satisfy: work reported on every run, forever.
+ */
+export const same = <T>(declared: T | undefined, live: T, frozen = false) =>
+  declared === undefined || frozen || declared === live;
+
+/**
+ * A declared autoscaler hint, or nothing when it is zero.
+ *
+ * ⚠️ A DECLARED ZERO IS "NO FLOOR, NO HINT", AND IT IS DELIBERATELY LEFT UNCOMPARED. REASONED, NOT
+ *   MEASURED: all four TB4 pools carry null for both `pg_num_min` and `target_size`, and finding
+ *   out for certain would mean writing to the cluster. Ceph CLEARS both when they are set to 0 and
+ *   `osd pool get all` then omits the key, which PVE reports as null and this pair reads as UNSET
+ *   — so a declared 0 would compare 0 against -1 on every plan, forever. Mapping 0 to UNSET
+ *   instead would be a guess in the OTHER direction, and wrong the same way if Ceph does report
+ *   the zero. Neither guess is made: a zero is still written, and then left unmanaged exactly like
+ *   an undeclared field.
+ */
+export const hint = (value: number | undefined) => (value === 0 ? undefined : value);
+
+/** One optional field, present in the form only when it was declared. */
+const field = (name: string, value: string | undefined): Record<string, string> =>
+  value === undefined ? {} : { [name]: value };
+
+/** ⚠️ Not named `digits`: `target_size_ratio` is a fraction, and `String` is right for both. */
+const numeric = (value: number | undefined) => (value === undefined ? undefined : String(value));
+
+/**
+ * The PUT body: everything POST and PUT both accept, `pg_num` excepted. `createBody` builds on it,
+ * the way storage.ts's `mutable` serves both of its forms. `name` is the path's last segment on an
+ * update and is not repeated here.
+ *
+ * ⚠️ SAFE TO RE-APPLY TO A POOL THAT ALREADY MATCHES, which reconcile relies on. MEASURED in
+ *   PVE::Ceph::Tools::set_pool (Tools.pm:293-300): it reads `osd pool get all` first and SKIPS
+ *   every setting whose value did not change, so re-sending the declared set costs one mon read.
+ * ⛔ BUT A SETTING THAT DID CHANGE AND CANNOT BE APPLIED KILLS THE WHOLE PUT. Tools.pm:310 dies
+ *   with "Could not set: <fields>" if any parameter is left unapplied, so a pool carrying Ceph's
+ *   `nosizechange` fails an entire update over one field. That is why the `no*` flags are reported
+ *   and why `matches` refuses to diff what they freeze.
+ *
+ * ⚠️ AN UNDECLARED FIELD IS NEITHER SENT NOR COMPARED — storage.ts's rule, and the opposite of
+ *   Proxmox.Pool's. Undeclared means UNMANAGED here, because a pool has no one set of defaults to
+ *   fall back on: PVE's POST fills in size 3, min_size 2, application rbd and pg_autoscale_mode
+ *   'warn' (MEASURED in createpool), while Ceph's own defaults — which is what every pool on TB4
+ *   was actually born with — put pg_autoscale_mode at 'on'. Guessing either set would rewrite a
+ *   pool somebody tuned by hand.
+ *
+ * ⛔ THERE IS NO `delete=` HERE AND THERE MUST NOT BE ONE. `setpool` is not a SectionConfig write:
+ *   it turns each parameter into an `osd pool set`, and Ceph has no "unset" for size, min_size or
+ *   crush_rule. metric-server-form.ts clears an undeclared optional because status.cfg supports
+ *   it; the same move here would send a parameter PVE has no verb for.
+ *
+ * ⚠️ `target_size` IS BYTES ON THE WIRE IN BOTH DIRECTIONS, WHICH IS WHY THE PROP IS A NUMBER AND
+ *   NOT PVE's `1T` STRING. MEASURED: the API parses the string with PVE::JSONSchema::parse_size
+ *   and stores Ceph's `target_size_bytes` (Pool.pm:474-477 for POST, 683-686 for PUT), and
+ *   `GET .../status` hands that integer back under the name `target_size` (Pool.pm:878). Run on
+ *   n2, `parse_size('1099511627776')` returns 1099511627776 — bare digits are bytes, no
+ *   multiplier — so a byte count survives the round trip exactly, while a declared `1T` would read
+ *   back as 1099511627776 and diff against itself on every plan, forever.
+ */
+export const updateBody = (props: CephPoolProps): Record<string, string> => ({
+  ...field('crush_rule', props.crush_rule),
+  ...field('min_size', numeric(props.min_size)),
+  ...field('pg_autoscale_mode', props.pg_autoscale_mode),
+  ...field('pg_num_min', numeric(props.pg_num_min)),
+  ...field('size', numeric(props.size)),
+  ...field('target_size', numeric(props.target_size)),
+  ...field('target_size_ratio', numeric(props.target_size_ratio)),
+});
+
+/**
+ * The POST body.
+ *
+ * ⛔ `add_storages=0` IS SENT EXPLICITLY RATHER THAN LEFT OUT, AND THE DEFAULT IS NOT WHAT IT LOOKS
+ *   LIKE. MEASURED at Pool.pm:481 — `$add_storages = 1 if $ec && !defined($add_storages)` — so for
+ *   an erasure-coded pool PVE turns it ON when the parameter is absent. A pool created with it
+ *   writes a NEW SECTION INTO storage.cfg that this graph does not own: `Proxmox.Storage` would
+ *   not know about it, `alchemy destroy` would leave it behind, and the first person to notice
+ *   would be whoever found a storage nobody declared.
+ */
+export const createBody = (props: CephPoolProps): Record<string, string> => ({
+  ...updateBody(props),
+  ...field('application', props.application),
+  ...field('pg_num', numeric(props.pg_num)),
+  add_storages: '0',
+  name: props.name,
+});

package/src/proxmox/ceph-pool-settle.ts

@@ -0,0 +1,70 @@
+/**
+ * Waiting for Ceph to finish, which is a concern of its own.
+ *
+ * ★ SPLIT OUT OF ceph-pool.ts FOR THE 250-LINE CAP, and the seam is real: every other PVE family
+ *   in this package writes and reads back in one breath, because PVE's config endpoints are
+ *   synchronous. Ceph's are not — a pool delete returns before the PGs are gone — so this file is
+ *   the polling that difference forces, and ceph-pool.ts is the declaration.
+ */
+import * as Effect from 'effect/Effect';
+import type { CephPoolAttributes, CephPoolProps } from './ceph-pool-form.ts';
+import { pve } from './client.ts';
+import type { PveRequirements } from './resource.ts';
+
+/**
+ * ⚠️ THE DEPENDENCIES ARE PASSED IN RATHER THAN IMPORTED, and that is what made this file
+ *   separable at all. `collection`, `object` and `ops.read` are module-level bindings in
+ *   ceph-pool.ts; importing them back would be a runtime cycle, and duplicating them would be two
+ *   definitions of one path. Passing them is the pattern zfs-pool-write.ts already uses.
+ */
+export type PoolRead = (
+  props: CephPoolProps,
+) => Effect.Effect<CephPoolAttributes | undefined, never, PveRequirements>;
+
+/**
+ * ⛔ THE GUARD ON THE CREATE. `read` folds a 403, a timeout and a node that is down into the same
+ *   `undefined` as a pool that is genuinely missing — so "absent" is not evidence. This asks a
+ *   second, different question: does the cluster LIST this pool? A failure is left to propagate
+ *   rather than folded, so "I could not ask" fails the deploy instead of creating over live data.
+ *   An empty list is trusted: the collection 403s when the role is too narrow rather than
+ *   filtering, so `[]` really does mean a cluster with no pools.
+ */
+export const confirmAbsent = (props: CephPoolProps, collection: string, describe: string) =>
+  pve<{ pool_name?: string }[]>(props.target, 'read', 'GET', collection).pipe(
+    Effect.flatMap((rows) =>
+      (rows ?? []).some((row) => row.pool_name === props.name)
+        ? Effect.die(
+            new Error(
+              `${describe}: the cluster lists this pool but its status could not be read, ` +
+                'so this deploy will NOT create over it. Check that the node is up and that the ' +
+                'read role holds Sys.Audit or Datastore.Audit on / -- a create here would apply ' +
+                'pg_num to a live pool and start a PG merge.',
+            ),
+          )
+        : Effect.void,
+    ),
+  );
+
+/**
+ * Wait for the cluster to agree, then answer the last thing it said.
+ *
+ * ★ IT POLLS `matches`, THE SAME PREDICATE `diff` USES, so "settled" has exactly one definition in
+ *   this file. Polling `/nodes/{node}/tasks/{upid}/status` instead would read the worker's own
+ *   exit status, but it needs `Sys.Audit` on the node for a token that is NOT the one that started
+ *   the task — every `pve` call mints a fresh token, so the task's owner check cannot pass.
+ * ⚠️ SHORT POLLS, LOW CAP: 2s apart, 30 tries, about a minute. A pool create takes seconds; one
+ *   still unsettled after a minute is a fault to surface, not a wait to lengthen.
+ */
+export const settle = (
+  props: CephPoolProps,
+  read: PoolRead,
+  done: (live: CephPoolAttributes | undefined) => boolean,
+) =>
+  Effect.gen(function* () {
+    for (let attempt = 0; attempt < 30; attempt += 1) {
+      const live = yield* read(props);
+      if (done(live)) return live;
+      yield* Effect.sleep('2 seconds');
+    }
+    return yield* read(props);
+  });