@homeflare/alchemy 0.15.0 → 0.19.1

package/src/linux/unit-lifecycle.ts

@@ -0,0 +1,175 @@
+/**
+ * Systemd.Unit's read / diff / reconcile / delete as plain async functions over a HostRunner, so
+ * the whole lifecycle runs against a fake host with no real systemd.
+ *
+ * ⛔ WHAT A DEPLOY DOES NOT DO — the rule this family was built around. It NEVER mass-restarts.
+ *   A unit is restarted only when THIS resource's unit file changed, or when a digest the
+ *   declaration itself listed in `restartOn` changed. A unit that is already running the content
+ *   we declare is left strictly alone: no restart, no reload, not even a `start`. An estate rebuild
+ *   must be able to reach a host that holds a vault, a UPS handler or a clock without bouncing
+ *   them, and "the deploy ran" must never be a reason anything went down.
+ * ★ THE ORDER IS WRITE, RELOAD, ENABLE, THEN START OR RESTART. systemd reads the unit file at
+ *   `daemon-reload`, so writing it while the old unit runs changes nothing yet, and a write that
+ *   fails leaves the old unit running rather than leaving nothing running.
+ * ⚠️ A FAILED START LEAVES THE UNIT DOWN. On an update the new unit file stays and state keeps the
+ *   previous digest, so the next deploy retries. On a CREATE the file this deploy wrote is removed
+ *   and systemd reloaded again: left behind, the next plan's recovery read finds a unit with no
+ *   state, reports it `Unowned`, and every later deploy demands `--adopt` for our own file.
+ * ⛔ A MASKED UNIT IS SOMEONE'S DECISION, NOT DRIFT. `systemctl mask` survives reboots and makes
+ *   start fail; unmasking here would silently overrule whoever masked it.
+ */
+import type { Diff } from 'alchemy/Diff';
+import type { HostRunner } from '../launchd/runner.ts';
+import { daemonReload, disableUnit, showUnit, stopUnit } from './systemctl.ts';
+import {
+  type SystemdUnitAttributes,
+  type SystemdUnitProps,
+  UNIT_WRITE,
+  configDigest,
+  digestOf,
+  unitPathFor,
+  unitText,
+} from './unit-form.ts';
+import { assertMayWrite, assertReplaceable, assertUsable, assertValid } from './unit-preflight.ts';
+import { attributesOf, refuse, settle } from './unit-settle.ts';
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** What is on the host now: the unit file's digest and systemd's view. `undefined` when neither. */
+export const readUnit = async (
+  runner: HostRunner,
+  props: SystemdUnitProps,
+): Promise<SystemdUnitAttributes | undefined> => {
+  const bytes = await runner.readFile(unitPathFor(props));
+  const status = await showUnit(runner, props.name);
+  if (bytes === undefined && !status.known) return undefined;
+  return attributesOf(props, bytes === undefined ? '' : digestOf(decoder.decode(bytes)), status);
+};
+
+export const diffUnit = async (
+  runner: HostRunner,
+  news: SystemdUnitProps,
+  output: SystemdUnitAttributes,
+  expect?: string,
+): Promise<Diff> => {
+  assertValid(news, expect);
+  // ★ The unit's name or its directory is its identity on the host: a change is a replace, and
+  //   delete-first, because two unit files for one name cannot both be the one systemd reads.
+  // ⛔ Which is why everything the new unit's reconcile would refuse is refused HERE, at plan
+  //   time (unit-preflight.ts): after the delete it would be too late.
+  if (news.name !== output.name || unitPathFor(news) !== output.unitPath) {
+    await assertReplaceable(runner, news, output, expect);
+    return { action: 'replace', deleteFirst: true };
+  }
+  const desired = digestOf(unitText(news));
+  const update = async (): Promise<Diff> => {
+    assertMayWrite(runner, news.name);
+    await runner.checkWrite?.(unitPathFor(news), UNIT_WRITE);
+    return { action: 'update' };
+  };
+  // ⛔ BOTH digests: the stored one catches a start that failed after the write landed, the live
+  //   one catches a hand edit. Either alone reports `noop` over a unit that is not what we say.
+  if (desired !== output.unitSha256) return update();
+  if (configDigest(news.restartOn) !== output.configSha256) return update();
+  const live = await readUnit(runner, news);
+  if (live === undefined || live.unitSha256 !== desired) return update();
+  if (live.enabled !== (news.enabled !== false)) return update();
+  if (live.active !== (news.started !== false)) return update();
+  // ⚠️ systemd's own word for "the file on disk is newer than what I loaded" — a write that landed
+  //   without its reload. It is drift that neither digest can see.
+  const status = await showUnit(runner, news.name);
+  return status.needDaemonReload ? update() : { action: 'noop' };
+};
+
+/**
+ * `adopt` is whether adoption is on AND this apply is a create or an unfinished generation of our
+ * own (ownership/adopt.ts): it lets such a generation take over a unit already on the host.
+ * ★ AN ADOPTED UNIT THAT ALREADY MATCHES IS NOT RESTARTED. That is the whole point of adopting one:
+ *   the estate's live services come under declaration without a single bounce.
+ */
+export const reconcileUnit = async (
+  runner: HostRunner,
+  props: SystemdUnitProps,
+  output: SystemdUnitAttributes | undefined,
+  adopt = false,
+  expect?: string,
+): Promise<SystemdUnitAttributes> => {
+  assertValid(props, expect);
+  assertMayWrite(runner, props.name);
+  const path = unitPathFor(props);
+  const status = await showUnit(runner, props.name);
+  assertUsable(props, status);
+  const text = unitText(props);
+  const desired = digestOf(text);
+  const before = await runner.readFile(path);
+  const liveSha = before === undefined ? undefined : digestOf(decoder.decode(before));
+  const moved = output !== undefined && (output.name !== props.name || output.unitPath !== path);
+  /**
+   * ★ A rename the diff could not see — a name that was still an unresolved Output at plan time
+   *   (unit-handlers.ts diffHandler) — arrives here as an update. Run the same read-only checks a
+   *   plan-time replace runs, BEFORE deleteUnit, or the old unit is already gone when we refuse.
+   */
+  if (moved && output !== undefined) await assertReplaceable(runner, props, output, expect);
+  const prior = moved ? undefined : output;
+  /**
+   * ⛔ A UNIT THIS RESOURCE DOES NOT OWN IS NEVER OVERWRITTEN. Where the engine's probe never
+   *   looked — a replace's new name, a create whose props were still an Output at plan time — a
+   *   unit file already there with other content belongs to someone else, and writing ours over it
+   *   would take their service. ★ A byte-identical file is this declaration's own leftover.
+   */
+  if (
+    prior === undefined &&
+    !(adopt && output === undefined) &&
+    liveSha !== undefined &&
+    liveSha !== desired
+  ) {
+    throw refuse(
+      props.name,
+      `${path} is already on this host and is not this resource. Remove it, or declare it as a ` +
+        'new resource and deploy with --adopt.',
+    );
+  }
+  if (moved && output !== undefined) await deleteUnit(runner, output);
+  const wrote = liveSha !== desired;
+  /**
+   * ⛔ THE THREE THINGS THAT EARN A RESTART, and nothing else:
+   *   - the unit file's bytes changed (`wrote`);
+   *   - state holds an older digest than the file does — a previous deploy's write landed and its
+   *     reload or restart never ran, so systemd is still running the old content;
+   *   - systemd itself says its loaded unit is older than the file (`NeedDaemonReload`, measured);
+   *   - a digest the declaration listed in `restartOn` changed.
+   * ★ An adopted, converged unit hits none of them, which is why adoption never bounces a service.
+   */
+  const stale = prior !== undefined && prior.unitSha256 !== desired;
+  const configChanged = prior !== undefined && prior.configSha256 !== configDigest(props.restartOn);
+  if (wrote) await runner.writeFileAtomic(path, encoder.encode(text), UNIT_WRITE);
+  if (wrote || status.needDaemonReload) await daemonReload(runner);
+  const changed = wrote || stale || status.needDaemonReload;
+  return settle(runner, props, { before, changed, configChanged, desired, path, status });
+};
+
+/**
+ * Stop, disable, remove the unit file, reload. Idempotent.
+ * ⛔ DELETING THE DECLARATION STOPS THE SERVICE. That is what removing it from the stack means, and
+ *   it is why a unit that must outlive its declaration is adopted rather than deleted.
+ */
+export const deleteUnit = async (
+  runner: HostRunner,
+  output: SystemdUnitAttributes,
+): Promise<void> => {
+  assertMayWrite(runner, output.name);
+  const status = await showUnit(runner, output.name);
+  if (status.activeState === 'active' || status.activeState === 'activating') {
+    await stopUnit(runner, output.name);
+  }
+  if (status.unitFileState === 'enabled' || status.unitFileState === 'enabled-runtime') {
+    await disableUnit(runner, output.name);
+  }
+  const stat = await runner.stat(output.unitPath);
+  if (stat !== undefined) {
+    if (stat.kind !== 'file') throw refuse(output.name, `${output.unitPath} is a ${stat.kind}`);
+    await runner.removeFile(output.unitPath);
+  }
+  await daemonReload(runner);
+};

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

@@ -0,0 +1,128 @@
+/**
+ * A systemd rename is a delete-first replace, so every refusal has to fire at PLAN time. Caught
+ * only in reconcile, Alchemy has already stopped and removed the old unit (Apply.ts,
+ * deleteOldGenerations under `node.deleteFirst`).
+ *
+ * ★ The last case is the one the diff cannot see: a name that was still an Output at plan time
+ *   arrives at reconcile as an update (unit-handlers.ts). The same refusals have to fire there,
+ *   before deleteUnit.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeLinuxHost } from './fake-linux-host.ts';
+import { renderUnit } from './unit-form.ts';
+import { deleteUnit, diffUnit, reconcileUnit } from './unit-lifecycle.ts';
+
+const NAME = 'hf-example.service';
+const PATH = `/etc/systemd/system/${NAME}`;
+const RENAMED = 'hf-renamed.service';
+const RENAMED_PATH = `/etc/systemd/system/${RENAMED}`;
+
+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 renamed = { ...props, name: RENAMED };
+const host = () => fakeLinuxHost({ dirs: { '/etc/systemd/system': 0 } });
+
+const running = async () => {
+  const fake = host();
+  const output = await reconcileUnit(fake.runner, props, undefined);
+  return { fake, output };
+};
+
+describe('a rename is refused at plan time, and the old unit is still running', () => {
+  test('a masked new name', async () => {
+    const { fake, output } = await running();
+    fake.placeUnit(RENAMED_PATH, body('/usr/bin/other'), { masked: true });
+    await expect(diffUnit(fake.runner, renamed, output)).rejects.toThrow(/is masked/);
+    expect(fake.units.get(NAME)?.active).toBe(true);
+    expect(fake.files.has(PATH)).toBe(true);
+  });
+
+  test('a new name whose file belongs to someone else', async () => {
+    const { fake, output } = await running();
+    fake.placeUnit(RENAMED_PATH, body('/usr/bin/other'), { active: true, enabled: true });
+    await expect(diffUnit(fake.runner, renamed, output)).rejects.toThrow(/not this resource/);
+    expect(fake.units.get(NAME)?.active).toBe(true);
+    expect(fake.units.get(RENAMED)?.active).toBe(true);
+  });
+
+  test('a file byte-identical to our render is our own leftover, not a claim', async () => {
+    const { fake, output } = await running();
+    fake.placeUnit(RENAMED_PATH, props.content);
+    expect(await diffUnit(fake.runner, renamed, output)).toEqual({
+      action: 'replace',
+      deleteFirst: true,
+    });
+  });
+
+  test('a runner that will not write the new path', async () => {
+    const { fake, output } = await running();
+    const refusing = {
+      ...fake.runner,
+      checkWrite: async () => {
+        throw new Error('HostRunner.checkWrite refused');
+      },
+    };
+    await expect(diffUnit(refusing, renamed, output)).rejects.toThrow(/checkWrite/);
+    expect(fake.units.get(NAME)?.active).toBe(true);
+  });
+
+  test('the old unit must be deletable before a delete-first replace is promised', async () => {
+    const { fake, output } = await running();
+    const unprivileged = { ...fake.runner, effectiveUid: () => 1001, privileged: false };
+    await expect(diffUnit(unprivileged, renamed, output)).rejects.toThrow(/never calls sudo/);
+    expect(fake.units.get(NAME)?.active).toBe(true);
+    expect(fake.files.has(PATH)).toBe(true);
+  });
+});
+
+describe('a free name', () => {
+  test('plans a delete-first replace, and delete-then-reconcile leaves only the new unit', async () => {
+    const { fake, output } = await running();
+    expect(await diffUnit(fake.runner, renamed, output)).toEqual({
+      action: 'replace',
+      deleteFirst: true,
+    });
+    await deleteUnit(fake.runner, output);
+    const next = await reconcileUnit(fake.runner, renamed, output);
+    expect(next).toMatchObject({
+      active: true,
+      enabled: true,
+      name: RENAMED,
+      unitPath: RENAMED_PATH,
+    });
+    expect(fake.files.has(PATH)).toBe(false);
+    expect(fake.files.has(RENAMED_PATH)).toBe(true);
+    expect(fake.units.get(NAME)?.active ?? false).toBe(false);
+  });
+});
+
+describe('a rename the diff could not see is refused at apply, before the old unit stops', () => {
+  test('a masked new name', async () => {
+    const { fake, output } = await running();
+    fake.placeUnit(RENAMED_PATH, body('/usr/bin/other'), { masked: true });
+    await expect(reconcileUnit(fake.runner, renamed, output)).rejects.toThrow(/is masked/);
+    expect(fake.units.get(NAME)?.active).toBe(true);
+    expect(fake.files.has(PATH)).toBe(true);
+  });
+
+  test('a new name whose file belongs to someone else', async () => {
+    const { fake, output } = await running();
+    fake.placeUnit(RENAMED_PATH, body('/usr/bin/other'), { active: true, enabled: true });
+    await expect(reconcileUnit(fake.runner, renamed, output)).rejects.toThrow(/not this resource/);
+    expect(fake.units.get(NAME)?.active).toBe(true);
+    expect(fake.files.has(PATH)).toBe(true);
+    expect(fake.units.get(RENAMED)?.active).toBe(true);
+  });
+});

package/src/linux/unit-preflight.ts

@@ -0,0 +1,100 @@
+/**
+ * Everything Systemd.Unit checks before it touches the host — split from unit-lifecycle.ts so that
+ * a reconcile and a plan-time REPLACE run the very same checks.
+ *
+ * ★ WHY A REPLACE IS CHECKED AT PLAN TIME. A name or directory change is a delete-first replace,
+ *   and Alchemy runs `delete` on the old unit BEFORE `reconcile` on the new one (Apply.ts,
+ *   deleteOldGenerations under `node.deleteFirst`). A refusal that fired only in reconcile would
+ *   therefore arrive after the old unit was already stopped and its file removed: nothing running,
+ *   and a plan that had promised a clean swap.
+ * ★ EVERY CHECK HERE IS READ-ONLY. systemd has no `print-disabled` equivalent in this family —
+ *   masking is `systemctl show`'s LoadState / UnitFileState, which `showUnit` already returns.
+ *   Validation, that show, a file read and `HostRunner.checkWrite` write nothing. `systemctl
+ *   enable` itself stays an apply step; the ways it is known to fail (no `[Install]`, a directory
+ *   systemd does not search) are `unitProblems`, checked here before the plan may promise a swap.
+ */
+import { type HostRunner, canActAsRoot } from '../launchd/runner.ts';
+import { type UnitStatus, showUnit } from './systemctl.ts';
+import {
+  type SystemdUnitAttributes,
+  type SystemdUnitProps,
+  UNIT_WRITE,
+  digestOf,
+  unitPathFor,
+  unitProblems,
+  unitText,
+} from './unit-form.ts';
+import { refuse } from './unit-settle.ts';
+
+const decoder = new TextDecoder();
+
+/** Throw every refusal at once, so one plan shows the whole list. */
+export const assertValid = (props: SystemdUnitProps, expect?: string): void => {
+  const found = unitProblems(props, expect);
+  if (found.length > 0) throw refuse(props.name, found.join('; '));
+};
+
+/** ⛔ Writing a unit file and driving systemd are root's, so refuse up front rather than mid-apply. */
+export const assertMayWrite = (runner: HostRunner, name: string): void => {
+  if (canActAsRoot(runner)) return;
+  throw refuse(
+    name,
+    'a systemd unit is root-owned and systemctl needs root. Point the runner at a destination ' +
+      'whose ssh user is root, or provide a privileged HostRunner. This provider never calls sudo.',
+  );
+};
+
+/**
+ * ⛔ A MASKED UNIT IS SOMEONE'S DECISION, NOT DRIFT. `systemctl mask` survives reboots and makes
+ *   start fail; unmasking here would silently overrule whoever masked it.
+ */
+export const assertUsable = (props: SystemdUnitProps, status: UnitStatus): void => {
+  if (status.loadState === 'masked' || status.unitFileState === 'masked') {
+    throw refuse(
+      props.name,
+      'is masked. If that is stale, `systemctl unmask` it deliberately, then redeploy. Nothing ' +
+        'was written.',
+    );
+  }
+};
+
+/**
+ * ⛔ A UNIT THIS RESOURCE DOES NOT OWN IS NEVER OVERWRITTEN. Alchemy's adoption probe guards a
+ *   create, but NOT the new name of a replace — the engine reads nothing there — so a rename onto
+ *   a unit file someone else already has would stop the old unit and write ours over theirs.
+ * ★ A file byte-identical to our render is exempt: it is this declaration's own leftover (a deploy
+ *   that died between write and reload), and rewriting it changes nothing.
+ */
+export const assertUnclaimed = async (
+  runner: HostRunner,
+  props: SystemdUnitProps,
+): Promise<void> => {
+  const path = unitPathFor(props);
+  const bytes = await runner.readFile(path);
+  const live = bytes === undefined ? undefined : digestOf(decoder.decode(bytes));
+  if (live !== undefined && live !== digestOf(unitText(props))) {
+    throw refuse(
+      props.name,
+      `${path} is already on this host and is not this resource. Remove it, or declare it as a ` +
+        'new resource and deploy with --adopt.',
+    );
+  }
+};
+
+/**
+ * A rename, checked at plan time: the new identity must be valid, writable, not masked and free,
+ * and the old one deletable — before the plan may promise a delete-first replace.
+ */
+export const assertReplaceable = async (
+  runner: HostRunner,
+  next: SystemdUnitProps,
+  old: SystemdUnitAttributes,
+  expect?: string,
+): Promise<void> => {
+  assertValid(next, expect);
+  assertMayWrite(runner, old.name);
+  assertMayWrite(runner, next.name);
+  assertUsable(next, await showUnit(runner, next.name));
+  await assertUnclaimed(runner, next);
+  await runner.checkWrite?.(unitPathFor(next), UNIT_WRITE);
+};

package/src/linux/unit-settle.ts

@@ -0,0 +1,110 @@
+/**
+ * The step that decides whether anything on the host actually moves: enablement, running state and
+ * — only for a real change — a restart. Split from unit-lifecycle.ts because it is the rule the
+ * whole family exists to keep, and it should be readable on its own.
+ *
+ * ⛔ THE RESTART CONDITION IS THE WHOLE CONTRACT. `changed` is set by the caller from the four
+ *   things that earn one (unit-lifecycle.ts reconcileUnit); `configChanged` is a digest the
+ *   DECLARATION itself listed. Nothing else restarts a unit — not a re-run, not an unrelated
+ *   resource in the same deploy, not `--adopt`.
+ */
+import type { HostRunner } from '../launchd/runner.ts';
+import {
+  type SystemdUnitAttributes,
+  type SystemdUnitProps,
+  configDigest,
+  unitPathFor,
+} from './unit-form.ts';
+import {
+  type UnitStatus,
+  daemonReload,
+  disableUnit,
+  enableUnit,
+  restartUnit,
+  showUnit,
+  startUnit,
+  stopUnit,
+} from './systemctl.ts';
+
+export const refuse = (name: string, message: string): Error =>
+  new Error(`Systemd.Unit ${name}: ${message}`);
+
+export const attributesOf = (
+  props: SystemdUnitProps,
+  unitSha256: string,
+  status: UnitStatus,
+): SystemdUnitAttributes => ({
+  active: status.activeState === 'active' || status.activeState === 'activating',
+  activeState: status.activeState,
+  configSha256: configDigest(props.restartOn),
+  enabled: status.unitFileState === 'enabled' || status.unitFileState === 'enabled-runtime',
+  loadState: status.loadState,
+  name: props.name,
+  unitPath: unitPathFor(props),
+  unitSha256,
+  ...(status.unitFileState === undefined ? {} : { unitFileState: status.unitFileState }),
+});
+
+export type Settle = {
+  readonly before: Uint8Array | undefined;
+  /** The unit 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 status: UnitStatus;
+};
+
+/**
+ * Bring enablement and running state to the declaration, restarting ONLY for a real change.
+ * ⛔ THE RESTART CONDITION IS THE WHOLE CONTRACT: the unit file changed, or a digest the caller
+ *   listed changed. Nothing else — not a re-run, not an unrelated resource, not `--adopt`.
+ */
+export const settle = async (
+  runner: HostRunner,
+  props: SystemdUnitProps,
+  step: Settle,
+): Promise<SystemdUnitAttributes> => {
+  const wantEnabled = props.enabled !== false;
+  const wantStarted = props.started !== false;
+  const isEnabled =
+    step.status.unitFileState === 'enabled' || step.status.unitFileState === 'enabled-runtime';
+  const undo = async (detail: string): Promise<never> => {
+    // ⚠️ A create that never came up leaves nothing behind; an update keeps the new file and the
+    //   old stored digest, so the next deploy retries.
+    if (step.before === undefined) {
+      await runner.removeFile(step.path).catch(() => undefined);
+      await daemonReload(runner).catch(() => undefined);
+    }
+    throw refuse(props.name, `${detail} The unit is NOT running.`);
+  };
+  try {
+    if (wantEnabled && (!isEnabled || step.changed)) await enableUnit(runner, props.name);
+    if (!wantEnabled && isEnabled) await disableUnit(runner, props.name);
+    const active = step.status.activeState === 'active' || step.status.activeState === 'activating';
+    if (!wantStarted) {
+      if (active) await stopUnit(runner, props.name);
+    } else if (!active) await startUnit(runner, props.name);
+    else if (step.changed || step.configChanged) await restartUnit(runner, props.name);
+  } catch (cause) {
+    return undo(cause instanceof Error ? cause.message : String(cause));
+  }
+  /**
+   * ⚠️ READ BACK, never echo the declaration. Returning `enabled: wantEnabled` because we called
+   *   `enable` would put a CLAIM in state instead of a reading, and the next plan would compare
+   *   the declaration against itself — so a link systemd did not actually make would never show up
+   *   as drift, in either direction.
+   */
+  const after = await showUnit(runner, props.name);
+  if (wantStarted && after.activeState !== 'active' && after.activeState !== 'activating') {
+    return undo(`systemctl reported success but the unit is ${after.activeState}.`);
+  }
+  const settled = attributesOf(props, step.desired, after);
+  if (wantEnabled && !settled.enabled) {
+    return undo(
+      `systemctl enable reported success but systemd calls the unit ` +
+        `${JSON.stringify(after.unitFileState ?? '')}, not enabled.`,
+    );
+  }
+  return settled;
+};

package/src/linux/unit.ts

@@ -0,0 +1,81 @@
+/**
+ * `Systemd.Unit` and `Systemd.Timer` — one systemd unit file and systemd's view of it, declared.
+ *
+ * - create / update — write the unit file atomically, `daemon-reload`, enable or disable, then
+ *   start, stop, or RESTART ONLY when something actually changed (unit-lifecycle.ts settle).
+ * - read — the unit file's SHA-256 plus `systemctl show` (load state, active state, enablement).
+ * - diff — the rendered digest against the stored AND the on-disk one, the declared enablement and
+ *   running state against systemd's, and systemd's own `NeedDaemonReload`.
+ * - replace — only when the unit's name or directory changes, and DELETE FIRST: two unit files for
+ *   one name cannot both be the one systemd reads.
+ * - delete — stop, disable, remove the file, reload.
+ *
+ * ⛔ A DEPLOY NEVER MASS-RESTARTS — see the ⛔ at the top of unit-lifecycle.ts. It is the property
+ *   that lets this family reach a host holding a vault, a clock or a UPS handler.
+ * ⛔ THE UNIT FILE IS NEVER A SECRET (unit-form.ts): it is 0644 and its props sit in state.
+ * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt`. A unit already on the host reads as `Unowned`; adopting
+ *   one that already matches the declaration does not restart it.
+ * ★ TWO RESOURCES, ONE LIFECYCLE. A timer is a unit whose file ends `.timer` and carries a
+ *   `[Timer]` section; splitting the TYPE rather than the code means a plan says which of the two
+ *   a row is, and a `.service` declared as a timer is a refusal instead of a puzzle.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { HostRunnerService } from '../launchd/runner.ts';
+import type { SystemdUnitAttributes, SystemdUnitProps } from './unit-form.ts';
+import { deleteHandler, diffHandler, readHandler, reconcileHandler } from './unit-handlers.ts';
+
+export type { SystemdUnitAttributes, SystemdUnitProps, UnitSection } from './unit-form.ts';
+
+export interface SystemdUnit extends Resource<
+  'Systemd.Unit',
+  SystemdUnitProps,
+  SystemdUnitAttributes
+> {}
+
+export interface SystemdTimer extends Resource<
+  'Systemd.Timer',
+  SystemdUnitProps,
+  SystemdUnitAttributes
+> {}
+
+export const SystemdUnit = Resource<SystemdUnit>('Systemd.Unit');
+export const SystemdTimer = Resource<SystemdTimer>('Systemd.Timer');
+
+export const SystemdUnitProvider = () =>
+  Provider.effect(
+    SystemdUnit,
+    Effect.gen(function* () {
+      const runner = yield* HostRunnerService;
+      return SystemdUnit.Provider.of({
+        /**
+         * ⛔ systemd's unit list is not a list of things this stack owns — it is every vendor,
+         *   package and hand-written unit on the host. Returning them would invite a nuke to stop
+         *   services nothing here declared.
+         */
+        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),
+      });
+    }),
+  );
+
+export const SystemdTimerProvider = () =>
+  Provider.effect(
+    SystemdTimer,
+    Effect.gen(function* () {
+      const runner = yield* HostRunnerService;
+      return SystemdTimer.Provider.of({
+        list: () => Effect.succeed([]),
+        read: ({ olds, output }) => readHandler(runner, olds, output),
+        // ★ `'timer'` is the whole difference: the same lifecycle, refusing a name that is not one.
+        diff: ({ instanceId, news, output }) =>
+          diffHandler(runner, instanceId, news, output, 'timer'),
+        reconcile: (args) => reconcileHandler(runner, args, 'timer'),
+        delete: ({ output }) => deleteHandler(runner, output),
+      });
+    }),
+  );

package/src/netbox/client.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Identity resolution, and the two ways it must refuse.
+ *
+ * ⛔ THE FAILURE THIS GUARDS IS SILENT AND SELF-RENEWING. If an ambiguous match took the first
+ *   row, adopt would bind to it, the next plan would bind to the other, and every plan after that
+ *   would report drift that is not there — while "fixing" it PATCHed one object with the other's
+ *   declaration. Failing loudly is the only outcome an operator can act on.
+ */
+import { describe, expect, test } from 'bun:test';
+import { NetboxError, apiBase, soleMatch } from './client.ts';
+
+describe('soleMatch', () => {
+  test('no candidate is absent, not an error — that is what plans a create', () => {
+    expect(soleMatch([], 'ipam/prefixes 10.0.0.0/24')).toBeUndefined();
+  });
+
+  test('exactly one candidate is the object', () => {
+    expect(soleMatch([{ id: 7 }], 'ipam/prefixes 10.0.0.0/24')).toEqual({ id: 7 });
+  });
+
+  /** ⛔ Two rows means the identity rule is wrong, and the message says which object it was. */
+  test('more than one candidate throws and names the object', () => {
+    expect(() => soleMatch([{ id: 7 }, { id: 8 }], 'ipam/prefixes 10.0.0.0/24')).toThrow(
+      /ipam\/prefixes 10\.0\.0\.0\/24 matched 2 NetBox objects/,
+    );
+  });
+});
+
+describe('the instance origin', () => {
+  /**
+   * ⛔ NO DEFAULT HOSTNAME. A published package that fell back to a loopback address would let a
+   *   consumer who forgot the variable watch every call fail against a machine that is not
+   *   theirs, rather than being told which variable is missing.
+   */
+  test('an unset or blank NETBOX_URL names the variable', () => {
+    const before = process.env['NETBOX_URL'];
+    try {
+      delete process.env['NETBOX_URL'];
+      expect(() => apiBase()).toThrow(/NETBOX_URL is not set/);
+      process.env['NETBOX_URL'] = '   ';
+      expect(() => apiBase()).toThrow(/NETBOX_URL is not set/);
+    } finally {
+      if (before === undefined) delete process.env['NETBOX_URL'];
+      else process.env['NETBOX_URL'] = before;
+    }
+  });
+
+  test('a trailing slash is stripped so paths do not double up', () => {
+    const before = process.env['NETBOX_URL'];
+    try {
+      process.env['NETBOX_URL'] = 'https://netbox.example.com/';
+      expect(apiBase()).toBe('https://netbox.example.com');
+    } finally {
+      if (before === undefined) delete process.env['NETBOX_URL'];
+      else process.env['NETBOX_URL'] = before;
+    }
+  });
+});
+
+describe('NetboxError', () => {
+  /** ⚠️ The status is on the instance, because `absentOn404` folds ONLY 404 and nothing else. */
+  test('it carries the status a caller has to branch on', () => {
+    const error = new NetboxError(404, 'GET', 'ipam/prefixes/', 'Not found.');
+    expect(error.status).toBe(404);
+    expect(error.message).toContain('NetBox GET ipam/prefixes/ -> 404');
+  });
+});