@homeflare/alchemy 0.31.1 → 0.32.0

package/src/linux/container-secrets.test.ts

@@ -0,0 +1,171 @@
+/**
+ * The secret refusal the task asks to be proven, not merely implemented: no secret can appear in
+ * the RENDERED file or in Alchemy STATE. `secretLikeEnvironment` is the detector; this file also
+ * proves the whole path is wired — `containerProblems` calls it, and `reconcileContainer` refuses
+ * BEFORE any write, so a secret-shaped `Environment=` never reaches the fake filesystem (which is
+ * what a real deploy's `writeFileAtomic` and Alchemy's state row both stand in for here).
+ */
+import { describe, expect, test } from 'bun:test';
+import { podmanArgsProblems, secretLikeEnvironment, secretLikeLines } from './container-secrets.ts';
+import { type ContainerProps, containerProblems, renderContainerFile } from './container-form.ts';
+import { fakeQuadletHost } from './fake-quadlet.ts';
+import { reconcileContainer } from './container-lifecycle.ts';
+
+describe('secretLikeEnvironment', () => {
+  test('a key name that says what it holds is refused', () => {
+    const found = secretLikeEnvironment({
+      API_TOKEN: 'x',
+      DB_PASSWORD: 'y',
+      GRAFANA_SECRET_KEY: 'z',
+    });
+    expect(found).toHaveLength(3);
+    expect(found.join(' ')).toMatch(/looks like a secret by its name/);
+  });
+
+  test('an ordinary config key is left alone', () => {
+    expect(
+      secretLikeEnvironment({ CADDY_CONFIG: '/etc/caddy/Caddyfile', GF_SERVER_DOMAIN: 'x' }),
+    ).toEqual([]);
+  });
+
+  test('a value shaped like a real vendor token is refused even under an innocuous key name', () => {
+    const found = secretLikeEnvironment({ EXTRA_ARGS: 'ghp_abcdefghijklmnopqrstuvwxyz0123456789' });
+    expect(found.join(' ')).toMatch(/looks like a credential/);
+  });
+
+  test('a bearer/basic auth header value is refused', () => {
+    expect(secretLikeEnvironment({ HEADER: 'Bearer sometoken' })).toHaveLength(1);
+  });
+});
+
+describe('a secret-shaped Environment= is refused before anything touches the host', () => {
+  const NAME = 'hf-example';
+
+  const withSecret: ContainerProps = {
+    container: {
+      environment: { GF_SECURITY_ADMIN_PASSWORD: 'hunter2' },
+      image: 'grafana/grafana:12',
+    },
+    name: NAME,
+  };
+
+  test('containerProblems names the offending key', () => {
+    expect(containerProblems(withSecret).join(' ')).toMatch(/GF_SECURITY_ADMIN_PASSWORD/);
+  });
+
+  test('reconcile refuses and writes nothing — not the file, not a generated unit', async () => {
+    const fake = fakeQuadletHost();
+    await expect(reconcileContainer(fake.runner, withSecret, undefined)).rejects.toThrow(
+      /GF_SECURITY_ADMIN_PASSWORD/,
+    );
+    expect(fake.calls).toHaveLength(0);
+    expect(fake.files.has(`/etc/containers/systemd/${NAME}.container`)).toBe(false);
+  });
+
+  test('the renderer alone does not filter secrets — validation is the only backstop', () => {
+    // ★ `renderContainerFile` is a pure formatter; it does not know what a secret looks like.
+    //   `containerProblems`/`assertValid` do, and the previous test proves `reconcileContainer`
+    //   calls one before any write. This is why that ordering is load-bearing: called on its own,
+    //   the renderer WOULD put the secret in the file — there is no second, independent filter.
+    expect(renderContainerFile(withSecret)).toContain('hunter2');
+  });
+});
+
+// ⛔ FOUND ON ADVERSARIAL REVIEW: `container.environment` was the only field checked. `exec`,
+//   `podmanArgs` and the `unit.lines`/`service.lines` escape hatches all render into the same
+//   0644 file and the same state row, unchecked. These prove the fix closes every one of them.
+describe('secretLikeLines — every OTHER rendered field', () => {
+  test('a value shaped like a vendor token is refused, wherever it sits in the line', () => {
+    const found = secretLikeLines([
+      ['Exec', 'sh -c "curl -H \'X: ghp_abcdefghijklmnopqrstuvwxyz0123\'"'],
+    ]);
+    expect(found.join(' ')).toMatch(/looks like it carries a credential/);
+  });
+
+  test('an embedded KEY=VALUE whose key looks secret is refused even with no known token shape', () => {
+    const found = secretLikeLines([['PodmanArgs', 'GITHUB_TOKEN=some-opaque-value']]);
+    expect(found.join(' ')).toMatch(/embeds a KEY=VALUE pair whose key looks like a secret/);
+  });
+
+  test('a raw systemd Environment= line is caught even though it never touches the typed map', () => {
+    const found = secretLikeLines([['Environment', 'DB_PASSWORD=hunter2']]);
+    expect(found).toHaveLength(1);
+  });
+
+  test('an ordinary line is left alone', () => {
+    expect(
+      secretLikeLines([
+        ['Description', 'the shared postgres'],
+        ['WantedBy', 'multi-user.target'],
+      ]),
+    ).toEqual([]);
+  });
+});
+
+describe('podmanArgsProblems — an env flag is refused outright', () => {
+  test('-e and --env, split or `=`-joined or glued, are all caught', () => {
+    for (const args of [
+      ['-e', 'FOO=bar'],
+      ['--env', 'FOO=bar'],
+      ['--env=FOO=bar'],
+      ['-eFOO=bar'],
+    ]) {
+      expect(podmanArgsProblems(args).length).toBeGreaterThan(0);
+    }
+  });
+
+  test('an unrelated arg is left alone', () => {
+    expect(podmanArgsProblems(['--pull=never', '--cgroups=split'])).toEqual([]);
+  });
+});
+
+describe('containerProblems catches a secret smuggled through every free-text field', () => {
+  const base = { container: { image: 'grafana/grafana:12', network: 'host' }, name: 'hf-example' };
+
+  test('exec', () => {
+    const problems = containerProblems({
+      ...base,
+      container: { ...base.container, exec: 'sh -c "export API_TOKEN=hunter2 && run"' },
+    });
+    expect(problems.join(' ')).toMatch(/embeds a KEY=VALUE pair/);
+  });
+
+  test('podmanArgs — the outright -e/--env refusal fires before the shape check even runs', () => {
+    const problems = containerProblems({
+      ...base,
+      container: {
+        ...base.container,
+        podmanArgs: ['-e', 'GITHUB_TOKEN=ghp_abcdefghijklmnopqrstuvwxyz0123'],
+      },
+    });
+    expect(problems.join(' ')).toMatch(/sets a container environment variable outside/);
+  });
+
+  test('unit.lines', () => {
+    const problems = containerProblems({
+      ...base,
+      unit: { lines: [['X-Note', 'token: ghp_abcdefghijklmnopqrstuvwxyz0123']] },
+    });
+    expect(problems.join(' ')).toMatch(/looks like it carries a credential/);
+  });
+
+  test('service.lines — a raw systemd Environment=, bypassing the typed map entirely', () => {
+    const problems = containerProblems({
+      ...base,
+      service: { lines: [['Environment', 'CLIENT_SECRET=abc123']] },
+    });
+    expect(problems.join(' ')).toMatch(/embeds a KEY=VALUE pair/);
+  });
+
+  test('reconcile refuses a podmanArgs secret before anything touches the host', async () => {
+    const fake = fakeQuadletHost();
+    const withArgSecret: ContainerProps = {
+      ...base,
+      container: { ...base.container, podmanArgs: ['-e', 'DB_PASSWORD=hunter2'] },
+    };
+    await expect(reconcileContainer(fake.runner, withArgSecret, undefined)).rejects.toThrow(
+      /environment variable outside/,
+    );
+    expect(fake.calls).toHaveLength(0);
+  });
+});

package/src/linux/container-secrets.ts

@@ -0,0 +1,112 @@
+/**
+ * A best-effort refusal of an inline secret ANYWHERE in a rendered `.container` file — checked
+ * from `containerProblems` (container-form.ts), so it runs at plan AND apply time, before anything
+ * is written.
+ *
+ * ⛔ THIS IS NOT A SECRET SCANNER. It cannot prove a value is safe, only refuse the OBVIOUS cases: a
+ *   key whose name says what it holds, or a value shaped like a real vendor token. The actual
+ *   contract is `EnvironmentFile=` (container-form.ts's header): a secret belongs in a host file an
+ *   out-of-band renderer (openbao-agent) maintains, never in a prop, because the WHOLE file is
+ *   rendered into a 0644 file (`unit-form.ts` `UNIT_WRITE`) AND persisted unencrypted in Alchemy
+ *   state — the same two reasons `Systemd.Unit`'s `content` is never secret. A determined caller can
+ *   still name a variable `CFG` and put a token in it; this check is a guardrail against the common
+ *   mistake, not a boundary a hostile caller cannot cross.
+ * ★ KEY-NAME FIRST, VALUE SECOND. The name check catches the overwhelming majority of real
+ *   mistakes (copying a `docker run -e SECRET=...` line verbatim) and has no false-negative risk
+ *   from an unfamiliar token format; the value check is defense in depth for a handful of
+ *   widely-recognised vendor prefixes, not an attempt at general entropy detection — an entropy
+ *   check has enough false positives on ordinary config (long image digests, base64 Caddyfile
+ *   snippets) that it would train callers to ignore the refusal.
+ * ⛔ CHECKED EVERYWHERE, NOT ONLY `container.environment` — found on adversarial review.
+ *   `container.environment` is the field most likely to carry one BY ACCIDENT, and gets the
+ *   precise per-key `secretLikeEnvironment` check below with the best error message. But every
+ *   other free-text field renders into the SAME 0644 file and the SAME state row: `exec`,
+ *   `podmanArgs` (each entry rendered verbatim), and the escape-hatch `unit.lines`/`service.lines`
+ *   — a `service.lines` entry can spell a native systemd `Environment=` directly, which never goes
+ *   through the typed `container.environment` map at all. `secretLikeLines` below runs the same two
+ *   heuristics — value-shape, and an embedded `KEY=VALUE` whose KEY looks like a secret — over every
+ *   OTHER rendered line, and `container-form.ts`'s `containerProblems` calls both, so nothing
+ *   rendered escapes either check.
+ */
+
+/** Case-insensitive: matches the key APPEARING to name a credential, wherever it sits in the name. */
+const SECRET_KEY_NAME =
+  /(SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE_KEY|API_?KEY|CREDENTIAL|ACCESS_KEY|CLIENT_SECRET|AUTH_?KEY|DSN)/i;
+
+/**
+ * A handful of widely-recognised credential value shapes: Bearer/Basic auth headers, common vendor
+ * token prefixes (GitHub `ghp_`/`gho_`, GitLab `glpat-`, Slack `xoxb-`/`xoxp-`/…, AWS `AKIA`), and a
+ * JWT's `eyJ` base64url header. ⚠️ Not exhaustive — see file header.
+ */
+const SECRET_VALUE_PREFIX = /^(Bearer\s|Basic\s|sk-|ghp_|gho_|glpat-|xox[baprs]-|AKIA|eyJ)/;
+/** The same shapes, but matched ANYWHERE in a longer string — a `podmanArgs`/`exec` line is a whole
+ *  command or arg list, not a bare value, so the token can sit mid-string (`... --env=ghp_xxx`). */
+const SECRET_VALUE_ANYWHERE = new RegExp(SECRET_VALUE_PREFIX.source.replace(/^\^/, ''));
+
+/** A `KEY=VALUE`-shaped substring whose KEY looks like a secret name, wherever it sits in a line —
+ *  catches `-e GITHUB_TOKEN=ghp_xxx` or a raw `service.lines` `Environment=SECRET=xxx`. */
+const EMBEDDED_SECRET_ASSIGNMENT = new RegExp(
+  `[A-Za-z0-9_]*(?:${SECRET_KEY_NAME.source})[A-Za-z0-9_]*\\s*=\\s*\\S+`,
+  'i',
+);
+
+/** `-e`/`--env` (and their `=`-joined and glued forms) in `PodmanArgs=`: refused OUTRIGHT, not only
+ *  when the value looks secret — this resource already has a dedicated, secret-checked way to set a
+ *  container env var (`container.environment`/`container.environmentFile`), so a raw `PodmanArgs=`
+ *  env flag is always the wrong tool here, whatever it carries. */
+const ENV_FLAG = /^(?:-e|--env)(?:=|$|[A-Za-z_])/;
+
+export const secretLikeEnvironment = (environment: Readonly<Record<string, string>>): string[] => {
+  const found: string[] = [];
+  for (const [key, value] of Object.entries(environment)) {
+    if (SECRET_KEY_NAME.test(key)) {
+      found.push(
+        `environment key ${JSON.stringify(key)} looks like a secret by its name. Environment= is ` +
+          'rendered into a world-readable file and stored in Alchemy state; use environmentFile ' +
+          'instead, pointing at a host path a secret renderer maintains.',
+      );
+    } else if (SECRET_VALUE_PREFIX.test(value)) {
+      found.push(
+        `environment key ${JSON.stringify(key)}'s value looks like a credential. Environment= is ` +
+          'rendered into a world-readable file and stored in Alchemy state; use environmentFile ' +
+          'instead, pointing at a host path a secret renderer maintains.',
+      );
+    }
+  }
+  return found;
+};
+
+/** The same two heuristics as `secretLikeEnvironment`, over any OTHER rendered `[key, value]` line
+ *  (`Exec=`, `PodmanArgs=`, and the `unit.lines`/`service.lines` escape hatches) — see file header. */
+export const secretLikeLines = (
+  lines: readonly (readonly [key: string, value: string])[],
+): string[] => {
+  const found: string[] = [];
+  for (const [key, value] of lines) {
+    if (SECRET_VALUE_ANYWHERE.test(value)) {
+      found.push(
+        `${key}=${JSON.stringify(value)} looks like it carries a credential by its value. This ` +
+          'line is rendered into a world-readable file and stored in Alchemy state; use ' +
+          'container.environmentFile instead, pointing at a host path a secret renderer maintains.',
+      );
+    } else if (EMBEDDED_SECRET_ASSIGNMENT.test(value)) {
+      found.push(
+        `${key}=${JSON.stringify(value)} embeds a KEY=VALUE pair whose key looks like a secret ` +
+          'name. This line is rendered into a world-readable file and stored in Alchemy state; use ' +
+          'container.environment (checked for secrets) or container.environmentFile instead.',
+      );
+    }
+  }
+  return found;
+};
+
+/** `PodmanArgs=` entries that try to set a container env var outright — see `ENV_FLAG`'s comment. */
+export const podmanArgsProblems = (args: readonly string[]): string[] =>
+  args
+    .filter((arg) => ENV_FLAG.test(arg))
+    .map(
+      (arg) =>
+        `podmanArgs entry ${JSON.stringify(arg)} sets a container environment variable outside ` +
+        'the typed props, which this family never checks for a secret. Use container.environment ' +
+        '(checked) or container.environmentFile (for anything secret) instead.',
+    );

package/src/linux/container-settle.ts

@@ -0,0 +1,97 @@
+/**
+ * The step that decides whether the GENERATED `<name>.service` actually moves: running state and —
+ * only for a real change — a restart. Split out for the same reason unit-settle.ts is split from
+ * unit-lifecycle.ts: it is the restart contract, and it should be readable on its own.
+ *
+ * ⛔ THE RESTART CONDITION IS THE WHOLE CONTRACT, same as `Systemd.Unit`'s (unit-settle.ts):
+ *   `changed` comes from the caller (container-lifecycle.ts `reconcileContainer`), `configChanged`
+ *   is a digest the DECLARATION itself listed. Nothing else restarts a container.
+ * ★ NO ENABLE/DISABLE HERE — the one place this file is SHORTER than unit-settle.ts, not longer.
+ *   Quadlet's generator applies `[Install]` itself on every `daemon-reload` (container-generator.ts
+ *   header); calling `systemctl enable`/`disable` on a generated unit does not work at all (same
+ *   header, doc-cited). So there is no enablement branch to settle — only started/stopped and the
+ *   restart-on-change rule.
+ */
+import type { HostRunner } from '../launchd/runner.ts';
+import { isUnitRunning } from './unit-form.ts';
+import {
+  type UnitStatus,
+  daemonReload,
+  restartUnit,
+  showUnit,
+  startUnit,
+  stopUnit,
+} from './systemctl.ts';
+import {
+  type ContainerAttributes,
+  type ContainerProps,
+  refuseContainer,
+} from './container-form.ts';
+
+export const attributesOf = (
+  props: ContainerProps,
+  configSha256: string,
+  containerSha256: string,
+  containerPath: string,
+  serviceName: string,
+  status: UnitStatus,
+): ContainerAttributes => ({
+  active: status.activeState === 'active' || status.activeState === 'activating',
+  activeState: status.activeState,
+  configSha256,
+  containerPath,
+  containerSha256,
+  loadState: status.loadState,
+  name: props.name,
+  serviceName,
+  ...(status.unitFileState === undefined ? {} : { unitFileState: status.unitFileState }),
+  ...(status.sourcePath === undefined ? {} : { sourcePath: status.sourcePath }),
+});
+
+export type Settle = {
+  readonly before: Uint8Array | undefined;
+  /** The `.container` file or systemd's view of it changed in a way that earns a restart. */
+  readonly changed: boolean;
+  readonly configChanged: boolean;
+  readonly desired: string;
+  readonly path: string;
+  readonly serviceName: string;
+  readonly status: UnitStatus;
+};
+
+/**
+ * Bring running state to the declaration, restarting ONLY for a real change. No enable/disable —
+ * see file header.
+ */
+export const settle = async (
+  runner: HostRunner,
+  props: ContainerProps,
+  configSha256: string,
+  step: Settle,
+): Promise<ContainerAttributes> => {
+  const wantStarted = props.started !== false;
+  const running = isUnitRunning(step.status.activeState, step.status.subState, wantStarted);
+  const undo = async (detail: string): Promise<never> => {
+    // ⚠️ A create that never came up leaves nothing behind; an update keeps the new file — the
+    //   generator-verification step already ran (container-lifecycle.ts) by the time settle is
+    //   called, so the unit DOES exist here; only the start/restart itself failed.
+    if (step.before === undefined) {
+      await runner.removeFile(step.path).catch(() => undefined);
+      await daemonReload(runner).catch(() => undefined);
+    }
+    throw refuseContainer(props.name, `${detail} The container's unit is NOT running.`);
+  };
+  try {
+    if (!wantStarted) {
+      if (running) await stopUnit(runner, step.serviceName);
+    } else if (!running) await startUnit(runner, step.serviceName);
+    else if (step.changed || step.configChanged) await restartUnit(runner, step.serviceName);
+  } catch (cause) {
+    return undo(cause instanceof Error ? cause.message : String(cause));
+  }
+  const after = await showUnit(runner, step.serviceName);
+  if (wantStarted && !isUnitRunning(after.activeState, after.subState, wantStarted)) {
+    return undo(`systemctl reported success but the unit is ${after.activeState}.`);
+  }
+  return attributesOf(props, configSha256, step.desired, step.path, step.serviceName, after);
+};

package/src/linux/container.ts

@@ -0,0 +1,60 @@
+/**
+ * `Podman.Container` — one Quadlet `.container` file, declared, plus the systemd unit Podman's own
+ * generator turns it into.
+ *
+ * - create / update — render, write the `.container` file atomically, `daemon-reload`, VERIFY the
+ *   generator actually produced `<name>.service` (container-generator.ts), then start or RESTART
+ *   the generated unit only when something changed (container-lifecycle.ts, container-settle.ts).
+ * - read — the `.container` file's SHA-256 plus `systemctl show <name>.service`.
+ * - diff — the rendered digest against stored and on-disk, running state against the declaration,
+ *   and systemd's own `NeedDaemonReload`.
+ * - replace — only when the file's name or directory changes, delete-first.
+ * - delete — stop the generated unit, remove the `.container` file, reload.
+ *
+ * ⛔ A DEPLOY NEVER MASS-RESTARTS — see container-lifecycle.ts's header.
+ * ⛔ THE `.container` FILE IS NEVER A SECRET, and `[Container] Environment=` is refused if it looks
+ *   like one — see container-form.ts and container-secrets.ts.
+ * ⛔ THE GENERATED UNIT IS NEVER `systemctl enable`D — see container-generator.ts's header for why,
+ *   measured and doc-cited, and what stands in for it (`install.wantedBy`).
+ * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt` — same contract as every family here.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { HostRunnerService } from '../launchd/runner.ts';
+import type { ContainerAttributes, ContainerProps } from './container-form.ts';
+import { deleteHandler, diffHandler, readHandler, reconcileHandler } from './container-handlers.ts';
+
+export type {
+  ContainerAttributes as PodmanContainerAttributes,
+  ContainerProps as PodmanContainerProps,
+  ContainerSection,
+  UnitLine as PodmanUnitLine,
+} from './container-form.ts';
+
+export interface PodmanContainer extends Resource<
+  'Podman.Container',
+  ContainerProps,
+  ContainerAttributes
+> {}
+
+export const PodmanContainer = Resource<PodmanContainer>('Podman.Container');
+
+export const PodmanContainerProvider = () =>
+  Provider.effect(
+    PodmanContainer,
+    Effect.gen(function* () {
+      const runner = yield* HostRunnerService;
+      return PodmanContainer.Provider.of({
+        /**
+         * ⛔ Same rule as `Systemd.Unit`'s `list` (unit.ts): systemd's unit list is every vendor,
+         *   package and hand-written unit on the host, not what this stack owns.
+         */
+        list: () => Effect.succeed([]),
+        read: ({ olds, output }) => readHandler(runner, olds, output),
+        diff: ({ instanceId, news, output }) => diffHandler(runner, instanceId, news, output),
+        reconcile: (args) => reconcileHandler(runner, args),
+        delete: ({ output }) => deleteHandler(runner, output),
+      });
+    }),
+  );

package/src/linux/fake-quadlet.ts

@@ -0,0 +1,127 @@
+/**
+ * The Quadlet half of the fake Linux host, layered on top of `fake-linux-host.ts`: a `daemon-reload`
+ * that turns `.container` files into generated units the way `podman-system-generator` does, and a
+ * `systemctl enable`/`disable` that FAILS the way it does on a live host.
+ *
+ * ⛔ TEST-ONLY, and not on the barrel — same rule as `fake-linux-host.ts`.
+ * ★ WHAT IT MODELS, each cited in container-generator.ts's header: `daemon-reload` deletes and
+ *   regenerates ALL generator output, so a `.container` file the (fake) generator refuses has no
+ *   generated unit afterwards, even if one existed a moment ago; a generated unit carries
+ *   `SourcePath=` back to its `.container` file; `enable`/`disable` on a generated unit fails.
+ * ⚠️ WHAT IT DOES NOT MODEL: `UnitFileState` still reads `enabled`/`disabled` from the shared
+ *   `fake-systemd.ts`, not the real `generated`. Nothing in `container-lifecycle.ts` branches on
+ *   that field — only `LoadState`, `ActiveState`/`SubState` and `SourcePath` drive any decision —
+ *   so a fresh string there would cost a fork of `fake-systemd.ts` for no behaviour under test.
+ */
+import { sha256Hex } from '../launchd/job-form.ts';
+import { type FakeLinuxOptions, fakeLinuxHost } from './fake-linux-host.ts';
+import { GENERATED_UNIT_DIRECTORY } from './container-generator.ts';
+import { QUADLET_SEARCH_DIRECTORIES } from './container-form.ts';
+import type { ExecResult, HostRunner } from '../launchd/runner.ts';
+
+/** A line no real Quadlet key ever spells, so a test can force the (fake) generator to refuse a file. */
+export const FAIL_GENERATOR_MARKER = 'X-Test-Fail-Generator=1';
+
+const digest = (text: string) => sha256Hex(new TextEncoder().encode(text));
+const decode = (bytes: Uint8Array | undefined) =>
+  bytes === undefined ? undefined : new TextDecoder().decode(bytes);
+const fail = (exitCode: number, stderr: string): ExecResult => ({ exitCode, stderr, stdout: '' });
+
+export const fakeQuadletHost = (options: FakeLinuxOptions = {}) => {
+  const base = fakeLinuxHost({
+    dirs: { '/etc/systemd/system': 0, [QUADLET_SEARCH_DIRECTORIES[1]]: 0, ...options.dirs },
+    ...options,
+  });
+  /** service name -> the `.container` path the (fake) generator last produced it from. */
+  const sourcePaths = new Map<string, string>();
+
+  const isQuadletFile = (path: string) =>
+    path.endsWith('.container') &&
+    QUADLET_SEARCH_DIRECTORIES.some((dir) => path.startsWith(`${dir}/`));
+
+  const serviceFor = (containerPath: string) =>
+    `${containerPath.slice(containerPath.lastIndexOf('/') + 1).replace(/\.container$/, '')}.service`;
+
+  /**
+   * ★ MEASURED (systemd.generator(7)): reload wipes and reruns generators from what is on disk
+   *   now. So a stale generated file at `GENERATED_UNIT_DIRECTORY` is removed HERE for every
+   *   service this reload does not (re)confirm — otherwise `fake-systemd.ts`'s own "a file
+   *   appeared" sweep would find that stale file still sitting there and resurrect the unit from
+   *   it, which is exactly backwards: real `daemon-reload` deletes it first.
+   * ⚠️ REASONED, NOT MEASURED: what happens to an ALREADY-ACTIVE unit's `LoadState` when the file
+   *   that generated it is wiped and the replacement fails — see container-generator.ts's header.
+   *   This fake takes the CONSERVATIVE reading (the stale definition stops being `loaded`), which
+   *   is the safer direction to be wrong in for a test suite: it exercises the refusal path this
+   *   family relies on rather than silently passing a scenario a real host might handle more
+   *   leniently through unit garbage-collection.
+   */
+  const regenerate = () => {
+    const seen = new Set<string>();
+    for (const [path, entry] of base.files) {
+      if (!isQuadletFile(path)) continue;
+      const service = serviceFor(path);
+      seen.add(service);
+      const text = decode(entry.bytes) ?? '';
+      const generatedPath = `${GENERATED_UNIT_DIRECTORY}/${service}`;
+      const existing = base.units.get(service);
+      if (text.includes(FAIL_GENERATOR_MARKER)) {
+        sourcePaths.delete(service);
+        base.files.delete(generatedPath);
+        // ★ Wiped, not merely stale: a unit that is not currently active stops being known at all,
+        //   same rule `fake-systemd.ts`'s own sweep already applies when a unit file disappears.
+        if (existing === undefined) continue;
+        if (existing.active) existing.loadedSha = undefined;
+        else base.units.delete(service);
+        continue;
+      }
+      sourcePaths.set(service, path);
+      base.placeUnit(generatedPath, text, {
+        active: existing?.active ?? false,
+        enabled: false,
+        loadedSha: digest(text),
+        ...(existing?.activeState === undefined ? {} : { activeState: existing.activeState }),
+        ...(existing?.subState === undefined ? {} : { subState: existing.subState }),
+      });
+    }
+    // A generated unit whose `.container` file is gone stops being generated — remove the stale
+    // generated file (same reasoning as above) and, once it is not running, the unit itself.
+    for (const service of sourcePaths.keys()) {
+      if (seen.has(service)) continue;
+      sourcePaths.delete(service);
+      base.files.delete(`${GENERATED_UNIT_DIRECTORY}/${service}`);
+      const existing = base.units.get(service);
+      if (existing === undefined) continue;
+      if (existing.active) existing.loadedSha = undefined;
+      else base.units.delete(service);
+    }
+  };
+
+  const runner: HostRunner = {
+    ...base.runner,
+    exec: async (argv) => {
+      const verb = argv[1];
+      if (argv[0] === 'systemctl' && (verb === 'enable' || verb === 'disable')) {
+        // ⛔ MEASURED-DOC (podman-systemd.unit(5)): a generated unit is transient; enable/disable
+        //   fails. Logged via `base.calls` so a test can assert it was never even ATTEMPTED.
+        base.calls.push([...argv]);
+        return fail(
+          1,
+          `Failed to ${verb} unit: unit ${argv.at(-1)} is transient or was generated by a ` +
+            'generator, and cannot be enabled/disabled (podman-systemd.unit(5)).',
+        );
+      }
+      if (argv[0] === 'systemctl' && verb === 'daemon-reload') regenerate();
+      const result = await base.runner.exec(argv);
+      if (argv[0] === 'systemctl' && verb === 'show') {
+        const name = argv.at(-1) ?? '';
+        return {
+          ...result,
+          stdout: `${result.stdout}\nSourcePath=${sourcePaths.get(name) ?? ''}\n`,
+        };
+      }
+      return result;
+    },
+  };
+
+  return { ...base, runner };
+};

package/src/linux/index.ts

@@ -1,13 +1,13 @@
 /**
  * Linux host providers for Alchemy — a host's directories, its files (whole, or one managed block
- * inside somebody else's file) and its systemd units, over the SAME HostRunner seam the launchd
- * subpath drives a Mac through.
+ * inside somebody else's file), its systemd units and its Podman Quadlet containers, over the SAME
+ * HostRunner seam the launchd subpath drives a Mac through.
  *
  * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY. The lifecycle
  *   files, the systemctl parsers and the fake host are internals; an `export *` would publish them
  *   as API and make the next refactor a breaking change.
  * ⛔ A DEPLOY NEVER MASS-RESTARTS: a unit is restarted only when its own file changed, or a digest
- *   the declaration listed changed. See docs/linux-host.md.
+ *   the declaration listed changed. See docs/linux-host.md and docs/quadlet-container.md.
  * ★ THE SEAM IS SHARED, NOT COPIED. `HostRunner` is re-exported here so a Linux stack never has to
  *   import from the launchd subpath to type its own runner.
  */
@@ -32,3 +32,11 @@ export { HostRunnerService, canActAsRoot, hostRunnerLayer } from '../launchd/run
 export type { SystemdUnitAttributes, SystemdUnitProps, UnitSection } from './unit-form.ts';
 export { DEFAULT_UNIT_DIRECTORY, renderUnit } from './unit-form.ts';
 export { SystemdTimer, SystemdTimerProvider, SystemdUnit, SystemdUnitProvider } from './unit.ts';
+export type {
+  ContainerSection,
+  PodmanContainerAttributes,
+  PodmanContainerProps,
+  PodmanUnitLine,
+} from './container.ts';
+export { QUADLET_DEFAULT_DIRECTORY, QUADLET_SEARCH_DIRECTORIES } from './container-form.ts';
+export { PodmanContainer, PodmanContainerProvider } from './container.ts';

package/src/linux/providers.ts

@@ -13,6 +13,7 @@
  */
 import * as Layer from 'effect/Layer';
 import { type HostRunner, hostRunnerLayer } from '../launchd/runner.ts';
+import { PodmanContainerProvider } from './container.ts';
 import { HostDirectoryProvider } from './directory.ts';
 import { RemoteFileProvider } from './remote-file.ts';
 import { SystemdTimerProvider, SystemdUnitProvider } from './unit.ts';
@@ -20,6 +21,7 @@ import { SystemdTimerProvider, SystemdUnitProvider } from './unit.ts';
 export const linuxProviders = (runner: HostRunner) =>
   Layer.mergeAll(
     HostDirectoryProvider(),
+    PodmanContainerProvider(),
     RemoteFileProvider(),
     SystemdTimerProvider(),
     SystemdUnitProvider(),

package/src/linux/systemctl.ts

@@ -26,6 +26,10 @@
  *   the state is read back with `show` afterwards rather than assumed.
  * ⛔ NEVER PUT `show` STDOUT WITH NO PROPERTY FILTER IN AN ERROR: the unfiltered property set
  *   carries the unit's whole environment block.
+ * ★ `SourcePath` ADDED 2026-09-24 for `Podman.Container` (container-generator.ts): a systemd
+ *   GENERATOR's output unit carries the source file it was generated from — MEASURED on CT100,
+ *   `systemctl show caddy.service -p SourcePath` -> `/etc/containers/systemd/caddy.container`. An
+ *   ordinary hand-written unit's `SourcePath` is empty, so this is additive for `Systemd.Unit`.
  */
 import type { HostRunner } from '../launchd/runner.ts';
 
@@ -39,6 +43,7 @@ export const SHOW_PROPERTIES = [
   'SubState',
   'UnitFileState',
   'FragmentPath',
+  'SourcePath',
   'NeedDaemonReload',
 ] as const;
 
@@ -60,6 +65,8 @@ export type UnitStatus = {
   readonly unitFileState?: string;
   /** The unit file systemd would read. Empty when there is none. */
   readonly fragmentPath?: string;
+  /** A GENERATOR's source file, e.g. Quadlet's `.container` file. Empty for a hand-written unit. */
+  readonly sourcePath?: string;
   /** systemd's own view that its on-disk unit files are newer than what it has loaded. */
   readonly needDaemonReload: boolean;
 };
@@ -81,6 +88,7 @@ export const statusOf = (stdout: string): UnitStatus => {
   const loadState = fields.get('LoadState') ?? 'not-found';
   const unitFileState = fields.get('UnitFileState') ?? '';
   const fragmentPath = fields.get('FragmentPath') ?? '';
+  const sourcePath = fields.get('SourcePath') ?? '';
   const subState = fields.get('SubState') ?? '';
   return {
     activeState: fields.get('ActiveState') ?? 'inactive',
@@ -92,6 +100,7 @@ export const statusOf = (stdout: string): UnitStatus => {
     ...(subState === '' ? {} : { subState }),
     ...(unitFileState === '' ? {} : { unitFileState }),
     ...(fragmentPath === '' ? {} : { fragmentPath }),
+    ...(sourcePath === '' ? {} : { sourcePath }),
   };
 };