@homeflare/alchemy 0.33.0 → 0.35.0

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

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

@@ -0,0 +1,123 @@
+/**
+ * `Grafana.ContactPoint` against a fake Grafana — the list-then-filter-by-uid read (no by-uid GET
+ * exists), the observe-before-write "adopt" posture, and subset-match tolerance. Mirrors
+ * `datasource.test.ts`. Secure-settings-ref tests: `contact-point-secrets.test.ts`. Provenance
+ * refusal tests (foreign and missing): `contact-point-provenance.test.ts` — split out 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 { 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('spec.fetchLive', () => {
+  test('lists and filters by uid client-side — no by-uid GET route exists', async () => {
+    const other = { ...liveJson, name: 'Other', uid: 'other' };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === LIST_PATH
+        ? Response.json([other, liveJson])
+        : fakeFailure(404, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(live !== undefined && spec.attributes(live, props)).toEqual({
+      disableResolveMessage: false,
+      name: 'On-call Slack',
+      provenance: 'api',
+      settings: { recipient: '#oncall' },
+      type: 'slack',
+      uid: 'slack-oncall',
+    });
+    // ⛔ THE POINT: a GET never carries a body.
+    expect(fake.bodies[0]).toBeUndefined();
+  });
+
+  test('a uid absent from the list decodes to undefined, not an error', async () => {
+    const fake = fakeGrafana(() => Response.json([]));
+    const result = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(result).toBeUndefined();
+  });
+
+  test('a 403 propagates — never folded to absent', async () => {
+    const fake = fakeGrafana(() => fakeFailure(403, 'forbidden'));
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('Forbidden');
+  });
+});
+
+describe('subset match — tolerates a default Grafana injects into settings', () => {
+  test('an unchanged declaration is a noop despite an extra live settings field it never declared', async () => {
+    const decorated = { ...liveJson, settings: { ...liveJson.settings, severity: 'critical' } };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === LIST_PATH
+        ? Response.json([decorated])
+        : fakeFailure(500, 'reconcile should not write when content is unchanged'),
+    );
+    const after = await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(after.uid).toBe('slack-oncall');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+});
+
+describe('reconcile — adopt semantics', () => {
+  test('declaring exactly what is live is a noop: no write is ever sent', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === LIST_PATH
+        ? Response.json([liveJson])
+        : fakeFailure(500, 'reconcile should not write when nothing changed'),
+    );
+    const after = await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(after.uid).toBe('slack-oncall');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+});
+
+describe('update and destroy — normal, api-provenance writes', () => {
+  test("an api-provenance contact point (this family's own writes) updates normally", async () => {
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === LIST_PATH) return Response.json([liveJson]);
+      if (method === 'PUT' && url.pathname === ITEM_PATH) {
+        return Response.json({ ...liveJson, 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);
+  });
+
+  test('deletes a live, api-provenance contact point by uid', async () => {
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === LIST_PATH) return Response.json([liveJson]);
+      if (method === 'DELETE' && url.pathname === ITEM_PATH) return Response.json({});
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .destroy(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen).toEqual([
+      { method: 'GET', path: LIST_PATH },
+      { method: 'DELETE', path: ITEM_PATH },
+    ]);
+  });
+});

package/src/grafana/contact-point.ts

@@ -0,0 +1,179 @@
+/**
+ * `Grafana.ContactPoint` — one Grafana alerting contact point, keyed by `uid`.
+ *
+ * ⚠️ NO GET-BY-UID ROUTE EXISTS — MEASURED against the SDK's generated operations (grep across
+ *   `services/grafana.ts` for `routeGet.*[Cc]ontactpoint`: only `routeGetContactpoints` (list,
+ *   with an optional `name` filter) and `routeGetContactpointsExport`). Unlike
+ *   `Grafana.Datasource`/`Grafana.Folder`/`Grafana.Dashboard`, `fetchLive` cannot key its read
+ *   directly on `uid`. Filtering server-side by `name` is NOT a substitute: `name` is a grouping
+ *   label a declaration can rename (`uid` is the only field this resource keys on, and Grafana's
+ *   own doc calls `name` "used as grouping key in the UI" — several contact points can share one),
+ *   so narrowing the GET to the DECLARED name would miss a live object still filed under an OLDER
+ *   name mid-rename, reporting it absent and attempting a duplicate `create`. `fetchLive` instead
+ *   lists every contact point (`routeGetContactpoints({})`, no filter) and matches `uid`
+ *   client-side — the same ambiguity `resource.ts`'s header and netbox's `soleMatch` name, resolved
+ *   the same way: requiring the one field the API is actually keyed on.
+ *
+ * ⛔ SECRET SETTINGS NEVER APPEAR AS A LITERAL PROP (S25) — same shape as `Grafana.Datasource`'s
+ *   `secureJsonDataRefs` (`secret-refs.ts`, shared). Grafana does not use a separate top-level
+ *   "secure settings" field for contact points the way it does for datasources; a secure key (a
+ *   webhook URL with an embedded token, an API key, …) lives INSIDE `settings` on write, and comes
+ *   back inside `settings` REDACTED on read — Grafana's own docs for the contact-points EXPORT
+ *   route say as much explicitly ("Redacted settings will contain RedactedValue instead"; the
+ *   plain, non-export GET this resource calls has no `decrypt` option at all, so it is redacted
+ *   unconditionally). `secureSettingsRefs` therefore names which keys of `settings` are secret —
+ *   value resolved from an env var NAME fresh inside `create`/`update`'s own effect (S24), merged
+ *   into `settings` only at that point, never stored and never diffed (see `matches` below).
+ *
+ * ⛔ A FOREIGN-PROVENANCE CONTACT POINT REFUSES EVERY UPDATE AND DESTROY — `alerting-provenance.ts`,
+ *   shared with `Grafana.MessageTemplate`/`Grafana.AlertRuleGroup`/`Grafana.NotificationPolicy`.
+ *   See that file's header for the full reasoning and citations. `create` is never at risk: it only
+ *   runs when `fetchLive` already found nothing with this `uid`.
+ *
+ * ⚠️ `X-Disable-Provenance` IS NEVER SET, BY DESIGN. Every create/update through this resource
+ *   therefore leaves the contact point with `provenance: "api"` (Grafana's own default for an
+ *   object this API just wrote) — which the docs describe as blocking that same object from being
+ *   edited in the Grafana UI afterward. That is the intended outcome, not an oversight: an object
+ *   this family declares is meant to be owned by the declaration, the same "one owner per resource"
+ *   posture `provisioned.ts` establishes for folders/dashboards — handing it back to UI-editability
+ *   by default would silently create the two-owner situation this whole file exists to prevent.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as grafana from '@distilled.cloud/grafana';
+import * as Effect from 'effect/Effect';
+import {
+  type GrafanaProvisionedObjectError,
+  isForeignProvenance,
+  refuseIfForeignProvenance,
+} from './alerting-provenance.ts';
+import { type GrafanaSpec, grafanaHandlers } from './resource.ts';
+import { GrafanaSecretRefUnsetError, resolveSecretRefs } from './secret-refs.ts';
+import { declaredContentMatches } from './subset-match.ts';
+
+export { GrafanaSecretRefUnsetError };
+
+export interface ContactPointProps {
+  uid: string;
+  name: string;
+  /** Grafana integration id — `slack`, `webhook`, `email`, `pagerduty`, `opsgenie`, … */
+  type: string;
+  /** Non-secret settings — shape depends on `type`. Never put a secret VALUE here — declare it
+   *  in `secureSettingsRefs` instead; see the file header. */
+  settings: Record<string, unknown>;
+  /** Secure field name (e.g. `url`, `token`, `password`) -> env var NAME holding its value. */
+  secureSettingsRefs?: Record<string, string>;
+  disableResolveMessage?: boolean;
+}
+
+export interface ContactPointAttributes {
+  uid: string;
+  name: string;
+  type: string;
+  /** As Grafana returns it — any secure key is a redaction placeholder, never the real value. */
+  settings: Record<string, unknown>;
+  disableResolveMessage: boolean;
+  /** `""`/`"api"` (this family may write); anything else, INCLUDING `undefined` (Grafana didn't
+   *  report the field), refuses — see alerting-provenance.ts's "fails open" note. */
+  provenance: string | undefined;
+}
+
+export interface GrafanaContactPoint extends Resource<
+  'Grafana.ContactPoint',
+  ContactPointProps,
+  ContactPointAttributes,
+  never
+> {}
+
+export const GrafanaContactPoint = Resource<GrafanaContactPoint>('Grafana.ContactPoint');
+
+/** `settings` minus every key `secureSettingsRefs` names — the only part `matches` ever compares
+ *  (a secure key's live value is always a redaction placeholder, never comparable). */
+const nonSecretSettings = (props: ContactPointProps): Record<string, unknown> => {
+  const refs = props.secureSettingsRefs;
+  if (refs === undefined) return props.settings;
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(props.settings)) {
+    if (!(key in refs)) out[key] = value;
+  }
+  return out;
+};
+
+const resolveSettings = (props: ContactPointProps) =>
+  Effect.map(
+    resolveSecretRefs(props.secureSettingsRefs, (field) => `settings.${field}`),
+    (secrets) => (secrets === undefined ? props.settings : { ...props.settings, ...secrets }),
+  );
+
+export const spec: GrafanaSpec<
+  ContactPointProps,
+  grafana.EmbeddedContactPoint,
+  ContactPointAttributes,
+  | grafana.RouteGetContactpointsError
+  | grafana.RoutePostContactpointsError
+  | grafana.RoutePutContactpointError
+  | grafana.RouteDeleteContactpointsError
+  | GrafanaProvisionedObjectError
+  | GrafanaSecretRefUnsetError
+> = {
+  attributes: (live) => ({
+    disableResolveMessage: live.disableResolveMessage ?? false,
+    name: live.name ?? '',
+    // ⛔ NEVER `?? ''` — an absent field must stay distinguishable from an explicit `""`
+    //   (ProvenanceNone); see alerting-provenance.ts's "fails open" note.
+    provenance: live.provenance,
+    settings: (live.settings ?? {}) as Record<string, unknown>,
+    type: live.type,
+    uid: live.uid ?? '',
+  }),
+  create: (props) =>
+    Effect.flatMap(resolveSettings(props), (settings) =>
+      grafana.routePostContactpoints({
+        name: props.name,
+        settings,
+        type: props.type,
+        uid: props.uid,
+        ...(props.disableResolveMessage === undefined
+          ? {}
+          : { disableResolveMessage: props.disableResolveMessage }),
+      }),
+    ),
+  destroy: (props, live) =>
+    Effect.gen(function* () {
+      if (isForeignProvenance(live.provenance)) {
+        return yield* refuseIfForeignProvenance('Grafana.ContactPoint', props.uid, live.provenance);
+      }
+      yield* grafana.routeDeleteContactpoints({ UID: props.uid });
+    }),
+  fetchLive: (props) =>
+    grafana
+      .routeGetContactpoints({})
+      .pipe(Effect.map((points) => points.find((point) => point.uid === props.uid))),
+  matches: (attributes, props) =>
+    attributes.name === props.name &&
+    attributes.type === props.type &&
+    attributes.disableResolveMessage === (props.disableResolveMessage ?? false) &&
+    declaredContentMatches(nonSecretSettings(props), attributes.settings),
+  update: (props, live) =>
+    Effect.gen(function* () {
+      if (isForeignProvenance(live.provenance)) {
+        return yield* refuseIfForeignProvenance('Grafana.ContactPoint', props.uid, live.provenance);
+      }
+      const settings = yield* resolveSettings(props);
+      yield* grafana.routePutContactpoint({
+        UID: props.uid,
+        name: props.name,
+        settings,
+        type: props.type,
+        uid: props.uid,
+        ...(props.disableResolveMessage === undefined
+          ? {}
+          : { disableResolveMessage: props.disableResolveMessage }),
+      });
+    }),
+};
+
+export const handlers = grafanaHandlers(spec);
+
+export const GrafanaContactPointProvider = () =>
+  Provider.effect(GrafanaContactPoint, Effect.succeed(GrafanaContactPoint.Provider.of(handlers)));