@homeflare/alchemy 0.34.0 → 0.36.0

package/src/grafana/alert-rule-group-model.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure functions over one declared alert rule within a `Grafana.AlertRuleGroup` — no SDK call, no
+ * Effect. Split out of `alert-rule-group.ts` the same way `dashboard-model.ts` is split out of
+ * `dashboard.ts`: keeps that file under the house's 250-line cap, and lets the volatile-field
+ * normalization be exercised directly in a test without a fake Grafana in the way.
+ */
+import type * as grafana from '@distilled.cloud/grafana';
+
+/** One declared rule — the SDK's own `ProvisionedAlertRuleInput` shape, minus the three fields
+ *  this resource derives from the GROUP itself (never declared per-rule) and `uid` widened from
+ *  optional to required — see alert-rule-group.ts's file header for the uid-required doctrine. */
+export type AlertRuleInput = Omit<
+  grafana.ProvisionedAlertRuleInput,
+  'folderUID' | 'orgID' | 'ruleGroup' | 'uid'
+> & { uid: string };
+
+/** Grafana injects/reassigns these on every write; a declared rule never sets them meaningfully.
+ *  MEASURED against `ProvisionedAlertRule` (services/grafana.ts): `id` is the internal numeric row
+ *  id, `updated` a server-set timestamp — neither exists on `ProvisionedAlertRuleInput` (the WRITE
+ *  shape) at all, only on the READ shape, confirming both are Grafana-managed, not declarable.
+ *  `provenance` is likewise read-only, but handled separately by `alerting-provenance.ts`'s
+ *  refusal rather than compared here: an object this family just wrote reads back with
+ *  `provenance: "api"`, which the DECLARATION never sets, so comparing it here would show a false
+ *  `update` on every rule this family itself owns — the refusal already gives it the attention it
+ *  needs, before this comparison ever runs. */
+const RULE_VOLATILE_FIELDS = ['id', 'updated', 'provenance'] as const;
+
+/** `folderUID`/`ruleGroup`/`orgID` are forced to the group's own values (mirrors
+ *  `dashboard-model.ts`'s `normalizeModel` forcing `uid`) — a rule's declaration never repeats its
+ *  own group/folder, and a rule pasted from Grafana's own export always embeds whatever it read at
+ *  export time, which forcing to canonical values makes comparable regardless.
+ *  ⚠️ `orgID` DEFAULTS TO `1` — NOT MEASURED against a multi-org instance. Every Grafana instance
+ *  this house runs is single-org (grafana.md's own credentials section has no org-selecting
+ *  example); `GrafanaTarget.orgId` exists for a future multi-org target but a rule's own spec
+ *  functions have no access to it (unlike credentials, it is not ambient context here). A
+ *  multi-org declaration would need an explicit `orgID` prop added to `AlertRuleInput` — not
+ *  attempted here since no live target needs it yet. */
+export const normalizeRule = (
+  rule: Record<string, unknown>,
+  folderUid: string,
+  group: string,
+): Record<string, unknown> => {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(rule)) {
+    if (key === 'folderUID' || key === 'ruleGroup' || key === 'orgID') continue;
+    if ((RULE_VOLATILE_FIELDS as readonly string[]).includes(key)) continue;
+    out[key] = value;
+  }
+  out.folderUID = folderUid;
+  out.ruleGroup = group;
+  out.orgID = 1;
+  return out;
+};
+
+/** The full wire body for one rule on `routePutAlertRuleGroup` — the group-derived fields filled
+ *  in, `orgID` defaulted per the note above. */
+export const toWireRule = (
+  rule: AlertRuleInput,
+  folderUid: string,
+  group: string,
+): grafana.ProvisionedAlertRuleInput => ({
+  ...rule,
+  folderUID: folderUid,
+  orgID: 1,
+  ruleGroup: group,
+});

package/src/grafana/alert-rule-group-provenance.test.ts

@@ -0,0 +1,116 @@
+/**
+ * `Grafana.AlertRuleGroup`'s per-rule provenance refusal — explicit-foreign (`"file"` on one
+ * rule), missing (a rule whose response omits the field, failing closed the same way every other
+ * resource in this family does), an EXPLICIT `""` being writable, and an empty group having
+ * nothing to refuse on. Split out of `alert-rule-group.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, liveJson, liveRule, props } from './alert-rule-group-fixtures.ts';
+import { spec } from './alert-rule-group.ts';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { grafanaOperations } from './resource.ts';
+
+describe('a foreign-provenance rule refuses the whole group', () => {
+  test('one file-provisioned rule among several refuses update and sends no PUT', async () => {
+    const mixed = {
+      ...liveJson,
+      rules: [liveRule, { ...liveRule, uid: 'other', provenance: 'file' }],
+    };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH
+        ? Response.json(mixed)
+        : fakeFailure(500, 'no write should be attempted'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .reconcile({ ...props, interval: 120 })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaProvisionedObjectError);
+    expect(failure.message).toContain('file');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('a file-provisioned group refuses destroy and sends no DELETE', async () => {
+    const fileProvisioned = { ...liveJson, rules: [{ ...liveRule, 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)
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaProvisionedObjectError);
+    expect(fake.seen).toEqual([{ method: 'GET', path: PATH }]);
+  });
+});
+
+describe('missing provenance on a rule fails closed', () => {
+  // ⛔ SAME REGRESSION AN ADVERSARIAL REVIEW OF kit PR 250 FOUND — see contact-point-provenance.
+  //   test.ts's own copy of this block for the full account.
+  const noProvenanceRule: Record<string, unknown> = { ...liveRule };
+  delete noProvenanceRule.provenance;
+
+  test('a response where a rule omits provenance entirely refuses update', async () => {
+    const missing = { ...liveJson, rules: [noProvenanceRule] };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH
+        ? Response.json(missing)
+        : fakeFailure(500, 'no write should be attempted'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .reconcile({ ...props, interval: 120 })
+          .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 = { ...liveJson, rules: [{ ...liveRule, 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({ ...props, interval: 120 })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen.some((s) => s.method === 'PUT')).toBe(true);
+  });
+});
+
+describe('an empty live group has nothing to refuse on', () => {
+  test('a group with zero rules is never foreign, and destroy proceeds', async () => {
+    const empty = { ...liveJson, rules: [] };
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === PATH) return Response.json(empty);
+      if (method === 'DELETE' && url.pathname === PATH) return Response.json({});
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .destroy(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen).toEqual([
+      { method: 'GET', path: PATH },
+      { method: 'DELETE', path: PATH },
+    ]);
+  });
+});

package/src/grafana/alert-rule-group.test.ts

@@ -0,0 +1,164 @@
+/**
+ * `Grafana.AlertRuleGroup` against a fake Grafana — the group-not-rule unit's create/update as one
+ * PUT, rule-order significance, volatile-field normalization, and the folder-doesn't-exist refusal.
+ * Provenance refusal tests: `alert-rule-group-provenance.test.ts` — split to keep each file under
+ * the house's 250-line cap. Mirrors `dashboard.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { PATH, liveJson, props, ruleInput } from './alert-rule-group-fixtures.ts';
+import { spec } from './alert-rule-group.ts';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { grafanaOperations } from './resource.ts';
+
+describe('spec.fetchLive', () => {
+  test('a live group decodes and normalizes into typed attributes', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH ? Response.json(liveJson) : 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({
+      folderUid: 'infra',
+      group: 'default',
+      interval: 60,
+      rules: [
+        {
+          condition: 'A',
+          data: [{ refId: 'A' }],
+          execErrState: 'Alerting',
+          folderUID: 'infra',
+          for: '5m',
+          noDataState: 'NoData',
+          orgID: 1,
+          ruleGroup: 'default',
+          title: 'High CPU',
+          uid: 'high-cpu',
+        },
+      ],
+    });
+    expect(fake.bodies[0]).toBeUndefined();
+  });
+
+  test('a 404 folds to undefined', async () => {
+    const fake = fakeGrafana(() => fakeFailure(404, 'rule group not found'));
+    const result = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(result).toBeUndefined();
+  });
+
+  test('a 403 propagates — never folded to absent', 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('create', () => {
+  test('sends interval and rules with the group-derived fields filled in', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'PUT' && url.pathname === PATH ? Response.json(liveJson) : fakeFailure(404, 'x'),
+    );
+    await Effect.runPromise(spec.create(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))));
+    expect(fake.bodies[0]).toEqual({
+      folderUid: 'infra',
+      interval: 60,
+      rules: [{ ...ruleInput, folderUID: 'infra', orgID: 1, ruleGroup: 'default' }],
+      title: 'default',
+    });
+  });
+
+  test('a nonexistent target folder fails as a typed BadRequest, never silently created', async () => {
+    // ⛔ THE POINT: this resource never checks folder existence itself and never calls
+    //   `Grafana.Folder`'s create path — see the file header. `RoutePutAlertRuleGroupError` has no
+    //   `NotFound` case; Grafana's own validation failure is a `BadRequest`, left uncaught here.
+    const fake = fakeGrafana(() => fakeFailure(400, 'folder does not exist'));
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.create(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('BadRequest');
+  });
+});
+
+describe('reconcile — adopt semantics, rule order significant', () => {
+  test('declaring exactly what is live is a noop despite id/updated/provenance differing', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH
+        ? Response.json(liveJson)
+        : fakeFailure(500, 'reconcile should not write when nothing changed'),
+    );
+    const after = await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(after.group).toBe('default');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('two rules in a different order than live shows update — order is content, not cosmetic', async () => {
+    // ⛔ live is [low-disk, high-cpu]; declared below is [high-cpu, low-disk] — the SAME two rules,
+    //   reversed. A looser "declared is a set of live's rules" comparison would call this a match;
+    //   subset-match's array rule (position-significant) must not.
+    const secondRule = { ...ruleInput, title: 'Low Disk', uid: 'low-disk' };
+    const reordered = {
+      ...liveJson,
+      rules: [
+        { ...liveJson.rules[0], title: 'Low Disk', uid: 'low-disk' },
+        { ...liveJson.rules[0] },
+      ],
+    };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH ? Response.json(reordered) : 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 declaredReordered = { ...props, rules: [ruleInput, secondRule] };
+    expect(attrs !== undefined && spec.matches(attrs, declaredReordered)).toBe(false);
+  });
+});
+
+describe('update', () => {
+  test('a content change updates via the same PUT, sending only declared fields', async () => {
+    const changed = { ...ruleInput, for: '10m' };
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === PATH) return Response.json(liveJson);
+      if (method === 'PUT' && url.pathname === PATH) {
+        return Response.json({ ...liveJson, rules: [{ ...liveJson.rules[0], for: '10m' }] });
+      }
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile({ ...props, rules: [changed] })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    const put = fake.seen.findIndex((s) => s.method === 'PUT');
+    expect(fake.bodies[put]).toMatchObject({ rules: [{ for: '10m' }] });
+  });
+});
+
+describe('destroy', () => {
+  test('deletes a live, api-provenance group', async () => {
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === PATH) return Response.json(liveJson);
+      if (method === 'DELETE' && url.pathname === PATH) return Response.json({});
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .destroy(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen).toEqual([
+      { method: 'GET', path: PATH },
+      { method: 'DELETE', path: PATH },
+    ]);
+  });
+});

package/src/grafana/alert-rule-group.ts

@@ -0,0 +1,231 @@
+/**
+ * `Grafana.AlertRuleGroup` — one Grafana alert rule GROUP, keyed by `(folderUid, group)`.
+ *
+ * ★ GROUP, NOT PER-RULE — THE UNIT CHOICE, JUSTIFIED. MEASURED against the SDK's generated
+ *   operations: `PUT /v1/provisioning/folder/{FolderUID}/rule-groups/{Group}`
+ *   (`routePutAlertRuleGroup`) takes the evaluation `interval` AND the full ordered `rules[]`
+ *   TOGETHER, replacing the whole group in one call (`RoutePutAlertRuleGroupRequest.rules:
+ *   Array<ProvisionedAlertRuleInput>`) — the individual `routePostAlertRule`/`routePutAlertRule`
+ *   operations have no `interval` field at all and cannot reorder rules within a group. Declaring
+ *   rules one at a time (`Grafana.AlertRule`) would leave a group's evaluation interval and rule
+ *   order — both real, load-bearing Grafana state — either undeclarable or racy across N
+ *   independent resources with no shared source of truth for them. Grafana's own docs describe
+ *   `X-Disable-Provenance` on the rule-group PUT as setting "the provenance for the rule group AND
+ *   ALL ITS ALERT RULES" — further evidence the group, not the rule, is Grafana's own natural unit
+ *   of ownership here. Mirrors Terraform's own `grafana_rule_group` resource, which takes the
+ *   identical shape (a list of rules under one folder/name/interval).
+ *
+ * ★ `uid` IS REQUIRED ON EVERY DECLARED RULE — same doctrine as every other resource in this
+ *   family (`AlertRuleInput` in `alert-rule-group-model.ts`). `ProvisionedAlertRuleInput.uid` is
+ *   optional on the wire (Grafana assigns one if omitted), but locating a specific rule this
+ *   resource didn't just create would then mean matching by title — the same ambiguity
+ *   `resource.ts`'s header and netbox's `soleMatch` exist to catch everywhere else in this family.
+ *
+ * ⛔ RULE ORDER IS SIGNIFICANT — NEVER REORDERED. `subset-match.ts`'s array comparison is already
+ *   position-significant (length, then element-wise) — this resource relies on that as-is; nothing
+ *   here re-sorts `rules` before comparing. Declaring rules in a different order than what is live
+ *   is a genuine content change (Grafana evaluates and displays a group's rules in array order),
+ *   not a cosmetic one.
+ *
+ * ⛔ A FOREIGN-PROVENANCE GROUP REFUSES EVERY UPDATE AND DESTROY — `alerting-provenance.ts`. Unlike
+ *   `ContactPoint`/`MessageTemplate`, `AlertRuleGroup` (the type `routeGetAlertRuleGroup` returns)
+ *   carries NO top-level `provenance` field — MEASURED: `folderUid?`/`interval?`/`rules?`/`title?`
+ *   only. Each RULE inside `rules[]` has its own (`ProvisionedAlertRule.provenance`), and Grafana's
+ *   docs say a new rule's provenance "must match the provenance value configured for its rule
+ *   group" — so this resource checks every live rule and refuses if ANY carries a foreign
+ *   provenance, naming the first one found. An empty live group (no rules yet) has nothing to check
+ *   and is never foreign. `create` is never at risk: it only runs when `fetchLive` already found
+ *   nothing.
+ *
+ * ⛔ A DECLARED GROUP WHOSE FOLDER DOES NOT EXIST REFUSES — IT IS NEVER AUTO-CREATED. This resource
+ *   makes no "does the folder exist" call of its own and does not depend on or invoke
+ *   `Grafana.Folder`'s create path. MEASURED: `RoutePutAlertRuleGroupError` is
+ *   `BadRequest | Forbidden | GrafanaOpError` — no `NotFound` case at all — so a nonexistent
+ *   `folderUid` fails the PUT as a typed `BadRequest`, left uncaught and propagated (the house rule
+ *   against folding a non-not-found error into absent), which fails the whole `reconcile` and stops
+ *   the deploy. Declare a `Grafana.Folder` for it first — the two resources sharing one `folderUid`
+ *   string is the dependency; auto-creating a folder from inside this resource would blur ownership
+ *   the same way `provisioned.ts`'s "one owner per resource" principle already guards against
+ *   elsewhere in this family. ⚠️ NOT RE-MEASURED against a live instance in this PR — inferred from
+ *   the declared error union, the same evidentiary bar `folder.ts`'s own `version` note uses.
+ *
+ * ⛔ DELETE DEFAULTS TO `retain` — DELETING A GROUP DELETES EVERY RULE IN IT IN ONE CALL
+ *   (`routeDeleteAlertRuleGroup`, whole-group DELETE). The same multi-object-cascade class
+ *   `Grafana.Folder`/`openbao/mount.ts` already guard with `defaultRemovalPolicy: 'retain'` — a
+ *   stack that wants the cascade opts in with `.pipe(RemovalPolicy.destroy())`; `destroy` below
+ *   still implements the real DELETE in full either way (S11).
+ *
+ * ⚠️ `orgID` DEFAULTS TO `1` ON EVERY WRITTEN RULE — see `alert-rule-group-model.ts`'s own note;
+ *   not measured against a multi-org instance, since none exists in this house yet.
+ *
+ * ⚠️ `X-Disable-Provenance` IS NEVER SET — same reasoning as `contact-point.ts`'s file header.
+ *
+ * ⚠️ A WHOLE-GROUP WRITE SILENTLY DROPS ANY LIVE RULE THE DECLARATION DOESN'T MENTION — flagged by
+ *   an adversarial review of this PR. Unlike every other resource in this family, this one does
+ *   not compare one object's fields; `update`/`diff` REPLACE an entire collection, so a live rule
+ *   with no counterpart in `props.rules` (e.g. one a human just added in the Grafana UI, ordinary
+ *   writable provenance — nothing for the refusal above to catch) is removed with no error and no
+ *   distinct `Diff` action to report it under. This is accepted by design — the group is still the
+ *   unit — but never SILENT: `alert-rule-group-drop-warning.ts`'s `warnOnDroppedRules` logs every
+ *   dropped rule by title and uid, called from both the custom `diff` below (so `bun run plan`
+ *   shows it before anything is written) and from `update` itself (so it is visible wherever
+ *   `reconcile` runs directly too).
+ */
+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 { warnOnDroppedRules } from './alert-rule-group-drop-warning.ts';
+import { type AlertRuleInput, normalizeRule, toWireRule } from './alert-rule-group-model.ts';
+import {
+  type GrafanaProvisionedObjectError,
+  isForeignProvenance,
+  refuseIfForeignProvenance,
+} from './alerting-provenance.ts';
+import { type GrafanaSpec, grafanaHandlers } from './resource.ts';
+import { declaredContentMatches } from './subset-match.ts';
+
+export type { AlertRuleInput };
+
+export interface AlertRuleGroupProps {
+  folderUid: string;
+  group: string;
+  /** Evaluation interval, in seconds. */
+  interval: number;
+  /** Order is significant — see the file header. */
+  rules: ReadonlyArray<AlertRuleInput>;
+}
+
+export interface AlertRuleGroupAttributes {
+  folderUid: string;
+  group: string;
+  interval: number;
+  rules: ReadonlyArray<Record<string, unknown>>;
+}
+
+export interface GrafanaAlertRuleGroup extends Resource<
+  'Grafana.AlertRuleGroup',
+  AlertRuleGroupProps,
+  AlertRuleGroupAttributes,
+  never
+> {}
+
+export const GrafanaAlertRuleGroup = Resource<GrafanaAlertRuleGroup>('Grafana.AlertRuleGroup', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** The first live rule whose provenance this family may not write to, or `undefined` when every
+ *  rule (including none at all) is writable. */
+const findForeignRule = (
+  rules: ReadonlyArray<grafana.ProvisionedAlertRule> | undefined,
+): grafana.ProvisionedAlertRule | undefined =>
+  (rules ?? []).find((rule) => isForeignProvenance(rule.provenance));
+
+const body = (props: AlertRuleGroupProps) => ({
+  folderUid: props.folderUid,
+  interval: props.interval,
+  rules: props.rules.map((rule) => toWireRule(rule, props.folderUid, props.group)),
+  title: props.group,
+});
+
+const refuseForForeignRule = (props: AlertRuleGroupProps, foreign: grafana.ProvisionedAlertRule) =>
+  refuseIfForeignProvenance(
+    'Grafana.AlertRuleGroup',
+    `${props.folderUid}/${props.group}`,
+    foreign.provenance,
+  );
+
+const declaredUids = (props: AlertRuleGroupProps): ReadonlySet<string> =>
+  new Set(props.rules.map((rule) => rule.uid));
+
+export const spec: GrafanaSpec<
+  AlertRuleGroupProps,
+  grafana.AlertRuleGroup,
+  AlertRuleGroupAttributes,
+  | grafana.RouteGetAlertRuleGroupError
+  | grafana.RoutePutAlertRuleGroupError
+  | grafana.RouteDeleteAlertRuleGroupError
+  | GrafanaProvisionedObjectError
+> = {
+  attributes: (live, props) => ({
+    folderUid: live.folderUid ?? props.folderUid,
+    group: props.group,
+    interval: live.interval ?? 0,
+    rules: (live.rules ?? []).map((rule) =>
+      normalizeRule(rule as unknown as Record<string, unknown>, props.folderUid, props.group),
+    ),
+  }),
+  create: (props) =>
+    grafana.routePutAlertRuleGroup({
+      FolderUID: props.folderUid,
+      Group: props.group,
+      ...body(props),
+    }),
+  destroy: (props, live) =>
+    Effect.gen(function* () {
+      const foreign = findForeignRule(live.rules);
+      if (foreign !== undefined) return yield* refuseForForeignRule(props, foreign);
+      yield* grafana.routeDeleteAlertRuleGroup({ FolderUID: props.folderUid, Group: props.group });
+    }),
+  fetchLive: (props) =>
+    grafana
+      .routeGetAlertRuleGroup({ FolderUID: props.folderUid, Group: props.group })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  matches: (attributes, props) =>
+    attributes.interval === props.interval &&
+    declaredContentMatches(
+      props.rules.map((rule) =>
+        normalizeRule(rule as unknown as Record<string, unknown>, props.folderUid, props.group),
+      ),
+      attributes.rules,
+    ),
+  update: (props, live) =>
+    Effect.gen(function* () {
+      const foreign = findForeignRule(live.rules);
+      if (foreign !== undefined) return yield* refuseForForeignRule(props, foreign);
+      yield* warnOnDroppedRules(props.folderUid, props.group, declaredUids(props), live.rules);
+      yield* grafana.routePutAlertRuleGroup({
+        FolderUID: props.folderUid,
+        Group: props.group,
+        ...body(props),
+      });
+    }),
+};
+
+/**
+ * ⚠️ A LOCAL REIMPLEMENTATION OF `resource.ts`'s GENERIC `diff`, NOT A WRAP OF IT — deliberately.
+ *   The generic `grafanaOperations(spec).diff` fetches live and maps it to `Attributes` entirely
+ *   inside itself, with no seam to run the drop warning against the rules it read; wrapping it
+ *   would mean a SECOND live fetch just to see what it saw. This resource's `diff` is the ONLY one
+ *   in the family that needs a resource-specific side effect mid-comparison, so it re-reads
+ *   `resource.ts`'s own logic here rather than changing the shared engine every other resource
+ *   also uses. Keep this in sync with `resource.ts`'s `grafanaOperations.diff` if that ever
+ *   changes shape.
+ */
+const diff = ({
+  news,
+  output,
+}: {
+  news: Input<AlertRuleGroupProps>;
+  output: AlertRuleGroupAttributes | undefined;
+}) =>
+  Effect.gen(function* () {
+    if (output === undefined || !isResolved(news)) return undefined;
+    const live = yield* spec.fetchLive(news);
+    if (live === undefined) return { action: 'update' } as const;
+    yield* warnOnDroppedRules(news.folderUid, news.group, declaredUids(news), live.rules);
+    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 GrafanaAlertRuleGroupProvider = () =>
+  Provider.effect(
+    GrafanaAlertRuleGroup,
+    Effect.succeed(GrafanaAlertRuleGroup.Provider.of(handlers)),
+  );

package/src/grafana/index.ts

@@ -7,11 +7,25 @@
  *   depend on.
  *
  * `Grafana.Datasource`, `Grafana.Folder`, `Grafana.Dashboard`, `Grafana.ContactPoint`,
- * `Grafana.MuteTiming` and `Grafana.MessageTemplate` ship here. `Grafana.AlertRuleGroup` and
- * `Grafana.NotificationPolicy` are stacked follow-up PRs 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,
+  type AlertRuleGroupProps,
+  type AlertRuleInput,
+  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,