@homeflare/alchemy 0.33.0 → 0.35.0

package/src/grafana/mute-timing.test.ts

@@ -0,0 +1,227 @@
+/**
+ * `Grafana.MuteTiming` against a fake Grafana — the widened-type `provenance`/`version` read (see
+ * the file's own header for why the SDK's declared `MuteTimeInterval` type undersells the runtime
+ * value), the foreign-provenance refusal, and opaque time-interval passthrough (weekdays/times
+ * fields the SDK's own `TimeInterval` type does not model either). Mirrors `contact-point.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { GrafanaProvisionedObjectError } from './alerting-provenance.ts';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { spec } from './mute-timing.ts';
+import { grafanaOperations } from './resource.ts';
+
+const PATH = '/api/v1/provisioning/mute-timings/weekends';
+const LIST_PATH = '/api/v1/provisioning/mute-timings';
+
+const timeIntervals = [
+  { times: [{ end_time: '09:00', start_time: '17:00' }], weekdays: ['friday'] },
+];
+
+const liveJson = {
+  name: 'weekends',
+  provenance: 'api',
+  time_intervals: timeIntervals,
+  version: 'v1',
+};
+const props = { name: 'weekends', timeIntervals };
+
+describe('spec.fetchLive', () => {
+  test('provenance and the real weekday/time fields survive decode despite the SDK type', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH ? Response.json(liveJson) : fakeFailure(404, 'x'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(live !== undefined && spec.attributes(live, props)).toEqual({
+      name: 'weekends',
+      provenance: 'api',
+      timeIntervals,
+    });
+    expect(fake.bodies[0]).toBeUndefined();
+  });
+
+  test('a 404 folds to undefined', async () => {
+    const fake = fakeGrafana(() => fakeFailure(404, 'mute timing 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 the real weekday/time fields on the wire — not dropped by the SDK type either', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'POST' && url.pathname === LIST_PATH
+        ? Response.json(liveJson)
+        : fakeFailure(404, 'x'),
+    );
+    await Effect.runPromise(spec.create(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))));
+    expect(fake.bodies[0]).toEqual({ name: 'weekends', time_intervals: timeIntervals });
+  });
+});
+
+describe('subset-match array rule — pinned, not re-measured live', () => {
+  // ⛔ FLAGGED BY AN ADVERSARIAL REVIEW OF THIS PR: `subset-match.ts`'s array comparison is exact
+  //   length, then element-wise — unverified against a real Grafana instance for whether it ever
+  //   pads or appends a default entry to `time_intervals` (no live mute timing exists in this house
+  //   to observe). This test pins TODAY's behavior — a live observation that finds Grafana doing so
+  //   would make this test itself the place to change, not a surprise discovered elsewhere.
+  test('live carrying one extra time-interval entry the declaration never mentioned still shows update', async () => {
+    const extraEntry = {
+      ...liveJson,
+      time_intervals: [...timeIntervals, { weekdays: ['sunday'] }],
+    };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH ? Response.json(extraEntry) : fakeFailure(500, 'x'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    const attrs = live !== undefined ? spec.attributes(live, props) : undefined;
+    expect(attrs !== undefined && spec.matches(attrs, props)).toBe(false);
+  });
+});
+
+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 === 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.name).toBe('weekends');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+});
+
+describe('foreign provenance refuses update and destroy', () => {
+  test('a file-provisioned mute timing refuses update and sends no PUT', async () => {
+    const fileProvisioned = { ...liveJson, provenance: 'file' };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH
+        ? Response.json(fileProvisioned)
+        : fakeFailure(500, 'no write should be attempted'),
+    );
+    const changed = { name: 'weekends', timeIntervals: [{ weekdays: ['saturday'] }] };
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .reconcile(changed)
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaProvisionedObjectError);
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('a file-provisioned mute timing refuses destroy and sends no DELETE', async () => {
+    const fileProvisioned = { ...liveJson, provenance: 'file' };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH
+        ? Response.json(fileProvisioned)
+        : 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: PATH }]);
+  });
+
+  test('deletes a live, api-provenance mute timing, sending its version for concurrency', async () => {
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === PATH) return Response.json(liveJson);
+      if (method === 'DELETE' && url.pathname === PATH) return Response.json({});
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .destroy(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    const del = fake.seen.findIndex((s) => s.method === 'DELETE');
+    expect(del).toBeGreaterThanOrEqual(0);
+    expect(fake.seen[del]?.path).toBe(`${PATH}?version=v1`);
+  });
+});
+
+describe('missing provenance fails closed', () => {
+  // ⛔ THE REGRESSION AN ADVERSARIAL REVIEW OF THIS PR FOUND — see contact-point.test.ts's own
+  //   copy of this block for the full account. This resource is the one where it matters most:
+  //   `provenance` isn't even in the SDK's declared `MuteTimeInterval` type, so "the field is
+  //   missing" is a real, plausible shape for a response to take, not a hypothetical.
+  const noProvenanceField: Record<string, unknown> = { ...liveJson };
+  delete noProvenanceField.provenance;
+
+  test('a response with no provenance field at all refuses update', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH
+        ? Response.json(noProvenanceField)
+        : fakeFailure(500, 'no write should be attempted'),
+    );
+    const changed = { name: 'weekends', timeIntervals: [{ weekdays: ['saturday'] }] };
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        grafanaOperations(spec)
+          .reconcile(changed)
+          .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toBeInstanceOf(GrafanaProvisionedObjectError);
+    expect(failure.message).toContain('did not report a provenance');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('a response with no provenance field at all refuses destroy', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === PATH
+        ? Response.json(noProvenanceField)
+        : 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: PATH }]);
+  });
+
+  test('an EXPLICIT empty-string provenance (ProvenanceNone) is writable', async () => {
+    const explicitlyNone = { ...liveJson, provenance: '' };
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === PATH) return Response.json(explicitlyNone);
+      if (method === 'PUT' && url.pathname === PATH) return Response.json(explicitlyNone);
+      return fakeFailure(500, 'unexpected request');
+    });
+    const changed = { name: 'weekends', timeIntervals: [{ weekdays: ['saturday'] }] };
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile(changed)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen.some((s) => s.method === 'PUT')).toBe(true);
+  });
+});

package/src/grafana/mute-timing.ts

@@ -0,0 +1,160 @@
+/**
+ * `Grafana.MuteTiming` — one Grafana alerting mute timing, keyed by `name` (there is no separate
+ * `uid` — `routeGetMuteTiming`/`routePutMuteTiming`/`routeDeleteMuteTiming` are all name-keyed on
+ * the wire, and `name` is the field a notification policy's own `mute_time_intervals` references).
+ *
+ * ★ `provenance`/`version` ARE READ THROUGH A WIDENED TYPE, NOT THE SDK's OWN `MuteTimeInterval` —
+ *   MEASURED, and a genuinely surprising result worth recording in full. The SDK's generated
+ *   `MuteTimeInterval` interface (`packages/distilled-grafana/src/services/grafana.ts`) declares
+ *   only `name`/`time_intervals` — no `provenance`, no `version` — unlike `EmbeddedContactPoint`/
+ *   `NotificationTemplate`/`ProvisionedAlertRule`/`Route`, which all carry `provenance`. A first
+ *   pass at this file assumed that meant the data was gone: decoding a raw payload containing both
+ *   fields through `S.decodeUnknownSync(MuteTimeInterval)` directly DOES strip them. But that is
+ *   the wrong code path — it is not what `routeGetMuteTiming` itself does. Proven empirically by
+ *   calling the REAL operation (through `fake-grafana.ts`'s harness, the exact path this file's own
+ *   `fetchLive` uses) with a response body containing `provenance`/`version`: both come through on
+ *   the decoded value intact. The mechanism, read from `@distilled.cloud/core@1.0.0-rc.12`'s
+ *   `protocol-rest.ts`/`protocol-http.ts` (the runtime this SDK's every operation shares): response
+ *   decoding is `JSON.parse` + `mapKeys` (renames only the field names a schema DOES declare) +
+ *   `wrapSensitive` (wraps only fields a schema marks sensitive in `Redacted`) — never a strict
+ *   `Schema.decode`. `protocol-http.ts`'s `mapKeys`, object branch: every response key NOT among a
+ *   type's declared `props` is copied to the output verbatim in a second pass
+ *   (`for (const [k, v] of Object.entries(value)) { if (consumed.has(k)) continue; out[k] = v; }`,
+ *   line ~297-311) — the doc comment on the sibling `wrapSensitive` states the same rule plainly:
+ *   "Keys the schema doesn't model pass through verbatim." So the TS type is simply narrower than
+ *   the runtime value; `MuteTimeIntervalWire` below is that same runtime value, typed honestly.
+ *   This is a real, worth-fixing SDK type-generation gap (tracked in `docs/upstream-conformance.md`,
+ *   same S22 route as the other named gaps) but NOT a data-loss gap — unlike, say, a field the wire
+ *   protocol itself never sent, this one is fully recoverable without touching vendored `src/`.
+ *
+ *   The same test proved the outbound direction too: an object with extra keys (`weekdays`, `times`
+ *   — the real Alertmanager time-interval fields Grafana's OpenAPI's own `TimeInterval` schema
+ *   apparently fails to model either, for the same reason) passed to `routePutMuteTiming` reaches
+ *   the wire body unchanged — `mapKeys`'s encode direction is the same verbatim-passthrough rule.
+ *   `MuteTimingProps.timeIntervals` is therefore typed as the opaque `Record<string, unknown>`
+ *   shape actually needed to declare a real mute timing (weekdays/times/months/etc.), not the
+ *   SDK's own too-narrow `TimeInterval`, and cast at the two call sites below.
+ *
+ * ⚠️ THE EVIDENCE ABOVE IS A HAND-AUTHORED FIXTURE, NOT A CAPTURED REAL RESPONSE — flagged by an
+ *   adversarial review of this PR. The estate has zero live mute timings to observe (grafana.md's
+ *   census), so nothing confirms Grafana always includes `provenance` on this route in practice,
+ *   or that some other SDK/version edge case never drops it. That is exactly why `attributes()`
+ *   below never coerces a missing `live.provenance` to `''` — see alerting-provenance.ts's "fails
+ *   open" note — an absent field refuses a write rather than being trusted as `ProvenanceNone`.
+ *
+ * ⛔ A FOREIGN-PROVENANCE MUTE TIMING REFUSES EVERY UPDATE AND DESTROY — `alerting-provenance.ts`,
+ *   shared with `Grafana.ContactPoint`/`MessageTemplate`/`AlertRuleGroup`/`NotificationPolicy`; see
+ *   that file's header. `create` is never at risk: it only runs when `fetchLive` already found
+ *   nothing with this `name`.
+ *
+ * ⚠️ `version` IS SENT ON DESTROY, NOT ON UPDATE — MEASURED: `RouteDeleteMuteTimingRequest.version`
+ *   ("Version of mute timing to use for optimistic concurrency. Leave empty to disable validation")
+ *   exists; `RoutePutMuteTimingRequest` has no `version` field at all, so an update has nothing to
+ *   send for it — a real Grafana API asymmetry between the two write routes, not an omission here.
+ *
+ * ⚠️ `X-Disable-Provenance` IS NEVER SET — same reasoning as `contact-point.ts`'s file header.
+ */
+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,
+  isForeignProvenance,
+  refuseIfForeignProvenance,
+} from './alerting-provenance.ts';
+import { type GrafanaSpec, grafanaHandlers } from './resource.ts';
+import { declaredContentMatches } from './subset-match.ts';
+
+export interface MuteTimingProps {
+  name: string;
+  /** Grafana's Alertmanager-style time-interval entries (`weekdays`/`times`/`months`/…), passed
+   *  through opaquely — see the file header for why this is not the SDK's own `TimeInterval`. */
+  timeIntervals: ReadonlyArray<Record<string, unknown>>;
+}
+
+export interface MuteTimingAttributes {
+  name: string;
+  timeIntervals: ReadonlyArray<Record<string, unknown>>;
+  /** `""`/`"api"` (this family may write); anything else, INCLUDING `undefined` (Grafana didn't
+   *  report the field, or the widened-type passthrough this file depends on turns out not to hold
+   *  for some response shape not yet observed), refuses — see alerting-provenance.ts's "fails
+   *  open" note. This is the field where that default matters most: unlike the other resources in
+   *  this family, `provenance` here is not even in the SDK's declared type. */
+  provenance: string | undefined;
+}
+
+export interface GrafanaMuteTiming extends Resource<
+  'Grafana.MuteTiming',
+  MuteTimingProps,
+  MuteTimingAttributes,
+  never
+> {}
+
+export const GrafanaMuteTiming = Resource<GrafanaMuteTiming>('Grafana.MuteTiming');
+
+/** The real runtime shape of a `GET`/list response — see the file header's "measured" note. */
+type MuteTimeIntervalWire = grafana.MuteTimeInterval & {
+  provenance?: string;
+  version?: string;
+};
+
+export const spec: GrafanaSpec<
+  MuteTimingProps,
+  MuteTimeIntervalWire,
+  MuteTimingAttributes,
+  | grafana.RouteGetMuteTimingError
+  | grafana.RoutePostMuteTimingError
+  | grafana.RoutePutMuteTimingError
+  | grafana.RouteDeleteMuteTimingError
+  | GrafanaProvisionedObjectError
+> = {
+  attributes: (live) => ({
+    name: live.name ?? '',
+    // ⛔ NEVER `?? ''` — see alerting-provenance.ts's "fails open" note, and this file's own
+    //   Attributes doc comment on why it matters most here.
+    provenance: live.provenance,
+    timeIntervals: (live.time_intervals ?? []) as unknown as ReadonlyArray<Record<string, unknown>>,
+  }),
+  create: (props) =>
+    grafana.routePostMuteTiming({
+      name: props.name,
+      time_intervals:
+        props.timeIntervals as unknown as grafana.RoutePostMuteTimingRequestTimeIntervalsList,
+    }),
+  destroy: (props, live) =>
+    Effect.gen(function* () {
+      if (isForeignProvenance(live.provenance)) {
+        return yield* refuseIfForeignProvenance('Grafana.MuteTiming', props.name, live.provenance);
+      }
+      yield* grafana.routeDeleteMuteTiming({
+        name: props.name,
+        ...(live.version === undefined ? {} : { version: live.version }),
+      });
+    }),
+  fetchLive: (props) =>
+    grafana.routeGetMuteTiming({ name: props.name }).pipe(
+      Effect.map((live) => live as MuteTimeIntervalWire),
+      Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+    ),
+  /** Subset match (subset-match.ts), not plain equality — tolerates a default Grafana might
+   *  inject into a time-interval entry the declaration never set. */
+  matches: (attributes, props) =>
+    declaredContentMatches(props.timeIntervals, attributes.timeIntervals),
+  update: (props, live) =>
+    Effect.gen(function* () {
+      if (isForeignProvenance(live.provenance)) {
+        return yield* refuseIfForeignProvenance('Grafana.MuteTiming', props.name, live.provenance);
+      }
+      yield* grafana.routePutMuteTiming({
+        name: props.name,
+        time_intervals:
+          props.timeIntervals as unknown as grafana.RoutePutMuteTimingRequestTimeIntervalsList,
+      });
+    }),
+};
+
+export const handlers = grafanaHandlers(spec);
+
+export const GrafanaMuteTimingProvider = () =>
+  Provider.effect(GrafanaMuteTiming, Effect.succeed(GrafanaMuteTiming.Provider.of(handlers)));

package/src/grafana/providers.ts

@@ -12,14 +12,22 @@
  *   deploys anything over HTTP already has one.
  */
 import * as Layer from 'effect/Layer';
+import { GrafanaAlertRuleGroupProvider } from './alert-rule-group.ts';
+import { GrafanaContactPointProvider } from './contact-point.ts';
 import { type GrafanaTarget, grafanaCredentials } from './credentials.ts';
 import { GrafanaDashboardProvider } from './dashboard.ts';
 import { GrafanaDatasourceProvider } from './datasource.ts';
 import { GrafanaFolderProvider } from './folder.ts';
+import { GrafanaMessageTemplateProvider } from './message-template.ts';
+import { GrafanaMuteTimingProvider } from './mute-timing.ts';
 
 export const grafanaProviders = (target: GrafanaTarget) =>
   Layer.mergeAll(
     GrafanaDatasourceProvider(),
     GrafanaFolderProvider(),
     GrafanaDashboardProvider(),
+    GrafanaContactPointProvider(),
+    GrafanaMuteTimingProvider(),
+    GrafanaMessageTemplateProvider(),
+    GrafanaAlertRuleGroupProvider(),
   ).pipe(Layer.provide(grafanaCredentials(target)));

package/src/grafana/secret-refs.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared "secret stays in env, never in state" resolution (S25) for this family —
+ * `Grafana.Datasource`'s `secureJsonDataRefs` and `Grafana.ContactPoint`'s `secureSettingsRefs`
+ * are the identical shape: a map of field name to an env var NAME, resolved fresh from
+ * `process.env` inside the caller's own create/update effect (S24), never at plan time and never
+ * returned in `attributes`. Extracted here once a second family needed the exact same loop
+ * `datasource.ts` already had — see that file's original note for why this exists at all:
+ * Grafana's own read APIs never return a secret value, only whether one is set
+ * (`DataSource.secureJsonFields`'s booleans; a contact point's `settings` comes back with secure
+ * keys replaced by a literal redaction placeholder instead — see contact-point.ts).
+ */
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+
+/** 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.
+ * `describeField` builds the refusal message's own field-specific phrase — each caller names its
+ * declaration path differently (`secureJsonData.<field>` for a datasource,
+ * `settings.<field>` for a contact point) — so the message stays accurate to what the caller
+ * itself declares.
+ */
+export const resolveSecretRefs = (
+  refs: Record<string, string> | undefined,
+  describeField: (field: string) => string,
+): 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 ${describeField(field)} there — ` +
+              'never as an Alchemy prop.',
+          }),
+        );
+      }
+      out[field] = raw.trim();
+    }
+    return out;
+  });

package/src/grafana/subset-match.ts

@@ -0,0 +1,71 @@
+/**
+ * `declaredContentMatches` — "is the declaration a subset of what is live", not plain equality.
+ * Extracted out of `dashboard-model.ts` (where it was introduced, after an adversarial review of
+ * that PR found plain structural equality made an ordinary, never-edited dashboard show `update`
+ * FOREVER) once a second shape needed the identical rule: `Grafana.ContactPoint`'s `settings` is
+ * the same story — Grafana can inject default fields into a contact point's settings that the
+ * declaration never mentioned, and `Grafana.AlertRuleGroup`'s per-rule `data`/`annotations`/
+ * `labels` maps carry the same risk. Nothing about the reasoning below is dashboard-specific;
+ * `dashboard-model.ts` now just re-exports this.
+ *
+ * ★ `declared` NEED ONLY BE A SUBSET OF `live`. Grafana's own save/decode path can decorate an
+ *   object with fields the declaration never set (a dashboard panel's auto-resolved `datasource`
+ *   reference is the documented example dashboard-model.ts found — Grafana's schema migration
+ *   decorates any panel/target whose `datasource` is absent with an explicit `{type, uid}`
+ *   reference on save). 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, 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.
+ *
+ * ⚠️ 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 previous declaration set a
+ *   field and a later one deletes that key entirely, `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; it now also
+ *   applies inside a nested JSON value, not just at the top-level props. 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 a looser "declared has fewer
+ *   items" rule. A caller whose array IS order-significant (dashboard `panels`/`targets`) or
+ *   position-keyed (an alert rule group's `rules`) gets that for free; a caller with a genuinely
+ *   unordered array would need its own normalization first (this file has no `sortedSet`, and
+ *   nothing in this kit's Grafana family needs one — see dashboard-model.ts's own note).
+ *
+ *   ⛔ NOT RE-MEASURED FOR EVERY CALLER — flagged by an adversarial review of this PR. The exact
+ *   length rule is confirmed for dashboards (the original, documented case), but whether Grafana
+ *   ever PADS or APPENDS a default entry to an array the way it decorates an object field (the
+ *   `datasource` auto-decoration above) is unverified for `Grafana.MuteTiming`'s `time_intervals`
+ *   specifically — no live mute timing exists in this house to observe (grafana.md's census), and
+ *   `mute-timing.test.ts`'s own fixtures are hand-authored, not captured. If a future live
+ *   observation finds Grafana appending an entry (e.g. a normalized default time range) to a
+ *   declared `time_intervals` array, the length check here would show a permanent false `update` —
+ *   the exact regression this whole file exists to prevent for OBJECT fields already. `mute-timing.
+ *   test.ts`'s "array length is exact, not tolerant" test pins today's behavior so that fix has an
+ *   obvious, single place to change (relax this rule, or give the mute-timing caller its own
+ *   length-tolerant wrapper) rather than being rediscovered from scratch.
+ * ⚠️ `null` ON EITHER SIDE OF A LEAF NEVER MISMATCHES (mirrors `alchemy/Diff`'s `deepEqual` with
+ *   `stripNullish: true`, which this function replaces wherever a caller needs subset semantics).
+ */
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+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/linux/index-export.test.ts

@@ -0,0 +1,25 @@
+/**
+ * `renderContainerFile`/`containerPathFor` are reachable from the package entry — the same pure
+ * `.container` renderer `container-fixture.test.ts` (container-form.ts) already proves internally,
+ * now callable by a CONSUMER without a deep import.
+ *
+ * ★ WHY THIS WAS MISSING. `index.ts`'s barrel forwarded `QUADLET_DEFAULT_DIRECTORY`/
+ *   `QUADLET_SEARCH_DIRECTORIES` (constants) but not the renderer or the path rule, unlike
+ *   `Systemd.Unit`'s own pure helpers (`renderUnit`/`DEFAULT_UNIT_DIRECTORY`), which ARE both on
+ *   the barrel. A consumer (homeflare-ct100 PR #1) writing an equivalence test against a live
+ *   host — the same kind of test this package's own fixture tests are — had no import path to
+ *   the real renderer and had to reimplement the render contract by hand to write one at all.
+ */
+import { expect, test } from 'bun:test';
+import { containerPathFor, renderContainerFile } from './index.ts';
+
+test('renderContainerFile and containerPathFor are reachable from the package entry', () => {
+  const rendered = renderContainerFile({
+    container: { image: 'docker.io/library/busybox:1', network: 'host' },
+    name: 'smoke',
+  });
+  expect(rendered).toContain('[Container]');
+  expect(rendered).toContain('Image=docker.io/library/busybox:1');
+  expect(rendered).toContain('Network=host');
+  expect(containerPathFor({ name: 'smoke' })).toBe('/etc/containers/systemd/smoke.container');
+});

package/src/linux/index.ts

@@ -38,5 +38,19 @@ export type {
   PodmanContainerProps,
   PodmanUnitLine,
 } from './container.ts';
-export { QUADLET_DEFAULT_DIRECTORY, QUADLET_SEARCH_DIRECTORIES } from './container-form.ts';
+// ★ `renderContainerFile`/`containerPathFor` are the pure `.container` file renderer and its path
+//   rule — the same kind of pure helper `renderUnit`/`DEFAULT_UNIT_DIRECTORY` above already are
+//   for `Systemd.Unit`. A consumer needs these to prove ITS OWN declared props render into the
+//   directive set it expects (an equivalence/fixture test against a live host), the same way this
+//   package's own container-fixture.test.ts does internally — without them, a consuming repo has
+//   no import path to the real renderer and has to reimplement it to write that test at all
+//   (found: homeflare-ct100 PR #1). `containerProblems`/`refuseContainer`/`serviceNameFor` stay
+//   internal — no consumer need for those was raised, and validation/naming internals are a wider
+//   surface to commit to than one pure render function.
+export {
+  containerPathFor,
+  QUADLET_DEFAULT_DIRECTORY,
+  QUADLET_SEARCH_DIRECTORIES,
+  renderContainerFile,
+} from './container-form.ts';
 export { PodmanContainer, PodmanContainerProvider } from './container.ts';

package/src/proxmox/constraints-host-forms.test.ts

@@ -11,7 +11,7 @@
 import { describe, expect, test } from 'bun:test';
 import { constraintsFor, formViolations } from './constraint-guard.ts';
 import type { PbsTarget, PveTarget } from './credentials.ts';
-import { createBody as ifaceCreateForm } from './node-network-form.ts';
+import { createForm as ifaceCreateForm } from './node-network-form.ts';
 import { resolveGroups, targetForm } from './pbs-notification-target-form.ts';
 import { createForm as zfsCreateForm } from './zfs-pool-form.ts';
 
@@ -26,7 +26,7 @@ describe('the host families plan clean against their own creates', () => {
    * 🔴 THE BUG THIS PROOF FOUND. `createForm` was `body`, which never sent `iface` — and PVE marks
    *   it REQUIRED on the POST while `{node}` is the only path parameter. Every NodeNetwork create
    *   this repository could have made would have 400ed; nothing caught it because C1's three nodes
-   *   were all adopted, which takes the PUT path. See the 🔴 on `createBody`.
+   *   were all adopted, which takes the PUT path. See the 🔴 on `createForm`.
    */
   test('an interface create carries iface, which PVE requires in the body', () => {
     const form = ifaceCreateForm({

package/src/proxmox/network-apply-read.ts

@@ -18,6 +18,12 @@
  *   drops the envelope, so the one readable pending signal is invisible to every other resource in
  *   this package. Without the fetch below, `Proxmox.NetworkApply` could not diff honestly at all.
  *   ★ `pveEnvelopeWith` in client.ts now carries the same member failover as every other call.
+ *   ⛔ WHY THIS FAMILY DID NOT MOVE TO DISTILLED WITH `Proxmox.NodeNetwork` (2026-09-24, decision
+ *     43's walk-down): CONFIRMED against `@distilled.cloud/proxmox`'s own `protocol.ts` that its
+ *     `transformResponse` unconditionally returns `body.data ?? {}` for every operation, before a
+ *     generated call's typed output is even built — no typed call, current or future, could see
+ *     `changes` without a protocol-level change upstream. `pveEnvelopeWith` stays because nothing
+ *     else preserves the sibling this function needs.
  *
  * ⛔ AND THE INTERFACE ROWS CANNOT TELL YOU EITHER. MEASURED in PVE/INotify.pm `read_file`: when
  *   `/etc/network/interfaces.new` exists, THAT is the file that gets parsed, so
@@ -188,6 +194,12 @@ const ATTEMPTS = 30;
  *   of the task". Every mint returns a NEW token id, so a second mint is a different identity and
  *   is not the owner — which is why this takes a `PveCredential` and the caller keeps one lease
  *   across both calls, instead of widening the provisioning role to read its own tasks.
+ *
+ * ⛔ THE OTHER REASON THIS FAMILY DID NOT MOVE TO DISTILLED (2026-09-24): CHECKED against
+ *   `@distilled.cloud/proxmox`'s own `Task.awaitTask` (`src/task.ts`) before deciding — it
+ *   propagates a poll failure as a genuine typed `GetNodeTaskStatusError` rather than collapsing
+ *   it to `UNREACHABLE` the way this function does, which would turn the ⛔ two paragraphs above
+ *   into a failed `reconcile` on exactly the poll a mid-reload connection drop is expected to hit.
  */
 export const awaitTask = (
   target: PveTarget,

package/src/proxmox/network-apply.ts

@@ -44,6 +44,8 @@
  *   task it starts so it can poll it without `Sys.Audit`. ⛔ `Sys.Modify` ON A NODE IS NOT A SMALL
  *   GRANT — it also carries that node's DNS, hosts file, time and service configuration. Granting
  *   it cluster-wide to run this resource widens the provisioning role well beyond networking.
+ *
+ * ⛔ STAYS ON `client.ts` (2026-09-24) — network-apply-read.ts's header has the two MEASURED reasons.
  */
 import { Resource } from 'alchemy';
 import { isResolved } from 'alchemy/Diff';