@homeflare/alchemy 0.54.0 → 0.55.0

package/dist/proxmox/scoped-api.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `pveScoped`: the agent helper for Ceph and container operations over the PVE API when SSH to a
+ * node is not available (2026-10-14, "PVE API path").
+ *
+ * ★ EVERY CALL MINTS A SCOPED TIER, NEVER `provision`. A call names its tier (`ceph-ops` or
+ *   `ct-config`); `scopedTarget` pins BOTH of the target's roles to that tier (credentials.ts's
+ *   "set both roles or neither"), so no read or write in it can fall back to the estate-wide tier.
+ *   In the estate those tiers are `proxmox-tb4/creds/{ceph-ops,ct-config}` → hf-ceph-ops@pve
+ *   (HFCephOps on `/`) and hf-ct-config@pve (HFCTConfig on `/vms`); the PVE ACL is the boundary.
+ * ★ A CLOSED SET OF OPERATIONS. Each builder returns a fixed method + path, with every path
+ *   segment validated, and `ctSetConfig` accepts only the keys HFCTConfig can change anyway.
+ *   No free-form path, so an agent cannot turn this into a general PVE client.
+ * ⛔ The minted secret never leaves `mint`/`pve()` (mint.ts's ⛔). Results are PVE's `data`.
+ * ⛔ Not a substitute for Alchemy: a change that should persist (a declared CT's cores, a Ceph
+ *   flag that a stack owns) still lands as a reviewed PR. This is the break-glass read/act path.
+ */
+import type * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/http/HttpClient';
+import type { PveCredentialDenied } from './credential-errors.ts';
+import { type PveForm } from './client.ts';
+import type { PveRole, PveTarget } from './credentials.ts';
+export type ScopedTier = 'ceph-ops' | 'ct-config';
+export type ScopedCall = {
+    readonly tier: ScopedTier;
+    readonly role: PveRole;
+    readonly method: 'GET' | 'POST' | 'PUT';
+    readonly path: string;
+    readonly form?: PveForm;
+};
+/** The target with BOTH roles pinned to `tier`: nothing here can mint `read`/`provision`. */
+export declare const scopedTarget: (target: PveTarget, tier: ScopedTier) => PveTarget;
+/** Flags an operator sets around maintenance. `pause`, `full` and friends are deliberately absent. */
+export declare const CEPH_FLAGS: readonly ['noout', 'norebalance', 'norecover', 'nobackfill', 'noscrub', 'nodeep-scrub'];
+export type CephFlag = (typeof CEPH_FLAGS)[number];
+/** The CT config keys `ctSetConfig` may write: exactly what HFCTConfig's VM.Config.* privs cover. */
+export declare const CT_CONFIG_KEYS: readonly ['cores', 'cpulimit', 'memory', 'swap', 'onboot', 'description', 'tags'];
+export type CtConfigPatch = Partial<Record<(typeof CT_CONFIG_KEYS)[number], string | number | boolean>>;
+export declare const scopedCalls: {
+    readonly cephStatus: () => ScopedCall;
+    readonly cephFlags: () => ScopedCall;
+    readonly cephSetFlag: (flag: CephFlag, on: boolean) => ScopedCall;
+    readonly cephOsd: (n: string, id: number, to: 'in' | 'out') => ScopedCall;
+    readonly ctConfig: (n: string, id: number) => ScopedCall;
+    readonly ctSetConfig: (n: string, id: number, patch: CtConfigPatch) => ScopedCall;
+    readonly ctPower: (n: string, id: number, action: 'start' | 'shutdown' | 'reboot') => ScopedCall;
+};
+/** Run one scoped call: mint its tier (only), call PVE, return `data`. */
+export declare const pveScoped: <T = unknown>(target: PveTarget, call: ScopedCall) => Effect.Effect<T | undefined, Error | PveCredentialDenied, HttpClient.HttpClient>;
+//# sourceMappingURL=scoped-api.d.ts.map

package/dist/proxmox/scoped-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-api.d.ts","sourceRoot":"","sources":["../../src/proxmox/scoped-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,KAAK,UAAU,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,KAAK,OAAO,EAAO,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE3D,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,WAAW,CAAC;AAElD,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,6FAA6F;AAC7F,eAAO,MAAM,YAAY,WAAY,SAAS,QAAQ,UAAU,KAAG,SAGjE,CAAC;AAgBH,sGAAsG;AACtG,eAAO,MAAM,UAAU,YACrB,OAAO,EACP,aAAa,EACb,WAAW,EACX,YAAY,EACZ,SAAS,EACT,cAAc,CACN,CAAC;AACX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,qGAAqG;AACrG,eAAO,MAAM,cAAc,YACzB,OAAO,EACP,UAAU,EACV,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,aAAa,EACb,MAAM,CACE,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,OAAO,CACjC,MAAM,CAAC,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CACnE,CAAC;AAEF,eAAO,MAAM,WAAW;aACtB,UAAU,QAAM,UAAU;aAM1B,SAAS,QAAM,UAAU;aAMzB,WAAW,SAAS,QAAQ,MAAM,OAAO,KAAG,UAAU;aAUtD,OAAO,MAAM,MAAM,MAAM,MAAM,MAAM,IAAI,GAAG,KAAK,KAAG,UAAU;aAS9D,QAAQ,MAAM,MAAM,MAAM,MAAM,KAAG,UAAU;aAM7C,WAAW,MAAM,MAAM,MAAM,MAAM,SAAS,aAAa,KAAG,UAAU;aAgBtE,OAAO,MAAM,MAAM,MAAM,MAAM,UAAU,OAAO,GAAG,UAAU,GAAG,QAAQ,KAAG,UAAU;CAS7E,CAAC;AAEX,0EAA0E;AAC1E,eAAO,MAAM,SAAS,GAAI,CAAC,GAAG,OAAO,UAC3B,SAAS,QACX,UAAU,KACf,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,EAAE,KAAK,GAAG,mBAAmB,EAAE,UAAU,CAAC,UAAU,CACK,CAAC"}

package/docs/pve-scoped-api.md

@@ -0,0 +1,23 @@
+# Scoped PVE API helper (`pveScoped`)
+
+Break-glass Ceph and container operations over the PVE API when SSH to a node is unavailable.
+
+```ts
+import { pveScoped, scopedCalls } from '@homeflare/alchemy/proxmox';
+
+const target = { mount: 'proxmox-tb4', members: ['n2.mgmt.homeflare.dev'], scheme: 'pve' } as const;
+const status = await Effect.runPromise(
+  pveScoped(target, scopedCalls.cephStatus()).pipe(Effect.provide(FetchHttpClient.layer)),
+);
+```
+
+- Every call mints its own scoped tier from OpenBao: `<mount>/creds/ceph-ops` or `<mount>/creds/ct-config`.
+  `scopedTarget` pins both roles to that tier, so nothing can fall back to `read` or `provision`.
+- In the estate, `ceph-ops` is `hf-ceph-ops@pve` (HFCephOps on `/`), and `ct-config` is
+  `hf-ct-config@pve` (HFCTConfig on `/vms`). Both are declared in homeflare-proxmox
+  `src/access-scoped-tiers.ts`. The OpenBao roles and the proxmox-deploy grant are declared in homeflare-openbao.
+- The operations are a closed set: `cephStatus`, `cephFlags`, `cephSetFlag` (maintenance flags only),
+  `cephOsd` (in/out), `ctConfig`, `ctSetConfig` (cores, cpulimit, memory, swap, onboot, description, tags) and
+  `ctPower` (start, shutdown, reboot). Every path segment is validated.
+- OpenBao is resolved the same way as `mint` (`BAO_ADDR`/`BAO_TOKEN` or an agent). The secret is never returned.
+- Not a substitute for Alchemy: a change a stack owns still lands as a reviewed PR.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",

package/src/ceph/ceph-argv-config.ts

@@ -4,19 +4,26 @@
  * split follows the same line the design docs already draw (2026-09-26-ceph-config-options.md is
  * its own companion to 2026-09-26-ceph-mon-transport.md).
  *
- * ⚠️ `<who>` IS NOT YET BOUNDED TO K-D's "declared daemons" (the config-options design's own
- *   acceptance test #1). `client.admin` still matches this shape. Latent today:
- *   `NAMED_CONFIG_OPTIONS` starts empty, so `namedOptionProblem` refuses every `config get/set/rm`
- *   regardless of `who` — LAND red team, 2026-09-26, flagged this as armed only once K-D's first
- *   named option lands, and narrowing it needs that family's own declared-daemon list, which does
- *   not exist yet. Tracked for `CephConfigOption` (K-D), not fixed here.
+ * ★ `<who>` IS BOUNDED PER OPTION (the config-options design's acceptance test #1). LAND red team,
+ *   2026-09-26, flagged the shape-only `WHO` check as armed the moment K-D's first named option
+ *   landed (`client.admin` matches it). That first option lands in the same change as this guard:
+ *   each `NAMED_CONFIG_OPTIONS` entry carries the sections it may be set for, and a `<who>` outside
+ *   that list is refused before anything dials.
  */
-import { NAMED_CONFIG_OPTIONS, isLockoutConfigOption } from './ceph-config-options.ts';
+import {
+  NAMED_CONFIG_OPTIONS,
+  allowedWhoFor,
+  isLockoutConfigOption,
+} from './ceph-config-options.ts';
 
 /** `config`'s `<who>`: a daemon class, optionally `.id` — never a path, never free text. */
 const WHO = /^(global|mon|osd|mgr|mds|client)(\.[A-Za-z0-9_-]{1,32})?$/;
-/** A ceph option name's own shape — snake_case, lowercase. Independent of the named list below. */
-const OPTION_NAME = /^[a-z][a-z0-9_]{0,63}$/;
+/**
+ * A ceph option name's own shape — snake_case, lowercase — or an mgr module option, which the mon
+ * config db keys as `mgr/<module>/<option>` (e.g. `mgr/prometheus/exclude_perf_counters`).
+ * Independent of the named list below; never a path beyond those exactly-three segments.
+ */
+const OPTION_NAME = /^(?:[a-z][a-z0-9_]{0,63}|mgr\/[a-z][a-z0-9_]{0,31}\/[a-z][a-z0-9_]{0,63})$/;
 /**
  * No shell metacharacters; the named list (below) is what actually decides secrecy, not this.
  * ⛔ NO LEADING `-` EXCEPT A NEGATIVE INTEGER, AND NEVER EMPTY. LAND red team (2026-09-26),
@@ -27,15 +34,13 @@ const OPTION_NAME = /^[a-z][a-z0-9_]{0,63}$/;
  *   `--admin-daemon=/var/run/ceph/ceph-mon.a.asok`, `--conf=/tmp/x`, `-n`, and the empty string.
  *   The sudoers entry has no argument restriction of its own (that is D4, a later step), so this
  *   allowlist is the only thing standing between a config value and an arbitrary ceph CLI flag.
- *   Latent while `NAMED_CONFIG_OPTIONS` is empty; K-D's first entry arms it.
+ *   Armed since K-D's first named entry (`mgr/prometheus/exclude_perf_counters`).
  */
 const CONFIG_VALUE = /^(?:[A-Za-z0-9][A-Za-z0-9 ._:/=,-]{0,255}|-[0-9]{1,255})$/;
 
 /**
  * `undefined` when `value` is a safe ceph config value — exported (like `boundedEntityProblem`)
- * so the shape itself is directly testable, since `NAMED_CONFIG_OPTIONS` being empty today means
- * `cephCommandProblem` never reaches this check on any real argv (`namedOptionProblem` refuses
- * first) — this stays exercised until K-D's first named option arms the path for real.
+ * so the shape itself is directly testable independently of whichever options are named.
  */
 export const configValueProblem = (value: string): string | undefined =>
   CONFIG_VALUE.test(value)
@@ -43,16 +48,19 @@ export const configValueProblem = (value: string): string | undefined =>
     : `config value ${JSON.stringify(value)} contains characters outside the safe set`;
 
 /**
- * `undefined` when `name` may be declared, adopted, read by value or written — see
+ * `undefined` when `name` may be declared for `who`, adopted, read by value or written — see
  * ceph-config-options.ts's header for why the list starts empty and stays reviewed line by line.
  */
-const namedOptionProblem = (name: string): string | undefined => {
+export const namedOptionProblem = (who: string, name: string): string | undefined => {
   if (!OPTION_NAME.test(name)) return `${JSON.stringify(name)} is not a plain ceph option name`;
   if (isLockoutConfigOption(name))
     return `${name} is a lockout-class option and can never be declared`;
-  return NAMED_CONFIG_OPTIONS.has(name)
+  if (!NAMED_CONFIG_OPTIONS.has(name))
+    return `${name} is not on the named option list (each entry is a reviewed PR line — see ceph-config-options.ts)`;
+  const allowed = allowedWhoFor(name);
+  return allowed.includes(who)
     ? undefined
-    : `${name} is not on the named option list (it starts empty — see ceph-config-options.ts)`;
+    : `${name} may only be set for ${allowed.join('/')} on the named option list, not ${JSON.stringify(who)}`;
 };
 
 /** `config get|set|rm <who> <name> [value]`, called with the operands after `config` stripped. */
@@ -64,14 +72,14 @@ export const configProblem = (rest: readonly string[]): string | undefined => {
   if (name === undefined) return 'config takes a `<name>` from the named option list';
   if (verb === 'get' || verb === 'rm') {
     return extra.length === 0
-      ? namedOptionProblem(name)
+      ? namedOptionProblem(who, name)
       : `config ${String(verb)} takes exactly \`<who> <name>\``;
   }
   if (verb === 'set') {
     const [value, ...more] = extra;
     if (value === undefined || more.length !== 0)
       return 'config set takes exactly `<who> <name> <value>`';
-    const named = namedOptionProblem(name);
+    const named = namedOptionProblem(who, name);
     return named !== undefined ? named : configValueProblem(value);
   }
   return `ceph config ${String(verb)} is not on the allowlist`;

package/src/ceph/ceph-argv.test.ts

@@ -161,7 +161,7 @@ describe('shape mismatches', () => {
   });
 });
 
-describe('config: the named list starts empty, so every shape is refused today', () => {
+describe('config: only options on the named list are accepted', () => {
   test.each([
     ['get', [CEPH_BIN, 'config', 'get', 'global', 'mon_allow_pool_delete', '-f', 'json']],
     ['set', [CEPH_BIN, 'config', 'set', 'global', 'mon_allow_pool_delete', 'true', '-f', 'json']],
@@ -197,6 +197,42 @@ describe('config: the named list starts empty, so every shape is refused today',
     expect(problem).toBeString();
   });
 
+  const OPT = 'mgr/prometheus/exclude_perf_counters';
+  test.each([
+    ['get', [CEPH_BIN, 'config', 'get', 'mgr', OPT, '-f', 'json']],
+    ['set', [CEPH_BIN, 'config', 'set', 'mgr', OPT, 'false', '-f', 'json']],
+    ['rm', [CEPH_BIN, 'config', 'rm', 'mgr', OPT, '-f', 'json']],
+  ])('config %s of the first named option, for its own <who>, is accepted', (_verb, argv) => {
+    expect(cephCommandProblem(argv)).toBeUndefined();
+  });
+
+  test.each(['global', 'client.admin', 'mon', 'mgr.a'])(
+    'the named option is refused for a <who> it is not listed for (%s)',
+    (who) => {
+      const problem = cephCommandProblem([
+        CEPH_BIN,
+        'config',
+        'set',
+        who,
+        OPT,
+        'false',
+        '-f',
+        'json',
+      ]);
+      expect(problem).toContain('may only be set for mgr');
+    },
+  );
+
+  test('an mgr-module-shaped name not on the list is refused', () => {
+    const argv = [CEPH_BIN, 'config', 'set', 'mgr', 'mgr/dashboard/ssl', 'false', '-f', 'json'];
+    expect(cephCommandProblem(argv)).toContain('named option list');
+  });
+
+  test('a path-like name beyond mgr/<module>/<option> is refused by shape', () => {
+    const argv = [CEPH_BIN, 'config', 'get', 'mgr', 'mgr/prometheus/../x', '-f', 'json'];
+    expect(cephCommandProblem(argv)).toContain('not a plain ceph option name');
+  });
+
   test('a config value with a shell metacharacter is refused', () => {
     const argv = [CEPH_BIN, 'config', 'set', 'global', 'x', 'true; rm -rf /', '-f', 'json'];
     expect(cephCommandProblem(argv)).toBeString();

package/src/ceph/ceph-argv.ts

@@ -187,3 +187,28 @@ export const quorumStatusArgv = (): readonly string[] => [
   'quorum_status',
   ...JSON_FORMAT,
 ];
+
+/**
+ * `config set <who> <name> <value>` — `Ceph.ConfigOption`'s write. ⚠️ The VALUE is in argv, so it
+ * lands in the runner's log and the node's sudo journal; acceptable only because the named option
+ * list carries no secret-valued option (ceph-config-options.ts).
+ */
+export const configSetArgv = (who: string, name: string, value: string): readonly string[] => [
+  CEPH_BIN,
+  'config',
+  'set',
+  who,
+  name,
+  value,
+  ...JSON_FORMAT,
+];
+
+/** `config rm <who> <name>` — `Ceph.ConfigOption`'s delete; idempotent on the ceph side. */
+export const configRmArgv = (who: string, name: string): readonly string[] => [
+  CEPH_BIN,
+  'config',
+  'rm',
+  who,
+  name,
+  ...JSON_FORMAT,
+];

package/src/ceph/ceph-config-option-form.ts

@@ -0,0 +1,73 @@
+/**
+ * Props, attributes and the pure helpers for `Ceph.ConfigOption` (K-D) — split from
+ * config-option.ts the same way ceph-auth-form.ts is split from auth-entity.ts: nothing here
+ * talks to a cluster, so every rule is unit-tested without PVE or ssh.
+ * Design: docs/plans/2026-09-26-ceph-config-options.md.
+ *
+ * ⛔ VALIDATION IS THE TRANSPORT'S OWN ALLOWLIST, NOT A SECOND COPY OF IT. `configOptionProblem`
+ *   builds the exact `config set` argv the write would run and asks `cephCommandProblem` — so the
+ *   named list (ceph-config-options.ts), the per-option `<who>` bound, the lockout classes and the
+ *   flag-shaped-value refusal can never disagree between plan time and write time.
+ */
+import type { ListNodeCephCfgDbResponseBodyItem } from '@distilled.cloud/proxmox/nodes';
+import type { WithTarget } from '../proxmox/resource-spec.ts';
+import { cephCommandProblem, configSetArgv } from './ceph-argv.ts';
+
+export interface CephConfigOptionProps extends WithTarget {
+  /**
+   * The PVE node whose `GET /nodes/{node}/ceph/cfg/db` answers the mon config db — the plan-time
+   * read. Any node of the Ceph cluster answers the same db.
+   */
+  node: string;
+  /** ssh destinations of the mon hosts the write (`config set`/`rm`) is tried against, in order. */
+  monNodes: readonly string[];
+  /** The config section: `global`, `mon`, `osd`, `mgr`, `mds`, `client`, optionally `.<id>`. */
+  who: string;
+  /** The option name — must be on `NAMED_CONFIG_OPTIONS` for exactly this `who`. */
+  name: string;
+  /**
+   * The value as ceph stores it — a string, compared byte-for-byte with what the config db reports.
+   * ⚠️ Spell it the way ceph echoes it back (`false`, not `0`), or every plan is an `update`.
+   */
+  value: string;
+}
+
+export interface CephConfigOptionAttributes {
+  who: string;
+  name: string;
+  /** The mon-db value observed after the last reconcile. The only field `matches` compares. */
+  value: string;
+}
+
+/** One row of the mon config db, as the PVE API reports it (`ceph config dump`'s shape). */
+export type CfgDbRow = Pick<
+  ListNodeCephCfgDbResponseBodyItem,
+  'section' | 'name' | 'value' | 'mask'
+>;
+
+/** `undefined` when props may be declared at all; else why not. Runs before any read or write. */
+export const configOptionProblem = (props: CephConfigOptionProps): string | undefined => {
+  if (props.monNodes.length === 0) return 'monNodes must name at least one mon ssh destination';
+  const problem = cephCommandProblem(configSetArgv(props.who, props.name, props.value));
+  return problem === undefined
+    ? undefined
+    : `Ceph.ConfigOption ${props.who}/${props.name}: ${problem}`;
+};
+
+/**
+ * The live row for exactly `{who, name}` with NO mask. ⚠️ A masked row (`osd/class:ssd`) is a
+ * different setting the bare `config set <who>` neither writes nor removes, so it is never matched.
+ */
+export const findLive = (
+  rows: readonly CfgDbRow[],
+  who: string,
+  name: string,
+): CephConfigOptionAttributes | undefined => {
+  const row = rows.find((r) => r.section === who && r.name === name && (r.mask ?? '') === '');
+  return row === undefined ? undefined : { name, value: String(row.value), who };
+};
+
+export const matches = (
+  live: CephConfigOptionAttributes | undefined,
+  props: CephConfigOptionProps,
+) => live !== undefined && live.value === props.value;

package/src/ceph/ceph-config-option-reconcile.ts

@@ -0,0 +1,88 @@
+/**
+ * The observe -> ensure -> sync loop and the delete for `Ceph.ConfigOption` (K-D) — plain
+ * functions, so a fake-runner test drives the real loop (same split as ceph-auth-reconcile.ts).
+ *
+ * ★ OBSERVE IS THE PVE API, WRITES ARE THE SSH MON TRANSPORT. The PVE API is read-only for the
+ *   config db (`GET /nodes/{node}/ceph/cfg/db`; no write endpoint exists), so writes go through
+ *   ceph-transport.ts's `runCephCommand` — the one transport every Ceph family in this kit uses,
+ *   allowlist-checked before it dials — and each write is followed by `assertFreshQuorum`.
+ * ★ A DEPLOY WITH NO DRIFT MAKES ZERO WRITES (S10). If the observed mon-db value already equals
+ *   props — an adopted, already-set option included — nothing reaches ssh at all.
+ * ⛔ A FAILED READ IS NEVER "ABSENT". The caller's `readRows` propagates its own failure; only a
+ *   successful read with no matching row means the option is unset.
+ * ⛔ READ BACK AFTER EVERY WRITE and refuse to record a value the mon db does not report.
+ */
+import * as Effect from 'effect/Effect';
+import { configRmArgv, configSetArgv } from './ceph-argv.ts';
+import {
+  type CephConfigOptionAttributes,
+  type CephConfigOptionProps,
+  type CfgDbRow,
+  configOptionProblem,
+  findLive,
+  matches,
+} from './ceph-config-option-form.ts';
+import { type CephTransportOptions, assertFreshQuorum, runCephCommand } from './ceph-transport.ts';
+
+export type CephConfigDeps = Pick<CephTransportOptions, 'dial' | 'log'>;
+
+const asError = (cause: unknown): Error =>
+  cause instanceof Error ? cause : new Error(String(cause));
+
+const runWrite = (transport: CephTransportOptions, argv: readonly string[]) =>
+  Effect.gen(function* () {
+    const result = yield* Effect.tryPromise({
+      catch: asError,
+      try: () => runCephCommand(transport, argv),
+    });
+    if (result.exitCode !== 0) {
+      return yield* Effect.fail(
+        new Error(
+          `ceph ${argv.slice(1, 3).join(' ')} failed on mon ${result.node} (exit ` +
+            `${String(result.exitCode)}): ${result.stderr.trim().slice(0, 300)}`,
+        ),
+      );
+    }
+    yield* Effect.tryPromise({ catch: asError, try: () => assertFreshQuorum(transport) });
+  });
+
+export const reconcileCephConfigOption = <E, R>(
+  props: CephConfigOptionProps,
+  readRows: Effect.Effect<readonly CfgDbRow[], E, R>,
+  deps: CephConfigDeps,
+): Effect.Effect<CephConfigOptionAttributes, E | Error, R> =>
+  Effect.gen(function* () {
+    const problem = configOptionProblem(props);
+    if (problem !== undefined) return yield* Effect.fail(new Error(problem));
+
+    const live = findLive(yield* readRows, props.who, props.name);
+    if (live !== undefined && matches(live, props)) return live;
+
+    yield* runWrite(
+      { nodes: props.monNodes, ...deps },
+      configSetArgv(props.who, props.name, props.value),
+    );
+    const after = findLive(yield* readRows, props.who, props.name);
+    if (after === undefined || !matches(after, props)) {
+      return yield* Effect.fail(
+        new Error(
+          `Ceph.ConfigOption ${props.who}/${props.name}: 'ceph config set' succeeded but the mon ` +
+            `config db reports ${after === undefined ? 'no value' : JSON.stringify(after.value)}, ` +
+            `not ${JSON.stringify(props.value)}. Not recorded — check \`ceph config dump\`.`,
+        ),
+      );
+    }
+    return after;
+  });
+
+/** Idempotent: an option already absent from the mon db is success, with nothing sent. */
+export const deleteCephConfigOption = <E, R>(
+  props: Pick<CephConfigOptionProps, 'who' | 'name' | 'monNodes'>,
+  readRows: Effect.Effect<readonly CfgDbRow[], E, R>,
+  deps: CephConfigDeps,
+): Effect.Effect<void, E | Error, R> =>
+  Effect.gen(function* () {
+    const live = findLive(yield* readRows, props.who, props.name);
+    if (live === undefined) return;
+    yield* runWrite({ nodes: props.monNodes, ...deps }, configRmArgv(props.who, props.name));
+  });

package/src/ceph/ceph-config-option.test.ts

@@ -0,0 +1,213 @@
+/**
+ * `Ceph.ConfigOption` (K-D): validation against the named list, the reconcile/delete loop against
+ * fakeCephDial (no ssh) and a canned config-db read (no PVE). Config-options design acceptance
+ * tests #1 (allowlist) and #2 (fake-runner loop).
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import type { PveTarget } from '../proxmox/credentials.ts';
+import {
+  type CephConfigOptionProps,
+  type CfgDbRow,
+  configOptionProblem,
+  findLive,
+} from './ceph-config-option-form.ts';
+import {
+  deleteCephConfigOption,
+  reconcileCephConfigOption,
+} from './ceph-config-option-reconcile.ts';
+import { fakeCephDial, fakeCephOk } from './fake-ceph-dial.ts';
+
+const MON = 'mon-a.example.test';
+const NAME = 'mgr/prometheus/exclude_perf_counters';
+const TARGET: PveTarget = { members: ['pve-a.example.test'], mount: 'proxmox-test', scheme: 'pve' };
+const PROPS: CephConfigOptionProps = {
+  monNodes: [MON],
+  name: NAME,
+  node: 'pve-a',
+  target: TARGET,
+  value: 'false',
+  who: 'mgr',
+};
+const HEALTHY_QUORUM = '{"quorum":[0,1,2]}';
+const row = (value: string, extra: Partial<CfgDbRow> = {}): CfgDbRow => ({
+  mask: '',
+  name: NAME,
+  section: 'mgr',
+  value,
+  ...extra,
+});
+
+/** A config-db read that answers each scripted snapshot in turn, last one repeating. */
+const rowsSeq = (...snapshots: (readonly CfgDbRow[])[]) => {
+  let at = 0;
+  return Effect.sync(() => snapshots[Math.min(at++, snapshots.length - 1)] ?? []);
+};
+const argvOf = (seen: readonly { readonly argv: readonly string[] }[]) => seen.map((c) => c.argv);
+const run = <A>(effect: Effect.Effect<A, unknown>) => Effect.runPromise(effect);
+
+describe('validation against the named option list', () => {
+  test('accepts the first named option for its own <who>', () => {
+    expect(configOptionProblem(PROPS)).toBeUndefined();
+  });
+
+  test('rejects a key that is not on the list', () => {
+    expect(configOptionProblem({ ...PROPS, name: 'osd_max_backfills', who: 'osd' })).toContain(
+      'not on the named option list',
+    );
+  });
+
+  test('rejects a listed key for an unlisted <who>', () => {
+    expect(configOptionProblem({ ...PROPS, who: 'global' })).toContain('may only be set for mgr');
+  });
+
+  test('rejects a lockout-class key and a flag-shaped value', () => {
+    expect(configOptionProblem({ ...PROPS, name: 'public_addr', who: 'mon' })).toContain('lockout');
+    expect(configOptionProblem({ ...PROPS, value: '--conf=/x' })).toContain('safe set');
+  });
+
+  test('rejects an empty mon list', () => {
+    expect(configOptionProblem({ ...PROPS, monNodes: [] })).toContain('monNodes');
+  });
+});
+
+describe('findLive maps the config-db read', () => {
+  test('the unmasked row for exactly {who, name}', () => {
+    expect(findLive([row('false')], 'mgr', NAME)).toEqual({
+      name: NAME,
+      value: 'false',
+      who: 'mgr',
+    });
+  });
+
+  test('a masked row, another section or another name is not this option', () => {
+    const rows = [
+      row('true', { mask: 'host:a' }),
+      row('true', { section: 'global' }),
+      row('true', { name: 'mgr/prometheus/x' }),
+    ];
+    expect(findLive(rows, 'mgr', NAME)).toBeUndefined();
+  });
+});
+
+describe('reconcile', () => {
+  test('live already matches (the codified exclude_perf_counters=false): zero ssh calls', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk('')] });
+    const attrs = await run(
+      reconcileCephConfigOption(PROPS, rowsSeq([row('false')]), { dial: fake.dial, log: () => {} }),
+    );
+    expect(attrs).toEqual({ name: NAME, value: 'false', who: 'mgr' });
+    expect(fake.seen).toHaveLength(0);
+  });
+
+  test('absent: exactly one config set, then a fresh quorum check, then read back', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk(''), fakeCephOk(HEALTHY_QUORUM)] });
+    const attrs = await run(
+      reconcileCephConfigOption(PROPS, rowsSeq([], [row('false')]), {
+        dial: fake.dial,
+        log: () => {},
+      }),
+    );
+    expect(attrs.value).toBe('false');
+    expect(argvOf(fake.seen)).toEqual([
+      ['/usr/bin/ceph', 'config', 'set', 'mgr', NAME, 'false', '-f', 'json'],
+      ['/usr/bin/ceph', 'quorum_status', '-f', 'json'],
+    ]);
+  });
+
+  test('drifted value: the update is the same single config set', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk(''), fakeCephOk(HEALTHY_QUORUM)] });
+    await run(
+      reconcileCephConfigOption(PROPS, rowsSeq([row('true')], [row('false')]), {
+        dial: fake.dial,
+        log: () => {},
+      }),
+    );
+    expect(argvOf(fake.seen)[0]).toEqual([
+      '/usr/bin/ceph',
+      'config',
+      'set',
+      'mgr',
+      NAME,
+      'false',
+      '-f',
+      'json',
+    ]);
+    expect(fake.seen).toHaveLength(2);
+  });
+
+  test('a read-back that disagrees is refused, never recorded', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk(''), fakeCephOk(HEALTHY_QUORUM)] });
+    await expect(
+      run(
+        reconcileCephConfigOption(PROPS, rowsSeq([row('true')]), {
+          dial: fake.dial,
+          log: () => {},
+        }),
+      ),
+    ).rejects.toThrow(/Not recorded/);
+  });
+
+  test('a non-listed key is refused before the read and before any ssh', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk('')] });
+    let reads = 0;
+    const readRows = Effect.sync(() => {
+      reads++;
+      return [] as CfgDbRow[];
+    });
+    await expect(
+      run(
+        reconcileCephConfigOption({ ...PROPS, name: 'osd_max_backfills', who: 'osd' }, readRows, {
+          dial: fake.dial,
+          log: () => {},
+        }),
+      ),
+    ).rejects.toThrow(/named option list/);
+    expect(reads).toBe(0);
+    expect(fake.seen).toHaveLength(0);
+  });
+
+  test('a failed config-db read propagates, never treated as absent', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk('')] });
+    await expect(
+      run(
+        reconcileCephConfigOption(PROPS, Effect.fail(new Error('pve down')), {
+          dial: fake.dial,
+          log: () => {},
+        }),
+      ),
+    ).rejects.toThrow(/pve down/);
+    expect(fake.seen).toHaveLength(0);
+  });
+
+  test('a degraded quorum after the write fails the row', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk(''), fakeCephOk('{"quorum":[]}')] });
+    await expect(
+      run(
+        reconcileCephConfigOption(PROPS, rowsSeq([], [row('false')]), {
+          dial: fake.dial,
+          log: () => {},
+        }),
+      ),
+    ).rejects.toThrow(/degraded/);
+  });
+});
+
+describe('delete', () => {
+  test('present: exactly one config rm, then a quorum check', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk(''), fakeCephOk(HEALTHY_QUORUM)] });
+    await run(
+      deleteCephConfigOption(PROPS, rowsSeq([row('false')]), { dial: fake.dial, log: () => {} }),
+    );
+    expect(argvOf(fake.seen)).toEqual([
+      ['/usr/bin/ceph', 'config', 'rm', 'mgr', NAME, '-f', 'json'],
+      ['/usr/bin/ceph', 'quorum_status', '-f', 'json'],
+    ]);
+  });
+
+  test('already absent: idempotent, nothing sent', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk('')] });
+    await run(deleteCephConfigOption(PROPS, rowsSeq([]), { dial: fake.dial, log: () => {} }));
+    expect(fake.seen).toHaveLength(0);
+  });
+});