@homeflare/alchemy 0.34.0 → 0.35.0

package/docs/grafana-alerting-rules.md

@@ -0,0 +1,143 @@
+# `Grafana.AlertRuleGroup` — `@homeflare/alchemy/grafana`
+
+Second of three stacked PRs bringing Grafana alerting provisioning under Alchemy
+([grafana-alerting.md](./grafana-alerting.md) covers the first: `Grafana.ContactPoint`,
+`Grafana.MuteTiming`, `Grafana.MessageTemplate`). Branched fresh off `main` after that PR merged,
+so this is its own diff, not stacked on it. No live call was made writing this PR.
+
+## The unit: group, not rule
+
+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. The individual
+`routePostAlertRule`/`routePutAlertRule` operations have no `interval` field at all and cannot
+reorder rules within a group — declaring rules one at a time would leave a group's interval and
+rule order either undeclarable or racy across N independent resources with no shared source of
+truth. 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" — the group, not the rule, is Grafana's own
+natural unit here. Mirrors Terraform's `grafana_rule_group` resource, which takes the identical
+shape.
+
+## Example
+
+```ts
+import { GrafanaAlertRuleGroup, grafanaProviders } from '@homeflare/alchemy/grafana';
+
+export class InfraAlerts extends GrafanaAlertRuleGroup('infra-alerts', {
+  folderUid: 'infra',
+  group: 'default',
+  interval: 60,
+  rules: [
+    {
+      uid: 'high-cpu',
+      title: 'High CPU',
+      condition: 'A',
+      data: [/* … AlertQuery, the SDK's own shape … */],
+      for: '5m',
+      noDataState: 'NoData',
+      execErrState: 'Alerting',
+    },
+  ],
+}) {}
+```
+
+## `uid` is required on every declared rule
+
+Same doctrine as every other resource in this family. `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 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 (exact length, then
+element-wise) — this resource relies on that as-is. 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), proven by a dedicated test (`alert-rule-group.test.ts`) that declares the same two rules
+reversed and asserts `matches` is `false`.
+
+## Dropped-rule warning — accepted, never silent
+
+⚠️ **Flagged by an adversarial review of this PR.** A whole-group `PUT` replaces the entire rule
+list — a live rule with no counterpart in the declaration (a human adding one in the Grafana UI
+minutes before a deploy, ordinary writable provenance, nothing for the refusal above to catch) is
+removed with no error, and `diff` has no distinct action to report a lossy update under
+(`alchemy/Diff`'s `Diff` type is exactly `NoopDiff | UpdateDiff | ReplaceDiff`). This is accepted
+by design — the group is still the unit — but never silent:
+`alert-rule-group-drop-warning.ts`'s `warnOnDroppedRules` logs a loud `Effect.logWarning` naming
+every dropped rule by title and uid, called from BOTH this resource's custom `diff` (so
+`bun run plan` shows it before anything is written) and from `update` itself (so it is visible
+wherever `reconcile` runs directly too). Mirrors the house pattern
+`proxmox/unreadable-read.ts`'s `unreadableWarning` established.
+
+`diff` is a LOCAL reimplementation of `resource.ts`'s generic `grafanaOperations(spec).diff`, not a
+wrap of it — the generic version has no seam to run a side effect against the live rules it reads,
+and wrapping it would mean fetching live twice just to see what it already saw. This is the only
+resource in the family that needs this; every other resource still uses the shared engine
+unmodified.
+
+## Volatile-field normalization (`alert-rule-group-model.ts`)
+
+`normalizeRule` strips three fields before ANY comparison, each measured against
+`ProvisionedAlertRule`/`ProvisionedAlertRuleInput`:
+
+- `id` — the internal numeric row id. Exists only on the READ shape, absent from the WRITE shape —
+  confirms it is Grafana-managed, never declarable.
+- `updated` — a server-set timestamp. Same evidence: read-only shape only.
+- `provenance` — read-only too, but handled by the foreign-provenance refusal below rather than
+  compared for drift: an object this family just wrote reads back `provenance: "api"`, which the
+  declaration never sets, so comparing it would show a false `update` on every rule this family
+  owns.
+
+`folderUID`/`ruleGroup`/`orgID` are forced to the group's own canonical values (mirrors
+`dashboard-model.ts`'s `normalizeModel` forcing `uid`) — a rule's declaration never repeats its own
+group/folder. ⚠️ `orgID` defaults to `1`, not measured against a multi-org instance (none exists in
+this house yet); a rule's own spec functions have no access to `GrafanaTarget.orgId` the way
+credentials do.
+
+## Foreign-provenance refusal — per rule, whole-group refuse
+
+Unlike `ContactPoint`/`MessageTemplate`, the `AlertRuleGroup` type itself (what
+`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 via
+`alerting-provenance.ts`'s shared `isForeignProvenance`/`refuseIfForeignProvenance` and refuses the
+WHOLE group's write if ANY rule carries a foreign provenance, naming the first one found. An empty
+live group (no rules yet) has nothing to check and is never foreign. The same "missing means
+foreign, never `ProvenanceNone`" fail-closed rule kit PR 250's adversarial review established
+applies here unchanged — pinned by `alert-rule-group-provenance.test.ts`.
+
+## A declared group whose folder does not exist — refuses, never auto-creates
+
+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, 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 — 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`) — 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())`.
+
+## Tests
+
+`alert-rule-group.test.ts` (fetchLive/create/reconcile/order/update/destroy),
+`alert-rule-group-model.test.ts` (pure `normalizeRule`/`toWireRule`),
+`alert-rule-group-provenance.test.ts` (foreign, missing, explicit-none, empty-group) and
+`alert-rule-group-drop-warning.test.ts` — split four ways to stay under the house's 250-line file
+cap, sharing fixtures from `alert-rule-group-fixtures.ts`. Prove: a GET never carries a body; a
+nonexistent folder propagates `BadRequest` rather than being folded to absent or silently creating
+one; a foreign-provenance rule (explicit `"file"` or MISSING) refuses the whole group's
+update/destroy while an explicit `""` is writable; reordering the same rules shows `update`; an
+unchanged declaration is a noop despite `id`/`updated`/`provenance` differing on every rule; and —
+`alert-rule-group-drop-warning.test.ts`, added after an adversarial review — a live rule the
+declaration doesn't mention is named by title and uid in a logged warning from both `diff` and
+`update`, and nothing is warned when every live rule is declared.

package/docs/grafana-alerting.md

@@ -3,9 +3,11 @@
 Declares Grafana's alerting-provisioning objects (decision 40: every internal alert lands in one
 place). Ships in three stacked PRs, in the order this file's own history records:
 
-1. **This PR:** `Grafana.ContactPoint`, `Grafana.MuteTiming`, `Grafana.MessageTemplate`.
-2. Next: `Grafana.AlertRuleGroup`.
-3. Then: `Grafana.NotificationPolicy` — the singleton policy tree, last on purpose (it references
+1. **`Grafana.ContactPoint`, `Grafana.MuteTiming`, `Grafana.MessageTemplate`** — this file, kit
+   PR 250.
+2. **`Grafana.AlertRuleGroup`** — [grafana-alerting-rules.md](./grafana-alerting-rules.md), a
+   separate stacked PR (its own diff off `main`, not this one) once this file's doc budget filled.
+3. Next: `Grafana.NotificationPolicy` — the singleton policy tree, last on purpose (it references
    contact points, mute timings and templates by name).
 
 All three ship on the same `@distilled.cloud/grafana@0.2.0` operations

package/docs/grafana.md

@@ -128,7 +128,9 @@ export class TeslaMateDatasource extends GrafanaDatasource('teslamate-datasource
   [grafana-folder-dashboard.md](./grafana-folder-dashboard.md), not repeated here.
 - **`Grafana.ContactPoint`, `Grafana.MuteTiming` and `Grafana.MessageTemplate` ship** — see
   [grafana-alerting.md](./grafana-alerting.md), not repeated here.
-- **`Grafana.AlertRuleGroup` and `Grafana.NotificationPolicy`** — stacked follow-up PRs on the same
-  operations, per grafana-alerting.md's own ordering; not blocked on anything.
+- **`Grafana.AlertRuleGroup` ships** — see [grafana-alerting-rules.md](./grafana-alerting-rules.md),
+  not repeated here.
+- **`Grafana.NotificationPolicy`** — the last stacked follow-up PR, the singleton policy tree, on
+  the same operations; not blocked on anything.
 - **`read` never answers `Unowned`** — the same open gap forgejo's and netbox's own families
   still carry (see upstream-conformance.md); a maintainer decision on the ownership-check shape.

package/docs/upstream-conformance.md

@@ -267,8 +267,9 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
     normalization that makes an unchanged dashboard a true noop are all in
     [grafana-folder-dashboard.md](./grafana-folder-dashboard.md), not repeated here.
 
-    ✅ **`Grafana.ContactPoint`/`Grafana.MuteTiming`/`Grafana.MessageTemplate` shipped** (this PR,
-    first of three stacked PRs — `Grafana.AlertRuleGroup` then `Grafana.NotificationPolicy` follow):
+    ✅ **`Grafana.ContactPoint`/`Grafana.MuteTiming`/`Grafana.MessageTemplate` shipped** (kit PR
+    250, first of three stacked PRs — `Grafana.AlertRuleGroup` then `Grafana.NotificationPolicy`
+    follow):
     the foreign-provenance refusal (`alerting-provenance.ts`, an allowlist of Grafana's own
     `ProvenanceNone`/`ProvenanceAPI` values, measured against `pkg/services/ngalert/models` and
     Grafana's v13.1 docs) and the secret-settings-ref seam (`secret-refs.ts`, shared with
@@ -288,8 +289,19 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
       timings or templates configured either (consistent with the alerting-provisioning gap having
       been real, not merely unexploited).
 
-    **Still open, not this PR's scope:** `Grafana.AlertRuleGroup`/`Grafana.NotificationPolicy` —
-    the next two stacked PRs, no longer blocked on the SDK.
+    ✅ **`Grafana.AlertRuleGroup` shipped** (this PR, second of three, branched fresh off `main`
+    after PR 250 merged): group, not per-rule, is the unit — `PUT .../rule-groups/{Group}` owns
+    evaluation `interval` and the full ordered `rules[]` together, which per-rule operations
+    cannot express (no `interval` field, no reordering). Rule order is significant, proven by a
+    dedicated test. The per-rule provenance refusal (each `ProvisionedAlertRule.provenance`, since
+    the group type itself carries none) reuses `alerting-provenance.ts` unchanged, including the
+    missing-means-foreign fix from PR 250's review. A declared group whose folder does not exist
+    refuses as a typed `BadRequest` (`RoutePutAlertRuleGroupError` has no `NotFound` case) rather
+    than being auto-created — this resource never calls `Grafana.Folder`'s create path. Full
+    detail: [grafana-alerting-rules.md](./grafana-alerting-rules.md).
+
+    **Still open, not this PR's scope:** `Grafana.NotificationPolicy` — the last stacked PR, the
+    singleton policy tree, no longer blocked on the SDK.
     - ⛔ **Same open gaps as `forgejo/*` and `netbox/*` above:** `read` never answers `Unowned`
       (H1), and credentials come from an explicit env var NAME at call time rather than an
       `alchemy/Auth` provider (S24) — here the house's own `grafanaCredentials(target)`, not the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",

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

@@ -0,0 +1,107 @@
+/**
+ * `warnOnDroppedRules` — pure logic, then wired through `diff`/`update` on a fake Grafana. Captures
+ * `Effect.logWarning` with a `Logger`, the house pattern `caddy/config-format-warning.test.ts`
+ * established for asserting on a warning without turning it into a refusal.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Logger from 'effect/Logger';
+import { warnOnDroppedRules } from './alert-rule-group-drop-warning.ts';
+import { PATH, liveJson, liveRule, props } from './alert-rule-group-fixtures.ts';
+import { handlers, spec } from './alert-rule-group.ts';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { grafanaOperations } from './resource.ts';
+
+/** Runs `effect` and returns its result plus every `Effect.logWarning` line it emitted. */
+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('warnOnDroppedRules — pure', () => {
+  test('logs nothing when every live rule is declared', async () => {
+    const { warnings } = await withWarnings(
+      warnOnDroppedRules('infra', 'default', new Set(['high-cpu']), [
+        { title: 'High CPU', uid: 'high-cpu' },
+      ]) as Effect.Effect<void, unknown, never>,
+    );
+    expect(warnings).toEqual([]);
+  });
+
+  test('names a dropped rule by title and uid', async () => {
+    const { warnings } = await withWarnings(
+      warnOnDroppedRules('infra', 'default', new Set(['high-cpu']), [
+        { title: 'High CPU', uid: 'high-cpu' },
+        { title: 'Low Disk', uid: 'low-disk' },
+      ]) as Effect.Effect<void, unknown, never>,
+    );
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('infra/default');
+    expect(warnings[0]).toContain('REMOVES 1 rule');
+    expect(warnings[0]).toContain('Low Disk (low-disk)');
+    expect(warnings[0]).not.toContain('High CPU');
+  });
+
+  test('a rule with no uid at all is never named — cannot express "keep it" anyway', async () => {
+    const { warnings } = await withWarnings(
+      warnOnDroppedRules('infra', 'default', new Set(), [{ title: 'Mystery' }]) as Effect.Effect<
+        void,
+        unknown,
+        never
+      >,
+    );
+    expect(warnings).toEqual([]);
+  });
+});
+
+describe('wired into diff and update', () => {
+  test('diff logs the dropped-rule warning before anything is written', async () => {
+    const extra = { ...liveRule, title: 'Low Disk', uid: 'low-disk' };
+    const withExtra = { ...liveJson, rules: [liveRule, 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: { folderUid: 'infra', group: 'default', interval: 60, rules: [] },
+        })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))) as Effect.Effect<
+        unknown,
+        unknown,
+        never
+      >,
+    );
+    expect(value).toEqual({ action: 'update' });
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('Low Disk (low-disk)');
+  });
+
+  test('update logs the same warning right before the PUT that would drop the rule', async () => {
+    const extra = { ...liveRule, title: 'Low Disk', uid: 'low-disk' };
+    const withExtra = { ...liveJson, rules: [liveRule, 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({ ...props, interval: 120 })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))) as Effect.Effect<
+        unknown,
+        unknown,
+        never
+      >,
+    );
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('Low Disk (low-disk)');
+  });
+});

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

@@ -0,0 +1,41 @@
+/**
+ * The warning `Grafana.AlertRuleGroup` logs when a whole-group PUT would silently drop a live rule
+ * the declaration never mentions — flagged by an adversarial review of this PR: a human adding a
+ * rule in the Grafana UI minutes before a deploy (ordinary, writable provenance — nothing foreign
+ * to refuse on) would otherwise be removed with no visible reason, `diff` only ever saying
+ * "update". `Grafana.AlertRuleGroup` is still the group as the unit BY DESIGN (that file's own
+ * header) — this does not refuse the write, only makes the loss visible.
+ *
+ * ★ `Effect.logWarning`, NEVER A REFUSAL — mirrors the house pattern `proxmox/unreadable-read.ts`'s
+ *   `unreadableWarning` established. Alchemy's `Diff` type is exactly `NoopDiff | UpdateDiff |
+ *   ReplaceDiff` (no fourth action to carry "update, but lossy" through to `bun run plan`'s printed
+ *   action), and refusing here would contradict "the group is the unit": a whole-group replacement
+ *   dropping an out-of-band rule is EXPECTED behavior for this resource, not an error condition —
+ *   only a silent one worth surfacing loudly.
+ *
+ * ★ NO IMPORT OF `AlertRuleGroupProps` — deliberately primitive arguments (`folderUid`/`group`/a
+ *   plain `Set` of declared uids) rather than the whole props object, so this file has no
+ *   dependency back on `alert-rule-group.ts` and can be unit-tested with plain data.
+ */
+import * as Effect from 'effect/Effect';
+
+export const warnOnDroppedRules = (
+  folderUid: string,
+  group: string,
+  declaredUids: ReadonlySet<string>,
+  liveRules: ReadonlyArray<{ readonly uid?: unknown; readonly title?: unknown }> | undefined,
+): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    const dropped = (liveRules ?? [])
+      .filter((rule): rule is { title?: unknown; uid: string } => typeof rule.uid === 'string')
+      .filter((rule) => !declaredUids.has(rule.uid));
+    if (dropped.length === 0) return;
+    const names = dropped
+      .map((rule) => `${typeof rule.title === 'string' ? rule.title : '(untitled)'} (${rule.uid})`)
+      .join(', ');
+    yield* Effect.logWarning(
+      `Grafana.AlertRuleGroup ${folderUid}/${group}: this update REMOVES ${dropped.length} ` +
+        `rule(s) not in the declaration: ${names}. Whole-group replacement is by design — add ` +
+        `them to the declaration to keep them, or give them their own group.`,
+    );
+  });

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

@@ -0,0 +1,46 @@
+/**
+ * Shared fixtures for `alert-rule-group.test.ts`/`alert-rule-group-provenance.test.ts` — 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/folder/infra/rule-groups/default';
+
+export const liveRule = {
+  condition: 'A',
+  data: [{ refId: 'A' }],
+  execErrState: 'Alerting',
+  folderUID: 'infra',
+  for: '5m',
+  id: 7,
+  noDataState: 'NoData',
+  orgID: 1,
+  provenance: 'api',
+  ruleGroup: 'default',
+  title: 'High CPU',
+  uid: 'high-cpu',
+  updated: '2026-09-24T00:00:00Z',
+};
+
+export const liveJson = {
+  folderUid: 'infra',
+  interval: 60,
+  rules: [liveRule],
+  title: 'default',
+};
+
+export const ruleInput = {
+  condition: 'A',
+  data: [{ refId: 'A' }],
+  execErrState: 'Alerting',
+  for: '5m',
+  noDataState: 'NoData',
+  title: 'High CPU',
+  uid: 'high-cpu',
+};
+
+export const props = {
+  folderUid: 'infra',
+  group: 'default',
+  interval: 60,
+  rules: [ruleInput],
+};

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

@@ -0,0 +1,75 @@
+/**
+ * `normalizeRule`/`toWireRule` in isolation — no SDK, no fake, no Effect. Mirrors
+ * `dashboard-model.test.ts`. Proves the volatile fields (`id`, `updated`, `provenance`) are
+ * stripped and `folderUID`/`ruleGroup`/`orgID` are forced to canonical values regardless of what a
+ * live-read rule embeds, which is what makes a pasted export and a freshly-read live rule compare
+ * equal in `alert-rule-group.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import { normalizeRule, toWireRule } from './alert-rule-group-model.ts';
+
+describe('normalizeRule', () => {
+  test('strips id, updated and provenance', () => {
+    const rule = {
+      condition: 'A',
+      id: 42,
+      provenance: 'api',
+      title: 'High CPU',
+      updated: '2026-09-24T00:00:00Z',
+    };
+    expect(normalizeRule(rule, 'infra', 'default')).toEqual({
+      condition: 'A',
+      title: 'High CPU',
+      folderUID: 'infra',
+      ruleGroup: 'default',
+      orgID: 1,
+    });
+  });
+
+  test('forces folderUID/ruleGroup/orgID to the canonical values, overwriting stale ones', () => {
+    const rule = { folderUID: 'stale', orgID: 99, ruleGroup: 'stale-group', title: 'High CPU' };
+    expect(normalizeRule(rule, 'infra', 'default')).toEqual({
+      title: 'High CPU',
+      folderUID: 'infra',
+      ruleGroup: 'default',
+      orgID: 1,
+    });
+  });
+
+  test('a declared rule and a live rule that only disagree on volatile fields normalize equal', () => {
+    const declared = { condition: 'A', title: 'High CPU' };
+    const live = {
+      condition: 'A',
+      folderUID: 'infra',
+      id: 7,
+      orgID: 1,
+      provenance: 'api',
+      ruleGroup: 'default',
+      title: 'High CPU',
+      updated: '2026-09-24T00:00:00Z',
+    };
+    expect(normalizeRule(declared, 'infra', 'default')).toEqual(
+      normalizeRule(live, 'infra', 'default'),
+    );
+  });
+
+  test('leaves a real content change genuinely different', () => {
+    const declared = { title: 'High CPU v2' };
+    const live = { title: 'High CPU' };
+    expect(normalizeRule(declared, 'infra', 'default')).not.toEqual(
+      normalizeRule(live, 'infra', 'default'),
+    );
+  });
+});
+
+describe('toWireRule', () => {
+  test('fills in the group-derived fields, orgID defaulted to 1', () => {
+    const rule = { condition: 'A', title: 'High CPU', uid: 'high-cpu' } as never;
+    expect(toWireRule(rule, 'infra', 'default')).toMatchObject({
+      folderUID: 'infra',
+      orgID: 1,
+      ruleGroup: 'default',
+      uid: 'high-cpu',
+    });
+  });
+});

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