@homeflare/alchemy 0.8.0 → 0.10.0

package/src/verify/spy.test.ts

@@ -0,0 +1,141 @@
+/**
+ * The watched providers (spy.ts) and the verdict (rows.ts), without an engine.
+ *
+ * ⛔ THE REFUSALS ARE THE POINT. A verifier that could reach `reconcile` is a deploy with a
+ *   reassuring name; these pin that every write path dies with the same message, on a direct
+ *   service, inside a collection, and on a dual registration's per-mode variant.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import type { ProviderService } from 'alchemy/Provider';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import { changedFields, rowsOf } from './rows.ts';
+import { type Observations, WRITE_REFUSED, spyContext } from './spy.ts';
+
+const calls: string[] = [];
+const service = (): ProviderService =>
+  ({
+    delete: () => Effect.sync(() => void calls.push('delete')),
+    diff: () => Effect.succeed({ action: 'update' }),
+    precreate: () => Effect.sync(() => calls.push('precreate')),
+    read: () => Effect.succeed(Unowned({ comment: 'live', name: 'a' })),
+    reconcile: () => Effect.sync(() => calls.push('reconcile')),
+  }) as unknown as ProviderService;
+
+const input = { fqn: 'a', id: 'a', instanceId: 'i-1', news: {}, olds: {}, output: undefined };
+
+const dies = async (effect: unknown) => {
+  const exit = await Effect.runPromiseExit(effect as Effect.Effect<unknown, unknown>);
+  expect(Exit.isFailure(exit)).toBe(true);
+  expect(String(Exit.isFailure(exit) ? exit.cause : '')).toContain(WRITE_REFUSED);
+};
+
+const watched = (value: unknown, key = 'Test.Thing') => {
+  const seen: Observations = new Map();
+  const context = spyContext(Context.makeUnsafe(new Map([[key, value]])), seen);
+  return { seen, service: context.mapUnsafe.get(key) as ProviderService & Record<string, unknown> };
+};
+
+describe('spyContext', () => {
+  test('every write path dies and nothing reaches the provider', async () => {
+    const { service: spied } = watched(service());
+    await dies(spied.reconcile(input as never));
+    await dies(spied.delete(input as never));
+    await dies(spied.precreate?.(input as never));
+    expect(calls).toEqual([]);
+  });
+
+  test('read and diff pass through and are recorded, Unowned included', async () => {
+    const { seen, service: spied } = watched(service());
+    await Effect.runPromise(spied.read?.(input as never) as Effect.Effect<unknown>);
+    await Effect.runPromise(spied.diff?.(input as never) as Effect.Effect<unknown>);
+    expect(seen.get('a')?.read?.answer).toBe('unowned');
+    expect(seen.get('a')?.read?.attributes).toEqual({ comment: 'live', name: 'a' });
+    expect(seen.get('a')?.diff?.answer).toBe('update');
+  });
+
+  test('a collection and a dual registration are watched too', async () => {
+    const collection = {
+      get: () => service(),
+      kind: 'ProviderCollection',
+      providers: { 'Test.Thing': service() },
+    };
+    const inner = watched(collection, 'Test/Collection').service as unknown as {
+      get: (type: string) => ProviderService;
+    };
+    await dies(inner.get('Test.Thing').reconcile(input as never));
+
+    const dual = {
+      ...service(),
+      modes: { live: Effect.sync(service), local: Effect.sync(service) },
+    };
+    const modes = (watched(dual).service as ProviderService).modes;
+    const live = await Effect.runPromise(modes?.live as Effect.Effect<ProviderService>);
+    await dies(live.delete(input as never));
+    expect(calls).toEqual([]);
+  });
+
+  test('anything that is not a provider is handed over untouched', () => {
+    const value = { some: 'service' };
+    expect(watched(value, 'Other').service).toBe(value as never);
+  });
+});
+
+describe('rows', () => {
+  test('changedFields compares declared, same-named fields by value and names them only', () => {
+    expect(
+      changedFields(
+        { comment: 'new', name: 'a', size: 3, target: { mount: 'm' }, unset: undefined },
+        { comment: 'old', name: 'a', size: 3, unset: 'x' },
+      ),
+    ).toEqual(['comment']);
+    expect(changedFields(undefined, { a: 1 })).toEqual([]);
+  });
+
+  test('a noop row with state and no diff is trusted; an adopted one is not', () => {
+    const seen: Observations = new Map([
+      ['kept', { diff: { answer: 'none', news: {} } }],
+      ['new', { diff: { answer: 'none', news: {} } }],
+    ]);
+    const plan = {
+      deletions: {},
+      resources: {
+        kept: { action: 'noop', resource: { Type: 'T' } },
+        new: { action: 'adopted', resource: { Type: 'T' } },
+      },
+    };
+    const rows = rowsOf(plan, new Set(['kept']), seen, true);
+    expect(rows.map((row) => [row.fqn, row.ok])).toEqual([
+      ['kept', true],
+      ['new', false],
+    ]);
+  });
+
+  test('a stack task that runs is reported in both modes; one that does not, only with all', () => {
+    const plan = {
+      actions: {
+        idle: { action: 'noop', def: { Type: 'Task' } },
+        seed: { action: 'run', def: { Type: 'Task' } },
+      },
+      deletions: {},
+      resources: {},
+    };
+    expect(rowsOf(plan, new Set(), new Map(), false).map((row) => [row.fqn, row.ok])).toEqual([
+      ['seed', false],
+    ]);
+    expect(rowsOf(plan, new Set(), new Map(), true).map((row) => row.fqn)).toEqual([
+      'idle',
+      'seed',
+    ]);
+  });
+
+  test('a noop adoption that brings a binding is not a no-op', () => {
+    const seen: Observations = new Map([['worker', { diff: { answer: 'noop', news: {} } }]]);
+    const node = { action: 'adopted', bindings: [{ action: 'create' }], resource: { Type: 'W' } };
+    const [row] = rowsOf({ deletions: {}, resources: { worker: node } }, new Set(), seen, false);
+    expect(row).toMatchObject({ bindings: 1, ok: false });
+    expect(row?.why).toContain('binding');
+  });
+});

package/src/verify/spy.ts

@@ -0,0 +1,149 @@
+/**
+ * The providers a stack registered, wrapped so the plan can be watched and can never write.
+ *
+ * ★ WHY A WRAPPER AND NOT A LOG LINE. alchemy beta.79 Plan.ts loses the provider's answer on the one
+ *   path that matters: after the cold-start adoption probe it sets `forceUpdateAfterAdoption` and
+ *   maps a `noop` diff to `update`, and the node says `adopted` either way. Nothing is logged, and
+ *   `alchemy plan` has no JSON output — `describePlan` carries only the forced action. The engine
+ *   resolves every provider from the Effect context by resource type (Provider.ts
+ *   `tryFindProviderRegistrationByType`), so the one honest place to hear the raw answer is the
+ *   provider service itself. This hands Alchemy's own `Plan.make` a context whose providers record
+ *   what `read` and `diff` answered, per FQN, and otherwise behave exactly as registered.
+ *
+ * ⛔ EVERY WRITE PATH DIES. `reconcile`, `delete` and `precreate` are replaced, not wrapped: the
+ *   planner never calls them, and a verifier that could reach one by accident is worse than none.
+ *   `read`, `diff`, `list`, `tail` and `logs` pass through — each is a read by Alchemy's contract.
+ *
+ * ⚠️ A MISSING `diff` IS WRAPPED AS ONE ANSWERING `undefined`, which is exactly what the planner
+ *   does without one (`provider?.diff?.(…)` then its own props compare), so behaviour is unchanged
+ *   and the report can say `none` instead of guessing. A missing `read` stays missing: adding one
+ *   would make the planner probe where it otherwise would not.
+ */
+import { Unowned, stripUnowned } from 'alchemy/AdoptPolicy';
+import {
+  type ProviderCollectionService,
+  type ProviderService,
+  isProviderCollectionService,
+  isProviderService,
+} from 'alchemy/Provider';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+
+export type ReadAnswer = 'found' | 'unowned' | 'absent' | 'failed' | 'not-read';
+export type DiffAnswer = 'noop' | 'update' | 'replace' | 'none' | 'not-run';
+
+/** What one FQN's provider answered during the plan — the LAST answer of each kind. */
+export interface Seen {
+  read?: { readonly answer: ReadAnswer; readonly attributes: unknown };
+  diff?: { readonly answer: DiffAnswer; readonly news: unknown };
+}
+
+/** Keyed by FQN. Filled while the plan runs; read once it is done. */
+export type Observations = Map<string, Seen>;
+
+const seenFor = (seen: Observations, fqn: string): Seen => {
+  const existing = seen.get(fqn);
+  if (existing !== undefined) return existing;
+  const fresh: Seen = {};
+  seen.set(fqn, fresh);
+  return fresh;
+};
+
+/** The refusal every write path answers with. Exported so a test can match it. */
+export const WRITE_REFUSED = 'hf-adopt-verify never writes';
+
+const refuse = (type: string, operation: string) => () =>
+  Effect.die(
+    new Error(
+      `${WRITE_REFUSED}: ${type}.${operation} was called during a verification. Alchemy's planner ` +
+        'does not call it, so something other than Plan.make is driving these providers.',
+    ),
+  );
+
+const readAnswer = (attributes: unknown): ReadAnswer =>
+  attributes === undefined ? 'absent' : Unowned.is(attributes) ? 'unowned' : 'found';
+
+const diffAnswer = (diff: unknown): DiffAnswer => {
+  const action = (diff as { action?: unknown } | undefined)?.action;
+  return action === 'noop' || action === 'update' || action === 'replace' ? action : 'none';
+};
+
+/**
+ * One provider service, watched. ⚠️ The spread keeps `version`, `aliases`, `mode`, `stables`,
+ * `list` and the rest exactly as registered — the planner reads several of them.
+ */
+export const spyService = (type: string, service: ProviderService, seen: Observations) => {
+  const read = service.read;
+  const diff = service.diff;
+  const modes = service.modes;
+  const watched: ProviderService = {
+    ...service,
+    diff: (input) =>
+      (diff === undefined ? Effect.succeed(undefined) : diff(input)).pipe(
+        Effect.tap((answer) =>
+          Effect.sync(() => {
+            seenFor(seen, input.fqn).diff = { answer: diffAnswer(answer), news: input.news };
+          }),
+        ),
+      ),
+    reconcile: refuse(type, 'reconcile'),
+    delete: refuse(type, 'delete'),
+  };
+  if (read !== undefined) {
+    watched.read = (input) =>
+      read(input).pipe(
+        Effect.tap((answer) =>
+          Effect.sync(() => {
+            const attributes = answer === undefined ? undefined : stripUnowned(answer);
+            seenFor(seen, input.fqn).read = { answer: readAnswer(answer), attributes };
+          }),
+        ),
+      );
+  }
+  if (service.precreate !== undefined) watched.precreate = refuse(type, 'precreate');
+  // ⚠️ A `ProviderLayer.dual` registration resolves a per-mode variant at plan time
+  //   (Provider.ts `providerForMode`); wrapping only the registration would miss it.
+  if (modes !== undefined) {
+    watched.modes = {
+      live: Effect.map(modes.live, (variant) => spyService(type, variant, seen)),
+      local: Effect.map(modes.local, (variant) => spyService(type, variant, seen)),
+    };
+  }
+  return watched;
+};
+
+const spyCollection = (
+  collection: ProviderCollectionService,
+  seen: Observations,
+): ProviderCollectionService => {
+  const providers = Object.fromEntries(
+    Object.entries(collection.providers).map(([type, service]) => [
+      type,
+      spyService(type, service, seen),
+    ]),
+  );
+  return { ...collection, get: (type: string) => providers[type] as never, providers };
+};
+
+/**
+ * The same context with every provider service — direct or inside a `Provider.collection` —
+ * replaced by its watched copy. Everything else (the state store, the stack, credentials) is the
+ * very object the session built.
+ */
+export const spyContext = <R>(
+  context: Context.Context<R>,
+  seen: Observations,
+): Context.Context<R> => {
+  const services = new Map<string, unknown>();
+  for (const [key, value] of context.mapUnsafe) {
+    services.set(
+      key,
+      isProviderService(value)
+        ? spyService(key, value, seen)
+        : isProviderCollectionService(value)
+          ? spyCollection(value, seen)
+          : value,
+    );
+  }
+  return Context.makeUnsafe<R>(services);
+};

package/src/verify/verify.test.ts

@@ -0,0 +1,124 @@
+/**
+ * The verifier against Alchemy's own planner (fake-engine.ts): what it reports for each kind of row,
+ * and that it never writes while the engine it watches would.
+ *
+ * ★ THE FIRST TEST IS THE MEASUREMENT THE TOOL EXISTS FOR. alchemy beta.79 prints `adopted` for a
+ *   matching object and for a drifting one alike, and the deploy reconciles both. Pinned here so an
+ *   Alchemy upgrade that stops forcing the update — or starts logging the diff — fails loudly and
+ *   this tool can be re-thought rather than silently duplicated.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import {
+  Blind,
+  type Body,
+  type Cloud,
+  Thing,
+  cloudOf,
+  fakeEngine,
+  writesOf,
+} from './fake-engine.ts';
+import { exitCodeOf } from './report.ts';
+
+const one = (name: string, comment?: string) =>
+  Thing(name, comment === undefined ? { name } : { comment, name });
+
+const rowsBy = async (cloud: Cloud, body: Body, all = false) => {
+  const report = await fakeEngine(cloud).verify(body, { all });
+  return { byFqn: Object.fromEntries(report.rows.map((row) => [row.fqn, row])), report };
+};
+
+describe('what alchemy beta.79 does with an adoption', () => {
+  test('prints adopted for a match and for a drift alike, and reconciles both', async () => {
+    const cloud = cloudOf({ same: 'x', drifted: 'old' });
+    const planned = await fakeEngine(cloud).deploy(
+      Effect.all([one('same', 'x'), one('drifted', 'new')]),
+    );
+    expect(planned).toEqual({ drifted: 'adopted', same: 'adopted' });
+    expect(writesOf(cloud).sort()).toEqual(['reconcile drifted', 'reconcile same']);
+  });
+});
+
+describe('verifySession', () => {
+  test('a matching adoption is a no-op, and verifying it writes nothing', async () => {
+    const cloud = cloudOf({ same: 'x' });
+    const { byFqn, report } = await rowsBy(cloud, one('same', 'x'));
+    expect(byFqn['same']).toMatchObject({
+      changed: [],
+      diff: 'noop',
+      ok: true,
+      planned: 'adopted',
+      read: 'found',
+      stateRow: false,
+      type: 'Test.Thing',
+    });
+    expect(exitCodeOf(report)).toBe(0);
+    expect(writesOf(cloud)).toEqual([]);
+    expect(cloud.calls).toEqual(['read same', 'diff same']);
+  });
+
+  test('a drifting adoption says update and names the field, though the engine says adopted', async () => {
+    const cloud = cloudOf({ drifted: 'old' });
+    const { byFqn, report } = await rowsBy(cloud, one('drifted', 'new'));
+    expect(byFqn['drifted']).toMatchObject({
+      changed: ['comment'],
+      diff: 'update',
+      ok: false,
+      planned: 'adopted',
+    });
+    expect(byFqn['drifted']?.why).toContain('the deploy writes');
+    expect(exitCodeOf(report)).toBe(1);
+    expect(writesOf(cloud)).toEqual([]);
+  });
+
+  test('an object the read cannot find is a create, not an adoption', async () => {
+    const cloud = cloudOf();
+    const { byFqn } = await rowsBy(cloud, one('fresh'));
+    expect(byFqn['fresh']).toMatchObject({ diff: 'not-run', ok: false, planned: 'create' });
+    expect(byFqn['fresh']?.read).toBe('absent');
+    expect(byFqn['fresh']?.why).toContain('CREATES');
+  });
+
+  test('an unowned match is a no-op with a note that the deploy needs --adopt', async () => {
+    const cloud = cloudOf({ theirs: 'x' });
+    cloud.unowned.add('theirs');
+    const { byFqn } = await rowsBy(cloud, one('theirs', 'x'));
+    expect(byFqn['theirs']).toMatchObject({ diff: 'noop', ok: true, read: 'unowned' });
+    expect(byFqn['theirs']?.why).toContain('--adopt');
+  });
+
+  test('a provider with no diff cannot prove an adoption', async () => {
+    const cloud = cloudOf({ blind: 'x' });
+    const { byFqn } = await rowsBy(cloud, Blind('blind', { comment: 'x', name: 'blind' }));
+    expect(byFqn['blind']).toMatchObject({ diff: 'none', ok: false, planned: 'adopted' });
+  });
+
+  test('rows with state are left out by default and read afresh with all', async () => {
+    const cloud = cloudOf();
+    const engine = fakeEngine(cloud);
+    await engine.deploy(one('kept', 'x'));
+    cloud.live.set('new', 'y');
+    cloud.calls.length = 0;
+    const body = Effect.all([one('kept', 'x'), one('new', 'y')]);
+
+    const scoped = await engine.verify(body);
+    expect(scoped.rows.map((row) => row.fqn)).toEqual(['new']);
+    expect(scoped.declared).toBe(2);
+
+    const all = await engine.verify(body, { all: true });
+    const kept = all.rows.find((row) => row.fqn === 'kept');
+    expect(kept).toMatchObject({ diff: 'noop', ok: true, planned: 'noop', read: 'found' });
+    expect(kept?.stateRow).toBe(true);
+    expect(writesOf(cloud)).toEqual([]);
+  });
+
+  test('with all, a row no longer declared is a pending delete', async () => {
+    const cloud = cloudOf();
+    const engine = fakeEngine(cloud);
+    await engine.deploy(one('gone', 'x'));
+    const report = await engine.verify(Effect.void, { all: true });
+    expect(report.rows).toEqual([expect.objectContaining({ fqn: 'gone', ok: false })]);
+    expect(report.rows[0]?.planned).toBe('delete');
+    expect(cloud.live.get('gone')).toBe('x');
+  });
+});

package/src/verify/verify.ts

@@ -0,0 +1,172 @@
+/**
+ * Prove a deploy's adoptions are no-ops — with Alchemy's own planner, before anything is written.
+ *
+ * ★ THE ENGINE PLANS, THIS ONLY WATCHES. `verifySession` runs `Plan.make` — the same call
+ *   `alchemy plan` makes (Alchemist routes/stack.ts) — over the session's context with every
+ *   provider swapped for a watched copy (spy.ts). Output resolution, the state lookup, rename
+ *   migrations, the adoption probe and `adopt(…)` all stay the engine's; nothing here re-derives
+ *   them. What it adds is the provider's own `diff` answer, which Plan.ts overwrites for every
+ *   adopted row (`forceUpdateAfterAdoption`), and the state-row check that says which rows ARE
+ *   adoptions.
+ *
+ * ⛔ READ-ONLY BY CONSTRUCTION. The planner calls `read` and `diff`; spy.ts replaces `reconcile`,
+ *   `delete` and `precreate` with refusals; nothing here calls `apply`. `--all` adds one `read` per
+ *   row with state — still a read by Alchemy's provider contract.
+ * ⚠️ READS ARE NOT FREE FOR EVERY FAMILY. A kit PVE/PBS read mints a lease through OpenBao, which
+ *   creates a short-lived API token on the cluster, exactly as `alchemy plan` does.
+ */
+import * as Alchemist from 'alchemy/Alchemist';
+import {
+  ArtifactStore,
+  Artifacts,
+  createArtifactStore,
+  makeScopedArtifacts,
+} from 'alchemy/Artifacts';
+import { InstanceId } from 'alchemy/InstanceId';
+import * as Plan from 'alchemy/Plan';
+import type { ProviderService } from 'alchemy/Provider';
+import type { CompiledStack } from 'alchemy/Stack';
+import { State, isActionState } from 'alchemy/State';
+import type * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import { type AdoptRow, type PlanView, rowsOf } from './rows.ts';
+import { type Observations, spyContext } from './spy.ts';
+
+export interface VerifyOptions {
+  /** Report every declared row and every pending deletion, not only rows without state. */
+  readonly all?: boolean;
+}
+
+export interface AdoptReport {
+  readonly stack: string;
+  readonly stage: string;
+  /** Resources the stack declares. */
+  readonly declared: number;
+  readonly rows: readonly AdoptRow[];
+}
+
+/** An imported stack and the context it plans under — what `Alchemist.open` returns. */
+export interface VerifySession {
+  readonly stack: CompiledStack<unknown, unknown>;
+  readonly context: Context.Context<unknown>;
+}
+
+/** The plan-node fields `--all` needs to read a row that has state. */
+type StatefulNode = {
+  readonly provider?: ProviderService;
+  readonly resource: { readonly LogicalId: string };
+  readonly state?: {
+    readonly instanceId: string;
+    readonly props: object;
+    readonly attr: object | undefined;
+  };
+};
+
+/**
+ * ⚠️ THE SAME SCOPE Plan.ts GIVES ITS OWN READS (`providePlanScope`, not exported): a scoped
+ *   `Artifacts` bag and the row's `InstanceId`. A kit family that consults either — the ownership
+ *   helpers do — sees what it would see under `alchemy plan`.
+ */
+const readWithState = (fqn: string, node: StatefulNode) =>
+  Effect.gen(function* () {
+    const read = node.provider?.read;
+    if (read === undefined || node.state === undefined) return;
+    const store = Option.getOrElse(yield* Effect.serviceOption(ArtifactStore), createArtifactStore);
+    yield* read({
+      fqn,
+      id: node.resource.LogicalId,
+      instanceId: node.state.instanceId,
+      olds: node.state.props,
+      output: node.state.attr,
+    }).pipe(
+      Effect.provideService(Artifacts, makeScopedArtifacts(store, fqn)),
+      Effect.provideService(InstanceId, node.state.instanceId),
+    );
+  });
+
+/** Which of `fqns` the stage's state store holds a resource row for. */
+const withState = (stack: CompiledStack<unknown, unknown>, fqns: readonly string[]) =>
+  Effect.gen(function* () {
+    const store = yield* yield* State;
+    const found = yield* Effect.all(
+      fqns.map((fqn) =>
+        store
+          .get({ fqn, stack: stack.name, stage: stack.stage })
+          .pipe(Effect.map((row) => (row === undefined || isActionState(row) ? [] : [fqn]))),
+      ),
+      { concurrency: 8 },
+    );
+    return new Set(found.flat());
+  });
+
+/**
+ * Plan `session.stack` with watched providers and report each row without state (or, with
+ * `all`, every row). Never writes.
+ */
+export const verifySession = (
+  session: VerifySession,
+  options: VerifyOptions = {},
+): Effect.Effect<AdoptReport, unknown> => {
+  const seen: Observations = new Map();
+  const all = options.all === true;
+  // ⚠️ THE CAST IS AT THE ENGINE'S TYPED BOUNDARY. `Plan.make` declares only `State` and hides the
+  //   rest behind a ts-expect-error; the session context carries all of it, as in routes/stack.ts.
+  const plan = Plan.make(session.stack) as unknown as Effect.Effect<
+    PlanView & { readonly resources: Readonly<Record<string, StatefulNode>> },
+    unknown
+  >;
+  return Effect.gen(function* () {
+    const planned = yield* plan;
+    const stateRows = yield* withState(session.stack, Object.keys(planned.resources));
+    if (all) {
+      const stateful = Object.entries(planned.resources).filter(([fqn]) => stateRows.has(fqn));
+      yield* Effect.all(
+        stateful.map(([fqn, node]) =>
+          readWithState(fqn, node).pipe(
+            Effect.catchCause(() =>
+              Effect.sync(() => {
+                const entry = seen.get(fqn) ?? {};
+                entry.read = { answer: 'failed', attributes: undefined };
+                seen.set(fqn, entry);
+              }),
+            ),
+          ),
+        ),
+        { concurrency: 8 },
+      );
+    }
+    return {
+      declared: Object.keys(planned.resources).length,
+      rows: rowsOf(planned, stateRows, seen, all),
+      stack: session.stack.name,
+      stage: session.stack.stage,
+    } satisfies AdoptReport;
+  }).pipe(Effect.provide(spyContext(session.context, seen)), Effect.scoped);
+};
+
+/** Where the stack lives — the fields `alchemy plan` takes as flags. */
+export interface VerifyTarget {
+  /** The stack entrypoint, e.g. `alchemy.run.ts`. */
+  readonly entrypoint: string;
+  readonly stage: string;
+  readonly profile?: string;
+  readonly envFile?: string;
+}
+
+/**
+ * Import the stack the way the Alchemy CLI does and verify it.
+ *
+ * ★ `adopt: true`, ALWAYS, AND IT CANNOT WRITE. Planning is side-effect free (Plan.ts keeps the
+ *   adopted state in memory, alchemy#793), so the flag only lets an `Unowned` row reach its
+ *   `diff` instead of failing the plan — the report marks it, because the real deploy then needs
+ *   `--adopt`. A resource declared `.pipe(adopt(false))` still fails the plan, as it would deploy.
+ */
+export const verifyStack = (
+  target: VerifyTarget,
+  options: VerifyOptions = {},
+): Effect.Effect<AdoptReport, unknown> =>
+  Effect.gen(function* () {
+    const session = yield* Alchemist.open(target, { adopt: true });
+    return yield* verifySession(session, options);
+  }).pipe(Effect.scoped, Effect.provide(Alchemist.layer()));