@homeflare/alchemy 0.15.0 → 0.19.0

package/docs/netbox.md

@@ -0,0 +1,103 @@
+# NetBox — `@homeflare/alchemy/netbox`
+
+NetBox is a record of decisions, not a controller. Nothing here reboots anything; the worst a
+mistake does is write the wrong intent into the source of truth everything else is checked against.
+That shapes every posture below.
+
+## Credentials
+
+Two environment variables, read **at call time**, never props:
+
+| variable       | holds                                                  |
+| -------------- | ------------------------------------------------------ |
+| `NETBOX_URL`   | the instance origin, e.g. `https://netbox.example.com` |
+| `NETBOX_TOKEN` | a scoped NetBox API token                              |
+
+⛔ **Neither has a default.** A package that fell back to a loopback address would let a consumer
+who forgot the variable watch every call fail against a machine that is not theirs, instead of
+being told which variable is missing.
+
+⚠️ **`Authorization: Token <value>`, not `Bearer`.** NetBox is Django REST Framework using DRF's
+own `TokenAuthentication`. Measured: `Bearer` returns 401 and `Token` returns 200 — and a wrong
+scheme and a wrong credential are indistinguishable in the response.
+
+⛔ **Mint a short-lived, scoped token.** A NetBox token can be given an expiry, a source-IP
+restriction and `write_enabled: false`; a plan-only run wants the last of those.
+
+## Adopt is the default posture
+
+`reconcile` LOCATES before it writes. An object the instance already holds is bound, not
+duplicated — NetBox predates this code by years on any real estate, and a provider that created a
+second `10.0.0.0/24` on first deploy would be worse than no provider.
+
+⛔ **An ambiguous identity FAILS.** `soleMatch` refuses more than one candidate rather than taking
+the first: binding to "whichever NetBox ordered first" would make the next plan bind to the other
+row and report drift that is not there.
+
+★ **Narrowing is split: a filter the schema declares, then a rule in this process.** `locate`
+sends only filters the vendor document states; `identifies` picks the one row among the candidates.
+
+⚠️ **`Netbox.Prefix` uses that split for the VRF, and the reason is a guess that was caught.** A
+prefix is unique per-VRF, so the CIDR alone can match several rows. The obvious server-side
+narrowing is `vrf_id=null` for the global table — NetBox does define `FILTERS_NULL_CHOICE_VALUE =
+'null'`. ⛔ But measured in the vendor's own source at v4.7.0, `PrefixFilterSet.vrf_id` is a plain
+`ModelMultipleChoiceFilter` with no `null_value`: it does not opt in, so `'null'` fails queryset
+validation and NetBox answers **400 on every plan for every global prefix**. The VRF is compared
+here instead, where the rule is readable and testable without a server.
+
+## Removal is `retain`
+
+⛔ **Deleting a NetBox row deletes history.** Child prefixes reparent, IP assignments detach, and
+the change log is the only trace left. Every family here defaults to `retain`, so dropping a
+declaration does not delete the object unless the caller opts into `.pipe(RemovalPolicy.destroy())`.
+The `delete` handler is fully implemented anyway — a stub that silently does nothing lies to
+whoever reads the plan.
+
+## An undeclared field is not an instruction to clear it
+
+🔴 **This shipped wrong once, and the shape of the mistake is worth keeping.** `Netbox.Prefix`
+sent `description: ''` whenever the prop was absent. On a create that is invisible — the field was
+empty anyway. ⛔ **On an adopt it is data loss**: a prefix's description is usually the only written
+trace of why that range exists, and the first deploy that adopted one would have PATCHed it to
+empty, with a plan that read `update`.
+
+★ **So the line is drawn at what the vendor itself defaults.** `status`, `is_pool` and
+`mark_utilized` have defaults in the schema, so omitting one genuinely means "the default" and
+settling it says what NetBox would have done anyway. `description`, `comments` and every optional
+foreign key have no such default — the schema's `''` is the absence of a value, not a decision —
+so they are **omitted from the body and uncompared** until you declare them.
+
+⚠️ **The cost, stated:** prose cannot be cleared by omission. Clearing it is `description: ''`,
+written on purpose, which is the readable way to say a destructive thing.
+
+⛔ **Whatever `matches` compares, `body` must send.** A field compared but never written produces
+a plan that says `update` forever: the PATCH omits it, so the next read is unchanged. The two move
+together, and `prefix-form.test.ts` asserts it.
+
+## Read and write are different shapes
+
+⛔ **This is the bug that makes a resource never converge, and it is handled in `values.ts`.** A
+prefix is WRITTEN with `status: "active"` and READ BACK as `{value: "active", label: "Active"}`; a
+foreign key is written as `4` and read back as `{id: 4, url: …, display: …}`. A `matches` that
+compared those directly would report drift on every plan, for every object, forever — and each
+"update" would PATCH the same value back.
+
+## Vendor constraints, checked before the request
+
+Every write is checked against a table **generated from NetBox's own OpenAPI document** — not from
+hand-typed limits. A declaration the vendor would reject dies at plan time with the endpoint named,
+rather than half-way through a deploy that has already adopted ten objects.
+
+```ts
+import { bodyViolations, constraintsFor } from '@homeflare/alchemy/netbox';
+
+constraintsFor('netbox:POST /api/ipam/prefixes/')['description']?.maxLength; // 200
+```
+
+⚠️ **What it deliberately does NOT enforce**, so a green plan is not read as more than it is: a
+`format` name DRF validates server-side; a pattern whose Python `\w` is Unicode where JavaScript's
+is ASCII (recorded as `patternSource` with no `pattern`); and uniqueness, VRF containment and
+custom-field validators, which live in Django rather than in the schema and still arrive as a 400.
+
+Provenance, the re-fetch recipe and the coverage report: [`codegen/netbox.md`](../../../codegen/netbox.md)
+and [`docs/netbox-coverage.md`](../../../docs/netbox-coverage.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.15.0",
+  "version": "0.19.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -56,6 +56,14 @@
       "types": "./dist/launchd/index.d.ts",
       "default": "./dist/launchd/index.js"
     },
+    "./netbox": {
+      "types": "./dist/netbox/index.d.ts",
+      "default": "./dist/netbox/index.js"
+    },
+    "./linux": {
+      "types": "./dist/linux/index.d.ts",
+      "default": "./dist/linux/index.js"
+    },
     "./caddy": {
       "types": "./dist/caddy/index.d.ts",
       "default": "./dist/caddy/index.js"

package/src/linux/directory-lifecycle.ts

@@ -0,0 +1,220 @@
+/**
+ * HostDirectory's props, validation and lifecycle over a HostRunner.
+ *
+ * ★ WHY IT EXISTS AT ALL. `Host.File` and `Remote.File` both refuse to create a parent directory,
+ *   on purpose — creating one would invent an owner and a mode nobody declared. The consequence is
+ *   that a first deploy into a new tree fails on its first file. This resource is the declaration
+ *   that was missing, not a convenience flag on the file.
+ * ⛔ ONE DIRECTORY, NEVER A CHAIN. A missing parent is a refusal that names it, so a tree is a
+ *   chain of declarations whose modes and owners are all visible in the plan. `mkdir -p` would
+ *   create the intermediate levels at whatever umask the deploy happened to run with.
+ * ⛔ DELETE IS `rmdir`, NEVER RECURSIVE. A directory that still holds files is a refusal: removing
+ *   a declaration must not be able to remove data the declaration never mentioned.
+ */
+import type { Diff } from 'alchemy/Diff';
+import { pathProblems } from '../launchd/host-file-form.ts';
+import { type HostRunner, canActAsRoot } from '../launchd/runner.ts';
+
+export interface HostDirectoryProps {
+  /** Absolute path. ⚠️ Its parent must already exist — declare it as another HostDirectory. */
+  path: string;
+  /** Permission bits. @default 0o755 */
+  mode?: number;
+  /** User name or numeric uid. Omitted: whoever the runner writes as. */
+  owner?: string | number;
+  /** Group name or numeric gid. Omitted: the parent's default group. */
+  group?: string | number;
+}
+
+export interface HostDirectoryAttributes {
+  path: string;
+  mode: number;
+  uid: number;
+  gid: number;
+}
+
+export const DEFAULT_DIR_MODE = 0o755;
+
+export const refuse = (path: string, message: string): Error =>
+  new Error(`Host.Directory ${path}: ${message}`);
+
+const idProblems = (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 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 directoryProblems = (props: HostDirectoryProps): string[] => {
+  const found = pathProblems(props.path);
+  const mode = props.mode ?? DEFAULT_DIR_MODE;
+  if (!Number.isSafeInteger(mode) || mode < 0 || mode > 0o7777) found.push('mode must be 0–0o7777');
+  found.push(...idProblems('owner', props.owner), ...idProblems('group', props.group));
+  return found;
+};
+
+const numericId = (value: string | number): number | undefined =>
+  typeof value === 'number' ? value : /^\d+$/.test(value) ? Number(value) : undefined;
+
+type Desired = { readonly mode: number; readonly uid?: number; readonly gid?: number };
+
+const desired = async (runner: HostRunner, props: HostDirectoryProps): Promise<Desired> => {
+  const found = directoryProblems(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 {
+    mode: props.mode ?? DEFAULT_DIR_MODE,
+    ...(uid === undefined ? {} : { uid }),
+    ...(gid === undefined ? {} : { gid }),
+  };
+};
+
+export const readDirectory = async (
+  runner: HostRunner,
+  path: string,
+): Promise<HostDirectoryAttributes | undefined> => {
+  const stat = await runner.stat(path);
+  if (stat === undefined || stat.kind !== 'directory') return undefined;
+  return { gid: stat.gid, mode: stat.mode, path, uid: stat.uid };
+};
+
+const octal = (mode: number) => mode.toString(8).padStart(3, '0');
+
+/** One program, checked: anything but exit 0 is an Error naming the argv and the host's words. */
+const must = async (runner: HostRunner, path: string, argv: readonly string[]): Promise<void> => {
+  const result = await runner.exec(argv);
+  if (result.exitCode !== 0) {
+    throw refuse(
+      path,
+      `${argv.join(' ')} -> ${String(result.exitCode)}: ${result.stderr.trim().slice(0, 300)}`,
+    );
+  }
+};
+
+/**
+ * Create it when absent, then bring mode and ownership to the declaration and read back.
+ * ⚠️ `mkdir -m` sets the mode with chmod(2) after mkdir(2), so it is exact — plain `mkdir` would
+ *   mask the declared bits through the deploying shell's umask and the drift would return forever.
+ */
+export const reconcileDirectory = async (
+  runner: HostRunner,
+  props: HostDirectoryProps,
+  output?: HostDirectoryAttributes,
+  adopt = false,
+): Promise<HostDirectoryAttributes> => {
+  const want = await desired(runner, props);
+  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 stat = await runner.stat(props.path);
+  if (stat !== undefined && stat.kind !== 'directory') {
+    throw refuse(props.path, `is a ${stat.kind}, not a directory`);
+  }
+  /**
+   * ⛔ A DIRECTORY THIS RESOURCE DOES NOT OWN IS NEVER RE-MODED. Where the engine's probe never
+   *   looked — a replace's new path, a create whose props were still an Output — an existing
+   *   directory with a different mode or owner is someone else's. ★ Adoption takes it over.
+   */
+  if (output === undefined && stat !== undefined && !adopt) {
+    const drifted = stat.mode !== want.mode || (want.uid !== undefined && stat.uid !== want.uid);
+    if (drifted) {
+      throw refuse(
+        props.path,
+        'already exists with another mode or owner and is not this resource. Remove it, or ' +
+          'declare it as a new resource and deploy with --adopt.',
+      );
+    }
+  }
+  if (stat === undefined) {
+    const parent = props.path.slice(0, props.path.lastIndexOf('/')) || '/';
+    const above = await runner.stat(parent);
+    if (above === undefined || above.kind !== 'directory') {
+      throw refuse(props.path, `its parent ${parent} does not exist; declare that directory too`);
+    }
+    await must(runner, props.path, ['mkdir', '-m', octal(want.mode), '--', props.path]);
+  } else if (stat.mode !== want.mode) {
+    await must(runner, props.path, ['chmod', octal(want.mode), '--', props.path]);
+  }
+  /**
+   * ★ Only when it is actually wrong. A `chown` that changes nothing is still a write on the host
+   *   and a line in the deploy log, and "a converged resource is not touched" is the rule this
+   *   whole family is judged by.
+   */
+  const owner = ownerMatches(
+    { gid: stat?.gid ?? -1, mode: 0, path: props.path, uid: stat?.uid ?? -1 },
+    want,
+  )
+    ? undefined
+    : ownerArg(want);
+  if (owner !== undefined) await must(runner, props.path, ['chown', owner, '--', props.path]);
+  const after = await readDirectory(runner, props.path);
+  // ⚠️ READ BACK: a runner that ignored the mode shows up here, not as a forever-`update`.
+  if (after === undefined || after.mode !== want.mode || !ownerMatches(after, want)) {
+    throw refuse(props.path, 'the directory on the host does not match the declaration');
+  }
+  return after;
+};
+
+/** ⛔ Never `<uid>:` — GNU chown reads a trailing colon as that user's LOGIN group, undeclared. */
+const ownerArg = (want: Desired): string | undefined => {
+  if (want.uid === undefined) return want.gid === undefined ? undefined : `:${String(want.gid)}`;
+  return want.gid === undefined ? String(want.uid) : `${String(want.uid)}:${String(want.gid)}`;
+};
+
+const ownerMatches = (live: HostDirectoryAttributes, want: Desired): boolean =>
+  (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) — a directory is
+ *   created and chmod'd through `exec`, but a runner that refuses to touch the path at all should
+ *   say so at plan time rather than mid-apply.
+ */
+export const diffDirectory = async (
+  runner: HostRunner,
+  news: HostDirectoryProps,
+  output: HostDirectoryAttributes,
+): Promise<Diff> => {
+  const want = await desired(runner, news);
+  if (news.path !== output.path) return { action: 'replace' };
+  const live = await readDirectory(runner, news.path);
+  // ⛔ BOTH: the live directory catches a hand chmod, the stored attributes catch a deploy that
+  //   died after the mkdir and before its commit.
+  const converged =
+    live !== undefined &&
+    live.mode === want.mode &&
+    ownerMatches(live, want) &&
+    output.mode === want.mode &&
+    ownerMatches(output, want);
+  if (converged) return { action: 'noop' };
+  await runner.checkWrite?.(news.path, want);
+  return { action: 'update' };
+};
+
+/** Remove it. ⛔ `rmdir`: a directory that still holds anything is a refusal, never a recursion. */
+export const deleteDirectory = async (
+  runner: HostRunner,
+  output: HostDirectoryAttributes,
+): Promise<void> => {
+  const stat = await runner.stat(output.path);
+  if (stat === undefined) return;
+  if (stat.kind !== 'directory')
+    throw refuse(output.path, `is now a ${stat.kind}; not removing it`);
+  await must(runner, output.path, ['rmdir', '--', output.path]);
+};

package/src/linux/directory.test.ts

@@ -0,0 +1,132 @@
+/**
+ * HostDirectory against the fake host: the resource that exists because every file resource refuses
+ * to create a parent.
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+  deleteDirectory,
+  diffDirectory,
+  directoryProblems,
+  readDirectory,
+  reconcileDirectory,
+} from './directory-lifecycle.ts';
+import { fakeLinuxHost } from './fake-linux-host.ts';
+
+const host = () =>
+  fakeLinuxHost({
+    dirs: { '/opt/app': 0 },
+    groups: { app: 60 },
+    users: { app: { gid: 60, home: '/opt/app', uid: 900 } },
+  });
+
+describe('create', () => {
+  test('makes the directory with the declared mode and owner, then reads it back', async () => {
+    const fake = host();
+    const attrs = await reconcileDirectory(fake.runner, {
+      group: 'app',
+      mode: 0o750,
+      owner: 'app',
+      path: '/opt/app/etc',
+    });
+    expect(attrs).toEqual({ gid: 60, mode: 0o750, path: '/opt/app/etc', uid: 900 });
+    // ⚠️ `mkdir -m` carries the mode, so a umask never masks a declared bit.
+    expect(fake.calls.some((call) => call[0] === 'mkdir' && call.includes('750'))).toBe(true);
+  });
+
+  test('a missing parent is a refusal that names it, never an mkdir -p', async () => {
+    const fake = host();
+    await expect(reconcileDirectory(fake.runner, { path: '/opt/app/one/two' })).rejects.toThrow(
+      /its parent \/opt\/app\/one does not exist/,
+    );
+    expect(fake.calls.some((call) => call.includes('-p'))).toBe(false);
+  });
+
+  test('a path that is a file is refused rather than replaced', async () => {
+    const fake = host();
+    await fake.runner.writeFileAtomic('/opt/app/thing', new Uint8Array(), { mode: 0o644 });
+    await expect(reconcileDirectory(fake.runner, { path: '/opt/app/thing' })).rejects.toThrow(
+      /is a file, not a directory/,
+    );
+  });
+});
+
+describe('drift', () => {
+  test('a hand chmod is an update, and reconcile puts it back', async () => {
+    const fake = host();
+    const output = await reconcileDirectory(fake.runner, { mode: 0o750, path: '/opt/app/etc' });
+    expect(await diffDirectory(fake.runner, { mode: 0o750, path: '/opt/app/etc' }, output)).toEqual(
+      {
+        action: 'noop',
+      },
+    );
+    const live = fake.modes.get('/opt/app/etc');
+    if (live !== undefined) live.mode = 0o777;
+    expect(await diffDirectory(fake.runner, { mode: 0o750, path: '/opt/app/etc' }, output)).toEqual(
+      {
+        action: 'update',
+      },
+    );
+    const fixed = await reconcileDirectory(
+      fake.runner,
+      { mode: 0o750, path: '/opt/app/etc' },
+      output,
+    );
+    expect(fixed.mode).toBe(0o750);
+  });
+
+  test('a directory that is not this resource is refused unless adoption is on', async () => {
+    const fake = host();
+    await reconcileDirectory(fake.runner, { mode: 0o700, path: '/opt/app/etc' });
+    await expect(
+      reconcileDirectory(fake.runner, { mode: 0o755, path: '/opt/app/etc' }),
+    ).rejects.toThrow(/deploy with --adopt/);
+    const adopted = await reconcileDirectory(
+      fake.runner,
+      { mode: 0o755, path: '/opt/app/etc' },
+      undefined,
+      true,
+    );
+    expect(adopted.mode).toBe(0o755);
+  });
+
+  test('a directory that already matches is not touched — not even a no-op chown', async () => {
+    const fake = host();
+    const props = { group: 'app', mode: 0o755, owner: 'app', path: '/opt/app/etc' };
+    const output = await reconcileDirectory(fake.runner, props);
+    const before = fake.calls.length;
+    await reconcileDirectory(fake.runner, props, output);
+    const after = fake.calls.slice(before).map((call) => call[0]);
+    expect(after).not.toContain('mkdir');
+    expect(after).not.toContain('chmod');
+    // ⛔ A chown that changes nothing is still a write on the host and a line in the deploy log.
+    expect(after).not.toContain('chown');
+  });
+});
+
+describe('delete', () => {
+  test('is rmdir: a directory that still holds a file is a refusal', async () => {
+    const fake = host();
+    const attrs = await reconcileDirectory(fake.runner, { path: '/opt/app/etc' });
+    await fake.runner.writeFileAtomic('/opt/app/etc/kept.conf', new Uint8Array(), { mode: 0o644 });
+    await expect(deleteDirectory(fake.runner, attrs)).rejects.toThrow(/Directory not empty/);
+    expect(fake.calls.some((call) => call.includes('-r') || call.includes('-rf'))).toBe(false);
+  });
+
+  test('an empty directory goes, and a second delete is a no-op', async () => {
+    const fake = host();
+    const attrs = await reconcileDirectory(fake.runner, { path: '/opt/app/etc' });
+    await deleteDirectory(fake.runner, attrs);
+    expect(await readDirectory(fake.runner, '/opt/app/etc')).toBeUndefined();
+    await deleteDirectory(fake.runner, attrs);
+  });
+});
+
+describe('validation', () => {
+  test('refuses a relative or unnormalised path and an impossible mode', () => {
+    expect(directoryProblems({ path: 'opt/app' })).toContain('path must be absolute');
+    expect(directoryProblems({ path: '/opt/../etc' }).length).toBeGreaterThan(0);
+    expect(directoryProblems({ mode: 0o10000, path: '/opt/app' })).toContain(
+      'mode must be 0–0o7777',
+    );
+  });
+});

package/src/linux/directory.ts

@@ -0,0 +1,71 @@
+/**
+ * `Host.Directory` — one directory on the host, declared: path, mode, owner, group.
+ *
+ * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt`: a directory already at the path reads as `Unowned`, and
+ *   where the plan never asked, reconcile honours the same flag (docs/ownership.md).
+ * ★ IT IS NOT LINUX-ONLY. `mkdir`, `chmod`, `chown` and `rmdir` are the same argv on macOS, so this
+ *   resource works through any HostRunner; it lives in the linux subpath because the gap it closes
+ *   was found there (a first deploy into a new tree, which every file resource refuses to create).
+ */
+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 { HostDirectoryAttributes, HostDirectoryProps } from './directory-lifecycle.ts';
+import {
+  deleteDirectory,
+  diffDirectory,
+  readDirectory,
+  reconcileDirectory,
+} from './directory-lifecycle.ts';
+
+export type { HostDirectoryAttributes, HostDirectoryProps } from './directory-lifecycle.ts';
+
+export interface HostDirectory extends Resource<
+  'Host.Directory',
+  HostDirectoryProps,
+  HostDirectoryAttributes
+> {}
+
+export const HostDirectory = Resource<HostDirectory>('Host.Directory');
+
+export const HostDirectoryProvider = () =>
+  Provider.effect(
+    HostDirectory,
+    Effect.gen(function* () {
+      const runner = yield* HostRunnerService;
+      return HostDirectory.Provider.of({
+        list: () => Effect.succeed([]),
+
+        read: ({ olds, output }) =>
+          lift(async () => {
+            const found = await readDirectory(runner, olds.path);
+            if (found === undefined) return undefined;
+            return output === undefined ? Unowned(found) : found;
+          }),
+
+        diff: ({ instanceId, news, output }) => {
+          if (output === undefined) return noteUnfinished(instanceId);
+          if (isResolved(news)) return lift(() => diffDirectory(runner, news, output));
+          // ⛔ A new path is a replace even while the rest is unresolved: the engine's default
+          //   update would create the new directory and leave the old one behind forever.
+          const path = resolvedString(news, 'path');
+          return Effect.succeed(
+            path !== undefined && path !== output.path ? { action: 'replace' as const } : undefined,
+          );
+        },
+
+        reconcile: ({ fqn, instanceId, news, output }) =>
+          Effect.flatMap(adoptsAtApply({ fqn, instanceId, output }), (adopt) =>
+            lift(() => reconcileDirectory(runner, news, output, adopt)),
+          ),
+
+        delete: ({ output }) => lift(() => deleteDirectory(runner, output)),
+      });
+    }),
+  );