@homeflare/alchemy 0.19.1 → 0.21.0

package/src/launchd/file-converge.ts

@@ -0,0 +1,233 @@
+/**
+ * The one path a declared file's bytes take onto a host, shared by every resource that owns ONE
+ * whole file: `Host.File` (text it was handed) and `Release.Binary` (bytes it downloaded and
+ * verified). Read, diff, converge and delete, as plain async functions over a HostRunner.
+ *
+ * ★ EXTRACTED FROM host-file-lifecycle.ts, NOT COPIED (2026-09-22). The ownership rules below — a
+ *   file this resource does not own is never overwritten, a move onto an occupied path stays
+ *   refused, a failed create is rolled back — were red-teamed on Host.File (docs/ownership.md). A
+ *   second resource that writes a whole file gets them by calling this, so a fix lands in both.
+ * ★ THE BYTES ARE ASKED FOR ONLY WHEN A WRITE IS DUE (`bytesFor`). Host.File has them already; a
+ *   binary has only a pinned digest until it downloads, and a host whose file already matches
+ *   must not cost a 120 MB download to prove it.
+ * ⛔ 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 { leaveOldPath, oneFile } from './file-identity.ts';
+import type { HostFileAttributes } from './host-file-form.ts';
+import { sha256Hex } from './job-form.ts';
+import { type HostRunner, type WriteOptions, canActAsRoot } from './runner.ts';
+
+/** What a whole file must be: where, which bytes (by digest), which mode and owner. */
+export type FileTarget = {
+  readonly path: string;
+  readonly sha256: string;
+  readonly mode: number;
+  readonly uid?: number;
+  readonly gid?: number;
+};
+
+/** A family's refusal: `<Type> <path>: <message>`, so a deploy log names the resource that said no. */
+export type Refuse = (path: string, message: string) => Error;
+
+const numericId = (value: string | number): number | undefined =>
+  typeof value === 'number' ? value : /^\d+$/.test(value) ? Number(value) : undefined;
+
+/** Resolve a declared owner and group (names or ids) to ids through the runner. */
+export const resolveIds = async (
+  runner: HostRunner,
+  declared: { readonly owner?: string | number; readonly group?: string | number },
+  path: string,
+  refuse: Refuse,
+): Promise<{ uid?: number; gid?: number }> => {
+  let uid: number | undefined;
+  let gid: number | undefined;
+  if (declared.owner !== undefined) {
+    uid = numericId(declared.owner) ?? (await runner.lookupUser(String(declared.owner)))?.uid;
+    if (uid === undefined) throw refuse(path, `no user ${String(declared.owner)} on this host`);
+  }
+  if (declared.group !== undefined) {
+    gid = numericId(declared.group) ?? (await runner.lookupGroup(String(declared.group)));
+    if (gid === undefined) throw refuse(path, `no group ${String(declared.group)} on this host`);
+  }
+  return { ...(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,
+  };
+};
+
+export const writeOptionsOf = (want: FileTarget): WriteOptions => ({
+  mode: want.mode,
+  ...(want.uid === undefined ? {} : { uid: want.uid }),
+  ...(want.gid === undefined ? {} : { gid: want.gid }),
+});
+
+export const fileMatches = (live: HostFileAttributes, want: FileTarget): boolean =>
+  live.sha256 === want.sha256 &&
+  live.mode === want.mode &&
+  (want.uid === undefined || live.uid === want.uid) &&
+  (want.gid === undefined || live.gid === want.gid);
+
+/**
+ * ★ A PLAN THAT WILL WRITE ASKS THE RUNNER FIRST (`checkWrite`, when it has one): sudoRunner's
+ *   refusals — a setuid or group-writable root file, a directory under a prefix another user may
+ *   change — then fail the plan, before any resource is applied, instead of halfway through it.
+ */
+export const diffTarget = async (
+  runner: HostRunner,
+  want: FileTarget,
+  output: HostFileAttributes,
+): Promise<Diff> => {
+  const writes = async (diff: Diff): Promise<Diff> => {
+    await runner.checkWrite?.(want.path, writeOptionsOf(want));
+    return diff;
+  };
+  // ★ Create-before-delete: two paths can hold two files at once, so nothing forces deleteFirst.
+  // ⛔ …unless the two paths are ONE file (file-identity.ts). That is a respelling, not a move: a
+  //   replace would let Phase 2 delete the old generation's path, which is the new one's file. An
+  //   update records the new spelling, and convergeFile keeps the file.
+  if (want.path !== output.path) {
+    const same = await oneFile(runner, want.path, output.path);
+    return writes({ action: same === true ? 'update' : 'replace' });
+  }
+  if (want.sha256 !== output.sha256) return writes({ action: 'update' });
+  const live = await readFileAttributes(runner, want.path);
+  return live !== undefined && fileMatches(live, want)
+    ? { action: 'noop' }
+    : writes({ action: 'update' });
+};
+
+export type Converge = {
+  readonly want: FileTarget;
+  /** The owner as declared (a name or an id), for the chown refusal's wording. */
+  readonly owner?: string | number | undefined;
+  /** The bytes to write, asked for only when a write is due; `before` is what is there now. */
+  readonly bytesFor: (before: HostFileAttributes | undefined) => Promise<Uint8Array>;
+  readonly refuse: Refuse;
+};
+
+/**
+ * Make the file at `want.path` match `want`, and return it as read back.
+ *
+ * `adopt` is whether adoption is on AND this apply is a create or an unfinished generation of our
+ * own (ownership/adopt.ts adoptsAtApply). It lets such a generation take over a file already at the
+ * path — the takeover the plan's probe would have allowed, had it run. ⛔ A move onto an occupied
+ *   path stays refused, both ways the engine drives one: an `update` across the move (`moved`,
+ *   below), and a fresh replace's new generation, which the caller never marks adoptable (its
+ *   `output` is undefined too, so this function cannot tell it from a create by itself).
+ */
+export const convergeFile = async (
+  runner: HostRunner,
+  spec: Converge,
+  output?: HostFileAttributes,
+  adopt = false,
+): Promise<HostFileAttributes> => {
+  const { want, refuse } = spec;
+  const path = want.path;
+  // ⛔ 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(
+      path,
+      `owner ${String(spec.owner)} is not the deploying user; only root may chown. Deploy as root ` +
+        'or through a privileged HostRunner (sudoRunner() with this path under a prefix). This ' +
+        'provider never calls sudo itself.',
+    );
+  }
+  const stat = await runner.stat(path);
+  if (stat !== undefined && stat.kind !== 'file') {
+    throw refuse(
+      path,
+      `is a ${stat.kind}; remove it from whatever owns it before declaring it here`,
+    );
+  }
+  const before = stat === undefined ? undefined : await readFileAttributes(runner, 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.
+  //   ★ A respelling of ONE file (file-identity.ts) still counts as moved here, so a file there
+  //   that does not match is refused below — never rewritten in place under the old spelling's pins.
+  const moved = output !== undefined && output.path !== 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 where it never
+   *   looked: the new path of a replace, and a create whose props still held an Output at plan
+   *   time. 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`. ★ With adoption on, a
+   *   create takes it over, as the probe would have let it (decided 2026-09-21).
+   */
+  const takeOver = adopt && output === undefined;
+  if (prior === undefined && before !== undefined && !fileMatches(before, want) && !takeOver) {
+    throw refuse(
+      path,
+      'already exists and is not this resource. Remove it, or declare it as a new resource and ' +
+        'deploy with --adopt.',
+    );
+  }
+  if (before === undefined || !fileMatches(before, want)) {
+    const bytes = await spec.bytesFor(before);
+    // ⛔ THE ONE WRITER NEVER WRITES BYTES THAT ARE NOT THE DECLARED ONES. Host.File's always are;
+    //   a supplier that verifies elsewhere (a download) is held to the same digest here, last.
+    if (sha256Hex(bytes) !== want.sha256) {
+      throw refuse(path, `the bytes to write do not hash to ${want.sha256}. Nothing was written.`);
+    }
+    await runner.writeFileAtomic(path, bytes, writeOptionsOf(want));
+  }
+  // ⚠️ 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`.
+  // ⚠️ 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. ⛔ Also when
+  //   the read-back THROWS: MEASURED 2026-09-22, a 0111 binary written as a non-root operator read
+  //   back EACCES and stayed, and every later plan's probe failed with the same EACCES.
+  const rollBack = async () => {
+    if (before === undefined) await runner.removeFile(path).catch(() => undefined);
+  };
+  const after = await readFileAttributes(runner, path).catch(async (cause: unknown) => {
+    await rollBack();
+    throw refuse(path, `the write returned but reading it back failed: ${String(cause)}`);
+  });
+  if (after === undefined || !fileMatches(after, want)) {
+    await rollBack();
+    throw refuse(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 — and ⛔ never when the old path IS this file (file-identity.ts).
+  if (moved)
+    await leaveOldPath(
+      runner,
+      output.path,
+      path,
+      () => removeWholeFile(runner, output, refuse),
+      refuse,
+    );
+  return after;
+};
+
+/** Remove the file. Idempotent. ⛔ Refuses a path that has since become a symlink or directory. */
+export const removeWholeFile = async (
+  runner: HostRunner,
+  output: HostFileAttributes,
+  refuse: Refuse,
+): 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);
+};

package/src/launchd/file-identity.ts

@@ -0,0 +1,69 @@
+/**
+ * Whether two paths name ONE file — the question a move must answer before it deletes its old
+ * path, and a plan before it answers `replace`.
+ *
+ * 🔴 MEASURED 2026-09-22 (release/binary-alias.test.ts, localRunner over a real temp directory,
+ *   through Alchemy's own Plan and Apply): a Release.Binary whose directory was respelled to
+ *   another path for the SAME file — through a symlinked parent (`/tmp` → `/private/tmp`, `/etc`
+ *   → `/private/etc`), or by case alone on case-insensitive APFS, macOS's default — planned a
+ *   `replace`. The new generation took the file already there as its own (same bytes, same mode:
+ *   file-converge.ts's resume rule), then Phase 2 deleted the old generation's path, which was that
+ *   same file. The deploy SUCCEEDED and the binary was gone. The `update` route lost it in one step:
+ *   convergeFile's move removed the old path after "writing" the new one. Host.File shares both.
+ * ★ IDENTITY, NOT SPELLING. Case-folding the strings would be wrong on a case-sensitive volume and
+ *   blind to a symlinked parent; device and inode from lstat are what the kernel itself compares.
+ * ⚠️ A HARD LINK also shares an inode. At the old path of a move it is therefore kept, not removed:
+ *   one stray link left behind, rather than the risk of deleting the file just verified.
+ */
+import type { FileStat, HostRunner } from './runner.ts';
+
+/**
+ * `true` when both entries exist and are one file; `false` when either is absent or they differ;
+ * `undefined` when the runner reported no identity, so nobody can tell (fakes, custom runners).
+ */
+export const sameEntry = (
+  a: FileStat | undefined,
+  b: FileStat | undefined,
+): boolean | undefined => {
+  if (a === undefined || b === undefined) return false;
+  if (a.dev === undefined || a.ino === undefined || b.dev === undefined || b.ino === undefined) {
+    return undefined;
+  }
+  return a.dev === b.dev && a.ino === b.ino;
+};
+
+/** Whether `a` and `b` are one file on this host right now. Equal strings always are. */
+export const oneFile = async (
+  runner: HostRunner,
+  a: string,
+  b: string,
+): Promise<boolean | undefined> => {
+  if (a === b) return true;
+  const [left, right] = await Promise.all([runner.stat(a), runner.stat(b)]);
+  return sameEntry(left, right);
+};
+
+/**
+ * The last step of a move: `remove` the old path unless it is the file just verified at `path`.
+ * ⚠️ A runner that reports no identity cannot be asked beforehand, so `path` is checked after: a
+ *   file lost to a respelling then fails the deploy instead of reporting success.
+ */
+export const leaveOldPath = async (
+  runner: HostRunner,
+  oldPath: string,
+  path: string,
+  remove: () => Promise<void>,
+  refuse: (path: string, message: string) => Error,
+): Promise<void> => {
+  const same = await oneFile(runner, oldPath, path);
+  if (same === true) return;
+  await remove();
+  if (same === undefined && (await runner.stat(path)) === undefined) {
+    throw refuse(
+      path,
+      `removing the old path ${oldPath} removed this file too: they are one file under two ` +
+        'spellings (a symlinked parent, or case on a case-insensitive volume). Deploy again to ' +
+        'reinstall it, and keep one spelling.',
+    );
+  }
+};

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

@@ -0,0 +1,65 @@
+/**
+ * Host.File's diff while `content` is still an Output, over the REAL localRunner in a fresh temp
+ * directory: a new path is a replace, unless it is the old file under another spelling
+ * (file-identity.ts), where a replace's Phase 2 would delete the file the new generation took.
+ *
+ * 🔴 The respelled case answered `replace` before the fix (2026-09-22). Nothing outside `mkdtemp`
+ *   is touched; the diff only reads.
+ */
+import { afterEach, beforeEach, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { HostFile, HostFileProvider } from './host-file.ts';
+import { localRunner } from './local-runner.ts';
+import { hostRunnerLayer } from './runner.ts';
+
+let tmp = '';
+beforeEach(async () => {
+  tmp = await mkdtemp(join(tmpdir(), 'hf-file-alias-'));
+  await mkdir(join(tmp, 'real'));
+  await writeFile(join(tmp, 'real', 'a.conf'), 'x');
+  await symlink(join(tmp, 'real'), join(tmp, 'link'));
+});
+afterEach(async () => {
+  await rm(tmp, { force: true, recursive: true });
+});
+
+const diffTo = (path: string) => {
+  const output = {
+    gid: 0,
+    mode: 0o644,
+    path: join(tmp, 'real', 'a.conf'),
+    sha256: '',
+    size: 1,
+    uid: 0,
+  };
+  const news = { content: Effect.succeed('x'), path } as never;
+  return Effect.runPromise(
+    Effect.gen(function* () {
+      const diff = (yield* HostFile.Provider).diff;
+      if (diff === undefined) throw new Error('Host.File has no diff');
+      return yield* diff({
+        bindings: [] as never,
+        fqn: 'stack/conf',
+        id: 'conf',
+        instanceId: 'i-1',
+        newBindings: [] as never,
+        news,
+        oldBindings: [] as never,
+        olds: { content: 'x', path: output.path },
+        output,
+      } as never);
+    }).pipe(Effect.provide(HostFileProvider().pipe(Layer.provide(hostRunnerLayer(localRunner()))))),
+  );
+};
+
+test('another file is still a replace', async () => {
+  expect(await diffTo(join(tmp, 'real', 'b.conf'))).toEqual({ action: 'replace' });
+});
+
+test('⛔ the same file through a symlinked parent is left to the engine (an update)', async () => {
+  expect(await diffTo(join(tmp, 'link', 'a.conf'))).toBeUndefined();
+});

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

@@ -34,7 +34,8 @@ export interface HostFileAttributes {
 
 export const DEFAULT_MODE = 0o644;
 
-const identityProblems = (name: string, value: string | number | undefined): string[] => {
+/** A user or group as declared: a non-negative id, or a name the host could have. */
+export const identityProblems = (name: string, value: string | number | undefined): string[] => {
   if (value === undefined) return [];
   if (typeof value === 'number') {
     return Number.isSafeInteger(value) && value >= 0

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

@@ -2,12 +2,19 @@
  * 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.
+ * ★ THE CONVERGENCE ITSELF IS file-converge.ts, shared with every resource that owns one whole file
+ *   (Release.Binary is the second). What stays here is what makes a HOST FILE: text content, its
+ *   validation (never a secret — host-file-form.ts), and the refusal wording `Host.File <path>: …`.
+ * ⛔ SYMLINKS AND DIRECTORIES ARE REFUSED, NOT REPLACED — see file-converge.ts for why.
  */
 import type { Diff } from 'alchemy/Diff';
+import {
+  type FileTarget,
+  convergeFile,
+  diffTarget,
+  removeWholeFile,
+  resolveIds,
+} from './file-converge.ts';
 import {
   DEFAULT_MODE,
   type HostFileAttributes,
@@ -15,106 +22,38 @@ import {
   fileProblems,
 } from './host-file-form.ts';
 import { sha256Hex } from './job-form.ts';
-import { type HostRunner, type WriteOptions, canActAsRoot } from './runner.ts';
+import type { HostRunner } from './runner.ts';
 
-type Desired = {
-  readonly bytes: Uint8Array;
-  readonly sha256: string;
-  readonly mode: number;
-  readonly uid?: number;
-  readonly gid?: number;
-};
+export { readFileAttributes } from './file-converge.ts';
 
-const refuse = (path: string, message: string): Error => new Error(`Host.File ${path}: ${message}`);
+type Desired = FileTarget & { readonly bytes: Uint8Array };
 
-const numericId = (value: string | number): number | undefined =>
-  typeof value === 'number' ? value : /^\d+$/.test(value) ? Number(value) : undefined;
+const refuse = (path: string, message: string): Error => new Error(`Host.File ${path}: ${message}`);
 
 /** 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,
+    path: props.path,
     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,
+    ...(await resolveIds(runner, props, props.path, refuse)),
   };
 };
 
-const writeOptionsOf = (want: Desired): WriteOptions => ({
-  mode: want.mode,
-  ...(want.uid === undefined ? {} : { uid: want.uid }),
-  ...(want.gid === undefined ? {} : { gid: want.gid }),
-});
-
-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);
-
-/**
- * ★ A PLAN THAT WILL WRITE ASKS THE RUNNER FIRST (`checkWrite`, when it has one): sudoRunner's
- *   refusals — a setuid or group-writable root file, a directory under a prefix another user may
- *   change — then fail the plan, before any resource is applied, instead of halfway through it.
- */
+/** Declared digest, mode and owner against state and the live file — see diffTarget. */
 export const diffFile = async (
   runner: HostRunner,
   news: HostFileProps,
   output: HostFileAttributes,
-): Promise<Diff> => {
-  const want = await desiredFile(runner, news);
-  const writes = async (diff: Diff): Promise<Diff> => {
-    await runner.checkWrite?.(news.path, writeOptionsOf(want));
-    return diff;
-  };
-  // ★ Create-before-delete: two paths can hold two files at once, so nothing forces deleteFirst.
-  if (news.path !== output.path) return writes({ action: 'replace' });
-  if (want.sha256 !== output.sha256) return writes({ action: 'update' });
-  const live = await readFileAttributes(runner, news.path);
-  return live !== undefined && matches(live, want)
-    ? { action: 'noop' }
-    : writes({ action: 'update' });
-};
+): Promise<Diff> => diffTarget(runner, await desiredFile(runner, news), output);
 
 /**
- * `adopt` is whether adoption is on AND this apply is a create or an unfinished generation of our
- * own (ownership/adopt.ts adoptsAtApply). It lets such a generation take over a file already at the
- * path — the takeover the plan's probe would have allowed, had it run. ⛔ A move onto an occupied
- *   path stays refused, both ways the engine drives one: an `update` across the move (`moved`,
- *   below), and a fresh replace's new generation, which the caller never marks adoptable (its
- *   `output` is undefined too, so this function cannot tell it from a create by itself).
+ * Write the declared text, unless the file already matches. `adopt` is adoptsAtApply's answer;
+ * what it may and may not take over is convergeFile's ⛔.
  */
 export const reconcileFile = async (
   runner: HostRunner,
@@ -123,68 +62,10 @@ export const reconcileFile = async (
   adopt = false,
 ): 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 (sudoRunner() with this path under a prefix). This ' +
-        'provider never calls sudo itself.',
-    );
-  }
-  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 where it never
-   *   looked: the new path of a replace, and a create whose props still held an Output at plan
-   *   time. 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`. ★ With adoption on, a
-   *   create takes it over, as the probe would have let it (decided 2026-09-21).
-   */
-  const takeOver = adopt && output === undefined;
-  if (prior === undefined && before !== undefined && !matches(before, want) && !takeOver) {
-    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, writeOptionsOf(want));
-  }
-  // ⚠️ 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;
+  const spec = { bytesFor: async () => want.bytes, owner: props.owner, refuse, want };
+  return convergeFile(runner, spec, output, adopt);
 };
 
 /** 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);
-};
+export const deleteFile = (runner: HostRunner, output: HostFileAttributes): Promise<void> =>
+  removeWholeFile(runner, output, refuse);

package/src/launchd/host-file.ts

@@ -21,6 +21,7 @@ import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import { adoptsAtApply } from '../ownership/adopt.ts';
 import { noteUnfinished } from '../ownership/resume.ts';
+import { oneFile } from './file-identity.ts';
 import { lift, resolvedString } from './host-effect.ts';
 import type { HostFileAttributes, HostFileProps } from './host-file-form.ts';
 import { deleteFile, diffFile, readFileAttributes, reconcileFile } from './host-file-lifecycle.ts';
@@ -54,9 +55,14 @@ export const HostFileProvider = () =>
           // ⛔ A new path is a replace even while `content` is unresolved (an Output templated in):
           //   the engine's default would be an update, which writes the new path and never
           //   removes the old one. reconcileFile also defends, for a path that is an Output.
+          //   ⛔ Unless the new path is the old FILE under another spelling (file-identity.ts):
+          //   a replace's Phase 2 would delete it. The update then records the new spelling.
           const path = resolvedString(news, 'path');
-          return Effect.succeed(
-            path !== undefined && path !== output.path ? { action: 'replace' as const } : undefined,
+          if (path === undefined || path === output.path) return Effect.succeed(undefined);
+          return lift(async () =>
+            (await oneFile(runner, path, output.path)) === true
+              ? undefined
+              : { action: 'replace' as const },
           );
         },
 

package/src/launchd/local-runner.test.ts

@@ -3,7 +3,7 @@
  * outside `mkdtemp`; the only programs it spawns are echo/false and a read-only user lookup.
  */
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
-import { mkdtemp, readdir, rm, stat, symlink, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, readdir, rm, stat, symlink, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { localRunner } from './local-runner.ts';
@@ -80,6 +80,17 @@ describe('read, stat, remove', () => {
     expect((await runner.stat(dir))?.kind).toBe('directory');
   });
 
+  test('stat carries identity: one file under two spellings has one dev and ino', async () => {
+    await mkdir(join(dir, 'real'));
+    await writeFile(join(dir, 'real', 'f'), 'x');
+    await symlink(join(dir, 'real'), join(dir, 'link'));
+    const [a, b] = await Promise.all(
+      [join(dir, 'real', 'f'), join(dir, 'link', 'f')].map((p) => runner.stat(p)),
+    );
+    expect(a?.ino).toBeNumber();
+    expect([b?.dev, b?.ino]).toEqual([a?.dev, a?.ino]);
+  });
+
   test('readFile returns the bytes; removeFile is idempotent', async () => {
     await writeFile(join(dir, 'f'), 'hello');
     expect(new TextDecoder().decode(await runner.readFile(join(dir, 'f')))).toBe('hello');

package/src/launchd/local-runner.ts

@@ -130,7 +130,9 @@ export const localRunner = (options: LocalRunnerOptions = {}): HostRunner => {
       try {
         const stats = await lstat(path);
         return {
+          dev: stats.dev,
           gid: stats.gid,
+          ino: stats.ino,
           kind: kindOf(stats),
           mode: stats.mode & 0o7777,
           size: stats.size,