@homeflare/alchemy 0.50.0 → 0.52.0

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([]);
+  });
+});

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

@@ -0,0 +1,115 @@
+/**
+ * The LIVE cross-check: the oracle port (container-env-oracle.ts) against the REAL
+ * `podman-system-generator`, wherever one is installed — the same dry run that produced every
+ * measured `--env` quote in this family's headers (podman 5.4.2, `QUADLET_UNIT_DIRS=<tmpdir>
+ * /usr/lib/systemd/system-generators/podman-system-generator --dryrun`, 2026-10-11/12).
+ *
+ * ★ WHY A TEST AND NOT A ONE-OFF: the pinned bytes in container-env-chain.test.ts hold the
+ *   contract between re-measurements; this test RE-MEASURES it, on every `bun test`, on any
+ *   machine with podman's generator. A podman update that changes what the generator emits for
+ *   these lines fails here first — and the oracle and its pins get re-measured together, not
+ *   silently left describing an old generator.
+ * ⚠️ SKIPS WHERE THE GENERATOR IS ABSENT (CI, macOS): the pinned tests still hold the contract
+ *   there; a skip is honest about what was not re-measured on that machine, rather than green
+ *   by assumption.
+ * ⛔ NOTHING AT STAKE: `--dryrun` prints the generated unit to stderr and writes nothing — no
+ *   daemon-reload, no unit start, no image pull, nothing touches a live host.
+ */
+import { describe, expect, test } from 'bun:test';
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { renderContainerFile } from './container-form.ts';
+import { quadletEnvArgs } from './container-env-quadlet-oracle.ts';
+
+const GENERATOR = '/usr/lib/systemd/system-generators/podman-system-generator';
+
+/** Every character class this row measured: `$`, `%`, `"`, `\`, a space, and Grafana's own text. */
+const ENVIRONMENT = {
+  // oxlint-disable-next-line no-template-curly-in-string -- `${HOME}` is the measured test data, not a placeholder
+  B: 'a${HOME}b',
+  BACKSLASH: 'C:\\path',
+  C: '$2y$10$abc',
+  D: 'pa$$word',
+  PCT: '50%off',
+  QUOTED: 'say "hi"',
+  SPACED: 'a b',
+} as const;
+
+/** The dry run's printed unit text (both streams — the generator logs to stderr). */
+const generatedExecStart = async (dir: string, unitDirs: string): Promise<string> => {
+  const proc = Bun.spawn([GENERATOR, '--dryrun'], {
+    cwd: dir,
+    env: { ...process.env, QUADLET_UNIT_DIRS: unitDirs },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  const [out, err] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  if ((await proc.exited) !== 0) throw new Error(`generator exited non-zero:\n${out}${err}`);
+  const line = [...err.split('\n'), ...out.split('\n')].find((l) => l.startsWith('ExecStart='));
+  if (line === undefined) throw new Error(`no ExecStart= in generator output:\n${out}${err}`);
+  return line.slice('ExecStart='.length);
+};
+
+describe('the oracle replays against the live podman generator (when installed)', () => {
+  // Quadlet emits the `--env` arguments contiguously, in the .container file's key order, just
+  // before the trailing image word (measured, artifacts gen.service / old-gen/gen.out) — so the
+  // whole segment is compared at once: content AND order, byte for byte.
+  test.skipIf(!existsSync(GENERATOR))(
+    'quadlet emits exactly the --env args the oracle models, quoted renderer',
+    async () => {
+      const image = 'docker.io/library/alpine:3';
+      const file = renderContainerFile({
+        name: 'dollar',
+        container: { image, environment: ENVIRONMENT },
+      });
+      const envLines = file.split('\n').filter((line) => line.startsWith('Environment='));
+      const dir = mkdtempSync(join(tmpdir(), 'hf-quadlet-live-'));
+      try {
+        writeFileSync(join(dir, 'dollar.container'), file);
+        const args = await generatedExecStart(dir, dir);
+        const segment = args.slice(args.indexOf('--env '), args.lastIndexOf(' '));
+        expect(segment).toBe(
+          quadletEnvArgs(envLines)
+            .map((arg) => `--env ${arg}`)
+            .join(' '),
+        );
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    },
+  );
+
+  // The shipped (unquoted) renderer, through the same live run: parser 1's split and skip must
+  // reproduce the corruption the chain tests pin — `TRUNC=a b c` yields one variable, not three.
+  test.skipIf(!existsSync(GENERATOR))(
+    'quadlet emits exactly the --env args the oracle models, unquoted renderer',
+    async () => {
+      const lines = [
+        'Environment=DOLLAR2=pa$$word',
+        'Environment=TRUNC=a b c',
+        // oxlint-disable-next-line no-template-curly-in-string -- the measured old-renderer line, not a placeholder
+        'Environment=DOLLARBRACE=a${HOME}b',
+      ];
+      const dir = mkdtempSync(join(tmpdir(), 'hf-quadlet-live-'));
+      try {
+        writeFileSync(
+          join(dir, 'old.container'),
+          ['[Container]', 'Image=docker.io/library/alpine:3', ...lines, ''].join('\n'),
+        );
+        const args = await generatedExecStart(dir, dir);
+        const segment = args.slice(args.indexOf('--env '), args.lastIndexOf(' '));
+        expect(segment).toBe(
+          quadletEnvArgs(lines)
+            .map((arg) => `--env ${arg}`)
+            .join(' '),
+        );
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    },
+  );
+});

package/src/linux/container-env-oracle.ts

@@ -0,0 +1,109 @@
+/**
+ * The `Environment=` oracle — a PORT of the three parsers a declared env value crosses, from
+ * `Environment=` line to what the container actually receives. The quadlet half (read, re-emit)
+ * is container-env-quadlet-oracle.ts; this file holds the SYSTEMD half — the `%` and `$` folds —
+ * and the composed chain. Every rule was MEASURED, not inferred (live podman 5.4.2
+ * `podman-system-generator --dryrun`, and a live systemd 257 unit start, 2026-10-11/12):
+ *
+ *   3. systemd parses the generated `ExecStart=` with the same splitter, then folds BOTH
+ *      expansion syntaxes: `%%` → one literal `%`, every other `%x` consumed as a specifier (an
+ *      unknown one invalidates the unit — systemd.unit(5) §Specifiers); and the `$` rules of
+ *      systemd.service(5) §Command lines (v257), measured against a live unit: `$$` → one literal
+ *      `$`; `${NAME}` "erased and replaced by the exact value of the environment variable" —
+ *      modelled here as UNSET, so recorded in `consumed` and replaced with the empty string — and
+ *      any other `$` mid-word stays literal, because unbraced expansion applies only to a word
+ *      that is EXACTLY `$FOO`, which a `KEY=value` word never is. An unterminated `${` stays
+ *      literal too (measured: `x${UNCLOSED` arrived intact). The generated ExecStart has no `:`
+ *      prefix, so variable substitution always applies. Measured end to end: the UNQUOTED
+ *      renderer's `pa$$word` arrives as `pa$word` (halved) and its `a${HOME}b` as `ab` (erased),
+ *      while the quoted-and-escaped forms of the same values arrive intact.
+ *
+ * ★ `consumed` IS THE FAILURE SIGNAL — a non-empty list means a `%x` or `${NAME}` the renderer let
+ *   through as data was eaten downstream, so the declared value did not survive (expanded away, or
+ *   the unit invalidated). The live unit also logged
+ *   `Referenced but unset environment variable evaluates to an empty string` for every `${NAME}`
+ *   — the host-side tell, in `journalctl`, if one ever escapes the renderer at deploy time.
+ * ⚠️ WHY A PORT, NOT THE REAL PARSERS: the real generator runs root-side per host, and starting a
+ *   unit IS a deploy — neither can be a unit test's dependency. The port lets every renderer
+ *   change replay the measured bytes in CI; container-env-live.test.ts re-validates the port
+ *   against the REAL generator wherever podman is installed, so port and pins stay honest.
+ */
+import { quadletEnvArgs, splitWords } from './container-env-quadlet-oracle.ts';
+
+/**
+ * Parser 3's `%` rules: `%%` folds to one literal `%`; every other `%x` is a specifier systemd
+ * consumes, so it is recorded — a non-empty record means the declared value did not survive
+ * (expanded away, or the unit invalidated).
+ */
+const foldSpecifiers = (text: string): { text: string; consumed: string[] } => {
+  const consumed: string[] = [];
+  const folded = text.replace(/%(.)/g, (_all, c: string) => {
+    if (c === '%') return '%';
+    consumed.push(`%${c}`);
+    return '';
+  });
+  return { text: folded, consumed };
+};
+
+/**
+ * Parser 3's `$` rules, left-to-right in ONE scan — a fold that ran two passes could not tell
+ * `pa$$$$word` (the escaped `pa$$word`) from anything else. systemd.service(5) §Command lines
+ * (v257), measured against a live unit: `$$` → one literal `$`; `${NAME}` → its value (unset →
+ * empty, recorded); any other `$` mid-word stays literal — unbraced expansion applies only to a
+ * word that is EXACTLY `$FOO`, and this oracle only ever folds `KEY=value` words.
+ */
+const foldDollars = (text: string): { text: string; consumed: string[] } => {
+  const consumed: string[] = [];
+  let out = '';
+  let i = 0;
+  while (i < text.length) {
+    const c = text.charAt(i);
+    if (c !== '$') {
+      out += c;
+      i++;
+      continue;
+    }
+    const next = text.charAt(i + 1);
+    if (next === '$') {
+      out += '$';
+      i += 2;
+      continue;
+    }
+    if (next === '{') {
+      const end = text.indexOf('}', i + 2);
+      if (end === -1) {
+        out += text.slice(i);
+        break;
+      }
+      consumed.push(text.slice(i, end + 1));
+      i = end + 1;
+      continue;
+    }
+    out += '$';
+    i++;
+  }
+  return { text: out, consumed };
+};
+
+/** Parser 3: what a `--env`-shaped ExecStart word becomes at the container — both folds applied. */
+const deployArgs = (
+  args: readonly string[],
+): { env: Record<string, string>; consumed: string[] } => {
+  const env: Record<string, string> = {};
+  const consumed: string[] = [];
+  for (const arg of args) {
+    const word = splitWords(arg)?.[0];
+    if (word === undefined) continue;
+    const specifiers = foldSpecifiers(word);
+    const dollars = foldDollars(specifiers.text);
+    consumed.push(...specifiers.consumed, ...dollars.consumed);
+    const eq = dollars.text.indexOf('=');
+    if (eq > 0) env[dollars.text.slice(0, eq)] = dollars.text.slice(eq + 1);
+  }
+  return { env, consumed };
+};
+
+/** The whole chain over rendered `Environment=` lines → what the container actually receives. */
+export const deployed = (
+  lines: readonly string[],
+): { env: Record<string, string>; consumed: string[] } => deployArgs(quadletEnvArgs(lines));

package/src/linux/container-env-quadlet-oracle.ts

@@ -0,0 +1,174 @@
+/**
+ * The QUADLET half of the `Environment=` oracle — how podman reads an `Environment=` line and
+ * re-emits it as `--env` arguments of the generated unit's `ExecStart=`. The systemd half (the
+ * `$`/`%` folds) and the composed chain live in container-env-oracle.ts, whose header carries
+ * the three-parser overview; every rule below was MEASURED against the live podman 5.4.2
+ * generator (2026-10-11/12), not inferred.
+ *
+ *   1. quadlet reads the line's value with systemd's own splitter (pkg/systemd/parser/unitfile.go
+ *      `LookupAllKeyVal` → `splitString(value, " \t\n\r", SplitRelax | SplitUnquote |
+ *      SplitCUnescape)`, podman v5.4.0). Measured: an unquoted space ends the assignment there
+ *      (`ROLE_ATTRIBUTE_PATH` was truncated at its first space); quoted fragments are unquoted
+ *      and re-parsed (`'cn=admins,ou=people')` became the bogus variable `cn`); words without
+ *      `=` are silently skipped; an unknown C escape (`\d`) drops EVERY assignment of that line,
+ *      silently.
+ *   2. quadlet re-emits each assignment as one `--env` argument (podman `addEnv` → `AddCmdline` →
+ *      `escapeWords`, pkg/systemd/parser/split.go v5.4.2): re-escaped, and wrapped in double quotes
+ *      iff ANY character needs escape — `wordNeedEscape`'s set: whitespace, control characters,
+ *      `"`, `'` and `\` — never touching `%` or `$`, which pass through verbatim. Measured:
+ *      `Environment="D=pa$$$$word"` → `--env D=pa$$$$word`, and the single quotes in Grafana's
+ *      role path stayed literal inside the double-quoted `--env "…'Admin'…"`.
+ */
+
+/**
+ * Parsers 1+2 composed: the assignments quadlet reads out of rendered `Environment=` lines, then
+ * the `--env` arguments it emits for them. Exported for container-env-live.test.ts, which replays
+ * this against the REAL generator wherever one is installed.
+ */
+export const quadletEnvArgs = (lines: readonly string[]): string[] => {
+  const told: Record<string, string> = {};
+  for (const line of lines) {
+    const words = splitWords(line.slice('Environment='.length));
+    if (words !== undefined) Object.assign(told, parseAssignments(words));
+  }
+  return emitPodmanArgs(told);
+};
+
+/** Podman's own separator set — `WhitespaceSeparators = " \t\n\r"` (split.go v5.4.2), NOT the
+ *  fuller C-locale whitespace: a raw `\f` or `\v` is a word character to quadlet, not a break. */
+const WHITESPACE = ' \t\n\r';
+
+const C_UNESCAPES: Record<string, string> = {
+  a: '\x07',
+  b: '\b',
+  f: '\f',
+  n: '\n',
+  r: '\r',
+  t: '\t',
+  v: '\v',
+  '\\': '\\',
+  '"': '"',
+  "'": "'",
+  0: '\0',
+};
+
+/**
+ * Parser 1: systemd's `splitString(value, WhitespaceSeparators, SplitRelax | SplitUnquote |
+ * SplitCUnescape)`. Returns the words, or `undefined` when the split FAILS — which is what turns
+ * into "every assignment on this line silently dropped" (measured, see header). Quotes are
+ * stripped and their content kept; `\xNN` is unescaped like the simple table.
+ */
+export const splitWords = (value: string): string[] | undefined => {
+  const words: string[] = [];
+  let word = '';
+  let quote: '"' | "'" | undefined;
+  let i = 0;
+  let started = false;
+  while (i < value.length) {
+    const c = value.charAt(i);
+    if (quote === undefined && WHITESPACE.includes(c)) {
+      if (started) words.push(word);
+      word = '';
+      started = false;
+      i++;
+      continue;
+    }
+    if (c === '\\') {
+      // CUNESCAPE applies inside and outside quotes; an unknown escape fails the whole split.
+      const next = value[i + 1];
+      if (next === undefined) return undefined;
+      if (next === 'x' && /^[0-9a-fA-F]{2}/.test(value.slice(i + 2, i + 4))) {
+        word += String.fromCharCode(parseInt(value.slice(i + 2, i + 4), 16));
+        i += 4;
+        started = true;
+        continue;
+      }
+      const unescaped = C_UNESCAPES[next];
+      if (unescaped === undefined) return undefined;
+      word += unescaped;
+      started = true;
+      i += 2;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      if (quote === c) quote = undefined;
+      else if (quote === undefined) {
+        quote = c;
+        started = true;
+      } else word += c;
+      i++;
+      continue;
+    }
+    word += c;
+    started = true;
+    i++;
+  }
+  if (started) words.push(word);
+  return words;
+};
+
+/** A word without `=` is not an assignment — measured: silently skipped, never an error. */
+export const parseAssignments = (words: readonly string[]): Record<string, string> => {
+  const env: Record<string, string> = {};
+  for (const word of words) {
+    const eq = word.indexOf('=');
+    if (eq <= 0) continue;
+    env[word.slice(0, eq)] = word.slice(eq + 1);
+  }
+  return env;
+};
+
+/**
+ * `wordNeedEscape`'s set, ported from podman pkg/systemd/parser/split.go (v5.4.2): a character
+ * forces quoting iff it is ASCII whitespace or control (`<= 0x20` or `0x7f`), a double or single
+ * quote, or a backslash — "unicode is ok" is the source's own comment, so anything above `0x80`
+ * passes. ⚠️ Note the SINGLE quote: podman quotes a word containing one even though escaping
+ * leaves it literal — a port that only quotes what escaping CHANGES would drift from the real
+ * `--env` bytes for values like `it's`.
+ */
+const needEscape = (word: string): boolean => {
+  for (const c of word) {
+    const code = c.charCodeAt(0);
+    if (code > 128) continue;
+    if (code <= 0x20 || code === 0x7f || c === '"' || c === "'" || c === '\\') return true;
+  }
+  return false;
+};
+
+/** `escapeString`'s table (same source): podman re-escapes the C control codes and `"`/`\`
+ *  inside the double quotes it adds, and writes a literal space and `'` — safe inside `"`. */
+const REESCAPES: Record<string, string> = {
+  '\x07': '\\a',
+  '\b': '\\b',
+  '\f': '\\f',
+  '\n': '\\n',
+  '\r': '\\r',
+  '\t': '\\t',
+  '\v': '\\v',
+  '\\': '\\\\',
+  '"': '\\"',
+  "'": "'",
+  ' ': ' ',
+};
+
+/** Parser 2: re-emit as one `--env` argument — escaped, and quoted iff any character needs it.
+ *  ⚠️ KEYS SORTED, NOT INSERTION-ORDERED: podman's `addEnv` → `addKeys` collects the map's keys
+ *  and `sort.Strings`s them before emitting (pkg/systemd/quadlet/podmancmdline.go, v5.4.2), so
+ *  the generated ExecStart holds the assignments sorted by key whatever order the file declared
+ *  them in — measured: a file declaring DOLLAR2, TRUNC, DOLLARBRACE emitted DOLLAR2, DOLLARBRACE,
+ *  TRUNC. The sort here compares UTF-16 code units like the renderer's own; for the ASCII env
+ *  key names in play it is Go's byte order exactly. */
+export const emitPodmanArgs = (env: Readonly<Record<string, string>>): string[] =>
+  Object.entries(env)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([key, value]) => {
+      const word = `${key}=${value}`;
+      if (!needEscape(word)) return word;
+      let escaped = '"';
+      for (const c of word) {
+        const known = c.charCodeAt(0) <= 128 ? REESCAPES[c] : undefined;
+        escaped +=
+          known ?? (needEscape(c) ? `\\x${c.charCodeAt(0).toString(16).padStart(2, '0')}` : c);
+      }
+      return `${escaped}"`;
+    });

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

@@ -0,0 +1,131 @@
+/**
+ * The TEXT-level contract of the `Environment=` renderer: what `quoteEnvironmentValue` /
+ * `environmentLines` emit, that newlines are refused rather than encoded, and that
+ * `renderContainerFile` places the quoted block where the unquoted renderer had it.
+ *
+ * ⛔ Every expected string below was accepted by the LIVE podman 5.4.2 system generator (measured
+ *   2026-10-11/12, artifacts in /tmp/opencode/quadlet-quote/): the generator read each quoted line
+ *   as exactly ONE assignment. What those bytes BECOME through quadlet's splitter, podman's
+ *   re-emission and systemd's ExecStart parsing is the parser-level proof —
+ *   container-env-chain.test.ts, which also shows the old unquoted renderer corrupting the same
+ *   values through the same chain.
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+  QuadletEnvironmentValueError,
+  environmentLines,
+  environmentValueProblems,
+  quoteEnvironmentValue,
+} from './container-env-quote.ts';
+import { containerProblems, renderContainerFile } from './container-form.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'";
+
+describe('the rendered text', () => {
+  test('the deployed Grafana expression, quoted whole', () => {
+    expect(environmentLines({ [VAR]: ROLE_PATH })).toEqual([
+      [
+        'Environment',
+        `"${VAR}=(contains(groups[*], 'Admin') || contains(email, ` +
+          `'tim@schenanigans.com')) && 'GrafanaAdmin'"`,
+      ],
+    ]);
+  });
+
+  test('escapes, quotes and percent signs, exactly as the generator accepted them', () => {
+    expect(
+      environmentLines({ BACKSLASH: 'C:\\path', PCT: '50%off', QUOTED: 'say "hi"' }).map(
+        ([key, value]) => `${key}=${value}`,
+      ),
+    ).toEqual([
+      String.raw`Environment="BACKSLASH=C:\\path"`,
+      String.raw`Environment="PCT=50%%off"`,
+      String.raw`Environment="QUOTED=say \"hi\""`,
+    ]);
+  });
+
+  test('dollar signs are doubled for systemd, exactly as the generator accepted them', () => {
+    // ⛔ THE PIN THE 2026-10-12 FIX ROUND ADDS: systemd.service(5) §Command lines (v257, measured
+    //   against a live unit) folds `$$` to one literal `$` and erases `${FOO}`, so a `$` left bare
+    //   is data the container never receives: `pa$$word` arrived as `pa$word`, `a${HOME}b` as `ab`.
+    expect(
+      // oxlint-disable-next-line no-template-curly-in-string -- the declared value under test, not a placeholder
+      environmentLines({ B: 'a${HOME}b', D: 'pa$$word' }).map(([key, value]) => `${key}=${value}`),
+    ).toEqual(
+      // oxlint-disable-next-line no-template-curly-in-string -- the measured bytes the renderer must emit
+      ['Environment="B=a$${HOME}b"', 'Environment="D=pa$$$$word"'],
+    );
+  });
+
+  test('keys are sorted, so the render is stable for an unordered plain object', () => {
+    expect(environmentLines({ B: '2', A: '1' })).toEqual([
+      ['Environment', '"A=1"'],
+      ['Environment', '"B=2"'],
+    ]);
+    expect(environmentLines({})).toEqual([]);
+  });
+});
+
+describe('newlines are refused, not encoded', () => {
+  test('a newline in a value is a typed error naming the key, never the value', () => {
+    expect(() => quoteEnvironmentValue('WEBHOOK_URL', 'https://x\nSECRET-TAIL')).toThrow(
+      QuadletEnvironmentValueError,
+    );
+    try {
+      quoteEnvironmentValue('WEBHOOK_URL', 'https://x\nSECRET-TAIL');
+    } catch (error) {
+      expect((error as QuadletEnvironmentValueError)._tag).toBe('QuadletEnvironmentValueError');
+      expect((error as QuadletEnvironmentValueError).key).toBe('WEBHOOK_URL');
+      const message = (error as QuadletEnvironmentValueError).message;
+      expect(message).toContain('WEBHOOK_URL');
+      expect(message).not.toContain('SECRET-TAIL');
+    }
+    expect(() => quoteEnvironmentValue('BAD\nKEY', 'value')).toThrow(QuadletEnvironmentValueError);
+  });
+
+  test('environmentValueProblems reports every refusal at once, as problem strings', () => {
+    expect(environmentValueProblems({ OK: 'fine', BAD: 'a\nb', WORSE: 'c\nd' })).toEqual([
+      expect.stringContaining('BAD'),
+      expect.stringContaining('WORSE'),
+    ]);
+    expect(environmentValueProblems({ OK: 'fine' })).toEqual([]);
+  });
+
+  test('containerProblems reports the refusal, never throwing past the plan', () => {
+    // The plan-time surface: a newline value must not abort `containerProblems` (a caller
+    // building a plan needs every refusal at once), and the string it gets back is the rule
+    // text — enough to locate the prop, never the value.
+    const problems = containerProblems({
+      name: 'grafana-primary',
+      container: { image: 'docker.io/library/alpine:3', environment: { BAD: 'a\nb' } },
+    });
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain('environment key "BAD" contains a newline');
+  });
+});
+
+describe('renderContainerFile wires the quoting in — the whole file', () => {
+  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('the Environment= block is quoted, still sorted, still after EnvironmentFile=', () => {
+    const lines = renderContainerFile(props).split('\n');
+    const envBlock = lines.filter((line) => line.startsWith('Environment='));
+    expect(envBlock).toEqual(
+      environmentLines(props.container.environment).map(([key, value]) => `${key}=${value}`),
+    );
+    expect(lines.indexOf(envBlock[0] ?? '')).toBeGreaterThan(
+      lines.indexOf('EnvironmentFile=/etc/grafana-primary/env'),
+    );
+  });
+});