@homeflare/alchemy 0.8.0 → 0.10.0

package/src/ownership/resume.ts

@@ -0,0 +1,118 @@
+/**
+ * Whether this apply RESUMES a create or replace the engine already started for this resource AND
+ * the live object it will find is proven that generation's own — the one case in which a stateless
+ * `reconcile` may write over a live object without `--adopt`.
+ *
+ * ★ HOW THE ENGINE TELLS US. Alchemy calls `diff` whenever a state row exists, and hands it `output`
+ *   = that row's attributes (alchemy beta.79 Plan.ts). A row with NO attributes is exactly an
+ *   unfinished generation: `creating` (a create interrupted after its write, before its commit),
+ *   `replacing` (the same for a replace), or `deleting` re-driven as a create. A fresh create is
+ *   never diffed at all. So the diff of such a row decides, and the apply that follows (the same
+ *   instance id: Apply.ts reuses the row's) finds the note.
+ * ⛔ A ROW PROVES NOTHING BY ITSELF (red team, 2026-09-21). Apply commits it BEFORE reconcile runs, so
+ *   a deploy killed before the claim — an upstream that failed, a Ctrl-C — leaves a row whose create
+ *   never asked whose object sat at its identity. 🔴 MEASURED (openbao/adopt-holes.test.ts): with the
+ *   name an Output, the next deploy "resumed" that create and wrote over another owner's role, in
+ *   every family that had a note on the row alone. So the note is left only when the family's own
+ *   `read`, asked as the recovery read (probe.ts ownedRead: a recorded instance, a row carrying the
+ *   whole declaration, and a live object that matches it), answers "ours". For a `creating` row
+ *   that is the question Plan.ts already asked; for a `replacing` row it is the only time it is asked.
+ * ⚠️ WHY NOT THE STATE STORE ALONE. At reconcile both look the same: Apply commits the fresh create's
+ *   `creating` row before calling reconcile, so a row with this instance id is always there.
+ * ★ THE CHANNEL IS ALCHEMY'S OWN: `Artifacts`, the per-FQN bag the engine shares between one plan
+ *   and its apply (Artifacts.ts: "diff computes … create / update reads the same artifact").
+ *   Deploy.ts and the Alchemist session both hold one store across the pair.
+ * ⚠️ IT FAILS CLOSED. No bag, a bag the plan never wrote, or an object the read cannot prove ours
+ *   reads as a fresh create, and adopt.ts then asks for `--adopt` — the safe direction.
+ * ★ AN UNPROVEN RESUME IS STILL MARKED UNFINISHED (`noteUnfinished`), so `--adopt` can take it over
+ *   the way Alchemy's own "Cannot resume creating … Re-run with --adopt" offers for a create — while
+ *   a FRESH replace's new generation, which no diff ever saw without attributes, stays unadoptable.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { Artifacts } from 'alchemy/Artifacts';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+const PROVEN = 'homeflare/ownership/resumes';
+const UNFINISHED = 'homeflare/ownership/unfinished';
+
+const note = (key: string, instanceId: string): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    const bag = yield* Effect.serviceOption(Artifacts);
+    if (Option.isSome(bag)) yield* bag.value.set(key, instanceId);
+  });
+
+const noted = (key: string, instanceId: string): Effect.Effect<boolean> =>
+  Effect.gen(function* () {
+    const bag = yield* Effect.serviceOption(Artifacts);
+    if (Option.isNone(bag)) return false;
+    return (yield* bag.value.get<string>(key)) === instanceId;
+  });
+
+/**
+ * `diff`'s note for a row with no attributes: `instanceId` is an unfinished generation of this
+ * resource's own, which `--adopt` may resume when nothing proves it (adopt.ts adoptable). Returns
+ * `undefined`, a diff's "defer to the engine".
+ */
+export const noteUnfinished = (instanceId: string): Effect.Effect<undefined> =>
+  Effect.as(note(UNFINISHED, instanceId), undefined);
+
+/**
+ * Note `instanceId` unfinished, and a proven resume when `recovered` — the family's `read` of the
+ * row's props, asked with no attributes — answers a plain object: ours. `Unowned`, nothing, or a
+ * read that fails or dies proves nothing. ⚠️ Never fails the plan: an unproven resume is refused
+ * at apply instead, unless `--adopt`.
+ */
+export const noteResume = <R>(
+  instanceId: string,
+  recovered: Effect.Effect<unknown, unknown, R>,
+): Effect.Effect<void, never, R> =>
+  Effect.gen(function* () {
+    yield* noteUnfinished(instanceId);
+    const unproven = () => Effect.succeed(undefined);
+    const found = yield* recovered.pipe(Effect.catch(unproven), Effect.catchDefect(unproven));
+    if (found === undefined || found === null || Unowned.is(found)) return;
+    yield* note(PROVEN, instanceId);
+  });
+
+/** Whether the plan for this apply noted `instanceId` as a proven resumed create or replace. */
+export const resumes = (instanceId: string): Effect.Effect<boolean> => noted(PROVEN, instanceId);
+
+/** Whether the plan for this apply saw `instanceId` as an unfinished generation (proven or not). */
+export const unfinished = (instanceId: string): Effect.Effect<boolean> =>
+  noted(UNFINISHED, instanceId);
+
+/** The fields of a `read` or `diff` call provingResumes uses; a family's own input carries more. */
+type Ask = {
+  readonly id: string;
+  readonly fqn: string;
+  readonly instanceId: string;
+  readonly olds: unknown;
+  readonly output: unknown;
+};
+type Hook = Effect.Effect<unknown, unknown, unknown>;
+
+/** The two hooks provingResumes wraps, as Alchemy's ProviderService declares them. */
+interface Resumable {
+  read?(input: Ask): Hook;
+  diff?(input: Ask): Hook;
+}
+
+/**
+ * A provider whose `diff`, for a row with no attributes, first asks the provider's own `read` whether
+ * the live object is that unfinished generation's (noteResume), then runs as written. Every Bao.*
+ * family is built through it, so their diffs answer such a row with a plain `undefined`.
+ */
+export const provingResumes = <S extends Resumable>(service: S): S => {
+  const { diff, read } = service;
+  if (diff === undefined || read === undefined) return service;
+  const proving: Resumable['diff'] = (input) =>
+    Effect.gen(function* () {
+      if (input.output === undefined) {
+        yield* noteResume(input.instanceId, read({ ...input, output: undefined }));
+      }
+      return yield* diff(input);
+    });
+  // ⚠️ The one cast: `diff` keeps the family's own signature — it is the family's diff, run after.
+  return { ...service, diff: proving } as S;
+};

package/src/ownership/rows.ts

@@ -0,0 +1,117 @@
+/**
+ * The questions ownership/ asks of Alchemy's state store: does a row record this instance, and with
+ * its whole declaration (probe.ts); is this apply a create rather than a replace's new generation
+ * (adopt.ts); and — when reconcile refuses a create — forget the row Apply committed for it
+ * (adopt.ts). Alchemy's own AWS.EC2.SecurityGroup provider reads the store the same way: the Stack
+ * service names the stack and stage, and `State` yields the store.
+ *
+ * ⚠️ WITHOUT A STACK OR STATE IN CONTEXT, or with a store that errors, a row reads as "not
+ *   recorded" — the object is then `Unowned`, the safe answer — and nothing is forgotten, which
+ *   leaves the one gap forgetRefusedCreate exists to close. `alchemy deploy` and the Alchemist
+ *   session provide both.
+ */
+import { Stack } from 'alchemy/Stack';
+import { State, type StateService, isActionState } from 'alchemy/State/State';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import { wholeDeclaration } from './whole.ts';
+
+type Where = { readonly stack: string; readonly stage: string };
+
+/** The store, where this stack lives, and what it declares — or undefined outside a stack. */
+const storeOf = Effect.gen(function* () {
+  const stack = yield* Effect.serviceOption(Stack);
+  const state = yield* Effect.serviceOption(State);
+  if (Option.isNone(stack) || Option.isNone(state)) return undefined;
+  const store: StateService = yield* state.value;
+  const where: Where = { stack: stack.value.name, stage: stack.value.stage };
+  return { resources: stack.value.resources, store, where };
+});
+
+const rowAt = (store: StateService, where: Where, fqn: string) =>
+  store.get({ ...where, fqn }).pipe(Effect.orElseSucceed(() => undefined));
+
+type Generation = {
+  readonly instanceId?: unknown;
+  readonly status?: unknown;
+  readonly props?: unknown;
+  readonly attr?: unknown;
+  readonly old?: unknown;
+};
+
+/** The generation of a persisted row that carries `instanceId`: the row itself, or one in `old`. */
+const generationOf = (row: unknown, instanceId: string): Generation | undefined => {
+  let at = row;
+  while (typeof at === 'object' && at !== null && !isActionState(at as never)) {
+    const generation = at as Generation;
+    if (generation.instanceId === instanceId) return generation;
+    at = generation.old;
+  }
+  return undefined;
+};
+
+/** The generation `instanceId` names — at the FQN, or at a former FQN `renamedFrom` names. */
+const recordedGeneration = (fqn: string, instanceId: string) =>
+  Effect.gen(function* () {
+    const found = yield* storeOf;
+    if (found === undefined) return undefined;
+    for (const at of [fqn, ...(found.resources[fqn]?.FormerFqns ?? [])]) {
+      const generation = generationOf(yield* rowAt(found.store, found.where, at), instanceId);
+      if (generation !== undefined) return generation;
+    }
+    return undefined;
+  });
+
+/**
+ * What the state store says of `instanceId` for this resource (at its FQN, or at a former FQN its
+ * `renamedFrom` names — the planner migrates that row before it recovers it):
+ *   · `absent`  — no row holds it. ★ This is what separates the probe from the recovery read: the
+ *     probe's instance id is minted for the probe (Plan.ts `generateInstanceId()`), 128 random bits
+ *     no row can hold.
+ *   · `partial` — a row holds it, but its props lack part of the declaration: a prop stripped at
+ *     commit because it was still an Output (whole.ts). Those props cannot prove an object ours.
+ *   · `whole`   — a row holds it with every prop the declaration names.
+ */
+export type Recorded = 'absent' | 'partial' | 'whole';
+
+export const recordedInstance = (fqn: string, instanceId: string): Effect.Effect<Recorded> =>
+  Effect.gen(function* () {
+    const generation = yield* recordedGeneration(fqn, instanceId);
+    if (generation === undefined) return 'absent';
+    return (yield* wholeDeclaration(fqn, generation.props)) ? 'whole' : 'partial';
+  });
+
+/**
+ * Whether this apply's `instanceId` is a CREATE: the row Apply committed for it is `creating`.
+ * ⛔ A REPLACE'S NEW GENERATION IS NOT ONE. Apply commits it as `replacing`, and the planner never
+ *   offers it adoption — the probe runs only for a resource with no state — so `--adopt` must not
+ *   let it write over whatever sits at its new identity (adopt.ts adoptsAtApply).
+ */
+export const isCreate = (fqn: string, instanceId: string): Effect.Effect<boolean> =>
+  Effect.map(
+    recordedGeneration(fqn, instanceId),
+    (generation) => generation?.status === 'creating',
+  );
+
+/**
+ * ⛔ A REFUSED CREATE MUST NOT LEAVE A ROW THAT CLAIMS THE OBJECT IT REFUSED. Apply commits a
+ *   `creating` row for this instance before it calls reconcile, and a failed reconcile leaves it
+ *   there. The next plan's recovery read would then find our instance id and an object that can
+ *   match its props — a prop that was an Output is stripped from the row, and an omitted prop is
+ *   "not managed" — and adopt exactly what this apply refused. 🔴 MEASURED 2026-09-21: Bao.Mount
+ *   and Bao.AuthMethod did (openbao/adopt-core.test.ts). So the row goes, and state reads as if
+ *   the create never started: the next plan probes, and the probe answers `Unowned`.
+ * ⚠️ ONLY a `creating` row of THIS instance with no attributes — the one Apply just wrote. A
+ *   `replacing` row carries the previous generation in `old` and is never touched.
+ */
+export const forgetRefusedCreate = (fqn: string, instanceId: string): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    const found = yield* storeOf;
+    if (found === undefined) return;
+    const row = yield* rowAt(found.store, found.where, fqn);
+    const mine = row as { status?: unknown; instanceId?: unknown; attr?: unknown } | undefined;
+    if (mine?.status !== 'creating' || mine.instanceId !== instanceId || mine.attr !== undefined) {
+      return;
+    }
+    yield* found.store.delete({ ...found.where, fqn }).pipe(Effect.ignore);
+  });

package/src/ownership/whole.test.ts

@@ -0,0 +1,39 @@
+/**
+ * whole.ts `carries`: a state row's props against the declaration — every declared value, Outputs
+ * included, needs a value in the row; an optional prop left out of both is no hole.
+ */
+import { describe, expect, test } from 'bun:test';
+import { carries } from './whole.ts';
+
+/** Stands in for an Output: Alchemy's are function-typed proxies (Diff.ts stripUnresolved). */
+const output = Object.assign(() => undefined, { kind: 'Output' });
+
+describe('carries', () => {
+  test('a row with every declared value is whole; an omission from both is no hole', () => {
+    expect(carries({ name: 'a', ttl: output }, { name: 'a', ttl: '15m' })).toBe(true);
+    expect(carries({ name: 'a', ttl: undefined }, { name: 'a' })).toBe(true);
+    expect(carries(undefined, { name: 'a' })).toBe(true);
+  });
+
+  test('a declared value — an Output or a literal — missing from the row is a hole', () => {
+    expect(carries({ name: output, ttl: '15m' }, { ttl: '15m' })).toBe(false);
+    expect(carries({ name: 'a', ttl: '15m' }, { name: 'a' })).toBe(false);
+    expect(carries({ name: 'a' }, undefined)).toBe(false);
+  });
+
+  test('holes inside arrays and nested objects count, as JSON stores keep them (null)', () => {
+    expect(carries({ policies: ['a', output] }, { policies: ['a', null] })).toBe(false);
+    expect(carries({ policies: ['a', output] }, { policies: ['a'] })).toBe(false);
+    expect(carries({ policies: [{ groups: [output] }] }, { policies: [{ groups: [] }] })).toBe(
+      false,
+    );
+    expect(carries({ policies: [{ groups: ['g'] }] }, { policies: [{ groups: ['g'] }] })).toBe(
+      true,
+    );
+  });
+
+  test('a shape the row does not share is not the declaration', () => {
+    expect(carries({ policies: ['a'] }, { policies: 'a' })).toBe(false);
+    expect(carries({ tune: { ttl: '1h' } }, { tune: '1h' })).toBe(false);
+  });
+});

package/src/ownership/whole.ts

@@ -0,0 +1,60 @@
+/**
+ * Whether a state row's props say everything the declaration says — the test that separates a row
+ * whose props can prove an object ours from one that cannot (probe.ts, rows.ts).
+ *
+ * ★ WHY A ROW CAN BE MISSING PART OF ITS DECLARATION. Apply commits the `creating` (or `replacing`)
+ *   row BEFORE reconcile runs, and strips every prop still an Output at that moment (alchemy
+ *   beta.79 Apply.ts `commit` → Diff.ts `stripUnresolved`); a JSON store then drops the key. So a
+ *   row written while an upstream was still being created carries a HOLE where that prop was.
+ * ⛔ A HOLE IS "UNKNOWN", NOT "UNMANAGED". Most families read an absent prop as "not managed", so a
+ *   recovery read comparing the live object with holed props proves nothing: 🔴 MEASURED 2026-09-21
+ *   (openbao/adopt-holes.test.ts), a Bao.Mount whose `defaultLeaseTtl` was an Output, killed before
+ *   its reconcile ran, adopted — and tuned — another owner's mount on the next deploy; with the
+ *   NAME an Output, every role family read an empty name, found nothing, and the resumed create
+ *   wrote over another owner's role. Neither deploy had ever asked whose object it was.
+ * ★ THE DECLARATION IS WHAT TELLS A HOLE FROM AN OMISSION. It still holds the Output (or the literal)
+ *   the row lacks, while an optional prop left out is absent from both.
+ * ⚠️ CONSERVATIVE BY DESIGN: a prop added to the declaration after the crash also reads as a hole.
+ *   That costs one `--adopt`, never a takeover.
+ */
+import { Stack } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+const absent = (value: unknown): boolean => value === undefined || value === null;
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const proto: unknown = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+
+/**
+ * Whether `recorded` carries a value everywhere `declared` does. Plain objects and arrays are
+ * walked; any other declared value — a literal, an Output, an Effect — needs a value in the row.
+ */
+export const carries = (declared: unknown, recorded: unknown): boolean => {
+  if (absent(declared)) return true;
+  if (absent(recorded)) return false;
+  if (Array.isArray(declared)) {
+    if (!Array.isArray(recorded)) return false;
+    return declared.every((each, index) => carries(each, recorded[index]));
+  }
+  if (isPlainObject(declared)) {
+    if (!isPlainObject(recorded)) return false;
+    return Object.entries(declared).every(([key, each]) => carries(each, recorded[key]));
+  }
+  return true;
+};
+
+/**
+ * Whether `props` — one generation's, from the state store — carry the whole declaration of the
+ * resource at `fqn`. ⛔ FALSE WITH NOTHING TO COMPARE: no Stack in context, or a resource no longer
+ *   declared (an orphan's delete). That object then reads as `Unowned` and Apply leaves it in place
+ *   with a note, rather than deleting what it cannot prove it made.
+ */
+export const wholeDeclaration = (fqn: string, props: unknown): Effect.Effect<boolean> =>
+  Effect.map(Effect.serviceOption(Stack), (stack) => {
+    const declared = Option.isSome(stack) ? stack.value.resources[fqn] : undefined;
+    return declared !== undefined && carries(declared.Props, props);
+  });

package/src/proxmox/adopt-noop.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Adopting an object that already matches must be read-only — measured per reconcile SHAPE, through
+ * Alchemy's own Plan and Apply over a fake cluster (fake-pve.ts, ../verify/fake-engine.ts).
+ *
+ * ★ ONE ROW PER WAY A FAMILY REACHES ITS WRITE, not one per family. Every family built on
+ *   `pveHandlers` shares resource.ts's reconcile, so `Proxmox.Pool` stands for all of them; `Acl`
+ *   wraps that reconcile; `PbsDatastore` and `SdnApply` write their own. CephPool, the one that got
+ *   it wrong, has its own file. docs/adopt-verify.md carries the full per-family table.
+ * ⚠️ A FIXTURE THAT DOES NOT MATCH TURNS A ROW INTO A DRIFT TEST, and the assertion on the
+ *   verifier's `noop` is what catches that: a wrong fixture fails loudly instead of passing for
+ *   the wrong reason. The Pool drift row proves the harness can see a write at all.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { ProxmoxAcl, ProxmoxAclProvider } from './acl.ts';
+import type { PbsTarget } from './credentials.ts';
+import { FAKE_TARGET, fakePve, withoutBao } from './fake-pve.ts';
+import { PbsDatastore, PbsDatastoreProvider } from './pbs-datastore.ts';
+import { ProxmoxPool, ProxmoxPoolProvider } from './pool.ts';
+import { ProxmoxSdnApply, ProxmoxSdnApplyProvider } from './sdn-apply.ts';
+
+const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };
+
+type Case = {
+  readonly name: string;
+  readonly provider: () => Layer.Layer<never, never, never>;
+  readonly declare: () => ReturnType<typeof ProxmoxPool>;
+  /** GET path → the `data` PVE/PBS answers; anything unlisted answers `null`. */
+  readonly live: Readonly<Record<string, unknown>>;
+};
+
+const cases: readonly Case[] = [
+  {
+    declare: () => ProxmoxPool('house', { comment: 'x', poolid: 'house', target: FAKE_TARGET }),
+    live: { 'pools/house': { comment: 'x', members: [] } },
+    name: 'Proxmox.Pool (pveHandlers: every factory family)',
+    provider: ProxmoxPoolProvider as never,
+  },
+  {
+    declare: () =>
+      ProxmoxAcl('auditor', {
+        path: '/',
+        roleid: 'PVEAuditor',
+        target: FAKE_TARGET,
+        type: 'user',
+        ugid: 'u@pve',
+      }) as never,
+    live: {
+      'access/acl': [
+        { path: '/', propagate: 1, roleid: 'PVEAuditor', type: 'user', ugid: 'u@pve' },
+      ],
+    },
+    name: 'Proxmox.Acl (wraps the factory reconcile)',
+    provider: ProxmoxAclProvider as never,
+  },
+  {
+    declare: () =>
+      PbsDatastore('store1', {
+        comment: 'c',
+        'gc-schedule': 'daily',
+        name: 'store1',
+        path: '/mnt/store1',
+        target: PBS,
+      }) as never,
+    live: {
+      'config/datastore/store1': {
+        comment: 'c',
+        'gc-schedule': 'daily',
+        name: 'store1',
+        path: '/mnt/store1',
+      },
+    },
+    name: 'Pbs.Datastore (its own reconcile)',
+    provider: PbsDatastoreProvider as never,
+  },
+  {
+    declare: () => ProxmoxSdnApply('sdn', { target: FAKE_TARGET }) as never,
+    live: {},
+    name: 'Proxmox.SdnApply (its own reconcile; nothing staged)',
+    provider: ProxmoxSdnApplyProvider as never,
+  },
+];
+
+const clusterWith = (live: Readonly<Record<string, unknown>>) =>
+  fakePve((call) => (call.method === 'GET' ? live[call.path] : 'UPID:fake'));
+
+describe('adopting a matching object only reads', () => {
+  test.each(cases.map((c) => [c.name, c] as const))('%s', async (_, c) => {
+    const fake = clusterWith(c.live);
+    await withoutBao(async () => {
+      const engine = engineOver(c.provider().pipe(Layer.provideMerge(fake.layer)));
+      const report = await engine.verify(c.declare());
+      expect(report.rows).toEqual([expect.objectContaining({ diff: 'noop', ok: true })]);
+      expect(Object.values(await engine.deploy(c.declare()))).toEqual(['adopted']);
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('and the harness does see a write: a drifted Pool is PUT once', async () => {
+    const fake = clusterWith({ 'pools/house': { comment: 'old', members: [] } });
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxPoolProvider().pipe(Layer.provideMerge(fake.layer)));
+      const declared = () =>
+        ProxmoxPool('house', { comment: 'x', poolid: 'house', target: FAKE_TARGET });
+      const report = await engine.verify(declared());
+      expect(report.rows[0]).toMatchObject({ changed: ['comment'], diff: 'update', ok: false });
+      expect(await engine.deploy(declared())).toEqual({ house: 'adopted' });
+    });
+    expect(fake.writes()).toEqual(['PUT pools/house']);
+  });
+});

package/src/proxmox/ceph-pool-adopt.test.ts

@@ -0,0 +1,88 @@
+/**
+ * `Proxmox.CephPool` adopted through Alchemy's own Plan and Apply, over a fake cluster.
+ *
+ * 🔴 THE BUG THIS PINS (found 2026-09-21, update-guard.ts). The family's hand-written reconcile
+ *   PUT the declared set whenever the pool existed. Plan.ts forces reconcile after the adoption
+ *   probe even when the diff says `noop`, so adopting a pool that already matched sent `setpool`
+ *   and forked a worker on the live cluster. The first test fails with that PUT on the old code.
+ * ★ THE VERIFIER RUNS OVER THE SAME ENGINE, so the same test also shows what it reports before
+ *   the deploy: `adopted` from the engine, `noop` from the provider.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { ProxmoxCephPool, ProxmoxCephPoolProvider } from './ceph-pool.ts';
+import { FAKE_TARGET, type PveCall, fakePve, withoutBao } from './fake-pve.ts';
+
+const STATUS = 'nodes/n2/ceph/pool/cephtb4/status?verbose=1';
+const OBJECT = 'nodes/n2/ceph/pool/cephtb4';
+
+/** TB4's rbd pool as `getpool` answers it — the fields ceph-pool.ts reads. */
+const livePool = (size: number): Record<string, unknown> => ({
+  application_list: ['rbd'],
+  crush_rule: 'replicated_rule',
+  id: 2,
+  min_size: 2,
+  name: 'cephtb4',
+  pg_autoscale_mode: 'on',
+  pg_num: 128,
+  size,
+});
+
+/** A cluster holding one pool; a PUT to it lands, as `setpool` would. */
+const cluster = (size: number) => {
+  const pool = livePool(size);
+  return fakePve((call: PveCall) => {
+    if (call.method === 'GET' && call.path === STATUS) return pool;
+    if (call.method === 'PUT' && call.path === OBJECT) {
+      for (const [key, value] of Object.entries(call.form)) {
+        pool[key] = /^\d+$/.test(value) ? Number(value) : value;
+      }
+      return 'UPID:n2:fake:setpool';
+    }
+    return undefined;
+  });
+};
+
+const declared = () =>
+  ProxmoxCephPool('cephtb4', {
+    crush_rule: 'replicated_rule',
+    min_size: 2,
+    name: 'cephtb4',
+    node: 'n2',
+    pg_autoscale_mode: 'on',
+    size: 3,
+    target: FAKE_TARGET,
+  });
+
+const engineFor = (fake: ReturnType<typeof cluster>) =>
+  engineOver(ProxmoxCephPoolProvider().pipe(Layer.provideMerge(fake.layer)));
+
+describe('adopting a Ceph pool', () => {
+  test('that already matches: the verifier says noop, and the deploy only reads', async () => {
+    const fake = cluster(3);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const report = await engine.verify(declared());
+      expect(report.rows).toEqual([
+        expect.objectContaining({ diff: 'noop', ok: true, planned: 'adopted', read: 'found' }),
+      ]);
+      expect(await engine.deploy(declared())).toEqual({ cephtb4: 'adopted' });
+    });
+    expect(fake.writes()).toEqual([]);
+    expect(fake.calls.every((call) => call.path === STATUS)).toBe(true);
+  });
+
+  test('that drifted: the verifier names the field, and the deploy PUTs once', async () => {
+    const fake = cluster(2);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const report = await engine.verify(declared());
+      expect(report.rows[0]).toMatchObject({ changed: ['size'], diff: 'update', ok: false });
+      expect(fake.writes()).toEqual([]);
+      expect(await engine.deploy(declared())).toEqual({ cephtb4: 'adopted' });
+    });
+    expect(fake.writes()).toEqual([`PUT ${OBJECT}`]);
+    expect(fake.calls.find((call) => call.method === 'PUT')?.form['size']).toBe('3');
+  });
+});

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

@@ -192,9 +192,9 @@ const numeric = (value: number | undefined) => (value === undefined ? undefined
  * the way storage.ts's `mutable` serves both of its forms. `name` is the path's last segment on an
  * update and is not repeated here.
  *
- * ⚠️ SAFE TO RE-APPLY TO A POOL THAT ALREADY MATCHES, which reconcile relies on. MEASURED in
- *   PVE::Ceph::Tools::set_pool (Tools.pm:293-300): it reads `osd pool get all` first and SKIPS
- *   every setting whose value did not change, so re-sending the declared set costs one mon read.
+ * ⚠️ SAFE TO RE-APPLY TO A POOL THAT ALREADY MATCHES (reconcile leaned on it until update-guard.ts).
+ *   MEASURED in PVE::Ceph::Tools::set_pool (Tools.pm:293-300): it reads `osd pool get all` first
+ *   and SKIPS every unchanged setting, so the undrifted fields that ride along cost one mon read.
  * ⛔ BUT A SETTING THAT DID CHANGE AND CANNOT BE APPLIED KILLS THE WHOLE PUT. Tools.pm:310 dies
  *   with "Could not set: <fields>" if any parameter is left unapplied, so a pool carrying Ceph's
  *   `nosizechange` fails an entire update over one field. That is why the `no*` flags are reported

package/src/proxmox/ceph-pool.ts

@@ -53,6 +53,7 @@ import {
 import { confirmAbsent, settle } from './ceph-pool-settle.ts';
 import { pve } from './client.ts';
 import { type PveRequirements, type PveSpec, pveOperations } from './resource.ts';
+import { formToSend } from './update-guard.ts';
 import { bool, int, num, text } from './values.ts';
 
 export type { CephPoolAttributes, CephPoolProps };
@@ -160,9 +161,15 @@ export const ProxmoxCephPoolProvider = () =>
               createBody(news),
             );
           } else {
-            // ⚠️ An empty form is not a write — resource.ts skips one for the same reason.
-            const form = updateBody(news);
-            if (Object.keys(form).length > 0) {
+            /**
+             * ⛔ ONLY WHEN `matches` IS FALSE. This PUT used to fire whenever the pool existed, so
+             *   adopting a pool that already matched — Plan.ts forces reconcile after the probe —
+             *   sent `setpool` and forked a worker on the live cluster. PVE skipping the unchanged
+             *   settings (ceph-pool-form.ts) made it harmless to Ceph, not free: it is still a
+             *   provision-lease write and a task in the cluster's list. update-guard.ts has the rest.
+             */
+            const form = formToSend(spec.matches, live, news, updateBody(news));
+            if (form !== undefined) {
               upid = yield* pve<string>(news.target, 'provision', 'PUT', object(news), form);
             }
           }

package/src/proxmox/fake-bao-env.ts

@@ -0,0 +1,28 @@
+/**
+ * The shell's OpenBao variables, replaced for the life of one test run and put back afterwards.
+ *
+ * ⛔ WHY A TEST CANNOT LEAVE THEM ALONE. `leased` mints through credentials.ts `mint`, which reads
+ *   `BAO_AGENT_ADDR` before `BAO_ADDR` (and the `VAULT_*` spellings), and sends `BAO_TOKEN` as a
+ *   header. A developer shell with any of them set would send its real token to a fake, or a mint
+ *   to a real agent. credentials.test.ts avoids it by passing an explicit environment; a test that
+ *   drives a provider cannot, because the lease cache reads `process.env`.
+ * ★ ONE HELPER FOR EVERY FAKE. lxc-harness.ts and fake-pve.ts each carried their own copy; the
+ *   first covered three names and the second every `BAO_*` / `VAULT_*`, so they now share the
+ *   wider one. ⛔ TEST-ONLY. No provider imports this file.
+ */
+const BAO_VARIABLES = /^(BAO|VAULT)_/;
+
+/** Run `body` with every BAO_* / VAULT_* unset except `BAO_ADDR=address`, then restore them. */
+export const withFakeBao = async <A>(address: string, body: () => Promise<A>): Promise<A> => {
+  const saved = Object.entries(process.env).filter(([name]) => BAO_VARIABLES.test(name));
+  for (const [name] of saved) delete process.env[name];
+  process.env['BAO_ADDR'] = address;
+  try {
+    return await body();
+  } finally {
+    for (const name of Object.keys(process.env)) {
+      if (BAO_VARIABLES.test(name)) delete process.env[name];
+    }
+    for (const [name, value] of saved) process.env[name] = value;
+  }
+};