@homeflare/alchemy 0.34.0 → 0.36.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,10 +3,13 @@
 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
-   contact points, mute timings and templates by name).
+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. **`Grafana.NotificationPolicy`** — [grafana-notification-policy.md](./grafana-notification-policy.md),
+   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
 [grafana.md](./grafana.md#the-sdk-gap--history-and-what-shipped-on-top-of-the-fix) already

package/docs/grafana-notification-policy.md

@@ -0,0 +1,127 @@
+# `Grafana.NotificationPolicy` — `@homeflare/alchemy/grafana`
+
+Third and last of the stacked PRs bringing Grafana alerting provisioning under Alchemy
+([grafana-alerting.md](./grafana-alerting.md): `Grafana.ContactPoint`/`Grafana.MuteTiming`/
+`Grafana.MessageTemplate`; [grafana-alerting-rules.md](./grafana-alerting-rules.md):
+`Grafana.AlertRuleGroup`). Branched fresh off `main` after that PR merged. No live call was made
+writing this PR.
+
+## A singleton — adopt and update only
+
+`GET`/`PUT /v1/provisioning/policies` always address the one tree an instance has; there is no path
+parameter. MEASURED: `RouteGetPolicyTreeError` is `Forbidden | GrafanaOpError` — no `NotFound` case
+at all, so `fetchLive` never returns `undefined`. `reconcile`'s `before === undefined` branch
+(`resource.ts`) is therefore dead code for this resource: there is no create in the sense every
+other resource in this family has, and `spec.create` exists only because `GrafanaSpec.create` is a
+required field on the shared type — implemented as the same `PUT` `update` sends, defensively,
+never actually reached.
+
+## Two gates before `routeResetPolicyTree` ever runs
+
+`destroy` never calls `routeResetPolicyTree` unless `allowReset: true` is explicitly declared — a
+gate independent of Alchemy's own removal policy:
+
+1. **`defaultRemovalPolicy: 'retain'`** — the same convention every multi-object-cascade resource
+   in this family uses (`Grafana.Folder`, `Grafana.AlertRuleGroup`, every `Bao.*`). Alchemy's own
+   engine never calls this resource's `delete` handler at all unless a stack opts in with
+   `.pipe(RemovalPolicy.destroy())`.
+2. **`allowReset` (a prop, not a stack-level policy)** — even a stack that HAS opted into destroy
+   at the Alchemy level still needs this resource's own explicit `allowReset: true` before
+   `destroy` will actually reset. Without it, `destroy` logs a warning and returns — retained.
+
+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, for the WHOLE instance, not one object. A test
+(`notification-policy-refusals.test.ts`) proves `destroy` sends no `DELETE` without `allowReset`,
+and a foreign-provenance tree still refuses `destroy` even WITH `allowReset: true`.
+
+## The tree is opaque `Record<string, unknown>`
+
+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. This family's own measured passthrough behavior
+(`mute-timing.ts`'s file header) means an opaque pass-through round-trips correctly regardless.
+
+## Route order is significant
+
+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, proven by a test that declares the same two
+routes reversed and asserts a mismatch.
+
+## Foreign-provenance refusal
+
+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 — it is
+unreachable (above).
+
+## Grafana-injected defaults — tolerated the `declaredContentMatches` way
+
+`matches()` runs the (`provenance`-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 (a default
+`group_wait`/`group_interval`/`repeat_interval`/`group_by: []` Grafana injects 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 — the documented, conservative default
+every unmeasured value shape in this family takes.
+
+## Dropped-route warning — accepted, never silent
+
+Same fix kit PR 254 made for `Grafana.AlertRuleGroup`, applied here: a whole-tree `PUT` REPLACES
+every route, so a nested route added out-of-band is removed with no error and no distinct `Diff`
+action to report it under. `notification-policy-drop-warning.ts`'s `warnOnDroppedRoutes` logs every
+dropped route by receiver and dotted-index path, called from both a local reimplementation of
+`diff` and from `update` itself — mirrors `alert-rule-group-drop-warning.ts` exactly, including
+being a LOCAL reimplementation of `resource.ts`'s generic `diff` rather than a wrap of it (no seam
+in the generic version for this side effect without fetching live twice).
+
+⚠️ **Identity is structural, not a stable key** — Grafana's policy routes have no id/uid.
+`FlatRoute.key` (`notification-policy-model.ts`) is the chain of ancestor own-fields from the root
+down to a node, `\0`-joined: two nodes are "the same" only under the identical lineage of parents,
+which makes an identical route under a DIFFERENT parent correctly distinct while staying
+order-insensitive among siblings (a shared parent contributes the same key to every child
+regardless of index) — reordering the same routes logs nothing, only genuine removal does.
+
+⛔ **Fixed after an adversarial review of this PR: the first version's identity collided across the
+WHOLE TREE, not just among siblings.** A plain `Set` of every node's own-fields JSON meant a
+duplicate route added anywhere (e.g. a second `severity=warning -> slack` alongside an
+already-declared one) matched the existing `Set` entry and went unwarned, even though the `PUT`
+still drops it — worse than the "siblings only" limitation the original comment claimed. Every key
+is now counted as a MULTISET (declared count vs. live count) rather than checked for membership: a
+key is "dropped" only for the amount its live count exceeds its declared count, so N identical live
+occurrences under the same parent are dropped only past however many the declaration itself
+repeats — proven by four tests: a duplicate added live warns; a plain sibling reorder doesn't; an
+identical route under a different, undeclared parent still warns (distinct lineage); and two
+declared duplicates against two live duplicates warns nothing (counts match).
+
+## Example
+
+```ts
+import { GrafanaNotificationPolicy, grafanaProviders } from '@homeflare/alchemy/grafana';
+
+export class Policy extends GrafanaNotificationPolicy('estate-policy', {
+  route: {
+    receiver: 'default-receiver',
+    group_by: ['alertname'],
+    routes: [
+      { receiver: 'pagerduty', matchers: ['severity=critical'] },
+      { receiver: 'slack', matchers: ['severity=warning'] },
+    ],
+  },
+}) {}
+```
+
+## Tests
+
+`notification-policy.test.ts` (fetchLive/reconcile/order), `notification-policy-model.test.ts`
+(pure `normalizeRoute`/`flattenRoutes`), `notification-policy-refusals.test.ts` (provenance +
+reset-gate) and `notification-policy-drop-warning.test.ts` — split four ways to stay under the
+house's 250-line file cap, sharing fixtures from `notification-policy-fixtures.ts`. Prove: a GET
+never carries a body; reconcile never sends a create-shaped write; a foreign-provenance tree
+(explicit `"file"` or MISSING) refuses update while an explicit `""` is writable; `destroy` never
+resets without `allowReset: true`, and still refuses a foreign tree even with it; reordering routes
+shows `update`; a live route the declaration doesn't mention is named in a logged warning from both
+`diff` and `update`, while a plain reorder logs nothing; and — the multiset fix — a duplicate route
+added live warns while an identical declared/live duplicate pair doesn't, and an identical route
+under a different, undeclared parent is still correctly reported as dropped.

package/docs/grafana.md

@@ -122,13 +122,19 @@ export class TeslaMateDatasource extends GrafanaDatasource('teslamate-datasource
 // …then provide `grafanaProviders({ baseUrl, tokenEnv })` alongside the stack's other providers.
 ```
 
+## Family status
+
+Every alerting-provisioning object this family set out to cover now ships:
+
+- **`Grafana.Folder` and `Grafana.Dashboard`** — see
+  [grafana-folder-dashboard.md](./grafana-folder-dashboard.md).
+- **`Grafana.ContactPoint`, `Grafana.MuteTiming` and `Grafana.MessageTemplate`** — see
+  [grafana-alerting.md](./grafana-alerting.md).
+- **`Grafana.AlertRuleGroup`** — see [grafana-alerting-rules.md](./grafana-alerting-rules.md).
+- **`Grafana.NotificationPolicy`** — the singleton policy tree, last on purpose (it references the
+  others by name) — see [grafana-notification-policy.md](./grafana-notification-policy.md).
+
 ## Not covered
 
-- **`Grafana.Folder` and `Grafana.Dashboard` ship** — see
-  [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.
 - **`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,33 @@ 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** (kit PR 254, 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. A whole-group
+    write silently dropping a live rule not in the declaration (found by that PR's own adversarial
+    review) is now warned about loudly rather than silent, never a refusal. Full detail:
+    [grafana-alerting-rules.md](./grafana-alerting-rules.md).
+
+    ✅ **`Grafana.NotificationPolicy` shipped** (this PR, third and last of the stacked PRs,
+    branched fresh off `main` after PR 254 merged): a SINGLETON — `fetchLive` never returns
+    `undefined` (`RouteGetPolicyTreeError` has no `NotFound` case), so this resource has no create
+    or delete in the sense every sibling resource does, only adopt-and-update. `destroy` never
+    calls `routeResetPolicyTree` without an explicit `allowReset: true` prop, a gate independent of
+    (and in addition to) `defaultRemovalPolicy: 'retain'` — two gates, since resetting wipes the
+    WHOLE instance's routing back to Grafana's bare default, not one object. The tree is opaque
+    `Record<string, unknown>` (same reasoning as `mute-timing.ts`'s `timeIntervals` — Grafana's
+    matcher-expression types are complex unions this family does not hand-model), compared via
+    `subset-match.ts` for Grafana-injected-default tolerance, with route order significant. The
+    same dropped-item warning kit PR 254 introduced for rule groups is mirrored here for dropped
+    routes. Full detail: [grafana-notification-policy.md](./grafana-notification-policy.md).
+
+    This completes the alerting-provisioning family this project set out to cover.
     - ⛔ **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.36.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',
+    });
+  });
+});