@homeflare/alchemy 0.29.1 → 0.31.0

package/src/grafana/datasource.test.ts

@@ -0,0 +1,183 @@
+/**
+ * `Grafana.Datasource` against a fake Grafana, proving the tagged-error paths, the secure-field
+ * reference seam (S25) and the observe-before-write "adopt" posture (S9/S10) — all through the
+ * REAL `@distilled.cloud/grafana` protocol (path assembly, JSON decode, status→typed-error
+ * matching), not re-implemented by hand. Mirrors `../forgejo/repository.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { grafanaOperations } from './resource.ts';
+import { GrafanaSecretRefUnsetError, spec } from './datasource.ts';
+
+const DS_PATH = '/api/datasources/uid/teslamate';
+const CREATE_PATH = '/api/datasources';
+
+const liveJson = {
+  access: 'proxy',
+  id: 7,
+  isDefault: true,
+  name: 'TeslaMate',
+  orgId: 1,
+  readOnly: false,
+  type: 'postgres',
+  uid: 'teslamate',
+  url: '127.0.0.1:5432',
+  version: 1,
+};
+
+const props = { name: 'TeslaMate', type: 'postgres', uid: 'teslamate' };
+
+describe('spec.fetchLive', () => {
+  test('a live datasource decodes into typed attributes', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === DS_PATH
+        ? Response.json(liveJson)
+        : fakeFailure(404, 'not found'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(live?.name).toBe('TeslaMate');
+    expect(live !== undefined && spec.attributes(live, props)).toEqual({
+      access: 'proxy',
+      id: 7,
+      isDefault: true,
+      name: 'TeslaMate',
+      orgId: 1,
+      readOnly: false,
+      type: 'postgres',
+      uid: 'teslamate',
+      url: '127.0.0.1:5432',
+      version: 1,
+    });
+    expect(fake.seen).toEqual([{ method: 'GET', path: DS_PATH }]);
+  });
+
+  test('a 404 folds to undefined — the exact idiom this family uses', async () => {
+    const fake = fakeGrafana(() => fakeFailure(404, 'Data source not found'));
+    const result = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(result).toBeUndefined();
+  });
+
+  test('a 401 propagates — Unauthorized is a real failure, never folded to absent', async () => {
+    const fake = fakeGrafana(() => fakeFailure(401, 'bad token'));
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('Unauthorized');
+  });
+});
+
+describe('secure field references (S25)', () => {
+  const ENV_VAR = 'GRAFANA_FAMILY_TEST_DS_PASSWORD';
+
+  test('create resolves the env var fresh and sends it as secureJsonData, never as a prop', async () => {
+    process.env[ENV_VAR] = 's3cret';
+    try {
+      const fake = fakeGrafana((method, url) =>
+        method === 'POST' && url.pathname === CREATE_PATH
+          ? Response.json({ datasource: liveJson, id: 7, message: 'ok', name: 'TeslaMate' })
+          : fakeFailure(404, 'unexpected request'),
+      );
+      await Effect.runPromise(
+        spec
+          .create({ ...props, secureJsonDataRefs: { password: ENV_VAR } })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      );
+      expect(fake.seen).toEqual([{ method: 'POST', path: CREATE_PATH }]);
+      // ⛔ THE POINT OF THIS TEST. Asserting only that a POST landed proves nothing about what it
+      //   carried — this is where a dropped `secureJsonData` spread would actually be caught.
+      expect(fake.bodies[0]).toMatchObject({ secureJsonData: { password: 's3cret' } });
+    } finally {
+      delete process.env[ENV_VAR];
+    }
+  });
+
+  test('create refuses with a typed error when the ref is unset — and never sends the request', async () => {
+    const fake = fakeGrafana(() => fakeFailure(500, 'should not be reached'));
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        spec
+          .create({ ...props, secureJsonDataRefs: { password: 'DEFINITELY_UNSET_VAR_XYZ' } })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaSecretRefUnsetError);
+    expect(fake.seen).toEqual([]);
+  });
+});
+
+describe('reconcile — adopt semantics', () => {
+  test('declaring exactly what is live is a noop: no create or update is ever sent', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === DS_PATH
+        ? Response.json(liveJson)
+        : fakeFailure(500, 'reconcile should not write when nothing changed'),
+    );
+    const ops = grafanaOperations(spec);
+    const after = await Effect.runPromise(
+      ops
+        .reconcile({ ...props, access: 'proxy', isDefault: true })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(after.uid).toBe('teslamate');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('a genuinely absent uid is created', async () => {
+    // ⚠️ STATEFUL ON PURPOSE. `reconcile` reads back AFTER writing (S9/S10) — a fake that always
+    //   404s the GET would make that read-back indistinguishable from the "write lied" defect
+    //   `resource.ts` raises, so the second GET must see what the POST just created.
+    let created = false;
+    const newOne = { ...liveJson, uid: 'new-one' };
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === '/api/datasources/uid/new-one') {
+        return created ? Response.json(newOne) : fakeFailure(404, 'not found');
+      }
+      if (method === 'POST' && url.pathname === CREATE_PATH) {
+        created = true;
+        return Response.json({ datasource: newOne, id: 7, message: 'ok', name: 'TeslaMate' });
+      }
+      return fakeFailure(500, 'unexpected request');
+    });
+    const ops = grafanaOperations(spec);
+    await Effect.runPromise(
+      ops
+        .reconcile({ ...props, uid: 'new-one' })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen.some((s) => s.method === 'POST' && s.path === CREATE_PATH)).toBe(true);
+  });
+});
+
+describe('destroy', () => {
+  test('deletes a live datasource by uid', async () => {
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === DS_PATH) return Response.json(liveJson);
+      if (method === 'DELETE' && url.pathname === DS_PATH) return Response.json({ message: 'ok' });
+      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: DS_PATH },
+      { method: 'DELETE', path: DS_PATH },
+    ]);
+  });
+
+  test('destroying an absent uid sends no DELETE — idempotent (S11)', async () => {
+    const fake = fakeGrafana(() => fakeFailure(404, 'not found'));
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .destroy(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen).toEqual([{ method: 'GET', path: DS_PATH }]);
+  });
+});

package/src/grafana/datasource.ts

@@ -0,0 +1,171 @@
+/**
+ * `Grafana.Datasource` — one Grafana data source, keyed by `uid`.
+ *
+ * ★ WHY `uid` IS REQUIRED, NOT GENERATED. `getDataSourceByUID`/`updateDataSourceByUID`/
+ *   `deleteDataSourceByUID` are all UID-keyed, and `getDataSources` (list) takes no filter — so
+ *   locating a datasource this resource didn't create means listing the whole org and matching by
+ *   name, the same ambiguity netbox/resource.ts's `soleMatch` exists to catch. Requiring `uid` up
+ *   front (Grafana accepts a caller-chosen one on create — `AddDataSourceRequest.uid`) sidesteps
+ *   it entirely: `read`/`reconcile`/`destroy` all key on the one field the API itself is keyed on.
+ *   `teslamate-grafana`'s live datasource (provisioned from a file, not this resource) has a
+ *   Grafana-generated uid; the census in the handoff script records it so a first declaration can
+ *   name it explicitly.
+ *
+ * ⛔ `secureJsonData` (e.g. a datasource password) NEVER APPEARS AS A LITERAL PROP (S25).
+ *   `secureJsonDataRefs` takes env var NAMES instead; `resolveSecureJsonData` reads them from
+ *   `process.env` fresh inside `create`/`update`'s own effect, never at plan time and never
+ *   returned in `attributes` — Grafana's own read API agrees: `DataSource.secureJsonFields` on a
+ *   GET is a map of booleans (is-it-set), never the value.
+ */
+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 GrafanaSpec, grafanaHandlers } from './resource.ts';
+
+export interface DatasourceProps {
+  uid: string;
+  name: string;
+  /** e.g. `postgres`, `prometheus`, `influxdb` — the Grafana plugin id. */
+  type: string;
+  url?: string;
+  access?: 'proxy' | 'direct';
+  database?: string;
+  user?: string;
+  basicAuth?: boolean;
+  basicAuthUser?: string;
+  isDefault?: boolean;
+  withCredentials?: boolean;
+  jsonData?: Record<string, unknown>;
+  /** Secure field name (e.g. `password`) -> env var NAME holding its value. Never the value. */
+  secureJsonDataRefs?: Record<string, string>;
+}
+
+export interface DatasourceAttributes {
+  uid: string;
+  id: number;
+  name: string;
+  type: string;
+  url: string;
+  access: string;
+  orgId: number;
+  isDefault: boolean;
+  readOnly: boolean;
+  version: number;
+}
+
+export interface GrafanaDatasource extends Resource<
+  'Grafana.Datasource',
+  DatasourceProps,
+  DatasourceAttributes,
+  never
+> {}
+
+export const GrafanaDatasource = Resource<GrafanaDatasource>('Grafana.Datasource');
+
+/** A named secure-field env var is unset — a domain refusal, not a distilled error. */
+export class GrafanaSecretRefUnsetError extends Data.TaggedError('GrafanaSecretRefUnsetError')<{
+  readonly message: string;
+}> {}
+
+/** Reads every named env var fresh, inside the caller's effect (S24) — never at plan time. */
+const resolveSecureJsonData = (
+  refs: Record<string, string> | undefined,
+): Effect.Effect<Record<string, string> | undefined, GrafanaSecretRefUnsetError> =>
+  Effect.gen(function* () {
+    if (refs === undefined) return undefined;
+    const out: Record<string, string> = {};
+    for (const [field, envVar] of Object.entries(refs)) {
+      const raw = process.env[envVar];
+      if (raw === undefined || raw.trim() === '') {
+        return yield* Effect.fail(
+          new GrafanaSecretRefUnsetError({
+            message:
+              `${envVar} is unset. Export the value of secureJsonData.${field} there — ` +
+              'never as an Alchemy prop.',
+          }),
+        );
+      }
+      out[field] = raw.trim();
+    }
+    return out;
+  });
+
+/** `exactOptionalPropertyTypes` means an undeclared field must be OMITTED, never sent as `undefined`. */
+const fields = (props: DatasourceProps) => ({
+  name: props.name,
+  type: props.type,
+  ...(props.access === undefined ? {} : { access: props.access }),
+  ...(props.basicAuth === undefined ? {} : { basicAuth: props.basicAuth }),
+  ...(props.basicAuthUser === undefined ? {} : { basicAuthUser: props.basicAuthUser }),
+  ...(props.database === undefined ? {} : { database: props.database }),
+  ...(props.isDefault === undefined ? {} : { isDefault: props.isDefault }),
+  ...(props.jsonData === undefined ? {} : { jsonData: props.jsonData }),
+  ...(props.url === undefined ? {} : { url: props.url }),
+  ...(props.user === undefined ? {} : { user: props.user }),
+  ...(props.withCredentials === undefined ? {} : { withCredentials: props.withCredentials }),
+});
+
+export const spec: GrafanaSpec<
+  DatasourceProps,
+  grafana.DataSource,
+  DatasourceAttributes,
+  | grafana.AddDataSourceError
+  | grafana.GetDataSourceByUIDError
+  | grafana.UpdateDataSourceByUIDError
+  | grafana.DeleteDataSourceByUIDError
+  | GrafanaSecretRefUnsetError
+> = {
+  attributes: (live) => ({
+    access: live.access ?? '',
+    id: live.id ?? 0,
+    isDefault: live.isDefault ?? false,
+    name: live.name ?? '',
+    orgId: live.orgId ?? 0,
+    readOnly: live.readOnly ?? false,
+    type: live.type ?? '',
+    uid: live.uid ?? '',
+    url: live.url ?? '',
+    version: live.version ?? 0,
+  }),
+  create: (props) =>
+    Effect.flatMap(resolveSecureJsonData(props.secureJsonDataRefs), (secureJsonData) =>
+      grafana.addDataSource({
+        ...fields(props),
+        ...(secureJsonData === undefined ? {} : { secureJsonData }),
+        uid: props.uid,
+      }),
+    ),
+  destroy: (props) => grafana.deleteDataSourceByUID({ uid: props.uid }),
+  fetchLive: (props) =>
+    grafana
+      .getDataSourceByUID({ uid: props.uid })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  /**
+   * ⛔ AN UNDECLARED FIELD IS NEITHER COMPARED NOR SENT — the same rule every family in this
+   *   estate follows. `secureJsonDataRefs` is never compared: Grafana never returns the value to
+   *   diff against, only whether a field is set (`secureJsonFields`), so this resource cannot
+   *   detect drift in a secret's value — only in whether one is configured at all.
+   */
+  matches: (attributes, props) =>
+    (props.name === undefined || attributes.name === props.name) &&
+    (props.type === undefined || attributes.type === props.type) &&
+    (props.url === undefined || attributes.url === props.url) &&
+    (props.access === undefined || attributes.access === props.access) &&
+    (props.isDefault === undefined || attributes.isDefault === props.isDefault),
+  update: (props, live) =>
+    Effect.flatMap(resolveSecureJsonData(props.secureJsonDataRefs), (secureJsonData) =>
+      grafana.updateDataSourceByUID({
+        ...fields(props),
+        ...(secureJsonData === undefined ? {} : { secureJsonData }),
+        ...(live.version === undefined ? {} : { version: live.version }),
+        uid: props.uid,
+      }),
+    ),
+};
+
+export const handlers = grafanaHandlers(spec);
+
+export const GrafanaDatasourceProvider = () =>
+  Provider.effect(GrafanaDatasource, Effect.succeed(GrafanaDatasource.Provider.of(handlers)));

package/src/grafana/fake-grafana.ts

@@ -0,0 +1,64 @@
+/**
+ * A minimal in-memory Grafana HTTP API for this family's tests — an in-memory `fetch` handed to
+ * Effect's real `FetchHttpClient` through its `Fetch` reference, mirroring
+ * `../forgejo/fake-forgejo.ts` and `../netbox/fake-netbox.ts`. Tests exercise distilled's REAL
+ * path assembly, JSON encode/decode and status→typed-error matching (`404` → `NotFound`, `403` →
+ * `Forbidden`, …) — nothing about that matching is re-implemented here, only the wire responses a
+ * scenario needs.
+ *
+ * ⛔ TEST-ONLY, AND NO NETWORK. No provider imports this file. The base URL is RFC 2606
+ *   `grafana.example.com`, and the token is a placeholder.
+ */
+import { type Credentials, fromApiKey } from '@distilled.cloud/grafana/Credentials';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+
+export const FAKE_BASE = 'https://grafana.example.com';
+export const FAKE_TOKEN = 'placeholder-grafana-token';
+
+export type Seen = { readonly method: string; readonly path: string };
+
+/** Grafana's `{ message?, status? }` failure envelope — matching the SDK's own protocol.ts note. */
+export const fakeFailure = (status: number, message: string) =>
+  Response.json({ message }, { status });
+
+/**
+ * `route` decides every response; this wrapper only records what was sent and adapts to
+ * `globalThis.fetch`'s signature. A test that expects no request at all asserts `seen` is empty.
+ *
+ * ★ `bodies` IS A SEPARATE, PARALLEL ARRAY (index-matched to `seen`), NOT FOLDED INTO IT — so
+ *   every existing `expect(fake.seen).toEqual([{method, path}, …])` stays exact rather than
+ *   growing an unrelated `body` key it would then have to repeat on every entry. A test that
+ *   cares what was actually sent (not just that a request was) reads `bodies[n]` instead of only
+ *   checking a request landed — the request landing is not proof of what it carried.
+ */
+export const fakeGrafana = (route: (method: string, url: URL, body: unknown) => Response) => {
+  const seen: Seen[] = [];
+  const bodies: unknown[] = [];
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    const text = await request.text();
+    const body: unknown = text === '' ? undefined : JSON.parse(text);
+    seen.push({ method: request.method, path: `${url.pathname}${url.search}` });
+    bodies.push(body);
+    return route(request.method, url, body);
+  }) as typeof globalThis.fetch;
+  return { fetch, seen, bodies };
+};
+
+/**
+ * distilled `Credentials` (via the SDK's own `fromApiKey`) + the real `FetchHttpClient` over the
+ * fake — `GrafanaOpContext`, what every resource file's exported `spec.fetchLive`/`create`/
+ * `update`/`destroy` needs. Unlike `grafanaHandlers`'s production callers, this never touches
+ * `process.env` — `grafanaCredentials` reads `tokenEnv` fresh per call (credentials.ts's own
+ * note), which a test-time `process.env` mutation cannot reliably reach either (measured for the
+ * same reason in the forgejo/netbox migrations: Effect's default `Config` provider snapshots the
+ * environment). Passing an explicit layer exercises exactly the same production code without
+ * that seam.
+ */
+export const fakeGrafanaLayer = (
+  fetchFn: typeof globalThis.fetch,
+  creds: Layer.Layer<Credentials> = fromApiKey({ apiBaseUrl: FAKE_BASE, apiKey: FAKE_TOKEN }),
+) => Layer.mergeAll(creds, FetchHttpClient.layer, Layer.succeed(FetchHttpClient.Fetch, fetchFn));

package/src/grafana/index.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ *
+ * ⛔ ONLY `Grafana.Datasource` SHIPS HERE. `@distilled.cloud/grafana@1.0.0-rc.12` has no folder,
+ *   dashboard, alert-rule or contact-point CRUD operations — see docs/grafana.md and
+ *   docs/upstream-conformance.md for the measured gap. Adding those resources now would mean
+ *   hand-rolling an `HttpClient` client for them, which S23 forbids for a vendor distilled
+ *   already covers in part; the right fix is upstream, in distilled, not a house workaround here.
+ */
+export {
+  type DatasourceAttributes,
+  type DatasourceProps,
+  GrafanaDatasource,
+  GrafanaDatasourceProvider,
+  GrafanaSecretRefUnsetError,
+} from './datasource.ts';
+export { type GrafanaTarget, grafanaCredentials } from './credentials.ts';
+export { grafanaProviders } from './providers.ts';

package/src/grafana/providers.ts

@@ -0,0 +1,19 @@
+/**
+ * The Grafana providers for one instance, with its credentials, as one layer for a stack.
+ *
+ *     Layer.mergeAll(grafanaProviders({ baseUrl: '...', tokenEnv: 'GRAFANA_TOKEN' }), …)
+ *
+ * ★ ONE CALL PER INSTANCE. A stack declaring resources against both `grafana.homeflare.dev` and
+ *   `teslamate-grafana` composes `grafanaProviders(targetA)` and `grafanaProviders(targetB)` —
+ *   each resource type's `Resource` constructor is a single global registration, so the SAME
+ *   `Grafana.Datasource` type serves both; only the credential layer differs per call.
+ * ⚠️ `HttpClient` is NOT provided here. It is ambient in every Alchemy runtime, the same as
+ *   `litellmProviders`/`netboxProviders`-style families in this kit assume; a stack that already
+ *   deploys anything over HTTP already has one.
+ */
+import * as Layer from 'effect/Layer';
+import { type GrafanaTarget, grafanaCredentials } from './credentials.ts';
+import { GrafanaDatasourceProvider } from './datasource.ts';
+
+export const grafanaProviders = (target: GrafanaTarget) =>
+  GrafanaDatasourceProvider().pipe(Layer.provide(grafanaCredentials(target)));

package/src/grafana/resource.ts

@@ -0,0 +1,120 @@
+/**
+ * One shape for every Grafana object this family declares — mirroring `../forgejo/resource.ts`
+ * and `../netbox/resource.ts` exactly, minus the credentials wrapping those two bake in.
+ *
+ * ★ CREDENTIALS ARE NOT PROVIDED HERE. Forgejo and NetBox each manage exactly one instance for
+ *   this house, so their engines close over a hardcoded `CredentialsFromEnv`. Grafana does not —
+ *   see `credentials.ts`'s note on `grafana.homeflare.dev` vs `teslamate-grafana` — so `Credentials`
+ *   stays a context requirement on every handler here, and `providers.ts`'s `grafanaProviders`
+ *   supplies it per target with `Layer.provide`, the same composition `litellm/providers.ts` uses.
+ *
+ * ⚠️ `NotFound` IS FOLDED TO "ABSENT" INSIDE EACH RESOURCE FILE'S OWN `fetchLive`, NOT HERE — the
+ *   same split forgejo's and netbox's engines use. `Effect.catchTag`'s tag-literal inference needs
+ *   a concrete error union to resolve `"NotFound"` against; a spec's `E` is only concrete at each
+ *   resource file's own call site.
+ */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import type { GrafanaOpContext } from '@distilled.cloud/grafana/Protocol';
+import * as Effect from 'effect/Effect';
+
+/**
+ * One Grafana object's distilled calls. `Live` is whatever the SDK decodes (a `DataSource`, …) —
+ * no untyped `Record<string, unknown>`. `E` is left to each resource file to declare (the union
+ * of the distilled operations it actually calls plus any domain refusal, e.g. an unset secret-ref
+ * env var), so a call site's precise error union flows straight through instead of being widened
+ * by hand here.
+ */
+export type GrafanaSpec<Props extends object, Live, Attributes, E> = {
+  /** Already folds the SDK's `NotFound` to `undefined` via its own `catchTag` — see the note above. */
+  readonly fetchLive: (props: Props) => Effect.Effect<Live | undefined, E, GrafanaOpContext>;
+  readonly attributes: (live: Live, props: Props) => Attributes | undefined;
+  readonly matches: (attributes: Attributes, props: Props) => boolean;
+  readonly create: (props: Props) => Effect.Effect<unknown, E, GrafanaOpContext>;
+  readonly update?: (props: Props, live: Live) => Effect.Effect<unknown, E, GrafanaOpContext>;
+  readonly destroy: (props: Props, live: Live) => Effect.Effect<unknown, E, GrafanaOpContext>;
+};
+
+export const grafanaOperations = <Props extends object, Live, Attributes, E>(
+  spec: GrafanaSpec<Props, Live, Attributes, E>,
+) => {
+  const read = (props: Props) =>
+    spec
+      .fetchLive(props)
+      .pipe(Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))));
+
+  return {
+    read,
+
+    diff: (news: Input<Props>, output: Attributes | undefined) =>
+      Effect.gen(function* () {
+        if (output === undefined || !isResolved(news)) return undefined;
+        const live = yield* read(news);
+        if (live === undefined) return { action: 'update' } as const;
+        if (spec.matches(live, news)) return { action: 'noop' } as const;
+        return spec.update === undefined
+          ? ({ action: 'replace' } as const)
+          : ({ action: 'update' } as const);
+      }),
+
+    /**
+     * ★ OBSERVES BEFORE IT WRITES (S9, S10) — THE WHOLE OF "ADOPT" FOR THIS FAMILY. A `uid` this
+     *   Grafana instance already has is bound and, when it already matches the declaration,
+     *   left alone; only a genuinely absent `uid` is created. Declaring exactly what is live
+     *   changes nothing on `reconcile`, the same posture netbox/resource.ts documents as
+     *   "adopt is the default posture, not a flag".
+     */
+    reconcile: (news: Props) =>
+      Effect.gen(function* () {
+        const before = yield* spec.fetchLive(news);
+        if (before === undefined) {
+          yield* spec.create(news);
+        } else if (spec.update !== undefined) {
+          const mapped = spec.attributes(before, news);
+          if (mapped === undefined || spec.matches(mapped, news)) {
+            /* adoption or already converged — no write */
+          } else {
+            yield* spec.update(news, before);
+          }
+        }
+        const after = yield* read(news);
+        if (after === undefined) {
+          return yield* Effect.die(
+            new Error(
+              'grafanaOperations: the write returned no error but the object is still absent. ' +
+                'Read back rather than trusting the response status.',
+            ),
+          );
+        }
+        return after;
+      }),
+
+    destroy: (olds: Props) =>
+      Effect.gen(function* () {
+        const live = yield* spec.fetchLive(olds);
+        if (live === undefined) return;
+        yield* spec.destroy(olds, live);
+      }),
+  };
+};
+
+/**
+ * The five provider handlers for a spec'd Grafana object, wired once. `Credentials` and
+ * `HttpClient.HttpClient` stay ambient context requirements — see the file header.
+ *
+ * ⚠️ `list` answers empty — an org's full datasource list is not a page this family sweeps for
+ *   adoption; adoption stays explicit, the same reasoning forgejo's and netbox's engines give.
+ */
+export const grafanaHandlers = <Props extends object, Live, Attributes extends object, E>(
+  spec: GrafanaSpec<Props, Live, Attributes, E>,
+) => {
+  const ops = grafanaOperations(spec);
+  return {
+    list: () => Effect.succeed([]),
+    read: ({ olds }: { olds: Props }) => ops.read(olds),
+    diff: ({ news, output }: { news: Input<Props>; output: Attributes | undefined }) =>
+      ops.diff(news, output),
+    reconcile: ({ news }: { news: Props }) => ops.reconcile(news),
+    delete: ({ olds }: { olds: Props }) => ops.destroy(olds),
+  };
+};