@homeflare/alchemy 0.35.0 → 0.36.0

package/docs/grafana-notification-policy.md

@@ -0,0 +1,127 @@
+# `Grafana.NotificationPolicy` — `@homeflare/alchemy/grafana`
+
+Third and last of the stacked PRs bringing Grafana alerting provisioning under Alchemy
+([grafana-alerting.md](./grafana-alerting.md): `Grafana.ContactPoint`/`Grafana.MuteTiming`/
+`Grafana.MessageTemplate`; [grafana-alerting-rules.md](./grafana-alerting-rules.md):
+`Grafana.AlertRuleGroup`). Branched fresh off `main` after that PR merged. No live call was made
+writing this PR.
+
+## A singleton — adopt and update only
+
+`GET`/`PUT /v1/provisioning/policies` always address the one tree an instance has; there is no path
+parameter. MEASURED: `RouteGetPolicyTreeError` is `Forbidden | GrafanaOpError` — no `NotFound` case
+at all, so `fetchLive` never returns `undefined`. `reconcile`'s `before === undefined` branch
+(`resource.ts`) is therefore dead code for this resource: there is no create in the sense every
+other resource in this family has, and `spec.create` exists only because `GrafanaSpec.create` is a
+required field on the shared type — implemented as the same `PUT` `update` sends, defensively,
+never actually reached.
+
+## Two gates before `routeResetPolicyTree` ever runs
+
+`destroy` never calls `routeResetPolicyTree` unless `allowReset: true` is explicitly declared — a
+gate independent of Alchemy's own removal policy:
+
+1. **`defaultRemovalPolicy: 'retain'`** — the same convention every multi-object-cascade resource
+   in this family uses (`Grafana.Folder`, `Grafana.AlertRuleGroup`, every `Bao.*`). Alchemy's own
+   engine never calls this resource's `delete` handler at all unless a stack opts in with
+   `.pipe(RemovalPolicy.destroy())`.
+2. **`allowReset` (a prop, not a stack-level policy)** — even a stack that HAS opted into destroy
+   at the Alchemy level still needs this resource's own explicit `allowReset: true` before
+   `destroy` will actually reset. Without it, `destroy` logs a warning and returns — retained.
+
+Two gates, not one, because `routeResetPolicyTree` is uniquely destructive among everything this
+family calls: it wipes every declared route, receiver reference and matcher back to Grafana's own
+bare default, for the WHOLE instance, not one object. A test
+(`notification-policy-refusals.test.ts`) proves `destroy` sends no `DELETE` without `allowReset`,
+and a foreign-provenance tree still refuses `destroy` even WITH `allowReset: true`.
+
+## The tree is opaque `Record<string, unknown>`
+
+Same reasoning as `mute-timing.ts`'s `timeIntervals`: Grafana's `Matchers`/`ObjectMatchers`/
+`MatchRegexps` (matcher expression shapes) are complex nested union/array types this family does
+not attempt to model field-by-field. This family's own measured passthrough behavior
+(`mute-timing.ts`'s file header) means an opaque pass-through round-trips correctly regardless.
+
+## Route order is significant
+
+Same as `Grafana.AlertRuleGroup`'s rules: `subset-match.ts`'s array comparison is
+position-significant, and Alertmanager itself routes an alert to the FIRST matching route in array
+order — reordering routes is a genuine routing change, proven by a test that declares the same two
+routes reversed and asserts a mismatch.
+
+## Foreign-provenance refusal
+
+Unchanged from kit PR 250/254, including the missing-means-foreign fix: `Route.provenance` is
+optional on the wire, and `undefined` is never folded into `""`. `create` is never at risk — it is
+unreachable (above).
+
+## Grafana-injected defaults — tolerated the `declaredContentMatches` way
+
+`matches()` runs the (`provenance`-stripped) declared and live trees through `subset-match.ts`'s
+tolerant-subset comparison — the same mechanism `Grafana.Dashboard`'s panel-`datasource`
+auto-decoration and `Grafana.ContactPoint`'s settings defaults already rely on: a live tree may
+carry additional fields, at any depth, the declaration never mentioned (a default
+`group_wait`/`group_interval`/`repeat_interval`/`group_by: []` Grafana injects when the declaration
+omits them is the plausible case) without failing the match. ⚠️ Not measured against a live
+instance — no live policy tree exists in this house to read — the documented, conservative default
+every unmeasured value shape in this family takes.
+
+## Dropped-route warning — accepted, never silent
+
+Same fix kit PR 254 made for `Grafana.AlertRuleGroup`, applied here: a whole-tree `PUT` REPLACES
+every route, so a nested route added out-of-band is removed with no error and no distinct `Diff`
+action to report it under. `notification-policy-drop-warning.ts`'s `warnOnDroppedRoutes` logs every
+dropped route by receiver and dotted-index path, called from both a local reimplementation of
+`diff` and from `update` itself — mirrors `alert-rule-group-drop-warning.ts` exactly, including
+being a LOCAL reimplementation of `resource.ts`'s generic `diff` rather than a wrap of it (no seam
+in the generic version for this side effect without fetching live twice).
+
+⚠️ **Identity is structural, not a stable key** — Grafana's policy routes have no id/uid.
+`FlatRoute.key` (`notification-policy-model.ts`) is the chain of ancestor own-fields from the root
+down to a node, `\0`-joined: two nodes are "the same" only under the identical lineage of parents,
+which makes an identical route under a DIFFERENT parent correctly distinct while staying
+order-insensitive among siblings (a shared parent contributes the same key to every child
+regardless of index) — reordering the same routes logs nothing, only genuine removal does.
+
+⛔ **Fixed after an adversarial review of this PR: the first version's identity collided across the
+WHOLE TREE, not just among siblings.** A plain `Set` of every node's own-fields JSON meant a
+duplicate route added anywhere (e.g. a second `severity=warning -> slack` alongside an
+already-declared one) matched the existing `Set` entry and went unwarned, even though the `PUT`
+still drops it — worse than the "siblings only" limitation the original comment claimed. Every key
+is now counted as a MULTISET (declared count vs. live count) rather than checked for membership: a
+key is "dropped" only for the amount its live count exceeds its declared count, so N identical live
+occurrences under the same parent are dropped only past however many the declaration itself
+repeats — proven by four tests: a duplicate added live warns; a plain sibling reorder doesn't; an
+identical route under a different, undeclared parent still warns (distinct lineage); and two
+declared duplicates against two live duplicates warns nothing (counts match).
+
+## Example
+
+```ts
+import { GrafanaNotificationPolicy, grafanaProviders } from '@homeflare/alchemy/grafana';
+
+export class Policy extends GrafanaNotificationPolicy('estate-policy', {
+  route: {
+    receiver: 'default-receiver',
+    group_by: ['alertname'],
+    routes: [
+      { receiver: 'pagerduty', matchers: ['severity=critical'] },
+      { receiver: 'slack', matchers: ['severity=warning'] },
+    ],
+  },
+}) {}
+```
+
+## Tests
+
+`notification-policy.test.ts` (fetchLive/reconcile/order), `notification-policy-model.test.ts`
+(pure `normalizeRoute`/`flattenRoutes`), `notification-policy-refusals.test.ts` (provenance +
+reset-gate) and `notification-policy-drop-warning.test.ts` — split four ways to stay under the
+house's 250-line file cap, sharing fixtures from `notification-policy-fixtures.ts`. Prove: a GET
+never carries a body; reconcile never sends a create-shaped write; a foreign-provenance tree
+(explicit `"file"` or MISSING) refuses update while an explicit `""` is writable; `destroy` never
+resets without `allowReset: true`, and still refuses a foreign tree even with it; reordering routes
+shows `update`; a live route the declaration doesn't mention is named in a logged warning from both
+`diff` and `update`, while a plain reorder logs nothing; and — the multiset fix — a duplicate route
+added live warns while an identical declared/live duplicate pair doesn't, and an identical route
+under a different, undeclared parent is still correctly reported as dropped.

package/docs/grafana.md

@@ -122,15 +122,19 @@ export class TeslaMateDatasource extends GrafanaDatasource('teslamate-datasource
 // …then provide `grafanaProviders({ baseUrl, tokenEnv })` alongside the stack's other providers.
 ```
 
+## Family status
+
+Every alerting-provisioning object this family set out to cover now ships:
+
+- **`Grafana.Folder` and `Grafana.Dashboard`** — see
+  [grafana-folder-dashboard.md](./grafana-folder-dashboard.md).
+- **`Grafana.ContactPoint`, `Grafana.MuteTiming` and `Grafana.MessageTemplate`** — see
+  [grafana-alerting.md](./grafana-alerting.md).
+- **`Grafana.AlertRuleGroup`** — see [grafana-alerting-rules.md](./grafana-alerting-rules.md).
+- **`Grafana.NotificationPolicy`** — the singleton policy tree, last on purpose (it references the
+  others by name) — see [grafana-notification-policy.md](./grafana-notification-policy.md).
+
 ## Not covered
 
-- **`Grafana.Folder` and `Grafana.Dashboard` ship** — see
-  [grafana-folder-dashboard.md](./grafana-folder-dashboard.md), not repeated here.
-- **`Grafana.ContactPoint`, `Grafana.MuteTiming` and `Grafana.MessageTemplate` ship** — see
-  [grafana-alerting.md](./grafana-alerting.md), not repeated here.
-- **`Grafana.AlertRuleGroup` ships** — see [grafana-alerting-rules.md](./grafana-alerting-rules.md),
-  not repeated here.
-- **`Grafana.NotificationPolicy`** — the last stacked follow-up PR, the singleton policy tree, on
-  the same operations; not blocked on anything.
 - **`read` never answers `Unowned`** — the same open gap forgejo's and netbox's own families
   still carry (see upstream-conformance.md); a maintainer decision on the ownership-check shape.

package/docs/upstream-conformance.md

@@ -289,7 +289,7 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
       timings or templates configured either (consistent with the alerting-provisioning gap having
       been real, not merely unexploited).
 
-    ✅ **`Grafana.AlertRuleGroup` shipped** (this PR, second of three, branched fresh off `main`
+    ✅ **`Grafana.AlertRuleGroup` shipped** (kit PR 254, second of three, branched fresh off `main`
     after PR 250 merged): group, not per-rule, is the unit — `PUT .../rule-groups/{Group}` owns
     evaluation `interval` and the full ordered `rules[]` together, which per-rule operations
     cannot express (no `interval` field, no reordering). Rule order is significant, proven by a
@@ -297,11 +297,25 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
     the group type itself carries none) reuses `alerting-provenance.ts` unchanged, including the
     missing-means-foreign fix from PR 250's review. A declared group whose folder does not exist
     refuses as a typed `BadRequest` (`RoutePutAlertRuleGroupError` has no `NotFound` case) rather
-    than being auto-created — this resource never calls `Grafana.Folder`'s create path. Full
-    detail: [grafana-alerting-rules.md](./grafana-alerting-rules.md).
+    than being auto-created — this resource never calls `Grafana.Folder`'s create path. A whole-group
+    write silently dropping a live rule not in the declaration (found by that PR's own adversarial
+    review) is now warned about loudly rather than silent, never a refusal. Full detail:
+    [grafana-alerting-rules.md](./grafana-alerting-rules.md).
 
-    **Still open, not this PR's scope:** `Grafana.NotificationPolicy` — the last stacked PR, the
-    singleton policy tree, no longer blocked on the SDK.
+    ✅ **`Grafana.NotificationPolicy` shipped** (this PR, third and last of the stacked PRs,
+    branched fresh off `main` after PR 254 merged): a SINGLETON — `fetchLive` never returns
+    `undefined` (`RouteGetPolicyTreeError` has no `NotFound` case), so this resource has no create
+    or delete in the sense every sibling resource does, only adopt-and-update. `destroy` never
+    calls `routeResetPolicyTree` without an explicit `allowReset: true` prop, a gate independent of
+    (and in addition to) `defaultRemovalPolicy: 'retain'` — two gates, since resetting wipes the
+    WHOLE instance's routing back to Grafana's bare default, not one object. The tree is opaque
+    `Record<string, unknown>` (same reasoning as `mute-timing.ts`'s `timeIntervals` — Grafana's
+    matcher-expression types are complex unions this family does not hand-model), compared via
+    `subset-match.ts` for Grafana-injected-default tolerance, with route order significant. The
+    same dropped-item warning kit PR 254 introduced for rule groups is mirrored here for dropped
+    routes. Full detail: [grafana-notification-policy.md](./grafana-notification-policy.md).
+
+    This completes the alerting-provisioning family this project set out to cover.
     - ⛔ **Same open gaps as `forgejo/*` and `netbox/*` above:** `read` never answers `Unowned`
       (H1), and credentials come from an explicit env var NAME at call time rather than an
       `alchemy/Auth` provider (S24) — here the house's own `grafanaCredentials(target)`, not the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.35.0",
+  "version": "0.36.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",

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 };

package/src/grafana/notification-policy-model.test.ts

@@ -0,0 +1,104 @@
+/**
+ * `normalizeRoute`/`flattenRoutes` in isolation — no SDK, no fake, no Effect. Mirrors
+ * `alert-rule-group-model.test.ts`. Proves `provenance` is stripped recursively, that
+ * `flattenRoutes` walks the tree depth-first with dotted-index paths, and — the fix an adversarial
+ * review of this PR made necessary — that its `key` is ancestry-scoped: shared by siblings with
+ * identical own-fields (so a multiset count, not set membership, is what distinguishes them),
+ * distinct across different parents, and unaffected by sibling reordering.
+ */
+import { describe, expect, test } from 'bun:test';
+import { flattenRoutes, normalizeRoute } from './notification-policy-model.ts';
+
+describe('normalizeRoute', () => {
+  test('strips provenance at the root', () => {
+    expect(normalizeRoute({ provenance: 'api', receiver: 'default' })).toEqual({
+      receiver: 'default',
+    });
+  });
+
+  test('strips provenance recursively, at every nested route', () => {
+    const tree = {
+      provenance: 'api',
+      receiver: 'default',
+      routes: [
+        {
+          provenance: 'api',
+          receiver: 'pagerduty',
+          routes: [{ provenance: 'api', receiver: 'slack' }],
+        },
+      ],
+    };
+    expect(normalizeRoute(tree)).toEqual({
+      receiver: 'default',
+      routes: [{ receiver: 'pagerduty', routes: [{ receiver: 'slack' }] }],
+    });
+  });
+
+  test('a declared tree and a live tree that only disagree on provenance normalize equal', () => {
+    const declared = { receiver: 'default', routes: [{ receiver: 'pagerduty' }] };
+    const live = {
+      provenance: 'api',
+      receiver: 'default',
+      routes: [{ provenance: 'api', receiver: 'pagerduty' }],
+    };
+    expect(normalizeRoute(declared)).toEqual(normalizeRoute(live));
+  });
+
+  test('leaves a real content change genuinely different', () => {
+    expect(normalizeRoute({ receiver: 'default' })).not.toEqual(
+      normalizeRoute({ receiver: 'other' }),
+    );
+  });
+});
+
+describe('flattenRoutes', () => {
+  test('walks the tree depth-first with dotted-index paths, root included', () => {
+    const tree = {
+      receiver: 'default',
+      routes: [{ receiver: 'pagerduty' }, { receiver: 'slack', routes: [{ receiver: 'nested' }] }],
+    };
+    const flat = flattenRoutes(tree);
+    expect(flat.map((r) => r.path)).toEqual(['root', 'root.0', 'root.1', 'root.1.0']);
+    expect(flat.map((r) => r.receiver)).toEqual(['default', 'pagerduty', 'slack', 'nested']);
+  });
+
+  test("a route with no receiver of its own reports '(inherited)'", () => {
+    expect(flattenRoutes({ matchers: ['x'] })[0]?.receiver).toBe('(inherited)');
+  });
+
+  test("each entry's key excludes its own routes children — they are separate entries", () => {
+    const tree = { receiver: 'default', routes: [{ receiver: 'child' }] };
+    const [root] = flattenRoutes(tree);
+    expect(root?.key).not.toContain('child');
+  });
+
+  test('two siblings with identical own-fields under the SAME parent share one key', () => {
+    const tree = { receiver: 'default', routes: [{ receiver: 'slack' }, { receiver: 'slack' }] };
+    const [, first, second] = flattenRoutes(tree);
+    expect(first?.key).toBe(second?.key);
+    expect(first?.path).not.toBe(second?.path);
+  });
+
+  test('an identical route under a DIFFERENT parent has a different key', () => {
+    const tree = {
+      receiver: 'default',
+      routes: [
+        { receiver: 'p1', routes: [{ receiver: 'slack' }] },
+        { receiver: 'p2', routes: [{ receiver: 'slack' }] },
+      ],
+    };
+    const flat = flattenRoutes(tree);
+    const underP1 = flat.find((r) => r.path === 'root.0.0');
+    const underP2 = flat.find((r) => r.path === 'root.1.0');
+    expect(underP1?.key).not.toBe(underP2?.key);
+  });
+
+  test('reordering siblings changes their path but not their key', () => {
+    const a = { receiver: 'pagerduty' };
+    const b = { receiver: 'slack' };
+    const forward = flattenRoutes({ receiver: 'default', routes: [a, b] });
+    const reversed = flattenRoutes({ receiver: 'default', routes: [b, a] });
+    const keysOf = (flat: typeof forward) => flat.map((r) => r.key).sort();
+    expect(keysOf(forward)).toEqual(keysOf(reversed));
+  });
+});