@homeflare/alchemy 0.31.2 → 0.33.0

package/src/grafana/dashboard.ts

@@ -0,0 +1,161 @@
+/**
+ * `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,
+  declaredContentMatches,
+  modelTitle,
+  normalizeModel,
+} from './dashboard-model.ts';
+import { type GrafanaProvisionedObjectError, refuseIfProvisioned } from './provisioned.ts';
+import { type GrafanaSpec, grafanaHandlers } 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 const GrafanaDashboard = Resource<GrafanaDashboard>('Grafana.Dashboard');
+
+const modelOf = (live: grafana.DashboardFullWithMeta): DashboardModel =>
+  live.dashboard !== null && typeof live.dashboard === 'object'
+    ? (live.dashboard as DashboardModel)
+    : {};
+
+export const spec: GrafanaSpec<
+  DashboardProps,
+  grafana.DashboardFullWithMeta,
+  DashboardAttributes,
+  | grafana.GetDashboardError
+  | grafana.PostDashboardError
+  | grafana.DeleteDashboardError
+  | GrafanaProvisionedObjectError
+> = {
+  attributes: (live, props) => {
+    const model = normalizeModel(modelOf(live), props.uid);
+    return {
+      dashboard: model,
+      folderUid: live.meta?.folderUid ?? '',
+      provisioned: live.meta?.provisioned ?? false,
+      provisionedExternalId: live.meta?.provisionedExternalId ?? '',
+      title: modelTitle(model),
+      uid: props.uid,
+      url: live.meta?.url ?? '',
+      version: live.meta?.version ?? 0,
+    };
+  },
+  create: (props) =>
+    grafana.postDashboard({
+      dashboard: normalizeModel(props.dashboard, props.uid),
+      ...(props.folderUid === undefined ? {} : { folderUid: props.folderUid }),
+    }),
+  destroy: (props, live) =>
+    Effect.gen(function* () {
+      if (live.meta?.provisioned) {
+        return yield* refuseIfProvisioned(
+          'Grafana.Dashboard',
+          props.uid,
+          live.meta.provisionedExternalId,
+        );
+      }
+      yield* grafana.deleteDashboard({ uid: props.uid });
+    }),
+  fetchLive: (props) =>
+    grafana
+      .getDashboard({ uid: props.uid })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  matches: (attributes, props) =>
+    (props.folderUid === undefined || attributes.folderUid === props.folderUid) &&
+    declaredContentMatches(normalizeModel(props.dashboard, props.uid), attributes.dashboard),
+  update: (props, live) =>
+    Effect.gen(function* () {
+      if (live.meta?.provisioned) {
+        return yield* refuseIfProvisioned(
+          'Grafana.Dashboard',
+          props.uid,
+          live.meta.provisionedExternalId,
+        );
+      }
+      return yield* grafana.postDashboard({
+        dashboard: {
+          ...normalizeModel(props.dashboard, props.uid),
+          ...(live.meta?.version === undefined ? {} : { version: live.meta.version }),
+        },
+        ...(props.folderUid === undefined ? {} : { folderUid: props.folderUid }),
+      });
+    }),
+};
+
+export const handlers = grafanaHandlers(spec);
+
+export const GrafanaDashboardProvider = () =>
+  Provider.effect(GrafanaDashboard, Effect.succeed(GrafanaDashboard.Provider.of(handlers)));

package/src/grafana/folder.test.ts

@@ -0,0 +1,212 @@
+/**
+ * `Grafana.Folder` against a fake Grafana — the observe-before-write "adopt" posture (S9/S10),
+ * the provisioned-object refusal (provisioned.ts) and the parentUid-is-create-only refusal, all
+ * through the REAL `@distilled.cloud/grafana` protocol. Mirrors `datasource.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { GrafanaFolderReparentError, spec } from './folder.ts';
+import { GrafanaProvisionedObjectError } from './provisioned.ts';
+import { grafanaOperations } from './resource.ts';
+
+const FOLDER_PATH = '/api/folders/team-dashboards';
+const CREATE_PATH = '/api/folders';
+
+const liveJson = {
+  id: 3,
+  managedBy: '',
+  parentUid: '',
+  title: 'Team Dashboards',
+  uid: 'team-dashboards',
+  url: '/dashboards/f/team-dashboards',
+  version: 1,
+};
+
+const props = { title: 'Team Dashboards', uid: 'team-dashboards' };
+
+describe('spec.fetchLive', () => {
+  test('a live folder decodes into typed attributes', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === FOLDER_PATH
+        ? Response.json(liveJson)
+        : fakeFailure(404, 'not found'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(live !== undefined && spec.attributes(live, props)).toEqual({
+      id: 3,
+      managedBy: '',
+      parentUid: '',
+      title: 'Team Dashboards',
+      uid: 'team-dashboards',
+      url: '/dashboards/f/team-dashboards',
+      version: 1,
+    });
+    expect(fake.seen).toEqual([{ method: 'GET', path: FOLDER_PATH }]);
+    // ⛔ THE POINT: a GET never carries a body — see the shared memory's "distilled JSON-encodes
+    //   unknown keys as a body even on a GET" trap.
+    expect(fake.bodies[0]).toBeUndefined();
+  });
+
+  test('a 404 folds to undefined', async () => {
+    const fake = fakeGrafana(() => fakeFailure(404, 'folder 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 only declared fields — parentUid omitted when undeclared', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'POST' && url.pathname === CREATE_PATH
+        ? Response.json(liveJson)
+        : fakeFailure(404, 'unexpected request'),
+    );
+    await Effect.runPromise(spec.create(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))));
+    expect(fake.bodies[0]).toEqual({ title: 'Team Dashboards', uid: 'team-dashboards' });
+  });
+
+  test('sends description and parentUid when declared', async () => {
+    const fake = fakeGrafana(() => Response.json(liveJson));
+    await Effect.runPromise(
+      spec
+        .create({ ...props, description: 'squad dashboards', parentUid: 'engineering' })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.bodies[0]).toMatchObject({
+      description: 'squad dashboards',
+      parentUid: 'engineering',
+    });
+  });
+});
+
+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 === FOLDER_PATH
+        ? Response.json(liveJson)
+        : fakeFailure(500, 'reconcile should not write when nothing changed'),
+    );
+    const after = await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(after.uid).toBe('team-dashboards');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+});
+
+describe('update', () => {
+  test('a title mismatch sends the live version for optimistic concurrency', async () => {
+    let updated = false;
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === FOLDER_PATH) {
+        return Response.json(updated ? { ...liveJson, title: 'Renamed' } : liveJson);
+      }
+      if (method === 'PUT' && url.pathname === FOLDER_PATH) {
+        updated = true;
+        return Response.json({ ...liveJson, title: 'Renamed' });
+      }
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile({ ...props, title: 'Renamed' })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    const put = fake.seen.findIndex((s) => s.method === 'PUT');
+    expect(put).toBeGreaterThanOrEqual(0);
+    expect(fake.bodies[put]).toMatchObject({ title: 'Renamed', version: 1 });
+  });
+
+  // ★ BOTH TESTS GO THROUGH `grafanaOperations(spec).reconcile`, NOT `spec.update` DIRECTLY —
+  //   `update` is optional on the shared `GrafanaSpec` type, and `reconcile` is what production
+  //   code actually calls; it also exercises the same `fetchLive` → `matches` → `update` sequence.
+  test('a parentUid mismatch refuses — updateFolder cannot reparent', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === FOLDER_PATH
+        ? Response.json(liveJson)
+        : fakeFailure(500, 'no write should be attempted'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .reconcile({ ...props, parentUid: 'engineering' })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaFolderReparentError);
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('a provisioned (managedBy set) folder refuses the write and sends nothing', async () => {
+    const provisioned = { ...liveJson, managedBy: 'repo' };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === FOLDER_PATH
+        ? Response.json(provisioned)
+        : fakeFailure(500, 'no write should be attempted'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .reconcile({ ...props, title: 'Renamed' })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaProvisionedObjectError);
+    expect(failure.message).toContain('repo');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+});
+
+describe('destroy', () => {
+  test('deletes a live, non-provisioned folder by uid', async () => {
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === FOLDER_PATH) return Response.json(liveJson);
+      if (method === 'DELETE' && url.pathname === FOLDER_PATH) {
+        return Response.json({ id: 3, message: 'ok', title: 'Team Dashboards' });
+      }
+      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: FOLDER_PATH },
+      { method: 'DELETE', path: FOLDER_PATH },
+    ]);
+  });
+
+  test('a provisioned folder refuses destroy and sends no DELETE', async () => {
+    const provisioned = { ...liveJson, managedBy: 'repo' };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === FOLDER_PATH
+        ? Response.json(provisioned)
+        : 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: FOLDER_PATH }]);
+  });
+});

package/src/grafana/folder.ts

@@ -0,0 +1,161 @@
+/**
+ * `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 Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import { type GrafanaProvisionedObjectError, refuseIfProvisioned } from './provisioned.ts';
+import { type GrafanaSpec, grafanaHandlers } 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 const GrafanaFolder = Resource<GrafanaFolder>('Grafana.Folder', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** A declared `parentUid` disagrees with the live folder's — `updateFolder` cannot reparent. */
+export class GrafanaFolderReparentError extends Data.TaggedError('GrafanaFolderReparentError')<{
+  readonly message: string;
+}> {}
+
+export const spec: GrafanaSpec<
+  FolderProps,
+  grafana.Folder,
+  FolderAttributes,
+  | grafana.CreateFolderError
+  | grafana.GetFolderByUIDError
+  | grafana.UpdateFolderError
+  | grafana.DeleteFolderError
+  | GrafanaProvisionedObjectError
+  | GrafanaFolderReparentError
+> = {
+  attributes: (live) => ({
+    id: live.id ?? 0,
+    managedBy: live.managedBy ?? '',
+    parentUid: live.parentUid ?? '',
+    title: live.title ?? '',
+    uid: live.uid ?? '',
+    url: live.url ?? '',
+    version: live.version ?? 0,
+  }),
+  create: (props) =>
+    grafana.createFolder({
+      uid: props.uid,
+      title: props.title,
+      ...(props.description === undefined ? {} : { description: props.description }),
+      ...(props.parentUid === undefined ? {} : { parentUid: props.parentUid }),
+    }),
+  destroy: (props, live) =>
+    Effect.gen(function* () {
+      if (live.managedBy) {
+        return yield* refuseIfProvisioned('Grafana.Folder', props.uid, live.managedBy);
+      }
+      yield* grafana.deleteFolder({ folder_uid: props.uid });
+    }),
+  fetchLive: (props) =>
+    grafana
+      .getFolderByUID({ folder_uid: props.uid })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  matches: (attributes, props) =>
+    attributes.title === props.title &&
+    (props.parentUid === undefined || attributes.parentUid === props.parentUid),
+  update: (props, live) =>
+    Effect.gen(function* () {
+      if (live.managedBy) {
+        return yield* refuseIfProvisioned('Grafana.Folder', props.uid, live.managedBy);
+      }
+      if (props.parentUid !== undefined && props.parentUid !== (live.parentUid ?? undefined)) {
+        return yield* Effect.fail(
+          new GrafanaFolderReparentError({
+            message:
+              `Grafana.Folder '${props.uid}' declares parentUid '${props.parentUid}' but is ` +
+              `live under '${live.parentUid ?? '(root)'}'. PUT /folders/{uid} cannot reparent a ` +
+              `folder — move it by hand in Grafana, then update the declaration to match.`,
+          }),
+        );
+      }
+      // ⚠️ UNLIKE DASHBOARD.TS's 412, THIS HAS NO VERIFIED CONFLICT SIGNAL. `version` is sent
+      //   optimistically, but the SDK's own doc comment on `UpdateFolderRequest.version` says
+      //   "only used by the legacy folder implementation" — on Grafana's newer unified-storage
+      //   folder backend it is plausibly ignored outright, meaning two concurrent title/description
+      //   writes could silently last-write-win with no error, unlike a dashboard save. NOT
+      //   MEASURED against a live instance either way (no live calls in this PR; flagged by an
+      //   adversarial review) — sending it is harmless (a no-op field on a backend that ignores it)
+      //   and correct on one that still honors it, so it stays, but do not read its PRESENCE here
+      //   as proof this resource detects folder update conflicts the way dashboard.ts does.
+      return yield* grafana.updateFolder({
+        folder_uid: props.uid,
+        title: props.title,
+        ...(props.description === undefined ? {} : { description: props.description }),
+        ...(live.version === undefined ? {} : { version: live.version }),
+      });
+    }),
+};
+
+export const handlers = grafanaHandlers(spec);
+
+export const GrafanaFolderProvider = () =>
+  Provider.effect(GrafanaFolder, Effect.succeed(GrafanaFolder.Provider.of(handlers)));

package/src/grafana/index.ts

@@ -2,15 +2,13 @@
  * 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` 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.
  */
 export {
   type DatasourceAttributes,
@@ -19,5 +17,20 @@ export {
   GrafanaDatasourceProvider,
   GrafanaSecretRefUnsetError,
 } 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 { GrafanaProvisionedObjectError } from './provisioned.ts';
 export { type GrafanaTarget, grafanaCredentials } from './credentials.ts';
 export { grafanaProviders } from './providers.ts';

package/src/grafana/providers.ts

@@ -13,7 +13,13 @@
  */
 import * as Layer from 'effect/Layer';
 import { type GrafanaTarget, grafanaCredentials } from './credentials.ts';
+import { GrafanaDashboardProvider } from './dashboard.ts';
 import { GrafanaDatasourceProvider } from './datasource.ts';
+import { GrafanaFolderProvider } from './folder.ts';
 
 export const grafanaProviders = (target: GrafanaTarget) =>
-  GrafanaDatasourceProvider().pipe(Layer.provide(grafanaCredentials(target)));
+  Layer.mergeAll(
+    GrafanaDatasourceProvider(),
+    GrafanaFolderProvider(),
+    GrafanaDashboardProvider(),
+  ).pipe(Layer.provide(grafanaCredentials(target)));

package/src/grafana/provisioned.ts

@@ -0,0 +1,49 @@
+/**
+ * The shared refusal for a file-provisioned Grafana object — `Grafana.Folder` and
+ * `Grafana.Dashboard` both carry a live signal Grafana itself treats as read-only through the
+ * classic write API this family calls: `Folder.managedBy` (non-empty when something other than
+ * this API manages the folder — provisioning is the case this house cares about, but the field
+ * itself is Grafana's general "who owns this" marker) and `DashboardMeta.provisioned` (paired
+ * with `provisionedExternalId`, the file path). A declaration must never attempt a write against
+ * either — see docs/grafana-folder-dashboard.md's "provisioned objects" section.
+ *
+ * ⚠️ THE EXACT `managedBy` VALUES ARE INFERRED FROM THE SDK's SCHEMA, NOT MEASURED. No live
+ *   instance in this house currently has a file-provisioned FOLDER to read (docs/grafana.md:
+ *   `teslamate-grafana` has none at all; the mini's Grafana provisions dashboards, not folders) and
+ *   this PR makes no live calls. `Folder.managedBy` and `DashboardMeta.provisioned` are exactly
+ *   the fields the OpenAPI schema types for this purpose — treat any non-empty `managedBy` as
+ *   provisioned rather than special-casing specific string values that were never observed live.
+ *
+ * ⛔ ADOPTING A PROVISIONED OBJECT IS STILL FINE. `read`/`reconcile`'s no-write "already converged"
+ *   path (resource.ts) never calls `create`/`update`/`destroy` at all when the declaration already
+ *   matches what is live — only an actual attempted WRITE against a provisioned object is refused,
+ *   by the two callers of this function inside folder.ts/dashboard.ts's own `update`/`destroy`.
+ */
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+
+export class GrafanaProvisionedObjectError extends Data.TaggedError(
+  'GrafanaProvisionedObjectError',
+)<{
+  readonly message: string;
+}> {}
+
+export const refuseIfProvisioned = (
+  kind: 'Grafana.Folder' | 'Grafana.Dashboard',
+  uid: string,
+  owner: string | undefined,
+): Effect.Effect<never, GrafanaProvisionedObjectError> => {
+  const ownerClause =
+    owner === undefined || owner === ''
+      ? `(this Grafana instance did not report an owning file)`
+      : `by ${owner}`;
+  return Effect.fail(
+    new GrafanaProvisionedObjectError({
+      message:
+        `${kind} '${uid}' is file-provisioned ${ownerClause} and read-only through the classic ` +
+        `write API this family calls. Edit the provisioning file instead — declaring this ` +
+        `object read-only (a declaration matching what is live) is safe and will never reach ` +
+        `this refusal.`,
+    }),
+  );
+};