@homeflare/alchemy 0.42.0 → 0.44.0

package/src/postgres/schema.ts

@@ -0,0 +1,130 @@
+/**
+ * `Postgres.Schema` — create-and-assert over one schema in a self-hosted PostgreSQL 18 cluster.
+ *
+ * ★ A SCHEMA CARRIES NO OWNERSHIP MARK, exactly like `Postgres.Database` (H1). `read` answers
+ *   `Unowned` for a match, so every already-live schema needs `adopt(true)` in the stack that
+ *   declares it.
+ * ⛔ NOT ALTER-CAPABLE. `ALTER SCHEMA` only renames or changes owner in Postgres; neither is
+ *   implemented. An owner or comment mismatch against the live row is a typed
+ *   `PostgresSchemaDrift` refusal, never an `ALTER SCHEMA` — same rule `Postgres.Database`
+ *   applies to its own asserted props. An omitted `owner` is compared to `current_user`
+ *   (`schema-assert.ts`): a fresh create without `AUTHORIZATION` would be owned by that role.
+ * ⛔ THE DECLARED `database` IS PROVEN, NEVER ASSUMED. The family connection points at a
+ *   maintenance database (a brand-new database cannot be connected to on a cold plan —
+ *   `docs/postgres.md#measured-path`), so the handlers below open `props.database` themselves
+ *   (`withPg`'s database override) and `reconcile`/`drop` first compare `current_database()`
+ *   against it (`PostgresSchemaWrongDatabase`). Without that proof a seat's schema would be
+ *   created in whatever database the single connection happened to target.
+ * ⛔ `delete` DROPS ONLY WHAT IT CAN PROVE IT CREATED. Before any `DROP`, the handler re-reads
+ *   the live row (`schema-delete.ts`) and matches it against the persisted `oid` + `owner`;
+ *   a mismatch is `PostgresSchemaDeleteForeignRefused`, never a `DROP` (`CASCADE` included) —
+ *   the schema under that name may be another role's, recreated out of band.
+ * ⛔ A MISSING DECLARED DATABASE IS "SCHEMA ABSENT" IN `read` AND `delete`. Both probe
+ *   `pg_database` over the family connection first (`database-sql.ts#databaseExists`), so a
+ *   cold plan against a not-yet-created database plans a create (`read` answers absent)
+ *   instead of failing untyped on connect (`ConnectionError` over psql, `UnknownError` 3D000
+ *   over the socket), and a delete of a dropped database stays idempotent. `reconcile` still
+ *   requires the database to exist — that ordering is the declaration's job (`docs/
+ *   postgres-schema.md`: pass `database: db.name`).
+ * ⛔ `delete` DROPS ONLY WHEN SAFE. `DROP SCHEMA` refuses a non-empty schema unless
+ *   `cascade: true` is declared (`PostgresSchemaDropNotEmptyError`); the `cascade` prop
+ *   defaults to `false` (retain policy by default — see `defaultRemovalPolicy: 'retain'`).
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { type PostgresSchemaAttributes, type PostgresSchemaProps } from './schema-attrs.ts';
+import { schemaNameByteRefusal } from './schema-attrs.ts';
+import { diffPostgresSchema } from './schema-diff.ts';
+import { selectSchema } from './schema-sql.ts';
+import { databaseExists } from './database-sql.ts';
+import { reconcileWithClient } from './schema-reconcile.ts';
+import { assertSchemaIdentity, assertSchemaTarget } from './schema-identity.ts';
+import { deleteWithClient, dropWithClient } from './schema-delete.ts';
+import type { PgExecutor } from './database-sql.ts';
+import { type PostgresConnection, withPg } from './connection.ts';
+import { PostgresSchemaNameRefused, PostgresSchemaWrongDatabase } from './schema-errors.ts';
+
+export interface PostgresSchema extends Resource<
+  'Postgres.Schema',
+  PostgresSchemaProps,
+  PostgresSchemaAttributes,
+  never,
+  PostgresConnection
+> {}
+
+export const PostgresSchema = Resource<PostgresSchema>('Postgres.Schema', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** Same dual `typeof` guard as `isPostgresDatabase` (see `database.ts`): a resource constructor
+ * is a callable `Object.assign`ed function, not a plain object. */
+export const isPostgresSchema = (value: unknown): value is PostgresSchema =>
+  (typeof value === 'object' || typeof value === 'function') &&
+  value !== null &&
+  (value as { Type?: unknown }).Type === 'Postgres.Schema';
+
+/** The core of `read`: one bound `SELECT`, no ownership branding. */
+export const readWithClient = (pg: PgExecutor, name: string) => selectSchema(pg, name);
+
+export { diffPostgresSchema } from './schema-diff.ts';
+export { reconcileWithClient } from './schema-reconcile.ts';
+export { deleteWithClient, dropWithClient };
+
+/** The five lifecycle handlers. Exported on its own so a test drives the real implementation. */
+export const postgresSchemaHandlers = PostgresSchema.Provider.of({
+  // ⚠️ EMPTY, NOT A LIVE SWEEP — same reasoning as Postgres.Database's list.
+  list: () => Effect.succeed([]),
+  nuke: { skip: true },
+
+  read: ({ olds, output }) =>
+    Effect.gen(function* () {
+      const name = output?.name ?? olds.name;
+      const database = output?.database ?? olds.database;
+      // A declared database that does not exist IS a schema absent. The probe runs over the
+      // FAMILY connection (no override), which points at the maintenance database a cold plan
+      // can always reach — opening the declared database instead would fail untyped
+      // (`ConnectionError` over psql, `UnknownError` 3D000 over the socket).
+      const present = yield* withPg((pg) => databaseExists(pg, database));
+      if (!present) return undefined;
+      const live = yield* withPg((pg) => readWithClient(pg, name), database);
+      if (live !== undefined && live.database !== database) {
+        return yield* Effect.fail(
+          new PostgresSchemaWrongDatabase({
+            schema: name,
+            declared: database,
+            connected: live.database,
+          }),
+        );
+      }
+      if (live !== undefined && output !== undefined) yield* assertSchemaIdentity(live, output);
+      return live === undefined ? undefined : Unowned(live);
+    }),
+
+  diff: ({ news, output, olds }) => diffPostgresSchema(news, output, olds),
+
+  reconcile: ({ news, output }) =>
+    Effect.gen(function* () {
+      const nameRefusal = schemaNameByteRefusal(news.name);
+      if (nameRefusal !== undefined) {
+        return yield* Effect.fail(
+          new PostgresSchemaNameRefused({ name: news.name, ...nameRefusal }),
+        );
+      }
+      yield* assertSchemaTarget(news, output);
+      return yield* withPg((pg) => reconcileWithClient(pg, news, output), news.database);
+    }),
+
+  delete: ({ olds, output }) =>
+    Effect.gen(function* () {
+      // Same missing-database rule as `read`: an absent database is an absent schema, and the
+      // delete stays idempotent instead of failing untyped on connect.
+      const present = yield* withPg((pg) => databaseExists(pg, olds.database));
+      if (!present) return undefined;
+      return yield* withPg((pg) => deleteWithClient(pg, olds, output), olds.database);
+    }),
+});
+
+export const PostgresSchemaProvider = () =>
+  Provider.succeed(PostgresSchema, postgresSchemaHandlers);

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(