@homeflare/alchemy 0.15.0 → 0.19.1

package/src/linux/remote-file-lifecycle.test.ts

@@ -0,0 +1,191 @@
+/**
+ * RemoteFile against the fake Linux host (no ssh, no real writes): whole-file mode, region mode,
+ * drift detection and the ownership refusals.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeLinuxHost } from './fake-linux-host.ts';
+import { fileProblems } from './remote-file-form.ts';
+import {
+  deleteFile,
+  diffFile,
+  readFileAttributes,
+  reconcileFile,
+} from './remote-file-lifecycle.ts';
+
+const PATH = '/etc/example/app.conf';
+const props = { content: 'listen = 127.0.0.1:9000\n', path: PATH };
+const decode = (bytes: Uint8Array | undefined) => new TextDecoder().decode(bytes);
+
+const host = (euid = 0) =>
+  fakeLinuxHost({
+    dirs: { '/etc': 0, '/etc/example': 0, '/home/someone': 1001 },
+    euid,
+    groups: { root: 0, staff: 50 },
+    users: {
+      root: { gid: 0, home: '/root', uid: 0 },
+      someone: { gid: 1001, home: '/home/someone', uid: 1001 },
+    },
+  });
+
+const writes = (calls: string[][]) => calls.filter((call) => call[0] === 'write').length;
+
+describe('whole-file mode', () => {
+  test('writes with the default mode and returns what is on the host', async () => {
+    const fake = host();
+    const attrs = await reconcileFile(fake.runner, props);
+    expect(attrs).toMatchObject({ mode: 0o644, path: PATH, size: props.content.length, uid: 0 });
+    expect(decode(fake.files.get(PATH)?.bytes)).toBe(props.content);
+  });
+
+  test('an already-matching file is not rewritten', async () => {
+    const fake = host();
+    const first = await reconcileFile(fake.runner, props);
+    await reconcileFile(fake.runner, props, first);
+    expect(writes(fake.calls)).toBe(1);
+  });
+
+  test('mode and owner drift is detected, not just content', async () => {
+    const fake = host();
+    const output = await reconcileFile(fake.runner, { ...props, mode: 0o640 });
+    expect(await diffFile(fake.runner, { ...props, mode: 0o640 }, output)).toEqual({
+      action: 'noop',
+    });
+    // A hand `chmod` on the host, with the content untouched.
+    const entry = fake.files.get(PATH);
+    if (entry !== undefined) entry.mode = 0o666;
+    expect(await diffFile(fake.runner, { ...props, mode: 0o640 }, output)).toEqual({
+      action: 'update',
+    });
+    const fixed = await reconcileFile(fake.runner, { ...props, mode: 0o640 }, output);
+    expect(fixed.mode).toBe(0o640);
+  });
+
+  test('owner and group resolve by name, and a foreign owner needs root', async () => {
+    const fake = host();
+    const owned = await reconcileFile(fake.runner, { ...props, group: 'staff', owner: 'someone' });
+    expect(owned).toMatchObject({ gid: 50, uid: 1001 });
+    const unprivileged = host(1001);
+    await expect(
+      reconcileFile(unprivileged.runner, { ...props, owner: 'root', path: '/home/someone/x' }),
+    ).rejects.toThrow(/only root may chown/);
+  });
+
+  test('a file that is not this resource is refused unless adoption is on', async () => {
+    const fake = host();
+    await fake.runner.writeFileAtomic(PATH, new TextEncoder().encode('someone else\n'), {
+      mode: 0o644,
+    });
+    await expect(reconcileFile(fake.runner, props)).rejects.toThrow(/deploy --adopt/);
+    const adopted = await reconcileFile(fake.runner, props, undefined, true);
+    expect(adopted.sha256).not.toBe('');
+  });
+
+  test('delete removes the file and is idempotent', async () => {
+    const fake = host();
+    const attrs = await reconcileFile(fake.runner, props);
+    await deleteFile(fake.runner, attrs);
+    await deleteFile(fake.runner, attrs);
+    expect(fake.files.has(PATH)).toBe(false);
+  });
+});
+
+describe('region mode', () => {
+  const VENDOR = '# vendor ruleset\nanchor "system"\nrule one\n';
+  const region = { name: 'homeflare' };
+  const block = { content: 'anchor "declared"\n', path: '/etc/vendor.conf', region };
+
+  const withVendor = () => {
+    const fake = host();
+    fake.files.set('/etc/vendor.conf', {
+      bytes: new TextEncoder().encode(VENDOR),
+      gid: 0,
+      kind: 'file',
+      mode: 0o600,
+      uid: 0,
+    });
+    return fake;
+  };
+
+  test('editing the block leaves the rest of the file byte-identical', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    const after = decode(fake.files.get('/etc/vendor.conf')?.bytes);
+    expect(after.startsWith(VENDOR)).toBe(true);
+    await reconcileFile(fake.runner, { ...block, content: 'anchor "changed"\n' }, output);
+    expect(decode(fake.files.get('/etc/vendor.conf')?.bytes).startsWith(VENDOR)).toBe(true);
+  });
+
+  test("the other owner's mode and uid are preserved, never re-declared", async () => {
+    const fake = withVendor();
+    await reconcileFile(fake.runner, block);
+    expect(fake.files.get('/etc/vendor.conf')?.mode).toBe(0o600);
+  });
+
+  test('a change anywhere else in the file is not this resource’s drift', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    const edited = `${decode(fake.files.get('/etc/vendor.conf')?.bytes)}rule two\n`;
+    fake.files.set('/etc/vendor.conf', {
+      bytes: new TextEncoder().encode(edited),
+      gid: 0,
+      kind: 'file',
+      mode: 0o600,
+      uid: 0,
+    });
+    expect(await diffFile(fake.runner, block, output)).toEqual({ action: 'noop' });
+  });
+
+  test('delete removes only the block', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    await deleteFile(fake.runner, output);
+    expect(decode(fake.files.get('/etc/vendor.conf')?.bytes)).toBe(VENDOR);
+  });
+
+  test('a missing file is a refusal, because a typo is likelier than an intention', async () => {
+    const fake = host();
+    await expect(
+      reconcileFile(fake.runner, { ...block, path: '/etc/example/absent.conf' }),
+    ).rejects.toThrow(/does not create the file it lives in/);
+    const created = await reconcileFile(fake.runner, {
+      ...block,
+      create: true,
+      path: '/etc/example/absent.conf',
+    });
+    expect(created.region).toEqual(region);
+  });
+
+  test('mode and owner without create are refused at validation', () => {
+    expect(fileProblems({ ...block, mode: 0o600 })).toHaveLength(1);
+    expect(fileProblems({ ...block, create: true, mode: 0o600 })).toEqual([]);
+  });
+
+  test('a block already there with other content needs --adopt', async () => {
+    const fake = withVendor();
+    fake.files.set('/etc/vendor.conf', {
+      bytes: new TextEncoder().encode(
+        `${VENDOR}# BEGIN homeflare\nsomething else\n# END homeflare\n`,
+      ),
+      gid: 0,
+      kind: 'file',
+      mode: 0o600,
+      uid: 0,
+    });
+    await expect(reconcileFile(fake.runner, block)).rejects.toThrow(/managed region/);
+    await expect(reconcileFile(fake.runner, block, undefined, true)).resolves.toBeDefined();
+  });
+});
+
+describe('a failed read refuses', () => {
+  test('a stat that throws is never read as “nothing is there”', async () => {
+    const fake = host();
+    const broken = {
+      ...fake.runner,
+      stat: async () => {
+        throw new Error('ssh somewhere: the remote command did not report a status');
+      },
+    };
+    await expect(reconcileFile(broken, props)).rejects.toThrow(/did not report a status/);
+    await expect(readFileAttributes(broken, PATH, undefined)).rejects.toThrow(/did not report/);
+  });
+});

package/src/linux/remote-file-lifecycle.ts

@@ -0,0 +1,161 @@
+/**
+ * RemoteFile's diff / reconcile / delete over a HostRunner, so the whole lifecycle runs against a
+ * fake host in tests with no ssh and no real write. What it would write is worked out next door
+ * (remote-file-plan.ts); this file is the part that decides to act.
+ *
+ * ⛔ IN REGION MODE, DRIFT MEANS THE REGION AND NOTHING ELSE. Every byte outside the markers belongs
+ *   to another owner, so a change there must never plan an update — otherwise the two owners fight
+ *   on every deploy and this resource loses the right to be in that file at all.
+ * ⚠️ THE WRITE REPLACES THE INODE, in both modes. A process holding the old file keeps reading it
+ *   until it reopens, and a hard link to the path stops tracking. That is the price of never
+ *   leaving a torn file, and it is the trade the launchd family already makes.
+ */
+import type { Diff } from 'alchemy/Diff';
+import { sha256Hex } from '../launchd/job-form.ts';
+import { type HostRunner, canActAsRoot } from '../launchd/runner.ts';
+import { removeRegion } from './region.ts';
+import {
+  DEFAULT_MODE,
+  type RemoteFileAttributes,
+  type RemoteFileProps,
+} from './remote-file-form.ts';
+import {
+  decoder,
+  digestOf,
+  encoder,
+  identity,
+  ownedDigest,
+  planWrite,
+  readFileAttributes,
+  refuse,
+} from './remote-file-plan.ts';
+
+export { readFileAttributes } from './remote-file-plan.ts';
+
+/**
+ * ★ A PLAN THAT WILL WRITE ASKS THE RUNNER FIRST (`checkWrite`, when it has one), so a runner's own
+ *   refusals fail the plan instead of arriving halfway through the apply.
+ */
+export const diffFile = async (
+  runner: HostRunner,
+  news: RemoteFileProps,
+  output: RemoteFileAttributes,
+): Promise<Diff> => {
+  const want = await identity(runner, news);
+  if (news.path !== output.path) {
+    // ★ Create-before-delete: two paths hold two files at once, so nothing forces deleteFirst.
+    await runner.checkWrite?.(news.path, { mode: news.mode ?? DEFAULT_MODE, ...want });
+    return { action: 'replace' };
+  }
+  const planned = await planWrite(runner, news, want);
+  // ⛔ BOTH digests: the live one catches a hand edit, the STORED one catches a write that landed
+  //   and whose deploy then died before committing. Either alone reports `noop` over a wrong file.
+  if (planned.converged && output.contentSha256 === digestOf(news.content)) {
+    return { action: 'noop' };
+  }
+  await runner.checkWrite?.(news.path, planned.write);
+  return { action: 'update' };
+};
+
+/**
+ * `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 what is already at the path — the
+ * takeover the plan's probe would have allowed, had it run.
+ * ★ IN REGION MODE THE FILE BEING THERE IS NOT A TAKEOVER: it belongs to someone else by
+ *   definition. What this resource claims is the block, so only a block already present with other
+ *   content is the thing adoption is asked about.
+ */
+export const reconcileFile = async (
+  runner: HostRunner,
+  props: RemoteFileProps,
+  output?: RemoteFileAttributes,
+  adopt = false,
+): Promise<RemoteFileAttributes> => {
+  const want = await identity(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 through ` +
+        'a root destination or a privileged HostRunner. This provider never calls sudo itself.',
+    );
+  }
+  const moved = output !== undefined && output.path !== props.path;
+  const prior = moved ? undefined : output;
+  const planned = await planWrite(runner, props, want);
+  const live = ownedDigest(planned.before, props.region);
+  const declared = digestOf(props.content);
+  /**
+   * ⛔ SOMETHING WE DO NOT OWN IS NEVER OVERWRITTEN. With no prior state the engine's probe has
+   *   already refused whatever it found — except where it never looked: a replace's new path, and a
+   *   create whose props still held an Output at plan time. A path typo there would otherwise
+   *   overwrite a system file. ★ With adoption on, a create takes it over, as the probe would have.
+   */
+  if (
+    prior === undefined &&
+    live !== undefined &&
+    live !== declared &&
+    !(adopt && output === undefined)
+  ) {
+    throw refuse(
+      props.path,
+      `${props.region === undefined ? 'already exists' : 'already carries that managed region'}` +
+        ' and is not this resource. Remove it, or declare it as a new resource and deploy --adopt.',
+    );
+  }
+  if (!planned.converged) await runner.writeFileAtomic(props.path, planned.bytes, planned.write);
+  /**
+   * ⚠️ 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, props.region);
+  if (
+    after === undefined ||
+    after.sha256 !== sha256Hex(planned.bytes) ||
+    after.contentSha256 !== declared
+  ) {
+    /**
+     * ⚠️ Roll back a CREATE only: 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.
+     * ⛔ NEVER IN REGION MODE — the file was someone else's before this deploy and must survive it.
+     */
+    if (planned.before === undefined && props.region === 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 once the new one is
+  //   written and verified.
+  if (moved && output !== undefined) await deleteFile(runner, output);
+  return after;
+};
+
+/**
+ * Whole-file mode removes the file. ⛔ REGION MODE REMOVES ONLY THE BLOCK, leaving every other byte
+ *   identical — removing the file would delete another owner's configuration. Idempotent both ways.
+ */
+export const deleteFile = async (
+  runner: HostRunner,
+  output: RemoteFileAttributes,
+): 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 touching it`);
+  if (output.region === undefined) {
+    await runner.removeFile(output.path);
+    return;
+  }
+  const bytes = await runner.readFile(output.path);
+  if (bytes === undefined) return;
+  const before = decoder.decode(bytes);
+  const next = removeRegion(before, output.region);
+  if (next === before) return;
+  await runner.writeFileAtomic(output.path, encoder.encode(next), {
+    gid: stat.gid,
+    mode: stat.mode,
+    uid: stat.uid,
+  });
+};

package/src/linux/remote-file-plan.ts

@@ -0,0 +1,154 @@
+/**
+ * What RemoteFile would write, worked out from what is on the host right now — the half of the
+ * lifecycle that reads and decides, with no write in it.
+ *
+ * ⛔ IN REGION MODE THE LIVE FILE IS AN INPUT, not merely something to compare against: the declared
+ *   block is spliced into the bytes that are there, so every surrounding line survives verbatim.
+ *   That is why this cannot be a pure function of the props the way a whole-file render is.
+ */
+import { sha256Hex } from '../launchd/job-form.ts';
+import type { FileStat, HostRunner, WriteOptions } from '../launchd/runner.ts';
+import { type RegionSpec, readRegion, spliceRegion } from './region.ts';
+import {
+  DEFAULT_MODE,
+  type RemoteFileAttributes,
+  type RemoteFileProps,
+  fileProblems,
+} from './remote-file-form.ts';
+
+export const decoder = new TextDecoder();
+export const encoder = new TextEncoder();
+
+export const refuse = (path: string, message: string): Error =>
+  new Error(`Remote.File ${path}: ${message}`);
+
+const numericId = (value: string | number): number | undefined =>
+  typeof value === 'number' ? value : /^\d+$/.test(value) ? Number(value) : undefined;
+
+export type Identity = { readonly uid?: number; readonly gid?: number };
+
+/** Validate, then resolve owner and group names to ids through the runner. */
+export const identity = async (runner: HostRunner, props: RemoteFileProps): Promise<Identity> => {
+  const found = fileProblems(props);
+  if (found.length > 0) throw refuse(props.path, found.join('; '));
+  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 { ...(uid === undefined ? {} : { uid }), ...(gid === undefined ? {} : { gid }) };
+};
+
+export const digestOf = (text: string): string => sha256Hex(encoder.encode(text));
+
+/** The digest of the part this resource owns, or `undefined` when that part is not there. */
+export const ownedDigest = (
+  file: string | undefined,
+  region: RegionSpec | undefined,
+): string | undefined => {
+  if (file === undefined) return undefined;
+  if (region === undefined) return digestOf(file);
+  const body = readRegion(file, region);
+  return body === undefined ? undefined : digestOf(body);
+};
+
+/** The file as it is now, plus the digest of the part this resource owns. */
+export const readFileAttributes = async (
+  runner: HostRunner,
+  path: string,
+  region: RegionSpec | undefined,
+): Promise<RemoteFileAttributes | undefined> => {
+  const stat = await runner.stat(path);
+  if (stat === undefined) return undefined;
+  const bytes = stat.kind === 'file' ? await runner.readFile(path) : undefined;
+  const text = bytes === undefined ? undefined : decoder.decode(bytes);
+  return {
+    contentSha256: ownedDigest(text, region) ?? '',
+    gid: stat.gid,
+    mode: stat.mode,
+    path,
+    ...(region === undefined ? {} : { region }),
+    sha256: bytes === undefined ? '' : sha256Hex(bytes),
+    size: stat.size,
+    uid: stat.uid,
+  };
+};
+
+const matches = (stat: FileStat | undefined, write: WriteOptions): boolean =>
+  stat !== undefined &&
+  stat.mode === write.mode &&
+  (write.uid === undefined || stat.uid === write.uid) &&
+  (write.gid === undefined || stat.gid === write.gid);
+
+export type Plan = {
+  /** The whole file's new bytes, in both modes. */
+  readonly bytes: Uint8Array;
+  readonly write: WriteOptions;
+  /** The bytes on disk right now, or `undefined` when nothing is there. */
+  readonly before: string | undefined;
+  /** Nothing to do: the file already says what we declare, with the mode and owner we declare. */
+  readonly converged: boolean;
+};
+
+/**
+ * ⛔ A SYMLINK OR A DIRECTORY IS REFUSED, NOT REPLACED. The write is a rename(2), which over a
+ *   symlink replaces the LINK — quietly taking the path from whatever put it there (a config
+ *   manager's `/etc` entries are symlinks, and so is `/etc/resolv.conf` on most Linux hosts).
+ */
+export const planWrite = async (
+  runner: HostRunner,
+  props: RemoteFileProps,
+  want: Identity,
+): Promise<Plan> => {
+  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 current = stat === undefined ? undefined : await runner.readFile(props.path);
+  const before = current === undefined ? undefined : decoder.decode(current);
+  const declaredMode = props.mode ?? DEFAULT_MODE;
+  if (props.region === undefined) {
+    const write: WriteOptions = { mode: declaredMode, ...want };
+    return {
+      before,
+      bytes: encoder.encode(props.content),
+      converged: before === props.content && matches(stat, write),
+      write,
+    };
+  }
+  if (before === undefined) {
+    if (props.create !== true) {
+      throw refuse(
+        props.path,
+        'does not exist, and a managed region does not create the file it lives in. Check the ' +
+          'path, declare the file itself, or pass create: true.',
+      );
+    }
+    return {
+      before,
+      bytes: encoder.encode(spliceRegion('', props.region, props.content)),
+      converged: false,
+      write: { mode: declaredMode, ...want },
+    };
+  }
+  const next = spliceRegion(before, props.region, props.content);
+  /**
+   * ⛔ THE FILE'S OWN MODE AND OWNER ARE COPIED BACK, never re-declared. We borrowed a block; the
+   *   rename would otherwise hand a file someone else owns a mode and an owner this stack chose,
+   *   which is a second claim nobody made.
+   */
+  return {
+    before,
+    bytes: encoder.encode(next),
+    converged: next === before,
+    write: { gid: stat?.gid ?? 0, mode: stat?.mode ?? declaredMode, uid: stat?.uid ?? 0 },
+  };
+};

package/src/linux/remote-file.ts

@@ -0,0 +1,88 @@
+/**
+ * `Remote.File` — one text file on a Linux host, declared: content, mode, owner, group — or one
+ * MANAGED BLOCK inside a file this resource does not own.
+ *
+ * - create / update — atomic write (stage beside the target, chown, chmod, rename), skipped when
+ *   the host already says what we declare; then read back and compared.
+ * - read — lstat plus the SHA-256 of the file and of the part this resource owns.
+ * - diff — the declared digest against the stored AND the on-disk one, plus mode and owner.
+ * - replace — only when `path` changes; create-before-delete.
+ * - delete — removes the file, or in region mode only the block.
+ *
+ * ⛔ NEVER A SECRET — see remote-file-form.ts.
+ * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt` (docs/ownership.md): a file already at the path, or a
+ *   block already carrying the markers, reads as `Unowned`.
+ * ★ IT IS A SEPARATE RESOURCE FROM `Host.File`, not a flag on it: the two have different attributes
+ *   (a region name that a delete cannot work without) and different promises about the rest of the
+ *   file, and folding them together would make every existing Mac HostFile's state shape change.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { lift, resolvedString } from '../launchd/host-effect.ts';
+import { HostRunnerService } from '../launchd/runner.ts';
+import { adoptsAtApply } from '../ownership/adopt.ts';
+import { noteUnfinished } from '../ownership/resume.ts';
+import type { RemoteFileAttributes, RemoteFileProps } from './remote-file-form.ts';
+import {
+  deleteFile,
+  diffFile,
+  readFileAttributes,
+  reconcileFile,
+} from './remote-file-lifecycle.ts';
+
+export type { RemoteFileAttributes, RemoteFileProps } from './remote-file-form.ts';
+
+export interface RemoteFile extends Resource<
+  'Remote.File',
+  RemoteFileProps,
+  RemoteFileAttributes
+> {}
+
+export const RemoteFile = Resource<RemoteFile>('Remote.File');
+
+export const RemoteFileProvider = () =>
+  Provider.effect(
+    RemoteFile,
+    Effect.gen(function* () {
+      const runner = yield* HostRunnerService;
+      return RemoteFile.Provider.of({
+        /** ⛔ A host's files are not a list of things this stack owns. */
+        list: () => Effect.succeed([]),
+
+        read: ({ olds, output }) =>
+          lift(async () => {
+            const found = await readFileAttributes(runner, olds.path, olds.region);
+            if (found === undefined) return undefined;
+            // ⛔ In region mode an existing file is NOT this resource: only the block is. A file
+            //   with no such block reads as nothing, so the create writes the block instead of
+            //   demanding --adopt for a file it was never claiming.
+            if (olds.region !== undefined && found.contentSha256 === '') return undefined;
+            return output === undefined ? Unowned(found) : found;
+          }),
+
+        diff: ({ instanceId, news, output }) => {
+          // ★ An unfinished generation of our own: `--adopt` may resume it (ownership/resume.ts).
+          if (output === undefined) return noteUnfinished(instanceId);
+          if (isResolved(news)) return lift(() => diffFile(runner, news, output));
+          // ⛔ 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.
+          const path = resolvedString(news, 'path');
+          return Effect.succeed(
+            path !== undefined && path !== output.path ? { action: 'replace' as const } : undefined,
+          );
+        },
+
+        // ★ `--adopt` reaches the apply too: the probe never ran for a create with an Output prop.
+        reconcile: ({ fqn, instanceId, news, output }) =>
+          Effect.flatMap(adoptsAtApply({ fqn, instanceId, output }), (adopt) =>
+            lift(() => reconcileFile(runner, news, output, adopt)),
+          ),
+
+        delete: ({ output }) => lift(() => deleteFile(runner, output)),
+      });
+    }),
+  );