@homeflare/alchemy 0.42.0 → 0.43.0

package/src/postgres/psql-executor.ts

@@ -0,0 +1,130 @@
+/**
+ * A `PgExecutor` that runs SQL through a caller-supplied command runner instead of a socket.
+ *
+ * For a host whose Postgres listens on loopback only inside a container (CT100: rootful podman
+ * container `postgres`, local socket, user `postgres`, no password): the consumer's runner is
+ * `ssh <host> sudo -n podman exec -i postgres <argv…>`, and this file only builds the `psql`
+ * argv and stdin and parses the answer.
+ *
+ * ⛔ NO ESTATE VALUE LIVES HERE (public kit). The ssh destination, container name and sudo
+ *   allowlist are the runner's, in the consuming stack.
+ * ⛔ `psql` HAS NO BIND PARAMETERS OVER STDIN. Every `$n` is replaced by a `quoteStringLiteral`
+ *   literal, and ONLY string params are accepted — this family binds a database or role name,
+ *   nothing else — so a number or object is a refusal, never silently stringified.
+ * ★ ROWS COME BACK AS JSON: a `SELECT` is wrapped in `json_agg`, so `oid` and `datconnlimit`
+ *   arrive as JS numbers exactly as the socket client decodes them (database-sql.ts, no bigint).
+ * ★ `VERBOSITY=verbose` puts the SQLSTATE in the error line, so `42P04` (duplicate database)
+ *   stays recognisable to `isDuplicateDatabaseRace`.
+ */
+import * as Effect from 'effect/Effect';
+import {
+  ConnectionError,
+  SqlError,
+  SqlSyntaxError,
+  UnknownError,
+} from 'effect/unstable/sql/SqlError';
+import { type PgExecutor, quoteStringLiteral } from './database-sql.ts';
+
+export interface PsqlResult {
+  readonly code: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/** Runs one `psql` argv (starting with `psql`) with `stdin` and answers its exit. The consumer's
+ * implementation prepends the transport (`ssh … sudo -n podman exec -i <container>`) and owns
+ * the timeout and output bound: the kit sets neither. */
+export type PsqlRunner = (call: {
+  readonly argv: readonly string[];
+  readonly stdin: string;
+}) => Promise<PsqlResult>;
+
+export interface PsqlTarget {
+  readonly database: string;
+  readonly username: string;
+}
+
+/** Replace `$1…$n` with string literals; refuses a non-string param or a missing one. */
+export const inlineParams = (sql: string, params: ReadonlyArray<unknown>): string =>
+  params.length === 0
+    ? sql
+    : sql.replace(/\$(\d+)/g, (_match, index: string) => {
+        const value = params[Number(index) - 1];
+        if (typeof value !== 'string') {
+          throw new Error(`psql executor: param $${index} must be a string, got ${typeof value}`);
+        }
+        return quoteStringLiteral(value);
+      });
+
+/** Postgres `to_json` emits the `oid` type as a string; the socket driver returns a number. */
+const normalizeRow = (row: unknown): unknown =>
+  typeof row === 'object' && row !== null && typeof (row as { oid?: unknown }).oid === 'string'
+    ? { ...row, oid: Number((row as { oid: string }).oid) }
+    : row;
+
+const isSelect = (sql: string): boolean => /^\s*SELECT\b/i.test(sql);
+
+const wrapRows = (sql: string): string =>
+  `SELECT coalesce(json_agg(t), '[]'::json)::text FROM (${sql}) t;`;
+
+const failure = (operation: string, result: PsqlResult): SqlError => {
+  const state = /ERROR:\s+([0-9A-Z]{5}):/.exec(result.stderr)?.[1];
+  const fields = {
+    cause: Object.assign(
+      new Error(result.stderr.trim()),
+      state === undefined ? {} : { code: state },
+    ),
+    message: result.stderr.trim(),
+    operation,
+  };
+  const reason =
+    state === undefined
+      ? new ConnectionError(fields)
+      : state.startsWith('42')
+        ? new SqlSyntaxError(fields)
+        : new UnknownError(fields);
+  return new SqlError({ reason });
+};
+
+export const makePsqlExecutor = (run: PsqlRunner, target: PsqlTarget): PgExecutor => ({
+  unsafe: <A extends object>(sql: string, params: ReadonlyArray<unknown> = []) =>
+    Effect.gen(function* () {
+      const inlined = yield* Effect.try({
+        try: () => inlineParams(sql, params),
+        catch: (cause) =>
+          new SqlError({ reason: new UnknownError({ cause, operation: 'psql inline params' }) }),
+      });
+      const rows = isSelect(inlined);
+      const result = yield* Effect.tryPromise({
+        try: () =>
+          run({
+            argv: [
+              'psql',
+              '-X',
+              '-q',
+              '-A',
+              '-t',
+              '-v',
+              'ON_ERROR_STOP=1',
+              '-v',
+              'VERBOSITY=verbose',
+              '-U',
+              target.username,
+              '-d',
+              target.database,
+            ],
+            stdin: rows ? wrapRows(inlined) : `${inlined};`,
+          }),
+        catch: (cause) =>
+          new SqlError({ reason: new ConnectionError({ cause, operation: 'psql exec' }) }),
+      });
+      if (result.code !== 0) return yield* Effect.fail(failure(inlined.slice(0, 40), result));
+      if (!rows) return [] as ReadonlyArray<A>;
+      const parsed = yield* Effect.try({
+        try: () => (JSON.parse(result.stdout.trim() || '[]') as unknown[]).map(normalizeRow),
+        catch: (cause) =>
+          new SqlError({ reason: new UnknownError({ cause, operation: 'psql parse output' }) }),
+      });
+      return parsed as ReadonlyArray<A>;
+    }),
+});

package/src/proxmox/ceph-flag-types.ts

@@ -0,0 +1,70 @@
+/**
+ * Flag names, props and attributes for `Proxmox.CephFlag`.
+ *
+ * ★ SPLIT OUT OF ceph-flag.ts FOR THE 250-LINE CAP. The comments stay with the types they
+ *   explain; nothing here talks to the cluster.
+ */
+import type { WithTarget } from './resource-spec.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 C1:
+ *   `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;
+}

package/src/proxmox/ceph-flag-wire.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Pins the two Opus findings on the CephFlag transport (kit PR 319, 2026-09-28).
+ *
+ * 1. A `{"data":null}` body becomes `{}` inside distilled's `transformResponse` before the
+ *    provider sees it. Guarding only `null`/`undefined` lets `bool({})` read a missing answer
+ *    as "flag clear".
+ * 2. A refused mint must not fail `diff`. Alchemy fails the whole plan if one resource's
+ *    `diff` fails (unreadable-read.ts).
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { engineOver } from '../verify/fake-engine.ts';
+import { scalarFlagOrDie } from './ceph-flag-wire.ts';
+import { ProxmoxCephFlag, ProxmoxCephFlagProvider } from './ceph-flag.ts';
+import { FAKE_TARGET, withoutBao } from './fake-pve.ts';
+
+const flagProps = { flag: 'noout' as const, target: FAKE_TARGET, value: true };
+
+describe('CephFlag GET of no data dies instead of reading clear', () => {
+  test('the post-transform empty object dies', async () => {
+    // distilled protocol.ts maps `{"data":null}` to `{}` before a RawResponseRoot decode.
+    await expect(Effect.runPromise(scalarFlagOrDie({}, flagProps))).rejects.toThrow(
+      /not a bare boolean/,
+    );
+    await expect(Effect.runPromise(scalarFlagOrDie(null, flagProps))).rejects.toThrow(
+      /not a bare boolean/,
+    );
+  });
+
+  test('a real scalar still decodes', async () => {
+    expect(await Effect.runPromise(scalarFlagOrDie(1, flagProps))).toBe(1);
+    expect(await Effect.runPromise(scalarFlagOrDie(false, flagProps))).toBe(false);
+  });
+});
+
+describe('a refused CephFlag read does not abort the plan', () => {
+  test('verify after a 403 mint reports noop, not a failed plan', async () => {
+    let refuse = false;
+    const stub = async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+      const request =
+        input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+      const url = new URL(request.url);
+      if (url.pathname.includes('/creds/')) {
+        if (refuse) {
+          return Response.json({ errors: ['status 403'] }, { status: 403 });
+        }
+        return Response.json({
+          data: { secret: 'fake-secret-not-real', token_id: 'hf-test@pve!fake' },
+          lease_duration: 0,
+        });
+      }
+      return Response.json({ data: 1 });
+    };
+    const layer = FetchHttpClient.layer.pipe(
+      Layer.provideMerge(
+        Layer.succeed(
+          FetchHttpClient.Fetch,
+          Object.assign(stub, { preconnect: globalThis.fetch.preconnect }) as typeof fetch,
+        ),
+      ),
+    );
+    const declare = () => ProxmoxCephFlag('noout', flagProps);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxCephFlagProvider().pipe(Layer.provideMerge(layer)));
+      expect(await engine.deploy(declare())).toEqual({ noout: 'adopted' });
+      refuse = true;
+      await expect(engine.verify(declare(), { all: true })).resolves.toBeDefined();
+    });
+  });
+});

package/src/proxmox/ceph-flag-wire.ts

@@ -0,0 +1,123 @@
+/**
+ * `Proxmox.CephFlag`'s distilled wire lane: the read and the single-flag write.
+ *
+ * ★ SPLIT OUT OF ceph-flag.ts FOR THE 250-LINE CAP, mirroring ceph-pool-wire.ts's split by "touches
+ *   the cluster or not" — ceph-flag.ts keeps the header, the props/attributes shapes, `matches` and
+ *   the provider wiring; this file is the only place that calls `runPve` for this family.
+ *
+ * ⛔ NEITHER OPERATION HERE DECLARES A TYPED ABSENCE (`errors: []` on both `getClusterCephFlag` and
+ *   `putClusterCephFlag`, MEASURED in distilled-proxmox/src/services/cluster.ts) — UNLIKE
+ *   ceph-pool-wire.ts's `CephPoolNotFound`. All eleven flags always exist (ceph-flag.ts's own ⛔ on
+ *   `CephFlagName` and on the old unreachable create branch), so there is no absence case to fold
+ *   here. `readClusterCephFlag` therefore has no `catchTag` at all and lets every failure — a
+ *   refused credential, a timeout, cluster exhaustion — propagate to the caller exactly as it
+ *   arrived, rather than inventing an "absent" this family does not have. Simpler than
+ *   ceph-pool-wire.ts's case, not harder.
+ *   ⚠️ THIS IS A BEHAVIOR CHANGE FROM THE PRE-MIGRATION FACTORY, AND A DELIBERATE ONE. The old
+ *     `pveOperations.read` folded EVERY failure into `undefined` via `Effect.orElseSucceed`, so an
+ *     expired lease or node-b being down looked identical to "the flag is absent" (which cannot
+ *     happen — see ceph-flag.ts). Now such a failure propagates as itself: a caller sees the real
+ *     error (an expired 300s lease, node-b down, ceph not configured) rather than a misleading
+ *     "absent" that would have sent `diff`/`reconcile` down a create path this endpoint has never
+ *     implemented. Same advice as the old comment gave, sharper because the failure is no longer
+ *     disguised.
+ *
+ * ⛔ THE PER-FLAG PUT IS SYNCHRONOUS (`$rados->mon_command` inline, MEASURED in Ceph.pm — see
+ *   ceph-flag.ts's header), which is what makes reading back immediately after
+ *   `writeClusterCephFlag` fair rather than a race against a worker task, unlike ceph-pool.ts's
+ *   forked-worker writes.
+ */
+import * as cluster from '@distilled.cloud/proxmox/cluster';
+import * as Effect from 'effect/Effect';
+import type { CephFlagAttributes, CephFlagProps } from './ceph-flag.ts';
+import { runPve } from './distilled-pve.ts';
+import { readOrUnreadable } from './unreadable-read.ts';
+import { bool, flag } from './values.ts';
+
+/** The one endpoint this family writes, as `guardWrite` (distilled-guard.ts) keys it. */
+export const CEPH_FLAG_UPDATE = 'pve:PUT /cluster/ceph/flags/{flag}';
+
+/**
+ * ⚠️ `live` IS A BARE BOOLEAN HERE, NOT AN OBJECT, AND IT IS HANDED TO `bool` WHOLE ON PURPOSE.
+ *   `get_flag` returns perl `1` or `0` under a `type => 'boolean'` return schema, so the wire is
+ *   `{"data":0}` or `{"data":false}` depending on how the REST layer renders it — matching
+ *   distilled's `GetClusterCephFlagResponse = unknown` (`S.Unknown.pipe(T.RawResponseRoot())`).
+ *   `bool` accepts every one of those spellings, which is exactly why it is a shared coercion.
+ *   ⚠️ THE SCALAR IS A MEASURED PROPERTY OF THIS PVE, NOT A PROMISE. A later version wrapping the
+ *     answer in an object would make `bool` read a SET flag as false, and `value: false` would then
+ *     plan `noop` over a live flag — silently. Re-measure `GET /cluster/ceph/flags/noout` after a
+ *     major upgrade; cheaper than a second parse path.
+ */
+const attributesOf = (live: unknown, props: CephFlagProps): CephFlagAttributes => ({
+  flag: props.flag,
+  value: bool(live),
+});
+
+/**
+ * ⛔ DIE ON THE POST-TRANSFORM SHAPE, NOT THE PRE-TRANSFORM ONE. `bool` treats a missing value as
+ *   `false` because most callers hand it an optional PVE form field where that is correct — but
+ *   here it would read an unmeasured "no answer" as "flag is clear". distilled's
+ *   `transformResponse` maps a `{"data":null}` body to `{}` BEFORE this function sees it (a shape
+ *   `get_flag`'s `type => 'boolean'` schema does not document and this PVE has never produced).
+ *   Guarding only `null`/`undefined` lets that `{}` through, and `bool({})` is `false` — a plan
+ *   of `noop` over a set brake, with no read-back guard, because `reconcile`'s guard only fires
+ *   on a write. A success here is a scalar (`true`/`false`/`0`/`1`/`'0'`/`'1'`). Anything else,
+ *   including the empty object the protocol substitutes for null, is the unmeasured shape.
+ */
+export const scalarFlagOrDie = (live: unknown, props: CephFlagProps) => {
+  const scalar =
+    typeof live === 'boolean' || live === 0 || live === 1 || live === '0' || live === '1';
+  return scalar
+    ? Effect.succeed(live)
+    : Effect.die(
+        new Error(
+          `cluster/ceph/flags/${props.flag}: GET answered ${JSON.stringify(live)}, not a bare ` +
+            "boolean. This endpoint's success is a scalar; an empty object is what the protocol " +
+            'substitutes for `{"data":null}`. Check `ceph osd dump | head -1` and the cluster ' +
+            'log rather than trust a coerced `false`.',
+        ),
+      );
+};
+
+/**
+ * The live flag, as attributes.
+ *
+ * ⚠️ NO ABSENCE TAG, ON PURPOSE. Both operations declare `errors: []` (see the file header), so
+ *   there is nothing to `catchTag` except `PveCredentialDenied`, and that one is caught by the
+ *   caller that plans (`readClusterCephFlagForDiff`) — not here. `read` and `reconcile` must
+ *   still see a refused mint as itself.
+ */
+export const readClusterCephFlag = (props: CephFlagProps) =>
+  runPve(props.target, 'read', false, cluster.getClusterCephFlag({ flag: props.flag })).pipe(
+    Effect.flatMap((live) => scalarFlagOrDie(live, props)),
+    Effect.map((live) => attributesOf(live, props)),
+  );
+
+/**
+ * The same read, with a refused mint turned into `UNREADABLE`.
+ *
+ * ⛔ `diff` MUST NOT FAIL ON A REFUSED READ. Alchemy runs every resource's `diff` under
+ *   `Effect.exit` and fails the whole plan if one fails (unreadable-read.ts). A lane that cannot
+ *   mint `read` would otherwise abort every other row, not just this flag. `read` and
+ *   `reconcile` keep the propagating form above.
+ */
+export const readClusterCephFlagForDiff = (props: CephFlagProps) =>
+  readOrUnreadable(readClusterCephFlag(props));
+
+/**
+ * ⚠️ ONLY `value` GOES IN THE BODY. `flag` is already bound by the path and the PUT declares
+ *   `additionalProperties => 0`, so a second copy in the form could only disagree with the URL.
+ * ⚠️ THE `?? '0'` IS UNREACHABLE, AND IS WRITTEN RATHER THAN CAST AWAY. `flag()` types its answer
+ *   `string | undefined` because it serves OPTIONAL props, and `value` here is required, so the
+ *   branch cannot be taken; a cast would claim a proof the type system has not made.
+ */
+export const updateForm = (props: CephFlagProps) => ({ value: flag(props.value) ?? '0' });
+
+/** The actual `putClusterCephFlag` call — `updateForm`'s own `value`, so the two cannot disagree. */
+export const writeClusterCephFlag = (props: CephFlagProps) =>
+  runPve(
+    props.target,
+    'provision',
+    true,
+    cluster.putClusterCephFlag({ flag: props.flag, value: updateForm(props).value }),
+  );

package/src/proxmox/ceph-flag.ts

@@ -73,73 +73,24 @@
  *     "Permission check failed (/, Sys.Modify)" on the first deploy, and widen deliberately.
  */
 import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
-import { bool, flag } from './values.ts';
+import {
+  CEPH_FLAG_UPDATE,
+  readClusterCephFlag,
+  readClusterCephFlagForDiff,
+  updateForm,
+  writeClusterCephFlag,
+} from './ceph-flag-wire.ts';
+import { mintTier } from './credentials.ts';
+import { UNREADABLE, unreadableWarning } from './unreadable-read.ts';
+import { guardWrite } from './distilled-guard.ts';
+import type { CephFlagAttributes, CephFlagProps } from './ceph-flag-types.ts';
+import type { PveRequirements } from './resource-spec.ts';
+import { formToSend } from './update-guard.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 C1:
- *   `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 type { CephFlagAttributes, CephFlagName, CephFlagProps } from './ceph-flag-types.ts';
 
 export interface ProxmoxCephFlag extends Resource<
   'Proxmox.CephFlag',
@@ -151,86 +102,82 @@ export interface ProxmoxCephFlag extends Resource<
 
 export const ProxmoxCephFlag = Resource<ProxmoxCephFlag>('Proxmox.CephFlag');
 
-const handlers = pveHandlers<CephFlagProps, CephFlagAttributes>({
-  /**
-   * ⚠️ `live` IS A BARE BOOLEAN HERE, NOT AN OBJECT, AND IT IS HANDED TO `bool` WHOLE ON PURPOSE.
-   *   `get_flag` returns perl `1` or `0` under a `type => 'boolean'` return schema, so the wire is
-   *   `{"data":0}` or `{"data":false}` depending on how the REST layer renders it. `bool` accepts
-   *   every one of those spellings, which is exactly why it is a shared coercion. The factory
-   *   types this parameter `Record<string, unknown>` because every OTHER PVE read is an object;
-   *   reaching for `live['value']` here would answer undefined on every plan and diff `false`
-   *   forever against a set flag.
-   *   ⚠️ THE SCALAR IS A MEASURED PROPERTY OF THIS PVE, NOT A PROMISE. A later version wrapping
-   *     the answer in an object would make `bool` read a SET flag as false, and `value: false`
-   *     would then plan `noop` over a live flag — silently. Re-measure
-   *     `GET /cluster/ceph/flags/noout` after a major upgrade; cheaper than a second parse path.
-   *
-   * ⛔ IT NEVER ANSWERS undefined, WHICH MAKES THE CREATE BRANCH UNREACHABLE, AND ITS ERROR WILL
-   *   MISLEAD YOU. All eleven flags always exist; there is nothing for "absent" to mean. So a POST
-   *   to `collection` means the READ failed — an expired 300s lease, node-b down, or ceph simply not
-   *   configured on the cluster (every one of these four handlers opens with
-   *   `check_ceph_configured()`, which dies). Read the resulting "Method 'POST /cluster/ceph/flags'
-   *   not implemented" as "the read failed" and go and look at the credential, not at ceph. Same
-   *   shape as the unreachable POST in acl.ts, same advice.
-   */
-  attributes: (live, props) => ({ flag: props.flag, value: bool(live) }),
-  collection: () => 'cluster/ceph/flags',
-  /**
-   * ⛔ UNREACHABLE — see the second ⛔ in `attributes`. It is written in the BULK endpoint's shape
-   *   (the flag name is the parameter, not `value`) rather than left empty, because that is the
-   *   only body `cluster/ceph/flags` has ever documented. Nothing sends it today.
-   */
-  createForm: (props) => ({ [props.flag]: flag(props.value) ?? '0' }),
-  endpoint: { update: 'pve:PUT /cluster/ceph/flags/{flag}' }, // ⛔ No create: see above.
-  /**
-   * ⚠️ `value` IS THE ONLY THING COMPARED, AND THE LIST OF THINGS DELIBERATELY NOT COMPARED IS THE
-   *   point of this resource. `flag` is props-derived (see `CephFlagAttributes`). `description`
-   *   and `name` exist only on the bulk GET, which this file does not read, so neither can be
-   *   compared by accident. Nothing PVE returns here is rewritten, re-ordered or re-typed by the
-   *   cluster, because all PVE returns here is one boolean.
-   *   ★ MEASURED: on C1, `GET /cluster/ceph/flags` answers value 0 for all eleven flags, so a
-   *     declaration of `value: false` reads back false and plans `noop`.
-   */
-  matches: (attributes, props) => attributes.value === props.value,
-  path: (props) => `cluster/ceph/flags/${props.flag}`,
-  /**
-   * ⚠️ ONLY `value` GOES IN THE BODY. `flag` is already bound by the path and the PUT declares
-   *   `additionalProperties => 0`, so a second copy in the form could only disagree with the URL.
-   * ⚠️ THE `?? '0'` IS UNREACHABLE, AND IS WRITTEN RATHER THAN CAST AWAY. `flag()` types its
-   *   answer `string | undefined` because it serves OPTIONAL props, and `value` here is required,
-   *   so the branch cannot be taken; a cast would claim a proof the type system has not made.
-   */
-  updateForm: (props) => ({ value: flag(props.value) ?? '0' }),
-});
+/**
+ * ⚠️ `value` IS THE ONLY THING COMPARED, AND THE LIST OF THINGS DELIBERATELY NOT COMPARED IS THE
+ *   point of this resource. `flag` is props-derived (see `CephFlagAttributes`). `description`
+ *   and `name` exist only on the bulk GET, which this file does not read, so neither can be
+ *   compared by accident. Nothing PVE returns here is rewritten, re-ordered or re-typed by the
+ *   cluster, because all PVE returns here is one boolean.
+ *   ★ MEASURED: on C1, `GET /cluster/ceph/flags` answers value 0 for all eleven flags, so a
+ *     declaration of `value: false` reads back false and plans `noop`.
+ */
+const matches = (attributes: CephFlagAttributes, props: CephFlagProps) =>
+  attributes.value === props.value;
 
+/**
+ * ★ MIGRATED OFF `pveHandlers`/`client.ts`'s generic `pve()` ONTO `@distilled.cloud/proxmox`'s
+ *   typed `cluster.getClusterCephFlag`/`cluster.putClusterCephFlag` (ceph-flag-wire.ts).
+ *   `pveHandlers` cannot run a distilled operation, so `diff`/`reconcile` are hand-written here,
+ *   the same way ceph-pool.ts and backup-job.ts hand-write theirs for the same reason.
+ *
+ * ⛔ THIS FAMILY HAS NO CREATE KEY, AND THAT IS THE VENDOR'S DOING, NOT AN OMISSION HERE. PVE
+ *   registers only `PUT /cluster/ceph/flags/{flag}`; `POST /cluster/ceph/flags` does not exist
+ *   (constraints-forms.test.ts's own regression test), which is why the second ⛔ in the header
+ *   above calls the create branch unreachable — there is no create form and no create endpoint to
+ *   guard, only `CEPH_FLAG_UPDATE`.
+ */
 export const ProxmoxCephFlagProvider = () =>
   Provider.effect(
     ProxmoxCephFlag,
     Effect.succeed(
       ProxmoxCephFlag.Provider.of({
-        /**
-         * ⚠️ NOT THE ONE-LINE `Provider.of(handlers)` EVERY OTHER FILE HERE USES, AND THE TWO
-         *   REASONS ARE BOTH acl.ts's. PVE implements no DELETE on this path, and the factory's
-         *   read-back guard is dead whenever `attributes` cannot answer undefined. Unlike acl.ts
-         *   this SPREADS the factory's handlers instead of retyping them, so `list`, `read` and
-         *   `diff` cannot drift from the shared ones — only the two that genuinely differ are
-         *   written out below.
-         */
-        ...handlers,
+        /** ⛔ Empty, like every resource in this package — see resource.ts's own ⚠️ on why. */
+        list: () => Effect.succeed([]),
+        read: ({ olds }) => readClusterCephFlag(olds),
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          yield* guardWrite(CEPH_FLAG_UPDATE, updateForm(news), false);
+          if (output === undefined) return undefined;
+          // ⛔ Never absent — see the second ⛔ above. A failed read other than a refused mint
+          //   propagates instead of reaching this point. A refused mint must NOT fail `diff`:
+          //   that aborts the whole plan (unreadable-read.ts). `read` still propagates.
+          const live = yield* readClusterCephFlagForDiff(news);
+          if (live === UNREADABLE) {
+            yield* unreadableWarning(
+              'Proxmox.CephFlag',
+              news.flag,
+              news.target.mount,
+              mintTier(news.target, 'read'),
+            );
+            return { action: 'noop' } as const;
+          }
+          return { action: matches(live, news) ? 'noop' : 'update' } as const;
+        }),
         /** ⛔ Inert, deliberately. The third ⛔ in the header is the whole argument; read it. */
         delete: () => Effect.void,
         /**
-         * ⚠️ THE READ-BACK GUARD, RESTORED FOR A FAMILY WHOSE "ABSENT" DOES NOT EXIST.
-         *   `ops.reconcile` refuses when the object is still missing after a write, and a flag is
-         *   never missing, so that check can never fire here — exactly the hole acl.ts patches
-         *   with `bound`. PVE answers 200 with `{"data":null}` on calls that did nothing, and this
-         *   PUT's documented return IS null, so the status code carries no evidence at all.
+         * ⚠️ THE READ-BACK GUARD, RESTORED FOR A FAMILY WHOSE "ABSENT" DOES NOT EXIST. A generic
+         *   `reconcile` (resource.ts) refuses when the object is still missing after a write, and
+         *   a flag is never missing, so that check could never fire here. PVE answers 200 with
+         *   `{"data":null}` on calls that did nothing, and this PUT's documented return IS null,
+         *   so the status code carries no evidence at all — only a read-back does.
          * ⚠️ THE PER-FLAG PUT IS SYNCHRONOUS (`$rados->mon_command` inline, MEASURED in Ceph.pm),
          *   which is what makes this check fair rather than a race against a worker task. If it
          *   ever fires spuriously the honest fix is to look at the mon, not to delete the guard.
+         * ⛔ `formToSend` IS WHAT MAKES ADOPTING AN ALREADY-MATCHING FLAG FREE. Alchemy's
+         *   `adopted` action reaches `reconcile` exactly like `update` does (resource.ts's own ⛔
+         *   on this), so without this guard adopting a flag that already reads correctly would
+         *   still fire a PUT — pointless against ceph, and update-guard.ts's header has the
+         *   incident where the equivalent gap on CephPool forked an unnecessary worker.
          */
         reconcile: Effect.fn(function* ({ news }) {
-          const after = yield* handlers.reconcile({ news });
+          const live = yield* readClusterCephFlag(news);
+          const form = formToSend(matches, live, news, updateForm(news));
+          if (form !== undefined) {
+            yield* guardWrite(CEPH_FLAG_UPDATE, updateForm(news), false);
+            yield* writeClusterCephFlag(news);
+          }
+          const after = yield* readClusterCephFlag(news);
           if (after.value !== news.value) {
             return yield* Effect.die(
               new Error(