@homeflare/alchemy 0.31.2 → 0.33.0

package/docs/unifi.md

@@ -0,0 +1,93 @@
+# UniFi Network — `@homeflare/alchemy/unifi`
+
+⛔ **READ-ONLY, BY TIM'S RULE (2026-09-24).** `Unifi.Network` and `Unifi.FirewallZone` read and
+adopt; neither has a create, an update body or a working delete. `reconcile`/`delete` both fail
+with a typed `UnifiWriteRefused` naming the policy rather than calling any SDK write operation.
+Lifting the rule is a kit change — a PR that adds a write path, reviewed as one — not a flag a
+stack can pass. See `packages/alchemy/src/unifi/policy.ts`.
+
+## What's declared, and why these two first
+
+`Unifi.Network` (`getNetworkDetails`/`getNetworksOverviewPage`) and `Unifi.FirewallZone`
+(`getFirewallZone`/`getFirewallZones`) — both list+get pairs over genuine, stable configuration,
+not runtime state (a connected client, a device statistic, a hotspot voucher, a switch stack).
+`Site` was the SDK README's other first suggestion; it has no `getSite`, only the list operation,
+so it fails this house's own "both a list and a get" bar for a first import. `FirewallPolicy` is
+also a list+get config object, but its `source`/`destination`/`ipProtocolScope` fields carry
+several of the vendor's converter-flattened discriminator variants each, and its ordering
+endpoint replaces the whole rule list — modelling that correctly is a bigger, separate PR.
+
+## Credentials
+
+Two environment variables, read **at call time**, never props — the SDK's own
+`CredentialsFromEnv` (`@distilled.cloud/unifi-network/Credentials`):
+
+| variable                     | holds                                               |
+| ---------------------------- | --------------------------------------------------- |
+| `UNIFI_NETWORK_API_KEY`      | an Integrations → API Key from the console's own UI |
+| `UNIFI_NETWORK_API_BASE_URL` | the console's integration API root — see below      |
+
+⛔ **Neither has a default**, and neither is ever logged, committed or persisted in state.
+
+⛔ **No console identifier, endpoint host or other live value ever appears in code, tests,
+fixtures, commits or a PR.** The base URL shape depends on how the console is reached: a cloud
+connector's is `https://api.ui.com/v1/connector/consoles/<consoleId>/proxy/network/integration`
+(`<consoleId>` is an account identifier); a local console is reached directly,
+`<endpoint>/proxy/network/integration`, where `<endpoint>` is a hostname behind a TLS certificate
+the caller trusts. Treat any UniFi base URL as sensitive; this package's tests use only the RFC
+2606 placeholder `https://unifi.example.com`.
+
+The estate's own credential lives in OpenBao at `kv/infra/unifi/api` — fields `api_key`,
+`connector_id`, `console`, `endpoint`, `site`, `transport` (`transport=local`: this console is
+reached directly, not through the cloud connector). A separate `kv/infra/unifi/site-manager`
+token is the _cloud_ Site Manager API credential, a different door (below) this family never
+reads.
+
+✅ **Auth was measured live, read-only, on 2026-09-24.** The OpenAPI document declares no
+`securitySchemes` at all — `X-API-KEY` comes from Ubiquiti's own Integration API guide, not the
+machine-readable spec (`@distilled.cloud/unifi-network/src/credentials.ts`'s own header) — but a
+hand-run, read-only probe confirmed it works against the estate's local console: `X-API-KEY`
+returns HTTP 200 on both `GET /v1/info` (key: `applicationVersion`) and `GET /v1/sites` (keys:
+`count`, `data`, `limit`, `offset`, `totalCount`). The _same_ key against the `api.ui.com` cloud
+connector returns 401 — the wrong door for a key minted on a local console, not evidence the
+cloud shape rejects `X-API-KEY` outright; `kv/infra/unifi/site-manager` is the separate cloud
+credential, untouched by this family. Only reads were probed, by hand, outside this package's own
+test suite — nothing in this PR's code exercises the vendor API live, and a write path would still
+need its own verification.
+
+## Adopt is the default posture, and it never writes
+
+`adopt(true)` is piped onto every resource by its convenience constructor (`network(...)`,
+`firewallZone(...)`) — H5. A cold read of a live match answers `Unowned(attrs)` (H1, the
+`Cloudflare/Snippets/Snippet.ts` reference every marker-less family here follows: UniFi Network
+objects carry no tag or metadata field this stack could stamp), and `adopt(true)` turns that into
+a silent bind instead of an `OwnedBySomeoneElse` refusal — the deploy never needs `--adopt`.
+
+⚠️ **A forced post-adoption reconcile still runs once (H6), and it still makes no write.**
+Beta.79 forces one `reconcile` call after every cold adoption whether or not `diff` said noop.
+`resource.ts`'s `reconcile` handles this the same way `discord/resource.ts` does: it reads the
+live object again and only refuses when it is missing (would need a create) or drifted (would
+need a write); an exact match returns the live attributes and calls nothing.
+
+## `list` answers `[]`
+
+`GET /v1/sites/{siteId}/networks` answers every network on the site. Adoption stays explicit —
+the same reasoning `Proxmox.User`'s and NetBox's own `list` give.
+
+## The declaration renderer
+
+`declareNetwork(live, siteId)` and `declareFirewallZone(live, siteId)` are pure functions: given
+one `getNetworkDetails`/`getFirewallZone` response, they return the `Props` a declaration needs
+so its plan is a no-op. A later import script reads every object on a site and writes one
+`network('<id>', declareNetwork(live, siteId))` row per result into `alchemy.run.ts` — nothing
+here performs that write; these two functions are what the script would call.
+
+## Vendor version
+
+UniFi Network Integration API **10.4.57** (OpenAPI 3.1.0, 44 paths), via
+`@distilled.cloud/unifi-network` aliased onto `@homeflare/distilled-unifi-network@0.2.0`
+(`docs/distilled-interim.md`). Traps in the underlying API that this read-only family cannot
+trigger but a future write path must respect — whole-object `PUT`, ordering endpoints that
+replace the whole list, `removeDevice` unadopting and factory-resetting hardware — are recorded
+in the distilled package's own `README.md` and in the estate's `docs/unifi-api-notes.md`
+(outside this repo).

package/docs/upstream-conformance.md

@@ -259,10 +259,15 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
     `@homeflare/distilled-grafana` (0.1.0 pre-release, 0.2.0 once this PR's `minor` changeset
     releases it), aliased onto `@distilled.cloud/grafana` the same S22 route
     `@homeflare/distilled-netbox` established. `Grafana.Datasource`'s props/attributes/generated code
-    are unchanged (diffed operation-by-operation against the prior commit). **Still open, and not
-    this PR's scope:** no `Grafana.Folder`/`Dashboard`/`AlertRule`/`ContactPoint`/
-    `NotificationPolicy`/`MuteTiming` resource calls the newly-available operations yet — follow-up
-    PRs, no longer blocked on the SDK.
+    are unchanged (diffed operation-by-operation against the prior commit).
+
+    ✅ **`Grafana.Folder`/`Grafana.Dashboard` shipped** (this PR, on top of the same
+    `@distilled.cloud/grafana` operations S22 unblocked) — the uid-required doctrine, the
+    provisioned-object refusal, the parentUid-is-create-only refusal and the volatile-field
+    normalization that makes an unchanged dashboard a true noop are all in
+    [grafana-folder-dashboard.md](./grafana-folder-dashboard.md), not repeated here. **Still open,
+    and not this PR's scope:** `Grafana.AlertRule`/`ContactPoint`/`NotificationPolicy`/`MuteTiming`
+    — follow-up PRs, no longer blocked on the SDK.
     - ⛔ **Same open gaps as `forgejo/*` and `netbox/*` above:** `read` never answers `Unowned`
       (H1), and credentials come from an explicit env var NAME at call time rather than an
       `alchemy/Auth` provider (S24) — here the house's own `grafanaCredentials(target)`, not the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.31.2",
+  "version": "0.33.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -100,6 +100,14 @@
       "types": "./dist/discord/index.d.ts",
       "default": "./dist/discord/index.js"
     },
+    "./unifi": {
+      "types": "./dist/unifi/index.d.ts",
+      "default": "./dist/unifi/index.js"
+    },
+    "./opnsense": {
+      "types": "./dist/opnsense/index.d.ts",
+      "default": "./dist/opnsense/index.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -110,9 +118,11 @@
     "@distilled.cloud/grafana": "npm:@homeflare/distilled-grafana@0.2.0",
     "@distilled.cloud/litellm": "npm:@homeflare/distilled-litellm@0.2.0",
     "@distilled.cloud/netbox": "npm:@homeflare/distilled-netbox@0.3.0",
+    "@distilled.cloud/opnsense": "npm:@homeflare/distilled-opnsense@0.2.0",
     "@distilled.cloud/paperless-ngx": "npm:@homeflare/distilled-paperless-ngx@0.3.0",
     "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.2.0",
-    "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.2.0"
+    "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.2.0",
+    "@distilled.cloud/unifi-network": "npm:@homeflare/distilled-unifi-network@0.2.0"
   },
   "peerDependencies": {
     "@distilled.cloud/cloudflare": "1.0.0-rc.12",

package/src/grafana/dashboard-model.test.ts

@@ -0,0 +1,111 @@
+/**
+ * `normalizeModel`/`modelTitle`/`declaredContentMatches` in isolation — no SDK, no fake, no
+ * Effect. Proves the volatile fields (`id`, `version`, `iteration`) are stripped and `uid` is
+ * forced to the canonical value regardless of where — or whether — the source model carried one,
+ * and that `declaredContentMatches` tolerates Grafana's own schema-migration auto-decoration
+ * without hiding genuine content drift. All of which is what makes a pasted "Export as JSON" and
+ * a freshly-read live model compare equal in dashboard.test.ts.
+ */
+import { describe, expect, test } from 'bun:test';
+import { declaredContentMatches, modelTitle, normalizeModel } from './dashboard-model.ts';
+
+describe('normalizeModel', () => {
+  test('strips id, version and iteration', () => {
+    const model = { id: 42, iteration: 1700000000, title: 'Fleet', version: 7 };
+    expect(normalizeModel(model, 'fleet')).toEqual({ title: 'Fleet', uid: 'fleet' });
+  });
+
+  test('forces uid to the canonical value, overwriting a stale embedded one', () => {
+    const exported = { title: 'Fleet', uid: 'some-old-uid-from-an-export' };
+    expect(normalizeModel(exported, 'fleet')).toEqual({ title: 'Fleet', uid: 'fleet' });
+  });
+
+  test('injects uid when the source model has none at all — a never-saved dashboard', () => {
+    const neverSaved = { title: 'Fleet' };
+    expect(normalizeModel(neverSaved, 'fleet')).toEqual({ title: 'Fleet', uid: 'fleet' });
+  });
+
+  test('a declared model and a live model that only disagree on volatile fields normalize equal', () => {
+    const declared = { panels: [{ id: 1, title: 'CPU' }], title: 'Fleet' };
+    const live = {
+      id: 42,
+      iteration: 1700000000,
+      panels: [{ id: 1, title: 'CPU' }],
+      title: 'Fleet',
+      uid: 'fleet',
+      version: 9,
+    };
+    expect(normalizeModel(declared, 'fleet')).toEqual(normalizeModel(live, 'fleet'));
+  });
+
+  test('preserves array order — panels and targets are position-significant, not a set', () => {
+    const model = { panels: [{ title: 'B' }, { title: 'A' }] };
+    expect(normalizeModel(model, 'x').panels).toEqual([{ title: 'B' }, { title: 'A' }]);
+  });
+
+  test('leaves an unrelated field genuinely different, so a real content change still shows', () => {
+    const declared = { title: 'Fleet v2' };
+    const live = { title: 'Fleet', uid: 'fleet' };
+    expect(normalizeModel(declared, 'fleet')).not.toEqual(normalizeModel(live, 'fleet'));
+  });
+});
+
+describe('modelTitle', () => {
+  test('reads the model title', () => {
+    expect(modelTitle({ title: 'Fleet' })).toBe('Fleet');
+  });
+
+  test('answers empty for a model with no title', () => {
+    expect(modelTitle({})).toBe('');
+  });
+});
+
+describe('declaredContentMatches', () => {
+  // ⛔ THE REGRESSION THIS FUNCTION EXISTS TO FIX — found by an adversarial review of this PR.
+  //   Grafana's own dashboard-save schema migration decorates a panel/target whose `datasource`
+  //   is absent with an explicit `{type, uid}` reference. Before this function existed, a
+  //   declared panel that never set `datasource` disagreed with what it read back FOREVER.
+  test('tolerates Grafana auto-decorating a panel/target with a datasource it never declared', () => {
+    const declared = {
+      panels: [{ targets: [{ refId: 'A' }], title: 'CPU' }],
+      title: 'Fleet',
+    };
+    const live = {
+      panels: [
+        {
+          datasource: { type: 'postgres', uid: 'teslamate' },
+          targets: [{ datasource: { type: 'postgres', uid: 'teslamate' }, refId: 'A' }],
+          title: 'CPU',
+        },
+      ],
+      title: 'Fleet',
+    };
+    expect(declaredContentMatches(declared, live)).toBe(true);
+  });
+
+  test('still catches a genuine change to a field the declaration DOES mention', () => {
+    const declared = { panels: [{ title: 'CPU' }] };
+    const live = { panels: [{ datasource: { uid: 'teslamate' }, title: 'Memory' }] };
+    expect(declaredContentMatches(declared, live)).toBe(false);
+  });
+
+  test('still fails when live is missing a field the declaration mentions', () => {
+    expect(declaredContentMatches({ title: 'Fleet' }, {})).toBe(false);
+  });
+
+  test('still fails on an array length mismatch — panels are not padded away', () => {
+    const declared = { panels: [{ title: 'A' }, { title: 'B' }] };
+    const live = { panels: [{ title: 'A' }] };
+    expect(declaredContentMatches(declared, live)).toBe(false);
+  });
+
+  test('ignores an extra top-level field live carries that the declaration never mentioned', () => {
+    expect(declaredContentMatches({ title: 'Fleet' }, { schemaVersion: 39, title: 'Fleet' })).toBe(
+      true,
+    );
+  });
+
+  test('null (or undefined) on a declared leaf never mismatches, mirroring stripNullish', () => {
+    expect(declaredContentMatches({ description: null }, { description: 'set live' })).toBe(true);
+  });
+});

package/src/grafana/dashboard-model.ts

@@ -0,0 +1,111 @@
+/**
+ * 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>;
+
+/** Grafana injects or increments these on every save; a declared model never sets them meaningfully. */
+const VOLATILE_FIELDS = ['id', 'version', 'iteration'] as const;
+
+/**
+ * ★ 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 const normalizeModel = (model: DashboardModel, uid: string): DashboardModel => {
+  const normalized: DashboardModel = {};
+  for (const [key, value] of Object.entries(model)) {
+    if (key === 'uid') continue;
+    if ((VOLATILE_FIELDS as readonly string[]).includes(key)) continue;
+    normalized[key] = value;
+  }
+  normalized.uid = uid;
+  return normalized;
+};
+
+/** 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 const modelTitle = (model: DashboardModel): string =>
+  typeof model.title === 'string' ? model.title : '';
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * ★ `declared` NEED ONLY BE A SUBSET OF `live` — an adversarial review of this PR (2026-09-24)
+ *   found that plain structural equality made an ordinary, never-edited dashboard show `update`
+ *   FOREVER: Grafana's own dashboard-save schema migration rewrites any panel or target whose
+ *   `datasource` is absent into an explicit `{type, uid}` reference to the resolved default
+ *   datasource — documented Grafana schema-migration behavior (not re-measured against a live
+ *   instance in this PR — no live calls). A declared panel that never sets `datasource` (the
+ *   common case: hand-authored JSON, or anything relying on the dashboard-level default) would,
+ *   after the FIRST create, read back with that field populated; plain `deepEqual` (this file used
+ *   `alchemy/Diff`'s before this fix) then disagreed with the declaration on every subsequent plan,
+ *   `update` sent the undecorated model back, and Grafana redecorated it again on the next read —
+ *   non-convergent.
+ *
+ * This function instead asks only "does every field the DECLARATION mentions, at any depth, still
+ * match what is live" — `live` may carry additional fields, at any depth, that `declared` never
+ * mentioned (the datasource auto-decoration above, or any future Grafana-injected default,
+ * `fieldConfig` defaults and `pluginVersion` included) without being compared at all. A field
+ * `declared` DOES mention that is missing, or different, in `live` still fails the match — real
+ * content drift is still caught exactly as before; only fields the declaration is silent about are
+ * now tolerated rather than compared.
+ *
+ * ⚠️ THE TRADE-OFF THIS ACCEPTS, DELIBERATELY: removing a field from the declaration (rather than
+ *   changing its value) can no longer force Grafana to drop it. If a panel once declared an
+ *   explicit `datasource` and a later declaration deletes that key entirely (rather than setting a
+ *   different one), `live` keeps whatever the last write set — the declaration is silent about that
+ *   key now, so nothing compares it, so no `update` ever fires to change it. This is the same
+ *   "undeclared means don't care, never means force-to-default" convention already used everywhere
+ *   else in this kit for a plain optional prop (e.g. `datasource.ts`'s `matches` never treats an
+ *   undeclared `access` as "must be unset"); it now also applies inside the JSON model, not just at
+ *   the props level. Declare an explicit replacement value to change a field; omission never clears
+ *   one that was set by a previous declaration or by Grafana itself.
+ *
+ * ⚠️ ARRAYS COMPARE BY LENGTH, THEN ELEMENT-WISE SUBSET — never by a looser "declared has fewer
+ *   items" rule. `panels`/`targets` are position-significant (see `normalizeModel`'s header); an
+ *   array Grafana pads or reorders on its own would still need normalizing here explicitly, the
+ *   same as any other newly-discovered auto-decoration — this function does not paper over that.
+ * ⚠️ `null` ON EITHER SIDE OF A LEAF NEVER MISMATCHES (mirrors `alchemy/Diff`'s `deepEqual` with
+ *   `stripNullish: true`, which this function replaces for the dashboard model specifically).
+ */
+export const declaredContentMatches = (declared: unknown, live: unknown): boolean => {
+  if (declared == null) return true;
+  if (Array.isArray(declared)) {
+    return (
+      Array.isArray(live) &&
+      declared.length === live.length &&
+      declared.every((item, index) => declaredContentMatches(item, live[index]))
+    );
+  }
+  if (isPlainObject(declared)) {
+    return (
+      isPlainObject(live) &&
+      Object.entries(declared).every(([key, value]) => declaredContentMatches(value, live[key]))
+    );
+  }
+  return declared === live;
+};

package/src/grafana/dashboard.test.ts

@@ -0,0 +1,232 @@
+/**
+ * `Grafana.Dashboard` against a fake Grafana — the noop-despite-volatile-fields normalization, the
+ * provisioned-object refusal, and 412 propagating as a genuine failure rather than being caught or
+ * overwritten blindly. Mirrors `datasource.test.ts`/`folder.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { spec } from './dashboard.ts';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { GrafanaProvisionedObjectError } from './provisioned.ts';
+import { grafanaOperations } from './resource.ts';
+
+const DASH_PATH = '/api/dashboards/uid/fleet-overview';
+const CREATE_PATH = '/api/dashboards/db';
+
+const model = { panels: [{ id: 1, title: 'CPU' }], title: 'Fleet Overview' };
+
+const liveJson = {
+  dashboard: { ...model, id: 42, uid: 'fleet-overview', version: 3 },
+  meta: {
+    folderUid: 'infra',
+    provisioned: false,
+    provisionedExternalId: '',
+    url: '/d/fleet-overview',
+    version: 3,
+  },
+};
+
+const props = { dashboard: model, folderUid: 'infra', uid: 'fleet-overview' };
+
+describe('spec.fetchLive', () => {
+  test('a live dashboard decodes and normalizes into typed attributes', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === DASH_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({
+      dashboard: { ...model, uid: 'fleet-overview' },
+      folderUid: 'infra',
+      provisioned: false,
+      provisionedExternalId: '',
+      title: 'Fleet Overview',
+      uid: 'fleet-overview',
+      url: '/d/fleet-overview',
+      version: 3,
+    });
+    expect(fake.bodies[0]).toBeUndefined();
+  });
+
+  test('a 404 folds to undefined', async () => {
+    const fake = fakeGrafana(() => fakeFailure(404, 'dashboard not found'));
+    const result = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(result).toBeUndefined();
+  });
+});
+
+describe('create', () => {
+  test('sends the normalized model and folderUid — no volatile fields, no extra keys', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'POST' && url.pathname === CREATE_PATH
+        ? Response.json({
+            folderUid: 'infra',
+            id: 42,
+            status: 'success',
+            title: 'Fleet Overview',
+            uid: 'fleet-overview',
+            url: '/d/fleet-overview',
+            version: 1,
+          })
+        : fakeFailure(404, 'unexpected request'),
+    );
+    await Effect.runPromise(spec.create(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))));
+    expect(fake.bodies[0]).toEqual({
+      dashboard: { ...model, uid: 'fleet-overview' },
+      folderUid: 'infra',
+    });
+  });
+});
+
+describe('reconcile — noop despite volatile fields', () => {
+  test('a declared model matching live content is a noop even though id/version/iteration differ', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === DASH_PATH
+        ? Response.json(liveJson)
+        : fakeFailure(500, 'reconcile should not write when content is unchanged'),
+    );
+    const after = await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(after.uid).toBe('fleet-overview');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+});
+
+describe('update', () => {
+  // ★ ALL THREE 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 a
+  //   real plan/deploy does, rather than a hand-assembled `live` argument.
+  test('a content change sends the live version for optimistic concurrency, never overwrite', async () => {
+    const changed = { ...model, title: 'Fleet Overview v2' };
+    let saved = false;
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === DASH_PATH) {
+        return Response.json(
+          saved
+            ? {
+                dashboard: { ...changed, id: 42, uid: 'fleet-overview', version: 4 },
+                meta: { ...liveJson.meta, version: 4 },
+              }
+            : liveJson,
+        );
+      }
+      if (method === 'POST' && url.pathname === CREATE_PATH) {
+        saved = true;
+        return Response.json({
+          folderUid: 'infra',
+          id: 42,
+          status: 'success',
+          title: 'Fleet Overview v2',
+          uid: 'fleet-overview',
+          url: '/d/fleet-overview',
+          version: 4,
+        });
+      }
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile({ ...props, dashboard: changed })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    const post = fake.seen.findIndex((s) => s.method === 'POST');
+    expect(fake.bodies[post]).toMatchObject({
+      dashboard: { ...changed, uid: 'fleet-overview', version: 3 },
+    });
+    // ⛔ `overwrite` IS NEVER SET — Grafana's own version check stays live on every update.
+    expect((fake.bodies[post] as { overwrite?: boolean }).overwrite).toBeUndefined();
+  });
+
+  test('a 412 from a concurrent save propagates — never caught, never retried here', async () => {
+    const changed = { ...model, title: 'Fleet Overview v2' };
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === DASH_PATH) return Response.json(liveJson);
+      if (method === 'POST' && url.pathname === CREATE_PATH) {
+        return fakeFailure(412, 'The dashboard has been changed by someone else');
+      }
+      return fakeFailure(500, 'unexpected request');
+    });
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .reconcile({ ...props, dashboard: changed })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure._tag).toBe('PreconditionFailed');
+  });
+
+  test('a provisioned dashboard refuses the write, naming its owning file', async () => {
+    const provisioned = {
+      ...liveJson,
+      meta: { ...liveJson.meta, provisioned: true, provisionedExternalId: 'dashboards/fleet.json' },
+    };
+    const changed = { ...model, title: 'Fleet Overview v2' };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === DASH_PATH
+        ? Response.json(provisioned)
+        : fakeFailure(500, 'no write should be attempted'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .reconcile({ ...props, dashboard: changed })
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaProvisionedObjectError);
+    expect(failure.message).toContain('dashboards/fleet.json');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+});
+
+describe('destroy', () => {
+  test('deletes a live, non-provisioned dashboard by uid', async () => {
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === DASH_PATH) return Response.json(liveJson);
+      if (method === 'DELETE' && url.pathname === DASH_PATH) {
+        return Response.json({ message: 'ok', title: 'Fleet Overview', uid: 'fleet-overview' });
+      }
+      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: DASH_PATH },
+      { method: 'DELETE', path: DASH_PATH },
+    ]);
+  });
+
+  test('a provisioned dashboard refuses destroy and sends no DELETE', async () => {
+    const provisioned = {
+      ...liveJson,
+      meta: { ...liveJson.meta, provisioned: true, provisionedExternalId: 'dashboards/fleet.json' },
+    };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === DASH_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: DASH_PATH }]);
+  });
+});