@homeflare/alchemy 0.8.0 → 0.10.1

package/src/proxmox/update-guard.ts

@@ -0,0 +1,31 @@
+/**
+ * Whether an update has anything to write — decided ONCE for every PVE and PBS family.
+ *
+ * ⛔ AN ADOPTED ROW IS RECONCILED EVEN WHEN ITS DIFF SAID `noop`, SO THIS GUARD IS WHAT MAKES
+ *   ADOPTION FREE. alchemy beta.79 Plan.ts sets `forceUpdateAfterAdoption` after the cold-start
+ *   probe and turns a `noop` diff into an update; Apply.ts then calls `reconcile` for the
+ *   `adopted` action exactly as for `update`. The plan prints `adopted` either way, so nothing on
+ *   screen tells a matching object from a drifting one. docs/adopt-verify.md has the table of
+ *   what each family does on that path.
+ *
+ * 🔴 THE FAMILY THAT DID NOT HAVE IT. `Proxmox.CephPool` wrote its own reconcile and PUT the
+ *   declared set whenever the pool existed, so adopting a pool that already matched sent
+ *   `setpool` and forked a worker on the live cluster (found 2026-09-21 by tracing every family).
+ *   resource.ts and pbs-datastore.ts each had the guard inline; three copies of one predicate is
+ *   how the fourth family forgets it, so it lives here and all three call it.
+ *
+ * ★ `matches` IS THE SAME PREDICATE `diff` USES, so "the diff said noop" and "reconcile writes
+ *   nothing" cannot disagree. A field left OUT of `matches` is one the family does not manage, so
+ *   its drift is not this write's to repair.
+ *
+ * ⚠️ AN EMPTY FORM IS ALSO NOT A WRITE. `updateForm` can legitimately answer `{}` — a storage
+ *   declaring only `storage`, `type` and its locator has no mutable field at all — and PUTting an
+ *   empty body is a pointless write at best and a 400 that reads as a broken provider at worst.
+ *   (Moved here from resource.ts with the guard it explains.)
+ */
+export const formToSend = <Attributes, Props, Form extends object>(
+  matches: (attributes: Attributes, props: Props) => boolean,
+  live: Attributes,
+  props: Props,
+  form: Form,
+): Form | undefined => (matches(live, props) || Object.keys(form).length === 0 ? undefined : form);

package/src/verify/args.ts

@@ -0,0 +1,82 @@
+/**
+ * `hf-adopt-verify`'s flags — the ones `alchemy plan` takes, so a stack script can swap one
+ * command for the other.
+ *
+ * ★ `node:util` parseArgs, NOT effect's CLI module. Alchemy builds its CLI on
+ *   `effect/unstable/cli`, but that needs a CliConfig and a Terminal layer to parse six flags; the
+ *   standard library parses them with no service at all, which keeps this pure and testable.
+ * ⛔ `--stage` HAS NO GUESSED DEFAULT. Alchemy falls back to `live_$USER`; a gate that silently
+ *   verified the wrong stage would pass for the wrong reason. It comes from the flag or from
+ *   `$ALCHEMY_STAGE`, or the run stops.
+ */
+import { parseArgs } from 'node:util';
+import type { VerifyOptions, VerifyTarget } from './verify.ts';
+
+export const USAGE = `Usage: hf-adopt-verify --stage <stage> [--config alchemy.run.ts] [options]
+
+Plans the stack with Alchemy's own planner, never writes, and reports each row
+without a state row: what the engine planned, the provider's read and its own
+diff (before Alchemy forces adopted rows to update), and the declared fields
+that differ from the live object. Exits 0 when every row is a no-op, 1 when
+any is not, 2 when it could not tell.
+
+  -c, --config <file>   stack entrypoint (default alchemy.run.ts)
+      --stage <stage>   stage to verify (default $ALCHEMY_STAGE; required)
+      --profile <name>  Alchemy auth profile
+      --env-file <file> .env file layered under the environment
+      --all             report every declared row and pending deletion
+      --json            print the report as JSON
+  -h, --help            this text
+`;
+
+export type Parsed =
+  | { readonly kind: 'help' }
+  | { readonly kind: 'error'; readonly message: string }
+  | {
+      readonly kind: 'run';
+      readonly target: VerifyTarget;
+      readonly options: VerifyOptions;
+      readonly json: boolean;
+    };
+
+const parse = (argv: readonly string[]) =>
+  parseArgs({
+    args: [...argv],
+    allowPositionals: false,
+    options: {
+      all: { type: 'boolean', default: false },
+      config: { type: 'string', short: 'c', default: 'alchemy.run.ts' },
+      'env-file': { type: 'string' },
+      help: { type: 'boolean', short: 'h', default: false },
+      json: { type: 'boolean', default: false },
+      profile: { type: 'string' },
+      stage: { type: 'string' },
+    },
+    strict: true,
+  });
+
+/** Parse argv (without the runtime and script) against the environment. Never throws. */
+export const parseVerifyArgs = (
+  argv: readonly string[],
+  env: Readonly<Record<string, string | undefined>>,
+): Parsed => {
+  let parsed: ReturnType<typeof parse>;
+  try {
+    parsed = parse(argv);
+  } catch (error) {
+    return { kind: 'error', message: error instanceof Error ? error.message : String(error) };
+  }
+  const { values } = parsed;
+  if (values.help) return { kind: 'help' };
+  const stage = values.stage ?? env['ALCHEMY_STAGE'];
+  if (stage === undefined || stage === '') {
+    return { kind: 'error', message: 'pass --stage (or set ALCHEMY_STAGE): no stage is guessed' };
+  }
+  const target: VerifyTarget = {
+    entrypoint: values.config,
+    stage,
+    ...(values.profile === undefined ? {} : { profile: values.profile }),
+    ...(values['env-file'] === undefined ? {} : { envFile: values['env-file'] }),
+  };
+  return { json: values.json, kind: 'run', options: { all: values.all }, target };
+};

package/src/verify/cli.test.ts

@@ -0,0 +1,86 @@
+/**
+ * The bin's two pure halves: its flags (args.ts) and its text (report.ts).
+ *
+ * ⛔ NO STAGE IS GUESSED. Alchemy defaults `--stage` to `live_$USER`; a gate that verified that by
+ *   accident would pass while the real stage went unchecked, so a missing stage is an error here.
+ */
+import { describe, expect, test } from 'bun:test';
+import { parseVerifyArgs } from './args.ts';
+import { exitCodeOf, formatReport } from './report.ts';
+import type { AdoptRow } from './rows.ts';
+import type { AdoptReport } from './verify.ts';
+
+describe('parseVerifyArgs', () => {
+  test('takes the flags alchemy plan takes', () => {
+    const parsed = parseVerifyArgs(
+      ['-c', 'alchemy.pbs.ts', '--stage', 'live', '--profile', 'p', '--env-file', '.env', '--all'],
+      {},
+    );
+    expect(parsed).toEqual({
+      json: false,
+      kind: 'run',
+      options: { all: true },
+      target: { entrypoint: 'alchemy.pbs.ts', envFile: '.env', profile: 'p', stage: 'live' },
+    });
+  });
+
+  test('defaults the entrypoint and reads ALCHEMY_STAGE, but never guesses a stage', () => {
+    const parsed = parseVerifyArgs(['--json'], { ALCHEMY_STAGE: 'live' });
+    expect(parsed).toMatchObject({ json: true, target: { entrypoint: 'alchemy.run.ts' } });
+    expect(parseVerifyArgs([], { USER: 'tim' })).toMatchObject({ kind: 'error' });
+  });
+
+  test('an unknown flag or a positional is an error, and --help is help', () => {
+    expect(parseVerifyArgs(['--stage', 'live', '--yes'], {})).toMatchObject({ kind: 'error' });
+    expect(parseVerifyArgs(['--stage', 'live', 'alchemy.run.ts'], {})).toMatchObject({
+      kind: 'error',
+    });
+    expect(parseVerifyArgs(['-h'], {})).toEqual({ kind: 'help' });
+  });
+});
+
+const row = (over: Partial<AdoptRow>): AdoptRow => ({
+  bindings: 0,
+  changed: [],
+  diff: 'noop',
+  fqn: 'house',
+  ok: true,
+  planned: 'adopted',
+  read: 'found',
+  stateRow: false,
+  type: 'Proxmox.Pool',
+  why: '',
+  ...over,
+});
+
+const report = (rows: AdoptRow[]): AdoptReport => ({
+  declared: 5,
+  rows,
+  stack: 'HomeFlareProxmox',
+  stage: 'live',
+});
+
+describe('formatReport', () => {
+  test('a clean report exits 0 and says so', () => {
+    const clean = report([row({})]);
+    expect(exitCodeOf(clean)).toBe(0);
+    expect(formatReport(clean, false)).toContain('every row is a no-op');
+  });
+
+  test('a failing row exits 1, shows its reason and field names, never values', () => {
+    const dirty = report([
+      row({ changed: ['comment'], diff: 'update', ok: false, why: 'the deploy writes' }),
+    ]);
+    const text = formatReport(dirty, false);
+    expect(exitCodeOf(dirty)).toBe(1);
+    expect(text).toContain('FAIL');
+    expect(text).toContain('changed: comment');
+    expect(text).toContain('the deploy writes');
+    expect(text).toContain('1 row(s) are NOT a no-op');
+  });
+
+  test('nothing to verify is a pass that says why', () => {
+    expect(formatReport(report([]), false)).toContain('every declared row already has state');
+    expect(exitCodeOf(report([]))).toBe(0);
+  });
+});

package/src/verify/cli.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * `hf-adopt-verify` — the bin. Parse, verify, print, exit 0 / 1 / 2.
+ *
+ * ★ `runMain` IS ALCHEMY'S (alchemy/Util/PlatformServices), so this runs under bun or node the way
+ *   `alchemy` itself does, and exits once the report is out rather than lingering on keep-alive
+ *   sockets. Run it where the stack's `alchemy` runs: `bunx --bun hf-adopt-verify …` next to
+ *   `bun ./node_modules/alchemy/bin/cli.js plan …`, because the entrypoint it imports is
+ *   TypeScript.
+ * ⛔ EXIT 2 IS "COULD NOT TELL", NEVER A PASS. A plan that fails — a provider that dies, an
+ *   `adopt(false)` row that is not ours, a state store it cannot read — prints the cause and exits
+ *   2, so a gate reading `!= 0` stops either way.
+ */
+import { runMain } from 'alchemy/Util/PlatformServices';
+import * as Cause from 'effect/Cause';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+import { USAGE, parseVerifyArgs } from './args.ts';
+import { exitCodeOf, formatReport } from './report.ts';
+import { verifyStack } from './verify.ts';
+
+const setExit = (code: number) =>
+  Effect.sync(() => {
+    process.exitCode = code;
+  });
+
+const program = Effect.gen(function* () {
+  const parsed = parseVerifyArgs(process.argv.slice(2), process.env);
+  if (parsed.kind === 'help') return yield* Console.log(USAGE);
+  if (parsed.kind === 'error') {
+    yield* Console.error(`hf-adopt-verify: ${parsed.message}\n\n${USAGE}`);
+    return yield* setExit(2);
+  }
+  const report = yield* verifyStack(parsed.target, parsed.options);
+  yield* Console.log(
+    parsed.json
+      ? JSON.stringify(report, null, 2)
+      : formatReport(report, parsed.options.all === true),
+  );
+  yield* setExit(exitCodeOf(report));
+}).pipe(
+  Effect.catchCause((cause) =>
+    Console.error(`hf-adopt-verify: the plan could not be verified\n${Cause.pretty(cause)}`).pipe(
+      Effect.andThen(setExit(2)),
+    ),
+  ),
+);
+
+runMain(program);

package/src/verify/fake-engine.ts

@@ -0,0 +1,182 @@
+/**
+ * A test-only stack: Alchemy's real Plan and Apply over an in-memory state store, and a fake family
+ * whose "cloud" is a Map — so the verifier runs against the engine's own plans with no network.
+ *
+ * ★ THE ENGINE, NOT A HAND-BUILT PLAN. What the verifier claims is about alchemy beta.79: that an
+ *   adopted row's `diff` answer is lost to `forceUpdateAfterAdoption`, that Apply then reconciles
+ *   it, and that a watched plan never writes. openbao/fake-stack.ts measured the same engine for
+ *   the Bao families; this one is family-neutral and records every provider call in order.
+ * ⛔ TEST-ONLY. No provider imports this file.
+ */
+import * as Alchemy from 'alchemy';
+import { AdoptPolicy, Unowned } from 'alchemy/AdoptPolicy';
+import { provideFreshArtifactStore } from 'alchemy/Artifacts';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { type AdoptReport, type VerifyOptions, verifySession } from './verify.ts';
+
+export interface ThingProps {
+  name: string;
+  comment?: string;
+}
+export interface ThingAttributes {
+  name: string;
+  comment: string;
+}
+
+export interface Thing extends Alchemy.Resource<'Test.Thing', ThingProps, ThingAttributes> {}
+export const Thing = Alchemy.Resource<Thing>('Test.Thing');
+
+/** The same object with no `diff`, like a provider that never wrote one. */
+export interface Blind extends Alchemy.Resource<'Test.Blind', ThingProps, ThingAttributes> {}
+export const Blind = Alchemy.Resource<Blind>('Test.Blind');
+
+/**
+ * The same object with a `diff` that compares the RECORDED props with the declaration and never
+ * the live object — the shape of Alchemy's own `Cloudflare.R2Bucket` diff (beta.79
+ * Cloudflare/R2/Bucket.ts: `olds.domains` against `news.domains`). recheck.ts exists for it.
+ */
+export interface Recorded extends Alchemy.Resource<'Test.Recorded', ThingProps, ThingAttributes> {}
+export const Recorded = Alchemy.Resource<Recorded>('Test.Recorded');
+
+/** The fake cloud: what exists, what is someone else's, and every call made to it, in order. */
+export interface Cloud {
+  readonly live: Map<string, string>;
+  readonly unowned: Set<string>;
+  readonly calls: string[];
+}
+
+export const cloudOf = (live: Record<string, string> = {}): Cloud => ({
+  calls: [],
+  live: new Map(Object.entries(live)),
+  unowned: new Set(),
+});
+
+/** Every call that would change the cloud. */
+export const writesOf = (cloud: Cloud): string[] =>
+  cloud.calls.filter((call) => call.startsWith('reconcile') || call.startsWith('delete'));
+
+const lifecycle = (cloud: Cloud) => ({
+  list: () => Effect.succeed([]),
+  read: ({ olds }: { olds: ThingProps }) =>
+    Effect.sync(() => {
+      cloud.calls.push(`read ${olds.name}`);
+      const comment = cloud.live.get(olds.name);
+      if (comment === undefined) return undefined;
+      const found = { comment, name: olds.name };
+      return cloud.unowned.has(olds.name) ? Unowned(found) : found;
+    }),
+  reconcile: ({ news }: { news: ThingProps }) =>
+    Effect.sync(() => {
+      cloud.calls.push(`reconcile ${news.name}`);
+      cloud.live.set(news.name, news.comment ?? '');
+      return { comment: news.comment ?? '', name: news.name };
+    }),
+  delete: ({ olds }: { olds: ThingProps }) =>
+    Effect.sync(() => {
+      cloud.calls.push(`delete ${olds.name}`);
+      cloud.live.delete(olds.name);
+    }),
+});
+
+/** Both fake families over `cloud` — also what tests/fixtures/verify-stack.ts registers. */
+export const thingProviders = (cloud: Cloud) =>
+  Layer.mergeAll(
+    Provider.effect(
+      Thing,
+      Effect.succeed(
+        Thing.Provider.of({
+          ...lifecycle(cloud),
+          diff: ({ news, output }) =>
+            Effect.sync(() => {
+              if (output === undefined || !isResolved(news)) return undefined;
+              cloud.calls.push(`diff ${news.name}`);
+              return cloud.live.get(news.name) === (news.comment ?? '')
+                ? ({ action: 'noop' } as const)
+                : ({ action: 'update' } as const);
+            }),
+        }),
+      ),
+    ),
+    Provider.effect(Blind, Effect.succeed(Blind.Provider.of(lifecycle(cloud)))),
+    Provider.effect(
+      Recorded,
+      Effect.succeed(
+        Recorded.Provider.of({
+          ...lifecycle(cloud),
+          diff: ({ news, olds }) =>
+            Effect.sync(() => {
+              if (!isResolved(news)) return undefined;
+              cloud.calls.push(`diff ${news.name}`);
+              return (olds.comment ?? '') === (news.comment ?? '')
+                ? ({ action: 'noop' } as const)
+                : ({ action: 'update' } as const);
+            }),
+        }),
+      ),
+    ),
+  );
+
+/** A stack body: resource declarations, as an `alchemy.run.ts` would write them. */
+export type Body = Effect.Effect<unknown, unknown, unknown>;
+
+type Compiled = { readonly name: string; readonly stage: string; readonly services: never };
+type PlanView = { readonly resources: Readonly<Record<string, { readonly action: string }>> };
+
+export interface FakeEngine {
+  /** Plan and apply `body`, as `alchemy deploy --adopt` would; resolves to the planned actions. */
+  readonly deploy: (body: Body) => Promise<Record<string, string>>;
+  /** Verify `body` against what the earlier deploys recorded. */
+  readonly verify: (body: Body, options?: VerifyOptions) => Promise<AdoptReport>;
+}
+
+/**
+ * One stack over one state store and any providers, shared by every call — a family's own test
+ * hands in its real provider over a fake transport (proxmox/ceph-pool-adopt.test.ts).
+ * ⚠️ THE CASTS ARE AT THE ENGINE'S TYPED BOUNDARY — openbao/fake-stack.ts has the reasoning.
+ */
+export const engineOver = <ROut, E, RIn>(layer: Layer.Layer<ROut, E, RIn>): FakeEngine => {
+  const state = Alchemy.inMemoryState();
+  const stack = Alchemy.Stack as unknown as (
+    name: string,
+    options: { providers: typeof layer; state: typeof state },
+    body: Body,
+  ) => Effect.Effect<Compiled, unknown, never>;
+  const plan = Alchemy.Plan.make as unknown as (c: Compiled) => Effect.Effect<PlanView, unknown>;
+  const apply = Alchemy.apply as unknown as (planned: PlanView) => Effect.Effect<unknown, unknown>;
+
+  const run = <A>(body: Body, next: (compiled: Compiled) => Effect.Effect<A, unknown, unknown>) =>
+    Effect.runPromise(
+      Effect.gen(function* () {
+        const compiled = yield* stack('VerifyStack', { providers: layer, state }, body);
+        return yield* next(compiled).pipe(Effect.provide(Layer.succeedContext(compiled.services)));
+      }).pipe(
+        Effect.provideService(AdoptPolicy, true),
+        Effect.provideService(Alchemy.Stage, 'test'),
+        Effect.provide(state),
+        Effect.scoped,
+      ) as Effect.Effect<A>,
+    );
+
+  return {
+    deploy: (body) =>
+      run(body, (compiled) =>
+        Effect.gen(function* () {
+          const planned = yield* plan(compiled);
+          yield* apply(planned);
+          return Object.fromEntries(
+            Object.entries(planned.resources).map(([fqn, node]) => [fqn, node.action]),
+          );
+        }).pipe(provideFreshArtifactStore),
+      ),
+    verify: (body, options) =>
+      run(body, (compiled) =>
+        verifySession({ context: compiled.services, stack: compiled as never }, options),
+      ),
+  };
+};
+
+/** The fake family over `cloud`. */
+export const fakeEngine = (cloud: Cloud): FakeEngine => engineOver(thingProviders(cloud));

package/src/verify/index.ts

@@ -0,0 +1,37 @@
+/**
+ * `@homeflare/alchemy/verify` — prove a deploy's adoptions are no-ops before it runs.
+ *
+ * ★ ONE TOOL FOR EVERY STACK, NOT A TEST PER REPO. A stack runs `hf-adopt-verify --config
+ *   alchemy.run.ts --stage live` before a gated deploy, or calls `verifyStack` from its own
+ *   script; both plan with Alchemy's planner and never write. docs/adopt-verify.md has the why,
+ *   the report's columns, and what each kit family does on an adopted deploy.
+ * ⛔ A SUBPATH OF ITS OWN: it imports the stack module from disk and reads the state store, which
+ *   is host access, so it never rides along with the runtime-neutral root entry.
+ */
+export { type Parsed, USAGE, parseVerifyArgs } from './args.ts';
+export { exitCodeOf, formatReport } from './report.ts';
+export {
+  type AdoptRow,
+  type NodeView,
+  type PlanView,
+  type TaskView,
+  changedFields,
+  rowsOf,
+} from './rows.ts';
+export {
+  type DiffAnswer,
+  type Observations,
+  type ReadAnswer,
+  type RecheckAnswer,
+  type Seen,
+  WRITE_REFUSED,
+  spyContext,
+} from './spy.ts';
+export {
+  type AdoptReport,
+  type VerifyOptions,
+  type VerifySession,
+  type VerifyTarget,
+  verifySession,
+  verifyStack,
+} from './verify.ts';

package/src/verify/plan-scope.ts

@@ -0,0 +1,34 @@
+/**
+ * The scope Plan.ts gives every provider call it makes, for the calls the verifier makes itself
+ * after the plan: `--all`'s reads (verify.ts) and the recheck's diffs (recheck.ts).
+ *
+ * ⚠️ RE-CREATED, BECAUSE Plan.ts DOES NOT EXPORT IT (`providePlanScope`, alchemy beta.79): a scoped
+ *   `Artifacts` bag over the run's `ArtifactStore` (a fresh one when none is provided) and the row's
+ *   `InstanceId`. A kit family that consults either — the ownership helpers do — sees what it
+ *   would see under `alchemy plan`. Moved here from verify.ts once a second caller needed it.
+ */
+import {
+  ArtifactStore,
+  Artifacts,
+  createArtifactStore,
+  makeScopedArtifacts,
+} from 'alchemy/Artifacts';
+import { InstanceId } from 'alchemy/InstanceId';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+export const inPlanScope =
+  (fqn: string, instanceId: string) =>
+  <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ): Effect.Effect<A, E, Exclude<R, Artifacts | InstanceId>> =>
+    Effect.gen(function* () {
+      const store = Option.getOrElse(
+        yield* Effect.serviceOption(ArtifactStore),
+        createArtifactStore,
+      );
+      return yield* effect.pipe(
+        Effect.provideService(Artifacts, makeScopedArtifacts(store, fqn)),
+        Effect.provideService(InstanceId, instanceId),
+      );
+    }) as Effect.Effect<A, E, Exclude<R, Artifacts | InstanceId>>;

package/src/verify/recheck.test.ts

@@ -0,0 +1,56 @@
+/**
+ * An adopted row whose provider's `diff` never looks at the live object (recheck.ts).
+ *
+ * 🔴 THE FALSE PASS THIS PINS (red-teamed 2026-09-21). Plan.ts hands an adopted row's diff
+ *   `olds: news`, so a diff that compares recorded props with the declaration answers `noop`
+ *   whatever the cloud holds. The verifier printed `ok` and exited 0 over a drift it had itself
+ *   listed under `changed`, and the deploy then wrote it. The first test fails that way on the
+ *   verifier without recheck.ts.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { Recorded, Thing, cloudOf, fakeEngine, writesOf } from './fake-engine.ts';
+import { exitCodeOf } from './report.ts';
+
+const recorded = (name: string, comment: string) => Recorded(name, { comment, name });
+
+describe('an adopted row whose diff compares recorded props', () => {
+  test('that drifted: asked again with the live value, it says update, and the row fails', async () => {
+    const cloud = cloudOf({ drifted: 'old' });
+    const engine = fakeEngine(cloud);
+    const report = await engine.verify(recorded('drifted', 'new'));
+    expect(report.rows).toEqual([
+      expect.objectContaining({
+        changed: ['comment'],
+        diff: 'noop',
+        ok: false,
+        planned: 'adopted',
+        recheck: 'update',
+      }),
+    ]);
+    expect(report.rows[0]?.why).toContain('recorded props');
+    expect(exitCodeOf(report)).toBe(1);
+    expect(writesOf(cloud)).toEqual([]);
+
+    // ★ And the verdict is the deploy's: the forced reconcile writes the drift the diff hid.
+    expect(await engine.deploy(recorded('drifted', 'new'))).toEqual({ drifted: 'adopted' });
+    expect(cloud.live.get('drifted')).toBe('new');
+  });
+
+  test('that matches: nothing differs, so it is not asked again and passes', async () => {
+    const cloud = cloudOf({ same: 'x' });
+    const report = await fakeEngine(cloud).verify(recorded('same', 'x'));
+    expect(report.rows[0]).toMatchObject({ changed: [], diff: 'noop', ok: true });
+    expect(report.rows[0]?.recheck).toBeUndefined();
+    expect(cloud.calls.filter((call) => call.startsWith('diff'))).toEqual(['diff same']);
+  });
+
+  test('a diff that reads the live object is not asked again when it already said update', async () => {
+    const cloud = cloudOf({ drifted: 'old' });
+    const report = await fakeEngine(cloud).verify(
+      Effect.all([Thing('drifted', { comment: 'new', name: 'drifted' })]),
+    );
+    expect(report.rows[0]).toMatchObject({ diff: 'update', ok: false });
+    expect(report.rows[0]?.recheck).toBeUndefined();
+  });
+});

package/src/verify/recheck.ts

@@ -0,0 +1,71 @@
+/**
+ * Ask an adopted row's `diff` a second time, with the live values as its recorded props, when its
+ * first `noop` sits beside a read that differs from the declaration.
+ *
+ * 🔴 WHY (red-teamed 2026-09-21). Plan.ts hands an adopted row's diff `olds: news`, because the
+ *   adopted state carries `props: news`. A diff that compares the RECORDED props with the
+ *   declaration therefore answers `noop` whatever the cloud holds, and the forced reconcile then
+ *   writes. Alchemy's own `Cloudflare.R2Bucket` diff is that shape (beta.79
+ *   Cloudflare/R2/Bucket.ts, `olds.domains` against `news.domains`). The verifier said `ok`,
+ *   exited 0, and listed the drift under `changed` on the same line. rows.ts already refused to
+ *   trust a MISSING diff for this reason; a diff that never looks at the live object is the same
+ *   blind spot one level down.
+ *
+ * ★ THE QUESTION IS "WOULD YOU STILL SAY noop IF STATE HAD RECORDED WHAT THE READ FOUND?" It is the
+ *   planner's own input, replayed with one change: `olds` carries the read's value for each field
+ *   in `changed`. A diff that reads the live object ignores `olds` and answers as before. Every kit
+ *   PVE/PBS family re-reads (`pveOperations.diff`), so a field its `matches` leaves out, such as
+ *   CephPool's autoscaled `pg_num`, still passes. A diff that compares `olds` now sees the drift.
+ *
+ * ⛔ ONLY `diff`, a read by Alchemy's contract, and through the WATCHED provider, so every write
+ *   path still answers with spy.ts's refusal. The first answer is put back afterwards: the report's
+ *   `diff` column stays what the planner heard.
+ * ⚠️ IT CAN ONLY TURN A PASS INTO A FAIL. It runs on a row that would otherwise pass (adopted,
+ *   `noop`, something in `changed`), and anything but a second `noop`, a failure included, fails it.
+ * ⚠️ SAME-NAMED FIELDS ONLY, like `changed`: a drift in a field whose attribute has another name is
+ *   invisible to both. Whether a `reconcile` PUTs identical values anyway is still up to the
+ *   provider (docs/adopt-verify.md, Limits).
+ */
+import type { ProviderService } from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { inPlanScope } from './plan-scope.ts';
+import { changedFields } from './rows.ts';
+import { type Observations, type RecheckAnswer, diffAnswer } from './spy.ts';
+
+/** The plan-node fields a recheck needs. */
+export interface RecheckNode {
+  readonly action: string;
+  readonly provider?: ProviderService;
+  readonly state?: { readonly instanceId: string };
+}
+
+/** Recheck one planned row if it needs it; the answer lands in `seen` as `recheck`. */
+export const recheck = (fqn: string, node: RecheckNode, seen: Observations): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    const observed = seen.get(fqn);
+    const first = observed?.diff;
+    const input = first?.input;
+    const diff = node.provider?.diff;
+    if (node.action !== 'adopted' || first?.answer !== 'noop' || input === undefined) return;
+    const live = observed?.read?.attributes as Record<string, unknown> | undefined;
+    const changed = changedFields(input.news, live);
+    if (live === undefined || changed.length === 0) return;
+    if (diff === undefined || node.state === undefined) return;
+    const olds = {
+      ...(input.olds as object),
+      ...Object.fromEntries(changed.map((key) => [key, live[key]])),
+    };
+    // ⚠️ THE CAST IS THE ENGINE'S BOUNDARY, as in verify.ts: the diff's requirements are the
+    //   session's, which verifySession provides around this call.
+    const asked = diff({ ...input, olds } as typeof input) as Effect.Effect<unknown>;
+    const answer: RecheckAnswer = yield* asked.pipe(
+      inPlanScope(fqn, node.state.instanceId),
+      Effect.map(diffAnswer),
+      Effect.catchCause(() => Effect.succeed('failed' as const)),
+    );
+    // The watched diff recorded the replay over the planner's answer; put the planner's back.
+    if (observed !== undefined) {
+      observed.diff = first;
+      observed.recheck = answer;
+    }
+  });