@homeflare/alchemy 0.34.0 → 0.36.0

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

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

@@ -0,0 +1,100 @@
+/**
+ * Pure functions over the notification policy tree — no SDK call, no Effect. Split out of
+ * `notification-policy.ts` the same way `dashboard-model.ts`/`alert-rule-group-model.ts` are split
+ * out of their resources.
+ *
+ * ★ THE TREE IS OPAQUE `Record<string, unknown>`, NOT THE SDK's OWN `Route` TYPE — 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. `routePutPolicyTree`'s request body encodes/decodes any key
+ *   verbatim regardless (the same unmodeled-key passthrough `mute-timing.ts`'s file header
+ *   documents for this SDK generally), so an opaque pass-through both round-trips correctly and
+ *   stays usable for every matcher/route shape Grafana accepts, not just the ones this file would
+ *   otherwise hand-model.
+ */
+export type PolicyRoute = Record<string, unknown>;
+
+/** Grafana-managed, never declared content. MEASURED against `Route` (services/grafana.ts):
+ *  `provenance` is the only field on this type that is unambiguously read-only (every other field
+ *  — `receiver`, `group_by`, `matchers`, `routes`, … — is exactly what a declaration sets). An
+ *  object this family just wrote reads back with `provenance: "api"`, which the declaration never
+ *  sets, so comparing it would show a false `update` forever — the same reasoning
+ *  `alert-rule-group-model.ts`'s own `RULE_VOLATILE_FIELDS` note gives for a rule's `provenance`.
+ *  Stripped RECURSIVELY: `Route.routes` is `Array<Route>`, so a nested route could in principle
+ *  carry its own `provenance` too — not measured live (no live policy tree in this house to read),
+ *  but stripping it everywhere is the conservative reading, the same one `provisioned.ts`'s
+ *  `managedBy` note takes for an unmeasured value shape. */
+const ROUTE_VOLATILE_FIELDS = ['provenance'] as const;
+
+export const normalizeRoute = (route: PolicyRoute): PolicyRoute => {
+  const out: PolicyRoute = {};
+  for (const [key, value] of Object.entries(route)) {
+    if ((ROUTE_VOLATILE_FIELDS as readonly string[]).includes(key)) continue;
+    if (key === 'routes' && Array.isArray(value)) {
+      out.routes = value.map((child) => normalizeRoute(child as PolicyRoute));
+      continue;
+    }
+    out[key] = value;
+  }
+  return out;
+};
+
+export interface FlatRoute {
+  /** Dotted child-index path from the root, e.g. `root.0.1` — WHERE this occurrence sits, for the
+   *  warning message only; never part of `key`. */
+  readonly path: string;
+  readonly receiver: string;
+  /**
+   * Identity for the dropped-route warning — MEASURED FIX (an adversarial review of this PR found
+   * the first version's identity, plain per-node JSON in a `Set`, collided across the WHOLE TREE:
+   * a duplicate route added anywhere, not just as a live-only sibling, silently matched an
+   * unrelated declared node with the same fields and the drop went unwarned). `key` is now the
+   * chain of ancestor own-fields from the root down to this node (this node's own fields included,
+   * `routes` children excluded at every level, `\0`-joined — a byte no route's own JSON can
+   * contain): two nodes are "the same" only if they sit under the identical lineage of ancestors,
+   * which makes an identical route under a DIFFERENT parent correctly distinct, while still being
+   * ORDER-INSENSITIVE among siblings (a shared parent contributes the same ancestor key to every
+   * child regardless of index) — a plain reorder is never reported as a drop.
+   * `notification-policy-drop-warning.ts` counts occurrences of each `key` as a MULTISET (declared
+   * count vs. live count), not set membership, so N live duplicates of the same node under the
+   * same parent are only "dropped" past however many the declaration itself repeats.
+   */
+  readonly key: string;
+}
+
+const ownFieldsJson = (route: PolicyRoute): string => {
+  const { routes: _routes, ...ownFields } = route;
+  return JSON.stringify(ownFields);
+};
+
+/**
+ * Depth-first flatten of a (already-normalized) route tree, `root` itself included at `path:
+ * 'root'` and `key` equal to its own fields alone (no ancestor to chain from). Used only by
+ * `notification-policy-drop-warning.ts`'s best-effort "what did this write remove" detection —
+ * `matches()` in `notification-policy.ts` never uses this, only `declaredContentMatches` on the
+ * tree as a whole, so nothing about drift DETECTION depends on it.
+ *
+ * ⚠️ STILL A BEST-EFFORT KEY, NOT A STABLE ONE — Grafana's policy routes have no id/uid the way
+ *  every other object in this family does; `key` is a measured, deliberate improvement over plain
+ *  per-node identity (see `FlatRoute.key`'s own doc), not a claim of a real Grafana-side key. A
+ *  false negative here (missing a genuine drop) never hides real drift from `matches()`, which
+ *  compares the whole tree structurally regardless of this file.
+ */
+export const flattenRoutes = (
+  route: PolicyRoute,
+  path = 'root',
+  ancestorKey = '',
+): ReadonlyArray<FlatRoute> => {
+  const children = Array.isArray(route.routes) ? (route.routes as PolicyRoute[]) : [];
+  const ownJson = ownFieldsJson(route);
+  const key = ancestorKey === '' ? ownJson : `${ancestorKey}\0${ownJson}`;
+  const self: FlatRoute = {
+    key,
+    path,
+    receiver: typeof route.receiver === 'string' ? route.receiver : '(inherited)',
+  };
+  return [
+    self,
+    ...children.flatMap((child, index) => flattenRoutes(child, `${path}.${index}`, key)),
+  ];
+};

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

@@ -0,0 +1,119 @@
+/**
+ * `Grafana.NotificationPolicy`'s two refusal/gate mechanisms: the foreign-provenance refusal on
+ * `update` (explicit foreign, missing, and explicit-none-is-writable — the same fail-closed rule
+ * kit PR 250's adversarial review established) and the `allowReset` gate on `destroy` (never calls
+ * `routeResetPolicyTree` without it, regardless of Alchemy's own removal policy). Split out of
+ * `notification-policy.test.ts` to keep each file under the house's 250-line cap.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { GrafanaProvisionedObjectError } from './alerting-provenance.ts';
+import { PATH, liveTree, props } from './notification-policy-fixtures.ts';
+import { spec } from './notification-policy.ts';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { grafanaOperations } from './resource.ts';
+
+describe('foreign provenance refuses update', () => {
+  test('a file-provisioned tree refuses update and sends no PUT', async () => {
+    const fileProvisioned = { ...liveTree, provenance: 'file' };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH
+        ? Response.json(fileProvisioned)
+        : fakeFailure(500, 'no write should be attempted'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .reconcile({ route: { ...props.route, receiver: 'other' } })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaProvisionedObjectError);
+    expect(failure.message).toContain('file');
+  });
+
+  test('a response with no provenance field at all refuses update', async () => {
+    const noProvenance: Record<string, unknown> = { ...liveTree };
+    delete noProvenance.provenance;
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH
+        ? Response.json(noProvenance)
+        : fakeFailure(500, 'no write should be attempted'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .reconcile({ route: { ...props.route, receiver: 'other' } })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaProvisionedObjectError);
+    expect(failure.message).toContain('did not report a provenance');
+  });
+
+  test('an EXPLICIT empty-string provenance (ProvenanceNone) is writable', async () => {
+    const explicitlyNone = { ...liveTree, provenance: '' };
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === PATH) return Response.json(explicitlyNone);
+      if (method === 'PUT' && url.pathname === PATH) return Response.json(explicitlyNone);
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile({ route: { ...props.route, receiver: 'other' } })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen.some((s) => s.method === 'PUT')).toBe(true);
+  });
+});
+
+describe('destroy never resets without allowReset', () => {
+  test('destroy without allowReset sends no DELETE — retained, not reset', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH
+        ? Response.json(liveTree)
+        : fakeFailure(500, 'no DELETE should be attempted'),
+    );
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .destroy(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen).toEqual([{ method: 'GET', path: PATH }]);
+  });
+
+  test('destroy with allowReset: true calls routeResetPolicyTree', async () => {
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === PATH) return Response.json(liveTree);
+      if (method === 'DELETE' && url.pathname === PATH) return Response.json({});
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .destroy({ ...props, allowReset: true })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen).toEqual([
+      { method: 'GET', path: PATH },
+      { method: 'DELETE', path: PATH },
+    ]);
+  });
+
+  test('a foreign-provenance tree refuses destroy even with allowReset: true', async () => {
+    const fileProvisioned = { ...liveTree, provenance: 'file' };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH
+        ? Response.json(fileProvisioned)
+        : fakeFailure(500, 'no DELETE should be attempted'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .destroy({ ...props, allowReset: true })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaProvisionedObjectError);
+    expect(fake.seen).toEqual([{ method: 'GET', path: PATH }]);
+  });
+});

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

@@ -0,0 +1,86 @@
+/**
+ * `Grafana.NotificationPolicy` against a fake Grafana — the singleton read (never `undefined`),
+ * reconcile's adopt-and-update-only posture, and route-order significance. Provenance/reset-gate
+ * tests: `notification-policy-refusals.test.ts`. Drop-warning tests:
+ * `notification-policy-drop-warning.test.ts` — split to keep each file under the house's
+ * 250-line cap. Mirrors `alert-rule-group.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { PATH, declaredRoute, liveTree, props } from './notification-policy-fixtures.ts';
+import { spec } from './notification-policy.ts';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { grafanaOperations } from './resource.ts';
+
+describe('spec.fetchLive', () => {
+  test('a live tree decodes and normalizes into typed attributes', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH ? Response.json(liveTree) : fakeFailure(404, 'x'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(live !== undefined && spec.attributes(live, props)).toEqual({
+      provenance: 'api',
+      route: declaredRoute,
+    });
+    expect(fake.bodies[0]).toBeUndefined();
+  });
+
+  test('a 403 propagates — never folded to absent, and there is nothing TO fold to (no NotFound case)', async () => {
+    const fake = fakeGrafana(() => fakeFailure(403, 'forbidden'));
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('Forbidden');
+  });
+});
+
+describe('reconcile — adopt-and-update-only, never create', () => {
+  test('declaring exactly what is live is a noop: no write is ever sent', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH
+        ? Response.json(liveTree)
+        : fakeFailure(500, 'reconcile should not write when nothing changed'),
+    );
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('a content change PUTs the declared tree, never a create call', async () => {
+    const changed = { ...declaredRoute, receiver: 'other-receiver' };
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === PATH) return Response.json(liveTree);
+      if (method === 'PUT' && url.pathname === PATH) {
+        return Response.json({ ...liveTree, receiver: 'other-receiver' });
+      }
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile({ route: changed })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    const put = fake.seen.findIndex((s) => s.method === 'PUT');
+    expect(put).toBeGreaterThanOrEqual(0);
+    expect(fake.bodies[put]).toMatchObject({ receiver: 'other-receiver' });
+  });
+});
+
+describe('route order significant', () => {
+  test('the same two routes reversed shows a mismatch', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH ? Response.json(liveTree) : fakeFailure(500, 'x'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    const attrs = live !== undefined ? spec.attributes(live, props) : undefined;
+    const reversed = { route: { ...declaredRoute, routes: [...declaredRoute.routes].reverse() } };
+    expect(attrs !== undefined && spec.matches(attrs, reversed)).toBe(false);
+  });
+});