@homeflare/alchemy 0.59.0 → 0.60.0

package/src/caddy/config.ts

@@ -28,12 +28,10 @@
  *   place that discharges them — scoped to the handful of effects that actually call
  *   `@distilled.cloud/caddy`'s operations, never leaking into a sibling fetch-based provider merged
  *   into the same stack (admin.ts's own ⛔; MEASURED 2026-09-26, admin-transport-scope.test.ts).
- * ⛔ `CaddyConfig` IS WRAPPED IN `guardDuplicateIds` (scope/guard.ts). MEASURED, homeflare-mini PR
- *   329: a `NixJobRetirement('caddy', …)` declared in the same stack as this resource's `CADDY_ID
- *   = 'caddy'` collided silently — Alchemy's own `Resource()` treated the second registration as
- *   an idempotent re-reference to the first, so the retirement's props were never written
- *   anywhere a plan could see (`scope/duplicate-id.ts` has the full mechanism). This resource was
- *   one half of that collision, so it is the first to carry the guard.
+ * ⚠️ `CADDY_ID`-style collisions with another resource's id in the same stack (MEASURED,
+ *   homeflare-mini PR 329: `NixJobRetirement('caddy', …)` beside this resource's own `caddy`)
+ *   are refused by the patched `alchemy` every consuming stack applies — not by anything in
+ *   this file. See `packages/alchemy/docs/duplicate-resource-id.md`.
  */
 import { Resource } from 'alchemy';
 import { Unowned } from 'alchemy/AdoptPolicy';
@@ -42,7 +40,6 @@ import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import { resolvedString } from '../launchd/host-effect.ts';
 import { adoptEnabled } from '../ownership/adopt.ts';
-import { guardDuplicateIds } from '../scope/guard.ts';
 import { CaddyAdminService, CaddyAdminTransport } from './admin.ts';
 import { isUnreachable } from './caddy-http-client.ts';
 import type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
@@ -58,11 +55,9 @@ export interface CaddyConfig extends Resource<
   CaddyConfigAttributes
 > {}
 
-export const CaddyConfig = guardDuplicateIds(
-  Resource<CaddyConfig>('Caddy.Config', {
-    defaultRemovalPolicy: 'retain',
-  }),
-);
+export const CaddyConfig = Resource<CaddyConfig>('Caddy.Config', {
+  defaultRemovalPolicy: 'retain',
+});
 
 /**
  * ⚠️ A STOPPED CADDY MUST NOT FAIL THE PLAN THAT BRINGS IT BACK. Its launchd job usually sits in the

package/src/scope/duplicate-id.test.ts

@@ -1,95 +1,154 @@
 /**
- * `claimResourceId` against a minimal `Stack` + `Namespace` context — no real resources, no
- * provider, so these stay fast and pin the registry's own semantics directly. guard.test.ts
- * drives the same cases through a REAL `Alchemy.Stack(...)` with real `Resource()` classes, to
- * prove the wiring in guard.ts, not just this file's logic in isolation.
+ * The regression test for the measured incident (homeflare-mini PR 329): two different
+ * resource types sharing a logical id in one stack, driven through a REAL `Alchemy.Stack(...)`
+ * with real `Resource()` classes over the patched `alchemy` this package's own root
+ * `patchedDependencies` applies (see `../../../patches/alchemy@2.0.0-beta.81.patch`) — the same
+ * shape `litellm/fake-stack.ts` uses for the same reason its own header gives: a diff answer
+ * proves nothing about what the ENGINE actually does; only running it does.
+ *
+ * ⚠️ IF THIS SUITE EVER PASSES WITHOUT THE PATCH APPLIED, THE PATCH IS NOT REACHING THIS
+ *   PACKAGE'S OWN TESTS — re-run `bun install` at the workspace root and re-check
+ *   `patchedDependencies` in the root `package.json`. `patch-check.test.ts` is the test that
+ *   would catch that for a CONSUMER; this file has no equivalent self-check because it would
+ *   just be this file re-asserting itself.
  */
 import { describe, expect, test } from 'bun:test';
+import * as Alchemy from 'alchemy';
 import { push as pushNamespace } from 'alchemy/Namespace';
-import { Stack } from 'alchemy/Stack';
+import type { Resource } from 'alchemy/Resource';
 import * as Effect from 'effect/Effect';
-import { DuplicateResourceIdError, claimResourceId } from './duplicate-id.ts';
+import * as Layer from 'effect/Layer';
+import ownPackage from '../../package.json';
+import { PATCHED_ALCHEMY_VERSION } from './duplicate-id.ts';
 
-/** A bare `Stack` service good enough for `claimResourceId`: only `resources` is ever `yield*`ed. */
-const fakeStack = () => ({ name: 'test', stage: 'test', resources: {}, bindings: {}, actions: {} });
+interface Props {
+  readonly value?: number;
+}
+/** A plain, otherwise-meaningless resource shape — only the `Type` string matters here. */
+interface TestResource extends Resource<string, Props, object> {}
+const testResource = (type: string) => Alchemy.Resource<TestResource>(type);
 
-const withStack = <A, E>(effect: Effect.Effect<A, E, Stack>) =>
-  effect.pipe(Effect.provideService(Stack, fakeStack() as never));
+type StackBody = Effect.Effect<unknown, unknown, unknown>;
 
-describe('claimResourceId', () => {
-  test('a fresh id is claimed without error', async () => {
-    await Effect.runPromise(withStack(claimResourceId('Test.A', 'one')));
+const stack = Alchemy.Stack as unknown as (
+  stackName: string,
+  options: { providers: Layer.Layer<never>; state: ReturnType<typeof Alchemy.inMemoryState> },
+  body: StackBody,
+) => Effect.Effect<{ readonly resources: Record<string, unknown> }, unknown, never>;
+
+const run = (body: StackBody, name: string) =>
+  Effect.runPromiseExit(
+    stack(name, { providers: Layer.empty, state: Alchemy.inMemoryState() }, body).pipe(
+      Effect.provideService(Alchemy.Stage, 'test'),
+      Effect.scoped,
+    ),
+  );
+
+describe('PATCHED_ALCHEMY_VERSION', () => {
+  test('matches this package’s own peer pin, so a bump that forgets to re-cut the patch fails here', () => {
+    expect(PATCHED_ALCHEMY_VERSION).toBe(ownPackage.peerDependencies.alchemy);
   });
+});
 
-  test('the same type re-claiming its own id is fine (idempotent re-reference)', async () => {
-    await Effect.runPromise(
-      withStack(
-        Effect.gen(function* () {
-          yield* claimResourceId('Test.A', 'one');
-          yield* claimResourceId('Test.A', 'one');
-        }),
-      ),
+describe('the patched alchemy, driven through a real Stack', () => {
+  test('two different types sharing an id die naming both', async () => {
+    const Retirement = testResource('Nix.JobRetirement');
+    const Caddy = testResource('Caddy.Config');
+    const exit = await run(
+      Effect.gen(function* () {
+        yield* Retirement('caddy', { value: 1 });
+        yield* Caddy('caddy', { value: 2 });
+      }),
+      'IncidentStack',
+    );
+    expect(exit._tag).toBe('Failure');
+    if (exit._tag !== 'Failure') return;
+    const [reason] = (exit.cause as { reasons: readonly { _tag: string; defect?: unknown }[] })
+      .reasons;
+    expect(reason === undefined ? undefined : reason._tag).toBe('Die');
+    const defect = reason === undefined ? undefined : (reason.defect as { message?: string });
+    expect(defect?.message).toContain(
+      'REFUSING: duplicate resource id "caddy" in scope (root): ' +
+        'first declared by Nix.JobRetirement, again by Caddy.Config',
     );
   });
 
-  test('distinct ids never collide', async () => {
-    await Effect.runPromise(
-      withStack(
-        Effect.gen(function* () {
-          yield* claimResourceId('Test.A', 'one');
-          yield* claimResourceId('Test.B', 'two');
-        }),
-      ),
+  test('the reverse order dies the same way — order never decides the winner', async () => {
+    const Retirement = testResource('Nix.JobRetirement');
+    const Caddy = testResource('Caddy.Config');
+    const exit = await run(
+      Effect.gen(function* () {
+        yield* Caddy('caddy', { value: 2 });
+        yield* Retirement('caddy', { value: 1 });
+      }),
+      'IncidentStackReversed',
     );
+    expect(exit._tag).toBe('Failure');
   });
 
-  test('a second, different type claiming a taken id dies naming both types', async () => {
-    const run = Effect.runPromiseExit(
-      withStack(
-        Effect.gen(function* () {
-          yield* claimResourceId('Nix.JobRetirement', 'caddy');
-          yield* claimResourceId('Caddy.Config', 'caddy');
-        }),
-      ),
+  test('the same type re-registering its own id stays a noop, not a death', async () => {
+    const A = testResource('Test.A');
+    const exit = await run(
+      Effect.gen(function* () {
+        yield* A('shared', { value: 1 });
+        yield* A('shared', { value: 1 });
+      }),
+      'GoodStack',
     );
-    const exit = await run;
-    expect(exit._tag).toBe('Failure');
-    if (exit._tag !== 'Failure') return;
-    const [reason] = exit.cause.reasons;
-    const defect = reason?._tag === 'Die' ? reason.defect : undefined;
-    expect(defect).toBeInstanceOf(DuplicateResourceIdError);
-    const error = defect as DuplicateResourceIdError;
-    expect(error.message).toContain('REFUSING: duplicate resource id "caddy"');
-    expect(error.message).toContain('first declared by Nix.JobRetirement');
-    expect(error.message).toContain('again by Caddy.Config');
-    expect(error.scope).toBe('(root)');
+    expect(exit._tag).toBe('Success');
   });
 
-  test('the same id in a nested namespace is a different scope, so it does not collide', async () => {
-    await Effect.runPromise(
-      withStack(
-        Effect.gen(function* () {
-          yield* claimResourceId('Caddy.Config', 'caddy');
-          yield* pushNamespace('child', claimResourceId('Nix.JobRetirement', 'caddy'));
-        }),
-      ),
+  test('distinct ids never collide', async () => {
+    const A = testResource('Test.A');
+    const B = testResource('Test.B');
+    const exit = await run(
+      Effect.gen(function* () {
+        yield* A('one', { value: 1 });
+        yield* B('two', { value: 2 });
+      }),
+      'DistinctStack',
     );
+    expect(exit._tag).toBe('Success');
   });
 
-  test('two unrelated stacks never see each others claims', async () => {
-    const stackOne = fakeStack();
-    const stackTwo = fakeStack();
-    await Effect.runPromise(
-      claimResourceId('Caddy.Config', 'caddy').pipe(
-        Effect.provideService(Stack, stackOne as never),
-      ),
+  test('the same id in a nested namespace is a different scope', async () => {
+    const A = testResource('Test.A');
+    const B = testResource('Test.B');
+    const exit = await run(
+      Effect.gen(function* () {
+        yield* A('shared', { value: 1 });
+        yield* pushNamespace('child', B('shared', { value: 2 }));
+      }),
+      'NestedStack',
     );
-    // A DIFFERENT stack object claiming the same id with a different type is fine — the
-    // registry is keyed by the Stack instance (see duplicate-id.ts), not the bare fqn string.
-    await Effect.runPromise(
-      claimResourceId('Nix.JobRetirement', 'caddy').pipe(
-        Effect.provideService(Stack, stackTwo as never),
-      ),
+    expect(exit._tag).toBe('Success');
+  });
+
+  test('the thrown defect carries the exact fields DuplicateResourceIdError documents', async () => {
+    const A = testResource('Test.A');
+    const B = testResource('Test.B');
+    const exit = await run(
+      Effect.gen(function* () {
+        yield* A('x', {});
+        yield* B('x', {});
+      }),
+      'ShapeStack',
     );
+    expect(exit._tag).toBe('Failure');
+    if (exit._tag !== 'Failure') return;
+    const [reason] = (exit.cause as { reasons: readonly { defect?: unknown }[] }).reasons;
+    // Not `instanceof DuplicateResourceIdError` — alchemy's patched copy and this package's
+    // export are two separately defined classes with the same `_tag` by construction
+    // (duplicate-id.ts's own header explains why `catchTag` still works across that split).
+    const defect = reason?.defect as {
+      _tag?: string;
+      fqn?: string;
+      firstType?: string;
+      secondType?: string;
+    };
+    expect(defect._tag).toBe('DuplicateResourceIdError');
+    expect(defect.fqn).toBe('x');
+    expect(defect.firstType).toBe('Test.A');
+    expect(defect.secondType).toBe('Test.B');
   });
 });

package/src/scope/duplicate-id.ts

@@ -1,113 +1,55 @@
 /**
- * Refuse a second resource claiming a logical id already taken in the same stack scope.
+ * `DuplicateResourceIdError` and the pinned alchemy version the kit's patch targets.
  *
- * ★ WHY THIS EXISTS (measured, homeflare-mini PR 329, Tim 2026-10-19). `NixJobRetirement('caddy',
- *   …)` and `Caddy.Config` (`CADDY_ID = 'caddy'`) both declared logical id `caddy` in one stack.
- *   Alchemy's own `Resource()` constructor treats a second `yield*` at an already-claimed FQN as
- *   an idempotent re-reference — correct for "the same resource, read from two call sites" — and
- *   returns the FIRST-registered resource without ever comparing `Type` (`Resource.ts`, the
- *   `if (existing) { … return existing; }` branch; a sibling TODO there already flags a related
- *   gap — "check if props are different and die"). The SECOND resource's props are never written
- *   anywhere: `stack.resources[fqn]` never changes, so nothing downstream — not `Plan.make`, not a
- *   later inspection of the compiled stack — can tell two different registrations ever happened.
- *   Measured directly (dup-experiment.ts, this PR): registering `Test.ResourceB('shared-id', …)`
- *   after `Test.ResourceA('shared-id', …)` compiles a stack whose ONLY entry at that fqn reports
- *   `Type: 'Test.ResourceA'` — the second declaration leaves no trace to check after the fact.
- * ★ WHY THE CHECK CANNOT BE BOLTED ON AFTER THE FACT. Because the losing registration leaves no
- *   trace (above), a guard built from `CompiledStack.resources` — inspected after the stack's body
- *   has run, e.g. before `Plan.make` — sees only one entry per fqn and cannot know a second,
- *   different-typed claim ever happened. The only point where both the existing claim AND the new
- *   claimant's `Type` are both in hand is at the moment of registration, which is why this module
- *   is a REGISTRY populated and checked as each resource is `yield*`ed (see `guard.ts`), not a
- *   post-hoc scan.
- * ⛔ UPSTREAM IS THE RIGHT HOME FOR THE REAL FIX. The comparison belongs in `Resource.ts` itself,
- *   right where its own TODO already sits — every resource (ours and every vendor built-in) goes
- *   through that one function, and this kit cannot wrap a type it does not author (e.g.
- *   `Cloudflare.Worker`). This module is the house-side stopgap decision 49 allows ("a house rule
- *   only fills a gap upstream is silent on"): it protects any TWO resources that both go through
- *   `guardDuplicateIds` (guard.ts), which is everywhere this kit's own providers adopt it. The
- *   upstream issue text proposing the real fix is in this PR's body.
+ * ★ THE FIX ITSELF IS NOT HERE. A second resource of a different type claiming an id already
+ *   taken in one stack scope is refused by a PATCH to `alchemy`'s own `Resource.ts` — see
+ *   `../../patches/alchemy@2.0.0-beta.81.patch` and docs/duplicate-resource-id.md for why a
+ *   kit-side `Proxy` wrapper (PR 468's first version, replaced by this PR) cannot actually
+ *   catch the incident it was built for: wrapping `@homeflare/alchemy`'s OWN resource exports
+ *   never reaches `NixJobRetirement`, a resource homeflare-mini declares directly against
+ *   `alchemy`'s `Resource()`, so the measured collision still succeeded silently in BOTH
+ *   orderings. This file now holds only:
+ *
+ *   1. `DuplicateResourceIdError` — the exact shape the patched `alchemy` throws, duplicated
+ *      here (not imported — `alchemy` cannot depend on `@homeflare/alchemy`) purely so a
+ *      consumer can write `Effect.catchTag("DuplicateResourceIdError", …)` against a type this
+ *      package exports, without needing to know alchemy carries its own copy of the same tag.
+ *      Effect dispatches `catchTag` on the `_tag` STRING, not `instanceof`, so either class
+ *      works identically as a catch target.
+ *   2. `PATCHED_ALCHEMY_VERSION` — the exact alchemy version the patch was cut against.
+ *      Hardcoded, like `ESTATE_VERSIONS` in `@homeflare/config/versions` (the same reasoning:
+ *      a second source of truth derived by import would cross `tsconfig.build.json`'s
+ *      `rootDir: "src"` boundary to reach `package.json`). `duplicate-id.test.ts` asserts it
+ *      still matches this package's own `peerDependencies.alchemy`, so a pin bump that forgets
+ *      to re-cut the patch fails a test here instead of silently shipping a patch filename that
+ *      no longer matches what consumers install.
  */
-import { toFqn } from 'alchemy/FQN';
-import { CurrentNamespace, type NamespaceNode } from 'alchemy/Namespace';
-import { Stack } from 'alchemy/Stack';
 import * as Data from 'effect/Data';
-import * as Effect from 'effect/Effect';
 
 /**
- * Two resources of different types both claimed `fqn` in `scope`. Carries both type names so the
- * message — and any catcher — can tell the attacker from the defender without re-deriving them.
+ * Mirrors the error the patched `alchemy@2.0.0-beta.81` throws at registration — same `_tag`,
+ * same fields — for a consumer that wants to `catchTag` it without importing from `alchemy`'s
+ * own patched internals.
+ *
+ * ⚠️ ONLY `Type` IS COMPARED, NEVER `Props`. A platform-typed resource's tagged pattern
+ * (`alchemy`'s own `Platform.ts` ~581) rewrites `Props` on a resource already registered, and a
+ * bare-tag forward reference legitimately registers with `Props: undefined` until its
+ * `.make(...)` Layer builds (`MissingImplementationError`'s own doc comment in `Resource.ts`).
+ * Comparing props as well as type would make both of those die. `Type` is stable from a
+ * resource's very first `yield*` and is exactly what distinguishes "the same resource,
+ * referenced twice" (fine) from "two different resources that picked the same id" (refused).
  */
 export class DuplicateResourceIdError extends Data.TaggedError('DuplicateResourceIdError')<{
   message: string;
   fqn: string;
-  scope: string;
+  /** The type that first claimed `fqn`. */
   firstType: string;
+  /** The different type that tried to claim it again. */
   secondType: string;
 }> {}
 
-const scopeLabel = (namespace: NamespaceNode | undefined): string => {
-  if (!namespace) return '(root)';
-  const path: string[] = [];
-  let node: NamespaceNode | undefined = namespace;
-  while (node) {
-    path.unshift(node.Id);
-    node = node.Parent;
-  }
-  return path.join('/');
-};
-
-/**
- * One registry per compiled stack, keyed by the `Stack` service object `yield* Stack` returns
- * (a fresh `StackSpec` per `Alchemy.Stack(...)`/`make()` call — see `Stack.ts`'s `Layer.effect`).
- * A `WeakMap` so two unrelated stacks (sequential test runs, two stacks in one process) never see
- * each other's claims, and so the registry is collected with the stack instead of growing forever
- * in a long-running process (an `alchemy dev` watch loop, this package's own test suite).
- */
-const registries = new WeakMap<object, Map<string, string>>();
-
-const registryFor = (stack: object): Map<string, string> => {
-  const existing = registries.get(stack);
-  if (existing) return existing;
-  const created = new Map<string, string>();
-  registries.set(stack, created);
-  return created;
-};
-
 /**
- * Claim `id` for `type` in the current namespace scope. Fine the first time, and fine again for
- * the SAME type (the legitimate "yield the same resource from two call sites" pattern Alchemy's
- * own idempotent registration supports). Dies with {@link DuplicateResourceIdError} the moment a
- * DIFFERENT type claims an id already taken — before that second resource's provider ever runs.
- *
- * ⚠️ `Effect.die`, NOT a typed failure. This runs at registration, not inside a lifecycle
- * operation (`read`/`diff`/`reconcile`/`delete`) — the provider-standard's S20 ban on
- * `Effect.orDie` in LIFECYCLE operations does not apply here, and `ConflictingProviderModeError`
- * right next door in upstream's own `Resource.ts` dies the same way for the same reason: there is
- * no recovery a caller could usefully attempt mid-registration.
+ * The exact `alchemy` version `patches/alchemy@2.0.0-beta.81.patch` was cut against.
+ * `duplicate-id.test.ts` keeps this honest against `package.json`'s own `peerDependencies`.
  */
-export const claimResourceId = (type: string, id: string): Effect.Effect<void, never, Stack> =>
-  Effect.gen(function* () {
-    const stack = yield* Stack;
-    const namespace = yield* CurrentNamespace;
-    const fqn = toFqn(namespace, id);
-    const registry = registryFor(stack);
-    const firstType = registry.get(fqn);
-    if (firstType === undefined) {
-      registry.set(fqn, type);
-      return;
-    }
-    if (firstType !== type) {
-      return yield* Effect.die(
-        new DuplicateResourceIdError({
-          message:
-            `REFUSING: duplicate resource id "${fqn}" in scope ${scopeLabel(namespace)}: ` +
-            `first declared by ${firstType}, again by ${type}`,
-          fqn,
-          scope: scopeLabel(namespace),
-          firstType,
-          secondType: type,
-        }),
-      );
-    }
-  });
+export const PATCHED_ALCHEMY_VERSION: string = '2.0.0-beta.81';

package/src/scope/index.ts

@@ -1,20 +1,22 @@
 /**
- * `@homeflare/alchemy/scope` — refuse a second resource claiming a logical id already taken in
- * the same stack scope, instead of Alchemy's own `Resource()` silently treating it as the same
- * resource re-referenced (see duplicate-id.ts for the measured incident and why the check has to
- * run at registration time). Every `@homeflare/alchemy` resource export wrapped in
- * `guardDuplicateIds` gets this for free; a stack's OWN custom resource types (declared directly
- * with Alchemy's `Resource()`, the way homeflare-mini's `NixJobRetirement` is) get it too, by
- * wrapping their export the same way:
+ * `@homeflare/alchemy/scope` — a consuming stack's own check that it carries the
+ * duplicate-resource-id patch, and the error shape that patch throws.
+ *
+ * The fix itself is a patch to `alchemy`'s own `Resource.ts`
+ * (`../../patches/alchemy@2.0.0-beta.81.patch`), applied at EACH consuming stack's own root
+ * (`alchemy` is a peer dependency here, so `patchedDependencies` in this package's manifest
+ * only reaches this package's own install, never a consumer's). docs/duplicate-resource-id.md
+ * has the full guide, the exact `bun patch` workflow, and what this does and does not cover.
  *
  * ```ts
- * import { guardDuplicateIds } from '@homeflare/alchemy/scope';
+ * import { checkAlchemyPatch } from '@homeflare/alchemy/scope';
  *
- * export const NixJobRetirement = guardDuplicateIds(Resource<NixJobRetirement>('Nix.JobRetirement'));
+ * const problems = await checkAlchemyPatch(import.meta.dirname);
+ * if (problems.length > 0) {
+ *   console.error(problems.join('\n'));
+ *   process.exit(1);
+ * }
  * ```
- *
- * docs/duplicate-resource-id.md has the full guide, the three test cases, and what this does and
- * does not cover.
  */
-export { DuplicateResourceIdError, claimResourceId } from './duplicate-id.ts';
-export { guardDuplicateIds } from './guard.ts';
+export { DuplicateResourceIdError, PATCHED_ALCHEMY_VERSION } from './duplicate-id.ts';
+export { checkAlchemyPatch, type PatchProblem } from './patch-check.ts';

package/src/scope/patch-check.test.ts

@@ -0,0 +1,114 @@
+/**
+ * `checkAlchemyPatch` against a fixture consumer directory — every failure mode a consuming
+ * stack's own `check` should catch, built one `mkdtemp` at a time rather than against this
+ * repo's own tree, so each case controls exactly what is "installed".
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, test } from 'bun:test';
+import { PATCHED_ALCHEMY_VERSION } from './duplicate-id.ts';
+import { checkAlchemyPatch } from './patch-check.ts';
+
+const OUR_PATCH = await Bun.file(
+  new URL(`../../patches/alchemy@${PATCHED_ALCHEMY_VERSION}.patch`, import.meta.url),
+).text();
+
+let dir: string | undefined;
+afterEach(() => {
+  if (dir) rmSync(dir, { recursive: true, force: true });
+  dir = undefined;
+});
+
+/** A fresh scratch "consumer project" directory, empty except for what each test adds. */
+const scratch = (): string => {
+  dir = mkdtempSync(join(tmpdir(), 'alchemy-patch-check-'));
+  return dir;
+};
+
+const writePkg = async (root: string, content: Record<string, unknown>) =>
+  writeFile(join(root, 'package.json'), JSON.stringify(content, null, 2));
+
+const installAlchemy = async (
+  root: string,
+  options: { version?: string; applied?: boolean } = {},
+) => {
+  const { version = PATCHED_ALCHEMY_VERSION, applied = true } = options;
+  const alchemyDir = join(root, 'node_modules', 'alchemy');
+  await mkdir(join(alchemyDir, 'src'), { recursive: true });
+  await mkdir(join(alchemyDir, 'lib'), { recursive: true });
+  await writeFile(join(alchemyDir, 'package.json'), JSON.stringify({ version }));
+  const marker = applied ? 'class DuplicateResourceIdError' : '// // TODO(sam): unpatched';
+  await writeFile(join(alchemyDir, 'src', 'Resource.ts'), marker);
+  await writeFile(join(alchemyDir, 'lib', 'Resource.js'), marker);
+};
+
+describe('checkAlchemyPatch', () => {
+  test('alchemy not installed at all', async () => {
+    const root = scratch();
+    expect(await checkAlchemyPatch(root)).toEqual([expect.stringContaining('not installed')]);
+  });
+
+  test('installed alchemy is a different version than the patch targets', async () => {
+    const root = scratch();
+    await installAlchemy(root, { version: '2.0.0-beta.999' });
+    const problems = await checkAlchemyPatch(root);
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain('2.0.0-beta.999');
+    expect(problems[0]).toContain(PATCHED_ALCHEMY_VERSION);
+  });
+
+  test('right version installed, but package.json has no patchedDependencies entry', async () => {
+    const root = scratch();
+    await installAlchemy(root);
+    await writePkg(root, {});
+    const problems = await checkAlchemyPatch(root);
+    expect(problems).toEqual([expect.stringContaining('no entry')]);
+  });
+
+  test('patchedDependencies points at a file that does not exist', async () => {
+    const root = scratch();
+    await installAlchemy(root);
+    await writePkg(root, {
+      patchedDependencies: { [`alchemy@${PATCHED_ALCHEMY_VERSION}`]: 'patches/missing.patch' },
+    });
+    const problems = await checkAlchemyPatch(root);
+    expect(problems).toEqual([expect.stringContaining('missing')]);
+  });
+
+  test('the referenced patch file differs from what @homeflare/alchemy ships', async () => {
+    const root = scratch();
+    await installAlchemy(root);
+    await mkdir(join(root, 'patches'), { recursive: true });
+    await writeFile(join(root, 'patches', 'alchemy.patch'), 'not the real patch');
+    await writePkg(root, {
+      patchedDependencies: { [`alchemy@${PATCHED_ALCHEMY_VERSION}`]: 'patches/alchemy.patch' },
+    });
+    const problems = await checkAlchemyPatch(root);
+    expect(problems).toEqual([expect.stringContaining('differs')]);
+  });
+
+  test('declared and byte-identical, but never actually applied', async () => {
+    const root = scratch();
+    await installAlchemy(root, { applied: false });
+    await mkdir(join(root, 'patches'), { recursive: true });
+    await writeFile(join(root, 'patches', 'alchemy.patch'), OUR_PATCH);
+    await writePkg(root, {
+      patchedDependencies: { [`alchemy@${PATCHED_ALCHEMY_VERSION}`]: 'patches/alchemy.patch' },
+    });
+    const problems = await checkAlchemyPatch(root);
+    expect(problems).toEqual([expect.stringContaining('not applied')]);
+  });
+
+  test('declared, byte-identical, and applied: no problems', async () => {
+    const root = scratch();
+    await installAlchemy(root);
+    await mkdir(join(root, 'patches'), { recursive: true });
+    await writeFile(join(root, 'patches', 'alchemy.patch'), OUR_PATCH);
+    await writePkg(root, {
+      patchedDependencies: { [`alchemy@${PATCHED_ALCHEMY_VERSION}`]: 'patches/alchemy.patch' },
+    });
+    expect(await checkAlchemyPatch(root)).toEqual([]);
+  });
+});