@homeflare/alchemy 0.31.1 → 0.32.0

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

@@ -0,0 +1,92 @@
+/**
+ * Renders the SAME directives as CT100's live `caddy.container`
+ * (`/etc/containers/systemd/caddy.container`, read read-only over `ssh ct100` 2026-09-24) and checks
+ * every line against that fixture.
+ *
+ * ⚠️ NOT BYTE-FOR-BYTE, AND HERE IS EXACTLY WHY NOT. `renderContainerFile` renders a TYPED
+ *   `ContainerProps` — the whole point of this family (container-form.ts's header) — and CT100's
+ *   file interleaves long prose comments BETWEEN directives inside `[Unit]` and `[Container]`
+ *   (why host networking, the OpenBao-unreachable note, the rate-limit warning). There is nowhere
+ *   in a typed prop to attach "this comment goes between EnvironmentFile= and Environment=": the
+ *   comments are the file's OWN authored documentation, not data this resource's props carry.
+ *   `Systemd.Unit` has the identical limit for the same reason — `unit-form.ts`'s `renderUnit`
+ *   is lines-in-order with no comment slots either. So this fixture proves DIRECTIVE parity
+ *   (every key, in a stable order, with CT100's exact values) rather than text-diff parity; the
+ *   `[Unit]`/`[Service]`/`[Install]` VALUES below are copied verbatim from CT100's file, and the
+ *   `[Container]` ones from CT100's `[X-Container]` section (Quadlet 5.x renders that heading;
+ *   this family emits the pre-5.x `[Container]` spelling, both documented (podman-systemd.unit(5))).
+ */
+import { expect, test } from 'bun:test';
+import { type ContainerProps, renderContainerFile } from './container-form.ts';
+
+// ★ Copied verbatim from CT100's /etc/containers/systemd/caddy.container, 2026-09-24.
+const caddy: ContainerProps = {
+  container: {
+    containerName: 'caddy',
+    environment: { CADDY_CONFIG: '/etc/caddy/Caddyfile' },
+    environmentFile: ['/etc/caddy/cf-token.env'],
+    image: 'localhost/homeflare/caddy:2.11.4-hf1',
+    network: 'host',
+    volume: [
+      '/etc/caddy/Caddyfile:/etc/caddy/Caddyfile:ro,Z',
+      '/etc/caddy/rendered:/etc/caddy/rendered:ro,Z',
+      '/etc/caddy/cf-token.env:/run/cf/token.env:ro',
+      'caddy-data:/data',
+      'caddy-config:/config',
+    ],
+  },
+  install: { wantedBy: ['multi-user.target'] },
+  name: 'caddy',
+  service: { restart: 'always', restartSec: '5s' },
+  unit: {
+    description: 'HomeFlare TLS front door (Caddy, DNS-01)',
+    documentation:
+      'https://gitlab.homeflare.dev/homeflare/homeflare-config/-/tree/main/hosts/ct100/caddy',
+    lines: [
+      ['After', 'network-online.target'],
+      ['Wants', 'network-online.target'],
+      ['After', 'caddy-cf-token.service'],
+      ['Wants', 'caddy-cf-token.service'],
+    ],
+  },
+};
+
+test('renders every directive CT100’s live caddy.container carries', () => {
+  const rendered = renderContainerFile(caddy);
+  const expected = [
+    '[Unit]',
+    'Description=HomeFlare TLS front door (Caddy, DNS-01)',
+    'Documentation=https://gitlab.homeflare.dev/homeflare/homeflare-config/-/tree/main/hosts/ct100/caddy',
+    'After=network-online.target',
+    'Wants=network-online.target',
+    'After=caddy-cf-token.service',
+    'Wants=caddy-cf-token.service',
+    '[Container]',
+    'Image=localhost/homeflare/caddy:2.11.4-hf1',
+    'ContainerName=caddy',
+    'Network=host',
+    'EnvironmentFile=/etc/caddy/cf-token.env',
+    'Environment=CADDY_CONFIG=/etc/caddy/Caddyfile',
+    'Volume=/etc/caddy/Caddyfile:/etc/caddy/Caddyfile:ro,Z',
+    'Volume=/etc/caddy/rendered:/etc/caddy/rendered:ro,Z',
+    'Volume=/etc/caddy/cf-token.env:/run/cf/token.env:ro',
+    'Volume=caddy-data:/data',
+    'Volume=caddy-config:/config',
+    '[Service]',
+    'Restart=always',
+    'RestartSec=5s',
+    '[Install]',
+    'WantedBy=multi-user.target',
+  ];
+  for (const line of expected) expect(rendered).toContain(line);
+  // Every non-blank, non-header line in our render is one of the expected lines — nothing invented.
+  const ours = rendered.split('\n').filter((line) => line !== '' && !line.startsWith('['));
+  expect(ours.sort()).toEqual(expected.filter((line) => !line.startsWith('[')).sort());
+});
+
+test('no comment lines — the one documented gap, not an accident', () => {
+  // Quadlet accepts `#`/`;` comments in a .container file; renderUnit (unit-form.ts) never emits
+  // one, in this family or Systemd.Unit's. CT100's own comments live only in the file this
+  // resource would MANAGE, never in state — restating them is a future prop, not a bug here.
+  expect(renderContainerFile(caddy)).not.toMatch(/^\s*[#;]/m);
+});

package/src/linux/container-form.ts

@@ -0,0 +1,243 @@
+/**
+ * `Podman.Container` props, attributes and the `.container` file renderer — the pure half of the
+ * family, mirroring unit-form.ts's split for Systemd.Unit.
+ *
+ * ★ WHY THE `[Container]` SECTION IS TYPED, UNLIKE `Systemd.Unit`'s SECTIONS. unit-form.ts renders
+ *   `[Unit]`/`[Service]`/`[Install]` verbatim because there is no machine-readable schema of
+ *   `systemd.unit(5)` to check a key against. Quadlet's `[Container]` section is different: it is
+ *   ONE vendor's documented, versioned surface — `podman-systemd.unit(5)`, Podman 5.4 (checked
+ *   against `containers/podman` tag `v5.4.0`,
+ *   `docs/source/markdown/podman-systemd.unit.5.md`, read 2026-09-24) — so every key below is
+ *   checked against that page, not invented. `[Unit]`/`[Service]`/`[Install]` stay close to
+ *   unit-form.ts's own verbatim-lines approach, because THOSE three sections are still systemd's
+ *   own directive set, which Quadlet passes straight through (same doc, "All options and tables
+ *   available in standard systemd unit files are supported").
+ * ⛔ `[Container] Environment=` IS NEVER A SECRET — enforced in container-secrets.ts, called from
+ *   `containerProblems` below. A container that needs a secret takes `EnvironmentFile=` pointing at
+ *   a host path an out-of-band secret renderer (openbao-agent) maintains; this family never reads
+ *   or renders that file's contents.
+ * ⛔ `[Install]` SUPPORTS ONLY `Alias=`/`WantedBy=`/`RequiredBy=` FOR A `.container` FILE (same doc,
+ *   "Currently, only the Alias, WantedBy and RequiredBy keys are supported") — NOT `Also=`, which
+ *   plain `systemd.unit(5)` allows and unit-form.ts's `INSTALL_KEYS` therefore lists. See
+ *   container-generator.ts's header for why there is no `enabled` prop at all.
+ */
+import { type UnitSection, configDigest, digestOf, renderUnit } from './unit-form.ts';
+import { podmanArgsProblems, secretLikeEnvironment, secretLikeLines } from './container-secrets.ts';
+
+/** ★ Reused, not redefined: same digest and `restartOn`-join contract as Systemd.Unit. */
+export { configDigest, digestOf };
+
+export type UnitLine = readonly [key: string, value: string];
+
+/**
+ * The `[Container]` keys this family supports — a deliberate SUBSET of the ~80 keys
+ * `podman-systemd.unit(5)` documents (task scope: `Image`, `ContainerName`, `Network`, `Volume`,
+ * `EnvironmentFile`, `Environment`, `PublishPort`, `Exec`, `User`, `AutoUpdate`, `PodmanArgs`).
+ * Adding another key means adding a field here and checking it against the same doc — never a
+ * free-text escape hatch, or `Environment=` secret-checking (below) could be bypassed through it.
+ */
+export type ContainerSection = {
+  /** `Image=`. Required. "recommended to use a fully qualified image name" (doc). */
+  readonly image: string;
+  /** `ContainerName=`. @default quadlet's own `systemd-<name>` (doc) when omitted. */
+  readonly containerName?: string;
+  /** `Network=`. MUST support `'host'` — every container this rollout declares runs host netns. */
+  readonly network?: string;
+  /** `Volume=`, repeatable. */
+  readonly volume?: readonly string[];
+  /** `EnvironmentFile=`, repeatable. The ONLY way a secret reaches the container — see file header. */
+  readonly environmentFile?: readonly string[];
+  /** `Environment=`, repeatable `KEY=VALUE`. NEVER a secret — see container-secrets.ts. */
+  readonly environment?: Readonly<Record<string, string>>;
+  /** `PublishPort=`, repeatable. Refused together with `network: 'host'` — see `containerProblems`. */
+  readonly publishPort?: readonly string[];
+  /** `Exec=`. Appended after the image's entrypoint, "the same way as ... a Kubernetes pod" (doc). */
+  readonly exec?: string;
+  /** `User=`. The numeric UID inside the container (doc: "does not need to match the UID on the host"). */
+  readonly user?: string;
+  /** `AutoUpdate=`. Podman's own two values (doc): `'registry'` or `'local'`. */
+  readonly autoUpdate?: 'registry' | 'local';
+  /** `PodmanArgs=`, repeatable. Doc: "not recommended" — the generator does not understand it. */
+  readonly podmanArgs?: readonly string[];
+};
+
+export type ContainerProps = {
+  /** The Quadlet file's basename, WITHOUT `.container`. Written as `<name>.container`. */
+  name: string;
+  /** @default QUADLET_DEFAULT_DIRECTORY. Must be one of QUADLET_SEARCH_DIRECTORIES (below). */
+  directory?: string;
+  /** `[Unit]` — `Description=`/`Documentation=` typed, everything else verbatim (see file header). */
+  unit?: { description?: string; documentation?: string; lines?: readonly UnitLine[] };
+  /** `[Container]` — Quadlet's own, typed and doc-checked. */
+  container: ContainerSection;
+  /** `[Service]` — `Restart=`/`RestartSec=` typed, everything else verbatim. */
+  service?: { restart?: string; restartSec?: string; lines?: readonly UnitLine[] };
+  /** `[Install]` — the three keys Quadlet honours for a `.container` file (see file header). */
+  install?: {
+    wantedBy?: readonly string[];
+    requiredBy?: readonly string[];
+    alias?: readonly string[];
+  };
+  /** `systemctl start`/`stop` the GENERATED `<name>.service`. @default true. No `enabled` prop —
+   *  see container-generator.ts's header for why boot-time enablement is not a systemctl call here. */
+  started?: boolean;
+  /** Same contract as Systemd.Unit's `restartOn`: digests of things read outside the `.container` file. */
+  restartOn?: readonly string[];
+};
+
+export type ContainerAttributes = {
+  name: string;
+  /** The GENERATED unit's name: `<name>.service`. Never `.container` — systemctl never sees that. */
+  serviceName: string;
+  containerPath: string;
+  /** SHA-256 of the `.container` file this resource wrote. */
+  containerSha256: string;
+  configSha256: string;
+  loadState: string;
+  activeState: string;
+  unitFileState?: string;
+  /** `systemctl show`'s `SourcePath=` on the generated unit — measured on CT100 2026-09-24 to be
+   *  the `.container` file's own path; used to prove the generated unit is really ours. */
+  sourcePath?: string;
+  active: boolean;
+};
+
+/**
+ * Podman's OWN rootful search path, most specific first — `podman-systemd.unit(5)`, "Podman Unit
+ * Search Path", Podman 5.4, read 2026-09-24: "Quadlet files for the root user can be placed in the
+ * following directories ordered in precedence" (`/run` over `/etc` over `/usr/share`).
+ * ★ CT100's `caddy.container` lives in the middle one — measured live, `cat` over `ssh ct100`,
+ *   2026-09-24: `/etc/containers/systemd/caddy.container`.
+ * ⛔ A directory outside this list is invisible to Quadlet: the generator only reads these three, so
+ *   a file elsewhere is a `.container` file with no `.service` ever generated from it — silently,
+ *   unlike `Systemd.Unit`'s directory check, which at least writes a unit systemd could load if only
+ *   it were enabled. See `containerProblems`.
+ */
+export const QUADLET_SEARCH_DIRECTORIES = [
+  '/run/containers/systemd',
+  '/etc/containers/systemd',
+  '/usr/share/containers/systemd',
+] as const;
+
+export const QUADLET_DEFAULT_DIRECTORY = '/etc/containers/systemd';
+
+/** ★ A conservative subset of what Quadlet itself accepts as a unit name: no template `@`, no `/`. */
+export const NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+
+export const containerPathFor = (props: Pick<ContainerProps, 'name' | 'directory'>): string =>
+  `${props.directory ?? QUADLET_DEFAULT_DIRECTORY}/${props.name}.container`;
+
+/** The unit Quadlet generates FROM the `.container` file — systemctl only ever sees this name. */
+export const serviceNameFor = (props: Pick<ContainerProps, 'name'>): string =>
+  `${props.name}.service`;
+
+const unitLines = (props: ContainerProps): UnitLine[] => [
+  ...(props.unit?.description === undefined
+    ? []
+    : [['Description', props.unit.description] as UnitLine]),
+  ...(props.unit?.documentation === undefined
+    ? []
+    : [['Documentation', props.unit.documentation] as UnitLine]),
+  ...(props.unit?.lines ?? []),
+];
+
+const containerLines = (c: ContainerSection): UnitLine[] => [
+  ['Image', c.image],
+  ...(c.containerName === undefined ? [] : [['ContainerName', c.containerName] as UnitLine]),
+  ...(c.network === undefined ? [] : [['Network', c.network] as UnitLine]),
+  ...(c.user === undefined ? [] : [['User', c.user] as UnitLine]),
+  ...(c.exec === undefined ? [] : [['Exec', c.exec] as UnitLine]),
+  ...(c.autoUpdate === undefined ? [] : [['AutoUpdate', c.autoUpdate] as UnitLine]),
+  ...(c.environmentFile ?? []).map((file): UnitLine => ['EnvironmentFile', file]),
+  // ★ Sorted by key: a stable render for a plain object whose own key order JS does not promise.
+  ...Object.keys(c.environment ?? {})
+    .sort()
+    .map((key): UnitLine => [
+      'Environment',
+      `${key}=${(c.environment as Record<string, string>)[key]}`,
+    ]),
+  ...(c.volume ?? []).map((volume): UnitLine => ['Volume', volume]),
+  ...(c.publishPort ?? []).map((port): UnitLine => ['PublishPort', port]),
+  ...(c.podmanArgs ?? []).map((arg): UnitLine => ['PodmanArgs', arg]),
+];
+
+const serviceLines = (props: ContainerProps): UnitLine[] => [
+  ...(props.service?.restart === undefined ? [] : [['Restart', props.service.restart] as UnitLine]),
+  ...(props.service?.restartSec === undefined
+    ? []
+    : [['RestartSec', props.service.restartSec] as UnitLine]),
+  ...(props.service?.lines ?? []),
+];
+
+const installLines = (props: ContainerProps): UnitLine[] => [
+  ...(props.install?.wantedBy ?? []).map((target): UnitLine => ['WantedBy', target]),
+  ...(props.install?.requiredBy ?? []).map((target): UnitLine => ['RequiredBy', target]),
+  ...(props.install?.alias ?? []).map((name): UnitLine => ['Alias', name]),
+];
+
+/** The whole `.container` file. ★ Reuses unit-form.ts's `renderUnit` — same `[Section]` INI shape. */
+export const renderContainerFile = (props: ContainerProps): string => {
+  const sections: UnitSection[] = [
+    { name: 'Unit', lines: unitLines(props) },
+    { name: 'Container', lines: containerLines(props.container) },
+    { name: 'Service', lines: serviceLines(props) },
+    { name: 'Install', lines: installLines(props) },
+  ];
+  return renderUnit(sections.filter((section) => section.lines.length > 0));
+};
+
+export const refuseContainer = (name: string, message: string): Error =>
+  new Error(`Podman.Container ${name}: ${message}`);
+
+/** Every refusal at once, so one plan shows the whole list — mirrors `unitProblems`'s shape. */
+export const containerProblems = (props: ContainerProps): string[] => {
+  const found: string[] = [];
+  if (!NAME.test(props.name)) {
+    found.push(
+      `name must match ${String(NAME)}, with no '.container' suffix; got ${JSON.stringify(props.name)}`,
+    );
+  }
+  const directory = props.directory ?? QUADLET_DEFAULT_DIRECTORY;
+  if (!directory.startsWith('/') || directory.endsWith('/') || directory.includes('/..')) {
+    found.push('directory must be an absolute, normalised path with no trailing slash');
+  } else if (
+    !QUADLET_SEARCH_DIRECTORIES.includes(directory as (typeof QUADLET_SEARCH_DIRECTORIES)[number])
+  ) {
+    found.push(
+      `directory must be one of Quadlet's own rootful search path (${QUADLET_SEARCH_DIRECTORIES.join(', ')}); ` +
+        `${directory} is never read by the generator (podman-systemd.unit(5), Podman 5.4).`,
+    );
+  }
+  if (props.container.image.trim() === '') found.push('container.image is required');
+  if (props.container.network === 'host' && (props.container.publishPort?.length ?? 0) > 0) {
+    found.push(
+      "container.publishPort has no effect with container.network 'host': the container already " +
+        'binds the host’s ports directly. Drop publishPort, or use a different network.',
+    );
+  }
+  found.push(
+    ...secretLikeEnvironment(props.container.environment ?? {}).map(
+      (problem) => `container.${problem}`,
+    ),
+  );
+  found.push(
+    ...podmanArgsProblems(props.container.podmanArgs ?? []).map(
+      (problem) => `container.${problem}`,
+    ),
+  );
+  // ★ Every OTHER rendered line — `Exec=`/`PodmanArgs=` and the `unit`/`service`/`install` escape
+  //   hatches — checked too, so a secret cannot reach the file through a field this typed check does
+  //   not otherwise inspect. `container.environment`'s OWN lines are excluded: `secretLikeEnvironment`
+  //   above already checked them, with a better error message (the actual env var name).
+  found.push(
+    ...secretLikeLines([
+      ...unitLines(props),
+      ...containerLines(props.container).filter(([key]) => key !== 'Environment'),
+      ...serviceLines(props),
+      ...installLines(props),
+    ]),
+  );
+  if (renderContainerFile(props).includes('\u0000'))
+    found.push('the rendered .container file contains NUL');
+  return found;
+};

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

@@ -0,0 +1,195 @@
+/**
+ * The two things container-generator.ts's header stakes the whole design on:
+ *
+ * 1. A generator failure never reads as "the resource is absent" — it is a typed, loud
+ *    `QuadletGeneratorError`, and an UPDATE that fails restores the last-known-good `.container`
+ *    file and reloads again, so a container that was already running never loses its systemd unit.
+ * 2. `enable`/`disable` is never even ATTEMPTED on the generated unit — the fake fails the call
+ *    (fake-quadlet.ts), so a regression that reintroduced one would fail loudly here, not silently
+ *    no-op the way a plain assertion-of-absence would.
+ */
+import { describe, expect, test } from 'bun:test';
+import { FAIL_GENERATOR_MARKER, fakeQuadletHost } from './fake-quadlet.ts';
+import { type ContainerProps, digestOf, renderContainerFile } from './container-form.ts';
+import { deleteContainer, reconcileContainer } from './container-lifecycle.ts';
+import { QuadletGeneratorError, verifyGenerated } from './container-generator.ts';
+
+const NAME = 'hf-example';
+const PATH = `/etc/containers/systemd/${NAME}.container`;
+const SERVICE = `${NAME}.service`;
+
+const props = (image: string): ContainerProps => ({
+  container: { image, network: 'host' },
+  install: { wantedBy: ['multi-user.target'] },
+  name: NAME,
+});
+
+const broken: ContainerProps = {
+  ...props('example/one:1'),
+  service: { lines: [['X-Test-Fail-Generator', '1']] },
+};
+
+const verbs = (calls: string[][]) =>
+  calls.filter((call) => call[0] === 'systemctl').map((call) => call[1]);
+
+test('the fixture marker really does render into the file', () => {
+  expect(renderContainerFile(broken)).toContain(FAIL_GENERATOR_MARKER);
+});
+
+describe('a generator failure is a typed, loud error', () => {
+  test('a CREATE the generator refuses removes the file it wrote and reloads clean', async () => {
+    const fake = fakeQuadletHost();
+    await expect(reconcileContainer(fake.runner, broken, undefined)).rejects.toThrow(
+      QuadletGeneratorError,
+    );
+    expect(fake.files.has(PATH)).toBe(false);
+    expect(verbs(fake.calls)).toEqual(['show', 'daemon-reload', 'show', 'daemon-reload']);
+  });
+
+  test('an UPDATE the generator refuses restores the last-known-good file, not the broken one', async () => {
+    const fake = fakeQuadletHost();
+    const good = await reconcileContainer(fake.runner, props('example/one:1'), undefined);
+    const goodBytes = fake.files.get(PATH)?.bytes;
+    const before = fake.calls.length;
+    await expect(reconcileContainer(fake.runner, broken, good)).rejects.toThrow(
+      QuadletGeneratorError,
+    );
+    // ★ THE FILE ON DISK IS THE OLD, WORKING ONE — not the broken update.
+    expect(fake.files.get(PATH)?.bytes).toEqual(goodBytes);
+    // ★ AND THE GENERATED UNIT EXISTS AGAIN, still the container that was already running.
+    expect(fake.units.get(SERVICE)?.active).toBe(true);
+    expect(verbs(fake.calls.slice(before))).toEqual([
+      'show',
+      'daemon-reload',
+      'show',
+      'daemon-reload',
+    ]);
+  });
+
+  test('a file already on disk that the generator refuses is not "rolled back" onto itself', async () => {
+    // ⚠️ wrote === false: nothing NEW to restore to (container-lifecycle.ts's header explains why).
+    //   A reload IS still attempted — needsVerificationReload (container-generator.ts) rightly
+    //   tries once before giving up, since nothing has proven this content ever generated at all —
+    //   but it finds the same failure, so still no write and still no rollback.
+    const fake = fakeQuadletHost();
+    fake.files.set(PATH, {
+      bytes: new TextEncoder().encode(renderContainerFile(broken)),
+      gid: 0,
+      kind: 'file',
+      mode: 0o644,
+      uid: 0,
+    });
+    await expect(reconcileContainer(fake.runner, broken, undefined, true)).rejects.toThrow(
+      QuadletGeneratorError,
+    );
+    expect(verbs(fake.calls)).toEqual(['show', 'daemon-reload', 'show']);
+    expect(fake.calls.some((call) => call[0] === 'write')).toBe(false);
+  });
+});
+
+describe('enable/disable is never attempted on a generated unit', () => {
+  test('create, update and delete never call enable or disable', async () => {
+    const fake = fakeQuadletHost();
+    const first = await reconcileContainer(fake.runner, props('example/one:1'), undefined);
+    const second = await reconcileContainer(fake.runner, props('example/two:2'), first);
+    await deleteContainer(fake.runner, second);
+    expect(verbs(fake.calls)).not.toContain('enable');
+    expect(verbs(fake.calls)).not.toContain('disable');
+  });
+
+  test('the fake itself refuses enable, proving the guard is real and not just unexercised', async () => {
+    const fake = fakeQuadletHost();
+    const result = await fake.runner.exec(['systemctl', 'enable', '--', SERVICE]);
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stderr).toMatch(/transient or was generated/);
+  });
+});
+
+describe('an interrupted apply that crashed before daemon-reload', () => {
+  test('the retry still reloads and restarts onto the NEW definition, not the stale one', async () => {
+    const fake = fakeQuadletHost();
+    const oldProps = props('example/old:1');
+    const newProps = props('example/new:2');
+    const oldOutput = await reconcileContainer(fake.runner, oldProps, undefined);
+    // ★ Simulate apply 1: its write landed, but it crashed before `daemon-reload` ran, so the
+    //   generated unit is still the OLD one, and Alchemy's state is still `oldOutput` — a reconcile
+    //   that never returns never gets its attributes persisted.
+    fake.files.set(PATH, {
+      bytes: new TextEncoder().encode(renderContainerFile(newProps)),
+      gid: 0,
+      kind: 'file',
+      mode: 0o644,
+      uid: 0,
+    });
+    const before = fake.calls.length;
+    const retried = await reconcileContainer(fake.runner, newProps, oldOutput);
+    const after = verbs(fake.calls.slice(before));
+    // ⛔ THE BUG THIS PROVES FIXED: without the `stale` check, `wrote` is false (the file already
+    //   holds the new content) and systemd's own `NeedDaemonReload` is also false (the GENERATED
+    //   unit hasn't changed yet), so nothing would ever reload — the container would restart, if at
+    //   all, onto its OLD definition while state silently claimed the new one had taken effect.
+    expect(after).toContain('daemon-reload');
+    expect(after).toContain('restart');
+    const newDigest = digestOf(renderContainerFile(newProps));
+    expect(retried.containerSha256).toBe(newDigest);
+    // ★ Not just a claim in state: the fake's OWN generated-unit record is built from the NEW file.
+    expect(fake.units.get(SERVICE)?.loadedSha).toBe(newDigest);
+  });
+});
+
+describe('an interrupted CREATE that crashed before daemon-reload', () => {
+  test('the retry still reloads, verifies and starts — rather than getting stuck forever', async () => {
+    const fake = fakeQuadletHost();
+    const newProps = props('example/new:1');
+    // ★ Simulate apply 1: its write landed (the file is on disk with the desired content already),
+    //   but it crashed before `daemon-reload` ran — no generated unit exists yet, and a create that
+    //   never returns never gets a state row at all, so this retry starts from `output: undefined`,
+    //   the same as Alchemy's own "Cannot resume creating … Re-run with --adopt" (`adopt: true`).
+    fake.files.set(PATH, {
+      bytes: new TextEncoder().encode(renderContainerFile(newProps)),
+      gid: 0,
+      kind: 'file',
+      mode: 0o644,
+      uid: 0,
+    });
+    const before = fake.calls.length;
+    const retried = await reconcileContainer(fake.runner, newProps, undefined, true);
+    const after = verbs(fake.calls.slice(before));
+    // ⛔ THE BUG THIS PROVES FIXED: without `needsVerificationReload`, `wrote` is false (the file
+    //   already holds the new content) and there is no PRIOR state for `stale` to disagree with —
+    //   so nothing would ever reload, and `verifyGenerated` would throw on the still-missing
+    //   generated unit on every retry, FOREVER: loud, but stuck, since nothing a plain retry does
+    //   ever changes any of those three signals.
+    expect(after).toContain('daemon-reload');
+    expect(after).toContain('start');
+    const newDigest = digestOf(renderContainerFile(newProps));
+    expect(retried.containerSha256).toBe(newDigest);
+    expect(fake.units.get(SERVICE)?.loadedSha).toBe(newDigest);
+    expect(fake.units.get(SERVICE)?.active).toBe(true);
+  });
+});
+
+describe('verifyGenerated, directly', () => {
+  test('a missing generated unit is a QuadletGeneratorError naming the debug commands', () => {
+    expect(() =>
+      verifyGenerated(NAME, PATH, SERVICE, {
+        activeState: 'inactive',
+        known: false,
+        loadState: 'not-found',
+        needDaemonReload: false,
+      }),
+    ).toThrow(/podman-system-generator --dryrun/);
+  });
+
+  test('a SourcePath belonging to another file is a takeover, not a success', () => {
+    expect(() =>
+      verifyGenerated(NAME, PATH, SERVICE, {
+        activeState: 'active',
+        known: true,
+        loadState: 'loaded',
+        needDaemonReload: false,
+        sourcePath: '/usr/share/containers/systemd/hf-example.container',
+      }),
+    ).toThrow(/earlier in Quadlet/);
+  });
+});

package/src/linux/container-generator.ts

@@ -0,0 +1,113 @@
+/**
+ * Quadlet is a systemd GENERATOR (`systemd.generator(7)`, tag `v257`, `man/systemd.generator.xml`,
+ * read 2026-09-24), not a unit reader — this is the one fact the whole lifecycle is built around.
+ *
+ * ★ "Generator output is supposed to last only until the next `daemon-reload`... Units written by
+ *   generators are removed when the configuration is reloaded" (same doc). `daemon-reload` DELETES
+ *   `/run/systemd/generator` wholesale and reruns every generator from the `.container` files
+ *   currently on disk. So a `.container` file the generator refuses produces NO generated unit —
+ *   even one that generated fine a moment ago, if `daemon-reload` runs again over a now-broken file.
+ *   That is why `container-lifecycle.ts` restores the LAST-KNOWN-GOOD file and reloads again on a
+ *   failed update, rather than leaving the bad file in place the way `Systemd.Unit` leaves a bad
+ *   update for the next deploy to retry (unit-lifecycle.ts): here, "the next deploy" might be a
+ *   reboot, and by then the container this resource already promised running has no systemd unit
+ *   at all, not merely a stale one.
+ * ⛔ THE GENERATED UNIT CANNOT BE `systemctl enable`D — `podman-systemd.unit(5)`, Podman 5.4, "Podman
+ *   unit files": "The services created by Podman are considered transient by systemd... it is not
+ *   possible to 'systemctl enable' them... To compensate... the generator manually applies the
+ *   [Install] section... during generation, in the same way `systemctl enable` does when run
+ *   later." MEASURED on CT100 2026-09-24 (`ssh ct100`, read-only): `caddy.container` declares
+ *   `[Install] WantedBy=multi-user.target` and nothing ever ran `systemctl enable caddy`; yet
+ *   `systemctl is-enabled caddy.service` prints `generated`, `UnitFileState=generated`, and
+ *   `/run/systemd/generator/multi-user.target.wants/caddy.service` is a symlink the GENERATOR put
+ *   there. So `Podman.Container` has no `enabled` prop and never calls `enableUnit`/`disableUnit`
+ *   (systemctl.ts) — declaring `install.wantedBy` IS the enablement, applied by the generator on
+ *   every `daemon-reload`, exactly the way `Systemd.Unit`'s enable/disable calls are applied by
+ *   this family's own `settle` step. That is the one place this family's "enable logic" differs.
+ * ★ SourcePath TIES THE GENERATED UNIT BACK TO OUR FILE. MEASURED on CT100 2026-09-24:
+ *   `systemctl show caddy.service -p SourcePath` -> `/etc/containers/systemd/caddy.container`.
+ *   `verifyGenerated` below uses it the way `unit-preflight.ts`'s `assertUnclaimed` uses a file
+ *   digest: a generated unit whose SourcePath is NOT our path belongs to a same-named `.container`
+ *   file earlier in `QUADLET_SEARCH_DIRECTORIES` (container-form.ts) — a takeover, not a success.
+ * ⚠️ REASONED, NOT MEASURED — THE ONE GAP THIS VERIFICATION HAS: whether an ALREADY-ACTIVE unit's
+ *   `LoadState` stays `loaded` (systemd does not garbage-collect a referenced/active unit object
+ *   merely because a reload failed to reproduce it) even when the UPDATED `.container` file the
+ *   generator just refused would, on its own, generate nothing. Measuring this needs writing a
+ *   broken file to a live host, which read-only access forbids. If that is how a live host
+ *   behaves, `LoadState`/`SourcePath` alone would not catch a failed update to a container that
+ *   was already running — only a CREATE, or an update to an already-INACTIVE one, is verified with
+ *   full confidence by this check alone. Restoring the last-known-good file on ANY verification
+ *   failure (container-lifecycle.ts) does not depend on this gap: it always leaves the host at the
+ *   file that is known to generate, closing the risk window even where detection is uncertain.
+ * ⛔ `needsVerificationReload` (below) is what stops a NEW resource from getting stuck — found on
+ *   adversarial review. `container-lifecycle.ts`'s `needsReload` used to be `wrote || stale ||
+ *   preStatus.needDaemonReload`; for an INTERRUPTED CREATE (the write landed, the apply crashed
+ *   before `daemon-reload` ran) the retry sees `wrote: false` (the file already holds `desired`)
+ *   and `stale: false` (there is no PRIOR state to disagree with — this is a create), so nothing
+ *   ever reloaded and `verifyGenerated` threw on the still-missing generated unit, forever: loud,
+ *   but stuck, since nothing about a plain retry ever changed. The same holds for adopting a file
+ *   whose generated unit is missing or does not match. `needsVerificationReload` shares
+ *   `generatedMatches` with `verifyGenerated` itself, so the reload gate and the verification it
+ *   is gating can never disagree about what "already proven" means.
+ */
+import type { UnitStatus } from './systemctl.ts';
+
+/** MEASURED on CT100 2026-09-24: `systemctl show caddy.service -p FragmentPath`. */
+export const GENERATED_UNIT_DIRECTORY = '/run/systemd/generator';
+
+export class QuadletGeneratorError extends Error {
+  constructor(name: string, detail: string) {
+    super(`Podman.Container ${name}: ${detail}`);
+    this.name = 'QuadletGeneratorError';
+  }
+}
+
+/** Whether `status` already proves a generated unit that came from `containerPath` — the one
+ *  question both `verifyGenerated` (throws when false) and `needsVerificationReload` (reloads to
+ *  try to make it true) ask. */
+const generatedMatches = (containerPath: string, status: UnitStatus): boolean =>
+  status.known &&
+  status.loadState === 'loaded' &&
+  (status.sourcePath === undefined || status.sourcePath === containerPath);
+
+/**
+ * Whether `container-lifecycle.ts` must `daemon-reload` before trusting `status` as proof of
+ * anything — true whenever `status` does not already show a matching generation. Called on the
+ * PRE-write status, so it costs nothing when `wrote`/`stale`/`NeedDaemonReload` already force a
+ * reload; it earns its keep exactly when none of them do but nothing has actually been proven yet
+ * (a fresh create or adopt with no prior state to compare against).
+ */
+export const needsVerificationReload = (containerPath: string, status: UnitStatus): boolean =>
+  !generatedMatches(containerPath, status);
+
+/**
+ * Throws a typed, loud `QuadletGeneratorError` — never lets a generator failure read as "the
+ * resource is simply absent", which is what a plain `LoadState=not-found` would otherwise look
+ * like to a caller that only knows the `Systemd.Unit` shape (a unit that has genuinely never been
+ * declared also reads `not-found`).
+ */
+export const verifyGenerated = (
+  name: string,
+  containerPath: string,
+  serviceName: string,
+  status: UnitStatus,
+): void => {
+  if (!status.known || status.loadState !== 'loaded') {
+    throw new QuadletGeneratorError(
+      name,
+      `${serviceName} does not exist after daemon-reload (LoadState=${status.loadState}). The ` +
+        '.container file was written and reloaded, so Quadlet’s generator refused it — a bad ' +
+        'key, a bad value, or an interaction this validation does not check. Debug on the host ' +
+        "with '/usr/lib/systemd/system-generators/podman-system-generator --dryrun' or " +
+        `'systemd-analyze --generators=true verify ${serviceName}' (podman-systemd.unit(5), Podman 5.4).`,
+    );
+  }
+  if (status.sourcePath !== undefined && status.sourcePath !== containerPath) {
+    throw new QuadletGeneratorError(
+      name,
+      `${serviceName}'s SourcePath is ${status.sourcePath}, not ${containerPath} — a same-named ` +
+        '.container file earlier in Quadlet’s search path is generating this unit instead of ours ' +
+        '(podman-systemd.unit(5) “Podman Unit Search Path”, Podman 5.4).',
+    );
+  }
+};