@homeflare/alchemy 0.5.0 → 0.6.0

package/src/launchd/fake-runner.ts

@@ -0,0 +1,176 @@
+/**
+ * An in-memory host for the tests beside it: a filesystem in a Map and a scripted launchd.
+ *
+ * ⛔ TEST-ONLY. No provider imports this file, it is not on the barrel, and it never touches the
+ *   real filesystem or runs a real program — which is the only way the lifecycle tests can prove
+ *   "bootout before bootstrap" without writing /Library or loading a job.
+ * ★ IT MODELS THE BEHAVIOURS THE PROVIDER DEPENDS ON, as launchctl.ts documents them: `print` of an
+ *   unknown target exits 113; bootstrap of a loaded or disabled label fails; bootout of an absent
+ *   job exits non-zero; a job can linger after bootout (`lingerPrints`); a gui uid with no login
+ *   session answers 112 (`loggedOut`); writes into a root-owned directory, or a chown to another
+ *   uid, need root.
+ */
+import { LAUNCHCTL, NOT_FOUND, NO_DOMAIN } from './launchctl.ts';
+import type { ExecResult, FileStat, HostRunner, HostUser, WriteOptions } from './runner.ts';
+
+type Entry = { bytes: Uint8Array; mode: number; uid: number; gid: number; kind: FileStat['kind'] };
+
+export type FakeOptions = {
+  euid?: number;
+  privileged?: boolean;
+  /** Directories that exist, and their owner uid. */
+  dirs?: Record<string, number>;
+  users?: Record<string, HostUser>;
+  groups?: Record<string, number>;
+};
+
+const ok = (stdout = ''): ExecResult => ({ exitCode: 0, stderr: '', stdout });
+const fail = (exitCode: number, stderr: string): ExecResult => ({ exitCode, stderr, stdout: '' });
+const errno = (code: string, path: string) =>
+  Object.assign(new Error(`${code}: ${path}`), { code });
+const parent = (path: string) => path.slice(0, path.lastIndexOf('/')) || '/';
+
+/** The shape `launchctl print` produced on macOS 27.2 (see launchctl.ts), trimmed. */
+const printBlock = (target: string, pid: number | undefined, lastExit: string) =>
+  [
+    `${target} = {`,
+    '\tactive count = 1',
+    `\tstate = ${pid === undefined ? 'not running' : 'running'}`,
+    '\targuments = {',
+    '\t\t/bin/sh',
+    '}',
+    '\t}',
+    '\tresource coalition = {',
+    '\t\tstate = active',
+    '\t}',
+    ...(pid === undefined ? [] : [`\tpid = ${String(pid)}`]),
+    `\tlast exit code = ${lastExit}`,
+    '}',
+  ].join('\n');
+
+export const fakeRunner = (options: FakeOptions = {}) => {
+  const euid = options.euid ?? 501;
+  const privileged = options.privileged ?? false;
+  const root = privileged || euid === 0;
+  const dirs = new Map(Object.entries(options.dirs ?? {}));
+  const files = new Map<string, Entry>();
+  const calls: string[][] = [];
+  /** target → pid (undefined = loaded, not running). */
+  const loaded = new Map<string, number | undefined>();
+  const disabled = new Set<string>();
+  const state = {
+    lingerPrints: 0,
+    nextPid: 4000,
+    bootstrapFailure: undefined as ExecResult | undefined,
+    /** Returned by bootout in place of success. The job still goes, unless `bootoutKeepsJob`. */
+    bootoutFailure: undefined as ExecResult | undefined,
+    bootoutKeepsJob: false,
+    /** gui uids with no login session: every launchctl call into `gui/<uid>` exits 112. */
+    loggedOut: new Set<number>(),
+  };
+  /** Booted-out targets launchd has not let go of yet → prints left before they vanish. */
+  const lingering = new Map<string, number>();
+
+  const labelIn = (path: string) =>
+    /<key>Label<\/key>\s*<string>([^<]*)<\/string>/.exec(
+      new TextDecoder().decode(files.get(path)?.bytes),
+    )?.[1];
+
+  const launchctl = (args: readonly string[]): ExecResult => {
+    const [sub, first, second] = args;
+    const gui = /^gui\/(\d+)(?:\/|$)/.exec(first ?? '')?.[1];
+    if (gui !== undefined && state.loggedOut.has(Number(gui))) {
+      // The measured shape (launchctl.ts): 112, "Bad request." then the domain line.
+      return fail(NO_DOMAIN, `Bad request.\nCould not find domain for user gui: ${gui}`);
+    }
+    if (sub === 'print' && first !== undefined) {
+      const left = lingering.get(first);
+      if (left !== undefined) {
+        if (left <= 0) {
+          lingering.delete(first);
+          loaded.delete(first);
+        } else lingering.set(first, left - 1);
+      }
+      if (!loaded.has(first)) return fail(NOT_FOUND, `Could not find service "${first}"`);
+      return ok(printBlock(first, loaded.get(first), '(never exited)'));
+    }
+    if (sub === 'print-disabled' && first !== undefined) {
+      const lines = [...disabled]
+        .filter((target) => target.startsWith(`${first}/`))
+        .map((target) => `\t\t"${target.slice(first.length + 1)}" => disabled`);
+      return ok(['\tdisabled services = {', ...lines, '\t}'].join('\n'));
+    }
+    if (sub === 'bootstrap' && first !== undefined && second !== undefined) {
+      if (state.bootstrapFailure !== undefined) return state.bootstrapFailure;
+      const label = labelIn(second);
+      if (label === undefined) return fail(5, 'Bootstrap failed: 5: Input/output error');
+      const target = `${first}/${label}`;
+      if (loaded.has(target) || disabled.has(target))
+        return fail(5, 'Bootstrap failed: 5: Input/output error');
+      state.nextPid += 1;
+      loaded.set(target, state.nextPid);
+      return ok();
+    }
+    if (sub === 'bootout' && first !== undefined) {
+      if (!loaded.has(first) || lingering.has(first))
+        return fail(3, 'Boot-out failed: 3: No such process');
+      if (state.bootoutKeepsJob) return state.bootoutFailure ?? fail(5, 'Boot-out failed: 5');
+      // ⚠️ Model launchd letting go late: the job stays visible for `lingerPrints` more prints.
+      if (state.lingerPrints === 0) loaded.delete(first);
+      else lingering.set(first, state.lingerPrints);
+      return state.bootoutFailure ?? ok();
+    }
+    return fail(64, `fake launchctl: unsupported ${args.join(' ')}`);
+  };
+
+  const runner: HostRunner = {
+    effectiveUid: () => euid,
+    exec: async (argv) => {
+      calls.push([...argv]);
+      if (argv[0] === LAUNCHCTL) return launchctl(argv.slice(1));
+      return fail(127, `fake: no program ${String(argv[0])}`);
+    },
+    lookupGroup: async (nameOrId) => options.groups?.[nameOrId],
+    lookupUser: async (nameOrId) =>
+      options.users?.[nameOrId] ??
+      Object.values(options.users ?? {}).find((user) => String(user.uid) === nameOrId),
+    privileged,
+    readFile: async (path) => files.get(path)?.bytes,
+    removeFile: async (path) => {
+      if (files.has(path) && (dirs.get(parent(path)) ?? 0) !== euid && !root)
+        throw errno('EACCES', path);
+      files.delete(path);
+    },
+    // ★ No real waiting: a lingering job drains one `print` per poll instead.
+    sleep: async () => undefined,
+    stat: async (path) => {
+      const entry = files.get(path);
+      if (entry !== undefined)
+        return {
+          gid: entry.gid,
+          kind: entry.kind,
+          mode: entry.mode,
+          size: entry.bytes.length,
+          uid: entry.uid,
+        };
+      return dirs.has(path)
+        ? { gid: 0, kind: 'directory', mode: 0o755, size: 0, uid: dirs.get(path) ?? 0 }
+        : undefined;
+    },
+    writeFileAtomic: async (path: string, bytes: Uint8Array, write: WriteOptions) => {
+      calls.push(['write', path]);
+      const owner = dirs.get(parent(path));
+      if (owner === undefined) throw errno('ENOENT', parent(path));
+      if (owner !== euid && !root) throw errno('EACCES', path);
+      if (write.uid !== undefined && write.uid !== euid && !root) throw errno('EPERM', path);
+      files.set(path, {
+        bytes,
+        gid: write.gid ?? 20,
+        kind: 'file',
+        mode: write.mode,
+        uid: write.uid ?? euid,
+      });
+    },
+  };
+  return { calls, disabled, dirs, files, loaded, runner, state };
+};

package/src/launchd/host-effect.ts

@@ -0,0 +1,28 @@
+/**
+ * The one place a HostRunner's promises become Effects — plus the one probe of an unresolved
+ * `news` both providers' diffs share.
+ *
+ * ★ The lifecycle files are plain async functions over a HostRunner (see runner.ts for why the
+ *   runner is promise-based), so each provider handler is a single `lift(() => step(runner, …))`.
+ * ⚠️ A thrown Error stays that Error — its message is the refusal a deploy prints. Anything else
+ *   thrown is wrapped, so the failure channel is always an Error with a readable message.
+ */
+import * as Effect from 'effect/Effect';
+
+export const lift = <A>(step: () => Promise<A>): Effect.Effect<A, Error> =>
+  Effect.tryPromise({
+    catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
+    try: step,
+  });
+
+/**
+ * A string prop of a diff's `news`, when that one prop is already resolved; `undefined` while it
+ * is still an Output (a function-typed proxy), an Effect or a Config.
+ * ★ For the identity props a diff must see even when the rest of `news` is unresolved — a plain
+ *   string is resolved by definition, so `typeof` is the whole test.
+ */
+export const resolvedString = (news: unknown, key: string): string | undefined => {
+  if (typeof news !== 'object' || news === null) return undefined;
+  const value = (news as Record<string, unknown>)[key];
+  return typeof value === 'string' ? value : undefined;
+};

package/src/launchd/host-file-form.ts

@@ -0,0 +1,71 @@
+/**
+ * HostFile's props, attributes and validation — the pure half of the provider.
+ *
+ * ⛔ `content` IS NEVER A SECRET. Alchemy stores props unencrypted, so the content of every HostFile
+ *   sits in the state store and in every plan diff. A secret file stays RENDERED BY A SECRET
+ *   RENDERER (openbao-agent templates, on this estate) that fetches it at run time; the stack
+ *   declares only non-secret config, and at most the PATH the renderer writes to.
+ *   secret-tripwire.ts refuses the obvious case (a PEM private key); nothing can catch all of them.
+ */
+import { fileSecretProblems } from './secret-tripwire.ts';
+
+export interface HostFileProps {
+  /** Absolute path. The parent directory must already exist. */
+  path: string;
+  /** UTF-8 text. ⛔ Never a secret — see the file header. */
+  content: string;
+  /** Permission bits. @default 0o644 */
+  mode?: number;
+  /** User name or numeric uid. Omitted: whoever the runner writes as (a rewrite keeps no owner). */
+  owner?: string | number;
+  /** Group name or numeric gid. Omitted: the directory's default group. */
+  group?: string | number;
+}
+
+export interface HostFileAttributes {
+  path: string;
+  /** SHA-256 of the bytes on disk. */
+  sha256: string;
+  mode: number;
+  uid: number;
+  gid: number;
+  size: number;
+}
+
+export const DEFAULT_MODE = 0o644;
+
+const identityProblems = (name: string, value: string | number | undefined): string[] => {
+  if (value === undefined) return [];
+  if (typeof value === 'number') {
+    return Number.isSafeInteger(value) && value >= 0
+      ? []
+      : [`${name} must be a non-negative integer id`];
+  }
+  return /^[A-Za-z_][A-Za-z0-9_.-]*$/.test(value) || /^\d+$/.test(value)
+    ? []
+    : [`${name} ${JSON.stringify(value)} is not a valid user or group name`];
+};
+
+export const fileProblems = (props: HostFileProps): string[] => {
+  const found: string[] = [];
+  const { path } = props;
+  if (!path.startsWith('/')) found.push('path must be absolute');
+  // ★ One spelling per file: `a/./b`, `a//b` and `a/../b` would each be a second resource for the
+  //   same inode, and `..` is how a derived path walks out of the directory it was meant for.
+  if (
+    path.endsWith('/') ||
+    path
+      .split('/')
+      .slice(1)
+      .some((part) => part === '' || part === '.' || part === '..')
+  ) {
+    found.push('path must be normalised (no trailing slash, no empty, "." or ".." segments)');
+  }
+  if (path.includes('\x00')) found.push('path contains NUL');
+  const mode = props.mode ?? DEFAULT_MODE;
+  if (!Number.isSafeInteger(mode) || mode < 0 || mode > 0o7777) found.push('mode must be 0–0o7777');
+  found.push(...identityProblems('owner', props.owner));
+  found.push(...identityProblems('group', props.group));
+  found.push(...fileSecretProblems(props.content));
+  return found;
+};

package/src/launchd/host-file-lifecycle.test.ts

@@ -0,0 +1,198 @@
+/**
+ * HostFile's lifecycle against the fake host (no real writes), plus its validation.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeRunner } from './fake-runner.ts';
+import { type HostFileProps, fileProblems } from './host-file-form.ts';
+import { deleteFile, diffFile, readFileAttributes, reconcileFile } from './host-file-lifecycle.ts';
+
+const PATH = '/etc/example/app.conf';
+const file: HostFileProps = { content: 'listen = 127.0.0.1:9000\n', path: PATH };
+
+const host = (euid = 0) =>
+  fakeRunner({
+    dirs: { '/etc/example': 0, '/Users/someone/cfg': 501 },
+    euid,
+    groups: { staff: 20, wheel: 0 },
+    users: {
+      root: { gid: 0, home: '/var/root', uid: 0 },
+      someone: { gid: 20, home: '/Users/someone', uid: 501 },
+    },
+  });
+
+const writeCount = (calls: string[][]) => calls.filter((call) => call[0] === 'write').length;
+
+describe('create and read back', () => {
+  test('writes the content with the default mode 0644 and returns what is on disk', async () => {
+    const fake = host();
+    const attrs = await reconcileFile(fake.runner, file);
+    expect(attrs).toMatchObject({ mode: 0o644, path: PATH, size: file.content.length, uid: 0 });
+    expect(new TextDecoder().decode(fake.files.get(PATH)?.bytes)).toBe(file.content);
+    expect(await readFileAttributes(fake.runner, PATH)).toEqual(attrs);
+  });
+
+  test('owner and group resolve by name or by id', async () => {
+    const fake = host();
+    const attrs = await reconcileFile(fake.runner, {
+      ...file,
+      group: 'staff',
+      mode: 0o640,
+      owner: 'someone',
+    });
+    expect(attrs).toMatchObject({ gid: 20, mode: 0o640, uid: 501 });
+    const byId = await reconcileFile(fake.runner, { ...file, group: 0, owner: '0' }, attrs);
+    expect(byId).toMatchObject({ gid: 0, uid: 0 });
+  });
+
+  test('an already-matching file is not rewritten', async () => {
+    const fake = host();
+    await reconcileFile(fake.runner, file);
+    await reconcileFile(fake.runner, file);
+    expect(writeCount(fake.calls)).toBe(1);
+  });
+});
+
+describe('diff', () => {
+  test('noop, then update on content, mode or owner drift', async () => {
+    const fake = host();
+    const output = await reconcileFile(fake.runner, { ...file, owner: 'root' });
+    expect(await diffFile(fake.runner, { ...file, owner: 'root' }, output)).toEqual({
+      action: 'noop',
+    });
+    expect(await diffFile(fake.runner, { ...file, content: 'x\n' }, output)).toEqual({
+      action: 'update',
+    });
+    expect(await diffFile(fake.runner, { ...file, mode: 0o600 }, output)).toEqual({
+      action: 'update',
+    });
+    expect(await diffFile(fake.runner, { ...file, owner: 'someone' }, output)).toEqual({
+      action: 'update',
+    });
+    const entry = fake.files.get(PATH);
+    if (entry === undefined) throw new Error('no file');
+    fake.files.set(PATH, { ...entry, mode: 0o666 });
+    expect(await diffFile(fake.runner, { ...file, owner: 'root' }, output)).toEqual({
+      action: 'update',
+    });
+  });
+
+  test('a file deleted behind our back is an update', async () => {
+    const fake = host();
+    const output = await reconcileFile(fake.runner, file);
+    fake.files.delete(PATH);
+    expect(await diffFile(fake.runner, file, output)).toEqual({ action: 'update' });
+  });
+
+  test('a new path is a create-before-delete replace', async () => {
+    const fake = host();
+    const output = await reconcileFile(fake.runner, file);
+    expect(
+      await diffFile(fake.runner, { ...file, path: '/etc/example/other.conf' }, output),
+    ).toEqual({ action: 'replace' });
+  });
+});
+
+describe('refusals', () => {
+  test('chown to another user as a non-root deployer', async () => {
+    const fake = host(501);
+    await expect(
+      reconcileFile(fake.runner, { ...file, owner: 'root', path: '/Users/someone/cfg/a' }),
+    ).rejects.toThrow('only root may chown');
+  });
+
+  test('a symlink or a directory at the path is never replaced', async () => {
+    const fake = host();
+    fake.files.set(PATH, { bytes: new Uint8Array(), gid: 0, kind: 'symlink', mode: 0o755, uid: 0 });
+    await expect(reconcileFile(fake.runner, file)).rejects.toThrow('is a symlink');
+    await expect(reconcileFile(fake.runner, { ...file, path: '/etc/example' })).rejects.toThrow(
+      'is a directory',
+    );
+  });
+
+  test('an unknown owner or group', async () => {
+    const fake = host();
+    await expect(reconcileFile(fake.runner, { ...file, owner: 'nobody-here' })).rejects.toThrow(
+      'no user',
+    );
+    await expect(reconcileFile(fake.runner, { ...file, group: 'nogroup' })).rejects.toThrow(
+      'no group',
+    );
+  });
+
+  test('a missing parent directory surfaces as the error it is', async () => {
+    await expect(reconcileFile(host().runner, { ...file, path: '/nowhere/x' })).rejects.toThrow(
+      'ENOENT',
+    );
+  });
+
+  test.each([
+    ['a relative path', { path: 'etc/x' }, 'absolute'],
+    ['a dot-dot segment', { path: '/etc/../x' }, 'normalised'],
+    ['a trailing slash', { path: '/etc/x/' }, 'normalised'],
+    ['a double slash', { path: '/etc//x' }, 'normalised'],
+    ['a mode above 0o7777', { mode: 0o10000 }, 'mode'],
+    ['a bad owner name', { owner: 'a b' }, 'not a valid user'],
+    ['a negative gid', { group: -1 }, 'non-negative'],
+    // ⚠️ Split so gitleaks' private-key rule does not flag the fixture (secret-tripwire.test.ts).
+    ['a private key', { content: `-----BEGIN EC ${'PRIVATE'} KEY-----\n` }, 'openbao-agent'],
+  ])('%s', (_name, patch, message) => {
+    expect(fileProblems({ ...file, ...patch } as HostFileProps).join('\n')).toContain(message);
+  });
+});
+
+describe('files this resource does not own, and moves', () => {
+  const OTHER = '/etc/example/other.conf';
+
+  test('a different file at a path with no prior state is refused and left alone', async () => {
+    // ★ The new path of a replace: the engine's adoption probe never looked there.
+    const fake = host();
+    fake.files.set(OTHER, {
+      bytes: new Uint8Array([7]),
+      gid: 0,
+      kind: 'file',
+      mode: 0o600,
+      uid: 0,
+    });
+    await expect(reconcileFile(fake.runner, { ...file, path: OTHER })).rejects.toThrow(
+      'not this resource',
+    );
+    expect(fake.files.get(OTHER)?.bytes).toEqual(new Uint8Array([7]));
+  });
+
+  test('a move that reaches reconcile as an update writes the new path, then removes the old', async () => {
+    const fake = host();
+    const output = await reconcileFile(fake.runner, file);
+    const moved = await reconcileFile(fake.runner, { ...file, path: OTHER }, output);
+    expect(moved.path).toBe(OTHER);
+    expect(fake.files.has(OTHER)).toBe(true);
+    expect(fake.files.has(PATH)).toBe(false);
+  });
+
+  test('a create whose read-back fails is rolled back, so the next plan finds nothing', async () => {
+    const fake = host();
+    const runner = {
+      ...fake.runner,
+      writeFileAtomic: (path: string, _bytes: Uint8Array, options: { mode: number }) =>
+        fake.runner.writeFileAtomic(path, new Uint8Array([0]), options),
+    };
+    await expect(reconcileFile(runner, file)).rejects.toThrow('does not match');
+    expect(fake.files.has(PATH)).toBe(false);
+  });
+});
+
+describe('delete', () => {
+  test('removes the file and is idempotent', async () => {
+    const fake = host();
+    const output = await reconcileFile(fake.runner, file);
+    await deleteFile(fake.runner, output);
+    expect(fake.files.has(PATH)).toBe(false);
+    await deleteFile(fake.runner, output);
+  });
+
+  test('refuses once the path has become something other than a file', async () => {
+    const fake = host();
+    const output = await reconcileFile(fake.runner, file);
+    fake.files.set(PATH, { bytes: new Uint8Array(), gid: 0, kind: 'symlink', mode: 0o755, uid: 0 });
+    await expect(deleteFile(fake.runner, output)).rejects.toThrow('not removing');
+  });
+});

package/src/launchd/host-file-lifecycle.ts

@@ -0,0 +1,164 @@
+/**
+ * HostFile's read / diff / reconcile / delete as plain async functions over a HostRunner, so the
+ * lifecycle runs against fake-runner.ts in tests.
+ *
+ * ⛔ SYMLINKS AND DIRECTORIES ARE REFUSED, NOT REPLACED. rename(2) over a symlink replaces the LINK,
+ *   so a path that is a symlink (nix-darwin's /etc entries point into /nix/store) would be quietly
+ *   taken from the tool that owns it — which puts it back, or refuses its next activation. Remove
+ *   the path from its owner first, then declare it here.
+ */
+import type { Diff } from 'alchemy/Diff';
+import {
+  DEFAULT_MODE,
+  type HostFileAttributes,
+  type HostFileProps,
+  fileProblems,
+} from './host-file-form.ts';
+import { sha256Hex } from './job-form.ts';
+import { type HostRunner, canActAsRoot } from './runner.ts';
+
+type Desired = {
+  readonly bytes: Uint8Array;
+  readonly sha256: string;
+  readonly mode: number;
+  readonly uid?: number;
+  readonly gid?: number;
+};
+
+const refuse = (path: string, message: string): Error => new Error(`Host.File ${path}: ${message}`);
+
+const numericId = (value: string | number): number | undefined =>
+  typeof value === 'number' ? value : /^\d+$/.test(value) ? Number(value) : undefined;
+
+/** Validate, then resolve owner/group names to ids through the runner. */
+export const desiredFile = async (runner: HostRunner, props: HostFileProps): Promise<Desired> => {
+  const found = fileProblems(props);
+  if (found.length > 0) throw refuse(props.path, found.join('; '));
+  const bytes = new TextEncoder().encode(props.content);
+  let uid: number | undefined;
+  let gid: number | undefined;
+  if (props.owner !== undefined) {
+    uid = numericId(props.owner) ?? (await runner.lookupUser(String(props.owner)))?.uid;
+    if (uid === undefined) throw refuse(props.path, `no user ${String(props.owner)} on this host`);
+  }
+  if (props.group !== undefined) {
+    gid = numericId(props.group) ?? (await runner.lookupGroup(String(props.group)));
+    if (gid === undefined) throw refuse(props.path, `no group ${String(props.group)} on this host`);
+  }
+  return {
+    bytes,
+    mode: props.mode ?? DEFAULT_MODE,
+    sha256: sha256Hex(bytes),
+    ...(uid === undefined ? {} : { uid }),
+    ...(gid === undefined ? {} : { gid }),
+  };
+};
+
+/** The file as it is now, or `undefined` when nothing is at the path. Non-files read with no digest. */
+export const readFileAttributes = async (
+  runner: HostRunner,
+  path: string,
+): Promise<HostFileAttributes | undefined> => {
+  const stat = await runner.stat(path);
+  if (stat === undefined) return undefined;
+  const bytes = stat.kind === 'file' ? await runner.readFile(path) : undefined;
+  return {
+    gid: stat.gid,
+    mode: stat.mode,
+    path,
+    sha256: bytes === undefined ? '' : sha256Hex(bytes),
+    size: stat.size,
+    uid: stat.uid,
+  };
+};
+
+const matches = (live: HostFileAttributes, want: Desired): boolean =>
+  live.sha256 === want.sha256 &&
+  live.mode === want.mode &&
+  (want.uid === undefined || live.uid === want.uid) &&
+  (want.gid === undefined || live.gid === want.gid);
+
+export const diffFile = async (
+  runner: HostRunner,
+  news: HostFileProps,
+  output: HostFileAttributes,
+): Promise<Diff> => {
+  // ★ Create-before-delete: two paths can hold two files at once, so nothing forces deleteFirst.
+  if (news.path !== output.path) return { action: 'replace' };
+  const want = await desiredFile(runner, news);
+  if (want.sha256 !== output.sha256) return { action: 'update' };
+  const live = await readFileAttributes(runner, news.path);
+  return live !== undefined && matches(live, want) ? { action: 'noop' } : { action: 'update' };
+};
+
+export const reconcileFile = async (
+  runner: HostRunner,
+  props: HostFileProps,
+  output?: HostFileAttributes,
+): Promise<HostFileAttributes> => {
+  const want = await desiredFile(runner, props);
+  // ⛔ NO SILENT SUDO: handing a file to another user is root's call (chown(2)), so say so up front.
+  if (want.uid !== undefined && want.uid !== runner.effectiveUid() && !canActAsRoot(runner)) {
+    throw refuse(
+      props.path,
+      `owner ${String(props.owner)} is not the deploying user; only root may chown. Deploy as root ` +
+        'or through a privileged HostRunner (privileged: true). This provider never calls sudo.',
+    );
+  }
+  const stat = await runner.stat(props.path);
+  if (stat !== undefined && stat.kind !== 'file') {
+    throw refuse(
+      props.path,
+      `is a ${stat.kind}; remove it from whatever owns it before declaring it here`,
+    );
+  }
+  const before = stat === undefined ? undefined : await readFileAttributes(runner, props.path);
+  // ⚠️ An `output` at another path: the engine planned an UPDATE across a move, which it does
+  //   when diff could not see the new path (host-file.ts). Finish it the way a replace would.
+  const moved = output !== undefined && output.path !== props.path;
+  const prior = moved ? undefined : output;
+  /**
+   * ⛔ A FILE THIS RESOURCE DOES NOT OWN IS NEVER OVERWRITTEN. With no prior state for this path,
+   *   the engine's adoption probe has already refused anything it found — except at the new path of
+   *   a replace, where it reads nothing. A path typo there would otherwise overwrite, say, a system
+   *   file that a fresh declaration of the same path would have been refused as `Unowned`.
+   */
+  if (prior === undefined && before !== undefined && !matches(before, want)) {
+    throw refuse(
+      props.path,
+      'already exists and is not this resource. Remove it, or declare it as a new resource and ' +
+        'deploy with --adopt.',
+    );
+  }
+  if (before === undefined || !matches(before, want)) {
+    await runner.writeFileAtomic(props.path, want.bytes, {
+      mode: want.mode,
+      ...(want.uid === undefined ? {} : { uid: want.uid }),
+      ...(want.gid === undefined ? {} : { gid: want.gid }),
+    });
+  }
+  // ⚠️ READ BACK, never echo the declaration: a umask, an ACL or a runner that ignored `uid` shows
+  //   up here as a refusal instead of as a forever-`update`.
+  const after = await readFileAttributes(runner, props.path);
+  if (after === undefined || !matches(after, want)) {
+    // ⚠️ Roll back a CREATE: left behind, the next plan's recovery `read` finds a file with no
+    //   state, reports it `Unowned`, and every later deploy demands --adopt for our own file.
+    if (before === undefined) await runner.removeFile(props.path).catch(() => undefined);
+    throw refuse(
+      props.path,
+      'the write returned but the file on disk does not match the declaration',
+    );
+  }
+  // ★ Create-before-delete, as the replace would have been: the old path goes only once the new
+  //   one is written and verified.
+  if (moved) await deleteFile(runner, output);
+  return after;
+};
+
+/** Remove the file. Idempotent. ⛔ Refuses a path that has since become a symlink or directory. */
+export const deleteFile = async (runner: HostRunner, output: HostFileAttributes): Promise<void> => {
+  const stat = await runner.stat(output.path);
+  if (stat === undefined) return;
+  if (stat.kind !== 'file') throw refuse(output.path, `is now a ${stat.kind}; not removing it`);
+  await runner.removeFile(output.path);
+};