@homeflare/alchemy 0.34.0 → 0.35.0

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,18 @@
  *   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` 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.
  */
+export {
+  type AlertRuleGroupAttributes,
+  type AlertRuleGroupProps,
+  type AlertRuleInput,
+  GrafanaAlertRuleGroup,
+  GrafanaAlertRuleGroupProvider,
+} from './alert-rule-group.ts';
 export {
   type DatasourceAttributes,
   type DatasourceProps,

package/src/grafana/providers.ts

@@ -12,6 +12,7 @@
  *   deploys anything over HTTP already has one.
  */
 import * as Layer from 'effect/Layer';
+import { GrafanaAlertRuleGroupProvider } from './alert-rule-group.ts';
 import { GrafanaContactPointProvider } from './contact-point.ts';
 import { type GrafanaTarget, grafanaCredentials } from './credentials.ts';
 import { GrafanaDashboardProvider } from './dashboard.ts';
@@ -28,4 +29,5 @@ export const grafanaProviders = (target: GrafanaTarget) =>
     GrafanaContactPointProvider(),
     GrafanaMuteTimingProvider(),
     GrafanaMessageTemplateProvider(),
+    GrafanaAlertRuleGroupProvider(),
   ).pipe(Layer.provide(grafanaCredentials(target)));

package/src/proxmox/constraints-host-forms.test.ts

@@ -11,7 +11,7 @@
 import { describe, expect, test } from 'bun:test';
 import { constraintsFor, formViolations } from './constraint-guard.ts';
 import type { PbsTarget, PveTarget } from './credentials.ts';
-import { createBody as ifaceCreateForm } from './node-network-form.ts';
+import { createForm as ifaceCreateForm } from './node-network-form.ts';
 import { resolveGroups, targetForm } from './pbs-notification-target-form.ts';
 import { createForm as zfsCreateForm } from './zfs-pool-form.ts';
 
@@ -26,7 +26,7 @@ describe('the host families plan clean against their own creates', () => {
    * 🔴 THE BUG THIS PROOF FOUND. `createForm` was `body`, which never sent `iface` — and PVE marks
    *   it REQUIRED on the POST while `{node}` is the only path parameter. Every NodeNetwork create
    *   this repository could have made would have 400ed; nothing caught it because C1's three nodes
-   *   were all adopted, which takes the PUT path. See the 🔴 on `createBody`.
+   *   were all adopted, which takes the PUT path. See the 🔴 on `createForm`.
    */
   test('an interface create carries iface, which PVE requires in the body', () => {
     const form = ifaceCreateForm({

package/src/proxmox/network-apply-read.ts

@@ -18,6 +18,12 @@
  *   drops the envelope, so the one readable pending signal is invisible to every other resource in
  *   this package. Without the fetch below, `Proxmox.NetworkApply` could not diff honestly at all.
  *   ★ `pveEnvelopeWith` in client.ts now carries the same member failover as every other call.
+ *   ⛔ WHY THIS FAMILY DID NOT MOVE TO DISTILLED WITH `Proxmox.NodeNetwork` (2026-09-24, decision
+ *     43's walk-down): CONFIRMED against `@distilled.cloud/proxmox`'s own `protocol.ts` that its
+ *     `transformResponse` unconditionally returns `body.data ?? {}` for every operation, before a
+ *     generated call's typed output is even built — no typed call, current or future, could see
+ *     `changes` without a protocol-level change upstream. `pveEnvelopeWith` stays because nothing
+ *     else preserves the sibling this function needs.
  *
  * ⛔ AND THE INTERFACE ROWS CANNOT TELL YOU EITHER. MEASURED in PVE/INotify.pm `read_file`: when
  *   `/etc/network/interfaces.new` exists, THAT is the file that gets parsed, so
@@ -188,6 +194,12 @@ const ATTEMPTS = 30;
  *   of the task". Every mint returns a NEW token id, so a second mint is a different identity and
  *   is not the owner — which is why this takes a `PveCredential` and the caller keeps one lease
  *   across both calls, instead of widening the provisioning role to read its own tasks.
+ *
+ * ⛔ THE OTHER REASON THIS FAMILY DID NOT MOVE TO DISTILLED (2026-09-24): CHECKED against
+ *   `@distilled.cloud/proxmox`'s own `Task.awaitTask` (`src/task.ts`) before deciding — it
+ *   propagates a poll failure as a genuine typed `GetNodeTaskStatusError` rather than collapsing
+ *   it to `UNREACHABLE` the way this function does, which would turn the ⛔ two paragraphs above
+ *   into a failed `reconcile` on exactly the poll a mid-reload connection drop is expected to hit.
  */
 export const awaitTask = (
   target: PveTarget,

package/src/proxmox/network-apply.ts

@@ -44,6 +44,8 @@
  *   task it starts so it can poll it without `Sys.Audit`. ⛔ `Sys.Modify` ON A NODE IS NOT A SMALL
  *   GRANT — it also carries that node's DNS, hosts file, time and service configuration. Granting
  *   it cluster-wide to run this resource widens the provisioning role well beyond networking.
+ *
+ * ⛔ STAYS ON `client.ts` (2026-09-24) — network-apply-read.ts's header has the two MEASURED reasons.
  */
 import { Resource } from 'alchemy';
 import { isResolved } from 'alchemy/Diff';