@homeflare/alchemy 0.33.0 → 0.34.0

package/src/grafana/index.ts

@@ -6,16 +6,17 @@
  *   dashboard-model.ts, fake-grafana.ts) are internals a provider needs but a consumer should not
  *   depend on.
  *
- * `Grafana.Datasource`, `Grafana.Folder` and `Grafana.Dashboard` ship here. `Grafana.AlertRule`
- * and friends are still follow-up work on the same now-available SDK operations — see
- * docs/grafana.md and docs/grafana-folder-dashboard.md for what shipped and what is still open.
+ * `Grafana.Datasource`, `Grafana.Folder`, `Grafana.Dashboard`, `Grafana.ContactPoint`,
+ * `Grafana.MuteTiming` and `Grafana.MessageTemplate` ship here. `Grafana.AlertRuleGroup` and
+ * `Grafana.NotificationPolicy` are stacked follow-up PRs on the same SDK operations — see
+ * docs/grafana.md, docs/grafana-folder-dashboard.md and docs/grafana-alerting.md for what shipped
+ * and what is still open.
  */
 export {
   type DatasourceAttributes,
   type DatasourceProps,
   GrafanaDatasource,
   GrafanaDatasourceProvider,
-  GrafanaSecretRefUnsetError,
 } from './datasource.ts';
 export {
   type DashboardAttributes,
@@ -31,6 +32,25 @@ export {
   GrafanaFolderProvider,
   GrafanaFolderReparentError,
 } from './folder.ts';
+export {
+  type ContactPointAttributes,
+  type ContactPointProps,
+  GrafanaContactPoint,
+  GrafanaContactPointProvider,
+} from './contact-point.ts';
+export {
+  type MessageTemplateAttributes,
+  type MessageTemplateProps,
+  GrafanaMessageTemplate,
+  GrafanaMessageTemplateProvider,
+} from './message-template.ts';
+export {
+  type MuteTimingAttributes,
+  type MuteTimingProps,
+  GrafanaMuteTiming,
+  GrafanaMuteTimingProvider,
+} from './mute-timing.ts';
 export { GrafanaProvisionedObjectError } from './provisioned.ts';
+export { GrafanaSecretRefUnsetError } from './secret-refs.ts';
 export { type GrafanaTarget, grafanaCredentials } from './credentials.ts';
 export { grafanaProviders } from './providers.ts';

package/src/grafana/message-template.test.ts

@@ -0,0 +1,212 @@
+/**
+ * `Grafana.MessageTemplate` against a fake Grafana — the PUT-is-both-create-and-update route (no
+ * `routePostTemplate` exists), the foreign-provenance refusal, and version-carrying updates.
+ * Mirrors `message-template.ts`'s own file header.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { GrafanaProvisionedObjectError } from './alerting-provenance.ts';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { spec } from './message-template.ts';
+import { grafanaOperations } from './resource.ts';
+
+const PATH = '/api/v1/provisioning/templates/slack-body';
+
+const liveJson = {
+  name: 'slack-body',
+  provenance: 'api',
+  template: '{{ define "slack-body" }}…{{ end }}',
+  version: '3',
+};
+const props = { name: 'slack-body', template: '{{ define "slack-body" }}…{{ end }}' };
+
+describe('spec.fetchLive', () => {
+  test('a live template decodes into typed attributes', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH ? Response.json(liveJson) : fakeFailure(404, 'x'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(live !== undefined && spec.attributes(live, props)).toEqual({
+      name: 'slack-body',
+      provenance: 'api',
+      template: '{{ define "slack-body" }}…{{ end }}',
+    });
+    expect(fake.bodies[0]).toBeUndefined();
+  });
+
+  test('a 404 folds to undefined', async () => {
+    const fake = fakeGrafana(() => fakeFailure(404, 'template not found'));
+    const result = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(result).toBeUndefined();
+  });
+
+  test('a 401 propagates — never folded to absent', async () => {
+    const fake = fakeGrafana(() => fakeFailure(401, 'bad token'));
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('Unauthorized');
+  });
+});
+
+describe('create and update — the same PUT route', () => {
+  test('create sends no version — nothing has been read yet', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'PUT' && url.pathname === PATH ? Response.json(liveJson) : fakeFailure(404, 'x'),
+    );
+    await Effect.runPromise(spec.create(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))));
+    // ⛔ `name` is a URL path label (`/templates/{name}`), never part of the body — only
+    //   `template` (and, on update, `version`) travel in the JSON payload.
+    expect(fake.bodies[0]).toEqual({ template: props.template });
+  });
+
+  test('an api-provenance template updates and sends the live version for concurrency', async () => {
+    const changed = { name: 'slack-body', template: 'v2' };
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === PATH) return Response.json(liveJson);
+      if (method === 'PUT' && url.pathname === PATH)
+        return Response.json({ ...liveJson, template: 'v2' });
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile(changed)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    const put = fake.seen.findIndex((s) => s.method === 'PUT');
+    expect(fake.bodies[put]).toEqual({ template: 'v2', version: '3' });
+  });
+
+  test('reconcile is a noop when the declared template already matches what is live', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === 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.name).toBe('slack-body');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+});
+
+describe('foreign provenance refuses update and destroy', () => {
+  test('a file-provisioned template refuses update and sends no PUT', async () => {
+    const fileProvisioned = { ...liveJson, provenance: 'file' };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH
+        ? Response.json(fileProvisioned)
+        : fakeFailure(500, 'no write should be attempted'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .reconcile({ name: 'slack-body', template: 'v2' })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaProvisionedObjectError);
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('a file-provisioned template refuses destroy and sends no DELETE', async () => {
+    const fileProvisioned = { ...liveJson, provenance: 'file' };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === 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: PATH }]);
+  });
+
+  test('deletes a live, api-provenance template', async () => {
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === PATH) return Response.json(liveJson);
+      if (method === 'DELETE' && url.pathname === 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: PATH },
+      { method: 'DELETE', path: PATH },
+    ]);
+  });
+});
+
+describe('missing provenance fails closed', () => {
+  // ⛔ THE REGRESSION AN ADVERSARIAL REVIEW OF THIS PR FOUND — see contact-point.test.ts's own
+  //   copy of this block for the full account.
+  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 === PATH
+        ? Response.json(noProvenanceField)
+        : fakeFailure(500, 'no write should be attempted'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .reconcile({ name: 'slack-body', template: 'v2' })
+          .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 === 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: 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 === PATH) return Response.json(explicitlyNone);
+      if (method === 'PUT' && url.pathname === PATH) {
+        return Response.json({ ...explicitlyNone, template: 'v2' });
+      }
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile({ name: 'slack-body', template: 'v2' })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen.some((s) => s.method === 'PUT')).toBe(true);
+  });
+});

package/src/grafana/message-template.ts

@@ -0,0 +1,114 @@
+/**
+ * `Grafana.MessageTemplate` — one Grafana notification-template group, keyed by `name`.
+ *
+ * ⚠️ CREATE AND UPDATE ARE THE SAME WIRE CALL — MEASURED: `services/grafana.ts` has no
+ *   `routePostTemplate` at all, only `routePutTemplate` (`PUT /v1/provisioning/templates/{name}`,
+ *   upsert by name), `routeGetTemplate`/`routeGetTemplates` and `routeDeleteTemplate`. `spec.create`
+ *   and `spec.update` both call it — kept as two separate functions anyway (rather than omitting
+ *   `update` and letting them collapse into one) so the shared engine's `diff` reports a content
+ *   change as `update`, not the `replace` it would show for any resource whose `spec.update` is
+ *   undefined (`resource.ts`).
+ *
+ * ⛔ A FOREIGN-PROVENANCE TEMPLATE REFUSES EVERY UPDATE AND DESTROY — `alerting-provenance.ts`,
+ *   shared with `Grafana.ContactPoint`/`AlertRuleGroup`/`NotificationPolicy`; see that file's
+ *   header. `create` is never at risk: it only runs when `fetchLive` already found nothing.
+ *
+ * ⚠️ `version` IS SENT FOR OPTIMISTIC CONCURRENCY WHEN GRAFANA REPORTS ONE — `RoutePutTemplateRequest.
+ *   version`'s own doc comment: "Version of template to use for optimistic concurrency. Leave empty
+ *   to disable validation." Unlike `Grafana.Dashboard`'s 412, no live call confirms what error this
+ *   produces on a genuine mismatch (no live calls in this PR) — whatever typed error the SDK
+ *   declares for `routePutTemplate` is left uncaught either way, per the house rule against
+ *   folding a non-not-found error into absent.
+ *
+ * ⚠️ `X-Disable-Provenance` IS NEVER SET — same reasoning as `contact-point.ts`'s file header.
+ */
+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';
+
+export interface MessageTemplateProps {
+  name: string;
+  /** The Go-template body, e.g. Grafana's own "Export as JSON/YAML" template text. */
+  template: string;
+}
+
+export interface MessageTemplateAttributes {
+  name: string;
+  template: string;
+  /** `""`/`"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 GrafanaMessageTemplate extends Resource<
+  'Grafana.MessageTemplate',
+  MessageTemplateProps,
+  MessageTemplateAttributes,
+  never
+> {}
+
+export const GrafanaMessageTemplate = Resource<GrafanaMessageTemplate>('Grafana.MessageTemplate');
+
+export const spec: GrafanaSpec<
+  MessageTemplateProps,
+  grafana.NotificationTemplate,
+  MessageTemplateAttributes,
+  | grafana.RouteGetTemplateError
+  | grafana.RoutePutTemplateError
+  | grafana.RouteDeleteTemplateError
+  | GrafanaProvisionedObjectError
+> = {
+  attributes: (live) => ({
+    name: live.name ?? '',
+    // ⛔ NEVER `?? ''` — see alerting-provenance.ts's "fails open" note.
+    provenance: live.provenance,
+    template: live.template ?? '',
+  }),
+  create: (props) => grafana.routePutTemplate({ name: props.name, template: props.template }),
+  destroy: (props, live) =>
+    Effect.gen(function* () {
+      if (isForeignProvenance(live.provenance)) {
+        return yield* refuseIfForeignProvenance(
+          'Grafana.MessageTemplate',
+          props.name,
+          live.provenance,
+        );
+      }
+      yield* grafana.routeDeleteTemplate({ name: props.name });
+    }),
+  fetchLive: (props) =>
+    grafana
+      .routeGetTemplate({ name: props.name })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  matches: (attributes, props) => attributes.template === props.template,
+  update: (props, live) =>
+    Effect.gen(function* () {
+      if (isForeignProvenance(live.provenance)) {
+        return yield* refuseIfForeignProvenance(
+          'Grafana.MessageTemplate',
+          props.name,
+          live.provenance,
+        );
+      }
+      yield* grafana.routePutTemplate({
+        name: props.name,
+        template: props.template,
+        ...(live.version === undefined ? {} : { version: live.version }),
+      });
+    }),
+};
+
+export const handlers = grafanaHandlers(spec);
+
+export const GrafanaMessageTemplateProvider = () =>
+  Provider.effect(
+    GrafanaMessageTemplate,
+    Effect.succeed(GrafanaMessageTemplate.Provider.of(handlers)),
+  );

package/src/grafana/mute-timing.test.ts

@@ -0,0 +1,227 @@
+/**
+ * `Grafana.MuteTiming` against a fake Grafana — the widened-type `provenance`/`version` read (see
+ * the file's own header for why the SDK's declared `MuteTimeInterval` type undersells the runtime
+ * value), the foreign-provenance refusal, and opaque time-interval passthrough (weekdays/times
+ * fields the SDK's own `TimeInterval` type does not model either). Mirrors `contact-point.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { GrafanaProvisionedObjectError } from './alerting-provenance.ts';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { spec } from './mute-timing.ts';
+import { grafanaOperations } from './resource.ts';
+
+const PATH = '/api/v1/provisioning/mute-timings/weekends';
+const LIST_PATH = '/api/v1/provisioning/mute-timings';
+
+const timeIntervals = [
+  { times: [{ end_time: '09:00', start_time: '17:00' }], weekdays: ['friday'] },
+];
+
+const liveJson = {
+  name: 'weekends',
+  provenance: 'api',
+  time_intervals: timeIntervals,
+  version: 'v1',
+};
+const props = { name: 'weekends', timeIntervals };
+
+describe('spec.fetchLive', () => {
+  test('provenance and the real weekday/time fields survive decode despite the SDK type', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH ? Response.json(liveJson) : fakeFailure(404, 'x'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(live !== undefined && spec.attributes(live, props)).toEqual({
+      name: 'weekends',
+      provenance: 'api',
+      timeIntervals,
+    });
+    expect(fake.bodies[0]).toBeUndefined();
+  });
+
+  test('a 404 folds to undefined', async () => {
+    const fake = fakeGrafana(() => fakeFailure(404, 'mute timing not found'));
+    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('create', () => {
+  test('sends the real weekday/time fields on the wire — not dropped by the SDK type either', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'POST' && url.pathname === LIST_PATH
+        ? Response.json(liveJson)
+        : fakeFailure(404, 'x'),
+    );
+    await Effect.runPromise(spec.create(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))));
+    expect(fake.bodies[0]).toEqual({ name: 'weekends', time_intervals: timeIntervals });
+  });
+});
+
+describe('subset-match array rule — pinned, not re-measured live', () => {
+  // ⛔ FLAGGED BY AN ADVERSARIAL REVIEW OF THIS PR: `subset-match.ts`'s array comparison is exact
+  //   length, then element-wise — unverified against a real Grafana instance for whether it ever
+  //   pads or appends a default entry to `time_intervals` (no live mute timing exists in this house
+  //   to observe). This test pins TODAY's behavior — a live observation that finds Grafana doing so
+  //   would make this test itself the place to change, not a surprise discovered elsewhere.
+  test('live carrying one extra time-interval entry the declaration never mentioned still shows update', async () => {
+    const extraEntry = {
+      ...liveJson,
+      time_intervals: [...timeIntervals, { weekdays: ['sunday'] }],
+    };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH ? Response.json(extraEntry) : fakeFailure(500, 'x'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    const attrs = live !== undefined ? spec.attributes(live, props) : undefined;
+    expect(attrs !== undefined && spec.matches(attrs, props)).toBe(false);
+  });
+});
+
+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 === 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.name).toBe('weekends');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+});
+
+describe('foreign provenance refuses update and destroy', () => {
+  test('a file-provisioned mute timing refuses update and sends no PUT', async () => {
+    const fileProvisioned = { ...liveJson, provenance: 'file' };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH
+        ? Response.json(fileProvisioned)
+        : fakeFailure(500, 'no write should be attempted'),
+    );
+    const changed = { name: 'weekends', timeIntervals: [{ weekdays: ['saturday'] }] };
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .reconcile(changed)
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaProvisionedObjectError);
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('a file-provisioned mute timing refuses destroy and sends no DELETE', async () => {
+    const fileProvisioned = { ...liveJson, provenance: 'file' };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === 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: PATH }]);
+  });
+
+  test('deletes a live, api-provenance mute timing, sending its version for concurrency', async () => {
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === PATH) return Response.json(liveJson);
+      if (method === 'DELETE' && url.pathname === PATH) return Response.json({});
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .destroy(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    const del = fake.seen.findIndex((s) => s.method === 'DELETE');
+    expect(del).toBeGreaterThanOrEqual(0);
+    expect(fake.seen[del]?.path).toBe(`${PATH}?version=v1`);
+  });
+});
+
+describe('missing provenance fails closed', () => {
+  // ⛔ THE REGRESSION AN ADVERSARIAL REVIEW OF THIS PR FOUND — see contact-point.test.ts's own
+  //   copy of this block for the full account. This resource is the one where it matters most:
+  //   `provenance` isn't even in the SDK's declared `MuteTimeInterval` type, so "the field is
+  //   missing" is a real, plausible shape for a response to take, not a hypothetical.
+  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 === PATH
+        ? Response.json(noProvenanceField)
+        : fakeFailure(500, 'no write should be attempted'),
+    );
+    const changed = { name: 'weekends', timeIntervals: [{ weekdays: ['saturday'] }] };
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .reconcile(changed)
+          .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 === 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: 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 === PATH) return Response.json(explicitlyNone);
+      if (method === 'PUT' && url.pathname === PATH) return Response.json(explicitlyNone);
+      return fakeFailure(500, 'unexpected request');
+    });
+    const changed = { name: 'weekends', timeIntervals: [{ weekdays: ['saturday'] }] };
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile(changed)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen.some((s) => s.method === 'PUT')).toBe(true);
+  });
+});