@homeflare/alchemy 0.33.0 → 0.34.0

package/dist/grafana/alerting-provenance.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 };
+/**
+ * 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 declare const isForeignProvenance: (provenance: string | undefined) => boolean;
+export declare const refuseIfForeignProvenance: (kind: 'Grafana.ContactPoint' | 'Grafana.MessageTemplate' | 'Grafana.MuteTiming' | 'Grafana.AlertRuleGroup' | 'Grafana.NotificationPolicy', id: string, provenance: string | undefined) => Effect.Effect<never, GrafanaProvisionedObjectError>;
+//# sourceMappingURL=alerting-provenance.d.ts.map

package/dist/grafana/alerting-provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerting-provenance.d.ts","sourceRoot":"","sources":["../../src/grafana/alerting-provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAC;AAEjE,OAAO,EAAE,6BAA6B,EAAE,CAAC;AAIzC;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,eAAgB,MAAM,GAAG,SAAS,KAAG,OACF,CAAC;AAEpE,eAAO,MAAM,yBAAyB,SAEhC,sBAAsB,GACtB,yBAAyB,GACzB,oBAAoB,GACpB,wBAAwB,GACxB,4BAA4B,MAC5B,MAAM,cACE,MAAM,GAAG,SAAS,KAC7B,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,6BAA6B,CAepD,CAAC"}

package/dist/grafana/contact-point-fixtures.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare const LIST_PATH = "/api/v1/provisioning/contact-points";
+export declare const ITEM_PATH = "/api/v1/provisioning/contact-points/slack-oncall";
+export declare const liveJson: {
+    disableResolveMessage: boolean;
+    name: string;
+    provenance: string;
+    settings: {
+        recipient: string;
+    };
+    type: string;
+    uid: string;
+};
+export declare const props: {
+    name: string;
+    settings: {
+        recipient: string;
+    };
+    type: string;
+    uid: string;
+};
+//# sourceMappingURL=contact-point-fixtures.d.ts.map

package/dist/grafana/contact-point-fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contact-point-fixtures.d.ts","sourceRoot":"","sources":["../../src/grafana/contact-point-fixtures.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,wCAAwC,CAAC;AAC/D,eAAO,MAAM,SAAS,qDAAqD,CAAC;AAE5E,eAAO,MAAM,QAAQ;IACnB,qBAAqB;IACrB,IAAI;IACJ,UAAU;IACV,QAAQ;QAAI,SAAS;;IACrB,IAAI;IACJ,GAAG;CACJ,CAAC;AAEF,eAAO,MAAM,KAAK;IAChB,IAAI;IACJ,QAAQ;QAAI,SAAS;;IACrB,IAAI;IACJ,GAAG;CACJ,CAAC"}

package/dist/grafana/contact-point.d.ts

@@ -0,0 +1,99 @@
+/**
+ * `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 } from './alerting-provenance.ts';
+import { type GrafanaSpec } from './resource.ts';
+import { GrafanaSecretRefUnsetError } from './secret-refs.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 declare const GrafanaContactPoint: import("alchemy").ResourceClass<GrafanaContactPoint>;
+export declare const spec: GrafanaSpec<ContactPointProps, grafana.EmbeddedContactPoint, ContactPointAttributes, grafana.RouteGetContactpointsError | grafana.RoutePostContactpointsError | grafana.RoutePutContactpointError | grafana.RouteDeleteContactpointsError | GrafanaProvisionedObjectError | GrafanaSecretRefUnsetError>;
+export declare const handlers: {
+    list: () => Effect.Effect<never[], never, never>;
+    read: ({ olds }: {
+        olds: ContactPointProps;
+    }) => Effect.Effect<ContactPointAttributes | undefined, grafana.BadGateway | import("@distilled.cloud/caddy").BadRequest | grafana.BadRequest | grafana.ConfigError | import("@distilled.cloud/caddy").Conflict | grafana.Conflict | import("@distilled.cloud/caddy").Forbidden | grafana.Forbidden | grafana.GatewayTimeout | GrafanaProvisionedObjectError | GrafanaSecretRefUnsetError | import("effect/unstable/http/HttpClientError").HttpClientError | grafana.InternalServerError | grafana.Locked | import("@distilled.cloud/caddy").NotFound | grafana.ServiceUnavailable | grafana.TooManyRequests | grafana.Unauthorized | grafana.UnknownGrafanaError | import("@distilled.cloud/caddy").UnprocessableEntity, grafana.GrafanaOpContext>;
+    diff: ({ news, output }: {
+        news: import("alchemy").Input<ContactPointProps>;
+        output: ContactPointAttributes | undefined;
+    }) => Effect.Effect<{
+        readonly action: 'update';
+    } | {
+        readonly action: 'noop';
+    } | {
+        readonly action: 'replace';
+    } | undefined, grafana.BadGateway | import("@distilled.cloud/caddy").BadRequest | grafana.BadRequest | grafana.ConfigError | import("@distilled.cloud/caddy").Conflict | grafana.Conflict | import("@distilled.cloud/caddy").Forbidden | grafana.Forbidden | grafana.GatewayTimeout | GrafanaProvisionedObjectError | GrafanaSecretRefUnsetError | import("effect/unstable/http/HttpClientError").HttpClientError | grafana.InternalServerError | grafana.Locked | import("@distilled.cloud/caddy").NotFound | grafana.ServiceUnavailable | grafana.TooManyRequests | grafana.Unauthorized | grafana.UnknownGrafanaError | import("@distilled.cloud/caddy").UnprocessableEntity, grafana.GrafanaOpContext>;
+    reconcile: ({ news }: {
+        news: ContactPointProps;
+    }) => Effect.Effect<ContactPointAttributes, grafana.BadGateway | import("@distilled.cloud/caddy").BadRequest | grafana.BadRequest | grafana.ConfigError | import("@distilled.cloud/caddy").Conflict | grafana.Conflict | import("@distilled.cloud/caddy").Forbidden | grafana.Forbidden | grafana.GatewayTimeout | GrafanaProvisionedObjectError | GrafanaSecretRefUnsetError | import("effect/unstable/http/HttpClientError").HttpClientError | grafana.InternalServerError | grafana.Locked | import("@distilled.cloud/caddy").NotFound | grafana.ServiceUnavailable | grafana.TooManyRequests | grafana.Unauthorized | grafana.UnknownGrafanaError | import("@distilled.cloud/caddy").UnprocessableEntity, grafana.GrafanaOpContext>;
+    delete: ({ olds }: {
+        olds: ContactPointProps;
+    }) => Effect.Effect<void, grafana.BadGateway | import("@distilled.cloud/caddy").BadRequest | grafana.BadRequest | grafana.ConfigError | import("@distilled.cloud/caddy").Conflict | grafana.Conflict | import("@distilled.cloud/caddy").Forbidden | grafana.Forbidden | grafana.GatewayTimeout | GrafanaProvisionedObjectError | GrafanaSecretRefUnsetError | import("effect/unstable/http/HttpClientError").HttpClientError | grafana.InternalServerError | grafana.Locked | import("@distilled.cloud/caddy").NotFound | grafana.ServiceUnavailable | grafana.TooManyRequests | grafana.Unauthorized | grafana.UnknownGrafanaError | import("@distilled.cloud/caddy").UnprocessableEntity, grafana.GrafanaOpContext>;
+};
+export declare const GrafanaContactPointProvider: () => import("effect/Layer").Layer<Provider.Provider<GrafanaContactPoint>, never, grafana.GrafanaOpContext>;
+//# sourceMappingURL=contact-point.d.ts.map

package/dist/grafana/contact-point.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contact-point.d.ts","sourceRoot":"","sources":["../../src/grafana/contact-point.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAC;AACpD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EACL,KAAK,6BAA6B,EAGnC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,0BAA0B,EAAqB,MAAM,kBAAkB,CAAC;AAGjF,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb;gEAC4D;IAC5D,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,6FAA6F;IAC7F,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,+FAA+F;IAC/F,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,qBAAqB,EAAE,OAAO,CAAC;IAC/B;uFACmF;IACnF,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,mBAAoB,SAAQ,QAAQ,CACnD,sBAAsB,EACtB,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,CACN;CAAG;AAEJ,eAAO,MAAM,mBAAmB,sDAAwD,CAAC;AAoBzF,eAAO,MAAM,IAAI,EAAE,WAAW,CAC5B,iBAAiB,EACjB,OAAO,CAAC,oBAAoB,EAC5B,sBAAsB,EACpB,OAAO,CAAC,0BAA0B,GAClC,OAAO,CAAC,2BAA2B,GACnC,OAAO,CAAC,yBAAyB,GACjC,OAAO,CAAC,6BAA6B,GACrC,6BAA6B,GAC7B,0BAA0B,CAyD7B,CAAC;AAEF,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;CAAwB,CAAC;AAE9C,eAAO,MAAM,2BAA2B,6GACyD,CAAC"}

package/dist/grafana/dashboard-model.d.ts

@@ -35,43 +35,13 @@ export declare const normalizeModel: (model: DashboardModel, uid: string) => Das
  *  normalized model is, in dashboard.ts's `matches`, so a title-only mismatch still shows `update`. */
 export declare const modelTitle: (model: DashboardModel) => string;
 /**
- * ★ `declared` NEED ONLY BE A SUBSET OF `live` — an adversarial review of this PR (2026-09-24)
- *   found that plain structural equality made an ordinary, never-edited dashboard show `update`
- *   FOREVER: Grafana's own dashboard-save schema migration rewrites any panel or target whose
- *   `datasource` is absent into an explicit `{type, uid}` reference to the resolved default
- *   datasource — documented Grafana schema-migration behavior (not re-measured against a live
- *   instance in this PR — no live calls). A declared panel that never sets `datasource` (the
- *   common case: hand-authored JSON, or anything relying on the dashboard-level default) would,
- *   after the FIRST create, read back with that field populated; plain `deepEqual` (this file used
- *   `alchemy/Diff`'s before this fix) then disagreed with the declaration on every subsequent plan,
- *   `update` sent the undecorated model back, and Grafana redecorated it again on the next read —
- *   non-convergent.
- *
- * This function instead asks only "does every field the DECLARATION mentions, at any depth, still
- * match what is live" — `live` may carry additional fields, at any depth, that `declared` never
- * mentioned (the datasource auto-decoration above, or any future Grafana-injected default,
- * `fieldConfig` defaults and `pluginVersion` included) without being compared at all. A field
- * `declared` DOES mention that is missing, or different, in `live` still fails the match — real
- * content drift is still caught exactly as before; only fields the declaration is silent about are
- * now tolerated rather than compared.
- *
- * ⚠️ THE TRADE-OFF THIS ACCEPTS, DELIBERATELY: removing a field from the declaration (rather than
- *   changing its value) can no longer force Grafana to drop it. If a panel once declared an
- *   explicit `datasource` and a later declaration deletes that key entirely (rather than setting a
- *   different one), `live` keeps whatever the last write set — the declaration is silent about that
- *   key now, so nothing compares it, so no `update` ever fires to change it. This is the same
- *   "undeclared means don't care, never means force-to-default" convention already used everywhere
- *   else in this kit for a plain optional prop (e.g. `datasource.ts`'s `matches` never treats an
- *   undeclared `access` as "must be unset"); it now also applies inside the JSON model, not just at
- *   the props level. Declare an explicit replacement value to change a field; omission never clears
- *   one that was set by a previous declaration or by Grafana itself.
- *
- * ⚠️ ARRAYS COMPARE BY LENGTH, THEN ELEMENT-WISE SUBSET — never by a looser "declared has fewer
- *   items" rule. `panels`/`targets` are position-significant (see `normalizeModel`'s header); an
- *   array Grafana pads or reorders on its own would still need normalizing here explicitly, the
- *   same as any other newly-discovered auto-decoration — this function does not paper over that.
- * ⚠️ `null` ON EITHER SIDE OF A LEAF NEVER MISMATCHES (mirrors `alchemy/Diff`'s `deepEqual` with
- *   `stripNullish: true`, which this function replaces for the dashboard model specifically).
+ * `declared` need only be a subset of `live` — dashboard.ts's `matches` runs `normalizeModel`'s
+ * output through this. Moved to `subset-match.ts` once `Grafana.ContactPoint`'s `settings` needed
+ * the identical "declaration silent about a field means don't compare it" rule; re-exported here
+ * under its original name so this file's own callers and dashboard-model.test.ts are unchanged.
+ * See subset-match.ts for the full reasoning, including the regression this exists to fix
+ * (Grafana's dashboard-save schema migration auto-decorating a panel's `datasource`) and the
+ * trade-off it accepts (an omitted field can no longer force-clear a previously-set one).
  */
-export declare const declaredContentMatches: (declared: unknown, live: unknown) => boolean;
+export { declaredContentMatches } from './subset-match.ts';
 //# sourceMappingURL=dashboard-model.d.ts.map

package/dist/grafana/dashboard-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dashboard-model.d.ts","sourceRoot":"","sources":["../../src/grafana/dashboard-model.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAKrD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,cAAc,UAAW,cAAc,OAAO,MAAM,KAAG,cASnE,CAAC;AAEF;uGACuG;AACvG,eAAO,MAAM,UAAU,UAAW,cAAc,KAAG,MACC,CAAC;AAKrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,sBAAsB,aAAc,OAAO,QAAQ,OAAO,KAAG,OAgBzE,CAAC"}
+{"version":3,"file":"dashboard-model.d.ts","sourceRoot":"","sources":["../../src/grafana/dashboard-model.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAKrD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,cAAc,UAAW,cAAc,OAAO,MAAM,KAAG,cASnE,CAAC;AAEF;uGACuG;AACvG,eAAO,MAAM,UAAU,UAAW,cAAc,KAAG,MACC,CAAC;AAErD;;;;;;;;GAQG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/grafana/datasource.d.ts

@@ -22,6 +22,8 @@ import * as Provider from 'alchemy/Provider';
 import * as grafana from '@distilled.cloud/grafana';
 import * as Effect from 'effect/Effect';
 import { type GrafanaSpec } from './resource.ts';
+import { GrafanaSecretRefUnsetError } from './secret-refs.ts';
+export { GrafanaSecretRefUnsetError };
 export interface DatasourceProps {
     uid: string;
     name: string;
@@ -54,14 +56,6 @@ export interface DatasourceAttributes {
 export interface GrafanaDatasource extends Resource<'Grafana.Datasource', DatasourceProps, DatasourceAttributes, never> {
 }
 export declare const GrafanaDatasource: import("alchemy").ResourceClass<GrafanaDatasource>;
-declare const GrafanaSecretRefUnsetError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "GrafanaSecretRefUnsetError";
-} & Readonly<A>;
-/** A named secure-field env var is unset — a domain refusal, not a distilled error. */
-export declare class GrafanaSecretRefUnsetError extends GrafanaSecretRefUnsetError_base<{
-    readonly message: string;
-}> {
-}
 export declare const spec: GrafanaSpec<DatasourceProps, grafana.DataSource, DatasourceAttributes, grafana.AddDataSourceError | grafana.GetDataSourceByUIDError | grafana.UpdateDataSourceByUIDError | grafana.DeleteDataSourceByUIDError | GrafanaSecretRefUnsetError>;
 export declare const handlers: {
     list: () => Effect.Effect<never[], never, never>;
@@ -86,5 +80,4 @@ export declare const handlers: {
     }) => Effect.Effect<void, grafana.BadGateway | import("@distilled.cloud/caddy").BadRequest | grafana.BadRequest | grafana.ConfigError | import("@distilled.cloud/caddy").Conflict | grafana.Conflict | import("@distilled.cloud/caddy").Forbidden | grafana.Forbidden | grafana.GatewayTimeout | GrafanaSecretRefUnsetError | import("effect/unstable/http/HttpClientError").HttpClientError | grafana.InternalServerError | grafana.Locked | import("@distilled.cloud/caddy").NotFound | grafana.NotFound | grafana.ServiceUnavailable | grafana.TooManyRequests | grafana.Unauthorized | grafana.UnknownGrafanaError | import("@distilled.cloud/caddy").UnprocessableEntity, grafana.GrafanaOpContext>;
 };
 export declare const GrafanaDatasourceProvider: () => import("effect/Layer").Layer<Provider.Provider<GrafanaDatasource>, never, grafana.GrafanaOpContext>;
-export {};
 //# sourceMappingURL=datasource.d.ts.map

package/dist/grafana/datasource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"datasource.d.ts","sourceRoot":"","sources":["../../src/grafana/datasource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAC;AAEpD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,eAAe,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,8FAA8F;IAC9F,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAkB,SAAQ,QAAQ,CACjD,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACpB,KAAK,CACN;CAAG;AAEJ,eAAO,MAAM,iBAAiB,oDAAoD,CAAC;;;;AAEnF,uFAAuF;AACvF,qBAAa,0BAA2B,SAAQ,gCAA+C;IAC7F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;CAAG;AAwCL,eAAO,MAAM,IAAI,EAAE,WAAW,CAC5B,eAAe,EACf,OAAO,CAAC,UAAU,EAClB,oBAAoB,EAClB,OAAO,CAAC,kBAAkB,GAC1B,OAAO,CAAC,uBAAuB,GAC/B,OAAO,CAAC,0BAA0B,GAClC,OAAO,CAAC,0BAA0B,GAClC,0BAA0B,CAgD7B,CAAC;AAEF,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;CAAwB,CAAC;AAE9C,eAAO,MAAM,yBAAyB,2GACuD,CAAC"}
+{"version":3,"file":"datasource.d.ts","sourceRoot":"","sources":["../../src/grafana/datasource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAC;AACpD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,0BAA0B,EAAqB,MAAM,kBAAkB,CAAC;AAEjF,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,8FAA8F;IAC9F,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAkB,SAAQ,QAAQ,CACjD,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACpB,KAAK,CACN;CAAG;AAEJ,eAAO,MAAM,iBAAiB,oDAAoD,CAAC;AAqBnF,eAAO,MAAM,IAAI,EAAE,WAAW,CAC5B,eAAe,EACf,OAAO,CAAC,UAAU,EAClB,oBAAoB,EAClB,OAAO,CAAC,kBAAkB,GAC1B,OAAO,CAAC,uBAAuB,GAC/B,OAAO,CAAC,0BAA0B,GAClC,OAAO,CAAC,0BAA0B,GAClC,0BAA0B,CAgD7B,CAAC;AAEF,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;CAAwB,CAAC;AAE9C,eAAO,MAAM,yBAAyB,2GACuD,CAAC"}

package/dist/grafana/index.d.ts

@@ -6,14 +6,20 @@
  *   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 DatasourceAttributes, type DatasourceProps, GrafanaDatasource, GrafanaDatasourceProvider, } from './datasource.ts';
 export { type DashboardAttributes, type DashboardModel, type DashboardProps, GrafanaDashboard, GrafanaDashboardProvider, } from './dashboard.ts';
 export { type FolderAttributes, type FolderProps, GrafanaFolder, 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';
 //# sourceMappingURL=index.d.ts.map

package/dist/grafana/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/grafana/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,aAAa,EACb,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,KAAK,aAAa,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/grafana/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,aAAa,EACb,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,mBAAmB,EACnB,2BAA2B,GAC5B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EACzB,sBAAsB,EACtB,8BAA8B,GAC/B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,KAAK,aAAa,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}