@homeflare/alchemy 0.51.0 → 0.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.51.0",
+  "version": "0.53.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",

package/src/grafana/folder-permission.test.ts

@@ -0,0 +1,107 @@
+/**
+ * `Grafana.FolderPermission` against a fake Grafana: only DIRECT team entries count, writes go through
+ * the per-team endpoint (never the whole-list replace), missing team fails loudly, delete sets "".
+ */
+import { describe, expect, test } from 'bun:test';
+import type { GrafanaOpContext } from '@distilled.cloud/grafana/Protocol';
+import * as Effect from 'effect/Effect';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { spec } from './folder-permission.ts';
+import { grafanaOperations } from './resource.ts';
+
+const TEAMS = '/api/teams/search';
+const PERMS = '/api/access-control/folders/village-grafana';
+const SET = '/api/access-control/folders/village-grafana/teams/7';
+const teamRow = {
+  id: 7,
+  uid: 'aex7',
+  name: 'village-grafana',
+  isProvisioned: false,
+  memberCount: 0,
+  orgId: 1,
+};
+const props = {
+  folderUid: 'village-grafana',
+  teamName: 'village-grafana',
+  permission: 'Edit' as const,
+};
+const run = <A, E>(
+  fake: ReturnType<typeof fakeGrafana>,
+  effect: Effect.Effect<A, E, GrafanaOpContext>,
+): Promise<A> => Effect.runPromise(effect.pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))));
+
+const grafanaWith = (entries: () => unknown[], teams = [teamRow]) =>
+  fakeGrafana((m, url) => {
+    if (m === 'GET' && url.pathname === TEAMS)
+      return Response.json({ teams, totalCount: teams.length });
+    if (m === 'GET' && url.pathname === PERMS) return Response.json(entries());
+    if (m === 'POST' && url.pathname === SET)
+      return Response.json({ message: 'Permission updated' });
+    return fakeFailure(404, `unexpected ${m} ${url.pathname}`);
+  });
+
+describe('Grafana.FolderPermission', () => {
+  test('an inherited entry for the team does not count as live', async () => {
+    const fake = grafanaWith(() => [
+      { teamId: 7, permission: 'Edit', isInherited: true },
+      { builtInRole: 'Admin', permission: 'Admin' },
+    ]);
+    expect(await run(fake, spec.fetchLive(props))).toBeUndefined();
+  });
+
+  test('a matching direct entry adopts with no write', async () => {
+    const fake = grafanaWith(() => [
+      { builtInRole: 'Viewer', permission: 'View', isInherited: true },
+      { teamId: 7, team: 'village-grafana', permission: 'Edit', isInherited: false },
+    ]);
+    const out = await run(fake, grafanaOperations(spec).reconcile(props));
+    expect(out).toEqual({
+      folderUid: 'village-grafana',
+      teamId: 7,
+      teamName: 'village-grafana',
+      permission: 'Edit',
+    });
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('create writes only through the per-team endpoint', async () => {
+    const state = { set: false };
+    const fake = fakeGrafana((m, url) => {
+      if (m === 'GET' && url.pathname === TEAMS)
+        return Response.json({ teams: [teamRow], totalCount: 1 });
+      if (m === 'GET' && url.pathname === PERMS)
+        return Response.json(
+          state.set ? [{ teamId: 7, permission: 'Edit', isInherited: false }] : [],
+        );
+      if (m === 'POST' && url.pathname === SET) {
+        state.set = true;
+        return Response.json({ message: 'Permission updated' });
+      }
+      return fakeFailure(404, `unexpected ${m} ${url.pathname}`);
+    });
+    await run(fake, grafanaOperations(spec).reconcile(props));
+    expect(fake.seen.filter((s) => s.method === 'POST')).toEqual([{ method: 'POST', path: SET }]);
+    expect(fake.bodies.filter((b) => b !== undefined)).toEqual([{ permission: 'Edit' }]);
+  });
+
+  test('a permission drift (View live, Edit declared) updates', async () => {
+    const fake = grafanaWith(() => [{ teamId: 7, permission: 'View', isInherited: false }]);
+    await run(fake, Effect.flip(grafanaOperations(spec).reconcile(props))).catch(() => undefined);
+    expect(fake.seen.some((s) => s.method === 'POST' && s.path === SET)).toBe(true);
+  });
+
+  test('a missing team fails loudly, never folds to absent', async () => {
+    const fake = grafanaWith(() => [], []);
+    const failure = await run(fake, Effect.flip(spec.fetchLive(props)));
+    expect((failure as { _tag: string })._tag).toBe('GrafanaTeamNotFoundError');
+  });
+
+  test('delete sets the empty permission, and is a no-op when already absent', async () => {
+    const live = grafanaWith(() => [{ teamId: 7, permission: 'Edit', isInherited: false }]);
+    await run(live, grafanaOperations(spec).destroy(props));
+    expect(live.bodies.filter((b) => b !== undefined)).toEqual([{ permission: '' }]);
+    const gone = grafanaWith(() => []);
+    await run(gone, grafanaOperations(spec).destroy(props));
+    expect(gone.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+});

package/src/grafana/folder-permission.ts

@@ -0,0 +1,128 @@
+/**
+ * `Grafana.FolderPermission` — ONE team's DIRECT permission on ONE folder.
+ *
+ * Walked against `@distilled.cloud/grafana` 0.2.1 (`@homeflare/distilled-grafana`):
+ * `getResourcePermissions` (`GET /access-control/folders/{uid}`) and `setResourcePermissionsForTeam`
+ * (`POST /access-control/folders/{uid}/teams/{teamId}`).
+ *
+ * ★ ADDITIVE BY CONSTRUCTION. The per-team endpoint touches only that team's managed entry; the
+ *   folder's other entries (built-in roles, admin users, other teams, anything inherited from a parent
+ *   folder) are never read into a write and never changed. The whole-list `setResourcePermissions`
+ *   would replace them all — deliberately not used.
+ * ★ ONLY DIRECT ENTRIES COUNT. An entry inherited from a parent folder (`isInherited`) is not this
+ *   resource's object: it can't be changed here, so it never satisfies a declaration either.
+ * ★ The team is named, not numbered. Team ids differ per instance, so `teamName` is resolved through
+ *   `findTeamByName` on every read and write; a missing team fails loudly with
+ *   `GrafanaTeamNotFoundError` (declare the `Grafana.Team` first) instead of folding to "absent".
+ * ★ delete = set the team's permission to "" (Grafana's documented way to remove a managed entry),
+ *   idempotent: an already-absent entry is a no-op (S11).
+ */
+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';
+import { findTeamByName } from './team.ts';
+
+export type FolderPermissionLevel = 'View' | 'Edit' | 'Admin';
+
+export interface FolderPermissionProps {
+  folderUid: string;
+  teamName: string;
+  permission: FolderPermissionLevel;
+}
+
+export interface FolderPermissionAttributes {
+  folderUid: string;
+  teamId: number;
+  teamName: string;
+  permission: string;
+}
+
+export interface GrafanaFolderPermission extends Resource<
+  'Grafana.FolderPermission',
+  FolderPermissionProps,
+  FolderPermissionAttributes,
+  never
+> {}
+
+export const GrafanaFolderPermission = Resource<GrafanaFolderPermission>(
+  'Grafana.FolderPermission',
+);
+
+export class GrafanaTeamNotFoundError extends Data.TaggedError('GrafanaTeamNotFoundError')<{
+  readonly message: string;
+}> {}
+
+interface LivePermission {
+  readonly teamId: number;
+  readonly permission: string;
+}
+
+const resolveTeamId = (teamName: string) =>
+  findTeamByName(teamName).pipe(
+    Effect.flatMap((team) =>
+      team === undefined
+        ? Effect.fail(
+            new GrafanaTeamNotFoundError({
+              message: `Grafana.FolderPermission: team '${teamName}' does not exist. Declare it with Grafana.Team first.`,
+            }),
+          )
+        : Effect.succeed(team.id),
+    ),
+  );
+
+const setTeam = (folderUid: string, teamId: number, permission: string) =>
+  grafana.setResourcePermissionsForTeam({
+    resource: 'folders',
+    resourceID: folderUid,
+    teamID: teamId,
+    permission,
+  });
+
+export const spec: GrafanaSpec<
+  FolderPermissionProps,
+  LivePermission,
+  FolderPermissionAttributes,
+  | grafana.SearchTeamsError
+  | grafana.GetResourcePermissionsError
+  | grafana.SetResourcePermissionsForTeamError
+  | GrafanaTeamNotFoundError
+> = {
+  attributes: (live, props) => ({
+    folderUid: props.folderUid,
+    permission: live.permission,
+    teamId: live.teamId,
+    teamName: props.teamName,
+  }),
+  create: (props) =>
+    resolveTeamId(props.teamName).pipe(
+      Effect.flatMap((teamId) => setTeam(props.folderUid, teamId, props.permission)),
+    ),
+  destroy: (props, live) => setTeam(props.folderUid, live.teamId, ''),
+  fetchLive: (props) =>
+    Effect.gen(function* () {
+      const teamId = yield* resolveTeamId(props.teamName);
+      const entries = yield* grafana.getResourcePermissions({
+        resource: 'folders',
+        resourceID: props.folderUid,
+      });
+      const direct = (entries ?? []).find(
+        (entry) => entry.teamId === teamId && entry.isInherited !== true,
+      );
+      return direct === undefined
+        ? undefined
+        : { permission: direct.permission ?? '', teamId: teamId };
+    }),
+  matches: (attributes, props) => attributes.permission === props.permission,
+  update: (props, live) => setTeam(props.folderUid, live.teamId, props.permission),
+};
+
+export const handlers = grafanaHandlers(spec);
+
+export const GrafanaFolderPermissionProvider = () =>
+  Provider.effect(
+    GrafanaFolderPermission,
+    Effect.succeed(GrafanaFolderPermission.Provider.of(handlers)),
+  );

package/src/grafana/index.ts

@@ -8,7 +8,7 @@
  *
  * `Grafana.Datasource`, `Grafana.Folder`, `Grafana.Dashboard`, `Grafana.ContactPoint`,
  * `Grafana.MuteTiming`, `Grafana.MessageTemplate`, `Grafana.AlertRuleGroup` and
- * `Grafana.NotificationPolicy` all ship here — see docs/grafana.md, docs/grafana-folder-dashboard.md,
+ * `Grafana.NotificationPolicy`, `Grafana.Team` and `Grafana.FolderPermission` all ship here — see docs/grafana.md, docs/grafana-folder-dashboard.md,
  * docs/grafana-alerting.md, docs/grafana-alerting-rules.md and
  * docs/grafana-notification-policy.md for what shipped.
  */
@@ -46,6 +46,15 @@ export {
   GrafanaFolderProvider,
   GrafanaFolderReparentError,
 } from './folder.ts';
+export { type TeamAttributes, type TeamProps, GrafanaTeam, GrafanaTeamProvider } from './team.ts';
+export {
+  type FolderPermissionAttributes,
+  type FolderPermissionLevel,
+  type FolderPermissionProps,
+  GrafanaFolderPermission,
+  GrafanaFolderPermissionProvider,
+  GrafanaTeamNotFoundError,
+} from './folder-permission.ts';
 export {
   type ContactPointAttributes,
   type ContactPointProps,

package/src/grafana/providers.ts

@@ -18,6 +18,8 @@ import { type GrafanaTarget, grafanaCredentials } from './credentials.ts';
 import { GrafanaDashboardProvider } from './dashboard.ts';
 import { GrafanaDatasourceProvider } from './datasource.ts';
 import { GrafanaFolderProvider } from './folder.ts';
+import { GrafanaFolderPermissionProvider } from './folder-permission.ts';
+import { GrafanaTeamProvider } from './team.ts';
 import { GrafanaMessageTemplateProvider } from './message-template.ts';
 import { GrafanaMuteTimingProvider } from './mute-timing.ts';
 import { GrafanaNotificationPolicyProvider } from './notification-policy.ts';
@@ -26,6 +28,8 @@ export const grafanaProviders = (target: GrafanaTarget) =>
   Layer.mergeAll(
     GrafanaDatasourceProvider(),
     GrafanaFolderProvider(),
+    GrafanaTeamProvider(),
+    GrafanaFolderPermissionProvider(),
     GrafanaDashboardProvider(),
     GrafanaContactPointProvider(),
     GrafanaMuteTimingProvider(),

package/src/grafana/provisioned.ts

@@ -29,7 +29,7 @@ export class GrafanaProvisionedObjectError extends Data.TaggedError(
 }> {}
 
 export const refuseIfProvisioned = (
-  kind: 'Grafana.Folder' | 'Grafana.Dashboard',
+  kind: 'Grafana.Folder' | 'Grafana.Dashboard' | 'Grafana.Team',
   uid: string,
   owner: string | undefined,
 ): Effect.Effect<never, GrafanaProvisionedObjectError> => {

package/src/grafana/team.test.ts

@@ -0,0 +1,108 @@
+/**
+ * `Grafana.Team` against a fake Grafana through the real `@distilled.cloud/grafana` protocol:
+ * exact-name observe (adopt), create body, update only on drift, provisioned refusal, idempotent delete.
+ */
+import { describe, expect, test } from 'bun:test';
+import type { GrafanaOpContext } from '@distilled.cloud/grafana/Protocol';
+import * as Effect from 'effect/Effect';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { grafanaOperations } from './resource.ts';
+import { spec } from './team.ts';
+
+const team = (over: Record<string, unknown> = {}) => ({
+  id: 7,
+  uid: 'aex7',
+  name: 'village-grafana',
+  email: '',
+  isProvisioned: false,
+  memberCount: 0,
+  orgId: 1,
+  ...over,
+});
+const search = (teams: unknown[]) =>
+  Response.json({ teams, totalCount: teams.length, page: 1, perPage: 100 });
+const run = <A, E>(
+  fake: ReturnType<typeof fakeGrafana>,
+  effect: Effect.Effect<A, E, GrafanaOpContext>,
+): Promise<A> => Effect.runPromise(effect.pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))));
+const props = { name: 'village-grafana' };
+
+describe('Grafana.Team', () => {
+  test('fetchLive keeps only an exact name match, GET without a body', async () => {
+    const fake = fakeGrafana((m, url) =>
+      m === 'GET' && url.pathname === '/api/teams/search'
+        ? search([team({ name: 'village-grafana-old', id: 9 }), team()])
+        : fakeFailure(404, 'x'),
+    );
+    const live = await run(fake, spec.fetchLive(props));
+    expect(live?.id).toBe(7);
+    expect(fake.bodies[0]).toBeUndefined();
+  });
+
+  test('absent team folds to undefined; 403 propagates', async () => {
+    expect(
+      await run(
+        fakeGrafana(() => search([])),
+        spec.fetchLive(props),
+      ),
+    ).toBeUndefined();
+    const failure = await run(
+      fakeGrafana(() => fakeFailure(403, 'forbidden')),
+      Effect.flip(spec.fetchLive(props)),
+    );
+    expect((failure as { _tag: string })._tag).toBe('Forbidden');
+  });
+
+  test('reconcile adopts a matching live team with no write', async () => {
+    const fake = fakeGrafana((m) =>
+      m === 'GET' ? search([team()]) : fakeFailure(500, 'no write expected'),
+    );
+    const out = await run(fake, grafanaOperations(spec).reconcile(props));
+    expect(out).toMatchObject({ id: 7, name: 'village-grafana' });
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('reconcile creates when absent, sending only declared fields', async () => {
+    let created = false;
+    const fake = fakeGrafana((m) => {
+      if (m === 'POST') {
+        created = true;
+        return Response.json({ teamId: 7, uid: 'aex7', message: 'Team created' });
+      }
+      return search(created ? [team()] : []);
+    });
+    await run(fake, grafanaOperations(spec).reconcile(props));
+    expect(fake.bodies.filter((b) => b !== undefined)).toEqual([{ name: 'village-grafana' }]);
+  });
+
+  test('email drift updates by team id', async () => {
+    let updated = false;
+    const fake = fakeGrafana((m) => {
+      if (m === 'PUT') {
+        updated = true;
+        return Response.json({ message: 'Team updated' });
+      }
+      return search([team({ email: updated ? 'ops@example.com' : '' })]);
+    });
+    await run(fake, grafanaOperations(spec).reconcile({ ...props, email: 'ops@example.com' }));
+    expect(fake.seen.some((s) => s.method === 'PUT' && s.path === '/api/teams/7')).toBe(true);
+  });
+
+  test('a provisioned team refuses update and delete without writing', async () => {
+    const fake = fakeGrafana(() => search([team({ isProvisioned: true, email: 'a@b' })]));
+    const failure = await run(
+      fake,
+      Effect.flip(grafanaOperations(spec).reconcile({ ...props, email: 'ops@example.com' })),
+    );
+    expect((failure as { _tag: string })._tag).toBe('GrafanaProvisionedObjectError');
+    const del = await run(fake, Effect.flip(grafanaOperations(spec).destroy(props)));
+    expect((del as { _tag: string })._tag).toBe('GrafanaProvisionedObjectError');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('delete is idempotent when the team is already gone', async () => {
+    const fake = fakeGrafana(() => search([]));
+    await run(fake, grafanaOperations(spec).destroy(props));
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+});

package/src/grafana/team.ts

@@ -0,0 +1,105 @@
+/**
+ * `Grafana.Team` — a Grafana team, keyed by NAME.
+ *
+ * Walked against `@distilled.cloud/grafana` 0.2.1 (`@homeflare/distilled-grafana`): `searchTeams`,
+ * `createTeam`, `updateTeam`, `deleteTeam`. Upstream Alchemy ships no Grafana family (S1); distilled
+ * ships the SDK, so every call goes through it (S23).
+ *
+ * ★ NAME IS THE KEY, NOT `uid`. `CreateTeamRequest` takes only `name`/`email` — there is no way to
+ *   choose a team uid, and Grafana enforces unique team names per org. `fetchLive` therefore runs
+ *   `GET /teams/search?name=<name>` (an exact-name filter) and keeps only an exact match; adoption of a
+ *   team created by hand or by a script is a plain observe (S9/S10).
+ * ★ `email` is optional and compared only when declared ("undeclared means don't care", the kit's
+ *   convention for optional props).
+ * ⛔ A provisioned team (`isProvisioned`, e.g. synced from SCIM/LDAP) is refused for update and delete.
+ */
+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, refuseIfProvisioned } from './provisioned.ts';
+import { type GrafanaSpec, grafanaHandlers } from './resource.ts';
+
+export interface TeamProps {
+  /** Team name — unique per org, and this resource's identity. */
+  name: string;
+  /** Optional team email; compared only when declared. */
+  email?: string;
+}
+
+export interface TeamAttributes {
+  id: number;
+  uid: string;
+  name: string;
+  email: string;
+  isProvisioned: boolean;
+}
+
+export interface GrafanaTeam extends Resource<'Grafana.Team', TeamProps, TeamAttributes, never> {}
+
+export const GrafanaTeam = Resource<GrafanaTeam>('Grafana.Team');
+
+/** Exact-name lookup. `/teams/search?name=` is already exact in Grafana; the filter keeps that true. */
+export const findTeamByName = (name: string) =>
+  grafana
+    .searchTeams({ name, perpage: 100 })
+    .pipe(Effect.map((result) => (result.teams ?? []).find((team) => team.name === name)));
+
+export const spec: GrafanaSpec<
+  TeamProps,
+  grafana.TeamDTO,
+  TeamAttributes,
+  | grafana.SearchTeamsError
+  | grafana.CreateTeamError
+  | grafana.UpdateTeamError
+  | grafana.DeleteTeamError
+  | GrafanaProvisionedObjectError
+> = {
+  attributes: (live) => ({
+    email: live.email ?? '',
+    id: live.id,
+    isProvisioned: live.isProvisioned,
+    name: live.name,
+    uid: live.uid,
+  }),
+  create: (props) =>
+    grafana.createTeam({
+      name: props.name,
+      ...(props.email === undefined ? {} : { email: props.email }),
+    }),
+  destroy: (props, live) =>
+    Effect.gen(function* () {
+      if (live.isProvisioned) {
+        return yield* refuseIfProvisioned(
+          'Grafana.Team',
+          props.name,
+          'an external team sync (isProvisioned)',
+        );
+      }
+      yield* grafana.deleteTeam({ team_id: String(live.id) });
+    }),
+  fetchLive: (props) => findTeamByName(props.name),
+  matches: (attributes, props) =>
+    attributes.name === props.name &&
+    (props.email === undefined || attributes.email === props.email),
+  update: (props, live) =>
+    Effect.gen(function* () {
+      if (live.isProvisioned) {
+        return yield* refuseIfProvisioned(
+          'Grafana.Team',
+          props.name,
+          'an external team sync (isProvisioned)',
+        );
+      }
+      return yield* grafana.updateTeam({
+        team_id: String(live.id),
+        name: props.name,
+        ...(props.email === undefined ? {} : { email: props.email }),
+      });
+    }),
+};
+
+export const handlers = grafanaHandlers(spec);
+
+export const GrafanaTeamProvider = () =>
+  Provider.effect(GrafanaTeam, Effect.succeed(GrafanaTeam.Provider.of(handlers)));

package/src/linux/container-env-chain.test.ts

@@ -0,0 +1,135 @@
+/**
+ * The `Environment=` quoting contract, proven against a port of the three parsers a value crosses —
+ * container-env-oracle.ts, whose every rule was reproduced with the LIVE podman 5.4.2 system
+ * generator and a live systemd 257 unit (2026-10-11/12, `QUADLET_UNIT_DIRS=<dir>
+ * /usr/lib/systemd/system-generators/podman-system-generator --dryrun`; artifacts in
+ * /tmp/opencode/quadlet-quote/) — not inferred. The port's own header cites each measurement.
+ *
+ * The TEXT-level contract of the renderer itself (what we emit) is container-env-quote.test.ts;
+ * this file is the parser-level proof that what we emit SURVIVES, and that what shipped before
+ * did not. container-env-live.test.ts re-validates the port against the real generator wherever
+ * one is installed.
+ */
+import { describe, expect, test } from 'bun:test';
+import { environmentLines } from './container-env-quote.ts';
+import { renderContainerFile } from './container-form.ts';
+import { deployed } from './container-env-oracle.ts';
+
+// ── The real values this row exists for (homeflare-ct100 commit 53b84c1, grafana.container) ──
+
+const VAR = 'GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH';
+const ROLE_PATH =
+  "(contains(groups[*], 'Admin') || contains(email, 'tim@schenanigans.com')) && 'GrafanaAdmin'";
+const oracleLines = (value: string): string[] => [
+  'Environment=SCOPES=openid',
+  `Environment=${VAR}=${value}`,
+];
+
+describe('the unquoted renderer (what shipped before) corrupts values through the real chain', () => {
+  test('the deployed Grafana expression is truncated at its first space', () => {
+    const { env } = deployed(oracleLines(ROLE_PATH));
+    expect(env[VAR]).toBe('(contains(groups[*],');
+    // Everything after the first space produced no variable of its own here — it is simply gone.
+    expect(Object.keys(env).sort()).toEqual([VAR, 'SCOPES']);
+  });
+
+  test('a quoted fragment holding `=` becomes a bogus second variable (measured oracle output)', () => {
+    const { env } = deployed(
+      oracleLines("contains(groups[*], 'cn=admins,ou=people') && is_member('')"),
+    );
+    expect(env).toEqual({
+      [VAR]: 'contains(groups[*],',
+      cn: 'admins,ou=people)',
+      SCOPES: 'openid',
+    });
+  });
+
+  test('an unknown escape drops every assignment of its line, silently', () => {
+    const { env } = deployed(oracleLines('A=1 B=2\\d C=3'));
+    expect(env).toEqual({ SCOPES: 'openid' });
+  });
+
+  test('a bare % is consumed as a specifier, never literal data', () => {
+    const { env, consumed } = deployed(oracleLines('PCT=50%off'));
+    expect(consumed).toContain('%o');
+    // ⛔ Assert the VALUE the chain produced, not what it is not: `oracleLines` puts the text
+    //   under VAR, so an `env.PCT` assertion compares `undefined` and can never fail.
+    expect(env[VAR]).toBe('PCT=50ff');
+  });
+
+  test('systemd halves $$: the shipped renderer lets `pa$$word` arrive as `pa$word`', () => {
+    // Measured 2026-10-12, live systemd 257 unit: the ExecStart word `pa$$word` (no `:` prefix,
+    // so variables ARE substituted) folds to `pa$word` — systemd.service(5) §Command lines.
+    const { env, consumed } = deployed(oracleLines('pa$$word'));
+    expect(env[VAR]).toBe('pa$word');
+    expect(consumed).toEqual([]);
+  });
+
+  test('systemd erases braced variables: the shipped renderer lets a braced HOME ref arrive as `ab`', () => {
+    // oxlint-disable-next-line no-template-curly-in-string -- `${HOME}` is the measured test data, not a placeholder
+    const { env, consumed } = deployed(oracleLines('a${HOME}b'));
+    expect(env[VAR]).toBe('ab');
+    // oxlint-disable-next-line no-template-curly-in-string -- the consumed record is the literal reference systemd erased
+    expect(consumed).toEqual(['${HOME}']);
+  });
+});
+
+describe('the quoted renderer survives the same chain intact', () => {
+  test('the deployed Grafana expression round-trips exactly', () => {
+    const lines = environmentLines({
+      [VAR]: ROLE_PATH,
+      GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_STRICT: 'true',
+    }).map(([key, value]) => `${key}=${value}`);
+    const { env, consumed } = deployed(lines);
+    expect(env).toEqual({
+      [VAR]: ROLE_PATH,
+      GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_STRICT: 'true',
+    });
+    expect(consumed).toEqual([]);
+  });
+
+  test('escapes, quotes and percent signs each round-trip to the measured generator output', () => {
+    const lines = environmentLines({
+      BACKSLASH: 'C:\\path',
+      PCT: '50%off',
+      QUOTED: 'say "hi"',
+    }).map(([key, value]) => `${key}=${value}`);
+    const { env, consumed } = deployed(lines);
+    expect(env).toEqual({ BACKSLASH: 'C:\\path', PCT: '50%off', QUOTED: 'say "hi"' });
+    expect(consumed).toEqual([]);
+  });
+
+  test('dollars round-trip exactly: bcrypt hashes, braced references and $$ stay data', () => {
+    // The live-systemd counterparts of these three arrived corrupted under the shipped renderer
+    // (the two tests above); each `$` doubled to `$$` — systemd's literal-dollar escape — makes
+    // the fold restore exactly the declared bytes. `$2y$10$abc` is a bcrypt hash prefix: the
+    // common real-world `$` value this round trip must hold.
+    // oxlint-disable-next-line no-template-curly-in-string -- `${HOME}` is the measured test data, not a placeholder
+    const declared = { B: 'a${HOME}b', C: '$2y$10$abc', D: 'pa$$word' };
+    const lines = environmentLines(declared).map(([key, value]) => `${key}=${value}`);
+    const { env, consumed } = deployed(lines);
+    expect(env).toEqual(declared);
+    expect(consumed).toEqual([]);
+  });
+});
+
+describe('renderContainerFile wires the quoting in — end to end through the chain', () => {
+  const props = {
+    name: 'grafana-primary',
+    container: {
+      environmentFile: ['/etc/grafana-primary/env'],
+      environment: { [VAR]: ROLE_PATH, GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_STRICT: 'true' },
+      image: 'docker.io/grafana/grafana:12.2.1',
+      network: 'host',
+    },
+  };
+
+  test('what the container would receive equals what was declared', () => {
+    const envLines = renderContainerFile(props)
+      .split('\n')
+      .filter((line) => line.startsWith('Environment='));
+    const { env, consumed } = deployed(envLines);
+    expect(env).toEqual(props.container.environment);
+    expect(consumed).toEqual([]);
+  });
+});