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

@@ -0,0 +1,47 @@
+/**
+ * Pure functions over a dashboard JSON model — no SDK call, no Effect. Split out of dashboard.ts
+ * so that file stays under the house's 250-line cap, and so `normalizeModel`'s no-change-is-noop
+ * behavior is exercised directly in dashboard-model.test.ts without a fake Grafana in the way.
+ */
+export type DashboardModel = Record<string, unknown>;
+/**
+ * ★ NORMALIZES BOTH SIDES THE SAME WAY, so a no-change plan is a true noop
+ *   (docs/grafana-folder-dashboard.md). Strips `id`/`version`/`iteration` (Grafana-managed, never
+ *   declared content) and forces `uid` to this resource's OWN canonical value, wherever — or
+ *   whether — the source object carried one. That second part is "uid placement": a dashboard
+ *   pasted from Grafana's own "Export as JSON" always embeds the OLD live uid (or none, for a
+ *   never-saved dashboard), while the live model this resource reads back always carries the
+ *   CURRENT one; forcing both to `props.uid` before comparing is what makes those two shapes equal
+ *   instead of permanently disagreeing on one field neither side is meant to declare independently
+ *   (`DashboardProps.uid` — see dashboard.ts — is the single source of truth).
+ *
+ * ⚠️ EVERY OTHER DECLARED FIELD COMPARES STRUCTURALLY, ARRAY ORDER INCLUDED — dashboard.ts's
+ *   `matches` runs this output through THIS FILE's own `declaredContentMatches` (below), which
+ *   never reorders an array. That is correct here: `panels` is position-significant (screen layout
+ *   via its own `gridPos`, but the array order also drives Grafana's internal panel indexing and
+ *   any `repeat` behavior) and each panel's `targets` is execution/legend order. Nothing in a
+ *   dashboard model is a genuinely unordered SET the way UniFi's `trustedDhcpServerIpAddresses` is
+ *   (unifi/network-form.ts's `sortedSet`) — this family has no field that needs one.
+ * ⚠️ `schemaVersion` IS DELIBERATELY **NOT** NORMALIZED — NOT MEASURED against a live instance (no
+ *   live calls in this PR). Community reports say Grafana can rewrite an old dashboard's
+ *   `schemaVersion` upward on load; IF that also happens on every plain save of an
+ *   already-current-schema dashboard, every plan against it would show a false `update` forever —
+ *   but silently normalizing it away on a guess would just as easily hide a genuine schema
+ *   mismatch. Left comparing until measured: add it to `VOLATILE_FIELDS` with a dated, measured
+ *   comment the day it is seen live, the same standard every other row in this file meets.
+ */
+export declare const normalizeModel: (model: DashboardModel, uid: string) => DashboardModel;
+/** The model's own declared title — reporting only. It is never compared on its own; the whole
+ *  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` — 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 { declaredContentMatches } from './subset-match.ts';
+//# sourceMappingURL=dashboard-model.d.ts.map

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

@@ -0,0 +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;AAErD;;;;;;;;GAQG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/grafana/dashboard.d.ts

@@ -0,0 +1,98 @@
+/**
+ * `Grafana.Dashboard` — one Grafana dashboard, keyed by `uid`. Same uid-required doctrine as
+ * `datasource.ts`/`folder.ts` (`getDashboard`/`postDashboard`/`deleteDashboard` are all UID-keyed
+ * on the wire — `postDashboard`'s own `uid` travels INSIDE the `dashboard` JSON body, not as a
+ * request field, because Grafana's classic dashboard-save API has never had one; see
+ * `dashboard-model.ts`'s `normalizeModel`, which is what puts it there).
+ *
+ * ★ THE DECLARED CONTENT IS THE DASHBOARD JSON MODEL — `DashboardProps.dashboard`, the same shape
+ *   Grafana's own "Export as JSON" produces. `dashboard-model.ts`'s `normalizeModel` strips the
+ *   volatile fields (`id`, `version`, `iteration`) and forces `uid` to this resource's own value
+ *   before ANY comparison, so a plan against an unchanged dashboard is a true noop despite those
+ *   fields moving on every live save — see that file for the full reasoning, including which
+ *   fields (`panels`, `targets`) are array-ORDER-significant and compared as such.
+ *
+ * ⛔ `matches` COMPARES "IS THE DECLARATION A SUBSET OF WHAT IS LIVE", NOT PLAIN EQUALITY —
+ *   `dashboard-model.ts`'s `declaredContentMatches`, added after an adversarial review of this PR
+ *   found plain `deepEqual` made an ordinary dashboard show `update` FOREVER: Grafana's own
+ *   schema-migration on save decorates any panel/target whose `datasource` is absent with an
+ *   explicit reference, so a declaration that never sets one would permanently disagree with what
+ *   it reads back. See that function's own header for the full reasoning and the trade-off it
+ *   accepts (an omitted field can no longer be used to CLEAR a previously-set one).
+ *
+ * ⛔ VERSION CONFLICTS (412) FAIL LOUDLY — NEVER OVERWRITTEN BLINDLY. `update` injects the
+ *   `version` this resource just read (`live.meta.version`, from the SAME `fetchLive` call
+ *   `resource.ts`'s `reconcile` already made before calling `update`) into the model it sends, and
+ *   `overwrite` is never set. If Grafana's own version check then still fails — someone else saved
+ *   in the gap between that read and this write — `postDashboard` answers `412` and
+ *   `PreconditionFailed` is left IN the error union below, uncaught: the whole reconcile fails, the
+ *   deploy stops, and nothing is written. The next run's `fetchLive` re-reads the new live version
+ *   fresh, which is the "re-read" half of "re-read and fail loudly" — there is no separate retry
+ *   loop in this file, because the next `plan`/`deploy` invocation already IS that re-read.
+ *
+ * ⛔ A PROVISIONED DASHBOARD (`meta.provisioned` — see provisioned.ts) REFUSES EVERY UPDATE AND
+ *   DESTROY, naming `meta.provisionedExternalId` (the file) when Grafana reports one. `matches`
+ *   still compares structurally regardless, so a mismatched declaration against a provisioned
+ *   dashboard shows `update` in a plan rather than a silent, permanently-hidden noop.
+ *
+ * ⚠️ NO RETAIN DEFAULT, UNLIKE `Grafana.Folder`. Deleting one dashboard is a single-object blast
+ *   radius — the same class `Grafana.Datasource` already accepts without a retain guard — not
+ *   folder.ts's multi-object cascade (a folder's delete takes its dashboards AND their alert rules
+ *   with it). See folder.ts's file header for the full contrast.
+ */
+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 DashboardModel } from './dashboard-model.ts';
+import { type GrafanaProvisionedObjectError } from './provisioned.ts';
+import { type GrafanaSpec } from './resource.ts';
+export type { DashboardModel };
+export interface DashboardProps {
+    uid: string;
+    /** Omit for the General/root folder. */
+    folderUid?: string;
+    /** The dashboard JSON model — see the file header. `id`/`version`/`iteration`/`uid` inside it
+     *  are ignored; `uid` above is the single source of truth. */
+    dashboard: DashboardModel;
+}
+export interface DashboardAttributes {
+    uid: string;
+    title: string;
+    version: number;
+    folderUid: string;
+    url: string;
+    /** True when Grafana reports this dashboard as file-provisioned (read-only — see provisioned.ts). */
+    provisioned: boolean;
+    provisionedExternalId: string;
+    /** The live model, normalized the same way `matches` compares it. */
+    dashboard: DashboardModel;
+}
+export interface GrafanaDashboard extends Resource<'Grafana.Dashboard', DashboardProps, DashboardAttributes, never> {
+}
+export declare const GrafanaDashboard: import("alchemy").ResourceClass<GrafanaDashboard>;
+export declare const spec: GrafanaSpec<DashboardProps, grafana.DashboardFullWithMeta, DashboardAttributes, grafana.GetDashboardError | grafana.PostDashboardError | grafana.DeleteDashboardError | GrafanaProvisionedObjectError>;
+export declare const handlers: {
+    list: () => Effect.Effect<never[], never, never>;
+    read: ({ olds }: {
+        olds: DashboardProps;
+    }) => Effect.Effect<DashboardAttributes | undefined, grafana.BadGateway | import("@distilled.cloud/caddy").BadRequest | grafana.BadRequest | grafana.ConfigError | import("@distilled.cloud/caddy").Conflict | import("@distilled.cloud/caddy").Forbidden | grafana.Forbidden | grafana.GatewayTimeout | GrafanaProvisionedObjectError | import("effect/unstable/http/HttpClientError").HttpClientError | grafana.InternalServerError | grafana.Locked | import("@distilled.cloud/caddy").NotFound | grafana.NotFound | grafana.PreconditionFailed | grafana.ServiceUnavailable | grafana.TooManyRequests | grafana.Unauthorized | grafana.UnknownGrafanaError | import("@distilled.cloud/caddy").UnprocessableEntity | grafana.UnprocessableEntity, grafana.GrafanaOpContext>;
+    diff: ({ news, output }: {
+        news: import("alchemy").Input<DashboardProps>;
+        output: DashboardAttributes | 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 | import("@distilled.cloud/caddy").Forbidden | grafana.Forbidden | grafana.GatewayTimeout | GrafanaProvisionedObjectError | import("effect/unstable/http/HttpClientError").HttpClientError | grafana.InternalServerError | grafana.Locked | import("@distilled.cloud/caddy").NotFound | grafana.NotFound | grafana.PreconditionFailed | grafana.ServiceUnavailable | grafana.TooManyRequests | grafana.Unauthorized | grafana.UnknownGrafanaError | import("@distilled.cloud/caddy").UnprocessableEntity | grafana.UnprocessableEntity, grafana.GrafanaOpContext>;
+    reconcile: ({ news }: {
+        news: DashboardProps;
+    }) => Effect.Effect<DashboardAttributes, grafana.BadGateway | import("@distilled.cloud/caddy").BadRequest | grafana.BadRequest | grafana.ConfigError | import("@distilled.cloud/caddy").Conflict | import("@distilled.cloud/caddy").Forbidden | grafana.Forbidden | grafana.GatewayTimeout | GrafanaProvisionedObjectError | import("effect/unstable/http/HttpClientError").HttpClientError | grafana.InternalServerError | grafana.Locked | import("@distilled.cloud/caddy").NotFound | grafana.NotFound | grafana.PreconditionFailed | grafana.ServiceUnavailable | grafana.TooManyRequests | grafana.Unauthorized | grafana.UnknownGrafanaError | import("@distilled.cloud/caddy").UnprocessableEntity | grafana.UnprocessableEntity, grafana.GrafanaOpContext>;
+    delete: ({ olds }: {
+        olds: DashboardProps;
+    }) => Effect.Effect<void, grafana.BadGateway | import("@distilled.cloud/caddy").BadRequest | grafana.BadRequest | grafana.ConfigError | import("@distilled.cloud/caddy").Conflict | import("@distilled.cloud/caddy").Forbidden | grafana.Forbidden | grafana.GatewayTimeout | GrafanaProvisionedObjectError | import("effect/unstable/http/HttpClientError").HttpClientError | grafana.InternalServerError | grafana.Locked | import("@distilled.cloud/caddy").NotFound | grafana.NotFound | grafana.PreconditionFailed | grafana.ServiceUnavailable | grafana.TooManyRequests | grafana.Unauthorized | grafana.UnknownGrafanaError | import("@distilled.cloud/caddy").UnprocessableEntity | grafana.UnprocessableEntity, grafana.GrafanaOpContext>;
+};
+export declare const GrafanaDashboardProvider: () => import("effect/Layer").Layer<Provider.Provider<GrafanaDashboard>, never, grafana.GrafanaOpContext>;
+//# sourceMappingURL=dashboard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../../src/grafana/dashboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;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,cAAc,EAIpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,6BAA6B,EAAuB,MAAM,kBAAkB,CAAC;AAC3F,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,eAAe,CAAC;AAElE,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;kEAC8D;IAC9D,SAAS,EAAE,cAAc,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,qGAAqG;IACrG,WAAW,EAAE,OAAO,CAAC;IACrB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,qEAAqE;IACrE,SAAS,EAAE,cAAc,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAiB,SAAQ,QAAQ,CAChD,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,KAAK,CACN;CAAG;AAEJ,eAAO,MAAM,gBAAgB,mDAAkD,CAAC;AAOhF,eAAO,MAAM,IAAI,EAAE,WAAW,CAC5B,cAAc,EACd,OAAO,CAAC,qBAAqB,EAC7B,mBAAmB,EACjB,OAAO,CAAC,iBAAiB,GACzB,OAAO,CAAC,kBAAkB,GAC1B,OAAO,CAAC,oBAAoB,GAC5B,6BAA6B,CAuDhC,CAAC;AAEF,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;CAAwB,CAAC;AAE9C,eAAO,MAAM,wBAAwB,0GACsD,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/folder.d.ts

@@ -0,0 +1,100 @@
+/**
+ * `Grafana.Folder` — one Grafana folder, keyed by `uid`. Mirrors `datasource.ts`'s shape and
+ * doctrine (uid required, not generated — same reasoning, `getFolderByUID`/`updateFolder`/
+ * `deleteFolder` are all UID-keyed and `getFolders` (list) has no per-uid filter).
+ *
+ * ⛔ `description` IS WRITE-ONLY — MEASURED against `@distilled.cloud/grafana`'s generated types
+ *   (`Folder` in services/grafana.ts has no `description` field at all, though
+ *   `CreateFolderRequest`/`UpdateFolderRequest` both accept one). Grafana's classic folder GET
+ *   never returns it, not even as an is-it-set flag the way `DataSource.secureJsonFields` reports
+ *   for a datasource's secure fields. So `description` is sent on every create/update that
+ *   declares it but is NEVER part of `matches` — this resource cannot detect drift in a value it
+ *   is never shown, the same treatment `datasource.ts` gives `secureJsonDataRefs`.
+ *
+ * ⚠️ NESTING (`parentUid`) IS CREATE-ONLY — MEASURED against the same generated types.
+ *   `CreateFolderRequest.parentUid` exists; `UpdateFolderRequest` has no `parentUid` field at all
+ *   (`folder_uid`, `description`, `overwrite`, `title`, `version` — reparenting is simply not a
+ *   thing `PUT /folders/{uid}` can do). A declaration whose `parentUid` no longer matches the live
+ *   folder therefore REFUSES with `GrafanaFolderReparentError` rather than either silently doing
+ *   nothing (which would lie about the declaration taking effect) or deleting and recreating the
+ *   folder under the new parent (which — see the ⛔ below — takes every dashboard and alert rule in
+ *   it with it). Move a folder by hand in Grafana, then adjust the declaration to match.
+ *
+ * ⛔ DELETE DEFAULTS TO `retain` — DELETING A FOLDER DELETES ITS DASHBOARDS AND ALERT RULES IN
+ *   GRAFANA, per `deleteFolder`'s own operation description ("along with all dashboards (and their
+ *   alerts) stored in the folder... cannot be reverted... also deletes all the subfolders"). That
+ *   is the same class of multi-object cascade `openbao/mount.ts` guards with
+ *   `defaultRemovalPolicy: 'retain'` ("disabling a mount destroys every secret under it") — VERIFIED
+ *   there against Alchemy's own `Apply.ts` (not re-verified here; same engine, same option). A
+ *   stack that explicitly wants the cascade opts in with `.pipe(RemovalPolicy.destroy())` on the
+ *   declared instance; `destroy` below still implements the real DELETE in full either way (S11).
+ *   `Grafana.Dashboard` does NOT default to retain — deleting one dashboard is the same
+ *   single-object blast radius `Grafana.Datasource` already accepts without a retain guard, not
+ *   this family's multi-object cascade.
+ *
+ * ⛔ A PROVISIONED FOLDER (`managedBy` set — see provisioned.ts) REFUSES EVERY UPDATE AND DESTROY.
+ *   `matches` still compares structurally either way, so a mismatched declaration against a
+ *   provisioned folder shows `update` in a plan (never a silent, permanently-hidden noop) and then
+ *   fails loudly, by design, when reconcile actually tries to write.
+ */
+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 './provisioned.ts';
+import { type GrafanaSpec } from './resource.ts';
+export interface FolderProps {
+    uid: string;
+    title: string;
+    /** Write-only — see the file header. Sent on every create/update that declares it; never diffed. */
+    description?: string;
+    /** Parent folder UID, for nested folders. Create-only — see the file header. */
+    parentUid?: string;
+}
+export interface FolderAttributes {
+    uid: string;
+    id: number;
+    title: string;
+    parentUid: string;
+    /** Non-empty when Grafana reports this folder as externally managed (e.g. provisioning). */
+    managedBy: string;
+    url: string;
+    version: number;
+}
+export interface GrafanaFolder extends Resource<'Grafana.Folder', FolderProps, FolderAttributes, never> {
+}
+export declare const GrafanaFolder: import("alchemy").ResourceClass<GrafanaFolder>;
+declare const GrafanaFolderReparentError_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: "GrafanaFolderReparentError";
+} & Readonly<A>;
+/** A declared `parentUid` disagrees with the live folder's — `updateFolder` cannot reparent. */
+export declare class GrafanaFolderReparentError extends GrafanaFolderReparentError_base<{
+    readonly message: string;
+}> {
+}
+export declare const spec: GrafanaSpec<FolderProps, grafana.Folder, FolderAttributes, grafana.CreateFolderError | grafana.GetFolderByUIDError | grafana.UpdateFolderError | grafana.DeleteFolderError | GrafanaProvisionedObjectError | GrafanaFolderReparentError>;
+export declare const handlers: {
+    list: () => Effect.Effect<never[], never, never>;
+    read: ({ olds }: {
+        olds: FolderProps;
+    }) => Effect.Effect<FolderAttributes | 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 | GrafanaFolderReparentError | GrafanaProvisionedObjectError | 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>;
+    diff: ({ news, output }: {
+        news: import("alchemy").Input<FolderProps>;
+        output: FolderAttributes | 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 | GrafanaFolderReparentError | GrafanaProvisionedObjectError | 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>;
+    reconcile: ({ news }: {
+        news: FolderProps;
+    }) => Effect.Effect<FolderAttributes, 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 | GrafanaFolderReparentError | GrafanaProvisionedObjectError | 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>;
+    delete: ({ olds }: {
+        olds: FolderProps;
+    }) => 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 | GrafanaFolderReparentError | GrafanaProvisionedObjectError | 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 GrafanaFolderProvider: () => import("effect/Layer").Layer<Provider.Provider<GrafanaFolder>, never, grafana.GrafanaOpContext>;
+export {};
+//# sourceMappingURL=folder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"folder.d.ts","sourceRoot":"","sources":["../../src/grafana/folder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;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,6BAA6B,EAAuB,MAAM,kBAAkB,CAAC;AAC3F,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,eAAe,CAAC;AAElE,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,oGAAoG;IACpG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,4FAA4F;IAC5F,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAc,SAAQ,QAAQ,CAC7C,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,KAAK,CACN;CAAG;AAEJ,eAAO,MAAM,aAAa,gDAExB,CAAC;;;;AAEH,gGAAgG;AAChG,qBAAa,0BAA2B,SAAQ,gCAA+C;IAC7F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;CAAG;AAEL,eAAO,MAAM,IAAI,EAAE,WAAW,CAC5B,WAAW,EACX,OAAO,CAAC,MAAM,EACd,gBAAgB,EACd,OAAO,CAAC,iBAAiB,GACzB,OAAO,CAAC,mBAAmB,GAC3B,OAAO,CAAC,iBAAiB,GACzB,OAAO,CAAC,iBAAiB,GACzB,6BAA6B,GAC7B,0BAA0B,CA+D7B,CAAC;AAEF,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;CAAwB,CAAC;AAE9C,eAAO,MAAM,qBAAqB,uGACmD,CAAC"}

package/dist/grafana/index.d.ts

@@ -2,17 +2,24 @@
  * Grafana providers for Alchemy.
  *
  * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY. These are
- *   the symbols a real stack consumes; the rest of the files (resource.ts's engine, fake-grafana.ts)
- *   are internals a provider needs but a consumer should not depend on.
+ *   the symbols a real stack consumes; the rest of the files (resource.ts's engine, provisioned.ts,
+ *   dashboard-model.ts, fake-grafana.ts) are internals a provider needs but a consumer should not
+ *   depend on.
  *
- * ⛔ ONLY `Grafana.Datasource` SHIPS HERE. `@distilled.cloud/grafana` (aliased onto
- *   `@homeflare/distilled-grafana` — see docs/distilled-interim.md) now HAS folder, dashboard and
- *   alerting-provisioning CRUD operations — the SDK-level gap docs/grafana.md and
- *   docs/upstream-conformance.md recorded is fixed. Building `Grafana.Folder`, `Grafana.Dashboard`,
- *   `Grafana.AlertRule` etc. on top of them is follow-up work this PR deliberately does not do —
- *   see docs/grafana.md for what changed 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;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AACzB,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"}