@homeflare/alchemy 0.8.0 → 0.10.1

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,210 @@
+/**
+ * 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, RecheckAnswer } from './spy.ts';
+
+export interface AdoptRow {
+  readonly fqn: string;
+  readonly type: string;
+  /**
+   * 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;
+  /** 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 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;
+  /** 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'));
+
+/**
+ * ⛔ 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 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';
+  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 recheck = observed?.recheck;
+  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',
+    ...(recheck === undefined ? {} : { recheck }),
+    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) && proven(recheck) && 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));
+};

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,160 @@
+/**
+ * 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 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 };
+  /**
+   * ★ `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. */
+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';
+
+export 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), input, 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);
+};