@homeflare/alchemy 0.15.0 → 0.19.0

package/src/linux/systemctl.ts

@@ -0,0 +1,145 @@
+/**
+ * The `systemctl` subcommands the systemd family uses, over a HostRunner, plus the parser for the
+ * one that returns data.
+ *
+ * ★ MEASURED 2026-09-22 on Debian 13, systemd 257 (257.13-1~deb13u1), read-only — nothing was
+ *   enabled, started or reloaded to write this:
+ *
+ *   - `systemctl show -p <list> <unit>` EXITS 0 FOR A UNIT THAT DOES NOT EXIST, and answers with
+ *     the properties it would have had:
+ *         Id=hf-nonexistent-xyz.service   LoadState=not-found
+ *         ActiveState=inactive            SubState=dead
+ *         FragmentPath=                   UnitFileState=
+ *     ⛔ SO THE EXIT CODE IS NOT THE ANSWER — `LoadState` is. A provider that read exit 0 as "the
+ *       unit is there" would adopt a unit that does not exist and then never write its file.
+ *   - The properties come back in systemd's own order, not the order asked for, so the output is a
+ *     map and never positional.
+ *   - `systemctl is-enabled <unknown>` exits **4** and prints `not-found`; `is-active <unknown>`
+ *     exits **4** and prints `inactive`. Both are answers, not errors.
+ *   - `UnitFileState=static` is exactly systemd's name for a unit file with no `[Install]` section
+ *     (measured: the journal daemon is `static`, the ssh daemon is `enabled`).
+ *   - `/etc/systemd/system` is `root:root 0755` — the admin drop-in directory, ahead of the
+ *     vendor's `/usr/lib/systemd/system` in systemd's own search order.
+ * ⚠️ REASONED, NOT MEASURED: the write subcommands. `daemon-reload`, `enable`, `disable`, `start`,
+ *   `stop` and `restart` were never run for this file, because running them would change a live
+ *   host. Each is therefore checked the same way: exit 0 or an Error carrying systemd's stderr, and
+ *   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.
+ */
+import type { HostRunner } from '../launchd/runner.ts';
+
+export const SYSTEMCTL = 'systemctl';
+
+/** The properties every read asks for. ⛔ Never `Environment` — see the header. */
+export const SHOW_PROPERTIES = [
+  'Id',
+  'LoadState',
+  'ActiveState',
+  'SubState',
+  'UnitFileState',
+  'FragmentPath',
+  'NeedDaemonReload',
+] as const;
+
+export class SystemctlError extends Error {
+  constructor(command: string, exitCode: number, stderr: string) {
+    super(`systemctl ${command} -> ${String(exitCode)}: ${stderr.trim().slice(0, 300)}`);
+    this.name = 'SystemctlError';
+  }
+}
+
+export type UnitStatus = {
+  /** `loaded`, `not-found`, `masked`, `error`, `bad-setting`. ⛔ The authority on existence. */
+  readonly loadState: string;
+  /** systemd knows this unit: it has a unit file or is loaded. */
+  readonly known: boolean;
+  readonly activeState: string;
+  readonly subState?: string;
+  /** `enabled`, `disabled`, `static`, `masked`, … Empty for a unit with no unit file. */
+  readonly unitFileState?: string;
+  /** The unit file systemd would read. Empty when there is none. */
+  readonly fragmentPath?: string;
+  /** systemd's own view that its on-disk unit files are newer than what it has loaded. */
+  readonly needDaemonReload: boolean;
+};
+
+/** `key=value` lines into a map. ⚠️ First wins: systemd never repeats a key, a truncated read might. */
+export const parseShow = (stdout: string): Map<string, string> => {
+  const fields = new Map<string, string>();
+  for (const line of stdout.split('\n')) {
+    const at = line.indexOf('=');
+    if (at <= 0) continue;
+    const key = line.slice(0, at);
+    if (!fields.has(key)) fields.set(key, line.slice(at + 1));
+  }
+  return fields;
+};
+
+export const statusOf = (stdout: string): UnitStatus => {
+  const fields = parseShow(stdout);
+  const loadState = fields.get('LoadState') ?? 'not-found';
+  const unitFileState = fields.get('UnitFileState') ?? '';
+  const fragmentPath = fields.get('FragmentPath') ?? '';
+  const subState = fields.get('SubState') ?? '';
+  return {
+    activeState: fields.get('ActiveState') ?? 'inactive',
+    // ⛔ MEASURED: `show` answers for a unit that does not exist, so "known" is LoadState plus
+    //   whether systemd found a unit file at all — never the exit code.
+    known: loadState !== 'not-found' || unitFileState !== '',
+    loadState,
+    needDaemonReload: fields.get('NeedDaemonReload') === 'yes',
+    ...(subState === '' ? {} : { subState }),
+    ...(unitFileState === '' ? {} : { unitFileState }),
+    ...(fragmentPath === '' ? {} : { fragmentPath }),
+  };
+};
+
+export const showUnit = async (runner: HostRunner, name: string): Promise<UnitStatus> => {
+  const result = await runner.exec([
+    SYSTEMCTL,
+    'show',
+    '--no-pager',
+    '-p',
+    SHOW_PROPERTIES.join(','),
+    '--',
+    name,
+  ]);
+  // ⚠️ A non-zero `show` means systemctl itself failed (no bus, a malformed name) — not a missing
+  //   unit, which exits 0. Failing closed here is what keeps a broken connection from reading as
+  //   "the unit is gone", which would make the next deploy write its file and restart it.
+  if (result.exitCode !== 0)
+    throw new SystemctlError(`show ${name}`, result.exitCode, result.stderr);
+  return statusOf(result.stdout);
+};
+
+/** One write subcommand, checked. ⚠️ stderr only; `show` output never reaches an error. */
+const run = async (runner: HostRunner, args: readonly string[]): Promise<void> => {
+  const result = await runner.exec([SYSTEMCTL, ...args]);
+  if (result.exitCode !== 0) {
+    throw new SystemctlError(args.join(' '), result.exitCode, result.stderr);
+  }
+};
+
+/** ⛔ After every unit-file write or removal, and before enable/start reads it. */
+export const daemonReload = (runner: HostRunner): Promise<void> => run(runner, ['daemon-reload']);
+
+export const enableUnit = (runner: HostRunner, name: string): Promise<void> =>
+  run(runner, ['enable', '--', name]);
+
+export const disableUnit = (runner: HostRunner, name: string): Promise<void> =>
+  run(runner, ['disable', '--', name]);
+
+export const startUnit = (runner: HostRunner, name: string): Promise<void> =>
+  run(runner, ['start', '--', name]);
+
+export const stopUnit = (runner: HostRunner, name: string): Promise<void> =>
+  run(runner, ['stop', '--', name]);
+
+/**
+ * ⛔ `restart`, NOT `reload-or-restart`. The reloading form asks the unit to re-read its config in
+ *   place when it declares `ExecReload=`, which means "did the change take effect?" has two
+ *   different answers depending on the unit — and a deploy cannot report a half-applied change.
+ */
+export const restartUnit = (runner: HostRunner, name: string): Promise<void> =>
+  run(runner, ['restart', '--', name]);

package/src/linux/unit-form.ts

@@ -0,0 +1,183 @@
+/**
+ * Systemd.Unit / Systemd.Timer props, attributes, the unit-file renderer and the validation — the
+ * pure half of the family.
+ *
+ * ⛔ THE DIRECTIVE SET IS SYSTEMD'S, NOT THIS FILE'S. There is no machine-readable schema of
+ *   `systemd.unit(5)` / `systemd.service(5)` directives to generate from, so this renders SECTIONS
+ *   AND LINES VERBATIM and claims to know nothing about what the keys mean. What it validates is
+ *   only what an INI file must be true of — a section name, a key shape, no embedded newline —
+ *   plus the two structural rules systemd's own output proves (see `unitProblems`). ★ That is the
+ *   honest boundary: invent no vendor shapes, and let `systemd-analyze verify` be the deep check a
+ *   host stack runs on the host.
+ * ⛔ `content` IS NEVER A SECRET. Props sit unencrypted in Alchemy state and the unit file is
+ *   world-readable at 0644; a unit that needs a secret takes `EnvironmentFile=` pointing at a file
+ *   a secret renderer maintains.
+ */
+import { sha256Hex } from '../launchd/job-form.ts';
+
+export type UnitSection = {
+  /** `Unit`, `Service`, `Timer`, `Install`, … — verbatim, including its capitalisation. */
+  readonly name: string;
+  /**
+   * The section's lines, in order. A repeated key is allowed and meaningful in systemd
+   * (`ExecStartPre=` twice runs twice), so this is a list of pairs, never an object.
+   */
+  readonly lines: readonly (readonly [key: string, value: string])[];
+};
+
+export type SystemdUnitProps = {
+  /** Unit name WITH its suffix, e.g. `thing.service`. The unit file's name on disk. */
+  name: string;
+  /** The whole unit file, verbatim. Mutually exclusive with `sections`. */
+  content?: string;
+  /** The unit file as sections, rendered in the order given. Mutually exclusive with `content`. */
+  sections?: readonly UnitSection[];
+  /** Directory the unit file goes in. @default '/etc/systemd/system' */
+  directory?: string;
+  /** `systemctl enable` / `disable`. @default true */
+  enabled?: boolean;
+  /** `systemctl start` / `stop`. @default true */
+  started?: boolean;
+  /**
+   * Digests of things this unit READS that live outside its unit file — a rendered config file's
+   * `sha256` attribute, most often. A change here restarts the unit; nothing else does.
+   * ⚠️ A hand edit of that file is NOT noticed: the digest in state still matches what the stack
+   *   declared, so the unit reads converged. That limit is the same one the Mac side records.
+   */
+  restartOn?: readonly string[];
+};
+
+export type SystemdUnitAttributes = {
+  name: string;
+  unitPath: string;
+  /** SHA-256 of the unit file this resource wrote. */
+  unitSha256: string;
+  /** SHA-256 of `restartOn`, so a config change is a diff. */
+  configSha256: string;
+  loadState: string;
+  activeState: string;
+  unitFileState?: string;
+  enabled: boolean;
+  active: boolean;
+};
+
+/** ★ systemd's admin drop-in directory, ahead of the vendor's in its search order (measured). */
+export const DEFAULT_UNIT_DIRECTORY = '/etc/systemd/system';
+
+/**
+ * Directories systemd looks in for a unit file it can enable.
+ * ★ MEASURED 2026-09-22 with `systemd-analyze unit-paths` on Debian 13 / systemd 257, minus the
+ *   per-user and generator directories, which are not places a stack writes. `/lib/systemd/system`
+ *   is the same directory before the /usr merge, where the measured host has only the merged name.
+ * ⛔ WHY IT IS ENFORCED. `systemctl enable <name>` looks the unit up BY NAME; a unit file outside
+ *   these directories is invisible to that lookup, so an enabled unit declared into, say, `/opt`
+ *   writes its file, reloads, and then fails at `enable` with the file already on disk.
+ */
+export const UNIT_SEARCH_DIRECTORIES = [
+  '/etc/systemd/system',
+  '/run/systemd/system',
+  '/usr/local/lib/systemd/system',
+  '/usr/lib/systemd/system',
+  '/lib/systemd/system',
+] as const;
+
+/** ⛔ The unit file's mode and owner are systemd's rule, not a choice: readable, never writable. */
+export const UNIT_WRITE = { gid: 0, mode: 0o644, uid: 0 } as const;
+
+export const digestOf = (text: string): string => sha256Hex(new TextEncoder().encode(text));
+
+/** The digests of everything outside the unit file that should restart it, as one value. */
+export const configDigest = (restartOn: readonly string[] | undefined): string =>
+  digestOf((restartOn ?? []).join('\n'));
+
+/** Sections → an INI unit file. ★ Keys and values pass through untouched; see the file header. */
+export const renderUnit = (sections: readonly UnitSection[]): string =>
+  `${sections
+    .map((section) =>
+      [`[${section.name}]`, ...section.lines.map(([key, value]) => `${key}=${value}`)].join('\n'),
+    )
+    .join('\n\n')}\n`;
+
+export const unitText = (props: SystemdUnitProps): string =>
+  props.content ?? renderUnit(props.sections ?? []);
+
+export const unitPathFor = (props: SystemdUnitProps): string =>
+  `${props.directory ?? DEFAULT_UNIT_DIRECTORY}/${props.name}`;
+
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_.@:-]*\.([a-z]+)$/;
+/** systemd's own unit types. ★ Fixed vocabulary from `systemd.unit(5)`, not a guess at directives. */
+const TYPES = new Set([
+  'automount',
+  'device',
+  'mount',
+  'path',
+  'scope',
+  'service',
+  'slice',
+  'socket',
+  'swap',
+  'target',
+  'timer',
+]);
+
+const INSTALL_KEYS = new Set(['WantedBy', 'RequiredBy', 'UpsertedBy', 'Also', 'Alias']);
+
+/**
+ * Every refusal at once, so one plan shows the whole list.
+ * ⛔ THE TWO STRUCTURAL RULES, both proven by systemd's own output rather than assumed:
+ *   - `enabled: true` needs an `[Install]` section. `systemctl enable` has nothing to link without
+ *     one, and systemd's name for a unit file that has none is `UnitFileState=static` — measured on
+ *     a live host, where the journal daemon reads `static` and the ssh daemon reads `enabled`.
+ *   - A `.timer` needs a `[Timer]` section, and a timer's `[Install]` is what arms it at boot.
+ */
+export const unitProblems = (props: SystemdUnitProps, expect?: string): string[] => {
+  const found: string[] = [];
+  const type = NAME.exec(props.name)?.[1];
+  if (type === undefined || !TYPES.has(type)) {
+    found.push(
+      `name must be <unit>.<type> with a systemd unit type, got ${JSON.stringify(props.name)}`,
+    );
+  } else if (expect !== undefined && type !== expect) {
+    found.push(`this resource declares a .${expect} unit; ${props.name} is a .${type}`);
+  }
+  if ((props.content === undefined) === (props.sections === undefined)) {
+    found.push('declare exactly one of content or sections');
+  }
+  const directory = props.directory ?? DEFAULT_UNIT_DIRECTORY;
+  if (!directory.startsWith('/') || directory.endsWith('/') || directory.includes('/..')) {
+    found.push('directory must be an absolute, normalised path with no trailing slash');
+  }
+  found.push(...textProblems(unitText(props)));
+  if (props.enabled !== false && !UNIT_SEARCH_DIRECTORIES.includes(directory as never)) {
+    found.push(
+      `an enabled unit must live where systemd looks for it by name (${UNIT_SEARCH_DIRECTORIES.join(', ')}); ` +
+        `${directory} is not one of them. Move it, or declare enabled: false.`,
+    );
+  }
+  if (props.enabled !== false && !hasInstall(props)) {
+    found.push(
+      'enabled units need an [Install] section with WantedBy/RequiredBy/Also/Alias; without one ' +
+        'systemd calls the unit "static" and `systemctl enable` has nothing to link. Add one, or ' +
+        'declare enabled: false and let something else pull it in.',
+    );
+  }
+  if (type === 'timer' && !unitText(props).includes('[Timer]')) {
+    found.push('a .timer needs a [Timer] section');
+  }
+  return found;
+};
+
+const hasInstall = (props: SystemdUnitProps): boolean => {
+  const text = unitText(props);
+  if (!text.includes('[Install]')) return false;
+  const after = text.slice(text.indexOf('[Install]'));
+  return [...INSTALL_KEYS].some((key) => new RegExp(`^${key}=`, 'm').test(after));
+};
+
+const textProblems = (text: string): string[] => {
+  const found: string[] = [];
+  if (text.trim() === '') found.push('the unit file is empty');
+  if (text.includes('\u0000')) found.push('the unit file contains NUL');
+  if (!/^\s*\[[A-Za-z]+]/.test(text)) found.push('a unit file must begin with a [Section]');
+  return found;
+};

package/src/linux/unit-handlers.ts

@@ -0,0 +1,73 @@
+/**
+ * The four provider handlers `Systemd.Unit` and `Systemd.Timer` share, as plain functions over a
+ * HostRunner — so the two Resources differ only in their TYPE and the unit suffix they insist on.
+ *
+ * ★ WHY NOT ONE SHARED HANDLER OBJECT. `Provider.of` is typed per Resource, so an object built once
+ *   and passed to both would have to be widened or cast; functions with their arguments spelled out
+ *   keep both call sites fully checked and still say each rule once.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import type { Diff } from 'alchemy/Diff';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import { lift, resolvedString } from '../launchd/host-effect.ts';
+import type { HostRunner } from '../launchd/runner.ts';
+import { adoptsAtApply } from '../ownership/adopt.ts';
+import { noteUnfinished } from '../ownership/resume.ts';
+import type { SystemdUnitAttributes, SystemdUnitProps } from './unit-form.ts';
+import { deleteUnit, diffUnit, readUnit, reconcileUnit } from './unit-lifecycle.ts';
+
+export const readHandler = (
+  runner: HostRunner,
+  olds: SystemdUnitProps,
+  output: SystemdUnitAttributes | undefined,
+): Effect.Effect<SystemdUnitAttributes | undefined, Error> =>
+  lift(async () => {
+    const found = await readUnit(runner, olds);
+    if (found === undefined) return undefined;
+    return output === undefined ? Unowned(found) : found;
+  });
+
+export const diffHandler = (
+  runner: HostRunner,
+  instanceId: string,
+  news: Input<SystemdUnitProps>,
+  output: SystemdUnitAttributes | undefined,
+  expect?: string,
+): Effect.Effect<Diff | undefined, Error> => {
+  // ★ An unfinished generation of our own: `--adopt` may resume it (ownership/resume.ts).
+  if (output === undefined) return noteUnfinished(instanceId);
+  if (isResolved(news)) return lift(() => diffUnit(runner, news, output, expect));
+  /**
+   * ⛔ A RENAME MUST BE SEEN EVEN WHILE OTHER PROPS ARE UNRESOLVED. The engine's default for a prop
+   *   change is `update`, and an update under a new name writes the new unit file and leaves the old
+   *   unit running with nothing in state to ever remove it. `content` is exactly what is unresolved
+   *   when a rendered config file's digest is templated into the same deploy.
+   */
+  const name = resolvedString(news, 'name');
+  return Effect.succeed(
+    name !== undefined && name !== output.name
+      ? { action: 'replace' as const, deleteFirst: true }
+      : undefined,
+  );
+};
+
+export const reconcileHandler = (
+  runner: HostRunner,
+  args: {
+    fqn: string;
+    instanceId: string;
+    news: SystemdUnitProps;
+    output: SystemdUnitAttributes | undefined;
+  },
+  expect?: string,
+): Effect.Effect<SystemdUnitAttributes, Error> =>
+  Effect.flatMap(adoptsAtApply(args), (adopt) =>
+    lift(() => reconcileUnit(runner, args.news, args.output, adopt, expect)),
+  );
+
+export const deleteHandler = (
+  runner: HostRunner,
+  output: SystemdUnitAttributes,
+): Effect.Effect<void, Error> => lift(() => deleteUnit(runner, output));

package/src/linux/unit-lifecycle.test.ts

@@ -0,0 +1,220 @@
+/**
+ * The systemd family against the fake host. ⛔ The assertions that matter here are the NEGATIVE
+ *   ones: an adopted unit that already matches is not restarted, a re-run restarts nothing, and a
+ *   read that fails writes nothing. An estate rebuild must be able to reach a host holding a vault
+ *   or a clock without bouncing it.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeLinuxHost } from './fake-linux-host.ts';
+import { statusOf } from './systemctl.ts';
+import { renderUnit, unitProblems } from './unit-form.ts';
+import { deleteUnit, diffUnit, readUnit, reconcileUnit } from './unit-lifecycle.ts';
+
+const NAME = 'hf-example.service';
+const PATH = `/etc/systemd/system/${NAME}`;
+const body = (exec: string) =>
+  renderUnit([
+    { lines: [['Description', 'an example']], name: 'Unit' },
+    {
+      lines: [
+        ['ExecStart', exec],
+        ['Restart', 'on-failure'],
+      ],
+      name: 'Service',
+    },
+    { lines: [['WantedBy', 'multi-user.target']], name: 'Install' },
+  ]);
+
+const props = { content: body('/usr/bin/example'), name: NAME };
+const host = () => fakeLinuxHost({ dirs: { '/etc/systemd/system': 0 } });
+const verbs = (calls: string[][]) =>
+  calls.filter((call) => call[0] === 'systemctl').map((call) => call[1]);
+
+describe('create', () => {
+  test('writes, reloads, enables and starts — in that order', async () => {
+    const fake = host();
+    const attrs = await reconcileUnit(fake.runner, props, undefined);
+    expect(attrs).toMatchObject({ active: true, enabled: true, name: NAME, unitPath: PATH });
+    expect(verbs(fake.calls)).toEqual(['show', 'daemon-reload', 'enable', 'start', 'show']);
+    expect(fake.files.get(PATH)?.mode).toBe(0o644);
+    expect(fake.files.get(PATH)?.uid).toBe(0);
+  });
+
+  test('a start that fails removes the file this deploy wrote and says the unit is down', async () => {
+    const fake = fakeLinuxHost({ dirs: { '/etc/systemd/system': 0 } });
+    const broken = {
+      ...fake.runner,
+      exec: async (argv: readonly string[]) =>
+        argv[1] === 'start'
+          ? { exitCode: 1, stderr: 'Job failed', stdout: '' }
+          : fake.runner.exec(argv),
+    };
+    await expect(reconcileUnit(broken, props, undefined)).rejects.toThrow(/NOT running/);
+    expect(fake.files.has(PATH)).toBe(false);
+  });
+});
+
+describe('adoption', () => {
+  test('a live unit that already matches is adopted without a restart', async () => {
+    const fake = host();
+    fake.placeUnit(PATH, props.content, { active: true, enabled: true });
+    const before = fake.calls.length;
+    const attrs = await reconcileUnit(fake.runner, props, undefined, true);
+    expect(attrs).toMatchObject({ active: true, enabled: true });
+    const after = verbs(fake.calls.slice(before));
+    expect(after).toEqual(['show', 'show']);
+    expect(after).not.toContain('restart');
+    expect(after).not.toContain('daemon-reload');
+  });
+
+  test('and its diff is a noop, so a plan shows nothing to do', async () => {
+    const fake = host();
+    fake.placeUnit(PATH, props.content, { active: true, enabled: true });
+    const output = await reconcileUnit(fake.runner, props, undefined, true);
+    expect(await diffUnit(fake.runner, props, output)).toEqual({ action: 'noop' });
+  });
+
+  test('a live unit with other content is refused without --adopt', async () => {
+    const fake = host();
+    fake.placeUnit(PATH, body('/usr/bin/something-else'), { active: true, enabled: true });
+    await expect(reconcileUnit(fake.runner, props, undefined)).rejects.toThrow(/--adopt/);
+  });
+});
+
+describe('restart happens exactly when something changed', () => {
+  test('a changed unit file restarts once', async () => {
+    const fake = host();
+    fake.placeUnit(PATH, body('/usr/bin/old'), { active: true, enabled: true });
+    const output = await reconcileUnit(fake.runner, props, undefined, true);
+    const before = fake.calls.length;
+    const next = { ...props, content: body('/usr/bin/new') };
+    expect(await diffUnit(fake.runner, next, output)).toEqual({ action: 'update' });
+    const updated = await reconcileUnit(fake.runner, next, output);
+    const after = verbs(fake.calls.slice(before));
+    expect(after.filter((verb) => verb === 'restart')).toHaveLength(1);
+    expect(after).not.toContain('stop');
+    expect(updated.active).toBe(true);
+  });
+
+  test('a tracked config digest restarts the unit without rewriting its file', async () => {
+    const fake = host();
+    const first = await reconcileUnit(fake.runner, { ...props, restartOn: ['aaa'] }, undefined);
+    const next = { ...props, restartOn: ['bbb'] };
+    expect(await diffUnit(fake.runner, next, first)).toEqual({ action: 'update' });
+    const before = fake.calls.length;
+    await reconcileUnit(fake.runner, next, first);
+    const after = fake.calls.slice(before);
+    expect(verbs(after)).toContain('restart');
+    expect(after.some((call) => call[0] === 'write')).toBe(false);
+  });
+
+  test('a re-run with nothing changed restarts nothing at all', async () => {
+    const fake = host();
+    const output = await reconcileUnit(fake.runner, props, undefined);
+    const before = fake.calls.length;
+    await reconcileUnit(fake.runner, props, output);
+    const after = verbs(fake.calls.slice(before));
+    expect(after).toEqual(['show', 'show']);
+  });
+
+  test('started: false stops a running unit and does not restart it', async () => {
+    const fake = host();
+    fake.placeUnit(PATH, props.content, { active: true, enabled: true });
+    const output = await reconcileUnit(fake.runner, props, undefined, true);
+    const stopped = await reconcileUnit(fake.runner, { ...props, started: false }, output);
+    expect(stopped.active).toBe(false);
+    expect(verbs(fake.calls)).toContain('stop');
+    expect(verbs(fake.calls)).not.toContain('restart');
+  });
+});
+
+describe('refusals', () => {
+  test('a read that fails refuses and writes nothing', async () => {
+    const fake = fakeLinuxHost({ dirs: { '/etc/systemd/system': 0 }, failShow: true });
+    await expect(reconcileUnit(fake.runner, props, undefined)).rejects.toThrow(/systemctl show/);
+    expect(fake.files.has(PATH)).toBe(false);
+    expect(verbs(fake.calls)).not.toContain('daemon-reload');
+  });
+
+  test('a masked unit is someone’s decision, not drift', async () => {
+    const fake = host();
+    fake.placeUnit(PATH, props.content, { masked: true });
+    await expect(reconcileUnit(fake.runner, props, undefined, true)).rejects.toThrow(/is masked/);
+  });
+
+  test('an unprivileged runner refuses before it touches anything', async () => {
+    const fake = fakeLinuxHost({ dirs: { '/etc/systemd/system': 0 }, euid: 1001 });
+    await expect(reconcileUnit(fake.runner, props, undefined)).rejects.toThrow(/never calls sudo/);
+    expect(fake.calls).toHaveLength(0);
+  });
+
+  test('an enabled unit with no [Install] is refused at validation, not at systemctl', () => {
+    const noInstall = {
+      content: '[Unit]\nDescription=x\n[Service]\nExecStart=/bin/true\n',
+      name: NAME,
+    };
+    expect(unitProblems(noInstall).join(' ')).toMatch(/\[Install\]/);
+    expect(unitProblems({ ...noInstall, enabled: false })).toEqual([]);
+  });
+
+  test('a timer resource refuses a .service, and a .timer needs a [Timer] section', () => {
+    expect(unitProblems(props, 'timer').join(' ')).toMatch(/is a \.service/);
+    expect(unitProblems({ content: props.content, name: 'x.timer' }, 'timer').join(' ')).toMatch(
+      /\[Timer\]/,
+    );
+  });
+
+  test('an enabled unit outside systemd’s search path is refused at plan time', () => {
+    // ⛔ `systemctl enable` looks a unit up BY NAME; a file in /opt is invisible to that lookup,
+    //   so without this the deploy writes the file, reloads, and only then fails.
+    const elsewhere = { ...props, directory: '/opt/app/units' };
+    expect(unitProblems(elsewhere).join(' ')).toMatch(/where systemd looks for it by name/);
+    expect(unitProblems({ ...elsewhere, enabled: false })).toEqual([]);
+    expect(unitProblems({ ...props, directory: '/usr/local/lib/systemd/system' })).toEqual([]);
+  });
+
+  test('an enable that systemd did not honour is a refusal, not a claim in state', async () => {
+    const fake = host();
+    const lying = {
+      ...fake.runner,
+      exec: async (argv: readonly string[]) =>
+        argv[1] === 'enable' ? { exitCode: 0, stderr: '', stdout: '' } : fake.runner.exec(argv),
+    };
+    await expect(reconcileUnit(lying, props, undefined)).rejects.toThrow(/not enabled/);
+  });
+
+  test('both or neither of content and sections is a refusal', () => {
+    expect(unitProblems({ name: NAME }).join(' ')).toMatch(/exactly one of content or sections/);
+  });
+});
+
+describe('delete', () => {
+  test('stops, disables, removes the file and reloads', async () => {
+    const fake = host();
+    const output = await reconcileUnit(fake.runner, props, undefined);
+    const before = fake.calls.length;
+    await deleteUnit(fake.runner, output);
+    expect(verbs(fake.calls.slice(before))).toEqual(['show', 'stop', 'disable', 'daemon-reload']);
+    expect(fake.files.has(PATH)).toBe(false);
+    expect(await readUnit(fake.runner, props)).toBeUndefined();
+  });
+});
+
+describe('systemctl show, as measured', () => {
+  test('a unit that does not exist answers, and the answer is LoadState', () => {
+    // MEASURED 2026-09-22, Debian 13 / systemd 257: exit 0, LoadState=not-found.
+    const status = statusOf(
+      'Id=absent.service\nLoadState=not-found\nActiveState=inactive\nSubState=dead\n' +
+        'FragmentPath=\nUnitFileState=\nNeedDaemonReload=no\n',
+    );
+    expect(status).toMatchObject({ known: false, loadState: 'not-found' });
+  });
+
+  test('a real unit parses whatever order systemd prints', () => {
+    const status = statusOf(
+      'ExecStart={ path=/usr/sbin/sshd ; argv[]=/usr/sbin/sshd -D $SSHD_OPTS }\n' +
+        'Description=OpenBSD Secure Shell server\nLoadState=loaded\nUnitFileState=enabled\n',
+    );
+    expect(status).toMatchObject({ known: true, loadState: 'loaded', unitFileState: 'enabled' });
+  });
+});