@homeflare/alchemy 0.59.0 → 0.61.0

package/src/scope/duplicate-id.ts

@@ -1,113 +1,80 @@
 /**
- * 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 THIS package's own peer pin and
+ *      devDependency sit at, and the one `duplicate-id.test.ts` drives its real `Stack` 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.
+ *   3. `PATCHED_ALCHEMY_VERSIONS` — every alchemy version this package ships a CUT patch for
+ *      (currently beta.81 and beta.83, kit PR shipping beta.83's — a consumer on beta.82 or
+ *      beta.84 is NOT covered merely by being "close"; `bun`'s patch format keys to an exact
+ *      version string, and a patch cut against one version is not guaranteed to even apply to
+ *      another — see docs/duplicate-resource-id.md for why a diff was taken between the two
+ *      tarballs rather than assumed). `checkAlchemyPatch` (`patch-check.ts`) walks this list to
+ *      find the shipped patch matching a consumer's ACTUAL install, so a stack on beta.83 is not
+ *      forced to pin the single oldest supported version just to pass its own check.
  */
-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).
+ * The exact `alchemy` version `patches/alchemy@2.0.0-beta.81.patch` was cut against — this
+ * package's own peer pin, and the version `duplicate-id.test.ts` drives a real `Stack` over.
+ * `duplicate-id.test.ts` keeps this honest against `package.json`'s own `peerDependencies`.
+ *
+ * ⛔ STAYS, MEANING BETA.81 — do not repoint this at beta.83. A consumer that calls
+ * `checkAlchemyPatch` with an explicit `alchemyVersion` (or reads this constant directly)
+ * must keep getting the same answer it always has; {@link PATCHED_ALCHEMY_VERSIONS} is the
+ * list a caller walks to find ALL supported pins, this one constant is not retargeted to mean
+ * "whichever is newest."
  */
-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;
-};
+export const PATCHED_ALCHEMY_VERSION: string = '2.0.0-beta.81';
 
 /**
- * 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.
+ * Every alchemy version `@homeflare/alchemy` ships a cut `patches/alchemy@<version>.patch`
+ * for, oldest first. `checkAlchemyPatch` uses this to pick the shipped patch matching a
+ * consumer's ACTUAL installed version instead of only ever checking against
+ * {@link PATCHED_ALCHEMY_VERSION}. `patch-check.test.ts` and the static patch-coverage test
+ * both assert every entry here has a real `patches/alchemy@<version>.patch` file.
  */
-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_VERSIONS: readonly string[] = ['2.0.0-beta.81', '2.0.0-beta.83'];

package/src/scope/index.ts

@@ -1,20 +1,27 @@
 /**
- * `@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`, one per supported alchemy version
+ * (`../../patches/alchemy@<version>.patch`, listed in `PATCHED_ALCHEMY_VERSIONS`: beta.81 and
+ * beta.83), 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,
+  PATCHED_ALCHEMY_VERSIONS,
+} from './duplicate-id.ts';
+export { checkAlchemyPatch, type PatchProblem } from './patch-check.ts';

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

@@ -0,0 +1,142 @@
+/**
+ * `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".
+ *
+ * ★ TWO SUPPORTED VERSIONS, NOT ONE. `@homeflare/alchemy` ships a cut patch for both
+ *   `2.0.0-beta.81` ({@link PATCHED_ALCHEMY_VERSION}) and `2.0.0-beta.83` — a consumer on
+ *   either passes `checkAlchemyPatch` without pinning a specific version; one on neither is
+ *   the "unlisted version" case below.
+ */
+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, PATCHED_ALCHEMY_VERSIONS } from './duplicate-id.ts';
+import { checkAlchemyPatch } from './patch-check.ts';
+
+const BETA_83 = '2.0.0-beta.83';
+
+const shippedPatch = (version: string) =>
+  Bun.file(new URL(`../../patches/alchemy@${version}.patch`, import.meta.url)).text();
+
+const OUR_PATCH_81 = await shippedPatch(PATCHED_ALCHEMY_VERSION);
+const OUR_PATCH_83 = await shippedPatch(BETA_83);
+
+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);
+};
+
+/** Declares `patchedDependencies` for `version`, pointing at a copy of `patchContent`. */
+const declarePatch = async (root: string, version: string, patchContent: string) => {
+  await mkdir(join(root, 'patches'), { recursive: true });
+  await writeFile(join(root, 'patches', 'alchemy.patch'), patchContent);
+  await writePkg(root, {
+    patchedDependencies: { [`alchemy@${version}`]: 'patches/alchemy.patch' },
+  });
+};
+
+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 version this package has no shipped patch for', 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');
+    // Every supported version is named, so the caller knows what to re-cut against.
+    for (const supported of PATCHED_ALCHEMY_VERSIONS) {
+      expect(problems[0]).toContain(supported);
+    }
+  });
+
+  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 declarePatch(root, PATCHED_ALCHEMY_VERSION, 'not the real 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 declarePatch(root, PATCHED_ALCHEMY_VERSION, OUR_PATCH_81);
+    const problems = await checkAlchemyPatch(root);
+    expect(problems).toEqual([expect.stringContaining('not applied')]);
+  });
+
+  test('beta.81, declared, byte-identical, and applied: no problems', async () => {
+    const root = scratch();
+    await installAlchemy(root);
+    await declarePatch(root, PATCHED_ALCHEMY_VERSION, OUR_PATCH_81);
+    expect(await checkAlchemyPatch(root)).toEqual([]);
+  });
+
+  test('beta.83, declared, byte-identical, and applied: no problems, no version argument needed', async () => {
+    const root = scratch();
+    await installAlchemy(root, { version: BETA_83 });
+    await declarePatch(root, BETA_83, OUR_PATCH_83);
+    // No explicit alchemyVersion — a beta.83 consumer must pass by what is ACTUALLY
+    // installed, not by also being pinned to PATCHED_ALCHEMY_VERSION (beta.81).
+    expect(await checkAlchemyPatch(root)).toEqual([]);
+  });
+
+  test('an explicit alchemyVersion that does not match what is installed is still a problem', async () => {
+    const root = scratch();
+    await installAlchemy(root, { version: BETA_83 });
+    await declarePatch(root, BETA_83, OUR_PATCH_83);
+    const problems = await checkAlchemyPatch(root, PATCHED_ALCHEMY_VERSION);
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain(BETA_83);
+    expect(problems[0]).toContain(PATCHED_ALCHEMY_VERSION);
+  });
+});

package/src/scope/patch-check.ts

@@ -0,0 +1,139 @@
+/**
+ * A consuming stack's own `check` calls `checkAlchemyPatch` to assert it actually carries the
+ * duplicate-resource-id fix — not just that SOME version of `alchemy` is installed, but that
+ * THIS install carries the patch, for the alchemy version it was cut against.
+ *
+ * ★ WHY A BUMP CAN OTHERWISE DROP IT SILENTLY. `patchedDependencies` keys a patch to an EXACT
+ *   version string (`alchemy@2.0.0-beta.81`). `bun add alchemy@2.0.0-beta.82` leaves that key
+ *   pointing at a version nothing installs anymore — `bun install` neither errors nor warns,
+ *   it just stops applying the patch, and the stack is back to the original silent collision
+ *   with every other gate still green. This check is what turns that bump into a failing
+ *   `check`, the same way `tests/dist.test.ts` turns a build regression into a failing test
+ *   instead of a surprise three repos downstream (this package's own AGENTS.md, "the smoke
+ *   test is not optional").
+ * ★ A STATIC CHECK, mirroring `@homeflare/config/check`'s `checkCopy`/`checkOxfmt` — not a
+ *   functional probe that spins up a `Stack`/`Resource`/`Effect` harness on every `check` run.
+ *   The functional proof that the patch's LOGIC works lives in this package's own
+ *   `duplicate-id.test.ts`, against the exact pinned version; a consumer's `check` only needs
+ *   to know whether ITS install carries that same patch, applied — three file reads, no
+ *   `effect` runtime pulled into every repo's check step.
+ * ⛔ IT REPORTS, IT DOES NOT REPAIR, same as `checkProject` in `@homeflare/config/check` — this
+ *   never edits `package.json` or re-runs `bun install` for the caller.
+ */
+import { PATCHED_ALCHEMY_VERSION, PATCHED_ALCHEMY_VERSIONS } from './duplicate-id.ts';
+
+/** One thing wrong with a consuming stack's alchemy patch, in the imperative. */
+export type PatchProblem = string;
+
+const patchKey = (version: string) => `alchemy@${version}`;
+
+/** Where THIS package's own shipped copy of the patch lives, however it was installed. */
+const shippedPatchPath = (version: string): string =>
+  new URL(`../../patches/${patchKey(version)}.patch`, import.meta.url).pathname;
+
+type PackageJson = {
+  readonly patchedDependencies?: Readonly<Record<string, string>>;
+};
+
+/**
+ * @param projectDir The consuming stack's OWN repo root (where its `package.json` and
+ *   `patches/` directory live) — never this kit's own.
+ * @param alchemyVersion The version to check for. Omitted (the normal case): the version
+ *   actually installed at `projectDir` is used, so a consumer on ANY version this package
+ *   ships a patch for ({@link PATCHED_ALCHEMY_VERSIONS}) passes without having to pin
+ *   {@link PATCHED_ALCHEMY_VERSION} specifically — a stack on beta.83 is checked against the
+ *   beta.83 patch, one on beta.81 against the beta.81 patch. A caller passes this explicitly
+ *   only to assert a SPECIFIC pin regardless of what happens to be installed (as the tests do).
+ */
+export const checkAlchemyPatch = async (
+  projectDir: string,
+  alchemyVersion?: string,
+): Promise<readonly PatchProblem[]> => {
+  const problems: PatchProblem[] = [];
+
+  const installedPkg = Bun.file(`${projectDir}/node_modules/alchemy/package.json`);
+  if (!(await installedPkg.exists())) {
+    problems.push('node_modules/alchemy: not installed — nothing to check the patch against');
+    return problems;
+  }
+  const installedVersion = ((await installedPkg.json()) as { version?: string }).version;
+
+  // No explicit ask: check against whatever is ACTUALLY installed, not a single hardcoded
+  // pin — that is what lets a beta.83 consumer pass without also being on beta.81.
+  const targetVersion = alchemyVersion ?? installedVersion ?? PATCHED_ALCHEMY_VERSION;
+  const key = patchKey(targetVersion);
+
+  if (!PATCHED_ALCHEMY_VERSIONS.includes(targetVersion)) {
+    problems.push(
+      // ★ Name the version being CHECKED: with an explicit `alchemyVersion` it can differ from
+      //   the installed one, and naming the installed version then blames a supported one.
+      `alchemy ${targetVersion} (installed: ${installedVersion ?? 'unknown'}) is a version ` +
+        `@homeflare/alchemy has ` +
+        `no duplicate-resource-id patch for — supported versions are ` +
+        `${PATCHED_ALCHEMY_VERSIONS.join(', ')}; cut a new patches/${key}.patch ` +
+        "(@homeflare/alchemy's own patches/) before bumping alchemy, or this install has no " +
+        'protection at all',
+    );
+    return problems;
+  }
+  if (installedVersion !== targetVersion) {
+    problems.push(
+      `node_modules/alchemy is ${installedVersion ?? 'unknown'}, but the duplicate-resource-id ` +
+        `check was asked for ${targetVersion} — pass the installed version explicitly, or omit ` +
+        'alchemyVersion to check against whatever is actually installed',
+    );
+    return problems;
+  }
+
+  const pkgFile = Bun.file(`${projectDir}/package.json`);
+  if (!(await pkgFile.exists())) {
+    problems.push('package.json: missing');
+    return problems;
+  }
+  const pkg = (await pkgFile.json()) as PackageJson;
+  const declaredPath = pkg.patchedDependencies?.[key];
+  if (declaredPath === undefined) {
+    problems.push(
+      `package.json: patchedDependencies has no entry for "${key}" — this stack has no ` +
+        'duplicate-resource-id protection at all; see @homeflare/alchemy/docs/duplicate-resource-id.md',
+    );
+    return problems;
+  }
+
+  const theirs = Bun.file(`${projectDir}/${declaredPath}`);
+  if (!(await theirs.exists())) {
+    problems.push(`package.json declares "${key}" at ${declaredPath}, but that file is missing`);
+    return problems;
+  }
+  const ours = Bun.file(shippedPatchPath(targetVersion));
+  if (!(await ours.exists())) {
+    // The kit's own tarball is missing its patch — a packaging bug, not the consumer's.
+    problems.push(`@homeflare/alchemy ships no patches/${key}.patch to compare against`);
+    return problems;
+  }
+  if ((await theirs.text()) !== (await ours.text())) {
+    problems.push(
+      `${declaredPath}: differs from @homeflare/alchemy's shipped patch — re-copy it, ` +
+        'or say why it differs',
+    );
+  }
+
+  // Declared and byte-identical is not yet APPLIED: a hand-edited patchedDependencies entry,
+  // or an install under a package manager that does not support bun's patch format, leaves
+  // node_modules unpatched with nothing above noticing. One cheap textual proof it landed.
+  const resourceSrc = Bun.file(`${projectDir}/node_modules/alchemy/src/Resource.ts`);
+  const resourceLib = Bun.file(`${projectDir}/node_modules/alchemy/lib/Resource.js`);
+  const marker = 'DuplicateResourceIdError';
+  const [srcText, libText] = await Promise.all([
+    resourceSrc.exists().then((ok) => (ok ? resourceSrc.text() : '')),
+    resourceLib.exists().then((ok) => (ok ? resourceLib.text() : '')),
+  ]);
+  if (!srcText.includes(marker) && !libText.includes(marker)) {
+    problems.push(
+      'node_modules/alchemy/{src/Resource.ts,lib/Resource.js}: neither contains the patch — ' +
+        'declared in package.json but not applied; re-run `bun install`',
+    );
+  }
+
+  return problems;
+};

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

@@ -0,0 +1,50 @@
+/**
+ * Static coverage: every version `PATCHED_ALCHEMY_VERSIONS` claims to support actually has a
+ * shipped `patches/alchemy@<version>.patch` carrying the `DuplicateResourceIdError` fix.
+ *
+ * ★ STATIC, NOT FUNCTIONAL — no network. Proving a patch APPLIES to the real upstream tarball
+ *   needs `npm pack alchemy@<version>` pulled live and diffed, which this suite's own CI lane
+ *   cannot assume has network access (and must not: patch-check.ts's own header explains why a
+ *   consumer's `check` stays a static file read rather than a network-dependent probe). The
+ *   patch for {@link PATCHED_ALCHEMY_VERSION} (beta.81) already has that proof the hard way —
+ *   `duplicate-id.test.ts` drives a REAL patched `Stack` over the devDependency `alchemy`
+ *   install, which only passes because `bun install`'s `patchedDependencies` actually applied
+ *   it. This test is the one that would catch a version ADDED to the list here without a
+ *   patch file ever being cut for it, or a patch file that silently regressed back to the
+ *   upstream TODO.
+ */
+import { describe, expect, test } from 'bun:test';
+import { PATCHED_ALCHEMY_VERSIONS } from './duplicate-id.ts';
+
+/** `test.each` wants a plain mutable array of a known element type, not `readonly string[]`. */
+const versions: string[] = [...PATCHED_ALCHEMY_VERSIONS];
+
+const patchFile = (version: string) =>
+  Bun.file(new URL(`../../patches/alchemy@${version}.patch`, import.meta.url));
+
+describe('every supported alchemy version ships a cut patch', () => {
+  test.each(versions)('alchemy@%s has a patches/ file', async (version: string) => {
+    expect(await patchFile(version).exists()).toBe(true);
+  });
+
+  test.each(versions)(
+    'alchemy@%s patch carries the DuplicateResourceIdError fix',
+    async (version: string) => {
+      const text = await patchFile(version).text();
+      expect(text).toContain('DuplicateResourceIdError');
+      // The TODO it replaces must be gone from the ADDED ("+") side of the diff — present
+      // only as part of a removed ("-") line, never re-introduced unpatched.
+      const addedLines = text.split('\n').filter((line) => line.startsWith('+'));
+      expect(addedLines.some((line) => line.includes('TODO(sam)'))).toBe(false);
+    },
+  );
+
+  test('touches the three files every consumer resolution path needs', async () => {
+    for (const version of PATCHED_ALCHEMY_VERSIONS) {
+      const text = await patchFile(version).text();
+      expect(text).toContain('a/src/Resource.ts');
+      expect(text).toContain('a/lib/Resource.js');
+      expect(text).toContain('a/lib/Resource.d.ts');
+    }
+  });
+});

package/dist/scope/guard.d.ts

@@ -1,28 +0,0 @@
-/**
- * `guardDuplicateIds` — wrap a Resource class so every `("id", props)` call it makes first
- * claims that id through `duplicate-id.ts`'s per-stack registry, naming both resource types if
- * a second, different-typed resource already claimed it. See duplicate-id.ts's header for why
- * the check has to live HERE (at the moment of registration) rather than after the stack body
- * has finished running.
- *
- * Usage, in a resource's own file, right where it's exported today:
- *
- * ```ts
- * export const CaddyConfig = guardDuplicateIds(Resource<CaddyConfig>('Caddy.Config', { … }));
- * ```
- *
- * ★ A `Proxy` around the REAL class, not a reimplementation. `Resource()`'s return value is a
- *   callable object wearing an `Effectable.Prototype` (`Effect.isEffect(MyResource) === true`,
- *   for the bare-tag platform-resource pattern) plus `.ref`, `.Type`, `.Provider`, `.Self`,
- *   `.Aliases` — reconstructing that shape risks silently dropping one of them. A `Proxy` whose
- *   `get` trap is the default (`Reflect.get`) forwards every property read untouched; only the
- *   `apply` trap — the `MyResource("id", props)` call form — is new behaviour.
- * ⚠️ THE "REGISTER METHODS" OVERLOAD IS DELIBERATELY LEFT ALONE. `ResourceClass` is also callable
- *   with a single object argument to attach methods (`Resource()`'s own `typeof args[0] ===
- *   'object' ? Object.assign(...) : constructor(...)` branch) — that call mutates and returns the
- *   SAME class, carries no logical id, and has nothing to claim. Only a string first argument
- *   (the `(id, props)` form) goes through `claimResourceId`.
- */
-import type { ResourceClass, ResourceLike } from 'alchemy/Resource';
-export declare const guardDuplicateIds: <R extends ResourceLike>(resourceClass: ResourceClass<R>) => ResourceClass<R>;
-//# sourceMappingURL=guard.d.ts.map

package/dist/scope/guard.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/scope/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIpE,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,YAAY,iBACvC,aAAa,CAAC,CAAC,CAAC,KAC9B,aAAa,CAAC,CAAC,CAiBM,CAAC"}