@homeflare/alchemy 0.35.0 → 0.37.0

package/src/argocd/resource.ts

@@ -0,0 +1,150 @@
+/**
+ * One shape for every Argo CD REST object — Repository, RepoCreds, Cluster — the same four
+ * operations, different distilled call.
+ *
+ * ⛔ THIS IS A NEAR-VERBATIM COPY OF `../forgejo/resource.ts`'S ENGINE, ON PURPOSE. Both SDKs speak
+ *   plain bearer-authenticated REST with a real `NotFound` tag (see the family's own docs.md for
+ *   why Argo CD, UNLIKE Discord, gets a genuine typed 404 — measured from `protocol.ts`), so the
+ *   same read/diff/reconcile/destroy shape applies unchanged. A second hand-rolled engine here
+ *   would just be forgejo's with the names swapped.
+ *
+ * ⚠️ NO `Unowned`/`adopt(true)` WRAPPING HERE — mirrors forgejo's own choice (not netbox's or
+ *   discord's `Unowned` marker), not an oversight. A live match on a cold read (no persisted
+ *   `output`) is treated as ours, same as every other forgejo-shaped family in this kit today.
+ *
+ * ⚠️ `NotFound` IS FOLDED TO "ABSENT" INSIDE EACH RESOURCE FILE'S OWN `fetchLive`, NOT HERE.
+ *   `Effect.catchTag`'s tag-literal inference needs a concrete error union to resolve `"NotFound"`
+ *   against; a spec's `E` is only concrete at each resource file's own call site. So every
+ *   `fetchLive` ends `.pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined)))` itself.
+ */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import { CredentialsFromEnv } from '@distilled.cloud/argocd/Credentials';
+import type { ArgocdOpContext } from '@distilled.cloud/argocd/Protocol';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+
+/** What every handler needs from the caller's runtime, once `argocdHandlers` bakes in credentials. */
+export type ArgocdRequirements = HttpClient.HttpClient;
+
+/**
+ * Strips undefined-valued keys, mapping each to a genuinely optional key rather than a present
+ * key typed `X | undefined`. `tsconfig.base.json` turns on `exactOptionalPropertyTypes`, and every
+ * generated Argo CD request type declares its optional fields the strict way (`foo?: X`, never
+ * `foo?: X | undefined`) — so `{ foo: props.foo }` where `props.foo?: X` does not typecheck against
+ * it even when `foo` is genuinely absent at runtime. Every resource file's request body goes
+ * through this once, mirroring `forgejo/repository.ts#editForm`'s conditional-spread idiom, just
+ * generalized instead of repeated per field.
+ */
+export const present = <T extends object>(obj: T): { [K in keyof T]?: Exclude<T[K], undefined> } =>
+  Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined)) as never;
+
+/**
+ * One Argo CD object's distilled calls. `Live` is whatever the SDK decodes (`V1alpha1Repository`,
+ * `V1alpha1Cluster`, …); `E` is left to each resource file to declare.
+ */
+export type ArgocdSpec<Props extends object, Live, Attributes, E> = {
+  /**
+   * The identity key's value — `repo`/`url`/`server` depending on the resource — read off
+   * declared props and off persisted attributes respectively. `diff` compares the two to detect
+   * an identity change, which `upsert`'s single create-or-converge call cannot express as an
+   * in-place update: Argo CD indexes each of these objects BY this value, so a changed identity
+   * means a create at the new key, never a rename, and the object left at the old key must be
+   * deleted — exactly what a `replace` diff action tells Alchemy's own Plan/Apply to do (delete
+   * the old physical object, using `olds`, then reconcile `news`). Without this, a changed
+   * `repo`/`url`/`server` orphans the old, still-credentialed object with no state pointing at it
+   * — found in adversarial review 2026-09-24, fixed here.
+   */
+  readonly identityOfProps: (props: Props) => string;
+  readonly identityOfAttributes: (attributes: Attributes) => string;
+  /** Already folds the SDK's `NotFound` to `undefined` via its own `catchTag` — see the note above. */
+  readonly fetchLive: (props: Props) => Effect.Effect<Live | undefined, E, ArgocdOpContext>;
+  readonly attributes: (live: Live, props: Props) => Attributes | undefined;
+  readonly matches: (attributes: Attributes, props: Props) => boolean;
+  /**
+   * A single upsert call — every Argo CD create endpoint this family uses takes `upsert: true`
+   * and converges create-or-update in one request, so there is no separate update path to wire.
+   */
+  readonly upsert: (props: Props) => Effect.Effect<unknown, E, ArgocdOpContext>;
+  readonly destroy: (props: Props, live: Live) => Effect.Effect<unknown, E, ArgocdOpContext>;
+};
+
+export const argocdOperations = <Props extends object, Live, Attributes, E>(
+  spec: ArgocdSpec<Props, Live, Attributes, E>,
+) => {
+  const read = (props: Props) =>
+    spec
+      .fetchLive(props)
+      .pipe(Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))));
+
+  return {
+    read,
+
+    diff: (news: Input<Props>, output: Attributes | undefined) =>
+      Effect.gen(function* () {
+        if (output === undefined || !isResolved(news)) return undefined;
+        // The identity key changed (repo/url/server) — `upsert` cannot rename in place, it would
+        // create at the new key and leave the old, still-live object orphaned. See the spec type.
+        if (spec.identityOfProps(news) !== spec.identityOfAttributes(output)) {
+          return { action: 'replace' } as const;
+        }
+        const live = yield* read(news);
+        if (live === undefined) return { action: 'update' } as const;
+        return spec.matches(live, news)
+          ? ({ action: 'noop' } as const)
+          : ({ action: 'update' } as const);
+      }),
+
+    reconcile: (news: Props) =>
+      Effect.gen(function* () {
+        const before = yield* read(news);
+        // S10: no write when what's declared already matches what's live.
+        if (before === undefined || !spec.matches(before, news)) {
+          yield* spec.upsert(news);
+        }
+        const after = yield* read(news);
+        if (after === undefined) {
+          return yield* Effect.die(
+            new Error(
+              'the write returned no error but the object is still absent — read back rather ' +
+                'than trust the status code.',
+            ),
+          );
+        }
+        return after;
+      }),
+
+    destroy: (olds: Props) =>
+      Effect.gen(function* () {
+        const live = yield* spec.fetchLive(olds);
+        if (live === undefined) return;
+        yield* spec.destroy(olds, live);
+      }),
+  };
+};
+
+/**
+ * The four provider handlers for a spec'd Argo CD object, wired once.
+ *
+ * ★ CREDENTIALS ARE PROVIDED HERE, ONCE. `CredentialsFromEnv` resolves `ARGOCD_TOKEN` /
+ *   `ARGOCD_SERVER` on the calling fiber per request (credentials.ts), never captured at load.
+ *
+ * ⚠️ `list` answers empty — Argo CD's list endpoints return every object of that kind on the whole
+ *   instance; adoption stays explicit (a declared resource's own `read`), same reasoning as
+ *   forgejo and discord.
+ */
+export const argocdHandlers = <Props extends object, Live, Attributes extends object, E>(
+  spec: ArgocdSpec<Props, Live, Attributes, E>,
+) => {
+  const ops = argocdOperations(spec);
+  const withCredentials = <A>(effect: Effect.Effect<A, E, ArgocdOpContext>) =>
+    Effect.provide(effect, CredentialsFromEnv);
+  return {
+    list: () => Effect.succeed([]),
+    read: ({ olds }: { olds: Props }) => withCredentials(ops.read(olds)),
+    diff: ({ news, output }: { news: Input<Props>; output: Attributes | undefined }) =>
+      withCredentials(ops.diff(news, output)),
+    reconcile: ({ news }: { news: Props }) => withCredentials(ops.reconcile(news)),
+    delete: ({ olds }: { olds: Props }) => withCredentials(ops.destroy(olds)),
+  };
+};

package/src/cloudflare/r2-bucket-lock.test.ts

@@ -5,15 +5,15 @@
  *
  * ★ THE POINT OF THIS FILE IS THE TAGGED-ERROR PATHS, per the transport swap onto
  *   `@distilled.cloud/cloudflare/r2`: `NoSuchBucket` is matched by Cloudflare's own error code
- *   (10006), never by HTTP status, and only `readLock` treats it as "nothing to adopt" —
- *   `reconcileLock`/`deleteLock` let it die like any other tagged error.
+ *   (10006), never by HTTP status, and only `readLock`/`deleteLock` treat it as "nothing to do" —
+ *   `reconcileLock` still fails on it, but as a typed SDK error, not the `Effect.orDie`
+ *   defect this family used to raise (WI-7, decision 49 "upstream wins", 2026-09-24).
  */
+import * as Retry from '@distilled.cloud/cloudflare/Retry';
 import type { CloudflareOpContext } from '@distilled.cloud/cloudflare/r2';
 import { Unowned } from 'alchemy/AdoptPolicy';
 import { describe, expect, test } from 'bun:test';
-import * as Cause from 'effect/Cause';
 import * as Effect from 'effect/Effect';
-import * as Exit from 'effect/Exit';
 import {
   FAKE_ACCOUNT,
   type FakeR2Lock,
@@ -28,8 +28,14 @@ import { type R2BucketLockProps, deleteLock, readLock, reconcileLock } from './r
 const run = <A, E>(fake: FakeR2Lock, effect: Effect.Effect<A, E, CloudflareOpContext>) =>
   Effect.runPromise(effect.pipe(Effect.provide(fakeR2LockLayer(fake))));
 
-const dies = <A, E>(fake: FakeR2Lock, effect: Effect.Effect<A, E, CloudflareOpContext>) =>
-  Effect.runPromiseExit(effect.pipe(Effect.provide(fakeR2LockLayer(fake))));
+/**
+ * The operation's typed refusal, never a defect — asserts S20/S21 (WI-7). `Retry.none` keeps a
+ * simulated 429 from actually waiting out distilled's real, unbounded-under-test throttling
+ * backoff (`applyRetry`'s `makeDefault` in `@distilled.cloud/core/api.ts`) — the house's own
+ * speed doctrine (S26, `testing-speed-doctrine`) never lets a test wait on a real retry schedule.
+ */
+const refused = <A, E>(fake: FakeR2Lock, effect: Effect.Effect<A, E, CloudflareOpContext>) =>
+  Effect.runPromise(Effect.flip(effect).pipe(Retry.none, Effect.provide(fakeR2LockLayer(fake))));
 
 const rule: R2LockRule = {
   id: 'keep-30d',
@@ -83,11 +89,18 @@ describe('readLock', () => {
   test('a different tagged error at 404 is NOT swallowed as NoSuchBucket', async () => {
     // ⛔ code 7003 is `InvalidRoute`, not `NoSuchBucket` — even at the same 404 status a plain
     //   status check would have treated as "no bucket". `catchTag('NoSuchBucket', …)` leaves it
-    //   alone, and `Effect.orDie` turns it into a defect.
+    //   alone, and it now surfaces as a typed SDK error, never an `Effect.orDie` defect.
     const fake = fakeR2Lock({ onRoute: () => fakeFailure(404, 7003, 'Invalid route') });
-    const exit = await dies(fake, readLock(props(), false));
-    expect(Exit.isFailure(exit)).toBe(true);
-    expect(Exit.isFailure(exit) && Cause.hasDies(exit.cause)).toBe(true);
+    const refusal = await refused(fake, readLock(props(), false));
+    expect(refusal._tag).toBe('InvalidRoute');
+  });
+
+  test('a rate-limited read surfaces as a typed refusal, not a crash', async () => {
+    // ⛔ 429 WITH NO MATCHED CODE maps to distilled's `TooManyRequests` (protocol.ts step 3,
+    //   "Throttling"), one of the `CloudflareOpError` members this resource does not special-case.
+    const fake = fakeR2Lock({ onRoute: () => fakeFailure(429, 0, 'rate limited') });
+    const refusal = await refused(fake, readLock(props(), false));
+    expect(refusal._tag).toBe('TooManyRequests');
   });
 });
 
@@ -108,11 +121,10 @@ describe('reconcileLock', () => {
     expect(fake.locks.get('my-backups')).toEqual([rule]);
   });
 
-  test('NoSuchBucket is NOT caught here: a genuinely missing bucket dies', async () => {
+  test('NoSuchBucket is NOT caught here: a genuinely missing bucket is a typed refusal', async () => {
     const fake = fakeR2Lock();
-    const exit = await dies(fake, reconcileLock(props(), undefined));
-    expect(Exit.isFailure(exit)).toBe(true);
-    expect(Exit.isFailure(exit) && Cause.hasDies(exit.cause)).toBe(true);
+    const refusal = await refused(fake, reconcileLock(props(), undefined));
+    expect(refusal._tag).toBe('NoSuchBucket');
   });
 });
 
@@ -126,14 +138,38 @@ describe('deleteLock', () => {
     expect(fake.locks.has('my-backups')).toBe(false);
   });
 
-  test('NoSuchBucket is NOT caught here either: a genuinely missing bucket dies', async () => {
+  test('deleting when the bucket is already gone succeeds (S11, P10: delete is idempotent)', async () => {
+    // ⛔ THE ONE BEHAVIOUR CHANGE WI-7 MAKES: unlike `reconcileLock`, `deleteLock` now catches
+    //   `NoSuchBucket` into success — a bucket that no longer exists has nothing left to unlock.
     const fake = fakeR2Lock();
     const output = await run(
       fakeR2Lock({ existingBuckets: ['my-backups'] }),
       reconcileLock(props(), undefined),
     );
-    const exit = await dies(fake, deleteLock(output, FAKE_ACCOUNT));
-    expect(Exit.isFailure(exit)).toBe(true);
-    expect(Exit.isFailure(exit) && Cause.hasDies(exit.cause)).toBe(true);
+    await run(fake, deleteLock(output, FAKE_ACCOUNT));
+    expect(writes(fake)).toEqual(['PUT']);
+  });
+
+  test('delete does not swallow InvalidRoute at 404', async () => {
+    const fake = fakeR2Lock({ onRoute: () => fakeFailure(404, 7003, 'Invalid route') });
+    const refusal = await refused(
+      fake,
+      deleteLock(
+        { bucketName: 'my-backups', jurisdiction: 'default', rules: [rule] },
+        FAKE_ACCOUNT,
+      ),
+    );
+    expect(refusal._tag).toBe('InvalidRoute');
+  });
+
+  test('a rate-limited delete surfaces as a typed refusal, not a crash', async () => {
+    const setup = fakeR2Lock({ existingBuckets: ['my-backups'] });
+    const output = await run(setup, reconcileLock(props(), undefined));
+    const limited = fakeR2Lock({
+      existingBuckets: ['my-backups'],
+      onRoute: () => fakeFailure(429, 0, 'rate limited'),
+    });
+    const refusal = await refused(limited, deleteLock(output, FAKE_ACCOUNT));
+    expect(refusal._tag).toBe('TooManyRequests');
   });
 });

package/src/cloudflare/r2-bucket-lock.ts

@@ -103,7 +103,9 @@ export const R2BucketLock: ResourceClass<R2BucketLock> = Resource<R2BucketLock>(
  *   same case the status check used to cover — but by the vendor's own error identity, not by
  *   reading a number off the response. Letting it propagate would make the resource impossible to
  *   plan; swallowing every failure would also hide a 403 from a mis-scoped token, which is the
- *   failure this estate spends the most time on. So: `NoSuchBucket` → absent, everything else dies.
+ *   failure this estate spends the most time on. So: `NoSuchBucket` → absent, everything else
+ *   propagates with its SDK tag. Upstream `Cloudflare/R2/BucketSippy.ts` at beta.79 uses this
+ *   same catch-and-propagate shape; a blanket remap would hide those typed identities (S20/S21).
  *
  * ⛔ AN EMPTY LIVE RULE SET IS "NO LOCK", NOT "A LOCK WITH NOTHING IN IT", so it reads as absent
  *   and the resource CREATES. The API answers `{}` for a bucket that has never been locked and
@@ -117,15 +119,16 @@ export const R2BucketLock: ResourceClass<R2BucketLock> = Resource<R2BucketLock>(
 export const readLock = (
   props: { accountId: string; bucketName: string; jurisdiction?: Jurisdiction },
   written: boolean,
-): Effect.Effect<R2BucketLockAttributes | undefined, never, CloudflareOpContext> =>
+): Effect.Effect<
+  R2BucketLockAttributes | undefined,
+  Exclude<r2.GetBucketLockError, { _tag: 'NoSuchBucket' }>,
+  CloudflareOpContext
+> =>
   Effect.gen(function* () {
     const jurisdiction = jurisdictionOf(props);
     const live = yield* r2
       .getBucketLock({ accountId: props.accountId, bucketName: props.bucketName, jurisdiction })
-      .pipe(
-        Effect.catchTag('NoSuchBucket', () => Effect.succeed(undefined)),
-        Effect.orDie,
-      );
+      .pipe(Effect.catchTag('NoSuchBucket', () => Effect.succeed(undefined)));
     if (live === undefined) return undefined;
     const rules = (live.rules ?? []) as readonly R2LockRule[];
     if (rules.length === 0) return undefined;
@@ -144,23 +147,21 @@ export const readLock = (
  *   persisted (or what `read` just adopted), so the comparison costs nothing either.
  * ⛔ `NoSuchBucket` IS NOT CAUGHT HERE. Unlike `read`, a `reconcile` that hits it means the bucket
  *   this declaration names is genuinely gone — that is a real failure to surface, not a case to
- *   paper over, so it dies like every other tagged error `putBucketLock` can raise.
+ *   paper over, so it propagates like every other typed SDK error `putBucketLock` can raise.
  */
 export const reconcileLock = (
   news: R2BucketLockProps,
   output: R2BucketLockAttributes | undefined,
-): Effect.Effect<R2BucketLockAttributes, never, CloudflareOpContext> =>
+): Effect.Effect<R2BucketLockAttributes, r2.PutBucketLockError, CloudflareOpContext> =>
   Effect.gen(function* () {
     const jurisdiction = jurisdictionOf(news);
     if (output !== undefined && rulesEqual(output.rules, news.rules)) return output;
-    yield* r2
-      .putBucketLock({
-        accountId: news.accountId,
-        bucketName: news.bucketName,
-        jurisdiction,
-        ...toBody(news.rules),
-      })
-      .pipe(Effect.orDie);
+    yield* r2.putBucketLock({
+      accountId: news.accountId,
+      bucketName: news.bucketName,
+      jurisdiction,
+      ...toBody(news.rules),
+    });
     return { bucketName: news.bucketName, jurisdiction, rules: news.rules };
   });
 
@@ -170,11 +171,17 @@ export const reconcileLock = (
  *   rule is configured, so retiring the repository has to start here — and it is behind
  *   `defaultRemovalPolicy: 'retain'` and the estate CLI's refusal of `destroy` precisely because
  *   no ordinary deploy should ever reach it.
+ * ⛔ IDEMPOTENT (S11): a missing bucket has nothing left to unlock. Catch only `NoSuchBucket`;
+ *   every other SDK error propagates, like upstream `R2/BucketSippy.ts` at beta.79.
  */
 export const deleteLock = (
   output: R2BucketLockAttributes,
   accountId: string,
-): Effect.Effect<void, never, CloudflareOpContext> =>
+): Effect.Effect<
+  void,
+  Exclude<r2.PutBucketLockError, { _tag: 'NoSuchBucket' }>,
+  CloudflareOpContext
+> =>
   Effect.gen(function* () {
     yield* r2
       .putBucketLock({
@@ -183,7 +190,7 @@ export const deleteLock = (
         jurisdiction: output.jurisdiction,
         rules: [],
       })
-      .pipe(Effect.orDie);
+      .pipe(Effect.catchTag('NoSuchBucket', () => Effect.void));
   });
 
 export const R2BucketLockProvider = () =>

package/src/grafana/index.ts

@@ -7,10 +7,10 @@
  *   depend on.
  *
  * `Grafana.Datasource`, `Grafana.Folder`, `Grafana.Dashboard`, `Grafana.ContactPoint`,
- * `Grafana.MuteTiming`, `Grafana.MessageTemplate` and `Grafana.AlertRuleGroup` ship here.
- * `Grafana.NotificationPolicy` — the singleton policy tree — is a stacked follow-up PR on the same
- * SDK operations — see docs/grafana.md, docs/grafana-folder-dashboard.md and
- * docs/grafana-alerting.md for what shipped and what is still open.
+ * `Grafana.MuteTiming`, `Grafana.MessageTemplate`, `Grafana.AlertRuleGroup` and
+ * `Grafana.NotificationPolicy` all ship here — see docs/grafana.md, docs/grafana-folder-dashboard.md,
+ * docs/grafana-alerting.md, docs/grafana-alerting-rules.md and
+ * docs/grafana-notification-policy.md for what shipped.
  */
 export {
   type AlertRuleGroupAttributes,
@@ -19,6 +19,13 @@ export {
   GrafanaAlertRuleGroup,
   GrafanaAlertRuleGroupProvider,
 } from './alert-rule-group.ts';
+export {
+  type NotificationPolicyAttributes,
+  type NotificationPolicyProps,
+  type PolicyRoute,
+  GrafanaNotificationPolicy,
+  GrafanaNotificationPolicyProvider,
+} from './notification-policy.ts';
 export {
   type DatasourceAttributes,
   type DatasourceProps,

package/src/grafana/notification-policy-drop-warning.test.ts

@@ -0,0 +1,163 @@
+/**
+ * `warnOnDroppedRoutes` — pure logic, then wired through `diff`/`update` on a fake Grafana. Mirrors
+ * `alert-rule-group-drop-warning.test.ts`: captures `Effect.logWarning` with a `Logger`, the house
+ * pattern `caddy/config-format-warning.test.ts` established.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Logger from 'effect/Logger';
+import { PATH, liveTree, props } from './notification-policy-fixtures.ts';
+import { handlers, spec } from './notification-policy.ts';
+import { warnOnDroppedRoutes } from './notification-policy-drop-warning.ts';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { grafanaOperations } from './resource.ts';
+
+const withWarnings = async <A>(effect: Effect.Effect<A, unknown, never>) => {
+  const warnings: string[] = [];
+  const collect = Logger.make((options) => {
+    if (options.logLevel === 'Warn') warnings.push(String(options.message));
+  });
+  const value = await Effect.runPromise(effect.pipe(Effect.provide(Logger.layer([collect]))));
+  return { value, warnings };
+};
+
+describe('warnOnDroppedRoutes — pure', () => {
+  test('logs nothing when the declared tree already has every live route', async () => {
+    const tree = { receiver: 'default', routes: [{ receiver: 'pagerduty' }] };
+    const { warnings } = await withWarnings(warnOnDroppedRoutes(tree, tree));
+    expect(warnings).toEqual([]);
+  });
+
+  test('names a dropped nested route by receiver and path', async () => {
+    const declared = { receiver: 'default', routes: [{ receiver: 'pagerduty' }] };
+    const live = {
+      receiver: 'default',
+      routes: [{ receiver: 'pagerduty' }, { matchers: ['team=x'], receiver: 'slack' }],
+    };
+    const { warnings } = await withWarnings(warnOnDroppedRoutes(declared, live));
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('slack (root.1)');
+  });
+
+  test('a changed root receiver is never reported as "dropped" — root is replaced, not removed', async () => {
+    const { warnings } = await withWarnings(
+      warnOnDroppedRoutes({ receiver: 'new' }, { receiver: 'old' }),
+    );
+    expect(warnings).toEqual([]);
+  });
+
+  test('the same two routes reordered logs nothing — reordering is not dropping', async () => {
+    // ⛔ THE POINT: `matches()` (subset-match's position-significant array rule) still shows
+    //   `update` for a reorder — this warning stays silent because nothing is actually REMOVED,
+    //   complementing rather than duplicating that signal.
+    const a = { receiver: 'pagerduty' };
+    const b = { receiver: 'slack' };
+    const { warnings } = await withWarnings(
+      warnOnDroppedRoutes(
+        { receiver: 'default', routes: [b, a] },
+        { receiver: 'default', routes: [a, b] },
+      ),
+    );
+    expect(warnings).toEqual([]);
+  });
+
+  test('a duplicate route added live warns — the multiset fix, not the original Set collision', async () => {
+    // ⛔ THE REGRESSION AN ADVERSARIAL REVIEW OF THIS PR FOUND: the first version's `Set`-based
+    //   identity collided this duplicate with the already-declared one and warned nothing, even
+    //   though the PUT drops it. `severity=warning` -> `slack` is declared once; live has it TWICE.
+    const declared = {
+      receiver: 'default',
+      routes: [
+        { matchers: ['severity=warning'], receiver: 'slack' },
+        { matchers: ['severity=critical'], receiver: 'pagerduty' },
+      ],
+    };
+    const live = {
+      receiver: 'default',
+      routes: [
+        { matchers: ['severity=warning'], receiver: 'slack' },
+        { matchers: ['severity=critical'], receiver: 'pagerduty' },
+        { matchers: ['severity=warning'], receiver: 'slack' },
+      ],
+    };
+    const { warnings } = await withWarnings(warnOnDroppedRoutes(declared, live));
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('REMOVES 1 route');
+    expect(warnings[0]).toContain('slack (root.2)');
+  });
+
+  test('an identical route under a DIFFERENT (undeclared) parent still warns — distinct lineage', async () => {
+    const declared = {
+      receiver: 'default',
+      routes: [{ receiver: 'p1', routes: [{ receiver: 'slack' }] }],
+    };
+    const live = {
+      receiver: 'default',
+      routes: [
+        { receiver: 'p1', routes: [{ receiver: 'slack' }] },
+        { receiver: 'p2', routes: [{ receiver: 'slack' }] },
+      ],
+    };
+    const { warnings } = await withWarnings(warnOnDroppedRoutes(declared, live));
+    expect(warnings).toHaveLength(1);
+    // ⛔ NOT root.0.0 (that one IS declared, under p1) — the dropped one is the p2 lineage's.
+    expect(warnings[0]).toContain('slack (root.1.0)');
+  });
+
+  test('two declared duplicates vs two live duplicates warns nothing — counts match', async () => {
+    const pair = {
+      receiver: 'default',
+      routes: [{ receiver: 'slack' }, { receiver: 'slack' }],
+    };
+    const { warnings } = await withWarnings(warnOnDroppedRoutes(pair, pair));
+    expect(warnings).toEqual([]);
+  });
+});
+
+describe('wired into diff and update', () => {
+  test('diff logs the dropped-route warning before anything is written', async () => {
+    const extra = { matchers: ['team=x'], receiver: 'slack' };
+    const withExtra = { ...liveTree, routes: [...liveTree.routes, extra] };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH
+        ? Response.json(withExtra)
+        : fakeFailure(500, 'diff should not write'),
+    );
+    const { warnings, value } = await withWarnings(
+      handlers
+        .diff({ news: props, output: { provenance: 'api', route: props.route } })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))) as Effect.Effect<
+        unknown,
+        unknown,
+        never
+      >,
+    );
+    // ⚠️ NOT 'noop': subset-match's array rule requires EXACT length, so live carrying one MORE
+    //   route than declared already disagrees on its own — the warning and the mismatch are the
+    //   same signal here, not independent (see the file header on `matches` vs this warning).
+    expect(value).toEqual({ action: 'update' });
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('slack');
+  });
+
+  test('update logs the same warning right before the PUT that would drop the route', async () => {
+    const extra = { matchers: ['team=x'], receiver: 'slack' };
+    const withExtra = { ...liveTree, routes: [...liveTree.routes, extra] };
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === PATH) return Response.json(withExtra);
+      if (method === 'PUT' && url.pathname === PATH) return Response.json(withExtra);
+      return fakeFailure(500, 'unexpected request');
+    });
+    const { warnings } = await withWarnings(
+      grafanaOperations(spec)
+        .reconcile({ route: { ...props.route, receiver: 'changed' } })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))) as Effect.Effect<
+        unknown,
+        unknown,
+        never
+      >,
+    );
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('slack');
+  });
+});

package/src/grafana/notification-policy-drop-warning.ts

@@ -0,0 +1,60 @@
+/**
+ * The warning `Grafana.NotificationPolicy` logs when a whole-tree `PUT` would silently drop a live
+ * sub-route the declaration doesn't account for — same shape as `alert-rule-group-drop-warning.ts`
+ * (kit PR 254's own fix, after an adversarial review found the identical risk for rule groups):
+ * `PUT /v1/provisioning/policies` REPLACES the entire tree, so a nested route someone added
+ * out-of-band is removed with no error and no distinct `Diff` action to report it under.
+ *
+ * ★ `Effect.logWarning`, NEVER A REFUSAL — same reasoning as `alert-rule-group-drop-warning.ts`'s
+ *   own header, and further upstream `proxmox/unreadable-read.ts`'s `unreadableWarning`. A
+ *   whole-tree write dropping an out-of-band route is EXPECTED for a resource whose whole point is
+ *   to own the tree — only a silent one is worth surfacing loudly.
+ *
+ * ⛔ MULTISET COMPARISON, NOT SET MEMBERSHIP — fixed after an adversarial review of this PR found
+ *   the first version's `Set`-based check collided ACROSS THE WHOLE TREE: any two nodes anywhere
+ *   with identical own-fields shared one `Set` entry, so a duplicate route added out-of-band
+ *   (e.g. a second `severity=warning -> slack` alongside an already-declared one) matched the
+ *   existing entry and went unwarned even though the PUT would still drop it — worse than the
+ *   documented "siblings only" limitation the original comment claimed. Every key from
+ *   `FlatRoute.key` (ancestry-scoped — see that field's own doc) is now counted per side, and a
+ *   `key` is only "dropped" for the amount its LIVE count exceeds its DECLARED count — N identical
+ *   live occurrences under the same parent are dropped only past however many the declaration
+ *   itself repeats, never all of them at once just because one is declared.
+ */
+import * as Effect from 'effect/Effect';
+import { type PolicyRoute, flattenRoutes, normalizeRoute } from './notification-policy-model.ts';
+
+const countByKey = (routes: ReadonlyArray<{ readonly key: string }>): Map<string, number> => {
+  const counts = new Map<string, number>();
+  for (const route of routes) counts.set(route.key, (counts.get(route.key) ?? 0) + 1);
+  return counts;
+};
+
+export const warnOnDroppedRoutes = (
+  declared: PolicyRoute,
+  live: PolicyRoute,
+): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    // Root is never "dropped" — it is always replaced, not removed (the file header's own note).
+    const declaredNodes = flattenRoutes(normalizeRoute(declared)).filter((r) => r.path !== 'root');
+    const liveNodes = flattenRoutes(normalizeRoute(live)).filter((r) => r.path !== 'root');
+    const declaredCounts = countByKey(declaredNodes);
+    const liveCounts = countByKey(liveNodes);
+
+    const dropped: Array<{ readonly path: string; readonly receiver: string }> = [];
+    for (const [key, liveCount] of liveCounts) {
+      const extra = liveCount - (declaredCounts.get(key) ?? 0);
+      if (extra <= 0) continue;
+      // Report the LAST `extra` live occurrences of this key, by path — an arbitrary but
+      // deterministic choice among indistinguishable duplicates (multiset identity, no position).
+      const occurrences = liveNodes.filter((route) => route.key === key);
+      dropped.push(...occurrences.slice(-extra));
+    }
+    if (dropped.length === 0) return;
+    const names = dropped.map((route) => `${route.receiver} (${route.path})`).join(', ');
+    yield* Effect.logWarning(
+      `Grafana.NotificationPolicy: this update REMOVES ${dropped.length} route(s)/matcher(s) not ` +
+        `in the declaration: ${names}. Whole-tree replacement is by design — add them to the ` +
+        `declared tree to keep them.`,
+    );
+  });

package/src/grafana/notification-policy-fixtures.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared fixtures for the `notification-policy*.test.ts` files — split to keep each file under
+ * the house's 250-line cap. Deliberately NOT named `*.test.ts` — see `contact-point-fixtures.ts`'s
+ * own header for why.
+ */
+export const PATH = '/api/v1/provisioning/policies';
+
+export const liveTree = {
+  group_by: ['alertname'],
+  provenance: 'api',
+  receiver: 'default-receiver',
+  routes: [
+    { matchers: ['severity=critical'], receiver: 'pagerduty' },
+    { matchers: ['severity=warning'], receiver: 'slack' },
+  ],
+};
+
+export const declaredRoute = {
+  group_by: ['alertname'],
+  receiver: 'default-receiver',
+  routes: [
+    { matchers: ['severity=critical'], receiver: 'pagerduty' },
+    { matchers: ['severity=warning'], receiver: 'slack' },
+  ],
+};
+
+export const props = { route: declaredRoute };