@homeflare/alchemy 0.8.0 → 0.10.0

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,158 @@
+/**
+ * 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 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)))),
+  );
+
+/** 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,36 @@
+/**
+ * `@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 Seen,
+  WRITE_REFUSED,
+  spyContext,
+} from './spy.ts';
+export {
+  type AdoptReport,
+  type VerifyOptions,
+  type VerifySession,
+  type VerifyTarget,
+  verifySession,
+  verifyStack,
+} from './verify.ts';

package/src/verify/report.ts

@@ -0,0 +1,52 @@
+/**
+ * The verifier's answer, for a terminal and for a gate.
+ *
+ * ⛔ NAMES, NEVER VALUES. A row lists which declared fields differ from the live object, not what
+ *   either side holds: the tool runs over any stack, and a prop or an attribute can be a secret.
+ *   `alchemy plan --detailed` shows declared values; the family's own read shows live ones.
+ */
+import type { AdoptRow } from './rows.ts';
+import type { AdoptReport } from './verify.ts';
+
+/** 0 when every reported row is a no-op, 1 when any is not. (2 is the CLI's: it could not tell.) */
+export const exitCodeOf = (report: AdoptReport): 0 | 1 =>
+  report.rows.every((row) => row.ok) ? 0 : 1;
+
+const pad = (text: string, width: number) => text.padEnd(width);
+
+const line = (row: AdoptRow, widths: { planned: number; type: number }) => {
+  const head = [
+    row.ok ? 'ok  ' : 'FAIL',
+    pad(row.planned, widths.planned),
+    pad(row.diff, 8),
+    pad(row.read, 9),
+    pad(row.type, widths.type),
+    row.fqn,
+  ].join('  ');
+  const changed = row.changed.length > 0 ? `  changed: ${row.changed.join(', ')}` : '';
+  return row.why === '' ? `${head}${changed}` : `${head}${changed}\n      ${row.why}`;
+};
+
+/** Plain text, one row per line, with the reason under any row that is not a no-op. */
+export const formatReport = (report: AdoptReport, all: boolean): string => {
+  const scope = all ? 'every row' : 'rows without state';
+  const title = `hf-adopt-verify ${report.stack}/${report.stage}: ${String(report.rows.length)} ${scope} (of ${String(report.declared)} declared)`;
+  if (report.rows.length === 0) {
+    return `${title}\nnothing to verify — every declared row already has state. --all checks those too.\n`;
+  }
+  const widths = {
+    planned: Math.max(7, ...report.rows.map((row) => row.planned.length)),
+    type: Math.max(4, ...report.rows.map((row) => row.type.length)),
+  };
+  const header = ['    ', pad('planned', widths.planned), pad('diff', 8), pad('read', 9)]
+    .concat([pad('type', widths.type), 'fqn'])
+    .join('  ');
+  const failed = report.rows.filter((row) => !row.ok).length;
+  const verdict =
+    failed === 0
+      ? 'every row is a no-op: the deploy writes nothing to them'
+      : `${String(failed)} row(s) are NOT a no-op: the deploy would write, create or delete`;
+  return [title, '', header, ...report.rows.map((row) => line(row, widths)), '', verdict, ''].join(
+    '\n',
+  );
+};

package/src/verify/rows.ts

@@ -0,0 +1,169 @@
+/**
+ * One report row per planned resource: what the engine planned, what the provider said, and
+ * whether that adds up to "this deploy leaves the object alone".
+ *
+ * ★ PURE, SO THE VERDICT IS TESTABLE WITHOUT AN ENGINE. verify.ts gathers the three inputs — the
+ *   plan, which FQNs have a state row, and what the watched providers answered (spy.ts) — and
+ *   this file only decides.
+ */
+import { deepEqual, isResolved } from 'alchemy/Diff';
+import type { DiffAnswer, Observations, ReadAnswer } from './spy.ts';
+
+export interface AdoptRow {
+  readonly fqn: string;
+  readonly type: string;
+  /** Whether the state store holds a row for this FQN. An adoption is a row without one. */
+  readonly stateRow: boolean;
+  /** The engine's action — what `alchemy plan` prints (`adopted`, `create`, `noop`, …). */
+  readonly planned: string;
+  /** What the provider's `read` answered, or `not-read` when nothing asked it. */
+  readonly read: ReadAnswer;
+  /** What the provider's own `diff` answered BEFORE Plan.ts forced it (spy.ts). */
+  readonly diff: DiffAnswer;
+  /**
+   * Declared fields whose live value differs, by NAME only — values can be secrets. Compared on
+   * same-named keys of the declaration and the read's attributes, so a family whose attributes
+   * rename a field cannot show it here; the diff answer, not this list, is the verdict.
+   */
+  readonly changed: readonly string[];
+  /** Bindings the engine will create, update or delete — reconcile applies them even on `noop`. */
+  readonly bindings: number;
+  readonly ok: boolean;
+  /** Why the row is not a no-op, or a note on one that is; empty when there is nothing to say. */
+  readonly why: string;
+}
+
+/** The slice of an Alchemy plan node this file reads. */
+export interface NodeView {
+  readonly action: string;
+  readonly resource: { readonly Type: string };
+  readonly bindings?: readonly { readonly action: string }[];
+}
+
+/** A stack task (an Alchemy action): `run`, `noop` or `delete`. It has no provider to ask. */
+export interface TaskView {
+  readonly action: string;
+  readonly def: { readonly Type: string };
+}
+
+/** The slice of an Alchemy `Plan` this file reads. */
+export interface PlanView {
+  readonly resources: Readonly<Record<string, NodeView>>;
+  readonly deletions: Readonly<Record<string, NodeView | undefined>>;
+  readonly actions?: Readonly<Record<string, TaskView | undefined>>;
+}
+
+/** Same-named, declared, resolved fields where the live value differs. */
+export const changedFields = (declared: unknown, live: unknown): string[] => {
+  if (typeof declared !== 'object' || declared === null) return [];
+  if (typeof live !== 'object' || live === null) return [];
+  const actual = live as Record<string, unknown>;
+  return Object.entries(declared as Record<string, unknown>)
+    .filter(([key, value]) => value !== undefined && key in actual && isResolved(value))
+    .filter(([key, value]) => !deepEqual(value, actual[key]))
+    .map(([key]) => key)
+    .sort();
+};
+
+const STILL_LIVE = new Set(['adopted', 'noop']);
+
+/**
+ * ⛔ `adopted` NEEDS THE PROVIDER'S OWN `noop`. With no diff (`none`) the engine compared the
+ *   declaration with the declaration — an adopted row's state carries `props: news` (Plan.ts) — so
+ *   its noop proves nothing. A row with state is different: there the engine compared against the
+ *   props it last deployed, which is the same check `alchemy plan` makes.
+ */
+const isNoop = (planned: string, diff: DiffAnswer, stateRow: boolean) =>
+  STILL_LIVE.has(planned) &&
+  (diff === 'noop' || (diff === 'none' && stateRow && planned === 'noop'));
+
+const reason = (row: Omit<AdoptRow, 'ok' | 'why'>, ok: boolean): string => {
+  if (ok) return row.read === 'unowned' ? 'unowned: the deploy needs --adopt or adopt(true)' : '';
+  if (isNoop(row.planned, row.diff, row.stateRow)) {
+    return `${String(row.bindings)} binding(s) change: the deploy reconciles them though the diff is noop`;
+  }
+  if (row.planned === 'delete') return 'no longer declared: the deploy deletes it';
+  if (row.planned === 'orphaned') return 'no longer declared: the deploy drops its state (retain)';
+  if (row.read === 'failed') return "the verifier's own read of it failed";
+  if (row.planned === 'create') {
+    if (row.stateRow) return 'an interrupted create: the deploy finishes creating it';
+    return row.read === 'absent'
+      ? 'the read found nothing, so the deploy CREATES it (a lane that cannot see it reads the same)'
+      : 'never probed (a prop is an Output of another resource, or the provider has no read): ' +
+          'the deploy CREATES it';
+  }
+  if (row.diff === 'update') return "the provider's diff says update: the deploy writes";
+  if (row.diff === 'replace') return "the provider's diff says replace: a new one, then a delete";
+  if (row.diff === 'none') {
+    return 'the provider has no diff, so the engine compared the declaration with itself';
+  }
+  return `the engine plans ${row.planned} although the diff says ${row.diff} (a renamed row, changed bindings or --force)`;
+};
+
+export const rowFor = (
+  fqn: string,
+  node: NodeView,
+  stateRow: boolean,
+  seen: Observations,
+): AdoptRow => {
+  const observed = seen.get(fqn);
+  const base = {
+    bindings: (node.bindings ?? []).filter((binding) => binding.action !== 'noop').length,
+    changed: changedFields(observed?.diff?.news, observed?.read?.attributes),
+    diff: observed?.diff?.answer ?? 'not-run',
+    fqn,
+    planned: node.action,
+    read: observed?.read?.answer ?? 'not-read',
+    stateRow,
+    type: node.resource.Type,
+  } satisfies Omit<AdoptRow, 'ok' | 'why'>;
+  /**
+   * ⚠️ A NOOP DIFF DOES NOT COVER BINDINGS. Plan.ts diffs them separately and hands every
+   *   non-noop binding to `reconcile`, which an adopted row reaches anyway — a Worker adopted with
+   *   a new binding writes although its own diff said nothing changed.
+   */
+  const ok = isNoop(base.planned, base.diff, stateRow) && base.bindings === 0;
+  return { ...base, ok, why: reason(base, ok) };
+};
+
+/**
+ * ⚠️ A TASK THAT RUNS IS A WRITE THE PROVIDERS NEVER SEE, so it is reported in both modes; a task
+ *   that would not run appears only with `all`.
+ */
+const taskRow = (fqn: string, task: TaskView): AdoptRow => ({
+  bindings: 0,
+  changed: [],
+  diff: 'not-run',
+  fqn,
+  ok: task.action === 'noop',
+  planned: task.action,
+  read: 'not-read',
+  stateRow: task.action !== 'run',
+  type: task.def.Type,
+  why: task.action === 'noop' ? '' : `a stack task: the deploy will ${task.action} it`,
+});
+
+/**
+ * The rows to report. Without `all`, only rows WITHOUT a state row — the adoptions and creates a
+ * deploy would perform — which is the question this tool exists for, plus any task that runs. With
+ * `all`, every declared row, every pending deletion and every task.
+ */
+export const rowsOf = (
+  plan: PlanView,
+  stateRows: ReadonlySet<string>,
+  seen: Observations,
+  all: boolean,
+): AdoptRow[] => {
+  const declared = Object.entries(plan.resources)
+    .filter(([fqn]) => all || !stateRows.has(fqn))
+    .map(([fqn, node]) => rowFor(fqn, node, stateRows.has(fqn), seen));
+  const removed = all
+    ? Object.entries(plan.deletions).flatMap(([fqn, node]) =>
+        node === undefined ? [] : [rowFor(fqn, node, true, seen)],
+      )
+    : [];
+  const tasks = Object.entries(plan.actions ?? {}).flatMap(([fqn, task]) =>
+    task === undefined || (!all && task.action === 'noop') ? [] : [taskRow(fqn, task)],
+  );
+  return [...declared, ...removed, ...tasks].sort((a, b) => a.fqn.localeCompare(b.fqn));
+};