@homeflare/alchemy 0.35.0 → 0.37.0

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

package/src/grafana/notification-policy.ts

@@ -0,0 +1,191 @@
+/**
+ * `Grafana.NotificationPolicy` — the notification policy tree. A SINGLETON: `GET`/`PUT`
+ * `/v1/provisioning/policies` always address the ONE tree an instance has, there is no path
+ * parameter, and `RouteGetPolicyTreeError` is `Forbidden | GrafanaOpError` — no `NotFound` case at
+ * all, MEASURED. `fetchLive` therefore NEVER returns `undefined`: this resource has no create and
+ * no delete in the sense every other resource in this family does — `reconcile`'s `before ===
+ * undefined` branch (`resource.ts`) is dead code here, and `create` below exists only because
+ * `GrafanaSpec.create` is a required field on the shared type, not because it is ever reached.
+ * "Declaring" this resource means ADOPTING whatever tree is live and then keeping it in sync —
+ * never creating or destroying the tree itself, only ever `PUT`-replacing its contents.
+ *
+ * ⛔ `routeResetPolicyTree` IS NEVER CALLED UNLESS `allowReset: true` IS EXPLICITLY DECLARED — a
+ *   second, independent gate on top of `defaultRemovalPolicy: 'retain'` below. Alchemy's own
+ *   removal-policy gate decides whether the engine calls this resource's `delete` handler AT ALL
+ *   (retain means it never does, unless a stack opts in with `.pipe(RemovalPolicy.destroy())` —
+ *   the convention every `Bao.*`/`Grafana.Folder`/`Grafana.AlertRuleGroup` family member already
+ *   uses); `allowReset` is a SEPARATE prop-level gate inside `destroy` itself, so even a stack that
+ *   opted into destroy at the Alchemy level still needs this resource's own explicit opt-in before
+ *   it will reset. 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 in one call, for the WHOLE instance, not one object. Without
+ *   `allowReset`, `destroy` logs a warning and returns — retained, not reset.
+ *
+ * ★ PUT REPLACES THE WHOLE TREE — A DROPPED SUB-ROUTE IS WARNED ABOUT, NEVER SILENT. Same shape as
+ *   kit PR 254's `Grafana.AlertRuleGroup` fix (an adversarial review of that PR found the identical
+ *   risk for rule groups): `notification-policy-drop-warning.ts`'s `warnOnDroppedRoutes`, called
+ *   from both this resource's custom `diff` (so `bun run plan` shows it before anything is
+ *   written) and from `update` itself.
+ *
+ * ⛔ ROUTE ORDER IS SIGNIFICANT — NEVER REORDERED. 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, not cosmetic.
+ *
+ * ⛔ A FOREIGN-PROVENANCE TREE REFUSES EVERY UPDATE — `alerting-provenance.ts`, 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 — see above, it is
+ *   unreachable.
+ *
+ * ⚠️ GRAFANA-INJECTED DEFAULTS ARE TOLERATED THE `declaredContentMatches` WAY, NOT HAND-NORMALIZED
+ *   — `matches()` below runs the (volatile-field-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
+ *   (Grafana injecting a default `group_wait`/`group_interval`/`repeat_interval`/`group_by: []`
+ *   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 (no live
+ *   calls in this PR either) — this is the documented, conservative default every unmeasured value
+ *   shape in this family takes, not a guess dressed up as a fact.
+ *
+ * ⚠️ `X-Disable-Provenance` IS NEVER SET — same reasoning as `contact-point.ts`'s file header.
+ */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as grafana from '@distilled.cloud/grafana';
+import * as Effect from 'effect/Effect';
+import {
+  type GrafanaProvisionedObjectError,
+  isForeignProvenance,
+  refuseIfForeignProvenance,
+} from './alerting-provenance.ts';
+import { type PolicyRoute, normalizeRoute } from './notification-policy-model.ts';
+import { warnOnDroppedRoutes } from './notification-policy-drop-warning.ts';
+import { type GrafanaSpec, grafanaHandlers } from './resource.ts';
+import { declaredContentMatches } from './subset-match.ts';
+
+export type { PolicyRoute };
+
+export interface NotificationPolicyProps {
+  /** The root route and its full nested tree — Grafana's `Route` shape (`receiver`, `group_by`,
+   *  `matchers`, nested `routes[]`, …), passed through opaquely — see the file header. Order of
+   *  `routes[]` at every level is significant. */
+  route: PolicyRoute;
+  /** Lets `destroy` actually call `routeResetPolicyTree`. Defaults to `false` — see the file
+   *  header for why this is a second gate on top of Alchemy's own removal policy. */
+  allowReset?: boolean;
+}
+
+export interface NotificationPolicyAttributes {
+  route: PolicyRoute;
+  /** `""`/`"api"` (this family may write); anything else, INCLUDING `undefined`, refuses — see
+   *  alerting-provenance.ts's "fails open" note. */
+  provenance: string | undefined;
+}
+
+export interface GrafanaNotificationPolicy extends Resource<
+  'Grafana.NotificationPolicy',
+  NotificationPolicyProps,
+  NotificationPolicyAttributes,
+  never
+> {}
+
+export const GrafanaNotificationPolicy = Resource<GrafanaNotificationPolicy>(
+  'Grafana.NotificationPolicy',
+  { defaultRemovalPolicy: 'retain' },
+);
+
+const body = (props: NotificationPolicyProps) =>
+  props.route as unknown as grafana.RoutePutPolicyTreeRequest;
+
+export const spec: GrafanaSpec<
+  NotificationPolicyProps,
+  grafana.Route,
+  NotificationPolicyAttributes,
+  | grafana.RouteGetPolicyTreeError
+  | grafana.RoutePutPolicyTreeError
+  | grafana.RouteResetPolicyTreeError
+  | GrafanaProvisionedObjectError
+> = {
+  attributes: (live) => ({
+    provenance: live.provenance,
+    route: normalizeRoute(live as unknown as PolicyRoute),
+  }),
+  // ⚠️ UNREACHABLE IN PRACTICE — see the file header. Implemented as the same PUT `update` sends,
+  //   defensively, rather than `Effect.die`, in case a future Grafana version ever does answer
+  //   `NotFound` here; `GrafanaSpec.create` is required by the shared type either way.
+  create: (props) => grafana.routePutPolicyTree(body(props)),
+  destroy: (props, live) =>
+    Effect.gen(function* () {
+      if (isForeignProvenance(live.provenance)) {
+        return yield* refuseIfForeignProvenance(
+          'Grafana.NotificationPolicy',
+          'default',
+          live.provenance,
+        );
+      }
+      if (props.allowReset !== true) {
+        yield* Effect.logWarning(
+          'Grafana.NotificationPolicy: destroy requested but allowReset is not set -- the policy ' +
+            'tree is RETAINED, not reset. Grafana always needs a root route; resetting wipes ' +
+            "every declared route/receiver/matcher back to Grafana's own default for the WHOLE " +
+            'instance. Set allowReset: true to actually call routeResetPolicyTree.',
+        );
+        return;
+      }
+      yield* grafana.routeResetPolicyTree({});
+    }),
+  fetchLive: (_props) => grafana.routeGetPolicyTree({}),
+  matches: (attributes, props) =>
+    declaredContentMatches(normalizeRoute(props.route), attributes.route),
+  update: (props, live) =>
+    Effect.gen(function* () {
+      if (isForeignProvenance(live.provenance)) {
+        return yield* refuseIfForeignProvenance(
+          'Grafana.NotificationPolicy',
+          'default',
+          live.provenance,
+        );
+      }
+      yield* warnOnDroppedRoutes(props.route, live as unknown as PolicyRoute);
+      yield* grafana.routePutPolicyTree(body(props));
+    }),
+};
+
+/**
+ * ⚠️ A LOCAL REIMPLEMENTATION OF `resource.ts`'s GENERIC `diff`, NOT A WRAP OF IT — same reasoning
+ *   as `alert-rule-group.ts`'s own `diff`: the generic version has no seam to run the drop-warning
+ *   side effect against the live tree it reads, and wrapping it would mean a second live fetch
+ *   just to see what it already saw.
+ */
+const diff = ({
+  news,
+  output,
+}: {
+  news: Input<NotificationPolicyProps>;
+  output: NotificationPolicyAttributes | undefined;
+}) =>
+  Effect.gen(function* () {
+    if (output === undefined || !isResolved(news)) return undefined;
+    const live = yield* spec.fetchLive(news);
+    // ⚠️ UNREACHABLE IN PRACTICE — see the file header: `routeGetPolicyTree` has no `NotFound`
+    //   case, so `live` is never actually `undefined`. `GrafanaSpec.fetchLive`'s shared return
+    //   type is `Live | undefined` for every resource in the family, so this check exists purely
+    //   to satisfy that type, the same defensive stance `create` above takes.
+    if (live === undefined) return { action: 'update' } as const;
+    yield* warnOnDroppedRoutes(news.route, live as unknown as PolicyRoute);
+    const mapped = spec.attributes(live, news);
+    return mapped !== undefined && spec.matches(mapped, news)
+      ? ({ action: 'noop' } as const)
+      : ({ action: 'update' } as const);
+  });
+
+export const handlers = { ...grafanaHandlers(spec), diff };
+
+export const GrafanaNotificationPolicyProvider = () =>
+  Provider.effect(
+    GrafanaNotificationPolicy,
+    Effect.succeed(GrafanaNotificationPolicy.Provider.of(handlers)),
+  );

package/src/grafana/providers.ts

@@ -20,6 +20,7 @@ import { GrafanaDatasourceProvider } from './datasource.ts';
 import { GrafanaFolderProvider } from './folder.ts';
 import { GrafanaMessageTemplateProvider } from './message-template.ts';
 import { GrafanaMuteTimingProvider } from './mute-timing.ts';
+import { GrafanaNotificationPolicyProvider } from './notification-policy.ts';
 
 export const grafanaProviders = (target: GrafanaTarget) =>
   Layer.mergeAll(
@@ -30,4 +31,5 @@ export const grafanaProviders = (target: GrafanaTarget) =>
     GrafanaMuteTimingProvider(),
     GrafanaMessageTemplateProvider(),
     GrafanaAlertRuleGroupProvider(),
+    GrafanaNotificationPolicyProvider(),
   ).pipe(Layer.provide(grafanaCredentials(target)));

package/src/litellm/operations.ts

@@ -58,10 +58,14 @@ const semaphoreFor = (baseUrl: string): Effect.Effect<Semaphore.Semaphore> =>
 /**
  * Serialises a write against this call's own base URL — see the file header.
  *
- * Resolving `Credentials` can itself fail typed (`ConfigError` — S20/S24, credentials.ts), so
- * the return type carries that alongside the wrapped operation's own error `E`; every call
- * site's declared error type already includes `ConfigError` as a member of the SDK's shared
- * `LitellmOpError` (protocol.ts), so this widening is a no-op for callers.
+ * ⚠️ `Credentials` itself ends in `Effect.orDie` on a missing/misspelled env var (Q6, decision
+ *   49 "upstream wins", 2026-09-24, matching distilled's own convention — 73 of 80 packages'
+ *   `credentials.ts` do the same at `homeflare/base`), so resolving it here can no longer fail
+ *   typed. The `| ConfigError` this function still adds to its return type stays only because
+ *   `@distilled.cloud/litellm`'s own `LitellmOpError` (protocol.ts) unconditionally declares
+ *   `ConfigError` as a member of every generated operation's error union regardless of
+ *   `Credentials`'s own type — so `E` (the wrapped operation's error) already contains it, and
+ *   this widening is a genuine no-op for callers, not dead type-state left over from the revert.
  */
 const mutate = <A, E>(
   io: Effect.Effect<A, E, LitellmOpContext>,