@homeflare/alchemy 0.58.0 → 0.60.0

package/docs/duplicate-resource-id.md

@@ -0,0 +1,121 @@
+# Duplicate resource ids — a patch to `alchemy` itself
+
+Two resources of different types declaring the same logical id in one stack scope now fails at
+registration — before `Plan.make`, before any provider runs — instead of Alchemy silently
+treating the second one as a reference to the first. The fix is a **patch to `alchemy`'s own
+`Resource.ts`**, applied at each consuming stack's own root (`alchemy` is a peer dependency
+here, so this package's own `patchedDependencies` only reaches ITS OWN install).
+
+## The incident
+
+Tim, 2026-10-19 ("lets not let two things claim the same"): in homeflare-mini,
+`NixJobRetirement('caddy', …)` and the Caddy config resource (`CADDY_ID = 'caddy'`,
+`src/caddy/declare.ts`) both declared logical id `caddy` in one stack. The plan showed
+`[caddy] noop`, the retirement was silently dropped (deploy "49 succeeded" for 50 rows), and a
+later deploy showed `[caddy] update` as state reconciled back.
+
+## Why a kit-side wrapper cannot fix this (PR 468's first version, replaced here)
+
+PR 468 shipped `guardDuplicateIds`, a `Proxy` wrapped around `@homeflare/alchemy`'s own
+`CaddyConfig` export. A second-round review found it never actually closed the incident:
+
+- `NixJobRetirement` is declared directly in homeflare-mini against `alchemy`'s raw
+  `Resource()` — never through anything this kit exports — so wrapping `CaddyConfig` alone
+  leaves the OTHER half of the collision unguarded. The incident reproduced identically in
+  BOTH orderings, Proxy or not.
+- Wrapping every `@homeflare/alchemy` export still could not reach a hand-rolled, consumer-local
+  resource type, or any vendor built-in (`Cloudflare.Worker`, etc.) — this package cannot wrap a
+  class it does not author.
+- The `Proxy` had its own bypasses besides: `yield* SomeGuardedClass` (no call, the bare-tag
+  pattern) resolves through `Effectable.Prototype`'s `evaluate()`, which closes over the
+  UNWRAPPED constructor directly; and the "attach methods" call form
+  (`SomeGuardedClass({ ...methods })`) returns the raw, unwrapped class.
+
+None of that is fixable by wrapping harder. The real registration happens once, inside
+`alchemy`'s own `Resource()`, and every resource — ours, a consumer's own, and every vendor
+built-in — goes through that one function. A kit-side wrapper is structurally unable to be the
+single place a fix can live.
+
+## The root cause
+
+`alchemy@2.0.0-beta.81`'s `Resource.ts` treats a second `yield*` at an already-registered FQN as
+an idempotent re-reference and returns the first-registered resource without ever comparing
+`Type`:
+
+```ts
+const existing = stack.resources[fqn];
+if (existing) {
+  // … an ambient-provider-mode check, unrelated …
+  // // TODO(sam): check if props are different and die
+  return existing;
+}
+```
+
+## The patch
+
+`patches/alchemy@2.0.0-beta.81.patch` replaces that `TODO` with a `Type` comparison, dying with
+`DuplicateResourceIdError` the moment a different type claims an already-taken id:
+
+```
+REFUSING: duplicate resource id "caddy" in scope (root): first declared by Nix.JobRetirement, again by Caddy.Config
+```
+
+It touches three files so every consumer resolution path is covered: `src/Resource.ts` (the
+"bun" export condition), `lib/Resource.js` (the compiled "default"/node condition), and
+`lib/Resource.d.ts` (so `DuplicateResourceIdError` has types). Verified directly against both:
+registering the same collision under `bun test` and under plain `node` both die with the
+identical message.
+
+**Only `Type` is compared, never `Props`.** Comparing props as well would be wrong: 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. `Type` is stable from a resource's very
+first `yield*`; `Props` is not.
+
+## Adopting it in a consuming stack
+
+```sh
+cp node_modules/@homeflare/alchemy/patches/alchemy@2.0.0-beta.81.patch patches/
+```
+
+then add, in the stack's own root `package.json`:
+
+```json
+"patchedDependencies": {
+  "alchemy@2.0.0-beta.81": "patches/alchemy@2.0.0-beta.81.patch"
+}
+```
+
+and run `bun install`. This mirrors the house pattern for `bunfig.toml`
+("adoption is a copy, not an extend" — AGENTS.md) — the patch is copied, not referenced, so it
+ships in the consumer's OWN lockfile and survives even if `@homeflare/alchemy` is later removed.
+
+## The consumer check — catching a bump that silently drops it
+
+`patchedDependencies` keys a patch to an EXACT version string. Bumping `alchemy` without
+re-cutting the patch leaves that key pointing at nothing — `bun install` neither errors nor
+warns, it just stops applying the patch. `checkAlchemyPatch` (`@homeflare/alchemy/scope`) is
+what a stack's own `check` calls to catch that:
+
+```ts
+import { checkAlchemyPatch } from '@homeflare/alchemy/scope';
+
+const problems = await checkAlchemyPatch(import.meta.dirname);
+if (problems.length > 0) {
+  console.error(problems.join('\n'));
+  process.exit(1);
+}
+```
+
+It is a static check — three file reads, no `effect` runtime spun up — covering: alchemy
+installed at the wrong version for the patch, no `patchedDependencies` entry at all, the
+referenced file missing or differing from this package's own shipped copy, and (the one failure
+mode none of those other checks would catch) declared and byte-identical but never actually
+applied.
+
+## Upstream
+
+The real fix belongs in `alchemy` itself, at the exact line the patch replaces — every resource,
+vendor included, goes through that one function, which is the whole reason a kit-side fix can
+only ever be a stopgap. The issue/PR text proposed for `alchemy-run/alchemy` is in this PR's
+body; it has not been filed — posting it publicly needs Tim's sign-off.

package/docs/provider-standard.md

@@ -63,6 +63,15 @@ already ships is a finding, even when it works.
   owned ones, as upstream's third-party providers do; the core contract does not ask for it. `nuke` is declared wherever nuke must never reach the object.
 - **Scope (S15).** The account, zone and region are resolved inside each operation. They
   are never props.
+- **Duplicate ids (revised 2026-10-19 — a patch, not a provider rule).** A second, different
+  typed resource declaring a logical id another resource already claims in the same stack is
+  refused by a PATCH to `alchemy` itself, applied at each consuming stack's own root
+  (measured, homeflare-mini PR 329; [duplicate-resource-id.md](./duplicate-resource-id.md)).
+  Because the fix lives in `alchemy`'s own `Resource()` — the one function EVERY resource
+  (ours, a consumer's own, every vendor built-in) goes through — no individual provider file
+  in this package needs anything added or wrapped for this; a first attempt that wrapped each
+  resource's export in a kit-side `Proxy` turned out structurally unable to reach a
+  consumer-declared resource type, so it was replaced with the patch.
 
 ## Code, errors, credentials
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.58.0",
+  "version": "0.60.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -17,6 +17,7 @@
   "files": [
     "dist",
     "docs",
+    "patches",
     "src",
     "!src/**/fixtures",
     "!src/**/trust-boundary.seam.ts",
@@ -131,6 +132,10 @@
       "types": "./dist/valkey/index.d.ts",
       "default": "./dist/valkey/index.js"
     },
+    "./scope": {
+      "types": "./dist/scope/index.d.ts",
+      "default": "./dist/scope/index.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {

package/patches/alchemy@2.0.0-beta.81.patch

@@ -0,0 +1,147 @@
+diff --git a/lib/Resource.d.ts b/lib/Resource.d.ts
+index 07b92ae346b5f16475e8162e6d72284fceb8ce1c..868e8d1b6b23dbdfd558e1ff03a535c1be70801c 100644
+--- a/lib/Resource.d.ts
++++ b/lib/Resource.d.ts
+@@ -229,6 +229,23 @@ export declare class MissingImplementationError extends MissingImplementationErr
+ }> {
+ }
+ export declare const missingImplementation: (type: string, id: string) => MissingImplementationError;
++declare const DuplicateResourceIdError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
++    readonly _tag: "DuplicateResourceIdError";
++} & Readonly<A>;
++/**
++ * HOMEFLARE PATCH (homeflare-kit PR superseding #468) — see Resource.ts for the full comment.
++ * A second resource of a DIFFERENT type registered at a logical id an earlier resource
++ * already claimed in the same scope (namespace + id, i.e. the same FQN).
++ */
++export declare class DuplicateResourceIdError extends DuplicateResourceIdError_base<{
++    message: string;
++    fqn: string;
++    /** The type that first claimed `fqn`. */
++    firstType: string;
++    /** The different type that tried to claim it again. */
++    secondType: string;
++}> {
++}
+ /**
+  * Creates a resource constructor for a concrete resource type.
+  *
+diff --git a/lib/Resource.js b/lib/Resource.js
+index 71d9a3a4e0784ed09484736677d735c7c77444f8..e3b64e60b29538bfe46b094cfcf755eaea6673e7 100644
+--- a/lib/Resource.js
++++ b/lib/Resource.js
+@@ -4,7 +4,7 @@ import * as Effectable from "effect/Effectable";
+ import * as Layer from "effect/Layer";
+ import * as Option from "effect/Option";
+ import { AdoptPolicy } from "./AdoptPolicy.js";
+-import { toFqn } from "./FQN.js";
++import { toFqn, toPath } from "./FQN.js";
+ import { CurrentNamespace } from "./Namespace.js";
+ import * as Output from "./Output.js";
+ import { Provider } from "./Provider.js";
+@@ -60,6 +60,13 @@ export const isResourceOfType = (value, type) => (typeof value === "object" || t
+  */
+ export class MissingImplementationError extends Data.TaggedError("MissingImplementationError") {
+ }
++/**
++ * HOMEFLARE PATCH (homeflare-kit PR superseding #468) — see Resource.ts for the full comment.
++ * A second resource of a DIFFERENT type registered at a logical id an earlier resource
++ * already claimed in the same scope (namespace + id, i.e. the same FQN).
++ */
++export class DuplicateResourceIdError extends Data.TaggedError("DuplicateResourceIdError") {
++}
+ export const missingImplementation = (type, id) => new MissingImplementationError({
+     type,
+     id,
+@@ -128,7 +135,17 @@ export function Resource(type, options) {
+                     conflictingMode: ambientMode,
+                 }));
+             }
+-            // // TODO(sam): check if props are different and die
++            // HOMEFLARE PATCH: Type, not Props — see Resource.ts for why.
++            if (existing.Type !== type) {
++                return yield* Effect.die(new DuplicateResourceIdError({
++                    message: `REFUSING: duplicate resource id "${fqn}" in scope ` +
++                        `${toPath(namespace).join("/") || "(root)"}: first declared by ` +
++                        `${existing.Type}, again by ${type}`,
++                    fqn,
++                    firstType: existing.Type,
++                    secondType: type,
++                }));
++            }
+             return existing;
+         }
+         const bind = (...args) => typeof args[0] === "string"
+diff --git a/src/Resource.ts b/src/Resource.ts
+index d34c1809b90aba6ff7dc7d3952e3ab87e62e61c1..24b4d4d4d8a26c67e17e761b6b1080d38068f858 100644
+--- a/src/Resource.ts
++++ b/src/Resource.ts
+@@ -5,7 +5,7 @@ import * as Layer from "effect/Layer";
+ import * as Option from "effect/Option";
+ import type { Pipeable } from "effect/Pipeable";
+ import { AdoptPolicy } from "./AdoptPolicy.ts";
+-import { toFqn } from "./FQN.ts";
++import { toFqn, toPath } from "./FQN.ts";
+ import type { Input, InputProps, PropsInput } from "./Input.ts";
+ import { CurrentNamespace, type NamespaceNode } from "./Namespace.ts";
+ import * as Output from "./Output.ts";
+@@ -293,6 +293,30 @@ export class MissingImplementationError extends Data.TaggedError("MissingImpleme
+   id: string;
+ }> {}
+ 
++/**
++ * A second resource of a DIFFERENT type registered (`yield*`ed) at a logical id an earlier
++ * resource already claimed in the same scope (namespace + id, i.e. the same FQN).
++ *
++ * ★ HOMEFLARE PATCH (homeflare-kit PR superseding #468, 2026-10-19). Upstream's own
++ *   idempotent-registration branch below used to return the FIRST-registered resource for ANY
++ *   second `yield*` at an already-claimed FQN — correct for "the same resource read from two
++ *   call sites," but it never compared `Type`, so a second, DIFFERENT resource that merely
++ *   picked the same id silently lost: its props were never written to `stack.resources`, so
++ *   neither `Plan.make` nor any later inspection could tell two different resources ever
++ *   registered. Measured: `NixJobRetirement` and `Caddy.Config` both declaring id `caddy` in
++ *   one stack planned `[caddy] noop` and dropped the retirement entirely. This error, and the
++ *   `Type` check below, close that gap. Only `Type` is compared, not `Props` — see the check's
++ *   own comment for why.
++ */
++export class DuplicateResourceIdError extends Data.TaggedError("DuplicateResourceIdError")<{
++  message: string;
++  fqn: string;
++  /** The type that first claimed `fqn`. */
++  firstType: string;
++  /** The different type that tried to claim it again. */
++  secondType: string;
++}> {}
++
+ export const missingImplementation = (type: string, id: string) =>
+   new MissingImplementationError({
+     type,
+@@ -373,7 +397,27 @@ export function Resource<R extends ResourceLike>(
+             }),
+           );
+         }
+-        // // TODO(sam): check if props are different and die
++        // HOMEFLARE PATCH: the TODO above asked whether PROPS differ; this checks TYPE
++        // instead, which is the question that actually matters. Comparing props would be
++        // wrong — `Platform.ts`'s own tagged resources rewrite Props after first registration
++        // (Platform.ts ~581), and a bare-tag forward reference legitimately registers with
++        // `Props: undefined` until its `.make(...)` Layer builds (MissingImplementationError's
++        // own doc comment above). Type is stable from the resource's very first `yield*` and is
++        // exactly what distinguishes "the same resource, referenced twice" from "two different
++        // resources that picked the same id."
++        if (existing.Type !== type) {
++          return yield* Effect.die(
++            new DuplicateResourceIdError({
++              message:
++                `REFUSING: duplicate resource id "${fqn}" in scope ` +
++                `${toPath(namespace).join("/") || "(root)"}: first declared by ` +
++                `${existing.Type}, again by ${type}`,
++              fqn,
++              firstType: existing.Type,
++              secondType: type,
++            }),
++          );
++        }
+         return existing;
+       }
+       const bind = (

package/src/caddy/config.ts

@@ -28,6 +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).
+ * ⚠️ `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';

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

@@ -0,0 +1,154 @@
+/**
+ * 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 type { Resource } from 'alchemy/Resource';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import ownPackage from '../../package.json';
+import { PATCHED_ALCHEMY_VERSION } from './duplicate-id.ts';
+
+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);
+
+type StackBody = Effect.Effect<unknown, unknown, unknown>;
+
+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);
+  });
+});
+
+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('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('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',
+    );
+    expect(exit._tag).toBe('Success');
+  });
+
+  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('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',
+    );
+    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

@@ -0,0 +1,55 @@
+/**
+ * `DuplicateResourceIdError` and the pinned alchemy version the kit's patch targets.
+ *
+ * ★ 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 * as Data from 'effect/Data';
+
+/**
+ * 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;
+  /** The type that first claimed `fqn`. */
+  firstType: string;
+  /** The different type that tried to claim it again. */
+  secondType: string;
+}> {}
+
+/**
+ * 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 PATCHED_ALCHEMY_VERSION: string = '2.0.0-beta.81';

package/src/scope/index.ts

@@ -0,0 +1,22 @@
+/**
+ * `@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 { checkAlchemyPatch } from '@homeflare/alchemy/scope';
+ *
+ * const problems = await checkAlchemyPatch(import.meta.dirname);
+ * if (problems.length > 0) {
+ *   console.error(problems.join('\n'));
+ *   process.exit(1);
+ * }
+ * ```
+ */
+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([]);
+  });
+});