@homeflare/alchemy 0.59.0 → 0.61.0

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scope/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scope/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/scope/index.js

@@ -1,71 +1,73 @@
 // src/scope/duplicate-id.ts
-import { toFqn } from "alchemy/FQN";
-import { CurrentNamespace } from "alchemy/Namespace";
-import { Stack } from "alchemy/Stack";
 import * as Data from "effect/Data";
-import * as Effect from "effect/Effect";
 
 class DuplicateResourceIdError extends Data.TaggedError("DuplicateResourceIdError") {
 }
-var scopeLabel = (namespace) => {
-  if (!namespace)
-    return "(root)";
-  const path = [];
-  let node = namespace;
-  while (node) {
-    path.unshift(node.Id);
-    node = node.Parent;
+var PATCHED_ALCHEMY_VERSION = "2.0.0-beta.81";
+var PATCHED_ALCHEMY_VERSIONS = ["2.0.0-beta.81", "2.0.0-beta.83"];
+// src/scope/patch-check.ts
+var patchKey = (version) => `alchemy@${version}`;
+var shippedPatchPath = (version) => new URL(`../../patches/${patchKey(version)}.patch`, import.meta.url).pathname;
+var checkAlchemyPatch = async (projectDir, alchemyVersion) => {
+  const problems = [];
+  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;
   }
-  return path.join("/");
-};
-var registries = new WeakMap;
-var registryFor = (stack) => {
-  const existing = registries.get(stack);
-  if (existing)
-    return existing;
-  const created = new Map;
-  registries.set(stack, created);
-  return created;
-};
-var claimResourceId = (type, id) => 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;
+  const installedVersion = (await installedPkg.json()).version;
+  const targetVersion = alchemyVersion ?? installedVersion ?? PATCHED_ALCHEMY_VERSION;
+  const key = patchKey(targetVersion);
+  if (!PATCHED_ALCHEMY_VERSIONS.includes(targetVersion)) {
+    problems.push(`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;
   }
-  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
-    }));
+  const pkg = await pkgFile.json();
+  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;
   }
-});
-// src/scope/guard.ts
-import * as Effect2 from "effect/Effect";
-var guardDuplicateIds = (resourceClass) => new Proxy(resourceClass, {
-  apply(target, thisArg, args) {
-    const id = args[0];
-    if (typeof id !== "string") {
-      return Reflect.apply(target, thisArg, args);
-    }
-    return Effect2.gen(function* () {
-      yield* claimResourceId(resourceClass.Type, id);
-      return yield* Reflect.apply(target, thisArg, args);
-    });
+  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()) {
+    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");
+  }
+  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;
+};
 export {
   DuplicateResourceIdError,
-  claimResourceId,
-  guardDuplicateIds
+  PATCHED_ALCHEMY_VERSION,
+  PATCHED_ALCHEMY_VERSIONS,
+  checkAlchemyPatch
 };
 
-//# debugId=1AB58BD65E38742164756E2164756E21
+//# debugId=461D34CD68FB220064756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/scope/index.js.map

@@ -1,11 +1,11 @@
 {
   "version": 3,
-  "sources": ["../src/scope/duplicate-id.ts", "../src/scope/guard.ts"],
+  "sources": ["../src/scope/duplicate-id.ts", "../src/scope/patch-check.ts"],
   "sourcesContent": [
-    "/**\n * Refuse a second resource claiming a logical id already taken in the same stack scope.\n *\n * ★ WHY THIS EXISTS (measured, homeflare-mini PR 329, Tim 2026-10-19). `NixJobRetirement('caddy',\n *   …)` and `Caddy.Config` (`CADDY_ID = 'caddy'`) both declared logical id `caddy` in one stack.\n *   Alchemy's own `Resource()` constructor treats a second `yield*` at an already-claimed FQN as\n *   an idempotent re-reference — correct for \"the same resource, read from two call sites\" — and\n *   returns the FIRST-registered resource without ever comparing `Type` (`Resource.ts`, the\n *   `if (existing) { … return existing; }` branch; a sibling TODO there already flags a related\n *   gap — \"check if props are different and die\"). The SECOND resource's props are never written\n *   anywhere: `stack.resources[fqn]` never changes, so nothing downstream — not `Plan.make`, not a\n *   later inspection of the compiled stack — can tell two different registrations ever happened.\n *   Measured directly (dup-experiment.ts, this PR): registering `Test.ResourceB('shared-id', …)`\n *   after `Test.ResourceA('shared-id', …)` compiles a stack whose ONLY entry at that fqn reports\n *   `Type: 'Test.ResourceA'` — the second declaration leaves no trace to check after the fact.\n * ★ WHY THE CHECK CANNOT BE BOLTED ON AFTER THE FACT. Because the losing registration leaves no\n *   trace (above), a guard built from `CompiledStack.resources` — inspected after the stack's body\n *   has run, e.g. before `Plan.make` — sees only one entry per fqn and cannot know a second,\n *   different-typed claim ever happened. The only point where both the existing claim AND the new\n *   claimant's `Type` are both in hand is at the moment of registration, which is why this module\n *   is a REGISTRY populated and checked as each resource is `yield*`ed (see `guard.ts`), not a\n *   post-hoc scan.\n * ⛔ UPSTREAM IS THE RIGHT HOME FOR THE REAL FIX. The comparison belongs in `Resource.ts` itself,\n *   right where its own TODO already sits — every resource (ours and every vendor built-in) goes\n *   through that one function, and this kit cannot wrap a type it does not author (e.g.\n *   `Cloudflare.Worker`). This module is the house-side stopgap decision 49 allows (\"a house rule\n *   only fills a gap upstream is silent on\"): it protects any TWO resources that both go through\n *   `guardDuplicateIds` (guard.ts), which is everywhere this kit's own providers adopt it. The\n *   upstream issue text proposing the real fix is in this PR's body.\n */\nimport { toFqn } from 'alchemy/FQN';\nimport { CurrentNamespace, type NamespaceNode } from 'alchemy/Namespace';\nimport { Stack } from 'alchemy/Stack';\nimport * as Data from 'effect/Data';\nimport * as Effect from 'effect/Effect';\n\n/**\n * Two resources of different types both claimed `fqn` in `scope`. Carries both type names so the\n * message — and any catcher — can tell the attacker from the defender without re-deriving them.\n */\nexport class DuplicateResourceIdError extends Data.TaggedError('DuplicateResourceIdError')<{\n  message: string;\n  fqn: string;\n  scope: string;\n  firstType: string;\n  secondType: string;\n}> {}\n\nconst scopeLabel = (namespace: NamespaceNode | undefined): string => {\n  if (!namespace) return '(root)';\n  const path: string[] = [];\n  let node: NamespaceNode | undefined = namespace;\n  while (node) {\n    path.unshift(node.Id);\n    node = node.Parent;\n  }\n  return path.join('/');\n};\n\n/**\n * One registry per compiled stack, keyed by the `Stack` service object `yield* Stack` returns\n * (a fresh `StackSpec` per `Alchemy.Stack(...)`/`make()` call — see `Stack.ts`'s `Layer.effect`).\n * A `WeakMap` so two unrelated stacks (sequential test runs, two stacks in one process) never see\n * each other's claims, and so the registry is collected with the stack instead of growing forever\n * in a long-running process (an `alchemy dev` watch loop, this package's own test suite).\n */\nconst registries = new WeakMap<object, Map<string, string>>();\n\nconst registryFor = (stack: object): Map<string, string> => {\n  const existing = registries.get(stack);\n  if (existing) return existing;\n  const created = new Map<string, string>();\n  registries.set(stack, created);\n  return created;\n};\n\n/**\n * Claim `id` for `type` in the current namespace scope. Fine the first time, and fine again for\n * the SAME type (the legitimate \"yield the same resource from two call sites\" pattern Alchemy's\n * own idempotent registration supports). Dies with {@link DuplicateResourceIdError} the moment a\n * DIFFERENT type claims an id already taken — before that second resource's provider ever runs.\n *\n * ⚠️ `Effect.die`, NOT a typed failure. This runs at registration, not inside a lifecycle\n * operation (`read`/`diff`/`reconcile`/`delete`) — the provider-standard's S20 ban on\n * `Effect.orDie` in LIFECYCLE operations does not apply here, and `ConflictingProviderModeError`\n * right next door in upstream's own `Resource.ts` dies the same way for the same reason: there is\n * no recovery a caller could usefully attempt mid-registration.\n */\nexport const claimResourceId = (type: string, id: string): Effect.Effect<void, never, Stack> =>\n  Effect.gen(function* () {\n    const stack = yield* Stack;\n    const namespace = yield* CurrentNamespace;\n    const fqn = toFqn(namespace, id);\n    const registry = registryFor(stack);\n    const firstType = registry.get(fqn);\n    if (firstType === undefined) {\n      registry.set(fqn, type);\n      return;\n    }\n    if (firstType !== type) {\n      return yield* Effect.die(\n        new DuplicateResourceIdError({\n          message:\n            `REFUSING: duplicate resource id \"${fqn}\" in scope ${scopeLabel(namespace)}: ` +\n            `first declared by ${firstType}, again by ${type}`,\n          fqn,\n          scope: scopeLabel(namespace),\n          firstType,\n          secondType: type,\n        }),\n      );\n    }\n  });\n",
-    "/**\n * `guardDuplicateIds` — wrap a Resource class so every `(\"id\", props)` call it makes first\n * claims that id through `duplicate-id.ts`'s per-stack registry, naming both resource types if\n * a second, different-typed resource already claimed it. See duplicate-id.ts's header for why\n * the check has to live HERE (at the moment of registration) rather than after the stack body\n * has finished running.\n *\n * Usage, in a resource's own file, right where it's exported today:\n *\n * ```ts\n * export const CaddyConfig = guardDuplicateIds(Resource<CaddyConfig>('Caddy.Config', { … }));\n * ```\n *\n * ★ A `Proxy` around the REAL class, not a reimplementation. `Resource()`'s return value is a\n *   callable object wearing an `Effectable.Prototype` (`Effect.isEffect(MyResource) === true`,\n *   for the bare-tag platform-resource pattern) plus `.ref`, `.Type`, `.Provider`, `.Self`,\n *   `.Aliases` — reconstructing that shape risks silently dropping one of them. A `Proxy` whose\n *   `get` trap is the default (`Reflect.get`) forwards every property read untouched; only the\n *   `apply` trap — the `MyResource(\"id\", props)` call form — is new behaviour.\n * ⚠️ THE \"REGISTER METHODS\" OVERLOAD IS DELIBERATELY LEFT ALONE. `ResourceClass` is also callable\n *   with a single object argument to attach methods (`Resource()`'s own `typeof args[0] ===\n *   'object' ? Object.assign(...) : constructor(...)` branch) — that call mutates and returns the\n *   SAME class, carries no logical id, and has nothing to claim. Only a string first argument\n *   (the `(id, props)` form) goes through `claimResourceId`.\n */\nimport type { ResourceClass, ResourceLike } from 'alchemy/Resource';\nimport * as Effect from 'effect/Effect';\nimport { claimResourceId } from './duplicate-id.ts';\n\nexport const guardDuplicateIds = <R extends ResourceLike>(\n  resourceClass: ResourceClass<R>,\n): ResourceClass<R> =>\n  new Proxy(resourceClass, {\n    apply(target, thisArg, args: unknown[]) {\n      const id = args[0];\n      if (typeof id !== 'string') {\n        // The \"attach methods\" overload — not a registration, nothing to claim.\n        return Reflect.apply(target as (...a: unknown[]) => unknown, thisArg, args);\n      }\n      return Effect.gen(function* () {\n        yield* claimResourceId(resourceClass.Type, id);\n        return yield* Reflect.apply(\n          target as (...a: unknown[]) => unknown,\n          thisArg,\n          args,\n        ) as Effect.Effect<R>;\n      });\n    },\n  }) as ResourceClass<R>;\n"
+    "/**\n * `DuplicateResourceIdError` and the pinned alchemy version the kit's patch targets.\n *\n * ★ THE FIX ITSELF IS NOT HERE. A second resource of a different type claiming an id already\n *   taken in one stack scope is refused by a PATCH to `alchemy`'s own `Resource.ts` — see\n *   `../../patches/alchemy@2.0.0-beta.81.patch` and docs/duplicate-resource-id.md for why a\n *   kit-side `Proxy` wrapper (PR 468's first version, replaced by this PR) cannot actually\n *   catch the incident it was built for: wrapping `@homeflare/alchemy`'s OWN resource exports\n *   never reaches `NixJobRetirement`, a resource homeflare-mini declares directly against\n *   `alchemy`'s `Resource()`, so the measured collision still succeeded silently in BOTH\n *   orderings. This file now holds only:\n *\n *   1. `DuplicateResourceIdError` — the exact shape the patched `alchemy` throws, duplicated\n *      here (not imported — `alchemy` cannot depend on `@homeflare/alchemy`) purely so a\n *      consumer can write `Effect.catchTag(\"DuplicateResourceIdError\", …)` against a type this\n *      package exports, without needing to know alchemy carries its own copy of the same tag.\n *      Effect dispatches `catchTag` on the `_tag` STRING, not `instanceof`, so either class\n *      works identically as a catch target.\n *   2. `PATCHED_ALCHEMY_VERSION` — the exact alchemy version THIS package's own peer pin and\n *      devDependency sit at, and the one `duplicate-id.test.ts` drives its real `Stack` against.\n *      Hardcoded, like `ESTATE_VERSIONS` in `@homeflare/config/versions` (the same reasoning:\n *      a second source of truth derived by import would cross `tsconfig.build.json`'s\n *      `rootDir: \"src\"` boundary to reach `package.json`). `duplicate-id.test.ts` asserts it\n *      still matches this package's own `peerDependencies.alchemy`, so a pin bump that forgets\n *      to re-cut the patch fails a test here instead of silently shipping a patch filename that\n *      no longer matches what consumers install.\n *   3. `PATCHED_ALCHEMY_VERSIONS` — every alchemy version this package ships a CUT patch for\n *      (currently beta.81 and beta.83, kit PR shipping beta.83's — a consumer on beta.82 or\n *      beta.84 is NOT covered merely by being \"close\"; `bun`'s patch format keys to an exact\n *      version string, and a patch cut against one version is not guaranteed to even apply to\n *      another — see docs/duplicate-resource-id.md for why a diff was taken between the two\n *      tarballs rather than assumed). `checkAlchemyPatch` (`patch-check.ts`) walks this list to\n *      find the shipped patch matching a consumer's ACTUAL install, so a stack on beta.83 is not\n *      forced to pin the single oldest supported version just to pass its own check.\n */\nimport * as Data from 'effect/Data';\n\n/**\n * Mirrors the error the patched `alchemy@2.0.0-beta.81` throws at registration — same `_tag`,\n * same fields — for a consumer that wants to `catchTag` it without importing from `alchemy`'s\n * own patched internals.\n *\n * ⚠️ ONLY `Type` IS COMPARED, NEVER `Props`. A platform-typed resource's tagged pattern\n * (`alchemy`'s own `Platform.ts` ~581) rewrites `Props` on a resource already registered, and a\n * bare-tag forward reference legitimately registers with `Props: undefined` until its\n * `.make(...)` Layer builds (`MissingImplementationError`'s own doc comment in `Resource.ts`).\n * Comparing props as well as type would make both of those die. `Type` is stable from a\n * resource's very first `yield*` and is exactly what distinguishes \"the same resource,\n * referenced twice\" (fine) from \"two different resources that picked the same id\" (refused).\n */\nexport class DuplicateResourceIdError extends Data.TaggedError('DuplicateResourceIdError')<{\n  message: string;\n  fqn: string;\n  /** The type that first claimed `fqn`. */\n  firstType: string;\n  /** The different type that tried to claim it again. */\n  secondType: string;\n}> {}\n\n/**\n * The exact `alchemy` version `patches/alchemy@2.0.0-beta.81.patch` was cut against — this\n * package's own peer pin, and the version `duplicate-id.test.ts` drives a real `Stack` over.\n * `duplicate-id.test.ts` keeps this honest against `package.json`'s own `peerDependencies`.\n *\n * ⛔ STAYS, MEANING BETA.81 — do not repoint this at beta.83. A consumer that calls\n * `checkAlchemyPatch` with an explicit `alchemyVersion` (or reads this constant directly)\n * must keep getting the same answer it always has; {@link PATCHED_ALCHEMY_VERSIONS} is the\n * list a caller walks to find ALL supported pins, this one constant is not retargeted to mean\n * \"whichever is newest.\"\n */\nexport const PATCHED_ALCHEMY_VERSION: string = '2.0.0-beta.81';\n\n/**\n * Every alchemy version `@homeflare/alchemy` ships a cut `patches/alchemy@<version>.patch`\n * for, oldest first. `checkAlchemyPatch` uses this to pick the shipped patch matching a\n * consumer's ACTUAL installed version instead of only ever checking against\n * {@link PATCHED_ALCHEMY_VERSION}. `patch-check.test.ts` and the static patch-coverage test\n * both assert every entry here has a real `patches/alchemy@<version>.patch` file.\n */\nexport const PATCHED_ALCHEMY_VERSIONS: readonly string[] = ['2.0.0-beta.81', '2.0.0-beta.83'];\n",
+    "/**\n * A consuming stack's own `check` calls `checkAlchemyPatch` to assert it actually carries the\n * duplicate-resource-id fix — not just that SOME version of `alchemy` is installed, but that\n * THIS install carries the patch, for the alchemy version it was cut against.\n *\n * ★ WHY A BUMP CAN OTHERWISE DROP IT SILENTLY. `patchedDependencies` keys a patch to an EXACT\n *   version string (`alchemy@2.0.0-beta.81`). `bun add alchemy@2.0.0-beta.82` leaves that key\n *   pointing at a version nothing installs anymore — `bun install` neither errors nor warns,\n *   it just stops applying the patch, and the stack is back to the original silent collision\n *   with every other gate still green. This check is what turns that bump into a failing\n *   `check`, the same way `tests/dist.test.ts` turns a build regression into a failing test\n *   instead of a surprise three repos downstream (this package's own AGENTS.md, \"the smoke\n *   test is not optional\").\n * ★ A STATIC CHECK, mirroring `@homeflare/config/check`'s `checkCopy`/`checkOxfmt` — not a\n *   functional probe that spins up a `Stack`/`Resource`/`Effect` harness on every `check` run.\n *   The functional proof that the patch's LOGIC works lives in this package's own\n *   `duplicate-id.test.ts`, against the exact pinned version; a consumer's `check` only needs\n *   to know whether ITS install carries that same patch, applied — three file reads, no\n *   `effect` runtime pulled into every repo's check step.\n * ⛔ IT REPORTS, IT DOES NOT REPAIR, same as `checkProject` in `@homeflare/config/check` — this\n *   never edits `package.json` or re-runs `bun install` for the caller.\n */\nimport { PATCHED_ALCHEMY_VERSION, PATCHED_ALCHEMY_VERSIONS } from './duplicate-id.ts';\n\n/** One thing wrong with a consuming stack's alchemy patch, in the imperative. */\nexport type PatchProblem = string;\n\nconst patchKey = (version: string) => `alchemy@${version}`;\n\n/** Where THIS package's own shipped copy of the patch lives, however it was installed. */\nconst shippedPatchPath = (version: string): string =>\n  new URL(`../../patches/${patchKey(version)}.patch`, import.meta.url).pathname;\n\ntype PackageJson = {\n  readonly patchedDependencies?: Readonly<Record<string, string>>;\n};\n\n/**\n * @param projectDir The consuming stack's OWN repo root (where its `package.json` and\n *   `patches/` directory live) — never this kit's own.\n * @param alchemyVersion The version to check for. Omitted (the normal case): the version\n *   actually installed at `projectDir` is used, so a consumer on ANY version this package\n *   ships a patch for ({@link PATCHED_ALCHEMY_VERSIONS}) passes without having to pin\n *   {@link PATCHED_ALCHEMY_VERSION} specifically — a stack on beta.83 is checked against the\n *   beta.83 patch, one on beta.81 against the beta.81 patch. A caller passes this explicitly\n *   only to assert a SPECIFIC pin regardless of what happens to be installed (as the tests do).\n */\nexport const checkAlchemyPatch = async (\n  projectDir: string,\n  alchemyVersion?: string,\n): Promise<readonly PatchProblem[]> => {\n  const problems: PatchProblem[] = [];\n\n  const installedPkg = Bun.file(`${projectDir}/node_modules/alchemy/package.json`);\n  if (!(await installedPkg.exists())) {\n    problems.push('node_modules/alchemy: not installed — nothing to check the patch against');\n    return problems;\n  }\n  const installedVersion = ((await installedPkg.json()) as { version?: string }).version;\n\n  // No explicit ask: check against whatever is ACTUALLY installed, not a single hardcoded\n  // pin — that is what lets a beta.83 consumer pass without also being on beta.81.\n  const targetVersion = alchemyVersion ?? installedVersion ?? PATCHED_ALCHEMY_VERSION;\n  const key = patchKey(targetVersion);\n\n  if (!PATCHED_ALCHEMY_VERSIONS.includes(targetVersion)) {\n    problems.push(\n      // ★ Name the version being CHECKED: with an explicit `alchemyVersion` it can differ from\n      //   the installed one, and naming the installed version then blames a supported one.\n      `alchemy ${targetVersion} (installed: ${installedVersion ?? 'unknown'}) is a version ` +\n        `@homeflare/alchemy has ` +\n        `no duplicate-resource-id patch for — supported versions are ` +\n        `${PATCHED_ALCHEMY_VERSIONS.join(', ')}; cut a new patches/${key}.patch ` +\n        \"(@homeflare/alchemy's own patches/) before bumping alchemy, or this install has no \" +\n        'protection at all',\n    );\n    return problems;\n  }\n  if (installedVersion !== targetVersion) {\n    problems.push(\n      `node_modules/alchemy is ${installedVersion ?? 'unknown'}, but the duplicate-resource-id ` +\n        `check was asked for ${targetVersion} — pass the installed version explicitly, or omit ` +\n        'alchemyVersion to check against whatever is actually installed',\n    );\n    return problems;\n  }\n\n  const pkgFile = Bun.file(`${projectDir}/package.json`);\n  if (!(await pkgFile.exists())) {\n    problems.push('package.json: missing');\n    return problems;\n  }\n  const pkg = (await pkgFile.json()) as PackageJson;\n  const declaredPath = pkg.patchedDependencies?.[key];\n  if (declaredPath === undefined) {\n    problems.push(\n      `package.json: patchedDependencies has no entry for \"${key}\" — this stack has no ` +\n        'duplicate-resource-id protection at all; see @homeflare/alchemy/docs/duplicate-resource-id.md',\n    );\n    return problems;\n  }\n\n  const theirs = Bun.file(`${projectDir}/${declaredPath}`);\n  if (!(await theirs.exists())) {\n    problems.push(`package.json declares \"${key}\" at ${declaredPath}, but that file is missing`);\n    return problems;\n  }\n  const ours = Bun.file(shippedPatchPath(targetVersion));\n  if (!(await ours.exists())) {\n    // The kit's own tarball is missing its patch — a packaging bug, not the consumer's.\n    problems.push(`@homeflare/alchemy ships no patches/${key}.patch to compare against`);\n    return problems;\n  }\n  if ((await theirs.text()) !== (await ours.text())) {\n    problems.push(\n      `${declaredPath}: differs from @homeflare/alchemy's shipped patch — re-copy it, ` +\n        'or say why it differs',\n    );\n  }\n\n  // Declared and byte-identical is not yet APPLIED: a hand-edited patchedDependencies entry,\n  // or an install under a package manager that does not support bun's patch format, leaves\n  // node_modules unpatched with nothing above noticing. One cheap textual proof it landed.\n  const resourceSrc = Bun.file(`${projectDir}/node_modules/alchemy/src/Resource.ts`);\n  const resourceLib = Bun.file(`${projectDir}/node_modules/alchemy/lib/Resource.js`);\n  const marker = 'DuplicateResourceIdError';\n  const [srcText, libText] = await Promise.all([\n    resourceSrc.exists().then((ok) => (ok ? resourceSrc.text() : '')),\n    resourceLib.exists().then((ok) => (ok ? resourceLib.text() : '')),\n  ]);\n  if (!srcText.includes(marker) && !libText.includes(marker)) {\n    problems.push(\n      'node_modules/alchemy/{src/Resource.ts,lib/Resource.js}: neither contains the patch — ' +\n        'declared in package.json but not applied; re-run `bun install`',\n    );\n  }\n\n  return problems;\n};\n"
   ],
-  "mappings": ";AA8BA;AACA;AACA;AACA;AACA;AAAA;AAMO,MAAM,iCAAsC,iBAAY,0BAA0B,EAMtF;AAAC;AAEJ,IAAM,aAAa,CAAC,cAAiD;AAAA,EACnE,IAAI,CAAC;AAAA,IAAW,OAAO;AAAA,EACvB,MAAM,OAAiB,CAAC;AAAA,EACxB,IAAI,OAAkC;AAAA,EACtC,OAAO,MAAM;AAAA,IACX,KAAK,QAAQ,KAAK,EAAE;AAAA,IACpB,OAAO,KAAK;AAAA,EACd;AAAA,EACA,OAAO,KAAK,KAAK,GAAG;AAAA;AAUtB,IAAM,aAAa,IAAI;AAEvB,IAAM,cAAc,CAAC,UAAuC;AAAA,EAC1D,MAAM,WAAW,WAAW,IAAI,KAAK;AAAA,EACrC,IAAI;AAAA,IAAU,OAAO;AAAA,EACrB,MAAM,UAAU,IAAI;AAAA,EACpB,WAAW,IAAI,OAAO,OAAO;AAAA,EAC7B,OAAO;AAAA;AAeF,IAAM,kBAAkB,CAAC,MAAc,OACrC,WAAI,UAAU,GAAG;AAAA,EACtB,MAAM,QAAQ,OAAO;AAAA,EACrB,MAAM,YAAY,OAAO;AAAA,EACzB,MAAM,MAAM,MAAM,WAAW,EAAE;AAAA,EAC/B,MAAM,WAAW,YAAY,KAAK;AAAA,EAClC,MAAM,YAAY,SAAS,IAAI,GAAG;AAAA,EAClC,IAAI,cAAc,WAAW;AAAA,IAC3B,SAAS,IAAI,KAAK,IAAI;AAAA,IACtB;AAAA,EACF;AAAA,EACA,IAAI,cAAc,MAAM;AAAA,IACtB,OAAO,OAAc,WACnB,IAAI,yBAAyB;AAAA,MAC3B,SACE,oCAAoC,iBAAiB,WAAW,SAAS,QACzE,qBAAqB,uBAAuB;AAAA,MAC9C;AAAA,MACA,OAAO,WAAW,SAAS;AAAA,MAC3B;AAAA,MACA,YAAY;AAAA,IACd,CAAC,CACH;AAAA,EACF;AAAA,CACD;;ACtFH;AAGO,IAAM,oBAAoB,CAC/B,kBAEA,IAAI,MAAM,eAAe;AAAA,EACvB,KAAK,CAAC,QAAQ,SAAS,MAAiB;AAAA,IACtC,MAAM,KAAK,KAAK;AAAA,IAChB,IAAI,OAAO,OAAO,UAAU;AAAA,MAE1B,OAAO,QAAQ,MAAM,QAAwC,SAAS,IAAI;AAAA,IAC5E;AAAA,IACA,OAAc,YAAI,UAAU,GAAG;AAAA,MAC7B,OAAO,gBAAgB,cAAc,MAAM,EAAE;AAAA,MAC7C,OAAO,OAAO,QAAQ,MACpB,QACA,SACA,IACF;AAAA,KACD;AAAA;AAEL,CAAC;",
-  "debugId": "1AB58BD65E38742164756E2164756E21",
+  "mappings": ";AAmCA;AAAA;AAeO,MAAM,iCAAsC,iBAAY,0BAA0B,EAOtF;AAAC;AAaG,IAAM,0BAAkC;AASxC,IAAM,2BAA8C,CAAC,iBAAiB,eAAe;;ACpD5F,IAAM,WAAW,CAAC,YAAoB,WAAW;AAGjD,IAAM,mBAAmB,CAAC,YACxB,IAAI,IAAI,iBAAiB,SAAS,OAAO,WAAW,YAAY,GAAG,EAAE;AAgBhE,IAAM,oBAAoB,OAC/B,YACA,mBACqC;AAAA,EACrC,MAAM,WAA2B,CAAC;AAAA,EAElC,MAAM,eAAe,IAAI,KAAK,GAAG,8CAA8C;AAAA,EAC/E,IAAI,CAAE,MAAM,aAAa,OAAO,GAAI;AAAA,IAClC,SAAS,KAAK,0EAA0E;AAAA,IACxF,OAAO;AAAA,EACT;AAAA,EACA,MAAM,oBAAqB,MAAM,aAAa,KAAK,GAA4B;AAAA,EAI/E,MAAM,gBAAgB,kBAAkB,oBAAoB;AAAA,EAC5D,MAAM,MAAM,SAAS,aAAa;AAAA,EAElC,IAAI,CAAC,yBAAyB,SAAS,aAAa,GAAG;AAAA,IACrD,SAAS,KAGP,WAAW,6BAA6B,oBAAoB,6BAC1D,4BACA,iEACA,GAAG,yBAAyB,KAAK,IAAI,wBAAwB,eAC7D,wFACA,mBACJ;AAAA,IACA,OAAO;AAAA,EACT;AAAA,EACA,IAAI,qBAAqB,eAAe;AAAA,IACtC,SAAS,KACP,2BAA2B,oBAAoB,8CAC7C,uBAAuB,oEACvB,gEACJ;AAAA,IACA,OAAO;AAAA,EACT;AAAA,EAEA,MAAM,UAAU,IAAI,KAAK,GAAG,yBAAyB;AAAA,EACrD,IAAI,CAAE,MAAM,QAAQ,OAAO,GAAI;AAAA,IAC7B,SAAS,KAAK,uBAAuB;AAAA,IACrC,OAAO;AAAA,EACT;AAAA,EACA,MAAM,MAAO,MAAM,QAAQ,KAAK;AAAA,EAChC,MAAM,eAAe,IAAI,sBAAsB;AAAA,EAC/C,IAAI,iBAAiB,WAAW;AAAA,IAC9B,SAAS,KACP,uDAAuD,8BACrD,+FACJ;AAAA,IACA,OAAO;AAAA,EACT;AAAA,EAEA,MAAM,SAAS,IAAI,KAAK,GAAG,cAAc,cAAc;AAAA,EACvD,IAAI,CAAE,MAAM,OAAO,OAAO,GAAI;AAAA,IAC5B,SAAS,KAAK,0BAA0B,WAAW,wCAAwC;AAAA,IAC3F,OAAO;AAAA,EACT;AAAA,EACA,MAAM,OAAO,IAAI,KAAK,iBAAiB,aAAa,CAAC;AAAA,EACrD,IAAI,CAAE,MAAM,KAAK,OAAO,GAAI;AAAA,IAE1B,SAAS,KAAK,uCAAuC,8BAA8B;AAAA,IACnF,OAAO;AAAA,EACT;AAAA,EACA,IAAK,MAAM,OAAO,KAAK,MAAQ,MAAM,KAAK,KAAK,GAAI;AAAA,IACjD,SAAS,KACP,GAAG,iFACD,uBACJ;AAAA,EACF;AAAA,EAKA,MAAM,cAAc,IAAI,KAAK,GAAG,iDAAiD;AAAA,EACjF,MAAM,cAAc,IAAI,KAAK,GAAG,iDAAiD;AAAA,EACjF,MAAM,SAAS;AAAA,EACf,OAAO,SAAS,WAAW,MAAM,QAAQ,IAAI;AAAA,IAC3C,YAAY,OAAO,EAAE,KAAK,CAAC,OAAQ,KAAK,YAAY,KAAK,IAAI,EAAG;AAAA,IAChE,YAAY,OAAO,EAAE,KAAK,CAAC,OAAQ,KAAK,YAAY,KAAK,IAAI,EAAG;AAAA,EAClE,CAAC;AAAA,EACD,IAAI,CAAC,QAAQ,SAAS,MAAM,KAAK,CAAC,QAAQ,SAAS,MAAM,GAAG;AAAA,IAC1D,SAAS,KACP,0FACE,gEACJ;AAAA,EACF;AAAA,EAEA,OAAO;AAAA;",
+  "debugId": "461D34CD68FB220064756E2164756E21",
   "names": []
 }

package/dist/scope/patch-check.d.ts

@@ -0,0 +1,14 @@
+/** One thing wrong with a consuming stack's alchemy patch, in the imperative. */
+export type PatchProblem = 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 declare const checkAlchemyPatch: (projectDir: string, alchemyVersion?: string) => Promise<readonly PatchProblem[]>;
+//# sourceMappingURL=patch-check.d.ts.map

package/dist/scope/patch-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch-check.d.ts","sourceRoot":"","sources":["../../src/scope/patch-check.ts"],"names":[],"mappings":"AAwBA,iFAAiF;AACjF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAYlC;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,eAChB,MAAM,mBACD,MAAM,KACtB,OAAO,CAAC,SAAS,YAAY,EAAE,CAwFjC,CAAC"}

package/docs/duplicate-resource-id.md

@@ -1,23 +1,45 @@
-# `@homeflare/alchemy/scope` — refuse a duplicate resource id
+# 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.
+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 this fixes
+## 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. Alchemy did not error: 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. homeflare-mini PR 329
-prefixed that resource's ids as a one-off fix; nothing stopped the next collision in any stack.
-
-## Why Alchemy's own engine lets this through
-
-Alchemy's `Resource()` constructor (`alchemy@2.0.0-beta.81`, `Resource.ts`) treats a second
-`yield*` at an already-registered FQN as an idempotent re-reference — correct for "the same
-resource, read from two call sites" — and returns the first-registered resource without comparing
+`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
@@ -29,63 +51,104 @@ if (existing) {
 }
 ```
 
-That TODO is the gap. The second resource's props are never written anywhere — `stack.resources`
-never changes — so nothing downstream, including this package's own `hf-adopt-verify`, can tell
-two different registrations happened. Measured directly (`src/scope/duplicate-id.ts`'s header
-has the reproduction): registering `Test.ResourceB('shared-id', …)` right after
-`Test.ResourceA('shared-id', …)` compiles a stack whose only entry at that fqn reports
-`Type: 'Test.ResourceA'`.
+## The patch
 
-This is why the check cannot be a post-hoc scan over the compiled stack — by the time a plan runs,
-the collision has already been silently resolved in the first resource's favor. The only point
-where both the existing claim and the new claimant's type are in hand is at registration itself.
+`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:
 
-## What this package ships
+```
+REFUSING: duplicate resource id "caddy" in scope (root): first declared by Nix.JobRetirement, again by Caddy.Config
+```
 
-`guardDuplicateIds` wraps a `ResourceClass` so every `("id", props)` call first claims that id in
-a per-stack, per-namespace registry, and dies with `DuplicateResourceIdError` the moment a
-different type claims an id already taken:
+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.
+
+### Supported versions
+
+`patchedDependencies` keys to an EXACT version string, and `bun`'s patch format is not
+guaranteed to apply across versions even when the surrounding file is otherwise unchanged — so
+each alchemy version this covers gets its OWN cut, byte-diffed against that version's real
+tarball, not a renamed copy:
+
+| alchemy version | patch file                            |
+| --------------- | ------------------------------------- |
+| `2.0.0-beta.81` | `patches/alchemy@2.0.0-beta.81.patch` |
+| `2.0.0-beta.83` | `patches/alchemy@2.0.0-beta.83.patch` |
+
+Between beta.81 and beta.83, upstream's only change touching these three files was an
+unrelated, cosmetic rewrite of `isResource` (a function body collapsed to an arrow
+expression) earlier in `src/Resource.ts` / `lib/Resource.js` — `lib/Resource.d.ts` is
+byte-identical between the two. The patched spot itself (the `TODO(sam)` branch and its
+surrounding context) is unchanged content, shifted by the line count that earlier rewrite
+added or removed. `PATCHED_ALCHEMY_VERSIONS` (`@homeflare/alchemy/scope`) is the authoritative
+list; `checkAlchemyPatch` walks it to find the entry matching what is actually installed.
+A version not in that list — beta.82 included — has no patch cut for it; adopt the nearest
+supported version's workflow below and open an issue, rather than assuming an untested patch
+applies.
+
+**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
+
+Pick the file matching the stack's OWN installed `alchemy` version from the table above —
+here shown for beta.83; beta.81 is identical with the version string swapped:
+
+```sh
+cp node_modules/@homeflare/alchemy/patches/alchemy@2.0.0-beta.83.patch patches/
+```
 
-```ts
-import { Resource } from 'alchemy';
-import { guardDuplicateIds } from '@homeflare/alchemy/scope';
+then add, in the stack's own root `package.json`:
 
-export const MyResource = guardDuplicateIds(Resource<MyResource>('My.Resource'));
+```json
+"patchedDependencies": {
+  "alchemy@2.0.0-beta.83": "patches/alchemy@2.0.0-beta.83.patch"
+}
 ```
 
-The error names both sides:
+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);
+}
 ```
-REFUSING: duplicate resource id "caddy" in scope (root): first declared by Nix.JobRetirement, again by Caddy.Config
-```
 
-`Caddy.Config` (this package's `caddy/config.ts`) carries the guard already — it was one half of
-the measured incident. Every other `@homeflare/alchemy` resource adopts it as its own file is next
-touched (provider-standard.md, rule S47); there is no mechanical migration of every family in this
-one change.
-
-## What it does, and does not, cover
-
-- **Scope matches Alchemy's own FQN.** The registry is keyed by `toFqn(namespace, id)`, the exact
-  string Alchemy itself uses for state storage — the same id in a nested namespace
-  (`Namespace.push('child', …)`) is a different scope and never collides. Two different stacks
-  (two different `Stack` service instances) never see each other's claims either.
-- **The same type re-registering its own id is still fine.** That is Alchemy's legitimate
-  "reference the same resource from two call sites" pattern; `guardDuplicateIds` only refuses a
-  _different_ type at an already-claimed id.
-- **Both sides must be wrapped.** `guardDuplicateIds` is a `Proxy` around one resource class; it
-  has no way to see a DIFFERENT, unwrapped class's registration. A guarded `Caddy.Config` beside
-  an unguarded, hand-rolled `Resource('Nix.JobRetirement')` in a consuming stack still collides
-  silently — `guard.test.ts`'s "one guarded, one unguarded" case asserts this directly, so it is
-  documented behavior rather than a surprise. A stack's own custom resource types get full
-  protection the same way `Caddy.Config` does: wrap the export in `guardDuplicateIds`.
-- **It does not catch a collision against a vendor built-in** (e.g. `Cloudflare.Worker`) unless
-  that export is also wrapped — this package cannot wrap a class it does not author. See "Upstream"
-  below for the fix that would close this for every resource, vendor included.
+With no second argument, it checks against whatever `alchemy` version is ACTUALLY installed
+at that stack's root — a stack on beta.83 is checked against the beta.83 patch, one on beta.81
+against the beta.81 patch, neither has to pin `PATCHED_ALCHEMY_VERSION` (which stays beta.81,
+for the consumer that already reads it directly) to pass. Pass a version explicitly only to
+assert a SPECIFIC pin regardless of what is installed.
+
+It is a static check — three file reads, no `effect` runtime spun up — covering: alchemy
+installed at a version `@homeflare/alchemy` has no shipped patch for at all (`PATCHED_ALCHEMY_VERSIONS`
+names every version it DOES cover), an explicit ask that disagrees with what is installed, 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`'s own `Resource.ts`, at the `if (existing)` branch quoted above,
-where the TODO already sits — every resource, ours and every vendor built-in, goes through that
-one function. This PR's body has the issue text proposed for `alchemy-run/alchemy`; it has not
-been filed.
+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,15 +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 (added 2026-10-19, kit-local — not yet one of the skill's 46; house gap,
-  decision 49: upstream is silent, this rule fills it).** A touched or new resource's exported
-  `ResourceClass` is wrapped in
-  `guardDuplicateIds` (`@homeflare/alchemy/scope`): `export const X = guardDuplicateIds(Resource<X>(…))`.
-  Without it, a second, different-typed resource declaring the same logical id in one stack
-  silently wins — Alchemy's own idempotent-registration path returns the first-registered
-  resource with no `Type` check (measured, homeflare-mini PR 329;
-  [duplicate-resource-id.md](./duplicate-resource-id.md)). `Caddy.Config` carries it; every other
-  family adopts it the next time its own file is touched, not as one mechanical sweep.
+- **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.59.0",
+  "version": "0.61.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",