@homeflare/alchemy 0.32.0 → 0.34.0

package/docs/grafana-folder-dashboard.md

@@ -0,0 +1,145 @@
+# `Grafana.Folder` and `Grafana.Dashboard` — `@homeflare/alchemy/grafana`
+
+Built 2026-09-24 on the same `@distilled.cloud/grafana` (aliased onto
+`@homeflare/distilled-grafana@0.2.0`) operations that fixed the SDK gap
+[grafana.md](./grafana.md#the-sdk-gap--history-and-what-shipped-on-top-of-the-fix) recorded:
+`createFolder`/`getFolderByUID`/`updateFolder`/`deleteFolder`/`getFolders` and
+`postDashboard`/`getDashboard`/`deleteDashboard`, plus a typed `PreconditionFailed` (412) for
+dashboard version conflicts. No live call was made writing this PR — see "Measured vs inferred"
+below for exactly which claims that limits.
+
+## Both follow `Grafana.Datasource`'s doctrine
+
+Same file shape (`resource.ts`'s shared `GrafanaSpec`/`grafanaOperations`/`grafanaHandlers`), same
+credentials layer (`grafanaProviders(target)`), same **uid required, never generated** reasoning —
+`getFolderByUID`/`updateFolder`/`deleteFolder` and `getDashboard`/`postDashboard`/`deleteDashboard`
+are all UID-keyed, and neither `getFolders` nor a dashboard list endpoint takes a per-uid filter,
+so locating an object this resource didn't create would mean listing everything and matching by
+name — the ambiguity requiring `uid` up front sidesteps.
+
+## `Grafana.Folder`
+
+```ts
+import { GrafanaFolder, grafanaProviders } from '@homeflare/alchemy/grafana';
+
+export class Infra extends GrafanaFolder('infra-folder', {
+  uid: 'infra',
+  title: 'Infrastructure',
+}) {}
+```
+
+- **`description` is write-only** — MEASURED against the SDK's generated types: `Folder` (the GET
+  response) has no `description` field at all, though `CreateFolderRequest`/`UpdateFolderRequest`
+  both accept one. Sent on every create/update that declares it; never compared, the same
+  treatment `Grafana.Datasource` gives `secureJsonDataRefs` for the same reason (nothing to diff
+  against).
+- **Nesting (`parentUid`) is create-only** — MEASURED: `UpdateFolderRequest` has no `parentUid`
+  field (`folder_uid`, `description`, `overwrite`, `title`, `version` only). A declaration whose
+  `parentUid` no longer matches the live folder REFUSES with `GrafanaFolderReparentError` rather
+  than silently doing nothing or deleting-and-recreating under the new parent (which — next
+  bullet — takes every dashboard and alert rule in the folder with it). Move a folder by hand in
+  Grafana, then update the declaration.
+- **Delete defaults to `retain`** — `deleteFolder`'s own operation description says it deletes
+  "all dashboards (and their alerts) stored in the folder... cannot be reverted... also deletes
+  all the subfolders." That is the multi-object cascade `openbao/mount.ts` guards with
+  `defaultRemovalPolicy: 'retain'`, verified there against Alchemy's own `Apply.ts` (not
+  re-verified here; same engine, same option — see `folder.ts`'s header). A stack that wants the
+  cascade opts in with `.pipe(RemovalPolicy.destroy())`; `destroy` still implements the real
+  `DELETE` in full either way (S11). `Grafana.Dashboard` does **not** default to retain — see its
+  own section below.
+
+## `Grafana.Dashboard`
+
+```ts
+import { GrafanaDashboard, grafanaProviders } from '@homeflare/alchemy/grafana';
+
+export class FleetOverview extends GrafanaDashboard('fleet-overview-dashboard', {
+  uid: 'fleet-overview',
+  folderUid: 'infra',
+  dashboard: {
+    title: 'Fleet Overview',
+    panels: [/* … exported straight from Grafana's own "Export as JSON" … */],
+  },
+}) {}
+```
+
+- **The declared content is the dashboard JSON model** — the same shape Grafana's own "Export as
+  JSON" produces. `dashboard-model.ts`'s `normalizeModel` strips `id`/`version`/`iteration`
+  (Grafana-managed, injected/incremented on every save) and forces `uid` to this resource's own
+  value regardless of where — or whether — the source model carried one, before ANY comparison.
+  That is what makes a pasted export (which always embeds the OLD live uid) and a freshly-read
+  live model compare equal, and what makes a no-change plan a true noop despite those fields
+  moving on every live save.
+- **Array order is significant, and nothing here needs a `sortedSet`** — `panels` (screen layout
+  via its own `gridPos`, but the array order also drives Grafana's internal panel indexing and
+  `repeat` behavior) and each panel's `targets` (query execution/legend order) are compared
+  positionally, never reordered. Nothing in a dashboard model is a genuinely unordered SET the way
+  UniFi's `trustedDhcpServerIpAddresses` is (`unifi/network-form.ts`'s `sortedSet`) — this family
+  has no field that needs one. `schemaVersion` is deliberately left comparing as-is — NOT MEASURED
+  whether Grafana rewrites it on a plain save, so normalizing it away on a guess risked hiding a
+  genuine schema mismatch instead of a false diff; see `dashboard-model.ts` for the exact reasoning
+  and what evidence would justify adding it to the volatile-field list.
+- **`matches` compares "is the declaration a subset of what is live", not plain equality** —
+  `dashboard-model.ts`'s `declaredContentMatches`, added after an adversarial review of this PR
+  found plain structural equality (`alchemy/Diff`'s `deepEqual`, used in an earlier version of this
+  PR) made an ordinary, never-edited dashboard show `update` FOREVER: Grafana's own schema
+  migration on save decorates any panel or target whose `datasource` is absent with an explicit
+  `{type, uid}` reference — documented Grafana behavior, not re-measured against a live instance in
+  this PR. A declared panel that never sets `datasource` therefore read back with that field
+  populated, disagreed with the declaration, got written back undecorated, and got redecorated
+  again — non-convergent. `declaredContentMatches` instead asks only whether every field the
+  DECLARATION mentions, at any depth, still matches what is live; `live` may carry additional
+  fields Grafana injected that the declaration never mentioned. Real content drift (a field the
+  declaration DOES mention changing, or vanishing) is still caught exactly as before. The
+  trade-off, deliberate: **removing** a field from the declaration can no longer force Grafana to
+  drop a value it — or a previous declaration — set; only an explicit replacement value changes
+  one. This is the same "undeclared means don't care, never means force-to-default" convention this
+  whole kit already uses for a plain optional prop, now applied inside the JSON model too.
+- **412 version conflicts fail loudly, never overwritten blindly.** `update` injects the version
+  this resource just read (from the same `fetchLive` call `reconcile` already made) into the model
+  it sends, and `overwrite` is never set. If Grafana's own check still fails — someone saved in the
+  gap between that read and this write — `PreconditionFailed` is left uncaught: the whole reconcile
+  fails and nothing is written. The next `plan`/`deploy` re-reads the new live version fresh; there
+  is no separate retry loop in this file, because that next run already is the re-read.
+- **No retain default**, unlike `Grafana.Folder`. Deleting one dashboard is a single-object blast
+  radius — the same class `Grafana.Datasource` already accepts without a retain guard, not
+  `Grafana.Folder`'s multi-object cascade.
+
+## Provisioned objects — refused for writes, adoption is fine
+
+A folder or dashboard that a provisioning FILE manages (rather than this API) carries a live
+signal — `Folder.managedBy` (non-empty) and `DashboardMeta.provisioned`/`provisionedExternalId` —
+that `update`/`destroy` check before ever calling the SDK; `GrafanaProvisionedObjectError` names
+the owning file when Grafana reports one (dashboards only — a folder's `managedBy` value is
+reported as-is, since the SDK does not separately expose a folder's owning file). `create` is
+never at risk: it only runs when `fetchLive` already found nothing.
+
+`matches` still compares structurally regardless of provisioned status, so a mismatched
+declaration against a provisioned object shows `update` in a plan — never a silent, permanently
+hidden noop — and only fails, loudly, when reconcile actually tries to write. A declaration that
+already matches what is live never reaches `update`/`destroy` at all (the shared engine's
+observe-before-write path), so **adopting a provisioned object read-only is safe.**
+
+⚠️ **Measured vs inferred (no live call in this PR).** `DashboardMeta.provisioned`/
+`provisionedExternalId` are exactly the fields Grafana's classic dashboard-read response types for
+this purpose — high confidence, standard shape. `Folder.managedBy` is INFERRED from the SDK's
+schema only: no live instance in this house currently has a file-provisioned FOLDER to read against
+(`teslamate-grafana` has none at all — see grafana.md). Treating any non-empty `managedBy` as
+provisioned, rather than matching specific string values that were never observed live, is the
+conservative reading; confirm against a real provisioned folder before relying on the exact value in
+an error message. The panel/target `datasource` auto-decoration `declaredContentMatches` (above)
+exists to tolerate is documented Grafana schema-migration behavior, also not re-measured live in
+this PR. And `updateFolder`'s `version` field — sent optimistically for concurrency — carries the
+SDK's own caveat "only used by the legacy folder implementation"; whether Grafana's newer
+unified-storage folder backend honors it at all is unverified (`folder.ts`'s `update`).
+
+## Tests
+
+`folder.test.ts`, `dashboard.test.ts` and `dashboard-model.test.ts` mirror `datasource.test.ts`'s
+fake-Grafana harness (`fake-grafana.ts` — the real distilled protocol, only the wire responses
+faked). Each proves: a GET never carries a body (`fake.bodies[0]` is `undefined` — the exact
+"distilled JSON-encodes unknown keys as a body" trap this family's shared memory names); a
+provisioned object refuses update and destroy with no write sent; a transient failure (403/401)
+propagates rather than folding to absent; an unchanged declaration is a noop despite `id`/
+`version`/`iteration` differing; a 412 propagates uncaught; and the folder `parentUid` reparent
+refusal sends no write.

package/docs/grafana.md

@@ -6,15 +6,14 @@ any status check. Built 2026-09-24 against the live target `teslamate-grafana.se
 measured version **13.1.3** (`teslamate/grafana:4.2.0`), listening on `127.0.0.1:3100`, served
 publicly at `tesla.homeflare.dev/dash/`.
 
-## The SDK gap — why only `Datasource` ships
+## The SDK gap — history, and what shipped on top of the fix
 
 ✅ **SDK-level gap fixed 2026-09-24** (`@distilled.cloud/grafana`, aliased onto
-`@homeflare/distilled-grafana` — 0.1.0 pre-release, 0.2.0 once its `minor` changeset publishes it;
-see [docs/distilled-interim.md](./distilled-interim.md)).
-The gap below is otherwise unchanged and left as evidence of what was measured and why; only its
-status line moved. **Still true today:** only `Grafana.Datasource` ships as a house _resource_ —
-`Grafana.Folder`, `Grafana.Dashboard`, `Grafana.AlertRule` and friends are follow-up work on top of
-the now-available SDK operations, not part of this fix.
+`@homeflare/distilled-grafana` — 0.2.0; see [docs/distilled-interim.md](./distilled-interim.md)).
+The gap below is left as evidence of what was measured and why. `Grafana.Folder` and
+`Grafana.Dashboard` now ship on top of the unblocked operations —
+[grafana-folder-dashboard.md](./grafana-folder-dashboard.md) covers both in full. `Grafana.AlertRule`,
+`ContactPoint`, `NotificationPolicy` and `MuteTiming` remain follow-up work, not part of this PR.
 
 Measured 2026-09-24 against the published `@distilled.cloud/grafana@1.0.0-rc.12` tarball (its
 `lib/services/grafana.d.ts`, 4,938 lines): the package had **no create/read/update/delete
@@ -125,8 +124,11 @@ export class TeslaMateDatasource extends GrafanaDatasource('teslamate-datasource
 
 ## Not covered
 
-- **Folders, dashboards, 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.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

@@ -259,10 +259,37 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
     `@homeflare/distilled-grafana` (0.1.0 pre-release, 0.2.0 once this PR's `minor` changeset
     releases it), aliased onto `@distilled.cloud/grafana` the same S22 route
     `@homeflare/distilled-netbox` established. `Grafana.Datasource`'s props/attributes/generated code
-    are unchanged (diffed operation-by-operation against the prior commit). **Still open, and not
-    this PR's scope:** no `Grafana.Folder`/`Dashboard`/`AlertRule`/`ContactPoint`/
-    `NotificationPolicy`/`MuteTiming` resource calls the newly-available operations yet — follow-up
-    PRs, no longer blocked on the SDK.
+    are unchanged (diffed operation-by-operation against the prior commit).
+
+    ✅ **`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.
+
+    ✅ **`Grafana.ContactPoint`/`Grafana.MuteTiming`/`Grafana.MessageTemplate` shipped** (this PR,
+    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).
+
+    **Still open, not this PR's scope:** `Grafana.AlertRuleGroup`/`Grafana.NotificationPolicy` —
+    the next two stacked PRs, 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.32.0",
+  "version": "0.34.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/alerting-provenance.ts

@@ -0,0 +1,109 @@
+/**
+ * The shared refusal for a foreign-provenance ALERTING-PROVISIONING object — `Grafana.ContactPoint`,
+ * `Grafana.MessageTemplate`, `Grafana.AlertRuleGroup` and `Grafana.NotificationPolicy` each read a
+ * `provenance` string off what Grafana returns (`EmbeddedContactPoint.provenance`,
+ * `NotificationTemplate.provenance`, `ProvisionedAlertRule.provenance` per rule, `Route.provenance`
+ * on the policy tree — all measured against `@distilled.cloud/grafana`'s generated types,
+ * `packages/distilled-grafana/src/services/grafana.ts`) and refuse a write when it disagrees with
+ * what this family is allowed to own. Sibling to `provisioned.ts`, not a rename of it — the two
+ * refusals guard different fields with different value shapes (`managedBy`/`provisioned` there,
+ * `provenance` here) for two different Grafana API surfaces (classic folder/dashboard vs. alerting
+ * provisioning), but both end in the SAME tagged error, reused from `provisioned.ts` rather than
+ * declared twice: "a write was refused because something else owns this object" is one condition
+ * across the whole family, the spirit PR 245's provisioned refusal already established.
+ *
+ * ★ THE ALLOWLIST, MEASURED AGAINST GRAFANA'S OWN SOURCE (not this SDK, which only echoes the
+ *   value back on read — never re-fetched live in this PR): Grafana's `pkg/services/ngalert/
+ *   models` package defines a `Provenance` type with `ProvenanceNone = ""` (nothing has claimed
+ *   the object — fresh, or written through the classic non-provisioning path), `ProvenanceAPI =
+ *   "api"` (created or last written through THIS provisioning API — what this family's own
+ *   create/update leaves behind), `ProvenanceFile = "file"` (Grafana's file-based provisioning),
+ *   and `ProvenanceConvertedPrometheus = "converted_prometheus"` (the Prometheus-rules importer).
+ *   Corroborated by Grafana's own docs (grafana.com/docs/grafana/v13.1/alerting/set-up/
+ *   provision-alerting-resources/http-api-provisioning/), whose example payloads show
+ *   `"provenance": "api"` on an alert rule this API created and `"provenance": "file"` on a
+ *   file-provisioned mute timing and template.
+ *
+ *   `WRITABLE_PROVENANCES` is therefore an ALLOWLIST of `{"", "api"}`, not a denylist of the two
+ *   named foreign values — a provenance source not yet named above (a plugin importer, a future
+ *   Grafana release) refuses by default instead of silently being treated as writable, the safer
+ *   failure direction for a control-plane write.
+ *
+ * ⛔ A MISSING `provenance` FIELD IS TREATED AS FOREIGN, NEVER AS `ProvenanceNone` — fixed after an
+ *   adversarial review of this PR found the first version failed OPEN: every resource mapped
+ *   `live.provenance ?? ''`, and `''` (`ProvenanceNone`, writable) is indistinguishable from a
+ *   field the response simply never included once both collapse through `??`. Every `provenance`
+ *   field in this family is optional on the wire (`EmbeddedContactPoint.provenance?: string`, etc.
+ *   — genuinely absent is a real, typed possibility, not a hypothetical), and `Grafana.MuteTiming`'s
+ *   depends on an unmodeled-key passthrough this family has never observed against a real Grafana
+ *   response (see its own file header) — a version, edge case or bug in that decode path that drops
+ *   the field would, under the old `?? ''` rule, silently make a file-provisioned object look
+ *   writable. `isForeignProvenance`/`refuseIfForeignProvenance` below keep `undefined` as its own
+ *   value all the way through: ONLY a field Grafana explicitly reported as `""` or `"api"` is
+ *   writable; missing entirely refuses, with a message that says so rather than naming a fabricated
+ *   provenance value.
+ *
+ * ⚠️ CLIENT-SIDE DEFENSE, NOT THE ONLY GUARD — AND NOT RE-MEASURED LIVE IN THIS PR. Grafana's own
+ *   alerting provisioning API server ALSO enforces this (unlike the classic folder/dashboard write
+ *   API `provisioned.ts` guards, which has no such server-side check at all): grafana/grafana#103597
+ *   ("Unable to delete file provisioned alert rules") reports exactly this block firing for a
+ *   `file`-provenance object, and the `X-Disable-Provenance` header's own documented purpose is "by
+ *   default, you cannot edit API-provisioned alerting resources in Grafana" (same doc page). This
+ *   function exists anyway, for the same reason `provisioned.ts` does: a clear, typed, house error
+ *   instead of whatever 400-with-a-string-message Grafana's server happens to return this version —
+ *   and as a defense against the known server-side bug that same issue documents
+ *   (`X-Disable-Provenance` failing to actually unlock a `file`-provenance object), which could
+ *   otherwise leave a write silently rejected with only a generic `BadRequest` and no explanation
+ *   of why.
+ *
+ * ⚠️ `Grafana.MuteTiming` ALSO USES THIS FUNCTION, BUT THROUGH A WIDENED LIVE TYPE — the SDK's
+ *   generated `MuteTimeInterval` interface (the TS type for both `GET .../mute-timings` and
+ *   `GET .../mute-timings/{name}`) declares no `provenance` field at all, unlike every other type
+ *   named above. A first pass at this family assumed that meant the DATA was gone; it is not —
+ *   MEASURED (see mute-timing.ts's own file header for the full account): `@distilled.cloud/core`'s
+ *   response decoding never runs a strict schema decode, only `JSON.parse` + a key-rename pass that
+ *   passes any key a type doesn't model through verbatim, so `provenance` survives on the actual
+ *   runtime value even though the TS type doesn't know about it. `mute-timing.ts` reads it through
+ *   a small local `& { provenance?: string }` intersection type rather than the SDK's own.
+ */
+import * as Effect from 'effect/Effect';
+import { GrafanaProvisionedObjectError } from './provisioned.ts';
+
+export { GrafanaProvisionedObjectError };
+
+const WRITABLE_PROVENANCES = new Set(['', 'api']);
+
+/**
+ * True when `provenance` names an owner other than "this API" — INCLUDING when Grafana did not
+ * report the field at all (`undefined`). `undefined` is deliberately NEVER folded into `''`
+ * (`ProvenanceNone`) here — see the file header's "fails open" note. Only a value Grafana
+ * explicitly reported as `""` or `"api"` is writable.
+ */
+export const isForeignProvenance = (provenance: string | undefined): boolean =>
+  provenance === undefined || !WRITABLE_PROVENANCES.has(provenance);
+
+export const refuseIfForeignProvenance = (
+  kind:
+    | 'Grafana.ContactPoint'
+    | 'Grafana.MessageTemplate'
+    | 'Grafana.MuteTiming'
+    | 'Grafana.AlertRuleGroup'
+    | 'Grafana.NotificationPolicy',
+  id: string,
+  provenance: string | undefined,
+): Effect.Effect<never, GrafanaProvisionedObjectError> => {
+  const reason =
+    provenance === undefined
+      ? `did not report a provenance at all — this family cannot tell whether it is safe to own`
+      : `has provenance '${provenance}', not '(none)' or 'api'`;
+  return Effect.fail(
+    new GrafanaProvisionedObjectError({
+      message:
+        `${kind} '${id}' ${reason} — something other than this API may own it (file ` +
+        `provisioning, the Prometheus-rules importer, or similar), and writing here could take ` +
+        `over or corrupt an object this family does not actually control. Edit it at its actual ` +
+        `source instead — declaring this object read-only (a declaration matching what is live) ` +
+        `is safe and will never reach this refusal.`,
+    }),
+  );
+};

package/src/grafana/contact-point-fixtures.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared fixtures for `contact-point.test.ts`/`contact-point-secrets.test.ts`/
+ * `contact-point-provenance.test.ts` — split across three files to keep each under the house's
+ * 250-line cap. Deliberately NOT named `*.test.ts`: importing one test file from another would
+ * make `bun test`'s glob discovery execute its `describe` blocks twice (once directly, once as an
+ * import side effect of the importing file) — this file has none to run, only plain data.
+ */
+export const LIST_PATH = '/api/v1/provisioning/contact-points';
+export const ITEM_PATH = '/api/v1/provisioning/contact-points/slack-oncall';
+
+export const liveJson = {
+  disableResolveMessage: false,
+  name: 'On-call Slack',
+  provenance: 'api',
+  settings: { recipient: '#oncall' },
+  type: 'slack',
+  uid: 'slack-oncall',
+};
+
+export const props = {
+  name: 'On-call Slack',
+  settings: { recipient: '#oncall' },
+  type: 'slack',
+  uid: 'slack-oncall',
+};

package/src/grafana/contact-point-provenance.test.ts

@@ -0,0 +1,113 @@
+/**
+ * `Grafana.ContactPoint`'s provenance refusal — both the explicit-foreign case (`provenance:
+ * 'file'`) and the missing-field-fails-closed case an adversarial review of this PR found. Split
+ * out of `contact-point.test.ts` to keep each file under the house's 250-line cap.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { GrafanaProvisionedObjectError } from './alerting-provenance.ts';
+import { ITEM_PATH, LIST_PATH, liveJson, props } from './contact-point-fixtures.ts';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { grafanaOperations } from './resource.ts';
+import { spec } from './contact-point.ts';
+
+describe('update and destroy — foreign provenance refuses', () => {
+  test('a file-provisioned contact point refuses update and sends no PUT', async () => {
+    const fileProvisioned = { ...liveJson, provenance: 'file' };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === LIST_PATH
+        ? Response.json([fileProvisioned])
+        : fakeFailure(500, 'no write should be attempted'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .reconcile({ ...props, name: 'Renamed' })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaProvisionedObjectError);
+    expect(failure.message).toContain('file');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('a file-provisioned contact point refuses destroy and sends no DELETE', async () => {
+    const fileProvisioned = { ...liveJson, provenance: 'file' };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === LIST_PATH
+        ? Response.json([fileProvisioned])
+        : fakeFailure(500, 'no DELETE should be attempted'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .destroy(props)
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaProvisionedObjectError);
+    expect(fake.seen).toEqual([{ method: 'GET', path: LIST_PATH }]);
+  });
+});
+
+describe('missing provenance fails closed', () => {
+  // ⛔ THE REGRESSION AN ADVERSARIAL REVIEW OF THIS PR FOUND. An earlier version mapped
+  //   `live.provenance ?? ''`, so a response that simply omitted the field looked identical to an
+  //   explicit `ProvenanceNone` and was treated as writable — the guard failed OPEN. These three
+  //   tests pin the fix: missing refuses (both writes), an EXPLICIT `""` is the only thing that
+  //   allows one.
+  const noProvenanceField: Record<string, unknown> = { ...liveJson };
+  delete noProvenanceField.provenance;
+
+  test('a response with no provenance field at all refuses update', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === LIST_PATH
+        ? Response.json([noProvenanceField])
+        : fakeFailure(500, 'no write should be attempted'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .reconcile({ ...props, name: 'Renamed' })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaProvisionedObjectError);
+    expect(failure.message).toContain('did not report a provenance');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('a response with no provenance field at all refuses destroy', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === LIST_PATH
+        ? Response.json([noProvenanceField])
+        : fakeFailure(500, 'no DELETE should be attempted'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .destroy(props)
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaProvisionedObjectError);
+    expect(fake.seen).toEqual([{ method: 'GET', path: LIST_PATH }]);
+  });
+
+  test('an EXPLICIT empty-string provenance (ProvenanceNone) is writable', async () => {
+    const explicitlyNone = { ...liveJson, provenance: '' };
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === LIST_PATH) return Response.json([explicitlyNone]);
+      if (method === 'PUT' && url.pathname === ITEM_PATH) {
+        return Response.json({ ...explicitlyNone, name: 'Renamed' });
+      }
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile({ ...props, name: 'Renamed' })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen.some((s) => s.method === 'PUT' && s.path === ITEM_PATH)).toBe(true);
+  });
+});

package/src/grafana/contact-point-secrets.test.ts

@@ -0,0 +1,117 @@
+/**
+ * `Grafana.ContactPoint`'s `secureSettingsRefs` seam (S25) — split out of `contact-point.test.ts`
+ * to keep each file under the house's 250-line cap. A secret value must reach the wire on write and
+ * never appear anywhere this resource returns or would persist.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { LIST_PATH, liveJson, props } from './contact-point-fixtures.ts';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { grafanaOperations } from './resource.ts';
+import { GrafanaSecretRefUnsetError, spec } from './contact-point.ts';
+
+const ENV_VAR = 'GRAFANA_FAMILY_TEST_CP_TOKEN';
+
+describe('secure settings references (S25)', () => {
+  test('create resolves the env var fresh and merges it into settings, never as a prop', async () => {
+    process.env[ENV_VAR] = 'xoxb-s3cret';
+    try {
+      const fake = fakeGrafana((method, url) =>
+        method === 'POST' && url.pathname === LIST_PATH
+          ? Response.json(liveJson)
+          : fakeFailure(404, 'x'),
+      );
+      await Effect.runPromise(
+        spec
+          .create({ ...props, secureSettingsRefs: { url: ENV_VAR } })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      );
+      expect(fake.bodies[0]).toMatchObject({
+        settings: { recipient: '#oncall', url: 'xoxb-s3cret' },
+      });
+    } finally {
+      delete process.env[ENV_VAR];
+    }
+  });
+
+  test('the secret reaches the wire on create but never the RETURNED attributes — proven end to end', async () => {
+    // ⛔ THE POINT OF THIS FAMILY'S TESTS, TIGHTENED AFTER AN ADVERSARIAL REVIEW OF THIS PR: the
+    //   earlier version only asserted `JSON.stringify(props)` never contained the secret — trivially
+    //   true, since `props` never held it to begin with (it lives in `secureSettingsRefs`, an env
+    //   var NAME). This drives a REAL `reconcile` (create, then the read-back `resource.ts` always
+    //   does) through the fake and stringifies what it actually RETURNS — the shape that would be
+    //   persisted to state — proving the secret never survives there, not just that it was never in
+    //   an input we already knew was secret-free.
+    process.env[ENV_VAR] = 'xoxb-s3cret';
+    try {
+      let created = false;
+      const fake = fakeGrafana((method, url) => {
+        if (method === 'GET' && url.pathname === LIST_PATH) {
+          return created
+            ? Response.json([
+                { ...liveJson, settings: { recipient: '#oncall', url: 'RedactedValue' } },
+              ])
+            : Response.json([]);
+        }
+        if (method === 'POST' && url.pathname === LIST_PATH) {
+          created = true;
+          return Response.json(liveJson);
+        }
+        return fakeFailure(500, 'unexpected request');
+      });
+      const declared = { ...props, secureSettingsRefs: { url: ENV_VAR } };
+      const attrs = await Effect.runPromise(
+        grafanaOperations(spec)
+          .reconcile(declared)
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      );
+      const createBody = fake.bodies[fake.seen.findIndex((s) => s.method === 'POST')];
+      // The wire genuinely carried it — the write would be useless otherwise.
+      expect(createBody).toMatchObject({ settings: { recipient: '#oncall', url: 'xoxb-s3cret' } });
+      // Nothing this resource returns or would persist does — the declaration, and the attributes
+      // `reconcile` hands back after reading the object right back through Grafana's own redaction.
+      expect(JSON.stringify(declared)).not.toContain('xoxb-s3cret');
+      expect(JSON.stringify(attrs)).not.toContain('xoxb-s3cret');
+      expect(attrs.settings).toEqual({ recipient: '#oncall', url: 'RedactedValue' });
+    } finally {
+      delete process.env[ENV_VAR];
+    }
+  });
+
+  test('create refuses with a typed error when the ref is unset — and sends nothing', async () => {
+    const fake = fakeGrafana(() => fakeFailure(500, 'should not be reached'));
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        spec
+          .create({ ...props, secureSettingsRefs: { url: 'DEFINITELY_UNSET_VAR_XYZ' } })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaSecretRefUnsetError);
+    expect(fake.seen).toEqual([]);
+  });
+
+  test('a redacted secure field on read never fails matches, even if props still names a stale value', async () => {
+    // ⛔ THE POINT: `settings.url` is declared here (a stale placeholder — the real value comes
+    //   from `secureSettingsRefs` instead) specifically so a plain subset-match tolerance (live
+    //   simply carrying an UNDECLARED extra key) is not what makes this pass — `nonSecretSettings`
+    //   must actively exclude a key `secureSettingsRefs` names, even when `settings` also mentions
+    //   it, or a redacted live value would show a permanent false `update`.
+    const declared = {
+      ...props,
+      secureSettingsRefs: { url: 'IRRELEVANT' },
+      settings: { recipient: '#oncall', url: 'https://placeholder.invalid' },
+    };
+    const redactedLive = { ...liveJson, settings: { recipient: '#oncall', url: 'RedactedValue' } };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === LIST_PATH
+        ? Response.json([redactedLive])
+        : fakeFailure(500, 'x'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(declared).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    const attrs = live !== undefined ? spec.attributes(live, props) : undefined;
+    expect(attrs !== undefined && spec.matches(attrs, declared)).toBe(true);
+  });
+});