@homeflare/alchemy 0.20.0 → 0.22.0

package/src/release/apply-pins.test.ts

@@ -0,0 +1,128 @@
+/**
+ * ⛔ A PIN IS NEVER COMPUTED DURING THE DEPLOY — on a FIRST deploy too. Release.Binary through
+ * Alchemy's own Plan and Apply (openbao/fake-stack.ts), with a pin wired from another resource's
+ * Output: the shape of "fetch the checksum file at apply and trust what it says".
+ *
+ * 🔴 MEASURED 2026-09-22 (supply-chain review of PR 138): before the apply-time check, the engine
+ *   never diffed this create and skipped its probe (an Output in `news`), so reconcile saw only the
+ *   RESOLVED digests. The release asset and its checksum file were both swapped (the releases are
+ *   mutable, victoria.ts), the Output carried the swapped digests, and the deploy installed the
+ *   swapped bytes and reported them verified. binary-diff.ts refused the same declaration only
+ *   from the SECOND plan on — after the wrong binary was already on the host.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientResponse from 'effect/unstable/http/HttpClientResponse';
+import { sha256Hex } from '../launchd/job-form.ts';
+import { type HostRunner, hostRunnerLayer } from '../launchd/runner.ts';
+import { HostDirectory, HostDirectoryProvider } from '../linux/directory.ts';
+import { fakeLinuxHost } from '../linux/fake-linux-host.ts';
+import { fakeStack } from '../openbao/fake-stack.ts';
+import { ReleaseBinary, makeReleaseBinaryProvider } from './binary.ts';
+import { catalogBinary } from './catalog.ts';
+import {
+  VMALERT_REQUEST,
+  VMUTILS_URL,
+  bytesOf,
+  gzip,
+  syntheticRelease,
+  tarOf,
+} from './fake-release.ts';
+
+const ROOT = '/opt/example/bin';
+const DIR = `${ROOT}/vmutils-1.151.0`;
+const EVIL = bytesOf('#!swapped vmalert\n');
+const SWAPPED = gzip(tarOf([{ bytes: EVIL, name: 'vmalert-prod' }]));
+
+/** What a stack might write to "stay current": digests read from the release at apply. */
+type Sums = { readonly archive: string; readonly member: string; readonly size: number };
+interface FetchedSums extends Resource<'Test.FetchedSums', { url: string }, Sums> {}
+const FetchedSums = Resource<FetchedSums>('Test.FetchedSums');
+/** ★ It answers with the SWAPPED asset's digests — what the swapped checksum file would say. */
+const FetchedSumsProvider = () =>
+  Provider.effect(
+    FetchedSums,
+    Effect.succeed(
+      FetchedSums.Provider.of({
+        delete: () => Effect.void,
+        list: () => Effect.succeed([]),
+        reconcile: () =>
+          Effect.succeed({
+            archive: sha256Hex(SWAPPED),
+            member: sha256Hex(EVIL),
+            size: SWAPPED.length,
+          }),
+      }),
+    ),
+  );
+
+const harness = () => {
+  const pins = catalogBinary(syntheticRelease().catalog, VMALERT_REQUEST);
+  const fake = fakeLinuxHost({ dirs: { [ROOT]: 0 }, euid: 0 });
+  const events: string[] = [];
+  const runner: HostRunner = {
+    ...fake.runner,
+    writeFileAtomic: (path, bytes, options) => {
+      events.push(`write ${path}`);
+      return fake.runner.writeFileAtomic(path, bytes, options);
+    },
+  };
+  // ★ The attacker's release: the swapped archive at the REAL asset URL.
+  const client = HttpClient.make((request, url) => {
+    events.push(`GET ${url.toString()}`);
+    const body = url.toString() === VMUTILS_URL ? new Blob([SWAPPED.slice()]) : null;
+    return Effect.succeed(
+      HttpClientResponse.fromWeb(request, new Response(body, { status: body ? 200 : 404 })),
+    );
+  });
+  const providers = Layer.mergeAll(
+    makeReleaseBinaryProvider({ download: { retries: 0 } }),
+    HostDirectoryProvider(),
+    FetchedSumsProvider(),
+  ).pipe(
+    Layer.provide(
+      Layer.mergeAll(hostRunnerLayer(runner), Layer.succeed(HttpClient.HttpClient, client)),
+    ),
+  );
+  return { events, fake, pins, stack: fakeStack(providers, {}, 'ApplyPinStack') };
+};
+
+type Wiring = 'every digest and the size' | 'the member digest' | 'the archive digest and size';
+
+describe('a pin wired from an Output, on a first deploy', () => {
+  test.each<[Wiring, string]>([
+    ['every digest and the size', 'archive.sha256 is required, as a plain string'],
+    ['the member digest', 'sha256 is required, as a plain string'],
+    ['the archive digest and size', 'archive.size must be'],
+  ])('%s: refused at apply, nothing fetched, nothing written', async (wiring, refusal) => {
+    const h = harness();
+    const body = Effect.gen(function* () {
+      const dir = yield* HostDirectory('vmutils-1.151.0', { mode: 0o755, path: DIR });
+      const sums = yield* FetchedSums('sums', { url: `${VMUTILS_URL}_checksums.txt` });
+      const archive =
+        wiring === 'the member digest'
+          ? h.pins.archive
+          : { ...h.pins.archive, sha256: sums.archive, size: sums.size };
+      const sha256 = wiring === 'the archive digest and size' ? h.pins.sha256 : sums.member;
+      yield* ReleaseBinary('vmalert', { ...h.pins, archive, directory: dir.path, sha256 });
+    });
+    await expect(h.stack.deploy(body)).rejects.toThrow(refusal);
+    expect(h.events).toEqual([]);
+    expect(h.fake.files.has(`${DIR}/vmalert`)).toBe(false);
+  });
+
+  test('control: the same swap against plain pins is refused by the download it makes', async () => {
+    const h = harness();
+    const body = Effect.gen(function* () {
+      const dir = yield* HostDirectory('vmutils-1.151.0', { mode: 0o755, path: DIR });
+      yield* ReleaseBinary('vmalert', { ...h.pins, directory: dir.path });
+    });
+    await expect(h.stack.deploy(body)).rejects.toThrow('the pin says');
+    expect(h.events).toEqual([`GET ${VMUTILS_URL}`]);
+    expect(h.fake.files.has(`${DIR}/vmalert`)).toBe(false);
+  });
+});

package/src/release/archive.ts

@@ -0,0 +1,94 @@
+/**
+ * A pinned archive, verified, to the one member a declaration names, verified — the order the
+ * checks run in is the point of the file.
+ *
+ *   1. the archive's SHA-256 against its pin — BEFORE a single byte is unpacked;
+ *   2. gunzip and tar-read as one stream, keeping only the declared member (tar.ts refuses anything
+ *      unsafe in the archive, asked-for or not);
+ *   3. that member's SHA-256 against its own pin.
+ *
+ * ★ BOTH LAYERS, BECAUSE THE VENDOR HASHES BOTH. Each checksum file lists the archive AND every
+ *   binary inside it (measured 2026-09-22, all four). The archive check says the download is the
+ *   published file; the member check says the bytes about to be written are the published binary —
+ *   and it is the only check that still holds if the tar reader were ever wrong about a boundary.
+ * ★ DecompressionStream, THE WEB STANDARD: node and bun both ship it, so dist behaves the same
+ *   under either runtime — no zlib binding, no dependency.
+ * ⛔ IN MEMORY ONLY. Nothing here touches a disk, so no failure below can leave a staged download
+ *   behind; the bytes reach a host only through HostRunner.writeFileAtomic (file-converge.ts).
+ */
+import { sha256Hex } from '../launchd/job-form.ts';
+import type { PinnedDownload } from './binary-form.ts';
+import { ArchiveRefused, ChecksumMismatch } from './refused.ts';
+import { type TarContents, tarReader } from './tar.ts';
+
+/** How much gzip is handed to the inflater at a time. */
+const SLICE = 1 << 20;
+
+/** Gunzip and read a tar, keeping only `wanted`. Throws ArchiveRefused. */
+export const extractMembers = async (
+  gzipped: Uint8Array,
+  wanted: ReadonlySet<string>,
+): Promise<TarContents> => {
+  const tar = tarReader(wanted);
+  // ⚠️ FED IN SLICES, ON DEMAND. Enqueued whole, the 123.6 MB vmutils archive is inflated in one
+  //   transform step and all 264 MB of output queue up before the first read: MEASURED 2026-09-22,
+  //   a peak RSS of 1116 MB for vmalert alone under bun 1.4.0. `pull` hands over the next slice only
+  //   when the stream asks, so backpressure bounds what is inflated ahead of the tar reader.
+  let offset = 0;
+  const source = new ReadableStream<Uint8Array>({
+    pull(controller) {
+      if (offset >= gzipped.length) {
+        controller.close();
+        return;
+      }
+      controller.enqueue(gzipped.slice(offset, offset + SLICE));
+      offset += SLICE;
+    },
+  });
+  const unzipped = source.pipeThrough(new DecompressionStream('gzip')).getReader();
+  try {
+    for (;;) {
+      const { done, value } = await unzipped.read();
+      if (done) break;
+      tar.push(value);
+    }
+  } catch (cause) {
+    await unzipped.cancel().catch(() => undefined);
+    if (cause instanceof ArchiveRefused) throw cause;
+    throw new ArchiveRefused({ message: `not a gzip stream (${String(cause)})` });
+  }
+  return tar.finish();
+};
+
+const mismatch = (subject: string, expected: string, actual: string): ChecksumMismatch =>
+  new ChecksumMismatch({
+    actual,
+    expected,
+    message: `${subject} hashes to ${actual}, not the pinned ${expected}`,
+    subject,
+  });
+
+/**
+ * The declared member's bytes out of a downloaded archive, both layers checked.
+ * ⚠️ `archive` may be shared with another resource's extraction (download.ts sharingInFlight):
+ *   this only reads it.
+ */
+export const verifiedMember = async (
+  archive: Uint8Array,
+  release: PinnedDownload,
+): Promise<Uint8Array> => {
+  const archiveSha = sha256Hex(archive);
+  if (archiveSha !== release.sha256) throw mismatch(release.url, release.sha256, archiveSha);
+  const { members, names } = await extractMembers(archive, new Set([release.member]));
+  const bytes = members.get(release.member);
+  if (bytes === undefined) {
+    throw new ArchiveRefused({
+      message: `${release.url} has no member named exactly "${release.member}" (it has ${names.map((n) => `"${n}"`).join(', ') || 'none'})`,
+    });
+  }
+  const memberSha = sha256Hex(bytes);
+  if (memberSha !== release.memberSha256) {
+    throw mismatch(`member "${release.member}"`, release.memberSha256, memberSha);
+  }
+  return bytes;
+};

package/src/release/binary-alias.test.ts

@@ -0,0 +1,109 @@
+/**
+ * ONE FILE UNDER TWO SPELLINGS (launchd/file-identity.ts), on a REAL filesystem: localRunner in a
+ * fresh temp directory, through Alchemy's own Plan and Apply where the engine's order matters.
+ * Nothing outside `mkdtemp` is touched, and the release is synthetic (fake-release.ts).
+ *
+ * 🔴 EACH TEST BELOW FAILED BEFORE THE FIX (measured 2026-09-22): the respelled deploy planned a
+ *   `replace`, reported success, and left no binary on disk; the next deploy put it back.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm, stat, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { type HostRunner } from '../launchd/runner.ts';
+import { localRunner } from '../launchd/local-runner.ts';
+import { reconcileBinary } from './binary-lifecycle.ts';
+import { VMALERT_TEXT, realEngine } from './fake-engine.ts';
+import { VMUTILS_URL, fakeTransport, syntheticRelease, vmalertProps } from './fake-release.ts';
+
+let tmp = '';
+beforeEach(async () => {
+  tmp = await mkdtemp(join(tmpdir(), 'hf-alias-'));
+  await mkdir(join(tmp, 'real', 'vmutils-1.151.0'), { recursive: true });
+  await symlink(join(tmp, 'real'), join(tmp, 'link'));
+});
+afterEach(async () => {
+  await rm(tmp, { force: true, recursive: true });
+});
+
+const REAL = () => join(tmp, 'real', 'vmutils-1.151.0');
+const LINKED = () => join(tmp, 'link', 'vmutils-1.151.0');
+/** The installed binary's text, or undefined when the deploy lost it. */
+const onDisk = () =>
+  Bun.file(join(REAL(), 'vmalert'))
+    .text()
+    .catch(() => undefined);
+const engine = () => {
+  const e = realEngine();
+  return { deploy: (directory: string) => e.deploy({ vmalert: directory }), gets: e.gets };
+};
+
+/** Whether this temp directory's volume folds case (APFS's default on macOS; not ext4). */
+const foldsCase = async (): Promise<boolean> =>
+  stat(join(tmp, 'REAL')).then(
+    () => true,
+    () => false,
+  );
+
+describe('a respelled directory is an update that keeps the file, never a replace', () => {
+  test('through a symlinked parent, via the engine', async () => {
+    const e = engine();
+    expect(await e.deploy(REAL())).toEqual({ vmalert: 'create' });
+    expect(await e.deploy(LINKED())).toEqual({ vmalert: 'update' });
+    expect(await onDisk()).toBe(VMALERT_TEXT);
+    expect(await e.deploy(LINKED())).toEqual({ vmalert: 'noop' });
+    expect(e.gets).toEqual([VMUTILS_URL]);
+  });
+
+  test('by case alone, on a volume that folds case', async () => {
+    if (!(await foldsCase())) return;
+    const e = engine();
+    await e.deploy(REAL());
+    expect(await e.deploy(join(tmp, 'real', 'VMUTILS-1.151.0'))).toEqual({ vmalert: 'update' });
+    expect(await onDisk()).toBe(VMALERT_TEXT);
+  });
+
+  test('an update across the respelling (the path unresolved at plan) keeps the file', async () => {
+    const { catalog, vmutils } = syntheticRelease();
+    const fetch = fakeTransport({ [VMUTILS_URL]: vmutils }).fetch;
+    const olds = vmalertProps(catalog, { directory: REAL() });
+    const output = await reconcileBinary(localRunner(), fetch, olds);
+    const news = vmalertProps(catalog, { directory: LINKED() });
+    const after = await reconcileBinary(localRunner(), fetch, news, { olds, output });
+    expect(after.path).toBe(join(LINKED(), 'vmalert'));
+    expect(await onDisk()).toBe(VMALERT_TEXT);
+  });
+
+  test('⛔ other bytes at the respelled path are still refused, never written in place', async () => {
+    const { catalog, vmutils } = syntheticRelease();
+    const transport = fakeTransport({ [VMUTILS_URL]: vmutils });
+    const olds = vmalertProps(catalog, { directory: REAL() });
+    const output = await reconcileBinary(localRunner(), transport.fetch, olds);
+    const news = vmalertProps(catalog, { directory: LINKED(), sha256: 'e'.repeat(64) });
+    await expect(
+      reconcileBinary(localRunner(), transport.fetch, news, { olds, output }),
+    ).rejects.toThrow('already exists and is not this resource');
+    expect(await onDisk()).toBe(VMALERT_TEXT);
+  });
+
+  test('⚠️ a runner that reports no identity: the loss fails the deploy instead of passing', async () => {
+    const real = localRunner();
+    const blind: HostRunner = {
+      ...real,
+      stat: async (path) => {
+        const found = await real.stat(path);
+        if (found === undefined) return undefined;
+        const { dev: _dev, ino: _ino, ...rest } = found;
+        return rest;
+      },
+    };
+    const { catalog, vmutils } = syntheticRelease();
+    const fetch = fakeTransport({ [VMUTILS_URL]: vmutils }).fetch;
+    const olds = vmalertProps(catalog, { directory: REAL() });
+    const output = await reconcileBinary(blind, fetch, olds);
+    const news = vmalertProps(catalog, { directory: LINKED() });
+    await expect(reconcileBinary(blind, fetch, news, { olds, output })).rejects.toThrow(
+      'they are one file under two spellings',
+    );
+  });
+});

package/src/release/binary-claim.ts

@@ -0,0 +1,80 @@
+/**
+ * What a Release.Binary may take over at a path it holds no state for: ONLY the pinned binary, and
+ * only under `--adopt`. Asked the same way at plan (binary-diff.ts) and at apply
+ * (binary-lifecycle.ts), so a plan never says `adopted` or `create` for a file the apply would then
+ * overwrite or silently claim.
+ *
+ * ⛔ OTHER BYTES ARE NEVER ADOPTED, `--adopt` OR NOT. 🔴 MEASURED 2026-09-22 (adopt-parity.test.ts,
+ *   through Alchemy's own Plan and Apply): under `--adopt`, a file with other bytes at the path
+ *   planned as `adopted` — beta.79 forces an `adopted` update after every takeover and prints it for
+ *   drift too — and the apply downloaded the archive and overwrote that file in place. With the
+ *   directory an Output (the probe skipped) the same file planned as `create`, and was overwritten.
+ *   ★ Refused rather than converged, which is what Host.File does with a file it adopts: a binary's
+ *   content is named entirely by its pin, so "adopting" other bytes is replacing them under
+ *   whatever runs them, with no rollback but a re-download — the very overwrite binary-form.ts
+ *   inPlaceRefusal refuses for a re-pin. The pinned bytes with another mode or owner ARE adopted;
+ *   the apply re-writes the bytes already on disk.
+ * ⛔ THE PINNED BYTES WITH NO STATE ARE NOT OURS WITHOUT `--adopt` — AT APPLY AS AT PLAN. The probe
+ *   already says `Unowned` for them (docs/ownership.md: identical is not ours). file-converge.ts
+ *   accepts them at apply as the resume of an interrupted install, and that gap is where the probe
+ *   never runs: every first deploy that passes `directory: dir.path`. 🔴 MEASURED 2026-09-22: a
+ *   declaration renamed (a new logical id, the same path) in a deploy that also changed its
+ *   HostDirectory's mode claimed the identical file at apply without `--adopt`; the orphan delete of
+ *   the old name then removed it, and the deploy reported success with the binary gone. With the
+ *   directory unchanged, the probe refused that same rename.
+ *   ⚠️ THE COST: an install interrupted between its write and its commit while a prop was an
+ *   Output now resumes only with `--adopt` — as the same install with every prop resolved already
+ *   did (its recovery read is `Unowned`), and as ownership.md says a create or replace interrupted
+ *   while a prop was an Output does. A retained old version is not re-claimed by a rollback either.
+ *   ★ `renamedFrom()` IS THE REMEDY FOR A RENAME: `.pipe(renamedFrom('old-id'))` migrates the row
+ *   and keeps the file (adopt-parity.test.ts). 🔴 MEASURED 2026-09-22: the same rename under
+ *   `--adopt` claimed the file, the old name's delete then removed it, and the deploy succeeded
+ *   with the binary gone. binary.ts's delete now leaves a path another declaration installed in
+ *   the same deploy, so that is kept too — as an adoption, not as the old row. ⚠️ That guard sees
+ *   only this deploy's claims, by spelling; nothing here sees another row's claim in state.
+ * ★ HOW DIFF TELLS A TAKEOVER FROM ITS OWN ROW. Every row this resource commits records the digest
+ *   reconcile READ BACK, which it checked equal to the pin — so `output.sha256 === olds.sha256` for
+ *   every row of its own, and an update never changes the digest (a new digest is a new path, a
+ *   `replace`). The engine hands diff anything else only after a read of a path it holds no state
+ *   for: the adoption probe (`olds` = the declaration) or the recovery read of an interrupted
+ *   create (`olds` = its row). A non-file reads with digest '' (file-converge.ts).
+ */
+import { type FileTarget, readFileAttributes } from '../launchd/file-converge.ts';
+import type { HostRunner } from '../launchd/runner.ts';
+
+const TAKEN = 'already exists and is not this resource';
+
+const otherBytes = (found: string, pinned: string): string =>
+  `${found === '' ? 'something that is not a regular file' : `a file hashing to ${found}`} is ` +
+  `there, not the pinned binary (${pinned}). --adopt takes over only the pinned binary: taking ` +
+  'over other bytes would overwrite them in place. Remove it (or move it aside) and deploy again';
+
+/** Plan side: why diff must refuse `found` — a digest read at a path with no state — or undefined. */
+export const adoptionProblem = (found: string, pinned: string): string | undefined =>
+  found === pinned ? undefined : `${TAKEN}: ${otherBytes(found, pinned)}`;
+
+/**
+ * Apply side, for a reconcile with no `output` — a create, a replace's new generation, or the
+ * resume of either: why it must not write, or undefined. `adopt` is adoptsAtApply's answer (never
+ * true for a fresh replace). A symlink or directory is left to convergeFile, which refuses it by
+ * kind.
+ */
+export const claimProblem = async (
+  runner: HostRunner,
+  want: FileTarget,
+  adopt: boolean,
+): Promise<string | undefined> => {
+  const stat = await runner.stat(want.path);
+  if (stat?.kind !== 'file') return undefined;
+  const found = (await readFileAttributes(runner, want.path))?.sha256 ?? '';
+  if (found !== want.sha256) return adoptionProblem(found, want.sha256);
+  if (adopt) return undefined;
+  return (
+    `${TAKEN}: it holds the pinned binary, but this stack holds no state for it and the plan ` +
+    'could not ask first (a prop was still an Output, or a replace landed on it). ' +
+    'Identical is not ours: once claimed, a later delete removes it from whoever put it there. ' +
+    'Deploy with --adopt to take it over (a create, or an interrupted install of this one), or ' +
+    'remove it. If another declaration in this stack owned it under another name, declare the ' +
+    'rename with renamedFrom() instead'
+  );
+};

package/src/release/binary-claims.test.ts

@@ -0,0 +1,47 @@
+/**
+ * ONE PATH, ONE DECLARATION (binary.ts `claim`), through Alchemy's own Plan and Apply over the real
+ * localRunner in a fresh temp directory (fake-engine.ts).
+ *
+ * 🔴 MEASURED 2026-09-22 BEFORE THE FIX: `vmalert` and `vmalert-logs` declared at one path both
+ *   planned `create` and both succeeded; the next deploy, without `vmalert-logs`, planned
+ *   `vmalert: noop, vmalert-logs: delete` — and the file `vmalert` still declared was gone.
+ */
+import { afterEach, beforeEach, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { VMALERT_TEXT, realEngine } from './fake-engine.ts';
+import { VMUTILS_URL } from './fake-release.ts';
+
+let dir = '';
+beforeEach(async () => {
+  dir = join(await mkdtemp(join(tmpdir(), 'hf-claims-')), 'vmutils-1.151.0');
+  await mkdir(dir);
+});
+afterEach(async () => {
+  await rm(join(dir, '..'), { force: true, recursive: true });
+});
+
+const onDisk = () =>
+  Bun.file(join(dir, 'vmalert'))
+    .text()
+    .catch(() => undefined);
+
+test('⛔ a second resource at the same path is refused in the deploy that declares it', async () => {
+  const e = realEngine();
+  await expect(e.deploy({ vmalert: dir, 'vmalert-logs': dir })).rejects.toThrow(
+    'is already installed by',
+  );
+  // One of the two installed it; the other touched nothing.
+  expect(await onDisk()).toBe(VMALERT_TEXT);
+  expect(e.gets).toEqual([VMUTILS_URL]);
+});
+
+test('declared once, the survivor keeps its file when the stack is corrected', async () => {
+  const e = realEngine();
+  await e.deploy({ vmalert: dir, 'vmalert-logs': dir }).catch(() => undefined);
+  // ★ MEASURED: the first declared won the claim. The refused one left only the engine's
+  //   unfinished-create row, whose delete touches no file — so the survivor keeps its binary.
+  expect(await e.deploy({ vmalert: dir })).toEqual({ vmalert: 'noop', 'vmalert-logs': 'delete' });
+  expect(await onDisk()).toBe(VMALERT_TEXT);
+});

package/src/release/binary-diff.ts

@@ -0,0 +1,73 @@
+/**
+ * Release.Binary's plan-time answer: refuse what the plan can already see is wrong, `replace` when
+ * the binary's identity moves, and otherwise compare the live file with the declaration.
+ *
+ * ⛔ THE PINS MUST BE PLAIN VALUES, AND ARE CHECKED EVEN WHILE `directory` IS AN OUTPUT. A pin that
+ *   is an Output would be computed during the deploy — a fetch by another name — so a malformed or
+ *   non-literal pin fails the plan here, before a byte is fetched, whatever else is unresolved.
+ *   ⚠️ A CREATE IS NEVER DIFFED: the engine plans a first deploy without calling diff, and skips
+ *   the adoption probe while any prop is an Output. A pin wired from another resource's Output on
+ *   a FIRST deploy therefore reaches no plan-time check; reconcile refuses it before any host call
+ *   or request, from the props as the stack program declared them (declared-pins.ts). 🔴 Until
+ *   2026-09-22 it was checked there for shape only, and a swapped archive with swapped digests
+ *   installed (apply-pins.test.ts).
+ * ⛔ A NEW PIN IS A NEW PATH (binary-form.ts inPlaceRefusal). When the path is resolved and
+ *   unchanged, a changed pin is refused here; when it is resolved and new, it is a `replace`.
+ * ⚠️ WHILE THE DIRECTORY IS STILL AN OUTPUT the path is unknown, and the answer depends on whether
+ *   the BYTES move, because the path may turn out not to have:
+ *   - other bytes (or another name) → `replace`. If the path did not move after all, the new
+ *     generation's create finds the old file, which does not hold its bytes, and refuses
+ *     (file-converge.ts never overwrites what a generation does not own).
+ *   - the same bytes from another archive (a re-pin, a repack) → `update`, NEVER `replace`. 🔴 A
+ *     replace onto the same path would accept the old file as its own (same bytes, same mode) and
+ *     then Phase 2 would delete the OLD generation — at that same path, taking the new one's file
+ *     with it. An update reaches reconcile with `olds`, whose in-place guard refuses the same path,
+ *     and whose move (file-converge.ts) writes the new path before removing the old.
+ *   ★ Not the engine's default either way: a changed prop is an update by default, which is
+ *   exactly the in-place overwrite this resource refuses.
+ * ★ Create-before-delete: two versions can sit in two directories at once, so nothing forces
+ *   `deleteFirst`; the old file goes only once the new one is written and verified.
+ * ⚠️ HOUSE, NOT UPSTREAM: this reads the live file at plan time and can answer `noop`. Upstream's
+ *   guidance is a diff that rarely does either (docs/release-binary-upstream.md).
+ */
+import { type Diff, isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import { diffTarget } from '../launchd/file-converge.ts';
+import { resolvedString } from '../launchd/host-effect.ts';
+import type { HostRunner } from '../launchd/runner.ts';
+import { adoptionProblem } from './binary-claim.ts';
+import {
+  type ReleaseBinaryAttributes,
+  type ReleaseBinaryProps,
+  inPlaceRefusal,
+  pinProblems,
+  pinsMoved,
+} from './binary-form.ts';
+import { NOTHING, desiredBinary, refuse } from './binary-lifecycle.ts';
+
+export const diffBinary = async (
+  runner: HostRunner,
+  news: Input<ReleaseBinaryProps>,
+  olds: ReleaseBinaryProps,
+  output: ReleaseBinaryAttributes,
+): Promise<Diff | undefined> => {
+  const problems = pinProblems((news ?? {}) as Parameters<typeof pinProblems>[0]);
+  if (problems.length > 0) throw refuse(output.path, `${problems.join('; ')}. ${NOTHING}`);
+  // ⛔ A TAKEOVER IS ONLY EVER OF THE PINNED BINARY (binary-claim.ts): `output` here is a read of a
+  //   path with no state, so the plan refuses what it would otherwise print as `adopted`.
+  const takeover = adoptionProblem(output.sha256, olds.sha256);
+  if (takeover !== undefined) throw refuse(output.path, `${takeover}. ${NOTHING}`);
+  // ★ pinProblems passed, so every pin — and `name` — is a plain value; only these are read below.
+  const pins = news as Pick<ReleaseBinaryProps, 'archive' | 'member' | 'sha256' | 'name'>;
+  const directory = resolvedString(news, 'directory');
+  const path = directory === undefined ? undefined : `${directory}/${pins.name}`;
+  const pinned = pinsMoved(olds, pins);
+  if (pinned && path === output.path) {
+    throw refuse(output.path, `${inPlaceRefusal(olds, pins)}. ${NOTHING}`);
+  }
+  // Resolved: a new path is a replace, other bytes or a mode or owner drift an update (diffTarget).
+  if (isResolved(news)) return diffTarget(runner, (await desiredBinary(runner, news)).want, output);
+  if (path !== undefined) return path === output.path ? undefined : { action: 'replace' };
+  if (pins.name !== olds.name || pins.sha256 !== olds.sha256) return { action: 'replace' };
+  return pinned ? { action: 'update' } : undefined;
+};