@homeflare/alchemy 0.33.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

@@ -0,0 +1,147 @@
+# Grafana alerting provisioning — `@homeflare/alchemy/grafana`
+
+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. **`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
+[grafana.md](./grafana.md#the-sdk-gap--history-and-what-shipped-on-top-of-the-fix) already
+unblocked (`skipDeprecated` patched false for the 32 alerting-provisioning-write operations). No
+live call was made writing this PR — see "Measured vs inferred" below.
+
+## Foreign-provenance refusal — shared, `alerting-provenance.ts`
+
+Every resource in this family reads a `provenance` string off what Grafana returns and refuses to
+write when it names an owner other than this API. **Measured against Grafana's own source**
+(`pkg/services/ngalert/models`, not re-fetched live): `ProvenanceNone = ""` (unclaimed),
+`ProvenanceAPI = "api"` (this API's own writes), `ProvenanceFile = "file"`,
+`ProvenanceConvertedPrometheus = "converted_prometheus"`. `alerting-provenance.ts`'s
+`WRITABLE_PROVENANCES` is an **allowlist** of `{"", "api"}`, not a denylist of the two named
+foreign values — an unnamed future provenance source refuses by default, the safer failure
+direction for a control-plane write. Corroborated by Grafana's docs
+(grafana.com/docs/grafana/v13.1/alerting/set-up/provision-alerting-resources/http-api-provisioning/),
+whose example payloads show exactly `"api"` and `"file"`.
+
+This is **defense in depth, not the only guard**: Grafana's alerting provisioning API also enforces
+this server-side (grafana/grafana#103597, "Unable to delete file provisioned alert rules," reports
+the block firing) — unlike the classic folder/dashboard write API `provisioned.ts` guards, which
+has no such server-side check at all. `create` is never at risk for any resource below: it only
+runs when `fetchLive` already found nothing.
+
+⛔ **A missing `provenance` field is treated as foreign, never as `ProvenanceNone` — fixed after an
+adversarial review of this PR found the guard failing OPEN.** The first version mapped
+`live.provenance ?? ''`, collapsing "the field is absent" into "the field is explicitly empty" —
+both writable. `isForeignProvenance`/`refuseIfForeignProvenance` now keep `undefined` as its own
+value: only a field Grafana explicitly reports as `""` or `"api"` is writable. Every resource below
+has a test pinning all three cases (missing refuses, explicit `""` is writable, `"file"` refuses).
+
+`X-Disable-Provenance` is **never set** by any resource in this family. Every create/update
+therefore leaves the object at `provenance: "api"` — Grafana's own default for an API write, which
+blocks UI edits afterward. Deliberate: an object this family declares should stay owned by the
+declaration, the "one owner per resource" posture `provisioned.ts` already established for
+folders/dashboards.
+
+## `Grafana.ContactPoint`
+
+```ts
+import { GrafanaContactPoint, grafanaProviders } from '@homeflare/alchemy/grafana';
+
+export class OncallSlack extends GrafanaContactPoint('oncall-slack', {
+  uid: 'slack-oncall',
+  name: 'On-call Slack',
+  type: 'slack',
+  settings: { recipient: '#oncall' },
+  secureSettingsRefs: { url: 'GRAFANA_SLACK_WEBHOOK_URL_ENV' },
+}) {}
+```
+
+- **No by-uid GET route exists** — measured: `services/grafana.ts` has only `routeGetContactpoints`
+  (list, optional `name` filter) and its export sibling. Narrowing that GET to the declared `name`
+  is not safe either: `name` is a renameable grouping label (Grafana's own doc: "used as grouping
+  key in the UI"), so `fetchLive` lists every contact point unfiltered and matches `uid`
+  client-side — the same ambiguity `resource.ts`'s header and netbox's `soleMatch` name.
+- **Secrets never appear as a literal prop (S25).** A secure `settings` key (a webhook URL, an API
+  key, …) is named in `secureSettingsRefs` (field -> env var NAME), resolved fresh inside
+  `create`/`update`'s own effect and merged into `settings` only there. Grafana's plain GET has no
+  `decrypt` option (only the export route does, org-admin only) — a secure key always comes back
+  redacted, so `matches` excludes every `secureSettingsRefs` key from comparison entirely, even if
+  `settings` also names it with a stale placeholder value (`contact-point.test.ts`'s own test for
+  this). Non-secret `settings` compares via `subset-match.ts`'s `declaredContentMatches`, tolerating
+  a default Grafana injects that the declaration never mentioned.
+
+## `Grafana.MuteTiming`
+
+```ts
+import { GrafanaMuteTiming, grafanaProviders } from '@homeflare/alchemy/grafana';
+
+export class Weekends extends GrafanaMuteTiming('weekends-mute', {
+  name: 'weekends',
+  timeIntervals: [{ weekdays: ['saturday', 'sunday'] }],
+}) {}
+```
+
+- ⚠️ **A genuine, surprising SDK finding, worth restating here.** The generated `MuteTimeInterval`
+  type declares only `name`/`time_intervals` — no `provenance`, no `version`, unlike every other
+  type this family reads. A first pass assumed the data was gone; empirically it is not:
+  `@distilled.cloud/core`'s response decoding is `JSON.parse` + a key-rename pass, never a strict
+  schema decode — any key a type doesn't model passes through **verbatim** (`protocol-http.ts`'s
+  `mapKeys`, confirmed by calling the real operation with a `provenance`/`version`-bearing response
+  through this family's own fake-Grafana harness). `mute-timing.ts` reads both through a small
+  local `& { provenance?: string; version?: string }` intersection rather than the SDK's own type.
+  The same passthrough applies outbound: `timeIntervals` is typed as an opaque
+  `Record<string, unknown>[]`, not the SDK's own too-narrow `TimeInterval` (which is missing the
+  real Alertmanager fields — `weekdays`/`times`/`months`/`days_of_month`/`years`/`location` — for
+  the same reason), and a real weekday/time entry reaches the wire unchanged. Tracked as a real SDK
+  type-generation gap in `docs/upstream-conformance.md` (the S22 fix route) — not a data-loss gap.
+- **`version` rides on `destroy`, not `update`** — measured: `RouteDeleteMuteTimingRequest.version`
+  exists for optimistic concurrency; `RoutePutMuteTimingRequest` has no `version` field at all, a
+  real Grafana API asymmetry between the two write routes.
+
+## `Grafana.MessageTemplate`
+
+```ts
+import { GrafanaMessageTemplate, grafanaProviders } from '@homeflare/alchemy/grafana';
+
+export class SlackBody extends GrafanaMessageTemplate('slack-body-template', {
+  name: 'slack-body',
+  template: '{{ define "slack-body" }}...{{ end }}',
+}) {}
+```
+
+- **Create and update are the same wire call** — measured: no `routePostTemplate` exists, only
+  `routePutTemplate` (`PUT /v1/provisioning/templates/{name}`, upsert by name). Kept as two spec
+  functions anyway so the shared engine's `diff` reports a content change as `update`, not the
+  `replace` it shows for any resource whose `spec.update` is `undefined` (`resource.ts`).
+  `version` rides on `update` when Grafana reports one, for optimistic concurrency.
+
+## Tests
+
+Each resource's `*.test.ts` uses the family's `fake-grafana.ts` harness (the real distilled
+protocol, only wire responses faked) and proves: a GET never carries a body; a foreign-provenance
+object — an explicit `"file"` OR a MISSING `provenance` field — refuses update/destroy with no write
+sent, while an explicit `""` is writable; a transient failure (401/403) propagates rather than
+folding to absent; an unchanged declaration is a noop despite Grafana injecting an extra field the
+declaration never mentioned; and — `Grafana.ContactPoint` only — a secret value never appears in the
+attributes a real `reconcile` returns (driven end to end through create and the read-back
+`resource.ts` always does, not just asserted absent from a declaration that never held it).
+`Grafana.ContactPoint`'s tests are split three ways (`contact-point.test.ts`/`-secrets.test.ts`/
+`-provenance.test.ts`, sharing fixtures from `contact-point-fixtures.ts`) to stay under the house's
+250-line file cap.
+
+## Measured vs inferred (no live call in this PR)
+
+**Measured**, against the SDK's generated types and/or Grafana's own docs: the provenance enum and
+its values; the absence of a by-uid contact-point GET; the create/update PUT-only shape for
+templates and the `version`-on-destroy-only shape for mute timings; the response-decode
+verbatim-passthrough behavior (traced into `@distilled.cloud/core`'s own source and confirmed
+against the real operation through this family's fake-Grafana harness — as close to "measured" as
+this PR gets without a live Grafana instance). **Inferred, not measured live:** whether Grafana's
+real server-side provenance enforcement covers every write route this family calls the same way (only
+the alert-rule-deletion case is corroborated by a filed issue); whether a genuine mute-timing
+`version` conflict on delete surfaces as a typed `Conflict` in practice.

package/docs/grafana.md

@@ -126,8 +126,11 @@ export class TeslaMateDatasource extends GrafanaDatasource('teslamate-datasource
 
 - **`Grafana.Folder` and `Grafana.Dashboard` ship** — see
   [grafana-folder-dashboard.md](./grafana-folder-dashboard.md), not repeated here.
-- **Alert rules, contact points, notification policies, mute timings.** The SDK-level blocker is
-  fixed (above); no house `Resource` calls these operations yet — follow-up work, not blocked on
-  anything.
+- **`Grafana.ContactPoint`, `Grafana.MuteTiming` and `Grafana.MessageTemplate` ship** — see
+  [grafana-alerting.md](./grafana-alerting.md), not repeated here.
+- **`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

@@ -261,13 +261,47 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
     `@homeflare/distilled-netbox` established. `Grafana.Datasource`'s props/attributes/generated code
     are unchanged (diffed operation-by-operation against the prior commit).
 
-    ✅ **`Grafana.Folder`/`Grafana.Dashboard` shipped** (this PR, on top of the same
+    ✅ **`Grafana.Folder`/`Grafana.Dashboard` shipped** (PR 245, on top of the same
     `@distilled.cloud/grafana` operations S22 unblocked) — the uid-required doctrine, the
     provisioned-object refusal, the parentUid-is-create-only refusal and the volatile-field
     normalization that makes an unchanged dashboard a true noop are all in
-    [grafana-folder-dashboard.md](./grafana-folder-dashboard.md), not repeated here. **Still open,
-    and not this PR's scope:** `Grafana.AlertRule`/`ContactPoint`/`NotificationPolicy`/`MuteTiming`
-    — follow-up PRs, no longer blocked on the SDK.
+    [grafana-folder-dashboard.md](./grafana-folder-dashboard.md), not repeated here.
+
+    ✅ **`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
+    `Grafana.Datasource`) are both new shared building blocks — full detail:
+    [grafana-alerting.md](./grafana-alerting.md).
+    - 🔴 **New SDK gap found, not fixed here:** `MuteTimeInterval`'s generated type has no
+      `provenance`/`version` fields, and the SDK's own `TimeInterval` type is missing the real
+      Alertmanager time-interval fields (`weekdays`/`times`/`months`/etc.) entirely — Grafana's real
+      API returns and accepts all of them. NOT a data-loss gap: `@distilled.cloud/core`'s response
+      decoding never runs a strict schema decode (`JSON.parse` + a key-rename pass that leaves any
+      unmodeled key verbatim — `protocol-http.ts`'s `mapKeys`, confirmed by driving the real
+      operation through this family's fake-Grafana harness), so `mute-timing.ts` reads/writes both
+      through a locally-widened type instead. Same S22 fix route as the other named gaps
+      (regenerate the distilled clone's spec, copy forward) — not attempted here, since
+      `packages/distilled-grafana/src/` is vendored and never hand-edited.
+    - Measured, read-only, same census as PR 245's: `teslamate-grafana` has no contact points, mute
+      timings or templates configured either (consistent with the alerting-provisioning gap having
+      been real, not merely unexploited).
+
+    ✅ **`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.33.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',
+    });
+  });
+});