@homeflare/alchemy 0.41.0 → 0.43.0

package/src/postgres/providers.ts

@@ -9,8 +9,21 @@
  *   the results under whatever logical grouping it wants.
  */
 import * as Layer from 'effect/Layer';
-import { type PostgresConnectionConfig, postgresConnection } from './connection.ts';
+import {
+  type PostgresConnectionConfig,
+  type PostgresRunnerConfig,
+  postgresConnection,
+  postgresRunnerConnection,
+} from './connection.ts';
 import { PostgresDatabaseProvider } from './database.ts';
 
+// ⚠️ `Layer.provideMerge`, NEVER plain `Layer.provide`: the handlers' `withPg` reads
+//   `PostgresConnection` when the ENGINE later calls `read`/`reconcile`, and plain `provide`
+//   seals it away ("Service not found: Postgres.Connection" — measured for `caddyProviders`,
+//   see `caddy/providers.ts`).
 export const postgresProviders = (config: PostgresConnectionConfig) =>
-  PostgresDatabaseProvider().pipe(Layer.provide(postgresConnection(config)));
+  PostgresDatabaseProvider().pipe(Layer.provideMerge(postgresConnection(config)));
+
+/** The same provider over a command runner (`psql-executor.ts`) — for a loopback-only cluster. */
+export const postgresRunnerProviders = (config: PostgresRunnerConfig) =>
+  PostgresDatabaseProvider().pipe(Layer.provideMerge(postgresRunnerConnection(config)));

package/src/postgres/psql-executor.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { postgresRunnerProviders } from './providers.ts';
+import { postgresRunnerConnection, withPg } from './connection.ts';
+import { reconcileWithClient } from './database.ts';
+import { buildCreateDatabaseSql, isDuplicateDatabaseRace } from './database-sql.ts';
+import { type PsqlRunner, inlineParams, makePsqlExecutor } from './psql-executor.ts';
+
+const target = { database: 'postgres', username: 'postgres' };
+const ok = (stdout: string) => Promise.resolve({ code: 0, stdout, stderr: '' });
+
+describe('psql executor', () => {
+  test('inlines string params as literals and refuses non-strings', () => {
+    expect(inlineParams('SELECT $1, $2', ["it's", 'b'])).toBe("SELECT 'it''s', 'b'");
+    expect(() => inlineParams('SELECT $1', [5])).toThrow('must be a string');
+  });
+
+  test('a SELECT is wrapped in json_agg and parsed to rows', async () => {
+    const calls: { argv: readonly string[]; stdin: string }[] = [];
+    const run: PsqlRunner = (call) => {
+      calls.push(call);
+      return ok('[{"oid":"16400","name":"x"}]\n');
+    };
+    const rows = await Effect.runPromise(
+      makePsqlExecutor(run, target).unsafe('SELECT 1 FROM pg_database WHERE datname = $1', ['x']),
+    );
+    expect(rows).toEqual([{ oid: 16400, name: 'x' }]);
+    expect(calls[0]?.argv.slice(0, 1)).toEqual(['psql']);
+    expect(calls[0]?.stdin).toContain('json_agg');
+    expect(calls[0]?.stdin).toContain("datname = 'x'");
+  });
+
+  test('a duplicate-database failure stays recognisable as the 42P04 race', async () => {
+    const run: PsqlRunner = () =>
+      Promise.resolve({
+        code: 3,
+        stdout: '',
+        stderr: 'ERROR:  42P04: database "x" already exists\n',
+      });
+    const error = await Effect.runPromise(
+      Effect.flip(makePsqlExecutor(run, target).unsafe('CREATE DATABASE "x"')),
+    );
+    expect(isDuplicateDatabaseRace(error)).toBe(true);
+  });
+
+  test('a runner that never reached psql is a ConnectionError', async () => {
+    const run: PsqlRunner = () =>
+      Promise.resolve({ code: 255, stdout: '', stderr: 'ssh: refused' });
+    const error = await Effect.runPromise(
+      Effect.flip(makePsqlExecutor(run, target).unsafe('SELECT 1')),
+    );
+    expect(error.reason._tag).toBe('ConnectionError');
+  });
+});
+
+describe('runner transport through withPg', () => {
+  test('create uses template0 by default and the same adopt path on an existing row', async () => {
+    const stdins: string[] = [];
+    const row = {
+      oid: 1,
+      name: 'lite',
+      owner: 'litellm',
+      encoding: 'UTF8',
+      localeProvider: 'libc',
+      collate: 'C',
+      ctype: 'C',
+      allowConnections: true,
+      connectionLimit: -1,
+      isTemplate: false,
+      tablespace: 'pg_default',
+    };
+    let created = false;
+    const run: PsqlRunner = ({ stdin }) => {
+      stdins.push(stdin);
+      if (stdin.includes('pg_roles')) return ok('[{"present":1}]');
+      if (stdin.includes('FROM pg_database')) return ok(created ? JSON.stringify([row]) : '[]');
+      if (stdin.startsWith('CREATE DATABASE')) created = true;
+      return ok('');
+    };
+    const layer = postgresRunnerConnection({ run, ...target });
+    const props = { name: 'lite', owner: 'litellm' };
+    const attrs = await Effect.runPromise(
+      withPg((pg, ctx) => reconcileWithClient(pg, props, ctx.template)).pipe(Effect.provide(layer)),
+    );
+    expect(attrs.name).toBe('lite');
+    expect(stdins.find((s) => s.startsWith('CREATE DATABASE'))).toBe(
+      `${buildCreateDatabaseSql(props, 'template0')};`,
+    );
+    expect(stdins.find((s) => s.startsWith('CREATE DATABASE'))).toContain('TEMPLATE "template0"');
+    const before = stdins.length;
+    await Effect.runPromise(
+      withPg((pg, ctx) => reconcileWithClient(pg, props, ctx.template)).pipe(Effect.provide(layer)),
+    );
+    expect(stdins.slice(before).some((s) => s.startsWith('CREATE DATABASE'))).toBe(false);
+  });
+
+  test("postgresRunnerProviders keeps the connection live for the engine's later handler calls", async () => {
+    const run: PsqlRunner = () => ok('[]');
+    const rows = await Effect.runPromise(
+      withPg((pg) => pg.unsafe('SELECT 1')).pipe(
+        Effect.provide(postgresRunnerProviders({ run, ...target })),
+      ),
+    );
+    expect(rows).toEqual([]);
+  });
+});

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/acl.ts

@@ -50,6 +50,7 @@ import * as Effect from 'effect/Effect';
 import { attributesOf, bind, guardWrite, identity, matches, tuple } from './acl-wire.ts';
 import type { PveRequirements, WithTarget } from './resource-spec.ts';
 import { runPve } from './distilled-pve.ts';
+import { mintTier } from './credentials.ts';
 import {
   UNREADABLE,
   type Unreadable,
@@ -148,7 +149,12 @@ export const ProxmoxAclProvider = () =>
           // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and
           //   force `update` on a grant that was plainly there — see unreadable-read.ts.
           if (live === UNREADABLE) {
-            yield* unreadableWarning('Proxmox.Acl', identity(news));
+            yield* unreadableWarning(
+              'Proxmox.Acl',
+              identity(news),
+              news.target.mount,
+              mintTier(news.target, 'provision'),
+            );
             return { action: 'noop' } as const;
           }
           return live !== undefined && matches(live, news)

package/src/proxmox/api-token.ts

@@ -52,6 +52,7 @@ import * as Provider from 'alchemy/Provider';
 import * as access from '@distilled.cloud/proxmox/access';
 import * as Effect from 'effect/Effect';
 import { API_TOKEN_UPDATE, attributesOf, matches, shape } from './api-token-form.ts';
+import { mintTier } from './credentials.ts';
 import { guardWrite } from './distilled-guard.ts';
 import type { PveRequirements, WithTarget } from './resource-spec.ts';
 import { runPve } from './distilled-pve.ts';
@@ -190,7 +191,12 @@ export const ProxmoxApiTokenProvider = () =>
           // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and force
           //   `update` on a token that was plainly there — see unreadable-read.ts.
           if (live === UNREADABLE) {
-            yield* unreadableWarning('Proxmox.ApiToken', `${news.userid}!${news.tokenid}`);
+            yield* unreadableWarning(
+              'Proxmox.ApiToken',
+              `${news.userid}!${news.tokenid}`,
+              news.target.mount,
+              mintTier(news.target, 'provision'),
+            );
             return { action: 'noop' } as const;
           }
           // ⚠️ NO GUARDED-CREATE BRANCH HERE, UNLIKE EVERY OTHER FAMILY IN THIS SUB-AREA. There

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 }),
+  );