@homeflare/alchemy 0.10.0 → 0.11.0

package/src/verify/rows.ts

@@ -7,12 +7,15 @@
  *   this file only decides.
  */
 import { deepEqual, isResolved } from 'alchemy/Diff';
-import type { DiffAnswer, Observations, ReadAnswer } from './spy.ts';
+import type { DiffAnswer, Observations, ReadAnswer, RecheckAnswer } 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. */
+  /**
+   * Whether the row plans from a row the state store holds for it (verify.ts `withState`). An
+   * adoption is a row without one.
+   */
   readonly stateRow: boolean;
   /** The engine's action — what `alchemy plan` prints (`adopted`, `create`, `noop`, …). */
   readonly planned: string;
@@ -23,9 +26,16 @@ export interface AdoptRow {
   /**
    * 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.
+   * rename a field cannot show it here. The diff answer is the verdict; a name here beside an
+   * adopted `noop` only makes recheck.ts ask that diff again.
    */
   readonly changed: readonly string[];
+  /**
+   * What the provider's `diff` answered when asked again with the live values of `changed` as its
+   * recorded props (recheck.ts). Absent when it was not asked: only an adopted `noop` with
+   * something in `changed` is.
+   */
+  readonly recheck?: RecheckAnswer;
   /** Bindings the engine will create, update or delete — reconcile applies them even on `noop`. */
   readonly bindings: number;
   readonly ok: boolean;
@@ -77,9 +87,38 @@ const isNoop = (planned: string, diff: DiffAnswer, stateRow: boolean) =>
   STILL_LIVE.has(planned) &&
   (diff === 'noop' || (diff === 'none' && stateRow && planned === 'noop'));
 
+/**
+ * ⛔ AND A `noop` MUST SURVIVE BEING ASKED WITH THE LIVE VALUES. A diff that compares recorded props
+ *   answers an adopted row `noop` whatever the cloud holds; recheck.ts asks it again, and only a
+ *   second `noop` (or no need to ask) proves anything.
+ */
+const proven = (recheck: RecheckAnswer | undefined) => recheck === undefined || recheck === 'noop';
+
+/** Notes on a row that passes: nothing to say is the common case. */
+const notes = (row: Omit<AdoptRow, 'ok' | 'why'>): string =>
+  [
+    row.read === 'unowned' ? 'unowned: the deploy needs --adopt or adopt(true)' : '',
+    row.recheck === 'noop'
+      ? `${row.changed.join(', ')} differ, but the diff says noop even given the live values: ` +
+        'the family does not manage them, and the deploy leaves them alone'
+      : '',
+  ]
+    .filter((note) => note !== '')
+    .join('; ');
+
 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 (ok) return notes(row);
   if (isNoop(row.planned, row.diff, row.stateRow)) {
+    const live = `the live ${row.changed.join(', ')}`;
+    if (row.recheck === 'failed') {
+      return `asked again with ${live} as recorded props, the provider's diff failed: not proven`;
+    }
+    if (!proven(row.recheck)) {
+      return (
+        `the provider's diff compares recorded props, not the live object: given ${live} it ` +
+        `says ${String(row.recheck)}, and the deploy's forced reconcile writes`
+      );
+    }
     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';
@@ -107,6 +146,7 @@ export const rowFor = (
   seen: Observations,
 ): AdoptRow => {
   const observed = seen.get(fqn);
+  const recheck = observed?.recheck;
   const base = {
     bindings: (node.bindings ?? []).filter((binding) => binding.action !== 'noop').length,
     changed: changedFields(observed?.diff?.news, observed?.read?.attributes),
@@ -114,6 +154,7 @@ export const rowFor = (
     fqn,
     planned: node.action,
     read: observed?.read?.answer ?? 'not-read',
+    ...(recheck === undefined ? {} : { recheck }),
     stateRow,
     type: node.resource.Type,
   } satisfies Omit<AdoptRow, 'ok' | 'why'>;
@@ -122,7 +163,7 @@ export const rowFor = (
    *   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;
+  const ok = isNoop(base.planned, base.diff, stateRow) && proven(recheck) && base.bindings === 0;
   return { ...base, ok, why: reason(base, ok) };
 };
 

package/src/verify/spy.ts

@@ -31,11 +31,22 @@ 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 the diff answered when asked again with the live values as its recorded props (recheck.ts). */
+export type RecheckAnswer = DiffAnswer | 'failed';
+
+/** Exactly what the planner handed a provider's `diff`. */
+export type DiffInput = Parameters<NonNullable<ProviderService['diff']>>[0];
 
 /** 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 };
+  /**
+   * ★ `input` IS THE WHOLE CALL, NOT ONLY `news`, so recheck.ts can ask the same question again
+   *   with one field changed. In memory only; the report carries field names, never values. An
+   *   observation built by hand without it (rows.ts's tests) is simply never rechecked.
+   */
+  diff?: { readonly answer: DiffAnswer; readonly news: unknown; readonly input?: DiffInput };
+  recheck?: RecheckAnswer;
 }
 
 /** Keyed by FQN. Filled while the plan runs; read once it is done. */
@@ -63,7 +74,7 @@ const refuse = (type: string, operation: string) => () =>
 const readAnswer = (attributes: unknown): ReadAnswer =>
   attributes === undefined ? 'absent' : Unowned.is(attributes) ? 'unowned' : 'found';
 
-const diffAnswer = (diff: unknown): DiffAnswer => {
+export const diffAnswer = (diff: unknown): DiffAnswer => {
   const action = (diff as { action?: unknown } | undefined)?.action;
   return action === 'noop' || action === 'update' || action === 'replace' ? action : 'none';
 };
@@ -82,7 +93,7 @@ export const spyService = (type: string, service: ProviderService, seen: Observa
       (diff === undefined ? Effect.succeed(undefined) : diff(input)).pipe(
         Effect.tap((answer) =>
           Effect.sync(() => {
-            seenFor(seen, input.fqn).diff = { answer: diffAnswer(answer), news: input.news };
+            seenFor(seen, input.fqn).diff = { answer: diffAnswer(answer), input, news: input.news };
           }),
         ),
       ),

package/src/verify/verify.test.ts

@@ -8,6 +8,7 @@
  *   this tool can be re-thought rather than silently duplicated.
  */
 import { describe, expect, test } from 'bun:test';
+import { renamedFrom } from 'alchemy';
 import * as Effect from 'effect/Effect';
 import {
   Blind,
@@ -112,6 +113,27 @@ describe('verifySession', () => {
     expect(writesOf(cloud)).toEqual([]);
   });
 
+  /**
+   * ⚠️ A RENAME MAY HAND ITS OLD ID TO A NEW RESOURCE IN THE SAME DEPLOY (alchemy Rename.ts). The
+   *   store still holds the renamer's row at that id, so judging state by FQN alone hid the new
+   *   resource's `create` from the default report. Both rows are without state of their own.
+   */
+  test('a rename that hands its old id to a new resource shows both, the create included', async () => {
+    const cloud = cloudOf();
+    const engine = fakeEngine(cloud);
+    await engine.deploy(one('old', 'x'));
+    const body = Effect.all([
+      Thing('moved', { comment: 'x', name: 'old' }).pipe(renamedFrom('old')),
+      Thing('old', { name: 'fresh' }),
+    ]);
+    const report = await engine.verify(body);
+    const byFqn = Object.fromEntries(report.rows.map((row) => [row.fqn, row]));
+    expect(Object.keys(byFqn).sort()).toEqual(['moved', 'old']);
+    expect(byFqn['old']).toMatchObject({ ok: false, planned: 'create', stateRow: false });
+    expect(byFqn['moved']).toMatchObject({ ok: false, stateRow: false });
+    expect(writesOf(cloud)).toEqual(['reconcile old']);
+  });
+
   test('with all, a row no longer declared is a pending delete', async () => {
     const cloud = cloudOf();
     const engine = fakeEngine(cloud);

package/src/verify/verify.ts

@@ -11,25 +11,20 @@
  *
  * ⛔ 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.
+ *   row with state, and recheck.ts one more `diff` for an adopted `noop` whose read differs from
+ *   the declaration — both still reads 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 { inPlanScope } from './plan-scope.ts';
+import { recheck } from './recheck.ts';
 import { type AdoptRow, type PlanView, rowsOf } from './rows.ts';
 import { type Observations, spyContext } from './spy.ts';
 
@@ -52,8 +47,9 @@ export interface VerifySession {
   readonly context: Context.Context<unknown>;
 }
 
-/** The plan-node fields `--all` needs to read a row that has state. */
+/** The plan-node fields `--all` needs to read a row that has state, and the recheck to replay a diff. */
 type StatefulNode = {
+  readonly action: string;
   readonly provider?: ProviderService;
   readonly resource: { readonly LogicalId: string };
   readonly state?: {
@@ -63,37 +59,49 @@ type StatefulNode = {
   };
 };
 
-/**
- * ⚠️ 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`.
- */
+/** ⚠️ In the scope Plan.ts gives its own reads (plan-scope.ts). */
 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),
-    );
+    }).pipe(inPlanScope(fqn, 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[]) =>
+/**
+ * Which planned rows plan FROM a resource row the stage's state store holds for them.
+ *
+ * ⚠️ THE ROW MUST BE THE ONE THE NODE PLANS FROM, NOT MERELY A ROW AT THE SAME FQN. Alchemy lets a
+ *   rename hand its old id to a new resource in the same deploy (Rename.ts: `Bucket("Assets")
+ *   .pipe(renamedFrom("Bucket"))` beside a fresh `Bucket("Bucket")`). The store still holds the
+ *   renamer's row at `Bucket`, so a check by FQN alone called the reuser stateful and the default
+ *   report hid its `create`. Matching the node's `state.instanceId` also sees the renamer, whose
+ *   row still sits at its FORMER FQN, as a row without state.
+ */
+const withState = (
+  stack: CompiledStack<unknown, unknown>,
+  nodes: Readonly<Record<string, StatefulNode>>,
+) =>
   Effect.gen(function* () {
     const store = yield* yield* State;
     const found = yield* Effect.all(
-      fqns.map((fqn) =>
+      Object.entries(nodes).map(([fqn, node]) =>
         store
           .get({ fqn, stack: stack.name, stage: stack.stage })
-          .pipe(Effect.map((row) => (row === undefined || isActionState(row) ? [] : [fqn]))),
+          .pipe(
+            Effect.map((row) =>
+              row === undefined ||
+              isActionState(row) ||
+              (row as { readonly instanceId?: unknown }).instanceId !== node.state?.instanceId
+                ? []
+                : [fqn],
+            ),
+          ),
       ),
       { concurrency: 8 },
     );
@@ -118,7 +126,12 @@ export const verifySession = (
   >;
   return Effect.gen(function* () {
     const planned = yield* plan;
-    const stateRows = yield* withState(session.stack, Object.keys(planned.resources));
+    const stateRows = yield* withState(session.stack, planned.resources);
+    // ★ Before the rows are judged: an adopted `noop` beside a differing read is asked again.
+    yield* Effect.all(
+      Object.entries(planned.resources).map(([fqn, node]) => recheck(fqn, node, seen)),
+      { concurrency: 8 },
+    );
     if (all) {
       const stateful = Object.entries(planned.resources).filter(([fqn]) => stateRows.has(fqn));
       yield* Effect.all(