@homeflare/alchemy 0.57.0 → 0.59.0

package/docs/duplicate-resource-id.md

@@ -0,0 +1,91 @@
+# `@homeflare/alchemy/scope` — refuse a duplicate resource id
+
+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 incident this fixes
+
+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
+`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;
+}
+```
+
+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'`.
+
+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.
+
+## What this package ships
+
+`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:
+
+```ts
+import { Resource } from 'alchemy';
+import { guardDuplicateIds } from '@homeflare/alchemy/scope';
+
+export const MyResource = guardDuplicateIds(Resource<MyResource>('My.Resource'));
+```
+
+The error names both sides:
+
+```
+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.
+
+## 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.

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 (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.
 
 ## Code, errors, credentials
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.57.0",
+  "version": "0.59.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",
@@ -131,6 +131,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/src/caddy/config.ts

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

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

@@ -0,0 +1,95 @@
+/**
+ * `claimResourceId` against a minimal `Stack` + `Namespace` context — no real resources, no
+ * provider, so these stay fast and pin the registry's own semantics directly. guard.test.ts
+ * drives the same cases through a REAL `Alchemy.Stack(...)` with real `Resource()` classes, to
+ * prove the wiring in guard.ts, not just this file's logic in isolation.
+ */
+import { describe, expect, test } from 'bun:test';
+import { push as pushNamespace } from 'alchemy/Namespace';
+import { Stack } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import { DuplicateResourceIdError, claimResourceId } from './duplicate-id.ts';
+
+/** A bare `Stack` service good enough for `claimResourceId`: only `resources` is ever `yield*`ed. */
+const fakeStack = () => ({ name: 'test', stage: 'test', resources: {}, bindings: {}, actions: {} });
+
+const withStack = <A, E>(effect: Effect.Effect<A, E, Stack>) =>
+  effect.pipe(Effect.provideService(Stack, fakeStack() as never));
+
+describe('claimResourceId', () => {
+  test('a fresh id is claimed without error', async () => {
+    await Effect.runPromise(withStack(claimResourceId('Test.A', 'one')));
+  });
+
+  test('the same type re-claiming its own id is fine (idempotent re-reference)', async () => {
+    await Effect.runPromise(
+      withStack(
+        Effect.gen(function* () {
+          yield* claimResourceId('Test.A', 'one');
+          yield* claimResourceId('Test.A', 'one');
+        }),
+      ),
+    );
+  });
+
+  test('distinct ids never collide', async () => {
+    await Effect.runPromise(
+      withStack(
+        Effect.gen(function* () {
+          yield* claimResourceId('Test.A', 'one');
+          yield* claimResourceId('Test.B', 'two');
+        }),
+      ),
+    );
+  });
+
+  test('a second, different type claiming a taken id dies naming both types', async () => {
+    const run = Effect.runPromiseExit(
+      withStack(
+        Effect.gen(function* () {
+          yield* claimResourceId('Nix.JobRetirement', 'caddy');
+          yield* claimResourceId('Caddy.Config', 'caddy');
+        }),
+      ),
+    );
+    const exit = await run;
+    expect(exit._tag).toBe('Failure');
+    if (exit._tag !== 'Failure') return;
+    const [reason] = exit.cause.reasons;
+    const defect = reason?._tag === 'Die' ? reason.defect : undefined;
+    expect(defect).toBeInstanceOf(DuplicateResourceIdError);
+    const error = defect as DuplicateResourceIdError;
+    expect(error.message).toContain('REFUSING: duplicate resource id "caddy"');
+    expect(error.message).toContain('first declared by Nix.JobRetirement');
+    expect(error.message).toContain('again by Caddy.Config');
+    expect(error.scope).toBe('(root)');
+  });
+
+  test('the same id in a nested namespace is a different scope, so it does not collide', async () => {
+    await Effect.runPromise(
+      withStack(
+        Effect.gen(function* () {
+          yield* claimResourceId('Caddy.Config', 'caddy');
+          yield* pushNamespace('child', claimResourceId('Nix.JobRetirement', 'caddy'));
+        }),
+      ),
+    );
+  });
+
+  test('two unrelated stacks never see each others claims', async () => {
+    const stackOne = fakeStack();
+    const stackTwo = fakeStack();
+    await Effect.runPromise(
+      claimResourceId('Caddy.Config', 'caddy').pipe(
+        Effect.provideService(Stack, stackOne as never),
+      ),
+    );
+    // A DIFFERENT stack object claiming the same id with a different type is fine — the
+    // registry is keyed by the Stack instance (see duplicate-id.ts), not the bare fqn string.
+    await Effect.runPromise(
+      claimResourceId('Nix.JobRetirement', 'caddy').pipe(
+        Effect.provideService(Stack, stackTwo as never),
+      ),
+    );
+  });
+});

package/src/scope/duplicate-id.ts

@@ -0,0 +1,113 @@
+/**
+ * Refuse a second resource claiming a logical id already taken in the same stack scope.
+ *
+ * ★ 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.
+ */
+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.
+ */
+export class DuplicateResourceIdError extends Data.TaggedError('DuplicateResourceIdError')<{
+  message: string;
+  fqn: string;
+  scope: string;
+  firstType: string;
+  secondType: string;
+}> {}
+
+const scopeLabel = (namespace: NamespaceNode | undefined): string => {
+  if (!namespace) return '(root)';
+  const path: string[] = [];
+  let node: NamespaceNode | undefined = namespace;
+  while (node) {
+    path.unshift(node.Id);
+    node = node.Parent;
+  }
+  return path.join('/');
+};
+
+/**
+ * One registry per compiled stack, keyed by the `Stack` service object `yield* Stack` returns
+ * (a fresh `StackSpec` per `Alchemy.Stack(...)`/`make()` call — see `Stack.ts`'s `Layer.effect`).
+ * A `WeakMap` so two unrelated stacks (sequential test runs, two stacks in one process) never see
+ * each other's claims, and so the registry is collected with the stack instead of growing forever
+ * in a long-running process (an `alchemy dev` watch loop, this package's own test suite).
+ */
+const registries = new WeakMap<object, Map<string, string>>();
+
+const registryFor = (stack: object): Map<string, string> => {
+  const existing = registries.get(stack);
+  if (existing) return existing;
+  const created = new Map<string, string>();
+  registries.set(stack, created);
+  return created;
+};
+
+/**
+ * Claim `id` for `type` in the current namespace scope. Fine the first time, and fine again for
+ * the SAME type (the legitimate "yield the same resource from two call sites" pattern Alchemy's
+ * own idempotent registration supports). Dies with {@link DuplicateResourceIdError} the moment a
+ * DIFFERENT type claims an id already taken — before that second resource's provider ever runs.
+ *
+ * ⚠️ `Effect.die`, NOT a typed failure. This runs at registration, not inside a lifecycle
+ * operation (`read`/`diff`/`reconcile`/`delete`) — the provider-standard's S20 ban on
+ * `Effect.orDie` in LIFECYCLE operations does not apply here, and `ConflictingProviderModeError`
+ * right next door in upstream's own `Resource.ts` dies the same way for the same reason: there is
+ * no recovery a caller could usefully attempt mid-registration.
+ */
+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,
+        }),
+      );
+    }
+  });

package/src/scope/guard.test.ts

@@ -0,0 +1,128 @@
+/**
+ * `guardDuplicateIds` driven through a REAL `Alchemy.Stack(...)` body with real `Resource()`
+ * classes — the same shape `litellm/fake-stack.ts` and `github/repo-apply-order-fake-stack.ts`
+ * use for the same reason their own headers give: a check built only against this module's own
+ * logic (duplicate-id.test.ts) proves the registry works, not that wiring it onto a resource
+ * class via a `Proxy` actually intercepts the call Alchemy itself makes when a stack body
+ * `yield*`s it.
+ *
+ * ⚠️ `dup-experiment.ts` (this PR's own throwaway script, not checked in) first measured the
+ *   UNGUARDED failure mode this guards against: two different `Resource()` classes sharing a
+ *   logical id compile a stack whose only entry at that fqn is the FIRST type, with no trace the
+ *   second one ever ran. These tests are the regression guard for exactly that, once wrapped.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Alchemy from 'alchemy';
+import { push as pushNamespace } from 'alchemy/Namespace';
+import type { Resource, ResourceLike } from 'alchemy/Resource';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { guardDuplicateIds } from './guard.ts';
+
+interface Props {
+  readonly value: number;
+}
+interface TestResource extends Resource<string, Props, object> {}
+
+/** A plain `Resource()` class, wrapped, for a given vendor-style type string. */
+const guarded = (type: string) => guardDuplicateIds(Alchemy.Resource<TestResource>(type));
+
+type StackBody = Effect.Effect<unknown, unknown, unknown>;
+
+/** Same cast-at-the-typed-boundary shape as `litellm/fake-stack.ts`; see that file's own header. */
+const runStack = (body: StackBody) => {
+  const state = Alchemy.inMemoryState();
+  const stack = Alchemy.Stack as unknown as (
+    stackName: string,
+    options: { providers: Layer.Layer<never>; state: typeof state },
+    body: StackBody,
+  ) => Effect.Effect<
+    { readonly resources: Readonly<Record<string, ResourceLike>> },
+    unknown,
+    never
+  >;
+  return Effect.runPromiseExit(
+    stack('GuardTestStack', { providers: Layer.empty, state }, body).pipe(
+      Effect.provideService(Alchemy.Stage, 'test'),
+      Effect.scoped,
+    ),
+  );
+};
+
+describe('guardDuplicateIds, through a real stack', () => {
+  test('distinct ids both register', async () => {
+    const A = guarded('Test.A');
+    const B = guarded('Test.B');
+    const exit = await runStack(
+      Effect.gen(function* () {
+        yield* A('one', { value: 1 });
+        yield* B('two', { value: 2 });
+      }),
+    );
+    expect(exit._tag).toBe('Success');
+    if (exit._tag !== 'Success') return;
+    expect(Object.keys(exit.value.resources).sort()).toEqual(['one', 'two']);
+  });
+
+  test('the same guarded type re-registering its own id stays a noop, not a death', async () => {
+    const A = guarded('Test.A');
+    const exit = await runStack(
+      Effect.gen(function* () {
+        yield* A('shared', { value: 1 });
+        yield* A('shared', { value: 1 });
+      }),
+    );
+    expect(exit._tag).toBe('Success');
+  });
+
+  test('two different guarded types sharing an id die naming both, before either resource "wins"', async () => {
+    const Retirement = guarded('Nix.JobRetirement');
+    const Caddy = guarded('Caddy.Config');
+    const exit = await runStack(
+      Effect.gen(function* () {
+        yield* Retirement('caddy', { value: 1 });
+        yield* Caddy('caddy', { value: 2 });
+      }),
+    );
+    expect(exit._tag).toBe('Failure');
+    if (exit._tag !== 'Failure') return;
+    const reasons = (exit.cause as { reasons: readonly { _tag: string; defect?: unknown }[] })
+      .reasons;
+    const reason = reasons[0];
+    expect(reason === undefined ? undefined : reason._tag).toBe('Die');
+    const defect = reason === undefined ? undefined : (reason.defect as Error | undefined);
+    expect(defect === undefined ? '' : String(defect.message)).toContain(
+      'REFUSING: duplicate resource id "caddy" in scope (root): ' +
+        'first declared by Nix.JobRetirement, again by Caddy.Config',
+    );
+  });
+
+  test('one guarded, one unguarded type sharing an id still dies (the guarded side still claims it)', async () => {
+    const Guarded = guarded('Test.Guarded');
+    const Unguarded = Alchemy.Resource<TestResource>('Test.Unguarded');
+    const exit = await runStack(
+      Effect.gen(function* () {
+        yield* Guarded('shared', { value: 1 });
+        yield* Unguarded('shared', { value: 2 });
+      }),
+    );
+    // The unguarded side never calls `claimResourceId`, so Alchemy's own idempotent-registration
+    // branch runs instead (Resource.ts) and this SUCCEEDS as a silent noop — exactly the gap this
+    // PR documents as out of scope for a kit-only fix (docs/duplicate-resource-id.md). Asserting
+    // the current behaviour, not endorsing it: `guardDuplicateIds` only protects pairs where BOTH
+    // sides are wrapped.
+    expect(exit._tag).toBe('Success');
+  });
+
+  test('the same id in a nested namespace is a different scope', async () => {
+    const Retirement = guarded('Nix.JobRetirement');
+    const Caddy = guarded('Caddy.Config');
+    const exit = await runStack(
+      Effect.gen(function* () {
+        yield* Retirement('caddy', { value: 1 });
+        yield* pushNamespace('child', Caddy('caddy', { value: 2 }));
+      }),
+    );
+    expect(exit._tag).toBe('Success');
+  });
+});

package/src/scope/guard.ts

@@ -0,0 +1,49 @@
+/**
+ * `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';
+import * as Effect from 'effect/Effect';
+import { claimResourceId } from './duplicate-id.ts';
+
+export const guardDuplicateIds = <R extends ResourceLike>(
+  resourceClass: ResourceClass<R>,
+): ResourceClass<R> =>
+  new Proxy(resourceClass, {
+    apply(target, thisArg, args: unknown[]) {
+      const id = args[0];
+      if (typeof id !== 'string') {
+        // The "attach methods" overload — not a registration, nothing to claim.
+        return Reflect.apply(target as (...a: unknown[]) => unknown, thisArg, args);
+      }
+      return Effect.gen(function* () {
+        yield* claimResourceId(resourceClass.Type, id);
+        return yield* Reflect.apply(
+          target as (...a: unknown[]) => unknown,
+          thisArg,
+          args,
+        ) as Effect.Effect<R>;
+      });
+    },
+  }) as ResourceClass<R>;

package/src/scope/index.ts

@@ -0,0 +1,20 @@
+/**
+ * `@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:
+ *
+ * ```ts
+ * import { guardDuplicateIds } from '@homeflare/alchemy/scope';
+ *
+ * export const NixJobRetirement = guardDuplicateIds(Resource<NixJobRetirement>('Nix.JobRetirement'));
+ * ```
+ *
+ * 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';

package/src/unifi/firewall-policy-drift.test.ts

@@ -149,3 +149,67 @@ describe('I2 -- every declarable field is wired into the drift field list', () =
     },
   );
 });
+
+describe('set-like nested filter arrays compare as sets (homeflare-network PR 79)', () => {
+  const dest = (ports: number[], ips: string[]) =>
+    ({
+      zoneId: 'zone-storage',
+      trafficFilter: {
+        type: 'IP_ADDRESS',
+        ipAddressFilter: {
+          type: 'IP_ADDRESSES',
+          matchOpposite: false,
+          items: ips.map((value) => ({ type: 'IP_ADDRESS', value })),
+        },
+        portFilter: {
+          type: 'PORTS',
+          matchOpposite: false,
+          items: ports.map((value) => ({ type: 'PORT_NUMBER', value })),
+        },
+      },
+    }) as unknown as FirewallPolicyProps['destination'];
+
+  test('the measured case: declared [443, 9100], live [9100, 443] is a noop', () => {
+    const props = { ...PROPS, destination: dest([443, 9100], ['10.20.14.10']) };
+    const live = liveFirewallPolicy({ destination: dest([9100, 443], ['10.20.14.10']) as never });
+    expect(matches(attributesOf(live, props), props)).toBe(true);
+    expect(driftOf(live, props)).toEqual([]);
+  });
+
+  test('IP items in another order are a noop too, on source as well as destination', () => {
+    const props = { ...PROPS, source: dest([], ['10.0.0.1', '10.0.0.2']) as never };
+    const live = liveFirewallPolicy({ source: dest([], ['10.0.0.2', '10.0.0.1']) as never });
+    expect(driftOf(live, props)).toEqual([]);
+  });
+
+  test('a membership change still drifts: a port swapped, added or dropped', () => {
+    const props = { ...PROPS, destination: dest([443, 9100], ['10.20.14.10']) };
+    for (const ports of [[443, 22], [443, 9100, 22], [443]]) {
+      const live = liveFirewallPolicy({ destination: dest(ports, ['10.20.14.10']) as never });
+      expect(
+        driftOf(live, props).map((d) => d.field),
+        String(ports),
+      ).toEqual(['destination']);
+    }
+  });
+
+  test('a duplicate is not collapsed away: [443, 443] differs from [443]', () => {
+    const props = { ...PROPS, destination: dest([443], ['10.20.14.10']) };
+    const live = liveFirewallPolicy({ destination: dest([443, 443], ['10.20.14.10']) as never });
+    expect(driftOf(live, props).map((d) => d.field)).toEqual(['destination']);
+  });
+
+  test('mixed port items sort the same whatever their key order (range vs number)', () => {
+    const range = { start: 8000, stop: 8100, type: 'PORT_NUMBER_RANGE' };
+    const rangeDecoded = { type: 'PORT_NUMBER_RANGE', start: 8000, stop: 8100 };
+    const one = { type: 'PORT_NUMBER', value: 443 };
+    const withItems = (items: unknown[]) =>
+      ({
+        zoneId: 'zone-storage',
+        trafficFilter: { type: 'PORT', portFilter: { type: 'PORTS', matchOpposite: false, items } },
+      }) as unknown as FirewallPolicyProps['destination'];
+    const props = { ...PROPS, destination: withItems([range, one]) };
+    const live = liveFirewallPolicy({ destination: withItems([one, rangeDecoded]) as never });
+    expect(driftOf(live, props)).toEqual([]);
+  });
+});