@homeflare/alchemy 0.31.2 → 0.33.0

package/src/linux/container-handlers.ts

@@ -0,0 +1,73 @@
+/**
+ * `Podman.Container`'s four provider handlers, as plain functions over a HostRunner — the same
+ * split as `unit-handlers.ts`, so `container.ts`'s `Provider.of` stays a thin wire-up.
+ */
+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 { ContainerAttributes, ContainerProps } from './container-form.ts';
+import {
+  deleteContainer,
+  diffContainer,
+  readContainer,
+  reconcileContainer,
+} from './container-lifecycle.ts';
+import { assertRenameTarget } from './container-preflight.ts';
+
+export const readHandler = (
+  runner: HostRunner,
+  olds: ContainerProps,
+  output: ContainerAttributes | undefined,
+): Effect.Effect<ContainerAttributes | undefined, Error> =>
+  lift(async () => {
+    const found = await readContainer(runner, olds);
+    if (found === undefined) return undefined;
+    return output === undefined ? Unowned(found) : found;
+  });
+
+export const diffHandler = (
+  runner: HostRunner,
+  instanceId: string,
+  news: Input<ContainerProps>,
+  output: ContainerAttributes | undefined,
+): 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(() => diffContainer(runner, news, output));
+  /**
+   * ⛔ A RENAME MUST BE SEEN EVEN WHILE OTHER PROPS ARE UNRESOLVED — same reason as
+   *   `unit-handlers.ts`'s `diffHandler`: the engine's default for a prop change is `update`, and
+   *   an update under a new name writes the new `.container` file and leaves the old generated
+   *   unit running with nothing in state to ever remove it.
+   */
+  const name = resolvedString(news, 'name');
+  if (name === undefined || name === output.name) return Effect.succeed(undefined);
+  return lift(async () => {
+    await assertRenameTarget(runner, output, name);
+    return { action: 'replace' as const, deleteFirst: true };
+  });
+};
+
+export const reconcileHandler = (
+  runner: HostRunner,
+  args: {
+    fqn: string;
+    instanceId: string;
+    news: ContainerProps;
+    output: ContainerAttributes | undefined;
+  },
+): Effect.Effect<ContainerAttributes, Error> =>
+  Effect.flatMap(adoptsAtApply(args), (adopt) =>
+    lift(() => reconcileContainer(runner, args.news, args.output, adopt)),
+  );
+
+export const deleteHandler = (
+  runner: HostRunner,
+  output: ContainerAttributes,
+): Effect.Effect<void, Error> => lift(() => deleteContainer(runner, output));

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

@@ -0,0 +1,209 @@
+/**
+ * `Podman.Container` against the fake Quadlet host — mirrors `unit-lifecycle.test.ts`'s shape and,
+ * like it, cares most about the NEGATIVE assertions: an adopted container that already matches is
+ * not restarted, a re-run restarts nothing, and a read that fails writes nothing. Generator-failure
+ * rollback and the never-enable guarantee are in container-generator.test.ts; secret refusal is in
+ * container-secrets.test.ts; the CT100 fixture is in container-fixture.test.ts.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeQuadletHost } from './fake-quadlet.ts';
+import { type ContainerProps, containerProblems } from './container-form.ts';
+import {
+  deleteContainer,
+  diffContainer,
+  readContainer,
+  reconcileContainer,
+} from './container-lifecycle.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,
+  service: { restart: 'always', restartSec: '5s' },
+});
+
+const host = () => fakeQuadletHost();
+const verbs = (calls: string[][]) =>
+  calls.filter((call) => call[0] === 'systemctl').map((call) => call[1]);
+
+/** `Map#get`, refused instead of `!`-asserted — a missing fixture is a test bug, not a null we hide. */
+const must = <V>(map: Map<string, V>, key: string): V => {
+  const value = map.get(key);
+  if (value === undefined) throw new Error(`test fixture: nothing at ${key}`);
+  return value;
+};
+
+describe('create', () => {
+  test('writes, reloads, verifies the generator and starts — never enables', async () => {
+    const fake = host();
+    const attrs = await reconcileContainer(fake.runner, props('example/one:1'), undefined);
+    expect(attrs).toMatchObject({
+      active: true,
+      containerPath: PATH,
+      name: NAME,
+      serviceName: SERVICE,
+    });
+    expect(verbs(fake.calls)).toEqual(['show', 'daemon-reload', 'show', '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 = host();
+    const broken = {
+      ...fake.runner,
+      exec: async (argv: readonly string[]) =>
+        argv[1] === 'start'
+          ? { exitCode: 1, stderr: 'Job failed', stdout: '' }
+          : fake.runner.exec(argv),
+    };
+    await expect(reconcileContainer(broken, props('example/one:1'), undefined)).rejects.toThrow(
+      /NOT running/,
+    );
+    expect(fake.files.has(PATH)).toBe(false);
+  });
+});
+
+describe('adoption', () => {
+  /** A fresh fake for the "adopt" half: nothing in state, the file already on disk and generated —
+   *  exactly what a container Podman or another deploy started before this stack existed looks like. */
+  const adoptedHost = async () => {
+    const fake = host();
+    await reconcileContainer(fake.runner, props('example/one:1'), undefined);
+    const adopting = host();
+    adopting.files.set(PATH, must(fake.files, PATH));
+    await adopting.runner.exec(['systemctl', 'daemon-reload']); // the fake generator, as on a real host
+    must(adopting.units, SERVICE).active = true;
+    return adopting;
+  };
+
+  test('a live file that already matches is adopted without a restart', async () => {
+    const adopting = await adoptedHost();
+    const before = adopting.calls.length;
+    const attrs = await reconcileContainer(
+      adopting.runner,
+      props('example/one:1'),
+      undefined,
+      true,
+    );
+    expect(attrs).toMatchObject({ active: true, sourcePath: PATH });
+    const after = verbs(adopting.calls.slice(before));
+    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 adopting = await adoptedHost();
+    const output = await reconcileContainer(
+      adopting.runner,
+      props('example/one:1'),
+      undefined,
+      true,
+    );
+    expect(await diffContainer(adopting.runner, props('example/one:1'), output)).toEqual({
+      action: 'noop',
+    });
+  });
+
+  test('a live file with other content is refused without --adopt', async () => {
+    const fake = host();
+    await reconcileContainer(fake.runner, props('example/one:1'), undefined);
+    const other = host();
+    other.files.set(PATH, must(fake.files, PATH));
+    await expect(
+      reconcileContainer(other.runner, props('example/two:2'), undefined),
+    ).rejects.toThrow(/--adopt/);
+  });
+});
+
+describe('restart happens exactly when something changed', () => {
+  test('a changed image restarts once', async () => {
+    const fake = host();
+    const output = await reconcileContainer(fake.runner, props('example/one:1'), undefined);
+    const before = fake.calls.length;
+    const next = props('example/two:2');
+    expect(await diffContainer(fake.runner, next, output)).toEqual({ action: 'update' });
+    const updated = await reconcileContainer(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 container without rewriting its file', async () => {
+    const fake = host();
+    const first = await reconcileContainer(
+      fake.runner,
+      { ...props('example/one:1'), restartOn: ['aaa'] },
+      undefined,
+    );
+    const next = { ...props('example/one:1'), restartOn: ['bbb'] };
+    expect(await diffContainer(fake.runner, next, first)).toEqual({ action: 'update' });
+    const before = fake.calls.length;
+    await reconcileContainer(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 reconcileContainer(fake.runner, props('example/one:1'), undefined);
+    const before = fake.calls.length;
+    await reconcileContainer(fake.runner, props('example/one:1'), output);
+    const after = verbs(fake.calls.slice(before));
+    expect(after).toEqual(['show', 'show']);
+  });
+
+  test('started: false stops a running container and does not restart it', async () => {
+    const fake = host();
+    const output = await reconcileContainer(fake.runner, props('example/one:1'), undefined);
+    const stopped = await reconcileContainer(
+      fake.runner,
+      { ...props('example/one:1'), started: false },
+      output,
+    );
+    expect(stopped.active).toBe(false);
+    expect(verbs(fake.calls)).toContain('stop');
+    expect(verbs(fake.calls)).not.toContain('restart');
+  });
+});
+
+describe('refusals', () => {
+  test('an unprivileged runner refuses before it touches anything', async () => {
+    const fake = fakeQuadletHost({ euid: 1001 });
+    await expect(
+      reconcileContainer(fake.runner, props('example/one:1'), undefined),
+    ).rejects.toThrow(/never calls sudo/);
+    expect(fake.calls).toHaveLength(0);
+  });
+
+  test('container.image is required', () => {
+    const bad = {
+      ...props('example/one:1'),
+      container: { ...props('example/one:1').container, image: ' ' },
+    };
+    expect(containerProblems(bad).join(' ')).toMatch(/image is required/);
+  });
+
+  test('a directory outside Quadlet’s search path is refused', () => {
+    const elsewhere = { ...props('example/one:1'), directory: '/opt/quadlet' };
+    expect(containerProblems(elsewhere).join(' ')).toMatch(/rootful search path/);
+  });
+});
+
+describe('delete', () => {
+  test('stops, removes the file and reloads — never disables', async () => {
+    const fake = host();
+    const output = await reconcileContainer(fake.runner, props('example/one:1'), undefined);
+    const before = fake.calls.length;
+    await deleteContainer(fake.runner, output);
+    expect(verbs(fake.calls.slice(before))).toEqual(['show', 'stop', 'daemon-reload']);
+    expect(fake.files.has(PATH)).toBe(false);
+    expect(await readContainer(fake.runner, props('example/one:1'))).toBeUndefined();
+  });
+});

package/src/linux/container-lifecycle.ts

@@ -0,0 +1,217 @@
+/**
+ * `Podman.Container`'s read / diff / reconcile / delete as plain async functions over a
+ * HostRunner — same split as `unit-lifecycle.ts`, so the whole lifecycle runs against a fake host
+ * (fake-quadlet.ts) with no real systemd or Podman.
+ *
+ * ⛔ WHAT A DEPLOY DOES NOT DO — same rule `Systemd.Unit` was built around (unit-lifecycle.ts
+ *   header): it NEVER mass-restarts. A container is restarted only when THIS resource's rendered
+ *   `.container` file changed, or a digest the declaration listed in `restartOn` changed.
+ * ★ THE ORDER IS WRITE, RELOAD, VERIFY THE GENERATOR, THEN START OR RESTART. `daemon-reload` is
+ *   where Quadlet turns the `.container` file into `<name>.service` (container-generator.ts) —
+ *   writing it changes nothing on its own, and a write that fails leaves the old file (and its
+ *   already-generated unit) exactly as they were.
+ * ⛔ A GENERATOR FAILURE IS ROLLED BACK, NOT LEFT FOR THE NEXT DEPLOY. `container-generator.ts`'s
+ *   header explains why: `daemon-reload` deletes ALL generator output before regenerating, so a
+ *   `.container` file the generator refuses has NO generated unit at all, even if the file it
+ *   replaced generated one fine. An UPDATE that fails verification restores the previous file and
+ *   reloads again, so the container this resource already promised running never loses its unit; a
+ *   CREATE that fails removes the file it wrote, same as `Systemd.Unit`'s undo.
+ * ⛔ NO ENABLE/DISABLE — see container-generator.ts and container-settle.ts headers.
+ */
+import type { Diff } from 'alchemy/Diff';
+import type { HostRunner } from '../launchd/runner.ts';
+import { UNIT_WRITE, isUnitRunning } from './unit-form.ts';
+import { daemonReload, showUnit, stopUnit } from './systemctl.ts';
+import { needsVerificationReload, verifyGenerated } from './container-generator.ts';
+import {
+  type ContainerAttributes,
+  type ContainerProps,
+  configDigest,
+  containerPathFor,
+  digestOf,
+  refuseContainer,
+  renderContainerFile,
+  serviceNameFor,
+} from './container-form.ts';
+import {
+  assertMayWrite,
+  assertReplaceable,
+  assertUsable,
+  assertValid,
+} from './container-preflight.ts';
+import { attributesOf, settle } from './container-settle.ts';
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** What is on the host now: the `.container` file's digest and the GENERATED unit's status. */
+export const readContainer = async (
+  runner: HostRunner,
+  props: ContainerProps,
+): Promise<ContainerAttributes | undefined> => {
+  const path = containerPathFor(props);
+  const bytes = await runner.readFile(path);
+  const status = await showUnit(runner, serviceNameFor(props));
+  if (bytes === undefined && !status.known) return undefined;
+  const sha = bytes === undefined ? '' : digestOf(decoder.decode(bytes));
+  return attributesOf(
+    props,
+    configDigest(props.restartOn),
+    sha,
+    path,
+    serviceNameFor(props),
+    status,
+  );
+};
+
+export const diffContainer = async (
+  runner: HostRunner,
+  news: ContainerProps,
+  output: ContainerAttributes,
+): Promise<Diff> => {
+  assertValid(news);
+  // ★ The name or directory is the `.container` file's identity: a change is delete-first, same
+  //   reason as `Systemd.Unit` (unit-lifecycle.ts diffUnit) — two files for one name can never
+  //   both be the one Quadlet reads, and here also never both generate the same `.service`.
+  if (news.name !== output.name || containerPathFor(news) !== output.containerPath) {
+    await assertReplaceable(runner, news, output);
+    return { action: 'replace', deleteFirst: true };
+  }
+  const desired = digestOf(renderContainerFile(news));
+  const update = async (): Promise<Diff> => {
+    assertMayWrite(runner, news.name);
+    await runner.checkWrite?.(containerPathFor(news), UNIT_WRITE);
+    return { action: 'update' };
+  };
+  if (desired !== output.containerSha256) return update();
+  if (configDigest(news.restartOn) !== output.configSha256) return update();
+  const live = await readContainer(runner, news);
+  if (live === undefined || live.containerSha256 !== desired) return update();
+  const status = await showUnit(runner, serviceNameFor(news));
+  const wantStarted = news.started !== false;
+  if (isUnitRunning(status.activeState, status.subState, wantStarted) !== wantStarted)
+    return update();
+  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 — same meaning as `Systemd.Unit`'s (unit-lifecycle.ts reconcileUnit).
+ */
+export const reconcileContainer = async (
+  runner: HostRunner,
+  props: ContainerProps,
+  output: ContainerAttributes | undefined,
+  adopt = false,
+): Promise<ContainerAttributes> => {
+  assertValid(props);
+  assertMayWrite(runner, props.name);
+  const path = containerPathFor(props);
+  const serviceName = serviceNameFor(props);
+  const text = renderContainerFile(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.containerPath !== path);
+  if (moved && output !== undefined) await assertReplaceable(runner, props, output);
+  const prior = moved ? undefined : output;
+  if (
+    prior === undefined &&
+    !(adopt && output === undefined) &&
+    liveSha !== undefined &&
+    liveSha !== desired
+  ) {
+    throw refuseContainer(
+      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 deleteContainer(runner, output);
+  const wrote = liveSha !== desired;
+  /**
+   * ⛔ MUST GATE THE RELOAD, NOT ONLY THE RESTART — found on adversarial review. `wrote` and
+   *   `preStatus.needDaemonReload` both describe the GENERATED `<name>.service`'s own staleness;
+   *   neither can see that the SOURCE `.container` file was written by an apply that then crashed
+   *   (ssh drop, reboot) before its `daemon-reload` ran. On the retry: the file already holds
+   *   `desired` (`wrote` is false), and systemd's own flag is unset because the generated unit —
+   *   still built from the OLD content — hasn't changed either. Without `stale` here, no reload
+   *   happens, `verifyGenerated` passes against that stale generation, and `settle` (below) would
+   *   restart the container onto its OLD definition while returning `containerSha256: desired` —
+   *   state then claims the new declaration took effect, permanently and silently, since every
+   *   later diff compares state to itself. `stale` is exactly "the file's content no longer matches
+   *   what THIS resource last recorded as generated", which is the one signal that catches it.
+   *   Test: container-generator.test.ts, "an interrupted apply that crashed before daemon-reload".
+   */
+  const stale = prior !== undefined && prior.containerSha256 !== desired;
+  const preStatus = await showUnit(runner, serviceName);
+  assertUsable(props, preStatus);
+  /**
+   * ⛔ `prior === undefined` (a create, or an adopt) AND `needsVerificationReload` — found on
+   *   adversarial review, the same bug class as `stale` above but for a resource with no prior
+   *   state at all. An INTERRUPTED CREATE (the write landed, the apply crashed before its
+   *   `daemon-reload` ran) retries with `wrote: false` (the file already holds `desired`) and
+   *   `stale: false` (there is no PRIOR state to disagree with) — without this, nothing ever
+   *   reloaded and `verifyGenerated` threw on the still-missing generated unit FOREVER: loud, but
+   *   stuck, since a plain retry changes nothing about that. `needsVerificationReload`
+   *   (container-generator.ts) shares its predicate with `verifyGenerated` itself, so the two can
+   *   never disagree about what counts as already proven. Cost: one extra, idempotent reload on an
+   *   ordinary adoption whose generation was already fine — `daemon-reload` restarts nothing, so
+   *   the never-mass-restart property (`changed`, below) is untouched.
+   *   Test: container-generator.test.ts, "an interrupted CREATE that crashed before daemon-reload".
+   */
+  const needsReload =
+    wrote ||
+    stale ||
+    preStatus.needDaemonReload ||
+    (prior === undefined && needsVerificationReload(path, preStatus));
+  if (wrote) await runner.writeFileAtomic(path, encoder.encode(text), UNIT_WRITE);
+  if (needsReload) await daemonReload(runner);
+  const status = needsReload ? await showUnit(runner, serviceName) : preStatus;
+  try {
+    verifyGenerated(props.name, path, serviceName, status);
+  } catch (cause) {
+    // ⛔ Only a WRITE this reconcile made is worth rolling back — see file header. A file already
+    //   on disk before this reconcile ran (wrote === false) generated nothing NEW to restore to.
+    if (wrote) {
+      if (before === undefined) await runner.removeFile(path).catch(() => undefined);
+      else await runner.writeFileAtomic(path, before, UNIT_WRITE).catch(() => undefined);
+      await daemonReload(runner).catch(() => undefined);
+    }
+    throw cause;
+  }
+  const configChanged = prior !== undefined && prior.configSha256 !== configDigest(props.restartOn);
+  const changed = wrote || stale || preStatus.needDaemonReload;
+  return settle(runner, props, configDigest(props.restartOn), {
+    before,
+    changed,
+    configChanged,
+    desired,
+    path,
+    serviceName,
+    status,
+  });
+};
+
+/**
+ * Stop, remove the `.container` file, reload — clearing the orphaned generated unit. Idempotent.
+ * No `disableUnit`: never enabled through systemctl in the first place (container-settle.ts).
+ */
+export const deleteContainer = async (
+  runner: HostRunner,
+  output: ContainerAttributes,
+): Promise<void> => {
+  assertMayWrite(runner, output.name);
+  const status = await showUnit(runner, output.serviceName);
+  if (status.activeState === 'active' || status.activeState === 'activating') {
+    await stopUnit(runner, output.serviceName);
+  }
+  const stat = await runner.stat(output.containerPath);
+  if (stat !== undefined) {
+    if (stat.kind !== 'file')
+      throw refuseContainer(output.name, `${output.containerPath} is a ${stat.kind}`);
+    await runner.removeFile(output.containerPath);
+  }
+  await daemonReload(runner);
+};

package/src/linux/container-preflight.ts

@@ -0,0 +1,97 @@
+/**
+ * Everything `Podman.Container` checks before it touches the host — split from
+ * container-lifecycle.ts so a reconcile and a plan-time REPLACE run the very same checks, exactly
+ * the reason unit-preflight.ts exists (see that file's header; this mirrors it).
+ *
+ * ★ EVERY CHECK HERE IS READ-ONLY: validation, `systemctl show`, a file read and
+ *   `HostRunner.checkWrite`. Nothing here writes, reloads or drives Podman.
+ */
+import { type HostRunner, canActAsRoot } from '../launchd/runner.ts';
+import { UNIT_WRITE, digestOf } from './unit-form.ts';
+import { type UnitStatus, showUnit } from './systemctl.ts';
+import {
+  type ContainerAttributes,
+  type ContainerProps,
+  containerPathFor,
+  containerProblems,
+  refuseContainer,
+  renderContainerFile,
+  serviceNameFor,
+} from './container-form.ts';
+
+const decoder = new TextDecoder();
+
+/** Throw every refusal at once, so one plan shows the whole list. */
+export const assertValid = (props: ContainerProps): void => {
+  const found = containerProblems(props);
+  if (found.length > 0) throw refuseContainer(props.name, found.join('; '));
+};
+
+/** ⛔ Writing the file and driving systemctl/Podman are root's — refuse up front, not mid-apply. */
+export const assertMayWrite = (runner: HostRunner, name: string): void => {
+  if (canActAsRoot(runner)) return;
+  throw refuseContainer(
+    name,
+    'a Quadlet .container file is root-owned and daemon-reload/systemctl need root. Point the ' +
+      'runner at a destination whose ssh user is root, or provide a privileged HostRunner. This ' +
+      'provider never calls sudo.',
+  );
+};
+
+/**
+ * ⛔ A MASKED GENERATED UNIT IS SOMEONE'S DECISION, NOT DRIFT — same rule as `Systemd.Unit`
+ *   (unit-preflight.ts `assertUsable`). Masking a generated unit is done the ordinary way, by
+ *   symlinking its name to `/dev/null` in a directory Quadlet's generator output does not win
+ *   against (`/etc/systemd/system` outranks `/run/systemd/generator`); unmasking here would
+ *   silently overrule that.
+ */
+export const assertUsable = (props: Pick<ContainerProps, 'name'>, status: UnitStatus): void => {
+  if (status.loadState === 'masked' || status.unitFileState === 'masked') {
+    throw refuseContainer(
+      props.name,
+      `${serviceNameFor(props)} is masked. If that is stale, \`systemctl unmask\` it deliberately, ` +
+        'then redeploy. Nothing was written.',
+    );
+  }
+};
+
+/**
+ * ⛔ A `.container` FILE THIS RESOURCE DOES NOT OWN IS NEVER OVERWRITTEN — same rule and same
+ *   exemption as `unit-preflight.ts`'s `assertUnclaimed`: a file byte-identical to our render is
+ *   this declaration's own leftover, not someone else's.
+ */
+export const assertUnclaimed = async (runner: HostRunner, props: ContainerProps): Promise<void> => {
+  const path = containerPathFor(props);
+  const bytes = await runner.readFile(path);
+  const live = bytes === undefined ? undefined : digestOf(decoder.decode(bytes));
+  if (live !== undefined && live !== digestOf(renderContainerFile(props))) {
+    throw refuseContainer(
+      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.',
+    );
+  }
+};
+
+/** The half of a rename check that needs only the NEW NAME — mirrors `assertRenameTarget`. */
+export const assertRenameTarget = async (
+  runner: HostRunner,
+  old: ContainerAttributes,
+  name: string,
+): Promise<void> => {
+  assertMayWrite(runner, old.name);
+  assertMayWrite(runner, name);
+  assertUsable({ name }, await showUnit(runner, serviceNameFor({ name })));
+};
+
+/** A rename, checked at plan time, before the plan may promise a delete-first replace. */
+export const assertReplaceable = async (
+  runner: HostRunner,
+  next: ContainerProps,
+  old: ContainerAttributes,
+): Promise<void> => {
+  assertValid(next);
+  await assertRenameTarget(runner, old, next.name);
+  await assertUnclaimed(runner, next);
+  await runner.checkWrite?.(containerPathFor(next), UNIT_WRITE);
+};